Claude Code · Open Knowledge Format
The kit packages the setup you would otherwise assemble by hand to run goal-driven development with Claude Code: an owner-defined outcome becomes verified milestones, behavior specifications, proposed architecture decisions, and a progress log that change with the code.
Why it exists. Claude Code is the agentic coding tool — Claude directing its own tools in a loop. The kit isn’t another agent or tool; it’s the memory, skills, hooks, and knowledge that give that loop a goal, guardrails, and a reviewable record in the repository’s shared history.
The baseline
Claude Code carries knowledge between sessions, but not as a versioned, reviewable part of the repository. The kit is what makes it that.
The built-in /goal command keeps a session working toward a completion condition, and auto memory carries notes across sessions. But /goal is session-scoped and clears once met, and auto memory is machine-local and unversioned — neither becomes part of the repository a teammate reviews in a diff.
It places the owner-approved goal, ordered milestones, behavior specifications, architecture decisions, progress log, and source mappings in version control — so the objective and the decisions that reached it outlive the session that created them, and a fresh session can pick them up while a reviewer reads them in an ordinary diff.
What the kit adds
The contract says who owns the outcome, how Claude chooses work, where behavior and decisions are recorded, and what must be reviewed.
The owner confirms the problem, target state, success criteria, non-goals, fixed constraints, and milestone order.
“Continue” runs Claude Code’s agent loop over the backlog: Claude takes the first unfinished milestone, reads its governing context, edits code, and runs the tests — using that environmental feedback as ground truth for whether the milestone is done. It runs a first-time-user acceptance pass before declaring the goal met, and resumes in-flight work after an interrupted session.
Claude authors or updates the governing specification when behavior changes. The source map connects code areas to the contracts that describe them.
Dependencies, persistence, APIs, security boundaries, deployment, and similar choices begin as ADRs Claude writes itself, marked proposed. The owner accepts, revises, or rejects them.
The loop
You define the goal. From it, Claude Code drafts an ordered milestone backlog for you to confirm, then works the milestones one at a time — reading the specs and ADRs that govern each area before it edits, proposing an ADR whenever a change is decision-shaped, and writing or updating the behavior spec whenever behavior moves. Every milestone is verified and logged before the next begins.
Claude drafts the milestones, writes the specs, and writes the ADRs as proposals. You own the goal and confirm the milestones, and you accept, revise, or reject each proposed ADR.
A Claude Code session opens with a fresh, limited context window. The kit keeps the goal, milestones, specs, ADRs, and log in git and preloads only the goal and the spec and ADR indexes at session start — the rest is read from disk on demand, so the record survives every context reset.
What the kit installs
The knowledge bundle follows the Open Knowledge Format, an open spec for project knowledge that travels with the code. It rides Claude Code’s own extension points — project memory, skills, and hooks — so the kit is configuration, not a separate engine, and nothing here is hidden state: it is committed, diffable, and reviewed like source.
Holds the goal, rules, workflow, and verification commands. Its imports preload the goal and the spec and ADR indexes at session start, so Claude begins already knowing the project.
States the problem, target state, success criteria, and an ordered milestone backlog that Claude iterates toward across sessions.
Behavior contracts to preserve and architecture decisions to follow, versioned beside the code they govern. These paths are the defaults — a repo that already keeps specs or ADRs elsewhere points the kit at them with a small layout block in the source map, and nothing gets moved.
Maps source areas to the specs and ADRs that govern them, so Claude reads the right knowledge before editing and stale mappings can be caught.
A stop hook catches code changes with no matching docs update; a session-start hook reports version drift and pending decisions. Local helper commands find stale mappings, draft specs, and suggest ADRs.
Six skills load on demand — goal interview, acceptance pass, ADR review, kit upgrade, a guided adoption pass for existing repositories, and a guided port for adding a second agent — with binding one-liners kept in CLAUDE.md for when a skill does not load.
What is verified
The kit has two layers, in Anthropic’s terms: deterministic hooks that run as fixed code paths, and the agentic work Claude does with judgment. The test suite covers the first; the content of a specification or decision is the second, and still needs technical review.
The installed CLAUDE.md and on-demand skills preload the goal and tell Claude how to select, verify, and close milestones across sessions.
Claude is instructed to write and maintain specs. The kit supplies structure and checks for stale mappings; it does not prove that a contract is complete or correct.
Decision-shaped work starts with a proposed ADR. The kit can suggest and scaffold it; Claude fills the reasoning and the owner makes the decision.
A stop-time hook can prevent a turn from ending when code changed without a documentation update. A mapped spec, ADR, or dated rationale satisfies the check.
Within those layers, the division of labor is deliberate. Hooks carry what must never be skipped: they run as fixed code paths at session start and stop, whether or not anyone remembers them. The scripts/okf helper carries what must never vary: numbering, index entries, and staleness are computed in code, so Claude runs one command instead of re-deriving the mechanics each session and spends its judgment — and its context window — on the content of the work. Preloaded indexes carry what every session must know. When a mechanism misfires in a real repository, the helper declines visibly rather than guessing, Claude works around it in the open, and the friction is carried back into the kit — that is the dogfood record, not a failure mode.
The enforcement boundary matters. The hooks verify that expected files changed and mappings remain current. They cannot judge the quality of the reasoning. Test discipline, security rules, and consent rules remain instructions unless the target repository enforces them through CI, permissions, or branch protection.
Adopting the kit
The kit has separate paths for a new repository and a repository with existing code, documentation, and agent settings.
The new-repository path creates the project instructions, goal template, knowledge bundle, source map, hooks, and local helper.
The existing-repository path preserves current files, merges compatible settings, and writes review candidates when names or locally edited kit files conflict. After the updater, the installed adoption skill carries a guided pass: inventory the existing knowledge in place, map it to the source it governs, backfill missing specs, and validate before the loop starts.
Stack templates
The kit stays deliberately stack-agnostic: it installs the operating contract and nothing about any language, and the goal loop builds a stack from an empty repository perfectly well on its own. A stack template is an optional accelerator, not a requirement — when you build the same kind of project often, it saves re-deriving a toolchain you already trust. Those repeating decisions — packaging, quality gates, CI — belong in a separate template repository that layers under the kit, so neither release cadence pollutes the other.
A stack template is a minimal working project — a walking skeleton that passes its own quality gate in its own CI, so it cannot rot silently the way a bag of file stubs does. When you choose to use one, creating a project means starting from the template, renaming it, then running the kit's existing-repository installer over the result. The kit needs no changes to compose this way: layering onto whatever exists is what the brownfield path already does — the same path an ordinary existing repository takes.
The first stack template covers Python command-line tools, seeded from the proven chassis of the Spec Agent CLI dogfood repository: zero-runtime-dependency packaging with optional extras, ruff and strict mypy, pytest with a branch-coverage floor, repo-health tests that guard the repository itself, and a CI matrix across supported Pythons — decisions with their ADR reasoning attached, not just files. Spec Agent CLI itself stays what it is: the kit's dogfood exhibit and the template's one-time seed.
Where the approach helps
The method earns its cost when work spans sessions, decisions carry consequences, or several people and agents need the same project record.
Milestones, logs, and accepted decisions give a fresh session a reliable restart point.
Architecture choices remain visible with their context, consequences, and revisit conditions.
People and agents can review the same goal, contracts, and pending decisions through ordinary version control.
Owner boundaries, verification rules, and explicit review points reduce silent changes to scope and architecture.
The evidence is still early. The source-kit tests validate the mechanisms, and the dogfood repositories provide concrete findings. They do not establish a measured improvement in delivery time, defects, or maintenance cost. A small one-session change may cost less to handle directly.
Evidence from use
Spec Agent CLI, Repo Pulse, Skywatch, and an AWS alerting service exercised different repository shapes — greenfield, scheduled multi-service, and two kinds of brownfield. Their findings changed the kit’s goal interview, acceptance pass, hooks, source mapping, upgrade policy, review loop, and brownfield adoption path.
Each use case, the weakness it exposed, and the change carried back into the source kit.
The goal, specifications, decision records, templates, tests, and change log are public.