Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

speq-implement

Orchestrate implementation of a reviewed plan: task breakdown, TDD sub-agents, code review, and verification report. Use when the user asks to implement, build, or execute a plan under specs/_plans/ — after /speq-plan, before /speq-record. Arg: <plan-name>.

marconae · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add marconae/speq-skill --skill speq-implement

About this skill


name: speq-implement description: "Orchestrate implementation of a reviewed plan: task breakdown, TDD sub-agents, code review, and verification report. Use when the user asks to implement, build, or execute a plan under specs/_plans/ — after /speq-plan, before /speq-record. Arg: ." model: sonnet

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:

Sub-agentWhen used
implementer-agentGroups with no [expert] task (default)
implementer-expert-agentGroups with at least one [expert] task
code-reviewerFinal review of all changed files

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-research, /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.

Rotation rule: sub-agents checkpoint after every 2-3 tasks (expert: 1-2). 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: /speq-record's archive step removes it, and it is never committed evidence.

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

Open-questions gate: read specs/_plans/<plan-name>/open-questions.md. If it exists and is non-empty: stop and report that the plan has unresolved open questions pending human answers (resolve with /speq-plan <plan-name>, or via PR comments and /speq-plan-pr <plan-name> for a headless plan). This is the human-in-the-loop point, the same gate as speq-implement-pr's blocker check.

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.

Lifecycle guard: if tasks.md exists and contains a ## PR Lifecycle section, speq-implement-pr pre-created it as its checkpoint (per its references/checkpoint-protocol.md). Preserve that section verbatim at the top and write the ## Phase N sections below it. Never edit ## PR Lifecycle: its writers are fixed by that protocol. Standalone runs get no lifecycle section. Create the file as below.

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'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:

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 matching 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 the plan has a ## Design section with content specific to this group (Decision paragraph(s), Consequences row(s)), paste that excerpt verbatim i
Read the complete source ↗