docs(adr): add 0008-agent-instructions-in-claude-md + update README index

docs/adr/0008-agent-instructions-in-claude-md.md

@@ -0,0 +1,41 @@
+---
+title: "ADR-0008: Agent instructions in CLAUDE.md + topical runbooks"
+status: accepted
+date: 2026-05-03
+---
+
+# ADR-0008: Agent instructions in CLAUDE.md + topical runbooks
+
+## Status
+
+Accepted
+
+## Context
+
+Claude Code reads `CLAUDE.md` at session start and injects it verbatim into the system prompt. As the project grew, the file expanded to ~350 lines covering stack, patterns, MCP tools, commit strategy, branch policy, Vercel deployment, and demo-user rules. At that length the token cost was significant and the file was hard to navigate — both for humans and for AI agents skimming for a specific rule.
+
+A separate `docs/agent-instruction-audit.md` tracked *why* each rule existed, but that meta-history was buried and rarely consulted. The result: rules were added but never removed, and the file drifted toward being a reference dump rather than a decision-forcing instrument.
+
+## Decision
+
+Split `CLAUDE.md` into a short ≤150-line orientation hub that hard-links to topical runbooks:
+
+- `docs/runbooks/branch-and-commit.md` — branch policy, plan mode, commit strategy
+- `docs/runbooks/mcp-integration.md` — all 18 MCP tools + batch-loop invariants
+- `docs/runbooks/deploy-vercel.md` — Sharp, cron, env-var, preflight rules
+
+`CLAUDE.md` retains only the rules an agent **must** have in active context on every turn: the orientation table, the 8 hardstop rules, stack table, patterns quickref, and env vars. Everything else is a hyperlink.
+
+`AGENTS.md` (Codex entry-point) becomes a 10-line redirect stub pointing at `CLAUDE.md`.
+
+## Consequences
+
+**Positive**
+- Active-context token cost drops ~60 % — the hub is ~114 lines vs 350.
+- Each runbook is standalone and audience-tagged (`audience: [ai-agent]` etc.), so a future agent can fetch exactly the doc it needs.
+- The split gives a natural place to add rules without polluting the root file.
+- `docs/decisions/agent-instructions-history.md` (renamed from `agent-instruction-audit.md`) documents the *why* behind each rule as persistent institutional memory.
+
+**Negative**
+- An agent that reads only `CLAUDE.md` will miss branch/MCP/deploy rules unless it follows the links. Mitigation: critical one-liners (e.g., "PR only after user test") are kept as hardstops in the hub.
+- The split increases the number of files to maintain; runbooks can drift from `CLAUDE.md` if authors forget to update both. Mitigation: docs-sync convention in `CLAUDE.md` Conventions section.

docs/adr/README.md

@@ -86,6 +86,14 @@ typo fixes. Course corrections always create a new ADR.
 | # | Title | Status | Template |
 |---|---|---|---|
 | [0000](./0000-record-architecture-decisions.md) | Record architecture decisions | accepted | Nygard |
+| [0001](./0001-base-ui-over-radix.md) | @base-ui/react over Radix UI | accepted | Nygard |
+| [0002](./0002-float-sort-order.md) | Float sort_order for drag-and-drop reorder | accepted | Nygard |
+| [0003](./0003-one-branch-per-milestone.md) | One branch per milestone (Hobby plan) | accepted | MADR |
+| [0004](./0004-status-enum-mapping.md) | Status enum mapping via lib/task-status.ts | accepted | Nygard |
+| [0005](./0005-iron-session-over-nextauth.md) | iron-session over NextAuth/Clerk | accepted | MADR |
+| [0006](./0006-demo-user-three-layer-policy.md) | Demo-user three-layer write guard | accepted | Nygard |
+| [0007](./0007-claude-question-channel-design.md) | Agent ↔ user question channel via persistent table + LISTEN/NOTIFY | accepted | MADR |
+| [0008](./0008-agent-instructions-in-claude-md.md) | Agent instructions in CLAUDE.md + topical runbooks | accepted | Nygard |
 
 When new ADRs are added, the docs index generator (`npm run docs:index`)
 will list them in [`../INDEX.md`](../INDEX.md). Update this table by hand