After an ADR, spec, epic, story or design is written or changed
Looks for weak spots, checks every claim against the source and asks how the plan could fail. No flattery.
opus · max.projectstore / method / 1
A loop with an independent check in it.
Agents write code fast, and they re-decide settled questions just as fast: every fresh session arrives empty. The fix is not a smarter agent. It is gather context → act → verify, run over the project and not only over the code.
The loop
Eight steps. Two of them are checks by an agent that did not write the draft.
- 01You say what you want. The agent opens an artifact before it opens an editor.
- 02An ADR when something needs deciding, an epic and stories for the work, a spec when the "how" is not obvious. Previewed, and written on your yes.
- 03A critic with a fresh context, and no stake in the draft, attacks it. Expect "revise".
- 04You approve the fixes. The artifact is marked reviewed and lands in the backlog.
- 05An agent picks up a story. The planner reads how earlier epics landed in the code and says where this change belongs.
- 06Code and tests, following the story's plan.
- 07A reviewer with a fresh context checks the diff against each acceptance criterion and asks for evidence.
- 08Done, with evidence under each criterion. The board, the link graph and the code map regenerate.
The agents
6 agents. All but one may only read.
The advisors check, plan and tidy up, and change nothing. One clerk saves only what you approved, after your Yes.
Before work on a story starts (story plan)
Looks at where earlier epics live in the code. Says where the change belongs, what to reuse, what to watch out for and in what order to work.
opus · maxAfter code, before commit or story close
Asks for proof on every acceptance criterion, including the spec's. Then checks correctness, regressions and tests.
opus · maxFrom time to time, before releases, after the vault grows fast
Finds what no rule can catch: research notes that contradict an accepted ADR, duplicates, missing links, files ready to archive.
opus · maxOnce, after binding an existing codebase
Finds decisions nobody wrote down, in the code, config files and git history. Suggests ADRs for them, with evidence.
opus · maxOnly inside a command flow, only after your Yes
Saves exactly what you approved, nothing more. Then rebuilds the board and runs the checks. Writes nothing of its own and asks nothing.
sonnet · maxThe default models are Claude Code's. In Codex each role is a skill of the same name that asks Codex to start the role, such as $projectstore-critic for the critic; it uses the session's model unless you set one.
The guards
Mechanisms hold it together, not discipline.
No story, a nudge
An agent that starts editing code with no story open is reminded to open one. A feature-sized change starts in the vault.
Unreviewed stays marked
An artifact that needs review carries review_status: pending until a critic pass is applied. "Not yet reviewed" is a state the tools can read, not something someone must remember.
A doctor with no AI in it
doctor checks the vault's mechanical consistency deterministically. In CI it runs with no agent and no tokens.
Where to look, generated
graph.md holds every artifact's links in both directions; code-map.md says where each epic's code lives. Before an architectural choice, the agent is pointed at the ADR index first.
After /compact, the vault comes back
In Claude Code, after a /compact you run, the session starts with the vault's orientation again, and with the vault files the conversation touched before it.
A second session is warned
A session that starts while another one works on the same vault opens with a multi-session warning: search before creating anything new.
Done means proven
A story closes with evidence under each criterion.
--- type: story epic: "CHECKOUT" title: "Saved cards are listed at checkout" status: done code_refs: ["src/billing/cards/", "tests/cards.test.ts"] closed_at: "2026-07-14T16:02:11Z" --- ## Acceptance Criteria - [x] Saved cards are listed first — evidence: tests/cards.test.ts:21 - [x] A declined card shows the bank's reason — evidence: tests/cards.test.ts:58 - [x] No card number reaches the logs — evidence: tests/cards.test.ts:73
The planner said where the change belongs before the code, and the plan went into the story on your yes; the reviewer checked the diff against each criterion after it. Each line of proof is a test, a command that ran, or a line of code.
Any agent can read this record, with or without the plugin: through the CLI, which answers with JSON and needs no tokens, or through the MCP server's 8 read-only tools.
- orientation
- search
- status
- get_artifact
- lineage
- neighbors
- code_refs
- doctor
Fine print
Fine print
- Running the loop costs tokens: the drafts, the critic and the reviewer run on the model you already pay for. The README measures it.
- The critic and the reviewer are separate agents with a fresh context in Claude Code. In Codex the roles are skills.
- ProjectStore is shared project context and a way of working. It is not an agent orchestrator: launching agents is your harness's job.