cy-implement-spec

---
name: cy-implement-spec
description: Spec-direct execution loop for Compozy specs — self-healing checkpoint driver that ships a spec end to end straight from its documents, no task decomposition: the spec's acceptance criteria become tracked exit conditions and the model works in long-running milestones cut by provability, one atomic commit each, then QA and deep-review peer-review rounds until SHIP. Use for continuous codex-loop goal runs over a .compozy/tasks/<slug> that has _techspec.md but no task graph, or when decomposition is deliberately skipped to keep the whole spec in one model context. Do not use for one-off tasks, PRD/TechSpec authoring, or a slug carrying an authored task graph (use cy-loop-tasks).
---

# Implement Spec Driver

Drive a Compozy spec to completion as a **self-healing continue** loop that
works **directly on the spec documents** — there is no task queue and none
is ever created. Task decomposition existed to fit specs into small model
contexts; this loop instead registers the spec's own exit conditions as
**criteria** (`pending → met`) and lets the model manage the work between
checkpoints in its own context. State tracks *what is proven*, never *what
to do next*.

Each iteration detects the current phase, runs exactly one phase action,
writes memory, updates `state.yaml`, and prints the iteration summary —
then **continues** at detect unless the outcome is an evidence-backed
external blocker or Phase E. A failed command stays inside the current
phase action: diagnose, repair, and rerun it before writing iteration
state. Filesystem state still resumes cleanly if the session ends mid-loop.

The loop is a five-phase state machine:

| Phase | Action | Executor |
|-------|--------|----------|
| 0 | bootstrap: read spec docs, register criteria | orchestrator |
| B | one milestone + verify + checkpoint commit, until every criterion is met | orchestrator |
| C | `qa_report`, then `qa_execution` | Fable 5 herdr worker, then orchestrator |
| D | `deep-review` rounds until SHIP + checkpoint commit per round | orchestrator |
| E | done-signature | orchestrator |

Compatible with `~/dev/ai/codex-loop-plugin` goal mode; the plugin itself
is never modified. Prefer in-session **continue** over waiting for a
Stop→restart — restarts are a resume safety net, not the driver.

## Inputs

- `<slug>` — directory name under `.compozy/tasks/`.
- `<goal_text>` — verbatim `[[CODEX_LOOP goal="..."]]` text or the manual
  reason for the run. Captured once at bootstrap into
  `state.yaml.goal_signature`. Syntax in `references/goal-header-template.md`.
- A pre-authored `.compozy/tasks/<slug>/_techspec.md`. Without it, bootstrap
  stops with a blocker. Companion documents are read when present:
  `_prd.md`, `_tests.md`, `_user_stories.md`, `_design-spec.md`, `adrs/`.
- The slug must carry **no** `_tasks.md` / `task_*.md` — `init-state.py`
  refuses a task graph (exit 5); that slug belongs to `cy-loop-tasks`.

## Helper scripts

Bundled under `.agents/skills/cy-implement-spec/scripts/` — stdlib-only
Python 3.11+, no network, no model calls. Invoke by the explicit repo-root
paths shown in the workflow steps.

| Script | Role | Phase |
|--------|------|-------|
| `_state_io.py` | private strict state codec (imported, not invoked) | all state helpers |
| `init-state.py` | bootstrap (mutating once) | 0 |
| `detect-phase.py` | read-only | every iteration |
| `update-state.py` | mutating | every iteration |
| `commit-checkpoint.py` | mutating (git commit) | B, D |
| `test_scripts.py` | read-only self-test | skill maintenance only |

## Worker delegation

One lane dispatches work to a herdr worker TUI, for judgment independence:
the orchestrator implements the whole spec, so `qa_report` (Phase C) is
always produced by a fresh Claude Fable 5 worker with unbiased eyes —
launched direct, never plan-first. Before any dispatch, read
`references/worker-delegation.md` in full and activate the
`herdr-orchestration` skill it builds on. Every other action runs locally.

## Workflow

