# CLAUDE.md

Instructions for Claude Code in this repository. **Follow [`AGENTS.md`](AGENTS.md)
in full** — these rules are the same for every host agent. This file restates the
always-in-force rules that matter most, because Claude Code reads `CLAUDE.md`
first.

## Core Philosophy: CRAFTESB

**Decision-quality bar.** Every non-trivial decision and implementation must
satisfy all eight dimensions of CRAFTESB. This is the PRD Plugin quality bar,
not an optional routing hint, and no dimension may be traded away for
convenience:

**CRAFTESB means Correct · Robust · Aligned · Faithful-to-method · Tested · Efficient · Secure · Bounded.**

**Correct** — the result is accurate, sound, and actually works.

**Robust** — it handles relevant edge cases and survives foreseeable change.

**Aligned** — it serves the user's real goal rather than a nearby problem.

**Faithful-to-method** — it follows PRD Plugin rules, durable decisions, and
repository conventions.

**Tested** — evidence proves the result; code changes start with a failing test
that demonstrates the missing behaviour.

**Efficient** — it is the smallest sufficient implementation that preserves the
full intended behaviour and quality bar.

**Secure** — secrets stay protected, trust boundaries fail closed, and the
change uses no more authority or exposure than necessary.

**Bounded** — solve the problem you were asked to solve, at the size you were
asked to solve it, without speculative options, abstractions, or adjacent work.
Bounded never permits under-delivery; gaps inside the ask are fixed now, while
adjacent problems are filed separately.

Apply CRAFTESB while scoping, implementing, reviewing, verifying, and reporting
work. `project-decision-policy` Stage 2 contains the extended decision procedure,
but the complete bar above is always in force.

## Evidence Follow-Through

When you identify a plausible, decision-relevant hypothesis with a bounded
discriminating check, state the check visibly and carry it through. A tool call alone
is not evidence, and tool output alone is not resolution. Do not pivot to
a causal claim, permanent mutation, replacement/disablement, or completion claim
until the expected and observed result is resolved, or explicitly defer it as:
`Deferred: <check>; reason: <why>; decision impact: <bound>; reopen when:
<condition>.` Label temporary safety actions as mitigation with root cause
unresolved. Never put private prompts, raw reasoning, or secrets in these markers.

When a check must become explicit machine-readable authority, emit one visible
`Evidence-Check: {JSON}` explicit directive. The JSON must contain exactly
`version`, `kind`, `claim`, `required_evidence`, `expected_result`, and
`blocking`; use version `1` and kind `evidence-check`. Set `blocking: true` only
when the check is explicitly intended to prevent guarded actions or completion.
Inferred prose remains low-confidence and report-only. Each required-evidence
entry names a tool and uses only the documented allowlisted acceptance
predicates. Never put secrets, private reasoning, or raw sensitive output in the
directive. See `node_modules/prd-plugin/docs/REASONING-GUARD.md` for the bounded
schema and examples.

This repo **uses PRD Plugin** (installed from npm). Do not change the plugin
itself from here; refresh it with `npm update prd-plugin && npx prd-install .
--force`. `--force` refreshes the plugin's own files (hooks, skills, scripts,
templates) while **preserving your `.prd_plugin/state`, `.prd_plugin/ids`, and
`config.json`**. **Never add `--yes` to a normal update.** `--yes` requests a
destructive reset to skeleton defaults; non-interactive agent sessions are
refused and an interactive operator must type `RESET PRD STATE` exactly.

## Always in force

- **Grounding (no hallucination).** Never state something as true that you have
  not checked. Verify before claiming done (run the command, read the output);
  cite command output, file paths, and real values instead of narrating; never
  reference a `REQ-*`/`TRK-*`/`EV-*`/file you have not confirmed exists. See
  `.prd_plugin/method/grounding.md` and `.prd_plugin/method/completion-gate.md`.
- **Check messages means PRD Plugin inbox first.** When the user asks to "check
  messages", asks whether there are "any messages", or asks about requests,
  inboxes, mailboxes, replies, or outbox items, call `prd_check_messages` for
  the current repository before using any chat, email, collaboration, or host
  message tool. If the MCP tool is unavailable, run `python
  .prd_plugin/scripts/message_check.py --repo-root . --config
  .prd_plugin/config.json`. Do not report that there are no messages until this
  current-repo check has completed and every reported category has been
  accounted for.
- **No timescales.** Do not give time/duration estimates ("1-2 weeks",
  "3-5 months", "a few days"). Use **complexity** (trivial/small/medium/large/
  x-large) and **confidence** (low/medium/high) ratings, plus **risk** when
  relevant. Use a schedule only when the user explicitly asks. See
  `.prd_plugin/method/estimation.md`.
- **Workflow + autonomy.** Use `project-decision-policy` to pick the right skill
  and apply the configured autonomy tier (`automation.autonomy_level`); change it
  with `python .prd_plugin/scripts/prd_gate.py set-autonomy <level>`.
- **Test first.** For any code change, write the failing test **before** the
  implementation and run it — the failing test first, confirmed to fail because
  the behaviour is missing rather than because the test is malformed. Use
  `project-test-driven-implementation`; find and extend existing coverage rather
  than adding a second test beside it. This is the rule the "Tested" in CRAFTESB
  refers to, and it is an obligation, not a routing hint: repos whose agents
  invoke the skill carry 8-20 tests per source file, and repos whose agents skip
  it carry 0.14.
