Implement -- Task Execution Engine

Execute tasks from a track's implementation plan, following the configured workflow methodology (TDD or ship-fast). Supports single-agent mode (default), team mode (--team), and parallel mode (--parallel).

Arguments

$ARGUMENTS

<track-name>: Match track by name or ID substring. Optional -- auto-selects if only one track is pending.
--team: Enable team mode with parallel workers (kraken/spark).
--parallel: Enable parallel mode with Task sub-agents in isolated worktrees.
--resume: Skip already-completed tasks (marked [x]) and continue from next [ ] task.

Step 1: Mode Detection

Parse $ARGUMENTS:

If contains --team --> team mode (see reference/team-mode.md)
If contains --parallel --> parallel mode (see reference/parallel-mode.md)
Otherwise --> single-agent mode (default)
If contains --resume --> set resume flag

Step 2: Track Selection

Read .maestro/tracks.md. Parse status markers: [ ] = new, [~] = in-progress, [x] = complete. Support both - [ ] **Track: and legacy ## [ ] Track: formats.
If track name given: Match by exact ID or case-insensitive substring on description. If multiple matches, ask user.
If no track name: Filter [ ]/[~] tracks. 0 = error, 1 = auto-select, multiple = ask user.
Confirm selection: Ask user to start or cancel.

Step 3: Load Context

Load context in tiers to minimize upfront token cost:

Essential (load immediately)

Read track plan: .maestro/tracks/{track_id}/plan.md
Read track spec: .maestro/tracks/{track_id}/spec.md

Deferred (load at first task start)

Read workflow config: .maestro/context/workflow.md
Read tech stack: .maestro/context/tech-stack.md

On-demand (load only if relevant to current task)

Read guidelines: .maestro/context/guidelines.md (if exists)
Read code style guides: .maestro/context/code_styleguides/ (if exists)
Note matched skills from .maestro/tracks/{track_id}/metadata.json "skills" array. Reference their guidance when relevant to current task (skill descriptions are already in runtime context). Graceful degradation: if missing/empty, proceed without.
Read .maestro/notepad.md (if exists). Extract ## Priority Context bullets. These are injected as constraints into task execution context. Graceful degradation: if missing or empty, skip.

Step 4: Update Track Status

Edit .maestro/tracks.md: [ ] --> [~]. Update metadata.json: "status": "in_progress".

Step 4.5: BR Check

BR check: If metadata.json has beads_epic_id, set br_enabled=true. All BR operations below only apply when br_enabled. See reference/br-integration.md for commands.

If br_enabled and .beads/ does not exist: br init --prefix maestro --json.

Step 5: Build Task Queue

Parse plan.md: identify phases (## Phase N), tasks (### Task N.M), sub-tasks (- [ ] ...). If --resume: skip tasks already marked [x].

If br_enabled: use bv -robot-plan -label "track:{epic_id}" -format json to get dependency-respecting execution order. If --resume: use br list --status open --label "phase:{N}" --json to identify remaining work. Fall back to plan.md parsing if bv is unavailable.

Single-Agent Mode (Default)

Step 6a: Execute Tasks Sequentially

Follow the TDD or ship-fast methodology for each task. See reference/single-agent-execution.md for the full Red-Green-Refactor cycle (steps 6a.1-6a.9), ship-fast variant, and skill injection protocol. See reference/tdd-workflow.md for TDD best practices and anti-patterns.

Step 7a: Phase Completion Verification

When the last task in a phase completes, run the Phase Completion Protocol. See reference/phase-completion.md for details (coverage check, full test run, manual verification, user confirmation).

Parallel Mode (--parallel)

See reference/parallel-mode.md for full protocol: plan analysis for task independence, wave-based sub-agent spawning with worktree isolation, result verification and merge, conflict detection, and sequential fallback.

Team Mode (--team)

See reference/team-mode.md for full protocol: team creation, task delegation, worker spawning, monitoring, verification, and shutdown.

Step 8: Track Completion

When ALL phases are complete, run the Track Completion Protocol. See reference/track-completion.md for details (mark complete, skill effectiveness recording, cleanup, final commit, summary).

Relationship to Other Commands

Recommended workflow:

/maestro:setup -- Scaffold project context (run first)
/maestro:new-track -- Create a feature/bug track with spec and plan
/maestro:implement -- You are here. Execute the implementation
/maestro:review -- Verify implementation correctness
/maestro:status -- Check progress across all tracks
/maestro:revert -- Undo implementation if needed
/maestro:note -- Capture decisions and context to persistent notepad

Implementation consumes the plan.md created by /maestro:new-track. Each task produces atomic commits, which /maestro:review can analyze to verify correctness against the spec. Run /maestro:status to check progress mid-implementation, or /maestro:revert to undo if something goes wrong.

maestro-implement