Each **iteration** is one detect → phase action → memory → state →
summary cycle. After a completed (non-blocked) summary that is not
Phase E, **continue** at Step 1 in the same turn — do not end the
session between rounds.

If any command, gate, worker, or artifact check fails during a phase action,
read `references/recovery-loop.md` in full immediately and run its repair loop.
Do not write final iteration state or print the summary for an intermediate
failure.

**Step 1 — Detect.**

1. Print `pwd` and confirm the working directory is the repo root (the
   directory containing `.compozy/tasks/`). On mismatch, locate that root,
   change into it, and confirm again; block only when the task tree is absent.
2. Activate `cy-workflow-memory` so its protocol is loaded for later use
   (once per session is enough; re-activate only if context was dropped).
3. Run `python3 .agents/skills/cy-implement-spec/scripts/detect-phase.py <slug>`.
   The printed line decides the whole iteration; the output catalog and
   entry/exit conditions are in `references/phase-transitions.md`.

Done when: detect-phase emitted exactly one supported phase/action line and
the matching branch below is selected.

**Step 2 — Run exactly one phase branch.**

### Phase 0 — Bootstrap

1. Confirm `.compozy/tasks/<slug>/_techspec.md` exists. Missing → scaffold
   `memory/MEMORY.md` from `references/memory-protocol.md`, record the
   blocker under `## Open Risks`, print the iteration summary with
   `outcome=blocked`, and stop (`state.yaml` does not exist yet, so there is
   no update-state call).
2. Activate `cy-spec-preflight` so the repository's playbook, lessons,
   directives, and glossary ground the whole run.
3. Read every spec document in the slug **in full** — `_techspec.md` plus
   the companions listed under Inputs. These documents are the entire
   contract; nothing else will be generated from them.
4. Extract the spec's exit conditions into a criteria list: every
   acceptance criterion and deliverable from `_techspec.md`, anchored to
   spec text — split or merge entries only so each is independently
   provable, and keep each unique. When `_tests.md` exists, add one
   standing criterion: "every test case in _tests.md is implemented in its
   owning suite". Criteria are **exit conditions, not work items** — never
   register a to-do list.
5. Run `python3 .agents/skills/cy-implement-spec/scripts/init-state.py <slug> --goal "<goal_text>" --criterion "<text>"`,
   repeating `--criterion` once per extracted criterion.
6. Scaffold `.compozy/tasks/<slug>/memory/MEMORY.md` with the canonical
   sections from `references/memory-protocol.md`.
7. Run `python3 .agents/skills/cy-implement-spec/scripts/update-state.py <slug> --phase 0 --action "bootstrap (<N> criteria registered)" --outcome completed --memory-written "memory/MEMORY.md"`.

Done when: `state.yaml` exists with every criterion registered and
`memory/MEMORY.md` has the canonical sections.

### Phase B — implement one milestone

There is no queue to pull from: re-read the spec, judge the gap between
the codebase and the pending criteria, and close part of it. One iteration
= one **milestone** — a coherent, provable increment chosen by the model
(a subsystem landed, a contract co-shipped end to end, a vertical slice
passing its tests). No size ceiling: implement as far as coherent judgment
allows before checkpointing; a milestone is cut by provability, not by
clock or file count.

1. Re-anchor from filesystem truth: `state.yaml` (which criteria are
   pending), `memory/MEMORY.md` (decisions so far), and — on the first
   Phase B iteration or after any context loss or compaction — the spec
   documents in full. Never trust a summarized recollection of the spec.
2. State the milestone in one line; this exact text becomes the
   update-state `--action` suffix and the checkpoint commit header. The
   current memory file is `memory/impl-iter-<NNN>.md`,
   `<NNN>` = `state.iteration + 1`, zero-padded to three digits.
