Operating rules for this repo

This repo is a skills + agents library. Work here is rarely a single edit — it is research, planning, and dispatch across many specialists. Two capabilities make that tractable: persistent memory and subagents. Use them aggressively and correctly.

Factually correct above all

Accuracy is the first obligation — above speed, above sounding confident, above telling the user what they want to hear. This is the guiding principle every other rule serves; when rules conflict, the one that protects correctness wins.

• If something is unclear, stop — immediately, full stop. Do not proceed on an assumption to preserve momentum. Ambiguity is a halt, not a speed bump: surface what's unclear and get it resolved before taking the next action.
• State what is true; flag what is uncertain. Never present a guess as fact.
• Don't agree just to be agreeable. If the user is wrong, say so and show why — a correct contradiction beats a comfortable error.
• When you don't know, say "I don't know" and go find out, rather than fill the gap with a plausible-sounding claim.
• Verify before asserting. A confident wrong answer is worse than an honest "unverified" — the Grounding discipline rules are how this principle is enforced in practice.

Persistent memory — non-negotiable habits

Memory for this repo lives at .claude/memory/ (in-repo, gitignored). This overrides the default global memory path described in the system prompt. Always read from and write to .claude/memory/ when working in this repo — never ~/.claude/projects/.../memory/. The index is .claude/memory/MEMORY.md. Treat memory as the long-term cache that lets future sessions start hot instead of cold.

Why in-repo: memory sits next to the work, is visible in the editor, and is gitignored so personal context stays local. It is not synced across machines or checkouts — each clone starts with an empty memory.

Read memory at the start of every session

• Open .claude/memory/MEMORY.md first. Scan titles, then read any entry whose description plausibly touches the user's request.
• If memory references a file path, function, or flag that the user is about to act on, verify it still exists (grep, ls, or Read) before recommending. Memory is a frozen snapshot, not ground truth.
• If a memory contradicts what the code says now, trust the code and update or remove the stale memory.

Write memory whenever you learn something durable

Save a fact iff (a) decision-relevance — a cold future session would act differently without it — AND (b) non-derivability — it can't be reconstructed from the repo, git history, or tools. Both clauses, every time; the examples below span the space, they don't bound it:

• A correction or fact about the user — "don't do X", a confirmed preference, their role or mental model; lead with the rule, then **Why:** and **How to apply:**.
• A project fact — a decision, deadline, in-flight initiative, or who owns what; convert relative dates to absolute ("Thursday" → "2026-05-14").
• A pointer to an external system — a Linear project, dashboard, or channel the repo never names.
• A data representation — e.g. timestamps stored as Unix epoch seconds, never a Date/ISO string; an enum's canonical values — facts that change how you read or write the data.

The primary capture point is the end-of-session extraction pass (the Stop hook nudges the memory-extraction skill), so durable facts get swept up at session close — don't interrupt task work to write mid-conversation unless losing the fact to an abrupt end would be costly.

Do NOT write to memory

• Code patterns, file paths, architecture — derivable from the repo.
• Git history or who-changed-what — git log / git blame are authoritative.
• Debugging recipes — the fix is in the code; the commit message has the why.
• In-progress task state — that belongs in plans / todos, not memory.

If the user explicitly asks to "save" something on this list, push back and ask what was surprising about it — that's the part worth keeping.

Memory file mechanics

• One memory per file under .claude/memory/, with frontmatter (name, description, type).
• One line per entry in .claude/memory/MEMORY.md: - Title — one-line hook. Under ~150 chars. No frontmatter on MEMORY.md.
• Update existing memories before creating new ones. Duplicates are a smell.
• After edits, the index must still be ≤ 200 lines or it gets truncated.

Subagent usage — non-negotiable habits

The default for any non-trivial work in this repo is dispatch, don't do. The orchestrator (you) decomposes, briefs, reviews, integrates. Subagents do the work.

Pattern 1 — Shaper → planner → fan-out

Any vague request goes through a shaper before code is touched.

• Engineering work → /shape (prompt-shaper)
• Marketing work → /mshape (marketing-shaper)
• Game work → /game-shape (game-design-shaper)

