Speq Implement

Spec Implementer (Orchestrator)

Orchestrate implementation of the plan in specs/_plans/<plan-name>. Get the plan name from the user prompt. If none is given, ask.

Sub-agents do the heavy work. Each pins its own model and effort in its frontmatter:

Required Skills

Invoke before starting:

• /speq-cli: spec discovery
• /speq-writing-guardrails: prose style for artifacts and GitHub text

Do not invoke coding skills (/speq-code-tools, /speq-ext-library, /speq-code-guardrails) yourself: the orchestrator never writes code. Sub-agents invoke their own required skills.

Orchestrator Role

• Create and maintain tasks.md for persistence.
• Spawn sub-agents for parallel task groups.
• Update task status after each sub-agent completes.
• Never implement directly. Delegate all coding work.
• Rotate sub-agents to keep context windows fresh.
• Update tasks.md before the runtime task, so the persistent state is never behind.
• If a sub-agent fails, keep its tasks [~] and report the error. Never mark [x] while a test fails.

Rotation rule: when a sub-agent has completed max_tasks_per_agent (default 5) tasks, or returns ROTATION NEEDED: read tasks.md for current state, note the completed tasks from the return, and spawn a fresh agent of the SAME type with the remaining tasks. Repeat until the group is complete.

Rotation hand-off: the outgoing agent writes a hand-off note to specs/_plans/<plan-name>/notes/<group-letter>.md (its own duty, per its Early Termination section). <group-letter> is the group's letter only — the token before the : in its Parallelization-table Group entry (group A: plan-log validation → notes/A.md), never the full group name and never a slug of it. Add one line to the fresh agent's brief: Orientation: read specs/_plans/<plan-name>/notes/<group-letter>.md first. If the note is absent, omit the line. The note is working state inside the plan directory. It is never committed evidence, and it moves into the archive with the plan directory.

Workflow

Phase 0: Load Project Hook (orchestrator)

Check for .speq/implement-hook.md in the repo root.

• Present: read it. Announce "Loaded project hook: .speq/implement-hook.md". Its content is authoritative: it can add to, change, or override any part of this workflow. If the hook conflicts with this workflow, the hook wins.
• Absent: continue, no mention.

Add a Project Hook: line (path only, not content) to every sub-agent brief below. implementer-agent, implementer-expert-agent, and code-reviewer read the hook themselves from that path.

Phase 1: Load Plan

Copy code
Read: specs/_plans/<plan-name>/plan.md
Read: specs/_plans/<plan-name>/decision-log.md

Extract: feature specs, implementation tasks, parallelization groups, verification commands from plan.md, and the ## Design Decisions entries from decision-log.md.

Phase 2: Create Tasks

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

If tasks.md already exists, resume per Context Recovery instead of creating it again.

Format:

markdownCopy code
# 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's whole group to implementer-expert-agent (Phase 3 routing rule). Preserve the tag through every status transition.
• untagged: a group with only untagged tasks routes to implementer-agent.

If the plan tagged no tasks and a task clearly needs expert reasoning (for example concurrency, a cross-file refactor, a novel algorithm), you MAY add [expert] when materializing tasks.md. Tag sparingly: over-tagging wastes tokens.

Also create runtime tasks:

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

Phase 3: Implement (Orchestrated)

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

1. Route the whole group by its hardest task. Any [expert] task routes the whole group to implementer-expert-agent. Otherwise the whole group goes to implementer-agent. One agent per group. Never split a group by tag: a group is one knowledge cluster, and each extra agent rebuilds the same mental model, which costs more than the model-price difference.
2. Mark started: update tasks.md, [ ] → [~].
3. Spawn one sub-agent for the group with the invocation template below. If the plan's Parallelization table has a Knowledge column, copy the group's entry into the brief's Knowledge: line. If decision-log.md's ## Design Decisions has entries that touch this group's tasks, paste their Decision and Rationale verbatim into the brief's ## Rationale section. The orchestrator already read the plan and its decision log once in Phase 1, so the sub-agent does not reread them for this. Omit ## Rationale entirely when no entry touches this group.
4. Await completion: the sub-agent returns results or a rotation signal.
5. Handle rotation: apply the Rotation rule and Rotation hand-off above.
6. Mark completed: update tasks.md, [~] → [x] (preserve the [expert] tag).
7. Update TaskTools: TaskUpdate(taskId, status: "completed").
8. Next group: proceed once its dependencies are complete.

