# 08 — How we work `AGENTS.md` D17. Pouya architects. Claude Code implements, then adversarially reviews its own work. This is a standing agreement encoded in the repository, so it does not need restating in every prompt. --- ## The short version ``` /build the /med-arb/ page ``` That single command runs: plan → implement → adversarial review → resolve → verify → record. It requests deep reasoning, reads `AGENTS.md` and the specs, stops if the task conflicts with a locked decision, invokes `adversarial-reviewer` on the finished diff, resolves what it finds, runs the checks, and appends the Change Log entry. You do not need to ask for thinking, for review, or for the record to be updated. Those are the agreement, not the request. ## The three commands | Command | Does | |---|---| | `/build ` | The full loop. Use for every substantive change | | `/review [scope]` | The **code** review alone, on the working tree or a named scope. Reports; fixes nothing without your say-so. Under D20 it does not run the claims pass | | `/wrap` | End of session — updates `AGENTS.md` under its constitution and leaves the tree clean | ## The two reviewers, and when each of them runs — D20 Both are defined in `.claude/agents/`. **They no longer run together.** **`adversarial-reviewer` runs on every build step.** It reads the code: correctness and edge cases, accessibility, crawlability, performance budgets, security, and whether a materially simpler correct version exists. **`claims-auditor` runs once, at cutover, over the whole finished site.** It reads the copy against `AGENTS.md` §4 and nothing else — extracting every factual assertion (credentials, roles, numbers, languages, locations, capabilities, and the JSON-LD) and tracing each to the Verified table. Anything untraceable is reported and does not ship. `docs/06`'s cutover checklist carries it as a blocking item, alongside your own read of every page against §4. It is a separate agent on purpose. A general-purpose reviewer will happily approve elegant code containing a claim that should never have been published, because professional-conduct compliance is not what it is looking at. On this project that is the highest-stakes failure mode, so it keeps its own pass. ### Why the claims pass moved, and what it costs Your ruling, 2026-08-30. `AGENTS.md` D20 carries it in full; the short form: - **Nothing has shipped.** Every claims finding to date has been about a page no visitor can reach. The risk is deferred to cutover whether or not the audit is. - **One pass over twenty finished pages catches more than nine over drafts**, because it reads the site as a visitor does. The `/med-arb/` ADRIC gloss is the proof: no individual claim was false, the defect was **adjacency**, and adjacency does not exist until the pages sit next to each other. - **The code reviewer stays per step because what it catches compounds.** An accessibility or crawlability defect propagates into the next page built on it. A claims defect does not compound; it sits there until someone reads it. **What it costs, stated rather than glossed:** a claims defect can now live in an unpublished draft for weeks. Two things carry that risk in the meantime, and neither is a substitute for the cutover pass — **`npm run check:claims`**, which is unchanged and runs on every build and both deploy paths, and **you reading the copy as it is built.** ## Verifying the agents are loaded **`.claude/agents/` is the correct location.** To confirm the agents are live, invoke one directly: ``` Use the claims-auditor agent to audit README.md against AGENTS.md §4. ``` A verdict table back means both are wired. "No such agent" means the frontmatter needs looking at. **Agent definitions load at session start.** An edit to `.claude/agents/*.md` does not reach a running session — the version in force is the one that was on disk when the session began. So after changing a brief, restart before relying on it, and **say in the report which version actually ran.** This is not theoretical: the gloss lens was added to `claims-auditor` on 2026-08-30 and the agent reconstructed it from the Change Log rather than having it in its brief, because the edit and the run were in the same session. **Both are instructed to treat uncertainty as a defect.** They will sometimes be wrong. That is the intended trade: explaining why a finding is mistaken costs minutes, and a missed defect on this project's public marketing pages costs a great deal more. **This weighs heavier on the cutover pass, not lighter** — there is nothing behind it, so D19's two-round cap does not apply there. ## The rule that makes it work **A reviewer is given the diff and the specs — never the implementer's explanation of why the work is correct.** A rationale anchors the reviewer. Told why something is right, a reviewer looks for confirmation and finds it; given only the artefact, it forms an independent view. That independence is the entire mechanism. Every other detail of this protocol is adjustable — D20 just adjusted one of them. This one is not. --- ## Writing a task The commands carry the process, so your prompt only needs to carry the decision. Short and specific beats long and hedged. **Good:** ``` /build the /med-arb/ page per docs/01-architecture.md ``` ``` /build step 5 of the build order — the practice index and all six area pages ``` ``` /build the intake form on /contact/, per docs/05-backend-spec.md. Booking stays parked — reserve the slot, render nothing. ``` **When you are making a decision rather than assigning work**, say so plainly and let it record the decision: ``` Decision: drop the /for-parties/ page. The plain-language audience can be served by a section on /mediation/ instead. Update AGENTS.md and the architecture spec, then tell me what else this affects. ``` **When you want an opinion before committing**, ask for one — do not ask for code: ``` Before building /fees/: read docs/07-fees.md and tell me what a referring lawyer would find missing from that page. Do not write anything yet. ``` ## What it will do without being asked - Stop and ask when a task conflicts with a locked decision, or needs a fact it does not have. A blocked build is a correct build. - Leave `TODO(pouya)` in the source and a numbered question in `AGENTS.md` §9 rather than inventing a fact or softening a claim into something defensible. - Surface `AGENTS.md` §12 Standing Reminders at the start of a substantial session — including R1, your standing instruction about the licensure wording. - Refuse to publish a claim that is not in the §4 Verified register. - Append a Change Log entry covering decisions and plans, not only code. ## What to watch for **A review that finds nothing.** Possible, but it should be rare, and it must list which lenses were applied and what was checked. "Looks good" is not a review — send it back. **Findings declined without a reason.** Declining is legitimate. Declining silently is not; the reasoning belongs in the Change Log so a later reader can see that judgement was exercised rather than the finding missed. **A check reported as passing that was not run.** "Should pass" is not a result. If a build, a Lighthouse run, or a JavaScript-disabled render was not actually executed, it must say so. **A report that says "reviewed" without naming which agent ran.** Under D20 a build step gets `adversarial-reviewer` and not the claims pass; "reviewed" reads as both. The report must name the one that ran.