# SDD workflow (Codex CLI)

This project uses the sdd spec-driven development workflow. Large changes (>150 lines /
3+ files / new dependency / architecture choice) go through the gated flow instead of
being implemented directly:

```
$spec-research → $spec-ask → ($spec-design) → $spec-propose → [HARD GATE] → $spec-apply → $spec-verify → $spec-archive
```

Rules that bind you, the agent:

- **Never write project source before the HARD GATE is approved.** After emitting the
  `<HARD-GATE>` block at the end of `$spec-propose`, stop and wait for the user. The
  `<!-- APPROVED: ... -->` marker is appended by `$spec-apply` itself — do not add it,
  and never add it on the user's behalf.
- **Artifacts are fixed**: `spec/changes/<name>/` holds research.md, design.md (optional),
  proposal.md, tasks.md (optional), verify.md; project-durable facts go to
  `spec/knowledge.md`. Inventing extra artifact files requires explicit user approval.
- **Verification is independent**: `$spec-verify` spawns the spec-verifier agent
  (`~/.codex/agents/spec-verifier.toml`) with a fresh context. The conversation that
  implemented a change never audits itself.
- **Anti-Cheating**: nothing is "success" without having actually run; bypasses are
  declared as bypasses; another agent's self-reported success gets independently re-run.
- **Stuck Protection**: 3 consecutive failed fixes in one direction → emit the Stuck
  Self-Check block and wait; from the 2nd attempt on, state why the previous one failed.

The gates are enforced by hooks, not by this file — attempting to skip a step gets blocked
with the reason. (Plugin installs run them from the plugin bundle; script installs from
`~/.codex/sdd-hooks/`.) Details: the `spec-core` skill — shipped inside the sdd plugin
(`~/.codex/plugins/cache/.../skills/spec-core/`), or at `~/.agents/skills/spec-core/` for
script installs.