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 Selection

Parse $ARGUMENTS for explicit flags, then validate the choice is appropriate.

1a: Explicit Flag Detection

• 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 (works with all modes)

1b: Mode Selection Checklist

Before executing, validate that the chosen mode fits the work. Use this checklist when the user has NOT specified a flag and you need to recommend, or to warn when an explicit flag conflicts with the task shape.

MODE SELECTION CHECKLIST

   Evaluate:                          Single    Parallel    Team
   ----------------------------------------------------------------
1. Task count                         1-3       3-8         4+
2. Independent tasks in phase?        any       2+ needed   2+ needed
3. File scope overlap between tasks?  n/a       low/none    low/none
4. Cross-task dependencies?           any       few         moderate ok
5. Task complexity                    any       moderate    high
6. Need human review between tasks?   yes       wave-end    task-end
7. Runtime supports Task tool?        n/a       required    n/a
8. Runtime supports Agent Teams?      n/a       n/a         required

Decision rules:

Warn and suggest if the user's explicit flag conflicts:

[!] --parallel specified but all 3 tasks are sequential (each depends on previous).
--> Falling back to single-agent mode. No parallelism benefit here.

[!] --team specified but only 2 tasks in this track.
--> Single-agent mode is more efficient for small tracks. Proceed with --team anyway? (y/n)

1c: Mode Comparison

Step 2: Track Selection

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

Step 3: Load Context

Load context in tiers to minimize upfront token cost:

Essential (load immediately)

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

Deferred (load at first task start)

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

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

5. Read guidelines: .maestro/context/guidelines.md (if exists)
6. Read code style guides: .maestro/context/code_styleguides/ (if exists)
7. 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.
8. 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].

Task Dependency Resolution

Dependencies are resolved in this priority order:

1. BR dependencies (if br_enabled): Use bv -robot-plan -label "track:{epic_id}" -format json to get dependency-respecting execution order. This is the most reliable source because dependencies are explicit.
2. Plan structure: Tasks within a phase execute in document order. Phases execute sequentially. Cross-phase tasks are always sequential.
3. Inferred dependencies: If a task's description references output from another task (e.g., "using the API from Task 1.1"), treat it as a dependency even if not explicitly marked.

Dependency conflict detection:

[!] Task 2.3 references "the schema from Task 2.1" but plan.md lists them as independent.
--> Treating Task 2.3 as dependent on Task 2.1. Adjust wave assignment.

If br_enabled and --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, skill injection protocol, and worked examples. 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, sequential fallback, and worked examples.

Team Mode (--team)

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

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).

Failure Recovery

These recovery procedures apply across all modes. Mode-specific recovery is documented in the respective reference files.

Worker/Sub-agent Failure

When a worker or sub-agent fails during task execution:

FAILURE TRIAGE

1. Read the error output
2. Classify the failure:

   Build error         --> Fix the code, retry the task
   Test failure        --> Debug the test or implementation, retry
   Missing dependency  --> Install/configure, retry
   Unclear spec        --> STOP, ask user for clarification
   Infrastructure      --> Check environment, retry once, then STOP
   Repeated failure    --> STOP after 3 attempts on same task

Retry vs. Manual Fix Decision

Re-dispatch vs. Fix-in-Place

Re-dispatch (spawn a new worker/sub-agent) when:

• The failure was environmental (timeout, rate limit, infra)
• The task is independent and can run cleanly from scratch
• The previous attempt left no partial state

Fix-in-place (main session fixes directly) when:

• The failure is a small, obvious bug (typo, missing import)
• Partial work exists and is mostly correct
• Re-dispatching would repeat substantial correct work

Stale Task Recovery

If maestro status shows a task stuck in [~] (in-progress) with no active worker:

[!] Task 2.1 is marked in-progress but no worker is active.
--> This is a stale task from a crashed/interrupted session.

Recovery:

1. Check if partial work exists (uncommitted files, partial implementation)
2. If partial work is salvageable: use --resume to continue from current state
3. If partial work is broken: reset to last commit, mark task [ ], re-execute
4. If using BR: br update {issue_id} --status open --json to unblock downstream

Quality Gates

Apply these quality checks during and between task execution.

Post-Batch Hygienic Review

After each task checkpoint report, ask the operator if they want a Hygienic code review for the latest task. If yes, run a review subagent to inspect the implementation changes and apply feedback before starting the next task.

When to Stop and Ask for Help

STOP executing immediately when:

• Hit a blocker mid-task (missing dependency, test fails, instruction unclear)
• Plan has critical gaps preventing starting
• You don't understand an instruction
• Verification fails repeatedly (3+ attempts)
• A task produces side effects not anticipated by the plan

Ask for clarification rather than guessing.

When to Revisit Earlier Steps

Return to Review (Step 2) when:

• The operator updates the plan based on your feedback
• Fundamental approach needs rethinking

Re-planning signals:

• Multiple tasks are failing due to a shared incorrect assumption
• The codebase structure diverges significantly from what the plan expected
• Dependencies between tasks are discovered that the plan did not account for
• A completed task invalidated assumptions in upcoming tasks

Don't force through blockers -- stop and ask.

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.