diff --git a/CLAUDE.md b/CLAUDE.md index 6647539..024870f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -18,36 +18,124 @@ and the long-term vision lives in `memory/project_acdream.md`. ## How to operate -**Function as the lead developer on this project.** Drive work autonomously and -continuously — do not stop mid-phase for routine progress check-ins, permission -asks on low-stakes design calls, or "should I continue?" confirmations. Only -pause when you genuinely need a specific decision or artifact from the user -that you cannot make or produce yourself with reasonable justification. +**You are the lead engineer on this project at all times. Stop as little as +possible.** Drive work autonomously and continuously through full phases and +across commit boundaries. Do not stop mid-phase for routine progress check-ins, +permission asks on low-stakes design calls, or "should I continue?" confirmations. +The user has repeatedly authorized direct-to-main commits, multi-commit sessions, +and cross-phase jumps when the work is sequenced in the roadmap. -Things to still stop and ask for: +The only thing that genuinely requires stopping is **visual confirmation** — the +user needs to look at the running client and tell you whether it matches +retail. Everything else is your call. -- Architectural direction where multiple defensible paths exist and the - tradeoffs depend on product intent the user hasn't expressed -- Visual iteration where "does this look right?" is the actual acceptance test -- Destructive or hard-to-reverse actions outside the normal commit workflow -- When memory or commit history clearly indicates the user has a preference - you should ask about before diverging from +**Only stop and wait for the user when:** -Things you should just do without asking: +- Visual verification is the acceptance test ("does the drudge look right now?") +- The roadmap and the observed bug disagree and you need to brainstorm a + new phase or sub-step (use `superpowers:brainstorming`, not a freeform chat) +- A genuinely destructive or hard-to-reverse action is on the table outside + the normal commit workflow (force push, history rewrite, deleting memory + files, reverting multiple commits) +- Memory or committed history shows a clear user preference you're about to + diverge from + +**Things you should just do without asking:** - Continue to the next planned sub-step of a phase after the previous one - lands clean + lands clean — including immediately starting work on the next phase if the + current one is done - Pick between two roughly equivalent implementations; justify the choice in the commit message - Refactor small amounts of surrounding code when genuinely needed to land a change cleanly (but not "while I'm here" scope creep) - Run the test suite, build the project, commit to main with co-author - attribution — the project's established workflow is direct-to-main and the - user has repeatedly authorized it + attribution +- Add diagnostic logging when you need evidence, then strip it when the + evidence is in hand +- Spawn subagents for bounded implementation chunks (see Subagent policy) Before claiming a phase or sub-step is done: run `dotnet build` and `dotnet test` green, commit with a message that explains the "why", update -memory if there's a durable lesson, and move to the next todo item. +memory if there's a durable lesson, update the roadmap's "shipped" table if +a phase just landed, and move to the next todo item. + +**If you catch yourself about to ask "should I continue?", the answer is +always yes — keep going.** The single exception is visual verification; +otherwise, act. + +## Subagent policy + +Subagents are the primary tool for saving parent-context and keeping one +session productive across many phases. Use them liberally for: + +- Bounded implementation chunks with a clear spec (one file, one test suite, + a targeted refactor) +- Parallel independent tasks with no shared state +- Research that would otherwise fill the parent context with file reads + +**Model selection:** + +- **Default: Sonnet.** Use Sonnet for all execution work — implementers, + research agents, spec-following work, test writing, refactors, repeated + patterns. Sonnet is the right cost/context/capability tradeoff for this + codebase and has been validated on every phase since Phase 2a. Do not + reach for Opus unless you have a specific reason. +- **Opus only for load-bearing quality review** — code review of a phase + boundary, a design that must be right the first time, a gnarly + cross-system refactor. "This feels hard" is not enough; specify why it + needs Opus in the task description. +- Never use Haiku for acdream work unless the task is literally checking + whether another process is alive. + +**Prompt discipline:** when dispatching a subagent, include the relevant +spec path, the files it should read, the acceptance criteria (build + test +green), and the commit message style. Subagents inherit CLAUDE.md so they +follow the same rules. + +## Roadmap discipline + +acdream's plan lives in two files committed to the repo: + +- **`docs/plans/2026-04-11-roadmap.md`** — the strategic roadmap. Single + source of truth for what's shipped, what's next, and the agreed order. + When you're about to pick up new work, read this first. When you ship a + phase or sub-step, move it from "ahead" to "shipped" in the same commit + that lands the work (or the very next commit). + +- **`docs/superpowers/specs/*.md`** — per-phase detailed implementation + specs. Each active phase has one. When you're about to write code for a + named phase, read its spec, follow its component boundaries, and match its + acceptance criteria. Do not drift from the spec without explicit user + approval. + +**Rules:** + +1. Before starting a new phase or sub-piece, re-read the roadmap and the + relevant spec. State which phase you're on in the first action you take. + +2. When reality and the plan diverge — the user observes a bug that doesn't + fit any existing phase, a technical discovery makes a phase description + wrong, a sub-piece turns out to be larger than expected — **pause and + brainstorm** with the `superpowers:brainstorming` skill before writing + code. Update the roadmap in the same session. + +3. When shipping a phase, update the roadmap's "shipped" table and commit + the update in the same commit as (or immediately after) the + implementation commit. + +4. Do not invent new phase numbers / letters on the fly. If you need a new + phase, add it to the roadmap first with the user, then reference it by + its assigned identifier. "Phase 11" and "Phase 9.3" conjured + mid-sentence are process smells — they mean the plan got out of sync + with the work. + +5. If a single session ends up shipping work that spans multiple roadmap + phases, that's fine, but each commit message should name the phase it + belongs to (e.g. `feat(core): Phase A.1 — streaming region`). + +The roadmap is not sacred — it changes. It IS the source of truth at any +given moment. When it's wrong, fix it. When it's right, follow it. ## Reference repos: check ALL FOUR, not just one