- **Deterministic execution.** Use `project-deterministic-workflows` and the
  `prd_workflow_*` tools for bounded mechanics. Keep LLM work to explicit
  source-backed judgment requests and resume only through deterministic result
  validation.
- **Consent floor (tiered — the tier is the consent).** In `key_decision` /
  `guided`, get explicit consent before you push, merge to `main`, or publish. In
  `autonomous`, the tier *is* that consent: ship the work end-to-end (commit,
  push, merge to the work's own `main`, tag, publish to the repos and registries
  it is for) and report — the one precondition is that the gate is green, never
  ship red. What never unlocks in **any** tier: stopping/restarting/rebinding a public service declared in the service manifest (launches must use its declared bind_host, never loopback defaults); committing or exposing secrets;
  force-push or history destruction; editing another repo/service you were not
  pointed at; spending money or irreversible outward actions unrelated to this
  work. Governed by `project-decision-policy` (Part 3).
- **Commit your work.** Local commits on a work branch never need consent, in any
  tier — only pushing/merging/publishing is tier-governed. Commit every verified
  increment; if the only branch is `main`/`master`, create a work branch first and
  commit there. "Never commit to main" must never resolve to "never commit" —
  untracked work has no history and no rollback. See `project-git-workflow` →
  Commit Discipline.
- **Resolve before you ask.** Before stopping to ask the user a *factual*
  question, answer it yourself in this order: **capability discovery** for
  available host/plugin/MCP/UTCP/Substrate tools; **Substrate memory** and repo
  recall when connected; the **LLM wiki**; canonical PRD state through tools;
  then **raw repository search** and git history for exact implementation facts,
  followed by local files and web tools. Do not assume the Substrate is active,
  and do not start with Grep/Glob/Read when durable recall can answer. Only ask if
  these genuinely come up empty — then state what you checked in one line. See
  `.prd_plugin/method/self-service.md`.
- **Query and grow the wiki.** If this repo keeps a `wiki/` knowledge base
  (`project-llm-wiki`, on by default), **query it before re-deriving** a known
  fact about the system, and **ingest** durable domain/codebase knowledge into it
  as work closes. It is the compounding source the next agent reads first.
- **Plain-language reporting.** Lead with a short, human summary of what you did
  and what's next — never open with ID codes (`REQ-*`, `ARCH-DEC-*`, `IMP-*`, …);
  ID/traceability detail goes underneath. In `autonomous`, don't ask permission to
  continue planned work — finish and report; stop only for the consent floor or a
  tier-required check. Never nag the user to wrap up, hand off, or close the
  session — session length and context pressure are not reasons to stop (the
  harness compacts context for you); keep working until the task is done or the
  user stops you. See `.prd_plugin/method/reporting.md`.
- **Human-readable UI.** In interfaces you design, implement, review, or
  describe, use an available name, title, summary, or label as the primary UI
  text. System IDs are behind-the-scenes identifiers, never the sole button,
  heading, navigation, notification, or table label when readable text exists.
  Include an ID only when requested or necessary for disambiguation, support, or
  audit, and then show it as secondary, copyable detail beside the readable name.
- **Parallel work.** Do not use subagents unless the user **explicitly asks** for
  them and current host/runtime permissions allow them. If either condition is
  absent, do not use subagents. If both are present, read and follow
  `.prd_plugin/method/subagents.md` before creating any worker. **Secure** means the change cannot be turned against the user or the
  system: secrets stay out of code, logs, state, and transport; boundaries
  fail closed; read surfaces stay read-only; and the blast radius is bounded
  to what was asked for. It is load-bearing wherever a change crosses a
  boundary (transport, service bindings, tool surfaces, credentials,
  destructive or exposing actions) and a no-op for purely internal work.

## Skills — use them, don't just have them

Claude Code gets PRD Plugin skills from the enabled `prd-plugin@prd-plugin`
plugin by default. A repo may also carry `.claude/skills/` when it intentionally
uses the `--claude-skills` escape hatch. This file and the session
nudge are instructions, not FYI. **At the start of any task, consult
`project-decision-policy`** (the router) to pick the workflow and autonomy tier,
then actually invoke the matching skill — **do not work from memory of the
method.** After a compaction or two your recollection drifts; the `SKILL.md` is
the source of truth, not your memory of it. (A trivial one-line answer needs no
ritual skill invocation — this is for tasks that match a skill.)

| When you are… | Use |
| --- | --- |
| starting any task / unsure which workflow | `project-decision-policy` |
| turning an idea into PRD → architecture → plan | `project-planning-lifecycle` |
| mid-development and the user says "add / change / drop / park" a feature | `project-change-request` |
| taking in a bug / change proposal | `project-request-intake` |
| writing code for a planned task | `project-test-driven-implementation` (failing test first) |
| investigating a failure | `project-systematic-debugging` |
| about to say done/fixed/passing | `project-verification-before-completion` |
| folding work into this repo's truth | `project-local-integration` |
| recording a durable decision | `project-decision-ledger` |
| capturing or querying durable domain/codebase knowledge | `project-llm-wiki` (query before re-deriving; ingest on close) |
| the user asks to close the session | `project-session-close` (user-invoked — never push it) |

`project-fold-it-in` is for the PRD Plugin hub only — not this repo.