Agent-Skills.md

Agent Skills: Implement -- Task Execution Engine

Execute track tasks following TDD workflow. Single-agent by default, --team for parallel Agent Teams, Sub Agent Parallels. Use when ready to implement a planned track.

UncategorizedID: reinamaccredy/maestro/maestro:implement

Repository

reinamaccredy/maestro
ReinaMacCredy
254

Install this agent skill to your local

pnpm dlx add-skill https://github.com/ReinaMacCredy/maestro/tree/HEAD/.codex/skills/maestro%3Aimplement

Skill Files

Browse the full folder contents for maestro:implement.

Download Skill

Loading file tree…

.codex/skills/maestro:implement/SKILL.md

Skill Metadata

Name
maestro:implement
Description
"Execute track tasks following TDD workflow. Single-agent by default, --team for parallel Agent Teams, Sub Agent Parallels. Use when ready to implement a planned track."

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:

| Condition | Recommended Mode | Reason | |-----------|-----------------|--------| | 1-3 tasks, any dependency shape | Single | Overhead of parallelism exceeds benefit | | 3-8 tasks, 2+ independent per phase, low file overlap | Parallel | Wave-based execution saves time | | 4+ tasks, high complexity, need orchestration | Team | Workers handle complexity, orchestrator verifies | | All tasks are sequential (each depends on previous) | Single | No parallelism possible regardless of count | | Tasks touch many shared files | Single | File conflicts make parallel/team counterproductive | | Mix of independent and dependent tasks | Parallel | Waves handle the dependency ordering naturally |

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

| Aspect | Single | Parallel | Team | |--------|--------|----------|------| | Execution | Sequential in main session | Concurrent sub-agents in worktrees | Concurrent workers via delegation | | Isolation | None (main worktree) | Git worktree per sub-agent | Shared worktree, task-level isolation | | Who commits | Main session | Main session (after merge) | Orchestrator (after verification) | | Failure recovery | Fix inline, retry | Retry failed task sequentially | Reassign or fix task | | Best for | Small tracks, tight dependencies | Medium tracks, independent tasks | Large tracks, complex tasks | | Overhead | None | Worktree setup + merge | Team setup + monitoring |

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)

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

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

  1. Read guidelines: .maestro/context/guidelines.md (if exists)
  2. Read code style guides: .maestro/context/code_styleguides/ (if exists)
  3. 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.
  4. 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

| Signal | Action | |--------|--------| | Test failure with clear error message | Retry: fix the code and re-run | | Same test fails 3 times | STOP: ask user -- likely a spec or design issue | | Build error in generated/config code | Manual fix in main session, then continue | | Worker reports blocker | Assess blocker, provide decision, re-dispatch | | Merge conflict after parallel wave | Sequential retry for conflicting tasks | | Rate limit or infrastructure error | Wait and retry once, then fall back to sequential |

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.