implementation-planning

Implementation Planning Skill

Standard workflow only. If task_complexity is simple and workflow mode is Express, do not activate this skill. Simple tasks use the Express workflow, which does not activate implementation-planning. Return to the Express Workflow section.

Activate this skill during Phase 2 of Maestro orchestration, after the design document has been approved. This skill provides the methodology for generating detailed, actionable implementation plans that map directly to subagent assignments.

Codebase Grounding

Do not generate an implementation plan from guesses about the repository.

Use the built-in codebase_investigator before phase decomposition when:

• The task modifies an existing codebase
• File ownership, integration points, or validation commands are still unclear after reading the approved design
• Parallelization decisions depend on understanding current module boundaries or likely file overlap

Ask the investigator for:

• The modules and files most likely to change
• Existing architectural boundaries and conventions the plan must preserve
• Integration seams, dependencies, and shared ownership hotspots
• Validation commands and test entry points already used by the project
• Parallelization or conflict risks that should prevent batching

Skip the investigator only for greenfield tasks, documentation-only work, or plans where the current turn already established the relevant repo structure from direct reads.

Reuse investigator findings directly in the implementation plan:

• File inventories should reflect real candidate paths, not placeholders
• Validation criteria should prefer repo-native commands the investigator surfaced
• Parallel batches should account for actual ownership overlap and conflict risk

Plan Generation Methodology

Input Analysis

Before generating the plan, thoroughly analyze the approved design document for:

• Read task_complexity from the approved design document's frontmatter. Apply phase count guidance and domain analysis scaling accordingly. Record task_complexity in implementation plan frontmatter.
• Components and their responsibilities
• Interfaces and contracts between components
• Data models and their relationships
• External dependencies and integrations
• Technology stack decisions
• Quality requirements that influence implementation order

Phase Decomposition

Break the implementation into phases following these principles:

1. Foundation First: Infrastructure, configuration, and shared types/interfaces come first
2. Dependencies Flow Downward: A phase can only depend on phases with lower IDs
3. Single Responsibility: Each phase delivers a cohesive unit of functionality
4. Agent Alignment: Each phase maps to one or two agent specializations
5. Agent Capability Match: Verify the assigned agent's tool tier supports the phase deliverables (see compatibility check below)
6. Testability: Each phase should be independently validatable

Phase Ordering Strategy

Layer 1: Foundation (types, interfaces, configuration)
    |
Layer 2: Core Domain (business logic, data models)
    |
Layer 3: Infrastructure (database, external services, API layer)
    |
Layer 4: Integration (connecting components, middleware)
    |
Layer 5: Quality (testing, security review, performance)
    |
Layer 6: Documentation & Polish

Agent-Deliverable Compatibility Check

Before finalizing agent assignments, verify each phase's agent can deliver its requirements:

| Phase Deliverable | Required Tier | Compatible Agents | |-------------------|--------------|-------------------| | Creates/modifies files | Full Access or Read+Write | analytics-engineer, cobol-engineer, coder, copywriter, data-engineer, design-system-engineer, devops-engineer, hlasm-assembler-specialist, i18n-specialist, ibm-i-specialist, integration-engineer, ml-engineer, mlops-engineer, mobile-engineer, observability-engineer, platform-engineer, product-manager, prompt-engineer, refactor, release-manager, technical-writer, tester, ux-designer | | Runs shell commands | Full Access or Read+Shell | accessibility-specialist, analytics-engineer, cobol-engineer, coder, data-engineer, database-administrator, db2-dba, debugger, design-system-engineer, devops-engineer, hlasm-assembler-specialist, i18n-specialist, ibm-i-specialist, integration-engineer, ml-engineer, mlops-engineer, mobile-engineer, observability-engineer, performance-engineer, platform-engineer, refactor, security-engineer, seo-specialist, site-reliability-engineer, tester, zos-sysprog | | Analysis/review only | Any tier | All agents |

<HARD-GATE> Read-Only agents (architect, api-designer, cloud-architect, code-reviewer, compliance-reviewer, content-strategist, solutions-architect) CANNOT be assigned to phases that create or modify files. If a phase requires file creation and domain expertise from a Read-Only agent, split it: the Read-Only agent produces a spec or analysis, then a write-capable agent (typically coder) implements the files based on that output. </HARD-GATE>

Phase Count Guidance

Scale decomposition granularity to task_complexity (read from design document frontmatter):

• simple: 1-3 phases. Prefer single-phase execution when feasible. Combine foundation + implementation. Skip separate documentation/polish phases.
• medium: 3-5 phases. Use the layer model but combine Quality and Documentation into the final implementation phase where practical.
• complex: No phase count cap. Full layer decomposition strategy applies.

Parallelization Identification

Phases can run in parallel when:

• They have no shared file dependencies (no overlapping files_created or files_modified)
• They are at the same dependency depth (same layer)
• They do not share data model ownership
• Their validation can run independently

Mark parallel-eligible phases with parallel: true and group them into execution batches.

Implementation Detail Requirements

Per-Phase Specification

Each phase in the plan must include:

Objective

A clear, measurable statement of what this phase delivers.

Agent Assignment

Which agent(s) execute this phase, with rationale for selection.

Files to Create

For each new file:

• Full relative path from project root
• Purpose and responsibility
• Key interfaces, classes, or functions to define
• Complete type signatures for public APIs

Files to Modify

For each existing file:

• Full relative path from project root
• Specific changes required and why
• Expected before/after for critical sections

Implementation Details

Provide sufficient detail for the assigned agent to execute without ambiguity:

• Interface definitions with complete type signatures
• Base class contracts with abstract method signatures
• Dependency injection patterns and registration points
• Error handling strategy (error types, propagation, recovery)
• Configuration requirements (environment variables, config files)

Validation Criteria

Specific commands to run and expected outcomes:

• Build/compile commands
• Lint/format checks
• Unit test commands
• Integration test commands (if applicable)
• Manual verification steps (if applicable)

Dependencies

• blocked_by: Phase IDs that must complete before this phase starts
• blocks: Phase IDs that cannot start until this phase completes

Dependency Minimization

List only direct blockers in blocked_by. Do not include transitive dependencies — they inflate dependency depth and prevent parallelism.

Anti-pattern (over-specified):

• Phase 2: blocked_by: [1]
• Phase 3: blocked_by: [1, 2] — Phase 1 is redundant, already reachable via Phase 2
• Phase 4: blocked_by: [1, 2, 3] — Phases 1, 2 are redundant

Result: depths 0, 1, 2, 3 — zero parallel phases.

Correct (minimized):

• Phase 2: blocked_by: [1]
• Phase 3: blocked_by: [1] — Only needs Phase 1 output, not Phase 2
• Phase 4: blocked_by: [2, 3] — Needs both done

Result: depths 0, 1, 2 —