Atdd Cycle

---
description: Run the complete supervised ATDD cycle from requirements to verified, spec-compliant, quality-gated implementation — optionally through to PR creation. Stops for spec approval and asks before creating the PR.
argument-hint: "<feature or user story to implement>"
---

Run the complete ATDD cycle for:

$ARGUMENTS

**Authoritative procedure for every phase: `docs/atdd/workflow.md`.** Read that file before
executing a phase (or when you need the full step list). This command covers **orchestration
only** — subagent choices, gates, and reporting.

Track progress through each phase with the todo/task list.

## Hard Constraints

- Never write production code before tests are red for the right reason
- Never modify tests to make them pass; never add logic not demanded by a failing test
- Never proceed past Phase 1 without explicit user approval of the spec
- Never write Phase 3 production code without re-reading `docs/project-profile.md` and
  stating which conventions you will follow
- Never declare done while spec, README, profile, or any doc listed under `Sources consulted`
  in `docs/project-profile.md` has drift — Phase 6 is blocking
- Always detect stack AND conventions before generating code; always read existing project
  docs (README, CONTRIBUTING, ARCHITECTURE, ADRs) — they override inference
- Always prompt for tooling preferences in greenfield projects before writing specs
- Always run the full test suite after each implementation unit and after every refactor change

### The Test-First Rule (non-negotiable)

The **first files you create after spec approval must be test files**. No DTOs, entities,
interfaces, services, or repositories before a test file exists. If a missing type prevents
compilation, add the minimum empty shell (no fields, no logic) needed — nothing more. If the
test file is not the first Phase 2 artifact, you broke the rule.

## Cycle

Analyze → Spec → Tests (Red) → Implement (Green) → Quality Gates → Refactor → Spec & Doc Sync → PR

## Phase 0 — Project Analysis

**Start here — do not browse files speculatively.**

1. Check for `docs/project-profile.md`. If it exists, read it and treat as authoritative —
   skip detection unless the user asked to re-analyze.
2. If missing: follow `docs/atdd/workflow.md` § Phase 0 and `docs/atdd/project-detection.md`
   in full — this includes reading existing project docs (README, CONTRIBUTING, ARCHITECTURE,
   ADRs, etc.) **before** sampling code.
3. Write the profile to `docs/project-profile.md`. Actually persist the file — do not keep it
   in reasoning. Re-read to verify, then print verbatim:

   > ✓ Wrote `docs/project-profile.md` (Tooling: N rows, Conventions: N rows, Reference
   > Files: N entries). Future sessions will read this instead of re-detecting.

   If the write fails, stop the cycle and tell the user.

4. Greenfield vs. legacy:
   - **Greenfield**: prompt for tooling preferences in a single prompt (required: language,
     test framework, package manager; optional: linter, formatter, structure, CI/CD). Record
     choices in the profile. Do not set up configs yet.
   - **Legacy**: conventions discovery is mandatory. Match all existing conventions exactly.

## Phase 1 — Spec

1. Check `specs/` for an existing spec for this feature; if found, read it and skip to step 4.
2. Parse requirements. Ask at most 3 questions if actor, acceptance criteria, or critical
   error/edge cases are unclear.
3. Invoke the **spec-writer** subagent with the full requirements context. It produces
   `specs/features/<name>.feature` and `specs/technical/<name>-spec.md`.
4. Show the user the created specs. Ask: _"Do these specs look correct? Any adjustments before
   I generate tests?"_
5. **MANDATORY GATE — Wait for explicit user approval.** Iterate until approved. Everything
   after this gate is autonomous; this is the user's last mandatory checkpoint.

## Phase 2 — Acceptance Tests (Red)

**Order: test file first, everything else second.** See `docs/atdd/workflow.md` § Phase 2.

1. Write the test file first, using the profile's framework and conventions. One test per
   scenario. Each body throws a "not implemented" error. Header:
   `// Spec: specs/features/<name>.feature`.
2. Add minimum empty shells only if needed for compilation (no fields, no logic).
3. Run the **test command** (not the build command). Every test must fail for the right
   reason (not compile/import errors).
4. **Quality gate**: print the test runner output. Report: _"X scenarios, all red ✓"_.

## Phase 3 — Implementation (Green)

**Step 0 — Convention sync (mandatory before any production file is created or edited):**

a. Re-read `docs/project-profile.md` — `Conventions`, `Reference Files`, `Anti-patterns`.
b. Open at least one reference file from the same layer you are about to write.
c. **State explicitly which conventions you will follow.** This statement is required output.
d. If `docs/project-profile.md` is missing, stop and run Phase 0 first.

Then implement in priority order: `@smoke` → `@happy-path` → `@edge-case` → `@error`. Minimum
code per scenario, mirror the profile, run the full test suite after each scenario, never
modify tests. Full procedure: `docs/atdd/workflow.md` § Phase 3.

## Phase 4 — Quality Gates

Run lint, format, typecheck, build, test. Iterate until all pass (max 3 fix attempts per gate,
re-run all gates after each fix). Reference: `docs/atdd/quality-gates.md`. **Quality gate**:
report the gate results table. Do not proceed until all available gates pass.

## Phase 5 — Refactor

Only with tests green. One focused change at a time; run tests after each. Stop when clean —
no speculative abstractions. **Quality gate**: re-run all gates after refactoring.

## Phase 6 — Spec & Doc Sync (Hard Gate)

**Blocking.** Do not proceed with any unresolved drift — repair in-phase.

**6a. Spec compliance.** Invoke the **spec-reviewer** subagent to validate implementation
against the spec and produce a drift report.

**6b. Spec