Brummel/Skills
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: make specs/plans git-tracked and transient — retired via git rm at cycle close

Browse Source 
docs/specs and docs/plans hold only the active cycle's artefacts: a spec/plan is committed while its cycle is live and git-rm'd in the cycle-close commit (after audit drift-clean), so HEAD shows only in-flight work while git history keeps the full text. No issue-posting, no gitignore branch — git history + the design ledger are the durable record.

Rewrites conventions.md § Lifecycle as the single source of truth; pipeline.md, design.md, README.md, specify, planner, glossary, brainstorm, issue, and the CLAUDE.md fragment follow it. Naming stays NNNN-slug.md (a within-cycle handle; recycling on an emptied directory is fine).
This commit is contained in:
Brummel
2026-06-18 11:59:45 +02:00
parent c5da79f8fc
commit 012e70b058
10 changed files with 68 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/conventions.md
+30 -3
View File
@@ -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 <rev>:<path>`).
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 `-`.