Spec Implementer (Orchestrator)

Orchestrate implementation of plans in specs/_plans/<plan-name>.

Orchestration (reading tasks.md, dispatching sub-agents, verifying results) is tool-call heavy but not reasoning-heavy. The sub-agents do the heavy lifting — each pins its own model and effort in its frontmatter:

Get plan name from user prompt or ask if none specified.

Required Skills

Invoke before starting:

• /speq-code-tools — Semantic code navigation and editing
• /speq-ext-research — Library documentation and research
• /speq-code-guardrails — TDD cycle and quality standards
• /speq-cli — spec discovery

Subagents (implementer-agent, implementer-expert-agent, code-reviewer) must also invoke their required skills.

Orchestrator Role

The main agent acts as orchestrator:

• Creates and maintains tasks.md for persistence
• Spawns sub-agents for parallel task groups
• Updates task status after sub-agent completion
• Never implements directly — delegates all coding work
• Rotates sub-agents to maintain fresh context windows

Context Window Management

Strategy: Rotate sub-agents to maintain fresh context.

Rotation workflow:

1. Sub-agent completes tasks, updates tasks.md after each
2. Sub-agent reports checkpoint after 2-3 tasks
3. If max_tasks reached OR sub-agent reports "ROTATION NEEDED":

• Read tasks.md for current state
• Note completed tasks from sub-agent return
• Spawn fresh agent with remaining tasks

1. Continue until group complete

Workflow

Phase 1: Load Plan

Read: specs/_plans/<plan-name>/plan.md

Extract: feature specs, implementation tasks, parallelization groups, verification commands.

Phase 2: Create Tasks

Decompose the plan into a Work Breakdown Structure in specs/_plans/<plan-name>/tasks.md.

Format:

# Tasks: <plan-name>

## Phase 2: Implementation (Group A)
- [ ] 2.1 <task from plan>
- [ ] 2.2 <task from plan> [expert]

## Phase 2: Implementation (Group B)
- [ ] 2.3 <task from plan>

## Phase 3: Verification
- [ ] 3.1 Run test suite
- [ ] 3.2 Run linter

Status markers:

• [ ] pending
• [~] started
• [x] completed

Difficulty tags:

• [expert] — tagged by planner-agent during planning. Routes the task to implementer-expert-agent. Preserve the tag through every status transition.
• untagged — routed to implementer-agent. Most tasks are untagged.

If the plan did not tag any tasks but you encounter a task that clearly warrants expert reasoning (e.g. concurrency, cross-file refactor, novel algorithm), you MAY add [expert] when materializing tasks.md. Do this sparingly — over-tagging wastes tokens.

Also create runtime tasks:

For each task in tasks.md:
  TaskCreate(subject, description, activeForm)

Phase 3: Implement (Orchestrated)

For each parallel group in plan's ## Parallelization:

1. Partition tasks by tag — Split the group into expert_tasks (tagged [expert]) and standard_tasks (untagged)
2. Mark started — Update tasks.md: [ ] → [~]
3. Spawn subagent(s) — Route by tag:

• Standard tasks → implementer-agent
• Expert tasks → implementer-expert-agent
• Spawn in parallel when both exist and they touch disjoint files; otherwise sequence expert first (they often set up invariants the standard tasks rely on)

1. Await completion — Each sub-agent returns with results or rotation signal
2. Handle rotation — If a sub-agent signals rotation, spawn fresh agent of the SAME type with remaining tasks of that tag
3. Mark completed — Update tasks.md: [~] → [x] (preserve [expert] tag)
4. Update TaskTools — TaskUpdate(taskId, status: "completed")
5. Next group — Proceed to next parallel group

Standard subagent invocation:

Task(
  subagent_type="implementer-agent",
  description="Implement <group-name> standard tasks",
  prompt="""
## Your Tasks (standard)

{standard_task_list}

## Context

- Plan: specs/_plans/{plan_name}/plan.md
- Tasks file: specs/_plans/{plan_name}/tasks.md
- Update tasks.md after each task completion (preserve task numbering)
- Report checkpoint after every 2-3 tasks
"""
)

Expert subagent invocation:

Task(
  subagent_type="implementer-expert-agent",
  description="Implement <group-name> expert tasks",
  prompt="""
## Your Tasks (expert — reasoning-heavy)

{expert_task_list}

## Context

- Plan: specs/_plans/{plan_name}/plan.md
- Tasks file: specs/_plans/{plan_name}/tasks.md
- Preserve the [expert] tag when updating status markers
- Checkpoint after every 1-2 tasks (expert tasks are heavier)
- Report key reasoning / invariants applied
"""
)

Phase 4: Code Review

After implementation completes, review all changed files.

1. Collect changed files — git diff --name-only <base>...HEAD
2. Spawn code-reviewer agent:

   Task(
     subagent_type="code-reviewer",
     description="Review implementation quality",
     prompt="""
   ## Changed Files

   {changed_files_list}

   ## Context

   - Plan: specs/_plans/{plan_name}/plan.md
   - Review for: guardrail violations, dead code, obsolete tests, bad comments, optimizations
   - Structure findings using the **Pyramid Principle**: group by theme, lead each group with the key finding, support with evidence.
   """
   )

1. Process findings — If findings exist:

• Create fix tasks in tasks.md (tag [expert] when the finding involves subtle correctness, concurrency, or cross-file reasoning)
• Route fix tasks by tag: implementer-agent for untagged, implementer-expert-agent for [expert]

1. Proceed to verification — Phase 5 verifies all tests pass

Phase 5: Verification

#### 5a. Automated Checks

Execute commands from plan's ## Verification > Checklist:

• Build → exit 0
• Test → 0 failures
• Lint → 0 errors
• Format → no changes

#### 5b. Scenario Coverage Audit

Cross-reference plan's ## Verification > Scenario Coverage against test results:

• Every listed scenario → corresponding test exists and passes
• Flag any scenario without a passing test as incomplete

#### 5c. Manual Verification

Execute each step from plan's ## Verification > Manual Testing:

• Run documented commands against the built software
• Capture actual output as evidence for the verification report
• Mark pass/fail per feature

Update tasks.md verification tasks as completed.

Phase 6: Verification Report

Generate using references/verification-template.md. Structure the report BLUF (Bottom Line Up Front): lead with pass/fail verdict and summary before evidence details.

Save to: specs/_plans/<plan-name>/verification-report.md

Phase 7: Completion

✓ All tasks in tasks.md marked [x]
✓ Code review passed (or findings fixed)
✓ Verification passed
✓ Report generated

Ready for: /speq-record <plan-name>

Context Recovery

If context is lost or compacted:

1. Read specs/_plans/<plan-name>/tasks.md
2. Identify incomplete tasks ([ ] or [~])
3. Resume from first incomplete task
4. Continue orchestration workflow

References