standards/ — how I build, write, and work with AI
📐 standards/: how I build, write, and work with AI
  
The single source of truth for how I work across every repo: how I build software with an AI partner, how anything under my byline reads, and how a new repo is set up. Public and portable: any repo of mine references this folder instead of copying its own drifting rules.
How to use this, human or AI: read this index first, then fetch only the standard the task in front of you needs. Each line below is the whole hook: that's the point, so you load one file, not six.
The standards
| Read this when you're… | Standard | In one line |
|---|---|---|
| Building anything with an AI | AI-DEVELOPMENT.md | The working relationship, the definition of done, the conventions and pitfalls every change is held to. The rulebook. |
| Structuring a repo so AI sessions compound | AI-REPO-STANDARD.md | The repo-side companion to AI-DEVELOPMENT: the kit you commit (the map, the contracts, the guardrails) so every AI session inherits what the last one learned. AI-DEVELOPMENT owns the working relationship; this owns the repo. |
| Deciding where a file lives / unbloating a root | TREE.md | The layout standard: keep the root a readable index, only load-bearing files earn a place there, everything else folds one level down into a named home. AI-REPO-STANDARD owns which files exist; this owns where they sit. |
| Running a session / handing off | SESSION-LOOP.md | The session lifecycle: orient, the loop, the recurring chores, memory (so lessons stick), the handoff, and model economy. |
| Running one AI workflow across every repo | LOOP.md | The system around the sessions: the work-triggered heartbeat that makes skipped chores visible, the thin-kit shape, the accountability contract that keeps an unattended run honest. One floor above SESSION-LOOP. |
| Answering a code question without burning the window | GRAPH.md | Ask the code graph a scoped question before you fan out grep, reads, and subagents. Query by symbol not prose, keep it fresh with a free per-edit hook, never commit the artifact. The retrieval half of the loop. |
| Writing prose in my name | VOICE.md | The writing standard: cadence, the honesty clause, the machine-tells to refuse. Owns how it reads. |
| Drafting a note / blog post | NOTE-STANDARD.md | How a note is built (frontmatter, structure, footer), plus a runnable prompt. Owns the artifact; VOICE owns the words. |
| Making a diagram or chart | FIGURES.md | The figure standard: two tokenized inline-SVG scaffolds (data-viz + flow), one palette each, no mermaid on the published site. |
| Setting up a README | README-STANDARD.md | Title emoji, the honest badge row, the "built with Claude" footer, plus a runnable prompt. |
| Deciding which stack layers a new project needs | KICKSTART.md | A paste-in prompt that interviews you, reads the live stack and the public repos, and proposes which BREAD layers your project actually needs (and which it does not). The on-ramp before the repo exists. |
| Starting a new repo | CLAUDE.starter.md | The CLAUDE.md template that wires a fresh repo into all of the above from day one. |
How they fit together
- AI-DEVELOPMENT + SESSION-LOOP are the engineering pair: the first is the standards, the second
is the session mechanics that run against them. Start here for any building work.
- LOOP sits one floor above the pair: SESSION-LOOP owns a single session, LOOP owns the system that
spans them: the heartbeat, the shared kit shape, the contract that holds across a whole estate of repos worked the same way. Read it when the question is "how does every repo run," not "how does this session run."
- TREE is the layout companion to AI-REPO-STANDARD: the latter decides which files a repo commits,
TREE decides where each one sits and keeps the root a readable index instead of a junk drawer. Read it when a root has grown past a screen or a file has no obvious home.
- GRAPH is the retrieval half of that loop: a narrow rule for answering a structural code question
cheaply (ask the graph before you fan out) that SESSION-LOOP's model economy and LOOP's heartbeat both lean on. Read it the moment you catch yourself about to grep the whole tree.
- VOICE + NOTE-STANDARD + README-STANDARD + FIGURES are the writing set: VOICE owns the prose,
the others own specific artifacts and point back at it. Start here for any published words.
- KICKSTART + CLAUDE.starter are the two on-ramps, in order: KICKSTART runs *before the repo
exists*, deciding which layers the project needs; CLAUDE.starter is how the repo you then create inherits the whole set from day one.
The one rule this folder lives by
Single source of truth, everywhere. Each fact has exactly one home here; every other mention is a pointer, never a copy. Two copies of a rule drift, and then both are suspect. If you find the same thing stated in two of these files, one of them is a bug: fix it to a link.
🤖 Built with Claude, rules included. The standards that govern how I work with an AI were themselves written with one, which is either very meta or very honest, and I am going with both. I don't prompt and pray, I prompt and prove. How I actually work with AI, receipts and all →