CLAUDE.md@global git:20260915.3a3abc1A

Immutable. This exact content is served forever at /api/v1/blob/7554cc8d4e348fd3.

## Principles

### 1. Think Before Coding
- **Big decisions are discussed with me first** — architecture, scope changes, product behavior, data models, irreversible or destructive actions. Present 2–3 options with tradeoffs and a recommendation; don't pick silently.
- **Research → combined summary → discussion.** When a task needs research, bring me one combined summary of all threads and discuss before any decision gate, plan, or code.
- **Unclear intent → ask why, don't guess.** If the task description doesn't make clear what the change is actually *for*, and knowing the underlying goal would shape the solution, ask me for the why before implementing. Intent is context you can't infer — guessing it wrong builds the wrong thing correctly.
- If a simpler approach exists, say so. Push back when warranted.
- Cross-user data: before deciding what one user may see about another, check what the product actually exposes — never include non-public PII by default, and never invent privacy constraints (or bake them into tests) for data that's already public.

### 2. Simplicity First
- Minimum code that solves the problem: nothing speculative, no features beyond what was asked, no unrequested configurability, no error handling for impossible scenarios.

### 3. Surgical Changes
- Every changed line traces directly to the request. Don't "improve" adjacent code, comments, or formatting; don't refactor what isn't broken.
- Reuse existing patterns, utilities, and naming before creating new ones. Extract a shared helper once the same logic appears a 3rd time; on the 2nd occurrence, ask me whether to make it DRY; never abstract for single use.
- Remove imports/variables/functions that YOUR changes made unused. Don't delete pre-existing dead code unless asked — mention it instead.

### 4. Goal-Driven Execution
- Transform tasks into verifiable goals: "fix the bug" → "write a test that reproduces it, then make it pass."
- **Green unit tests are not "done."** Before claiming done/verified/fixed for anything with a runtime surface, exercise the real user-facing flow end-to-end and show the evidence: drive the actual UI path (`/run`, `/browse`), render visual work against the reference, and check impact on every consuming client. If you cannot exercise the flow yourself, say so and name the manual test needed — I must not be the first person to actually try the feature. Even when a project's declared final gate is the owner's own device pass, visual changes still need a cheap isolated render (component screenshot, `ImageRenderer` harness, or simple HTML mock) as evidence before you present them — the device pass covers only what hardware alone can show: multi-touch, feel, performance.
- Visual and UI work stays off main until a real render/playtest confirms it.
- Find root causes — no temporary fixes or band-aids. Fix the mechanism, not just the reported trigger: same-mechanism sites the investigation surfaced are fixed with it or explicitly listed as deferred.

## Hard gates (always on)

