diff --git a/internal/templater/templates/root/CLAUDE.md.tmpl b/internal/templater/templates/root/CLAUDE.md.tmpl index 3be6a32..16b2613 100644 --- a/internal/templater/templates/root/CLAUDE.md.tmpl +++ b/internal/templater/templates/root/CLAUDE.md.tmpl @@ -5,9 +5,39 @@ Development (TDD) workflow, native to **Claude Code**. Steering, specs, skills, and custom sub-agents are managed by the `csdd` CLI — or, preferably, its MCP tools (see *Driving csdd* below). -**Read [`csdd.md`](./csdd.md) before producing any artifact.** It is the -operational guide that tells you how to drive `csdd` without reading source. -Everything below is a quick map; `csdd.md` is the contract. +## STOP — read this before touching any artifact + +> **`csdd.md` is the contract; this file is the summary.** Before you create, +> generate, approve, or edit *any* steering file, spec, skill, or agent — +> **read [`csdd.md`](./csdd.md) first.** Do not infer the workflow from the file +> contents or from these bullets; the gates, exit codes, and approval mechanics +> live in `csdd.md`. If you have not read it this session, read it now. + +### Hard rules — enforced, not advisory + +These are not style preferences. Breaking one corrupts the contract layer that +every human review and every gate depends on: + +1. **`csdd` is the only sanctioned author of managed files.** Create and change + steering, specs, skills, and agents **only** through the `csdd_*` MCP tools or + the `csdd` CLI — never by writing the files directly. +2. **Never hand-edit `spec.json`.** It records phase approvals and + `ready_for_implementation`. Writing to it directly — even to "unblock" + yourself — bypasses the human gate and is a process violation. Phases are + crossed *only* with `csdd spec approve --phase `, which a + human authorizes. +3. **Never hand-edit frontmatter, task annotations, or `.mcp.json`.** If a + generated file is wrong, regenerate it from the template and edit the *body*, + then re-validate — do not patch the machine-managed parts by hand. +4. **Never skip a phase gate.** `requirements → design → tasks → implementation` + is strictly ordered; you cannot generate a phase until the prior one is + human-approved. `--force` is allowed **only** when the user explicitly + authorizes a fast-track / Quick Plan. +5. **When a rule blocks you, stop and surface it** — report the blocked item to + the human. Do not route around the gate. + +`csdd.md` is the authority on all five. When in doubt, re-read it rather than +guessing. ## Driving csdd — prefer the MCP tools for the dev flow @@ -53,19 +83,31 @@ between the markers. - `.github/pull_request_template.md` — evidence-bearing PR body. - `.mcp.json` — Model Context Protocol servers. -## Workflow at a glance +## The development cycle (follow it in order) -1. **Start each feature on a clean context:** run `/clear`, then `npx @protonspy/csdd spec init ` and iterate requirements → design → tasks. -2. Each phase requires explicit human approval recorded in `spec.json`. -3. `ready_for_implementation` flips to `true` only after all three phases are approved. -4. **Branch before the first task:** create the spec's branch — `git switch -c /` in kebab-case (`feat/` feature, `fix/` bugfix, `chore/` small adjustment; also `refactor/` `docs/` `test/` `perf/`). The PreToolUse hook blocks commits on the default branch to enforce this. -5. Implementation runs one task per iteration with fresh-context sub-agents (implementer → reviewer → debugger), TDD red→green per task. +Each phase is **generated by csdd**, then **human-approved via `csdd spec approve`** — +never by editing `spec.json`. You cannot generate a phase until the prior one is +approved. + +``` +requirements ──approve──▶ design ──approve──▶ tasks ──approve──▶ implementation + (human) (human) (human) ready_for_implementation: true +``` + +1. **Start each feature on a clean context:** run `/clear`, then `npx @protonspy/csdd spec init `. +2. **Generate → review → approve, one phase at a time:** + `csdd spec generate --artifact requirements` → human reviews → `csdd spec approve --phase requirements`; then `design`, then `tasks`. The gate refuses the next `generate` until the current phase is approved. +3. `ready_for_implementation` flips to `true` only after all three phases are approved — and only csdd flips it. Do not set it yourself. +4. **Branch before the first task:** `git switch -c /` in kebab-case (`feat/` feature, `fix/` bugfix, `chore/` small adjustment; also `refactor/` `docs/` `test/` `perf/`). The PreToolUse hook blocks commits on the default branch to enforce this. +5. Implementation runs one task per iteration with fresh-context sub-agents (implementer → reviewer → debugger), TDD red→green per task. Stay inside the approved design boundary. 6. The `pr-review` skill commits a slice only after review is clean, then pushes — the `pre-push` hook runs the test gate and blocks a red push. 7. **Close each feature with a `/clear`:** once its PR ships, reset the context before the next spec so it does not accumulate across features. The Stop hook reminds you when a spec's tasks are all checked. 8. Steering is updated only when a new pattern emerges that the agent could not derive from the code. ## Non-negotiables +- **`csdd` authors managed files; you never write them by hand** — not `spec.json`, not frontmatter, not task annotations, not `.mcp.json`. +- **Phase gates are crossed with `csdd spec approve`, by a human** — never by editing `spec.json` or skipping ahead. - EARS phrasing for every requirement. - `_Requirements:_`, `_Boundary:_`, and `_Depends:_` annotations on tasks. - Test-first: every behavior task pairs a failing test (RED) with the minimal code to pass (GREEN) before moving on.