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 |
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/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/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/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/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/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/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/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 | 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. 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 |
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, and the dependency graph. One row for the whole directory, because it is one artifact in eleven files rather than eleven documents. make dashboard, checked by make doc-gates, deployed by duchovni-net reading the files | any judgement, and any fact that is not in a tracked file - the live quota, 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 |
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/ |
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 |
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 |
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 and docs/products/*/journeys/*.md | 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 | the template's own vocabulary, that is GLOSSARY, what a journey file has to look like, that is PRODUCT-JOURNEYS, 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 |
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.