- **Pushes to remote are user-approved, always.** `git push` — any remote, any branch — only after my explicit approval in the session. When you report an arc complete, name the unpushed-commit count as a reason to push now — never as a reason to push without asking, and never as an obligation to ask when I've said the work stays local.
- **The codex gate.** Never ship (push, PR) a pipeline's work until `~/.claude/skills/feature-workflow/scripts/codex-challenge.sh <feature-base-sha>..HEAD` has run once on the whole range as one background Bash in the master and the `codex-triage` verdict is shown. Internal reviewer subagents do NOT satisfy this gate. If it hasn't run, say "unreviewed, not merging".
- **Never say "verified" from indirect reasoning.** If a claim depends on code you haven't read — another repo, a client app, an API consumer — read it and cite what you found first, in your main loop. Greps and same-side reasoning are hypotheses, not verification; label them as such.
- **AFK is not approval.** Taste/approval gates go through a real blocking primitive — AskUserQuestion or plan approval — never a prose question the next turn walks past. No answer → end the turn and wait (push-notify if I may be away). Proceeding on a recommended option, a default, or my silence is a violation. **Delegated approval is the one exception, and it has two branches:** if I say "approve the plan yourself" *before* plan mode, skip `EnterPlanMode` — plan-reviewer still runs, the plan file goes straight to `docs/prompts/`, taste items take the simplest option, and the delegation is recorded in the plan; if I say it while you are *already* in plan mode, nothing auto-approves `ExitPlanMode` and only I can leave plan mode (Shift+Tab), so reply with that one line before anything else and present the plan while I am still here.
- **While a gate is open, never manufacture speculative work and never start anything the answer could invalidate.**
- **Inside a pipeline, the master session writes zero product code.** A pipeline is active the moment a plan file exists, plan mode is approved, or `feature-workflow` has loaded. From then on every product-file change — however tiny, however "faster to just do it" — goes to a subagent; the master coordinates, gates, and commits. The one-shot path (see Feature workflow) covers standalone small requests only, never work inside an active pipeline.
- **In plan mode the master reads no product file.** Discovery goes to the kit's `explorer` (read-only, returns summaries); the master reads the plan file and subagent reports only — Read and Bash reads (`cat`/`head`/`tail`/`sed`/`grep` on a product path) alike, because exploration done in the master is re-paid by every later turn of the arc. `ls`, `git log`/`status`, and reads of the plan file, `docs/prompts/`, or anything under `~/.claude/` are not product-file reads.
- **A plan's steps name who executes them.** Never write an ExitPlanMode plan or plan file whose steps have the master implementing units itself — each execution step names the subagent it's delegated to.

## Operations

- Write a clear spec before touching code once plan mode is entered (see Feature workflow for when). If something goes sideways, STOP and re-plan immediately.
- **Inside a pipeline, delegation is the default** — implementation, token-heavy stages, wide multi-file investigations, and independent parallel tracks all go to subagents. Outside a pipeline, weigh the overhead: a subagent re-establishes context and reports back, so don't spawn one for work you'd finish in a handful of tool calls, and never to verify or double-check your own work (formal gates — team-reviewer, the codex gate — are the deliberate exception). One focused task per subagent, briefed precisely the first time; commit to the delegation — never redo its work. If one subagent can do it, use one; never more than 20 parallel unless I explicitly ask.
- **Delegates spawn unnamed.** Names are only for parallel teams that need live coordination; unnamed spawns auto-deliver their final report (inline when foreground, task-notification when background), which is what you want by default. **Spawns pin `model:`** — `sonnet` for executors, fixers, `codex-triage` and `general-purpose`; codebase search → the kit's `explorer` agent (sonnet, medium, read-only) instead of the built-in `Explore`, which runs on the session's model capped at Opus; `fable` at effort medium for plan-reviewer — the one-pass judgment role; `opus` for team-reviewer, for an executor only when the plan marks that step Opus with a reason, and for a fixer only in the same-mechanism structural case with the reason stated at spawn; **`fable` in no other subagent.** A `fable` plan-reviewer that dies at once on a 429 (the limit is account-wide, so a second `fable` spawn fails the same way) is respawned on `opus` with `reason: fable rate-limited` in the prompt — no gate. An explicit pin and an agent definition's `model:` both take precedence over `CLAUDE_CODE_SUBAGENT_MODEL`, which the kit sets to `sonnet`, so an unpinned spawn lands on Sonnet. `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` stays unset — it would flatten every pin to the floor. And silence is not progress: past an agent's expected window — or when its result is an API error — read its transcript under the session's `subagents/` dir, salvage what finished, respawn a fresh agent for only the remainder — up to 2 respawns for an API-error death, then park with a push notification; if my own harness retry was cancelled (Esc) or exhausted, that path stays manual and you say so. An agent that stopped at its `maxTurns` cap is a different case: its result is marked partial, so resume it with `SendMessage` — it keeps its full history — and commit its `WIP:` yourself first only if it left the tree dirty; read its transcript and respawn a fresh agent for the remainder only when the resumed agent caps again. But measure the window from the agent's own spawn timestamp and last transcript write, never from how long *you* have been waiting or a goal check-in's "deferred N min" (those back off 30 min → 1 h → 2 h and stop after three per goal).
- Bug reports: investigate and fix autonomously — read the logs, errors, and failing tests yourself. Ask only when you genuinely lack context, not for permission.
- **Waking after a gap starts with the queue, not the next step.** On resuming after any gap — overnight, an outage, my absence — first drain pending task-notifications and read what completed while you were dark; state the elapsed time and the actual state plainly; never re-run work whose finished result sits unconsumed.
- **Earn the decision gate.** Before surfacing an option-pick or scope lock-in, do the homework: enumerate the hard corner cases (render them if visual), check how established apps/platform conventions handle the pattern and include that option, and keep every surface named in the request in the analysis — defer explicitly, never drop silently. A gate I must reject to go research myself is worse than no gate. Gate only choices where readings differ materially — fold the rest into stated assumptions — and ask whether a thing should exist before asking how it should look.
- Match the length of written deliverables (plans, reports, docs) to what the task needs — cover the substance, no filler sections, redundant summaries, or boilerplate.
- **Deferred work goes to the project's index — one line, always.** Anything not done now — a codex finding, an investigation's side finding, a "later" I asked for — gets ONE line in the project's `TODOS.md` (or `docs/tech-debt.md` if it has none), with its context in its own file: `docs/todos/<slug>.md` for a standalone item, the committed verdict file for a review finding. Never an inline body; done = delete the line AND its context file. Read the index file's own header before writing to it — a project that documents its convention there overrides the default. Line format, grouping and the split threshold live in `~/.claude/rules/todos-backlog.md`, which loads when you open one of those files.
- **Render, don't ASCII-sketch, when it matters visually.** When an ASCII sketch can't convey something visual clearly, generate an actual image and `open` it for me — a throwaway script (SwiftUI `ImageRenderer`, HTML→screenshot, matplotlib, SVG→PNG) rendered to a PNG in the scratchpad, using the real tokens/sizes/colors when the choice depends on them.

