Method
The single entry point for how this project works. Every methodological document is listed here with what it owns and what it does not, so nothing has to be found by grep.
If you are about to write a new methodology document, add it here or do not write it.
The documents
| Document | Owns | Does not own |
|---|---|---|
docs/PROCESS.md | the rules, each with its enforcer | why the rule exists, that is LESSONS |
docs/PIPELINE.md | the seven stages, who runs them, where the rebase goes | the rules a stage must obey |
docs/LESSONS.md | the register of failure modes actually hit, with detection and remedy | the rules they produced |
docs/FRONTMATTER.md | the markdown schema, provenance, generated indexes | the content of any document |
docs/VERIFICATION.md | what each gate checks and how to run it | whether a gate is correct |
backlog/**/*.md | captured requests, findings and reference notes, with provenance and ticket status | the ticket schema and lifecycle rules, which are TICKETS |
docs/TICKETS.md | the ticket schema in backlog/schema.toml, the status state machine, definitions of done, lanes | what is in the backlog |
docs/CONTRIBUTING.md | commit and PR conventions, the Ref: line | the branching model, that is the user's global config |
docs/CODE_STYLE.md | the repository's half of a consolidation, not a settled guide. What this tree actually does, split into what a tool enforces and what is only convention, every rule with the command that measured it, the four places the tree is inconsistent, and the questions only the owner can answer | the rules with an enforcer that is not a style tool, that is PROCESS, the review standard, that is CODE_REVIEW, and the owner's own document, which has not arrived - DOC-068 |
docs/CODE_STYLE_CONSOLIDATION.md | the read of the owner's own four generations of coding guides against docs/CODE_STYLE.md: which of its fourteen questions his guides answer, every rule adopted with whose it was, every rule declined with why, and the conflicts only he can settle. Also the attribution audit, because a rule that is not his and is not general does not come in | the repository's own rules, that is CODE_STYLE, the review standard, that is CODE_REVIEW, commit and PR conventions, that is CONTRIBUTING, and his documents themselves, which stay in his vaults and are quoted rather than copied |
docs/AGENT-TOOLING.md | lenses, skills, policy, the human versus agent split | the lens schema, that is lenses/_schema.md |
docs/DEVELOPING.md | the walk from empty directory to a serving app, what each command tells you, troubleshooting from real failures | the rules, and the per-gate reference, that is PROCESS and VERIFICATION |
docs/DEV-CHECKLIST.md | the same walk as commands with expected exit statuses, for an agent | any reason for a command, that is DEVELOPING |
docs/QA.md | the QA pass before every promotion of dev to main, for an agent with no context: the automated gates, a fresh product with the main components, a browser walk at phone width, and the one-screen report. Each run's report is docs/qa/<date>.md | what each gate checks, that is VERIFICATION, the walk's reasons, that is DEVELOPING, and whether to promote, which is the owner's call |
docs/GOALS.md | the four finish lines this month, ordered, each with what stands in its way | why anything exists at all, that is PURPOSE, and which quest a ticket serves, that is schema.toml |
docs/QUEUE.md | what gets an agent next, and the per-product step table | which workstreams exist, that is PATHS |
docs/BATCH.md | what a batch is, the rules one may not break, and the batch currently planned | what is worth doing next, that is QUEUE |
docs/ROADMAP.md | the wave order across all five areas, and the unit each ticket belongs to | every unit's state, which scripts/gen_roadmap_status.py derives from the backlog, why a single item is worth doing, that is QUEUE, and which batch is out, that is BATCH |
docs/MEASUREMENT.md | how cost per attempt is counted, and what it ignores | what the number should be, that is QUEUE |
docs/BILLING.md | how a product charges money: the flow, the threat model, every failure mode and what happens in it, the 72-hour fail-open window, and what is still pending | what counts as done, that is contracts/billing.md, and the component's own boundary, that is components/billing/README.md |
docs/EMAIL-AUTH.md | email as an authentication factor: the one token primitive, the three flows over it, the threat model with a sourced answer to each, and what is still pending | the component's own boundary, that is components/auth/README.md, and what counts as done, that is contracts/auth-password.md |
docs/WEB.md | the web surface: how a product gets pages a person can use, how a client is generated for any platform, and where a product's own pages go | the screens' own boundary, that is components/webauth/README.md, and what counts as done, that is contracts/web-surface.md |
docs/INBOUND.md | what comes back from a product: why that direction is a report rather than a merge, what saas divergence classifies, and the four steps after reading it | the outbound direction, that is contracts/update.md, and whether a capability should be lifted, which is a judgement |
docs/WHAT-TRAVELS.md | one dated judgement pass over the outbound boundary: every template artifact outside components/ and skeleton/ classified factory-only, should-travel or travels-already, each with the path it reads or the thing a product loses, the should-travel rows ranked, and the measured drift of anything that exists in two copies | the copy mapping itself, that is WHATS_COPIED, what each gate checks, that is VERIFICATION, the documents a product owes, that is PRODUCT-DOCUMENTS, and what gets done about any row, which is the backlog |
docs/unsafe-defaults.toml | the register of unsafe defaults: every setting whose unsafe value is reachable, what it costs, where it may be held, the refusal that stops it, the test that proves the refusal and the create_app call that reaches it at boot, plus every other configuration refusal with why it is not one. scripts/check_unsafe_defaults.py holds it to the code both ways | what the safe value of any setting is, which is the ticket that decided it, and refusals of user input rather than configuration |
docs/ACCEPTANCE-CRITERIA.md | the acceptance-criteria practice as something portable: the two rules, how to write one with real before-and-after pairs, the four ways a criterion goes wrong with the instance of each, and what a criterion cannot do | this repository's mechanism, that is contracts/README.md for a criterion's shape and backlog/schema.toml for the fields that carry it, where criteria sit in a product's walk, that is PRODUCT-PATH, and the register of failure modes, that is LESSONS |
docs/AI-LED-DEVELOPMENT.md | the failure modes that come from the arrangement rather than from the code: ten rules for running a project this way, each with a measured instance from this repository and the countermeasure | the individual incidents, that is LESSONS, and the rules with enforcers, that is PROCESS |
docs/OWNER-PROFILE.md | who the owner is in his role here, what he needs from a page, what he reads first, what he never wants to see and how to write for him, each point cited | what is waiting on him, that is BLOCKED-ON-YOU.md, and what the project is for, that is PURPOSE |
docs/PORTAL-REVIEW.md | one dated review of the dashboard and the saas-app portal against the owner's profile: the ten-second test, the findings ranked by how much each would help him, and the pull requests that fixed some of them | who the owner is, that is OWNER-PROFILE, and what the portal is, that is PROD-062 |
docs/STRUCTURE-REVIEW.md | one dated review of how the template repository, its components and a generated product are laid out: the five structural improvements that matter most, the evidence for each, a target tree and a migration order in small steps | the layout inside docs/, which is saas-docs' own review, what a component must declare, that is components/CLAUDE.md, and what saas new copies, that is WHATS_COPIED |
docs/DELEGATION.md | the two-tier shape: what a unit owner decides without asking, the short list it escalates, and how to escalate without wasting the round trip | how to write a brief, that is AGENT-TOOLING, and the rules an owner reads rather than asks about, that is PROCESS |
docs/EDGES.md | whether blocked_by edges can be derived rather than written: the path-frequency distribution, the recovery test against the 62 hand-written edges, each evidence class's measured precision, what the frontier and centrality would be worth at each threshold, and the ranked candidates a human rules on | which edges are real, which is a human's ruling and is never this document's, the priority scale, that is PLANNING, and the schema of blocked_by, that is TICKETS |
docs/REVIEW-SWEEP.md | a ticket's life after it is filed: which of the owner's three 2026-09-17 asks already had a word for it, the four ids that have left the register and where their subjects went, when the seeded review dates come due, and the head of the queue with the decision each row wants | whether a particular ticket still matters, which is the reader's ruling and never this document's, the priority rule, that is TICKETS, and why re-scoring has no mechanism, that is OPS-150 |
docs/EDGE-RULING.md | a recommendation on the 21 mutual-citation rows of EDGES.md's shortlist: which pair is moot and why, and for each of the remaining twenty a direction with its argument or an honest "no edge" and what would settle it | the shortlist itself and its measured evidence classes, that is EDGES, and whether any blocked_by field gets written, which nothing here does |
docs/EPICS.md | a proposed outcome-epic grouping over the unbuilt backlog: eighteen epics, each naming an outcome and its member ticket ids, with the residue that lands in none | which grouping the owner picks, that is his ruling and never this document's, and the priority scale, that is PLANNING |
docs/PLANNING.md | how the next unit gets chosen: the two failures in the backlog's shape, why decomposing the problem does not fix them, the three moves in dependency order, and what is missing from the plan | the shape of a ticket, that is TICKETS, what a unit owner decides, that is DELEGATION, and how a day went, that is docs/journal |
docs/COST.md | how the weekly quota is attributed to days, roles and tickets, how good the conversion is, and how to price a ticket | hosting spend, which is docs/SPEND.md, and the quota's own weighting, which is not published |
docs/SPEND.md | this repository's lines, which have a card, and which can surprise you | any other project's spend, and the total |
docs/CONTINUITY.md | what would be lost if the one Mac died, measured by listing: repos with no remote or unpushed work, local-only factory state, secrets by name and location, Terraform state, the GitHub side, and the recommended nightly encrypted backup with which steps need the owner | the Claude plan's terms and a second GitHub identity, which are the owner's (BLIND-SPOTS item 5), how agents read secrets, that is SECRETS, and a product database's backup, that is RESTORE |
docs/SECURITY-PLAN.md | the whole security pile read at once: the re-derived population, the six causes with every ticket named under exactly one, five phases each with a command for an exit, and the answer on whether the small pile or the critical items go first | any single ticket's own fix, that is the ticket, which gate checks what, that is VERIFICATION, and how secrets are stored per deployment level, that is SECRETS |
docs/SOC2-GAPS.md | the SOC 2 gap list against avner-organization/soc2-reference: per gap the criterion, what the reference expects, what the kit has with the file, a HAVE, PARTIAL or MISSING verdict and an effort, kept apart for the product kit and for the organisation, with the first five to close and the proposed tickets | the 2026-09-12 first pass and its measurements, that is reviews/2026-09-12/soc2.md, any single ticket's fix, that is the ticket, and the security pile's causes and phases, that is SECURITY-PLAN |
docs/NIST-800-63B.md | components/auth against NIST SP 800-63B-4, the owner's chosen authentication standard ("Go", 2026-10-06): per requirement its SHALL or SHOULD, a HAVE, PARTIAL or MISSING verdict with the file, the gaps filed and the ones proposed | the development-lifecycle mapping, that is SSDF, the SOC 2 gap list, that is SOC2-GAPS, and any single ticket's fix, that is the ticket |
docs/journal/*.md | one file per working day on how the work went: what was slow, what was repeated, what a command could have done instead | a failure mode once with its remedy, that is LESSONS, the transferable rule, that is AI-LED-DEVELOPMENT, and the state of the project on a day, that is docs/sessions |
docs/PRODUCT-PATH.md | the road from saas new to a product: what a founder decides once per product, what per feature, what the template has deliberately not decided, and which components no example exercises | the template's own workstreams, that is PATHS, and the walk to a serving app, that is DEVELOPING |
docs/PRODUCT-LIFECYCLE.md | the states a product passes through from scaffold to customer, and the check each transition owes | the road a founder walks, that is PRODUCT-PATH, and the template's own delivery stages, that is PIPELINE |
docs/PRODUCT-DOCUMENTS.md | the four documents a product owes, who writes each and what fails without it, what belongs in a design guide, and which documents are deliberately refused because a check already covers them | the minimum handoff bar, that is PRODUCT-LIFECYCLE, and the steps that produce them, that is PRODUCT-PATH |
docs/interview/DESIGN-GUIDE-STRAWMAN.md | a mock design guide, written to unblock the pipeline and deleted when the real one lands | any real design judgement, and it says so |
docs/INTERVIEW.md | the one-command path from a founder to a product with a visual identity: the seven stages and the file each hands to the next, the tier decision, the cold-spine question order, the instruments and the one that was refused, which stage is the weak one and the three ways to replace it, and what the path deliberately does not do | what a design guide should say, that is the straw-man on atomic/prod-067/straw-man-design-guide and eventually PROD-063's real one, which documents a product owes, that is PRODUCT-DOCUMENTS, and whether any given walk is any good, which only a person who opened it can say |
docs/DESIGN-TOKENS-OUTSIDE-VIEW.md | one dated reading of how mature design systems decompose: the three tiers and what the middle one is for, why the component tier is a known scaling trap and why an install step avoids it, and the DTCG interchange format with what it expresses that this repository's token dataclass cannot | whether to adopt any of it, that is PROD-082, what a designer produces, that is PROD-076, what good looks like, that is PROD-063, and the kit's own seam for reading tokens, that is COMP-109 |
docs/PRODUCT-DOCUMENTS-OUTSIDE-VIEW.md | the same question answered from outside evidence alone: a must/should/could ranking with what concretely fails without each, the artifacts the process literature recommends and this project refuses, and the sources with dates | the answer derived from this repository's own two products, that is PRODUCT-DOCUMENTS, and the handoff bar it checks itself against, that is PRODUCT-LIFECYCLE |
docs/PRODUCT-JOURNEYS.md | the journey map at click resolution: what a step is, the eleven rules a journey obeys, one worked journey for the toy shop, and the dead-end check a gate can run with no server | who wants what, that is docs/products/<slug>/STORIES.md, whether a route is linked at all, that is scripts/check_reachability.py, and what a page looks like, that is a product's DESIGN.md |
docs/BORROWED-TERMS.md | terms owned by an RFC, a vendor or an industry that were used at the owner and that he asked about, each saying what it means for us and where the real definition lives | words this repository coined or bent, which is GLOSSARY |
docs/products/CANDIDATES.md | one dated shortlist: what this template could ship, ranked, with what was ruled out and the constraint that killed each | the road from an idea to tickets, that is PRODUCT-PATH, and any product actually being built, that is its own log |
docs/RESTORE.md | the one restore that has actually been run: which of the three targets the shipped restore verb refuses and which works, what a founder does in order, what the backup covers and what it does not, and how long each step took with the command that produced the number | the backup's schedule, destination, encryption and retention, which are OPS-035 and the owner's decisions and are named as decisions rather than answered, and the erasure replay a restore owes, that is adr-006 and OPS-058 |
docs/services/*.md | one external service each: what it costs, how to create the account, which credential, where it goes, and the command that verifies it | what the service is for by role, and its alternatives, that is SERVICES |
docs/PROVIDER-CHOICES.md | every place the template has more than one working implementation of something, the option the interview recommends for each and the rule that picks it, each option's strong and weak points with the provider's own page cited, and which choices the interview asks today | vendors with no code behind them, that is SERVICES, and how to set one up, that is docs/services/*.md |
docs/CAPABILITY-PLAN.md | every capability the 45 reference SaaS have, how often, whether the template has it with the evidence, the weighted and plain coverage numbers and their formula, and the milestones to 90 and 100 percent with a ticket for each gap | the reference products themselves, that is docs/reference-saas/, the 34-row day-one infrastructure score, that is reviews/ninety-rescore-2026-09-29.md, and the order inside a milestone, that is QUEUE |
docs/PRODUCT-FLOW.md | the four stages from a frozen template to a built product - the interview's seats and their required-outputs specs, the human-skill dial, what the planning step takes and returns, and how its tickets reach the fleet | what the planning prompt says, which the owner set aside, and what each seat asks, which is that seat's own spec |
docs/design/*.md | one row for the whole directory. The design role's own document set: the design seat spec for the interview, which lists everything a professional designer produces before design work starts, what complete means for each, and which parts wait on the marketing seat | what the role owns and may decide, that is roles/design.md, the shared shape of a seat spec, that is docs/PRODUCT-FLOW.md and PROD-124, and the mock design guide, that is docs/interview/DESIGN-GUIDE-STRAWMAN.md |
docs/marketing/*.md | one row for the whole directory. The marketing and business role's working directory: the owner's founding brief, positioning, audiences, market sizing, competitor notes, channel plans, demand tests and what they showed, the partner pitch, the business seat spec for the interview, and drafts of anything meant for people outside the repository, none of it sent | what the role owns and may decide, that is roles/marketing.md, how a page looks, that is roles/design.md, and who outside was contacted, that is the product role's contact record |
docs/reference-saas/*.md | one row for the whole directory. The 45 paying SaaS the template is measured against, researched 2026-10-06 with sources, copied unchanged below their frontmatter, the capability taxonomy they are scored on, and DECISIONS.md, the axes where they differ and which of those saas interview asks | what the template does about any of it, that is CAPABILITY-PLAN, and the interview's questions themselves, that is cli/interview/questions.py |
docs/ledger.jsonl | the only record of what he asked and what we dispatched. One append-only line per event: a request in his own words with whether it is answered, or a dispatch with its subject, tickets, agents, tokens and outcome. Written by scripts/ledger.py at the moment the thing happens. A subject that says more than the words names whose judgement the extra is, DOC-131 ruled 2026-10-07: his answer is often one word and the summary then carries everything, so it says where that content came from. A convention for a reviewer rather than a gate, and scripts/ledger.py's docstring carries the measurement showing why | what is in flight right now, that is DISPATCH.md, how the day went, that is docs/journal/*.md, and any state derived from it, that is docs/state.json |
docs/state.json | generated, never edited. One structured document of the whole project's state for anything that has to read it rather than a person: the unbuilt backlog with derived priority and reason, the blocked_by graph and its components, the frontier, what BLOCKED-ON-YOU.md reliably carries, and the ledger. The unbuilt tickets' full rows sit beside it in docs/state/<area>.json, one file per backlog area so no file crosses the pre-commit hook's size limit, and gen_state.read() puts them back. python3.12 scripts/gen_state.py, checked by make doc-gates | any judgement at all - it derives and never decides - the live quota, which is not a fact about a commit and needs --with-budget, and the prose any of its sources is written in |
docs/budget.json | generated, never edited, and the one generated artifact here that nothing drift-checks. One dated reading of the weekly and session quota, so the published dashboard can carry the figures the owner asked for. make budget-figure, and make doc-gates validates its shape without ever failing on its age - a --check over a clock-dependent artifact goes red every hour and gets ignored, which is docs/REVIEW-SWEEP.md's argument | the allowance arithmetic, which is scripts/budget.py, and any figure nobody read: a failed reading keeps the previous document and says how old it is |
docs/cost.json | generated, never edited, and not drift-checked, like docs/budget.json. Token counts from the session transcripts summed by day, role and ticket and converted to credits (1% of the weekly quota). python3.12 scripts/cost_report.py --write, and make doc-gates validates its shape and refuses anything that could be message text | any prompt or response text, any session title that is not a saas-* role, and any figure it could not calibrate |
dashboard/ | generated, never edited, and published. The owner's entry point: what is blocked on him first, then the open questions, the budget, what landed, what is next, agents, the methodology documents rendered in place, the dependency graph, and security.html - the security programme's four buckets, its red criteria with their commands and output, and its failure-scenario coverage, DOC-096. One row for the whole directory, because it is one artifact in thirteen files rather than thirteen documents. make dashboard, checked by make doc-gates, deployed by duchovni-net reading the files | any judgement, and any untracked fact - the git log and the worktree census are named on it as absent, with the command, because the committed copy has to be a pure function of the tree for its --check to mean anything. The quota is on it, via docs/budget.json, which is a tracked file |
HANDOVERS.md | one-line changes stranded outside their author's scope | anything with an owner who can act |
BLOCKED-ON-YOU.md | accounts, credentials and decisions only the owner can supply | anything more work could unblock |
RESUME.md | where the delivery loop currently stands and what the coordinator does next | the plan's reasoning, that is QUEUE |
docs/GLOSSARY.md | terms this project uses in a specific way | the rules they appear in |
docs/LEXICON.md | the words that turn up in a report, why each distinction was worth a word, and which are this project's own | the reference definition of any term, that is GLOSSARY |
docs/TOOLS.md | each third-party tool, what it checks, what its findings mean | which gate runs it and in what order, that is VERIFICATION |
docs/TEAM.md | who owns what, and whether a lane is a fan-out or a chain | the perspectives themselves, that is lenses/ |
roles/*.md | what each session owns, decides alone, escalates and runs | how a session dispatches agents, that is its own operating procedure, and what to look for, that is lenses/ |
docs/UNATTENDED.md | the review-to-summary cycle to run when nobody can be asked | what a single batch contains, that is BATCH |
docs/sessions/*.md | what happened, in order, and new instances of known failures | the register itself, that is LESSONS |
docs/security-programme/ | the standing security officer's state, which OPS-181 requires to live here rather than in a session: the compiled plan whose phase exits are commands, the running log of what was dispatched and what was actually verified, and state.json - generated by scripts/gen_security_state.py for the dashboard's security tab, with evidence.toml as its hand-written half, the failure scenarios and the run records that no amount of reading the tree can derive | the analysis of the pile, that is SECURITY-PLAN, how a secret is stored, that is SECRETS, and the tab itself, which is dashboard/security.html above - DOC-096 built it and DOC-094 is the wider per-lens view it is the first instance of |
docs/docs-programme/ | one row for the whole directory. The standing documentation session's state, here rather than in the session's card in roles/ because roles/CLAUDE.md puts findings, logs, plans and state where the work is and docs/security-programme/ is the precedent it names: the eight aspects of the corpus with a verdict each, the figure-by-figure inventory with the command that produced every number, and the running log. DOC-104, and the owner's instruction of 2026-09-20 that one session own all the docs and all their aspects | what this session may decide and must escalate, that is the session's card in roles/, what a reviewer looks for, that is lenses/review/, and the rules themselves, which are this file and docs/PROCESS.md |
docs/DOCS-STRUCTURE.md | the inventory of what is under docs/ - 157 files and 548,625 words, 74 of them loose at the top level - with a proposed target layout of roles/<role>/ and processes/, and a migration ordered by what each move costs in backtick claims. The owner's request of 2026-10-07 | the layout as it is today, which is this file's own rows, and anything a document says, which this deliberately does not touch |
reviews/*.md and reviews/*/*.md | one pass each: what a reader found at a named commit, with the command behind every claim, and the convergence check against that reader's previous pass | the register of failure modes, that is LESSONS, and what gets done about a finding, that is the backlog |
reviews/outside-view.md | the one evaluation of this repository as a starting point for a business rather than as a codebase meeting its own contracts: what a founder gets, what they hit, what should not be here, and which checks were watched to fail | any gate's own correctness, that is VERIFICATION, and what to do next, that is QUEUE |
contracts/*.md | one row for the whole directory, and it was missing while twenty-eight of them existed. One boundary each: the interface, the scope with what it deliberately does not own, and numbered acceptance criteria that are commands with observable results, each naming its source and whether it is confirmed or plausible | what makes a criterion, the pinned environment and who signs one, that is contracts/README.md, the practice as something portable rather than this repository's mechanism, that is ACCEPTANCE-CRITERIA, which stage writes one, that is PIPELINE, and whether any criterion currently passes, which is integrations/*.md |
The one rule about this set
LESSONS.md is the only register of failure modes. A session log records new instances by pointing at a lesson id. It does not restate the lesson.
That rule exists because the register was briefly duplicated: eight failure modes in LESSONS.md and eight recurring problems in a session log, roughly seventy percent the same prose. Two registers of one thing drift, and then neither can be trusted. Same reasoning as a hand maintained index.
Where invariants live
Rules that apply everywhere are in docs/PROCESS.md. Rules that apply to one directory live in a CLAUDE.md in that directory, because an agent editing components/ should not have to read every global rule to find the one that governs it.
| Location | Carries |
|---|---|
CLAUDE.md at repo root | what any agent needs before touching anything |
components/CLAUDE.md | the relative-import spelling in both worlds, the COMPONENT dict and what requires means, role cards, what the copier skips, the layering contracts |
cli/CLAUDE.md | exit codes are contract, what may never be silent, the CLI treats components as data |
docs/CLAUDE.md | frontmatter is mandatory, indexes are generated |
scripts/CLAUDE.md | standard library only, --self-test as the known-bad input, the three exit codes, reuse the three libraries |
tests/CLAUDE.md | which test path belongs to which owner, xfail over skip, how to watch a test fail without mutating the shared tree |
flows/CLAUDE.md | a flow names its model, nothing here is a gate, records are committed, the provider seam borrows components' vocabulary |
A directory CLAUDE.md states invariants and points at the authority. It never restates a global rule, for the same reason a session log never restates a lesson.
It carries no frontmatter either, at any depth. The carve-out and its reasoning are in docs/FRONTMATTER.md.
Three of these are blocked on tooling, not missing
A CLAUDE.md under contracts/ and one under lenses/ were both written, and both are withdrawn until scripts/ implements the frontmatter carve-out it already documents. docs/FRONTMATTER.md exempts a CLAUDE.md at any depth and says scripts/gen_docs_index.py excludes it by name "so the rule and the gate agree". Only that one script does. scripts/gen_lens_index.py reads a CLAUDE.md under lenses/ as a malformed lens and fails on the first line of make lens-gates, and scripts/gen_contracts_index.py reads one under contracts/ as a contract missing all seven required keys and fails the third line of make doc-gates. Landing either would hide every gate behind it, which is the ordering failure the doc-gates comment exists to prevent. The two one-line fixes are in HANDOVERS.md, and both files go in unchanged once they land.
The third is the skeleton's, and it is blocked for a different reason.
The skeleton's own CLAUDE.md is blocked, not missing
The planned row was "everything here is copied to a product, so it is product code", and that sentence is exactly why the file cannot exist yet. render_directory walks skeleton/ with rglob("*") and copies every file, so a plain CLAUDE.md sitting directly inside skeleton/ and the rendered output of skeleton/CLAUDE.md.j2 both target the same path in a product, and whichever the walk yields last wins. Confirmed by scaffolding: the plain file won three runs out of three and the product received no project instructions at all. A plain README.md beside skeleton/README.md.j2 collides the same way and resolved the other direction on the same filesystem, which shows the order is a directory-hash accident rather than a rule.
So skeleton/ keeps its two instruction files distinct in intent already, and the confusable pair is worth naming: skeleton/CLAUDE.md.j2 is a product's instruction to its own agents, rendered into every scaffolded project. A plain CLAUDE.md there would be the template's instruction to agents editing the skeleton, and it is the one that must not ship. Until the copier deterministically excludes a template-only file under skeleton/, both stay unwritten. The fix and its reproduction are in HANDOVERS.md against cli/core/template.py.
Where orientation lives
A CLAUDE.md is the agent contract. A README.md is the human landing for a directory: what is in here, why it exists, how it fits. Both jobs, never one file doing both.
| Location | Orients | |
|---|---|---|
README.md at repo root | the project, and its honest state | |
docs/README.md | every document, generated from frontmatter | |
components/README.md | what a component is, saas add, role cards, generated index | |
examples/README.md | where a product's own code goes, and the two built products that show it | |
docs/products/*.md, docs/products/*/*.md, docs/products/*/journeys/*.md and docs/products/*/product/* | one row for the whole directory. Per shipped product: a log of the decisions the code cannot state, and the documents every product owes - its own GLOSSARY of the nouns it invented, its STORIES of who wants what, its design voice, and one file per journey under journeys/, in the format docs/PRODUCT-JOURNEYS.md specifies and scripts/check_journeys.py reads. Also, where a product's interview was answered from a record rather than by walking it, that product's ANSWERS.md - one answer per qid in cli/interview/questions.py with the quote and the citation behind it, the questions the record cannot answer, and the places the record contradicts itself. And a product's dossier under product/, staged here until its own repository carries it, in the format adr-017 fixes and cli/gates/dossier.py checks | the template's own vocabulary, that is GLOSSARY, what a journey file has to look like, that is PRODUCT-JOURNEYS, what the interview asks, that is INTERVIEW, and what to build, that is the backlog |
docs/journeys/*.md | one row for the whole directory. The kit's own walks, one file per journey: the surfaces components/webauth mounts in every product - sign-in, create-account, the account page, deletion, sign-out - as a graph, in the same format docs/PRODUCT-JOURNEYS.md specifies and the same scripts/check_journeys.py reads. Here rather than under a product slug because docs/PRODUCT-PATH.md's routing test puts them in layer 1: every product that installs the component gets these pages unchanged | a product's own pages, that is docs/products/<slug>/journeys/, and what a journey file has to look like, that is PRODUCT-JOURNEYS |
contracts/README.md | what makes a criterion, the pinned environment, generated index | |
lenses/README.md | what a lens is and what each one runs. Generated whole | |
flows/README.md | what a flow is, how one is run and accepted, and what a run leaves on disk. One row for the whole directory: the definitions and the run records under flows/runs/ are all covered here, along with whatever a human accepts out of them, because a flow is config and a record is a dated fact rather than a rule | whether any generated content is good, which nothing asserts, and the decision itself, that is docs/adr/009-generation-is-recorded-not-reproducible.md |
integrations/README.md | what a signature is, and why it is not a review | |
scripts/README.md | four families of script, and which one owns which claim | |
tests/README.md | template tests versus product tests, and the partition | |
cli/README.md | the command reference, options and exit codes | |
cli/gates/README.md | the seven gates, three outcomes, division of labour with off-the-shelf tools | |
.claude/README.md | the skills and the agent worktrees | |
backlog/README.md | the backlog, generated index | |
docs/adr/README.md | the decisions, generated index | |
skeleton/infra/README.md | deploying a product to Fly.io | |
infra/runner/README.md | CI on our own box: sizing, the security condition, teardown | |
cli/commands/README.md, cli/core/README.md, cli/interview/README.md, cli/targets/README.md, cli/templates/README.md | one each for the CLI's subpackages: what the files in it do and where to go next. The command reference stays in cli/README.md | |
scripts/deploy/README.md | the scripts that create and tear down hosting, and the prove_*.sh rehearsals | |
skeleton/src/app/README.md, skeleton/alembic/README.md, skeleton/tests/README.md, skeleton/scripts/README.md, skeleton/docs/README.md, skeleton/infra/hetzner/README.md | the product's own directories, written for a reader inside a product, because every one of them is copied by saas new. skeleton/ itself has no README, for the collision explained above | |
docs/services/README.md, docs/sessions/README.md, docs/security-programme/README.md, docs/interview/README.md | what each docs/ subdirectory holds. docs/journeys/ has none, because scripts/check_journeys.py reads every .md there as a journey | |
reviews/README.md and roles/README.md | what a review pass is and how the dated rounds are laid out, and what a role is. The rules for roles stay in roles/CLAUDE.md |
A README carries frontmatter, because it is navigated to and indexed. Any file listing inside one is generated into a marked region when there is frontmatter to generate it from. scripts/README.md, tests/README.md and integrations/README.md name their contents in prose instead: Python files and a single signature have no frontmatter for a generator to read, and every path they name is a backtick claim that scripts/check_doc_paths.py resolves, so a rename turns the page red.
Reading order
New to the project, in this order: README.md, this file, docs/PROCESS.md, docs/PIPELINE.md. That is enough to work. Everything else is reference, reached when you need it.
An agent given a scoped task reads: the root CLAUDE.md, the CLAUDE.md of each directory it will touch, and the specific rules its brief names. Not all of PROCESS.md.