---
name: spec-driven-implementation
description: Spec-first implementation workflow with critique, TDD, tests, docs, and feature-branch GitOps.
---

## explore
role: explorer
output: context.md

Map the relevant code for: {goal}

Focus on `src/`, route entry points, feature modules, shared APIs, tests, existing docs, and project constraints from `AGENTS.md`. Mention `ClientApp/` only if legacy parity matters.

Tool policy: do not call `glob` or any unavailable abstract discovery tool. Use bash discovery only: `rg --files`, `rg -n`, `find`, `sed`, `nl`, and `git grep`. Keep exploration bounded and summarize early when the relevant files are already known. If a tool returns `Tool <name> not found`, stop using it immediately; if the same tool error repeats twice, stop the task and report the blocker. Do not repeat failed tool calls or shell commands. If a command exits non-zero with no useful output, do not retry it unchanged; inspect source/tests or change the hypothesis first. If a focused test fails, use the failure location to inspect and fix code/tests; do not repeatedly grep test output for unrelated terms. After two failed verification attempts without a code or test change, stop and report the blocker. Do not continue after five consecutive calls that add no new information. Treat semantically equivalent commands as repeats even when numeric limits or filters change; do not widen `sed`, `head`, `tail`, or `git diff | grep` ranges step by step.

## spec
role: spec
dependsOn: explore
reads: context.md
output: spec.md

Convert the goal and exploration notes into a concrete spec. Include scope, non-goals, business rules, acceptance criteria, edge cases, data/API contracts, and verification obligations.

## plan
role: planner
dependsOn: spec
reads: spec.md
output: plan.md

Create a concise implementation plan. Identify files to edit, tests to add or update, commands to run, risks, and handoff instructions.

## critique-plan
role: critic
dependsOn: plan
reads: spec.md, plan.md
output: critique.md

Challenge the spec and plan. Find hidden assumptions, missed tests, overengineering, SSR hazards, module-boundary issues, and rollback risks. Return concrete plan corrections.

## test-first
role: tdd
dependsOn: critique-plan
reads: spec.md, plan.md, critique.md
output: tdd-plan.md

Design the smallest failing test or test change that captures the intended behavior. State red/green conditions and the allowed implementation scope.

## implement
role: executor
dependsOn: test-first
reads: spec.md, plan.md, critique.md, tdd-plan.md
worktree: true

Implement the approved plan. Keep edits local to the task, respect SSR and layer boundaries, and do not touch `ClientApp/` unless explicitly requested.

## unit-verify
role: unit
dependsOn: implement
parallelGroup: verify
verify: true

Run or propose the fastest relevant verification, usually `pnpm typecheck`, `pnpm lint`, `pnpm test`, `pnpm test:coverage`, and `pnpm check-coverage`.

## e2e-verify
role: e2e
dependsOn: implement
parallelGroup: verify
verify: true

Run or propose browser-level verification when UI behavior changed. Use `pnpm test:e2e`, Playwright MCP, and parity commands when relevant.

## review
role: reviewer
dependsOn: unit-verify, e2e-verify
verify: true

Review the final diff against the spec, plan, tests, and project rules. Start with the reviewer heartbeat command from the reviewer agent instructions, then inspect changed files in bounded diff chunks. Do not use direct `read`; use `bash` only. Return prioritized findings and whether any fix is required before commit. If the review cannot finish, return a partial review with residual risk instead of waiting silently.

## docs
role: docs
dependsOn: review
output: docs-summary.md

Update or draft any required docs, specs, or release notes. If no docs are needed, explain why.

## gitops
role: gitops
dependsOn: docs
verify: true

Inspect the final diff, create a feature branch if needed, commit stable verified work, and push the feature branch. Do not force-push.