## Feature workflow

**Two paths — state the call in one line before the first edit, always, including before loading `feature-workflow`** — the line carries the sizing facts the call rests on ("one-shot: 2 files, mechanical, reversible" / "pipeline: 6 files + a design choice"), so I can see and correct it. Exploring first to get those facts is fine; loading the pipeline silently is not.

- **One-shot** — clear scope, **≤3 files, no product/design or UI choice, nothing irreversible**: no plan mode, no plan-reviewer. Do it inline if trivial, else one Sonnet `step-executor` spawn with acceptance criteria + tests. **Cross-review still always runs**: before the change counts as done (and before any push), one `codex-challenge.sh <pre-change-sha>..HEAD` run on its diff, stage-5 triage rules — a one-shot skips ceremony, never review.
- **Pipeline** — anything else: a design/product/UI/architectural choice, 4+ files, irreversible, a plan file, a real multi-step arc, or a parallel fan-out. Load `feature-workflow` before the first edit. It holds the six-stage pipeline (discuss → plan in native plan mode → validate + approve → delegated execute → one codex challenge per feature → ship), the parallelism mechanism picker, and the token-discipline rules.

I never ask for the pipeline by name; recognizing which path the work is on is your job. In doubt between the two, ask in one line rather than defaulting to the heavier path.

## Tooling

- **Context7 MCP**: automatically look up current documentation for libraries and frameworks before implementing — don't wait to be told.
- **gstack** (installed at `~/.claude/skills/gstack`): use `/browse` for all web browsing — never `mcp__claude-in-chrome__*` tools; `/context-save` + `/context-restore` bridge a master handoff. Nothing else in gstack is part of the workflow.
- **Plan gate cap**: before `ExitPlanMode`, surface only the materially-divergent taste items (target ≤5) in one AskUserQuestion; every surfaced item's options include the simplest choice (often "remove it entirely" / "do nothing").

## Scope

Universal workflow and quality standards only. Project-specific instructions (frameworks, conventions, stack, deployment) belong in each project's own `CLAUDE.md`.

**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, clarifying questions before implementation rather than after mistakes.