3. Activate the repository's required domain skills for the surfaces about
   to be touched (per the repo's skill dispatch table) before writing code.
4. Implement the milestone. Record decisions, learnings, and repairs in the
   current memory file as they happen — memory is the loop's continuity
   across compaction, not an afterthought.
5. Run scoped validation for every touched lane, then `cy-final-verify`.
6. Map evidence to criteria: a criterion is met only when its proof is
   named in the memory file's `## Criteria Advanced` section (command +
   result, test id, or artifact path). Implementation without proof stays
   pending. Skip any peer-review step a spec document requests — that
   review is Phase D (see Critical Rules).
7. Run `python3 .agents/skills/cy-implement-spec/scripts/update-state.py <slug> --phase B --action "milestone: <text>" --outcome completed --criterion-met "<exact text>" --memory-written "memory/impl-iter-<NNN>.md,memory/MEMORY.md" --verify-pass`,
   repeating `--criterion-met` once per criterion proven this iteration
   (omit it for a foundation milestone that proves none — then also record
   in memory what it unblocks). When the last pending criterion is proven,
   add `--implementation-complete` to the same call — the script refuses it
   while any criterion is pending or without `--verify-pass`.
8. Run `python3 .agents/skills/cy-implement-spec/scripts/commit-checkpoint.py <slug> --milestone "<text>"`,
   passing `--coauthor` with the driving agent's identity (e.g.
   `"Codex <[email protected]>"` or `"Claude Fable 5 <[email protected]>"`).
   Stdout is a commit SHA or `SKIP: no changes`; copy it into the iteration
   summary. On exit 1, enter the repair loop and retry the normal checkpoint
   after its root cause is fixed. Never bypass the hook with `--no-verify`.

Done when: the milestone's criteria flips, memory, `state.yaml`, and the
checkpoint result all reflect the same completed milestone.

### Phase C — QA

Run only the printed action.

`qa_report` — dispatched, never authored locally:

1. When release-grade runtime scope needs a lab and no active
   `bootstrap-manifest.json` exists, activate the project's QA bootstrap
   skill first (e.g. `agh-qa-bootstrap` in AGH) when installed.
2. Dispatch the Fable 5 worker per `references/worker-delegation.md`. The
   worker activates `qa-report` with `qa-docs-path=docs/qa` and updates
   journey flows, `docs/qa/scenarios/` files, and cycle charters.
3. Verify the worker evidence (each reported artifact exists, no worker
   commit), then run `python3 .agents/skills/cy-implement-spec/scripts/update-state.py <slug> --phase C --qa-report-done --action "qa-report produced" --outcome completed --memory-written "memory/qa-report.md,memory/MEMORY.md"`.

`qa_execution` — local:

1. Activate `qa-execution` with `qa-docs-path=docs/qa`; it writes the dated
   run report at `docs/qa/reports/<YYYY-MM-DD>-<slug>.md` and updates
   scenario-file verdicts.
2. When the report is "not ready" or a Blocks-Completion/Data-Loss bug is
   open, keep the Phase C action open: repair every in-scope bug, rerun the
   affected QA, and repeat `qa-execution` through the recovery loop. Do not
   set `--qa-execution-done` on an intermediate report.
3. Once the report is ready, run `python3 .agents/skills/cy-implement-spec/scripts/update-state.py <slug> --phase C --qa-execution-done --action "qa-execution produced" --outcome completed --memory-written "memory/qa-execution.md,memory/MEMORY.md" --verify-pass`.

Done when: the printed QA artifact exists on disk and its flag is recorded in
`state.yaml`.

### Phase D — peer-review rounds until SHIP

One round per iteration; detect-phase re-emits `peer_review` until the
verdict is SHIP on a verify-PASS tree. Enter this phase only after
`implementation_complete=true` and both QA flags are true.

1. Activate `deep-review` for the round number printed by detect-phase,
   scoped to the loop's full diff: `--base` = the ref the loop started from
   when known (default `main`), `--spec .compozy/tasks/<slug>` (contract
   conformance), `--subagent codex` (cross-LLM reviewer lane — the
   implementing model never solely reviews its own work). Later rounds ride
   deep-review's incremental state; never pass `--full` mid-loop.
