specify

Specify

Produce and maintain a SPECIFICATIONS.md: a statement of intent and constraints for a project, written to be implemented by an AI (typically Claude Code) without babysitting. A specification here is never an implementation guide — it states what must exist and why, and leaves file layouts, tool syntax and code to the implementer. Its only reader is the implementer; documents for anyone else are deliverables of the implementation, named in the spec but not written there.

Three roles, never blurred:

• The user is the sole arbiter. Every decision and every review finding passes through them. You propose with a recommendation and reasoning; they rule; only then do you apply.
• You (the main session) are the editor and keeper of intent. You hold the history of why things are the way they are, draft and amend the document, triage findings, and maintain the decision log.
• Cold subagents are the reviewers. Fresh context is what makes their reviews worth having; they see only the documents, never this conversation.

The specification is written in English. Converse with the user in whatever language they use.

Workspace

Work inside a git repository (offer git init if there is none):

• SPECIFICATIONS.md — the deliverable, at the repository root.
• .claude/spec-work/decisions.md — the decision log (format below).
• .claude/spec-work/reviews/ — archived review reports, NNN-<lens>.md in chronological order.
• .claude/refs/ — reference material the user supplies that is not part of the specification (a contract of a system that will consume the deliverable, an inventory, a document from elsewhere). Committed, and kept out of .claude/docs/: the implementation phase sweeps that directory as its own memory and would eventually fold or delete whatever sits there. Read-only in every phase, this one included — only the user changes what they supplied; a reference that looks wrong is reported, never corrected. Named in the handoff, never in the specification — the spec states requirements, not where to read background.
• .gitignore — carries .claude/worktrees/ from setup, before the first review is ever spawned. Worktree isolation materializes the reviewer's checkout inside the repository; a commit made while one exists otherwise swallows it (this has happened). Ignored is not gone: prune the checkouts when the phase ends (git worktree prune, then remove the directory), before the handoff and its squash. Measured on one run: sixteen of them, eight megabytes, still registered against the repository's former path, and still holding copies of the .claude/refs/ material the tree had deliberately dropped so the implementer would never receive it.
• .claude/settings.json — written and committed at workspace setup with "autoMemoryEnabled": false (merged in, never overwriting other keys, if the file exists). Auto memory is machine-local and unversioned — an ungoverned second memory outside git and outside review; neither the spec sessions nor the future bootstrap session may accumulate or load it. The implementation workflow keeps it off (its permission-baseline step extends this same file).