ClawAI: Instructions file for Claude Code

ClawAI — Claude Code notes

Start at AGENTS.md. It is the canonical router for every agent: identity, authority order, first command, how a change lands, the absolute prohibitions and where everything lives. This file adds only what is specific to working in Claude Code, plus a compact index (ADR-170).

Before you finish any change, update every doc it makes stale (rule 63). The hooks will reject it otherwise.

Testing is not optional. Before any change is called done, walk all 15 QA lanes and record them in docs/qa-evidence/<date>-<slug>.md (npm run qa:evidence:new). CI rejects a feat/fix push without a valid record. Read QA-WORKFLOW.md and rules/60 first.

Akinator runs on every change, with no command (rule 65). The plugin is optional: the in-repo skills/akinator/SKILL.md is the source. A new flagship or big feature ships its public marketing page in the same change (rule 66).

Read order for a task

1. npm run knowledge:context -- --task="<task>", then .ai/local/current-context.md.
2. rules/00-non-negotiable-rules.md.
3. The rules and skills the context file names; the touched workspace's own CLAUDE.md and generated AGENTS.md.
4. Work arriving as a document (prompt pack, plan, brief): rules/26 before any code.

Working in Claude Code

• Land through the hooks. git add <explicit paths> → git commit → git push. The hooks gate the change for its type (rules/23 gate matrix); do not pre-run the same gates by hand. Every commit carries a Docs: trailer (rules/63).
• A push whose pre-push runs for minutes can lose its connection and exit 141 after printing pre-push OK. Run npm run gates:receipt first: it proves the tree once and the push then skips those gates. Always check the push's real exit code and git log origin/<branch>..HEAD, never a summary.
• Background only long jobs, announce them in one line, and read their real exit code. Never edit files that a running hook or test run is reading.
• Subagents: foreground by default, each with a stated scope and explicit file ownership (rules/48 item 10). Small work: at most two at once. Large work: hire as many as there are independent parts, split big parts into sub-agents, one owner per shared file (locales, adr-index, package.json and lockfile, generated files), agents never run git, and the lead integrates, gates and commits in batches. Agents editing one tree without ownership contaminate each other's gates.
• Subagent models, every agent and tool (rules/64, skill): Haiku 5.5 for read-only work (audit, read, gain context); the main model (or sonnet/opus) for writing code and for Playwright, manual, API and automation QA, never Haiku there; gates climb Haiku 5.5 → Sonnet 5.5 → Sonnet 5.5 high effort → Opus 5.5 low/medium effort, only on a real failure; never Fable-class models or xhigh/max effort as subagents; unsure or confused: ask the owner (<Model X> at <effort> failed on <gate>: <error>. Try <Model Y> at <effort Z>?).
• Fresh worktree: npm ci, then npm run affected:shared-build and npm run prisma:generate --workspaces --if-present before trusting a gate. Never commit while a background agent writes in the same tree.
• Never --no-verify or any other hook bypass (ADR-061).