2. The loop is the deciding authority over the round: remediate **every
   confirmed finding and every nitpick** from the round's review.md in this
   same iteration, then re-run the project verification gate. The round's
   verdict is the SHIP/FIX_BEFORE_SHIP/REWORK value in review.md/state.json.
3. Update `memory/peer-review.md` (a `## Round <N>` section per round), then
   run `python3 .agents/skills/cy-implement-spec/scripts/update-state.py <slug> --phase D --review-round-done <SHIP|FIX_BEFORE_SHIP|REWORK> --action "peer-review round <N> (<verdict>)" --outcome completed --memory-written "memory/peer-review.md,memory/MEMORY.md" --verify-pass`.
   The call uses `--verify-pass`: a failed post-remediation gate stays inside
   the repair loop, and a SHIP verdict on a failing tree is void.
4. Run `python3 .agents/skills/cy-implement-spec/scripts/commit-checkpoint.py <slug> --review-round <N>`
   (same `--coauthor` and SKIP / exit-1 semantics as Phase B).

Done when: the round's review.md exists with a verdict, every confirmed
finding and nitpick from it is remediated (or the verdict was SHIP), and
`state.yaml` records the round.

### Phase E — done

1. Run a final `cy-final-verify` and confirm `state.verify.last_status=PASS`.
   A regression enters the repair loop and Phase E remains open until the
   fresh gate passes; skip the done-signature while repairing.
2. Walk the Phase E section of `references/checklist.md`; every box must
   pass.
3. Print the iteration summary block from
   `assets/iteration-summary.template.md` with `phase_out=E` and checkpoint
   field `n/a (phase != B/D)`.
4. Print the literal contents of `assets/done-signature.txt` on its own line
   — the codex-loop goal-check confirmation scans for it.
5. Stop — Phase E is the only successful terminal.

Done when: the Phase E checklist passes, the iteration summary is printed,
and the done-signature is the final output line.

**Step 3 — Self-audit, summarize, then continue.**

1. Walk `references/checklist.md` for the phase just executed; every box must
   pass before summarizing.
2. Print the iteration summary block from
   `assets/iteration-summary.template.md` (Phase E already printed it and
   adds only the done-signature line).
3. **Continue gate:** stop only when `phase_out=E` or the external-blocker
   criteria in `references/recovery-loop.md` are proven and
   `outcome=blocked`. Otherwise re-enter Step 1 immediately — the summary
   marks the round; it does not end the session.

Done when: the phase checklist passes, its summary is printed, and control
either returned to Step 1 or stopped at a permitted terminal.

## Memory protocol

Memory goes through the `cy-workflow-memory` skill — the exact paths per
phase are in `references/memory-protocol.md`. Update memory **before**
flipping any tracking field.

## Goal-mode integration

The canonical `[[CODEX_LOOP ...]]` header and the manual invocation text
live in `references/goal-header-template.md`.

## Critical Rules

- Criteria are **exit conditions, not work items**: `state.yaml` tracks
  what is proven; the model owns the work breakdown inside its own context.
  Never author `_tasks.md` or `task_*.md`, and never activate
  `cy-create-tasks`, `cy-execute-task`, or `cy-tasks-tail-qa-pair` inside
  this loop — a slug that needs a task graph belongs to `cy-loop-tasks`.
- One phase action per iteration; repair failures inside that action, then
  **continue** at detect until Phase E or a proven external blocker — never
  idle between rounds waiting for a restart or re-invocation.
- `state.yaml` mutates only through `init-state.py` and `update-state.py`;
  hand-edits void resume guarantees. There is no top-level `current_phase` —
  `detect-phase.py` derives it from durable state every run.
- Memory updates precede status flips. Always.
- Every `--criterion-met` is backed by proof named in memory (command +
  result, test id, or artifact path); `--implementation-complete` is
  script-guarded — zero pending criteria plus `--verify-pass` in the same
  call — and a criterion is never edited or reverted, only superseded via
  `--add-criterion` with a memory note.
