guidance-tiers
Guidance tiers
Two tiers. The frozen tier is the design document the project started from, kept byte-for-byte in a reference directory with an index README. The living docs are the project's current understanding: a vocabulary file, an architecture document, and ADRs. Precedence: living wins where it speaks, frozen is the fallback, and every divergence traces to an ADR. A check script, run in CI, is what makes these rules rules.
1. Inspect
Before asking anything, read what the repository already has. Look for each piece the scaffold writes: a reference directory with contents, CLAUDE.md or AGENTS.md, a vocabulary file, an architecture document, an ADR directory, a check script, a CI workflow. The header of scaffold.sh names the default location of each; a piece counts as present at any location. Done when each piece is marked present or absent.
2. Ask only what the inspection left open
At most three questions, in one message, each skipped when the repository already answers it:
- The frozen artefact — what it is and where it lives now: a path inside the repository, a path outside it, or "not yet in the repo". Skip when the reference directory already has contents.
- The guidance file —
CLAUDE.mdorAGENTS.md. Skip when exactly one of them exists. - The architecture document's name — only if none exists; offer the default.
Everything else takes the scaffold's default; change one only when the owner says so. Done when every open question has an answer.