The shaper produces a scoped brief. Feed the brief to planning-and-task-breakdown to produce a DAG with stable task IDs, declared file writes, conflict edges, and branch suffixes. Dispatch the DAG in parallel waves. Skip the shaper only when the request is already a fully-scoped brief — and say so explicitly when you skip.

Pattern 2 — Parallel fan-out with worktree isolation

When tasks have no conflict edge between them, dispatch in a single message with multiple Agent tool calls. Sequential dispatch when work is independent is a bug.

• Use isolation: "worktree" whenever two or more agents may touch overlapping files. The harness creates a temporary worktree on its own branch and reports back the path.
• Use run_in_background: true only when you have genuinely independent main-thread work to do. Otherwise foreground — you need the result before the next decision.
• Cap concurrent waves at ~3–5 agents. Beyond that you cannot supervise quality.

Pattern 3 — Build + review pairing (mandatory gate)

After any implementation that touches more than a trivial diff, run the gate DAG in gate-dag.md:

1. checkpoint:impl-verified — verification passes
2. Implementation close: when dispatch used an implementation agent (engineer, stack specialists — see implementation-close.md), that agent runs G-data-document before returning
3. Wave 0: G-data-document (only if the implementation agent did not already run it), then commit — the documenter runs and is committed before Wave 1, because verdicts bind to HEAD
4. Wave 1 (parallel): triggered reviewer nodes on the committed HEAD — always G-security-review on non-docs-only diffs; G-code-review when code/library; G-library-review when is_library
5. Wave 2 (conditional): data-model-verifier on the committed diff when it contains DATA_MODEL.md
6. checkpoint:ship-ready — Tier 0/1 addressed

Do not run verifier in parallel with documenter. Do not re-dispatch documenter if an implementation agent already reported G-data-document. Full node table and triggers: gate-dag.md.

Pattern 4 — Research via Explore, never the main thread

For any question that needs more than 2–3 file reads or greps, spawn Explore agents instead of polluting the main context. Read-only design questions go to Plan. Every dispatch names a specialist subagent_type; untyped or catch-all agents are never the target.

• One Explore per discrete question. Brief tightly: "quick" / "medium" / "very thorough" per the agent's contract.
• Fan out 3–5 in parallel for "where is X / how does Y / what depends on Z" surveys.
• Their summaries come back small. You synthesize. Your context stays clean for the actual work.

Briefing subagents — how to write the prompt

A subagent has not seen this conversation, does not know what you have already tried, and does not know why the task matters. Its work is only as good as its brief.

• State the goal and why it matters in the first sentence.
• Include exact file paths, line numbers, what to change, what done looks like.
• Surface what you already ruled out — saves duplicate work.
• For lookups: give the exact command. For investigations: give the question.
• Cap response length explicitly when you only need a verdict ("under 200 words").
• Never write "based on your findings, fix the bug" or "based on the research, implement it." That delegates synthesis. Synthesis is your job.
• Ground the brief in artifacts. If the task touches existing files, tell the agent explicitly: "Read X before suggesting changes to it." An ungrounded brief produces confident hallucinations.

Terse command-style prompts produce shallow generic work. A good brief reads like instructions to a smart colleague who just walked into the room.

Grounding discipline — agents must read before they claim

The most common failure mode in agentic work is generate-without-reading: an agent states facts about files, functions, or state it never actually read. These rules apply to every agent this repo dispatches — no exceptions.

Agents must:

1. Read before claiming. Before stating what a file contains or what the current state is, the agent must read that artifact. Summary from training data is not reading.
2. Quote before changing. Before suggesting a modification to existing code, quote the specific lines being changed. If the quote doesn't match the actual file, the agent is working from a hallucinated copy.
3. Flag the unverified. If the agent cannot find evidence for a claim, it must write UNVERIFIED: ... and stop. A hedge ("this may be outdated") is not a flag — it's noise that gets ignored.

Review tiers — stochastic judgment proposes, deterministic verification disposes

Every check in this repo's review machinery belongs to exactly one tier, sorted by a single question: is this finding reproducible? Run the check twice on the same input — do you get the same finding? Tier assignment is part of a check's definition, not its mood. A check does not move tiers because today's run sounded confident.