- Every Phase B milestone runs scoped validation then `cy-final-verify`
  before its checkpoint commit. A FAIL opens the repair loop; only the final
  PASS closes the phase action.
- `qa_report` is always produced by the Fable 5 worker; `qa_execution` always
  runs locally. Workers never commit.
- Peer review (`deep-review`) runs only in Phase D. Per-milestone review
  instructions inside spec documents are superseded by this loop's phase
  machine — note "deferred to Phase D" in the iteration memory and move on.
- Phase D repeats in consecutive rounds until SHIP; every non-SHIP round
  remediates all blockers and nits before the next round starts.
- Checkpoint commits (Phases B and D) belong to the orchestrator and capture
  code, memory, and the advanced `state.yaml` in one atomic, restorable
  snapshot.
- Phase E requires `progress.implementation_complete=true`,
  `qa.report_done=true`, `qa.execution_done=true`, `review.ship=true`, and
  `verify.last_status=PASS`.
- Spec regeneration is out of scope: do not rewrite `_techspec.md` or
  `_prd.md` with authoring skills. The only exception is a
  repository-mandated two-touch corrective TechSpec: activate its required
  spec skills, let the loop decide choices already bounded by the current
  goal/contract, persist the corrective design, register any new exit
  conditions via `--add-criterion`, and continue.

## Error Handling

- **Any failure** — read `references/recovery-loop.md` in full and execute it
  before mutating iteration state. Failed commands are repair work, not
  blockers. Use `outcome=blocked` only after its external-blocker test passes.
- **`_techspec.md` missing at bootstrap** — record the blocker in
  `memory/MEMORY.md` `## Open Risks`, print the iteration summary with
  `outcome=blocked`, stop. No update-state call: `state.yaml` does not exist
  yet.
- **Task graph present** — `init-state.py` exits 5. Do not delete the graph
  to force this loop; hand the slug to `cy-loop-tasks` and report the
  mismatch in the summary.
- **`state.yaml` parse failure** — `detect-phase.py` exits 1 with the parse
  error on stderr. Diagnose the malformed writer or interrupted write from
  evidence and repair it without discarding unrelated worktree changes.
- **`--criterion-met` text mismatch** — `update-state.py` exits 1 naming the
  unmatched text. Re-read `state.yaml`, pass the exact stored text, and fix
  the memory note if it quoted the criterion wrong.
- **A criterion is unprovable as written** — follow the criterion
  classification row in `references/recovery-loop.md`: resolve against the
  spec, supersede via `--add-criterion`, record the supersession in memory.
- **`commit-checkpoint.py` exit 1** — repair the hook or commit failure and
  retry normally. If the repair changes tracked source after the last PASS,
  rerun `cy-final-verify` before retrying. `SKIP: no changes` is success.
- **Worker launch or delegation failure** — the pane shows raw JSON instead
  of a TUI banner, `rtk herdr agent list` stays `unknown`, or the status wait
  times out with no progress: interrupt
  (`rtk herdr pane send-keys <pane_id> ctrl+c`) and relaunch once via
  `rtk herdr agent start`; if it fails again, diagnose and repair the worker
  environment through the recovery loop.
- **Delegated run lacks artifacts or committed anyway** — keep the phase
  open, recover the missing evidence or rerun the lane, and do not advance.
  A worker commit is a contract breach that requires preserving the worker's
  work and repairing checkpoint ownership before continuing.
- **Invalid peer-review round** (missing or malformed review artifacts, or no
  verdict) — the round does not count; follow `deep-review` error handling
  and re-run it.
- **Two-touch rule** — on the third corrective touch, replace patching with
  the structural redesign required by the repository, validate it, and
  continue. It becomes a blocker only when that redesign needs an external
  product decision or authority unavailable to the loop.
- **External blocker proven** — record the evidence and exhausted alternatives
  in memory, call `update-state.py` with `--verify-fail --blocker <text> --outcome blocked`,
  print the summary, and stop without the done-signature.