How Claude Code works with your repo.

The installed CLAUDE.md imports three small files at load time — docs/GOAL.md and the spec and ADR indexes — so every session begins already knowing the goal, which milestones are done, and what knowledge exists.

Full specs, ADRs, and code stay on disk until a task needs them; the indexes and the source-to-doc map tell Claude exactly which file to read for the task at hand. The conversation is a scratchpad; the docs bundle is the memory.

1. What are you building, and for whom?
2. What exists when it’s done — concretely?
3. What will users actually give it — realistic example inputs, including a messy or wrong one?
4. How is that verified mechanically? What’s the test command?
5. What should this repo deliberately not do?
6. Which stack and dependency choices are fixed, and which may Claude decide later through proposed ADRs?
7. What’s the first shippable slice, and how do we check it?

It pushes back on answers it can’t verify — “migrate the API to GraphQL” is a direction, not a done state — and in an existing codebase it proposes answers from the code first and lets you correct them.

1. Take the first unchecked milestone from docs/GOAL.md.
2. Impact analysis — name the specs and ADRs that govern the files about to change, and read them.
3. Implement the smallest change that satisfies the milestone.
4. Run the test command and make it pass.
5. Knowledge alignment — update the governing spec or ADR if behavior changed, and add a dated docs/log.md entry. The stale-map check catches anything missed.
6. Check the milestone off only when its stated verification passes, then take the next one.

The loop stops on its own in exactly three cases: the backlog is empty, a decision reserved for you comes up, or you say stop. An empty backlog isn’t a dead end — Claude first runs an acceptance pass, exercising the deliverable the way a first-time user would, then reports the goal met with any still-proposed ADRs listed, and proposes candidate next milestones for you to choose from.

Misfires are harvested, not hidden. When a helper meets a shape it doesn’t recognize — an index kept as a table, a naming convention it hasn’t seen — it declines visibly rather than guessing, and Claude works around it in the open. That friction is carried back into the kit as a proposed change. A silent workaround would hide the defect and re-pay its cost in every session; harvesting it pays once, in the kit.

Know the limit. These guardrails are instructions, not mechanical enforcement. The kit’s mechanical gates are docs sync (hooks) and a settings rule denying reads of local .env files — nothing else. When a rule must be guaranteed rather than followed — tests green before merge, no secrets in commits — put it in your repo’s own CI and branch protection, on top of this kit.

Milestone checkboxes, the dated log, ADRs, and git commits are the durable record — a fresh session reads them, with the goal preloaded, and knows exactly where the loop stands.

If a session was cut off mid-milestone, the next one treats uncommitted changes as in-flight work: it reconciles them against the first unchecked milestone and the newest log entry, then finishes or backs them out before taking anything new.

git clone https://github.com/lilabrooks/claude-okf-repo-kit.git
cd claude-okf-repo-kit
bash scripts/install-kit /path/to/target-repo
bash scripts/verify-install /path/to/target-repo

Then open the target repo in Claude Code — it runs the goal interview with you before the first task. Full instructions, the manual paths, and verification details are in the README.