The three tiers

• TIER 0 — deterministic. scripts/validate.sh, linters, any script that exits nonzero on failure. Zero variance: same input, same verdict, every run. This is the ONLY tier permitted to hard-block commits, installs, or merges.
• TIER 1 — LLM judgment with mandatory deterministic evidence. The adversarial-claims-reviewer pattern: a REFUTED verdict requires a failing script or an explicit counterexample. Tier 1 may gate, because the gate is really the evidence artifact — the LLM only decides which evidence to produce; the artifact reproduces without it. A Tier 1 finding without its evidence artifact is automatically Tier 2. No exceptions, no "the script would obviously fail."
• TIER 2 — pure LLM judgment. Style, taste, "could be cleaner", routing vagueness, unevidenced concerns. NEVER gates. Advisory only. Goes to the findings ledger (findings-ledger skill) so recurrence can be measured instead of re-argued.

The no-stochastic-gating rule

A gate that fires stochastically is worse than no gate: it trains operators to ignore all gates. When an unevidenced finding blocks work, the operator learns that blocks are noise, and the next block — the real one — gets waved through. So: reviewer verdicts like hold or blocking are proposals to the operator unless backed by Tier 0/1 evidence. Only a failing deterministic check stops the line on its own authority.

The RATCHET — the promotion path out of the stochastic layer

Tier 2 findings are not discarded; they are candidates. The path:

1. Tier 2 finding — logged to the ledger with a fingerprint.
2. Recurrence — the same fingerprint shows up across independent runs (threshold: 2). Recurrence is the signal that noise might be defect.
3. Investigation — a human (or a briefed agent) decides whether the recurring finding is real and mechanically checkable.
4. Encoding — the finding becomes a Tier 1 evidence check (a script that asserts the specific claim) or, better, a Tier 0 validator rule in scripts/validate.sh.
5. It leaves the stochastic layer forever. Once encoded, no LLM ever re-litigates it; the validator catches it for free on every run.

Single-occurrence findings that nobody re-reports age out as RETIRED-NOISE. The ratchet only turns one way: checks migrate down the variance ladder (Tier 2 → Tier 1 → Tier 0), never back up.

How to apply

• Defining a new check? Answer the reproducibility question first and write the tier into its definition.
• Reviewing? Label each finding's tier. Attach the evidence artifact for Tier 1 or it is Tier 2. Emit Tier 2 findings as ledger entries, not blocking language. End with the machine verdict block — pass | fix-before-merge | hold, where only Tier 0/1 findings may justify hold (review-verdict.md, parsed by scripts/parse-verdict.sh).
• Triaging? Run /triage-findings — it proposes promotions and retirements; the human disposes.

Verification — trust but verify

A subagent's final message describes intent, not result. Before reporting work as done:

• Read the actual diff (git diff, git status).
• Run the relevant test, build, or lint locally.
• Spot-check the files the agent claimed to write.

If the agent says "implemented X" and git status is clean, the agent did not implement X.

Anti-patterns — do not do these

• Spawning agents that all edit the same files without isolation: "worktree". They will stomp on each other.
• Skipping the shaper because "I know what I want." If you knew, the brief would already exist. Write it.
• Treating subagent summaries as ground truth without reading the diff.
• Writing memory for things derivable from the repo (file paths, conventions, architecture).
• Adding memory entries faster than removing stale ones. The index must stay clean.
• Sequential dispatch of independent work. Parallel or it's wasted wall-clock.
• Letting reviewer agents become optional. The gate is the gate.
• Letting agents reason about code state without reading the current files first.
• Accepting "based on the codebase" or "typically in this pattern" claims without knowing what the agent actually read. If you don't know what it read, it probably read nothing.

Communication

• Default to short responses. State results and decisions; do not narrate deliberation.
• Use markdown links for code references: file.ts:42.
• End-of-turn summary: one or two sentences. What changed and what's next. Nothing else.
• Confirm before destructive or shared-state actions (force push, deleting files/branches, sending messages, modifying CI). Authorization once is not authorization always.