diff --git a/README.md b/README.md index cbb96cd..2b24420 100644 --- a/README.md +++ b/README.md @@ -112,6 +112,9 @@ skills and documented once in `docs/conventions.md`: spec dir `docs/specs`, plan dir `docs/plans`, 4-digit per-directory naming, the vocabulary above, standing reading (`CLAUDE.md` + `git log -10`), git discipline, Gitea + `closes #N`, and the whole pipeline graph. +Specs and plans are ephemeral — git-tracked, held only for the active +cycle, then `git rm`'d at cycle close; git history keeps the record +(`docs/conventions.md` § Lifecycle). The handful of facts that genuinely vary per project live in the project's own `CLAUDE.md` under `## Skills plugin: project facts`: diff --git a/brainstorm/SKILL.md b/brainstorm/SKILL.md index e4d1a35..183a5d9 100644 --- a/brainstorm/SKILL.md +++ b/brainstorm/SKILL.md @@ -170,7 +170,7 @@ The production gates live there, not here. | "Cycle is small, two iterations, no spec needed" | Iteration count isn't the metric — feature surface is. A two-iter feature touching design-ledger invariants needs a spec; a CLI flag does not. Assess what the feature changes in invariants. | | "Three approaches in, none feel right, ship the least bad" | Three unsatisfying approaches usually means the problem is mis-framed. Stop, capture the three approaches and what fails about each in the spec's design notes (or escalate to the user), sleep on it. End-of-day pressure is the worst signal to resolve a design fork. | | "User is busy, present my own design without Q&A" | Reactive deference disguised as decisiveness. The Q&A surfaces constraints the user hasn't articulated; skipping it means shipping the user's defaults, not their intent. | -| "Spec exists from previous cycle, append to it" | New cycle = new spec file. The architect agent reads spec files per cycle; mixing scopes makes drift review unreadable. | +| "Spec exists from previous cycle, append to it" | The previous cycle's spec was retired at its close (see `../docs/conventions.md` § Lifecycle) — there is nothing to append to. New cycle = new spec file; the architect reads one cycle's spec at a time, and mixing scopes makes drift review unreadable. | | "Approaches A, B, C are all bad — proceed with A" | This is exactly the moment to surface "the problem is mis-framed" rather than ratify a known-bad shape into the design ledger. Escalate to the user. | ## Red Flags — STOP diff --git a/docs/conventions.md b/docs/conventions.md index b778860..8380c8c 100644 --- a/docs/conventions.md +++ b/docs/conventions.md @@ -27,14 +27,41 @@ These directories are fixed. A project that keeps specs and plans elsewhere is the rare exception and states the override in its `CLAUDE.md` project facts. +## Lifecycle + +`docs/specs/` and `docs/plans/` hold **only the active cycle's +artefacts** — they are working space, not an archive. A spec or plan is +valid for the cycle that produces it; its code shapes drift the moment +the code moves, so a stale one left lying around reads as a live API +reference and misleads the next agent that opens it. + +The two directories stay **git-tracked** — never git-ignored. A +spec/plan is committed while its cycle is live, and at **cycle close** — +after `audit` is drift-clean — the orchestrator **retires** it: `git rm` +the spec and plan in the cycle-close commit. The deletion rides in that +commit, so at `HEAD` the directories hold only what is still in flight, +while the full text stays recoverable from git history +(`git show :`). + +A spec/plan is therefore **transient in the repo**: present for its own +cycle, gone from `HEAD` afterwards. The durable record of a past cycle +is the design ledger (where the rationale is lifted during audit) + the +git history of the spec, plan, and code — never a live file under +`docs/specs` / `docs/plans`. + ## Naming Counter-prefixed, per directory: `NNNN-slug.md`, 4-digit zero-padded. The counter is per directory, assigned in creation order, and stable for the life of the file. New files take the -next-higher number; deleted files retire their number (numbers are -not recycled). `brainstorm` / `specify` / `planner` scan the target -directory for the next free number before writing. +next-higher number; `brainstorm` / `specify` / `planner` scan the +target directory for the next free number before writing. + +The number is a within-cycle handle, not a stable archival ID. +Because the directories hold only active artefacts (see § Lifecycle), +an emptied directory restarts at `0001` and a number freed by a +retired file may be reused — that recycling is fine, since the durable +record is git history, not the filename. The slug separator is `-`. diff --git a/docs/design.md b/docs/design.md index 50ef45a..c7aa4e0 100644 --- a/docs/design.md +++ b/docs/design.md @@ -87,6 +87,11 @@ standing reading (`CLAUDE.md` + `git log -10`), git discipline (only-orchestrator commits, main sacrosanct), Gitea + `closes #N`, and the whole pipeline graph (see `pipeline.md`). +Specs and plans are ephemeral active-cycle artefacts — the two +directories stay git-tracked and hold only what is in flight; at cycle +close each is `git rm`'d from the repo, kept only in git history, never +as a durable file (see `conventions.md` § Lifecycle). + ## Project facts (project-specific) The handful of facts that genuinely vary per project live in the diff --git a/docs/pipeline.md b/docs/pipeline.md index 2363f9e..8d0115e 100644 --- a/docs/pipeline.md +++ b/docs/pipeline.md @@ -123,8 +123,9 @@ Hard-gate before plan — the spec-production core and the carrier of the "no plan without an approved spec" invariant. Takes a settled design (directly from sources, or a ratified design handed over by `brainstorm`), applies the feature-acceptance criterion, writes the -spec to `docs/specs`, runs the `grounding-check` gate, and takes user -sign-off — with review but no interview. Bounces to `brainstorm` the moment the sources do not +spec to `docs/specs` (an ephemeral active-cycle artefact, git-tracked +and `git rm`'d at cycle close — see `conventions.md` § Lifecycle), runs +the `grounding-check` gate, and takes user sign-off — with review but no interview. Bounces to `brainstorm` the moment the sources do not resolve a load-bearing design decision. A core node — the spec-production gate before `planner` on every design path. @@ -148,7 +149,8 @@ juror can ratify the resolution instead of blocking for lack of one. See ### planner Hard-gate before implement. Produces a placeholder-free, -bite-sized implementation plan in `docs/plans` +bite-sized implementation plan in `docs/plans` (ephemeral, retired +alongside the spec at cycle close — see `conventions.md` § Lifecycle) that the implement skill can execute task-by-task. Dispatches the plan-recon agent for read-only file-structure mapping. @@ -188,7 +190,10 @@ review-and-commit discipline; the orchestrator inspects and commits. Runs at cycle close. Dispatches the architect agent (read-only drift review against the design ledger) and the bencher agent -(regression diagnostics). Reports drift and regress. +(regression diagnostics). Reports drift and regress. Once it is +drift-clean, the orchestrator retires the cycle's spec and plan — +`git rm`'ing them in the cycle-close commit (see `conventions.md` +§ Lifecycle). ### debug diff --git a/glossary/SKILL.md b/glossary/SKILL.md index 2e338f7..b6fe2ec 100644 --- a/glossary/SKILL.md +++ b/glossary/SKILL.md @@ -104,7 +104,9 @@ If the mode is ambiguous, ask once; do not guess. project's CLAUDE.md. 2. **Partition the prose surface into slices** — the readable prose of the project: `docs/`, `README.md`, the project's design ledger, if it - has one (its CLAUDE.md project facts), the spec directory `docs/specs`. + has one (its CLAUDE.md project facts). Exclude `docs/specs` and + `docs/plans` — those are ephemeral active-cycle artefacts, not durable + prose (see `../docs/conventions.md` § Lifecycle). One slice per coherent group, sized so a single agent can sweep it. 3. **Fan out one `glossary-extractor` per slice.** Dispatch the read-only agent (`agents/glossary-extractor.md`) with the carrier: the slice and diff --git a/issue/SKILL.md b/issue/SKILL.md index 2da16ec..61b2ecb 100644 --- a/issue/SKILL.md +++ b/issue/SKILL.md @@ -76,8 +76,7 @@ These apply to every issue, on create and on edit. link them. - Avoid: "Fixes the regression from the ledger refactor; see the spec." - - Use: "Fixes the regression behind `#38`; spec at - `docs/specs/0004-escaping.md`." + - Use: "Fixes the regression behind `#38`, introduced in `a1b2c3d`." **Language:** title and body are English — an issue is a repo artefact mirrored to Gitea ("would it be committed → English", per diff --git a/planner/SKILL.md b/planner/SKILL.md index f4795b2..ce177a6 100644 --- a/planner/SKILL.md +++ b/planner/SKILL.md @@ -232,7 +232,10 @@ plan file + optional task focus ("only Tasks 1-3 this run"). The orchestrator commits the plan when handing it forward (suggested commit subject: `plan: `). -The planner skill does not perform the commit itself. +The planner skill does not perform the commit itself. Like the spec, +the plan is an ephemeral active-cycle artefact: committed for its own +cycle and `git rm`'d at cycle close (see `docs/conventions.md` +§ Lifecycle). ## Handoff Contract diff --git a/specify/SKILL.md b/specify/SKILL.md index 9cbe36b..755dd7b 100644 --- a/specify/SKILL.md +++ b/specify/SKILL.md @@ -362,7 +362,9 @@ return here. Only proceed after approval AND a fresh Step 5 PASS. The orchestrator commits the approved spec after sign-off (suggested commit subject: `spec: `). The skill does not perform -the commit itself. +the commit itself. The spec is an ephemeral active-cycle artefact: it +lives in the repo only for its own cycle and is `git rm`'d at cycle +close (see `docs/conventions.md` § Lifecycle). **In `/boss` (autonomous):** `specify` is dispatched autonomously — it is bounded (no interview). It runs the criterion, parse, and diff --git a/templates/CLAUDE.md.fragment b/templates/CLAUDE.md.fragment index 30cd309..3b87a92 100644 --- a/templates/CLAUDE.md.fragment +++ b/templates/CLAUDE.md.fragment @@ -59,6 +59,15 @@ Two rules govern who touches git history and how: wrong does land on main, the remedy is a forward-fix commit, never a rewind. +## Spec/plan artefacts are ephemeral + +`docs/specs/` and `docs/plans/` hold only the active cycle's spec and +plan, and they stay **git-tracked** — do not git-ignore them. Each is +committed while its cycle is live and `git rm`'d at cycle close, so it +is transient in the repo: present for its own cycle, then gone from +`HEAD` while git history keeps the full text (see +`~/dev/skills/docs/conventions.md` § Lifecycle). + ## Design rationale ≠ implementation effort When picking between design options, the rationale must come