Subagent invocation (implementer-agent, or implementer-expert-agent for a group with an [expert] task):

Copy code
Delegate to <implementer-agent | implementer-expert-agent>: Implement <group-name>

## Your Tasks (the whole group)

{group_task_list}

## Rationale

<verbatim Decision and Rationale of the decision-log.md ## Design Decisions entries that touch this group's tasks; omit this section if none do>

## Context

- Plan: specs/_plans/{plan_name}/plan.md
- Tasks file: specs/_plans/{plan_name}/tasks.md
- Knowledge: <the group's Knowledge entry: read these spec deltas and files first; omit if the plan has no Knowledge column>
- Orientation: read specs/_plans/{plan_name}/notes/<group-letter>.md first <rotation respawns only>
- Update tasks.md after each task completion (preserve task numbering)
- The untagged tasks in the list are yours too: the group routes as one unit <expert groups only>
- Preserve the [expert] tag when updating status markers <expert groups only>
- Report the invariants the code now enforces <expert groups only>
- Project Hook: <if active, ".speq/implement-hook.md: read it and apply it"; otherwise omit this line>

Phase 4: Code Review

Review all changed files after implementation completes. Code review runs ONCE per implementation: after fix tasks complete, proceed to Phase 5 (its checks verify the fixes). Do not respawn code-reviewer for a second round.

1. Collect changed files: git diff --name-only <base> for tracked changes plus git ls-files --others --exclude-standard for new files. Implementation work is uncommitted at this point, so diff against the working tree. A commit-range diff (<base>...HEAD) would miss all of it.
2. Spawn code-reviewer agent:

   Copy code
   Delegate to code-reviewer — Review implementation quality
   
   ## Changed Files
   
   {changed_files_list}
   
   ## Context
   
   - Plan: specs/_plans/{plan_name}/plan.md
   - Review for: guardrail violations, dead code, test quality, bad comments, optimizations, YAGNI/over-engineering, error handling, design depth
   - Write findings to specs/_plans/{plan_name}/review-findings.md per your output format, partitioned into `## Standard fixes` and `## Expert fixes`; return only the one-line verdict.
   - Project Hook: <if active, ".speq/implement-hook.md — read it and apply it"; otherwise omit this line>
   

   It returns one line: CODE REVIEW: <n> findings — standard: <n>, expert: <n> — <path>. You never see the findings themselves.
3. Process findings: branch on the two counts in the verdict. If both are 0, go to Phase 5. One agent applies the whole fix pass, routed by its hardest finding: the findings cluster on the files just written, and a second agent there re-orients into the same code and can collide with the first.
   • standard > 0, expert == 0: spawn implementer-agent:

     Copy code
     Delegate to implementer-agent — Apply standard review fixes
     
     ## Your Assignment (fix-task mode)
     
     Read specs/_plans/{plan_name}/review-findings.md, section `## Standard fixes`.
     Append one fix task per finding to specs/_plans/{plan_name}/tasks.md under a
     `## Phase 4: Review Fixes` group, deriving each task line from the finding's
     `Fix:` field, then execute them.
     
     ## Context
     
     - Plan: specs/_plans/{plan_name}/plan.md
     - Project Hook: <if active, ".speq/implement-hook.md — read it and apply it"; otherwise omit this line>
     

   • expert > 0: spawn implementer-expert-agent with the same brief shape, naming section ## Expert fixes, and also ## Standard fixes when standard > 0. It tags only the tasks derived from ## Expert fixes with [expert].
4. Proceed to Phase 5.

Phase 5: Verification

5a. Automated Checks

Execute commands from plan's ## Verification > Checklist. Redirect each command's output to a log: mkdir -p target && <command> > target/speq-<suite>.log 2>&1, then branch on the exit code. If a report quotes output, quote at most tail -n 30 of the log. Raw build or test output never lands verbatim in the transcript.

• 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): verdict and summary first, evidence after. Fill the Verdict table's Code review row from Phase 4's verdict line: a later session's condensed PR comment quotes the Verdict table, and that row is how the counts survive.

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

Phase 7: Completion

Print the summary per references/implementation-summary-template.md, built from the verification-report.md Phase 6 just wrote, ending:

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

Context Recovery

If context is lost or compacted:

1. Read specs/_plans/<plan-name>/tasks.md
2. Find incomplete tasks ([ ] or [~])
3. Resume from the first incomplete task. A [~] task means its sub-agent was interrupted: respawn that group's agent
4. Continue the orchestration workflow

References

Anti-Patterns