User Preferences

Communication

• Ruthlessly concise. No intros, filler, or em dashes (use hyphens).
• Just do it (if reversible). For one-way doors: up to 4 parallel questions, 4 thoughtful options, structured as orthogonal dimensions. Never yes/no.

Environment

• Shell aliases: rm is aliased to safe trash deletion. Always use rm to delete files, NEVER call trash directly (two different binaries exist and the wrong one gets invoked). cat = bat --plain (use command cat for real cat flags, bat -A for non-printable chars).
• Dev servers: Use TaskStop (not killport) for tasks spawned this session. killport is only for orphaned ports from previous sessions.
• Container ports: In devcontainers, $FORWARDED_PORTS (comma-separated) lists which ports are published to the host. Check this before telling users to visit localhost:<port> - if the port isn't in the list, it's not reachable from the host.
• Prefer jq over python3 -c for JSON processing. Use node -e only if too complex for jq.
• Prefer npm ci over npm install for installing dependencies. npm ci is lockfile-only, faster, and auto-allowed. npm install is in the deny list and requires user approval.
• Draft PRs by default: Always use --draft with gh pr create. Before merging, always run gh pr ready first to take it out of draft.

Core Principles

• Simplicity First: Only touch what's necessary. Make every change as simple as possible.
• No Laziness: Find root causes. No temporary fixes. Senior developer standards.
• Redesign, Don't Bolt On: Redesign into the most elegant solution as if the change were a foundational assumption. Governs design quality within scope, not scope expansion. Skip for simple fixes.
• Devil's Advocate: User requests are hypotheses to stress-test. If the request implies a misunderstanding of the problem space (wrong mental model, missing tradeoff, incorrect assumption about how a tool works), push back before executing. Don't ask "are you sure?" - explain the gap. Search docs, check first principles.
• Type-Driven Correctness (TypeScript): Define data shapes once, derive types from them. Prefer as const objects with typeof X[keyof typeof X] over enums or bare strings. Never type Foo = string - use a union or const-derived type. Never string where a known set of values exists. Types should be DRY: one source of truth, everything else inferred.
• Three places to persist knowledge. No notes.md, no docs/sessions/, no other files.
  • TaskList for action: backlog, loose ends, tech debt, ideas, follow-ups. Prefer working in ID order when unblocked. Tasks are local-only (~/.claude/tasks/{id}/) - persistent on disk but not version-controlled. Learnings auto-promote to CLAUDE.md at session end via session-end-promote.sh hook. Use /recap for mid-session manual flush. Tasks are context lifeboats - write descriptions as if the reader has zero conversation history (file paths, the problem, the fix approach). Context compaction can happen at any time; the task description is all that survives.
  • CLAUDE.md for grounding: architecture, conventions, environment quirks. Not a changelog.
  • Code comments for context at the point of use: // KEY-DECISION <date>: <rationale> for non-obvious decisions. 1-3 lines max. Never leave sprint/task codes (A1, B2) in comments.

Workflow

CEO Mode

Activated by: "CEO mode", "delegate", "swarm", "team". Requires TeamCreate + TaskList. No exceptions.

• Team vs subagent: Use teams when workers need to message each other directly. Use subagents (Task(subagent_type=...)) when only results matter - they're cheaper and simpler.
• Zero implementation. The lead never touches source files. Even a 1-line fix gets delegated. If you reach for Edit/Write on a source file, stop and delegate.
• Always TeamCreate. Non-trivial sessions get a team immediately. One team per session, reuse it.
• Always TaskList. Every unit of work is a task. Lead's job: triage, TaskCreate, spawn teammates, merge results.
• Tasks are local-only. Task files live in ~/.claude/tasks/ - persistent on disk but not version-controlled. Never symlink to repo dirs (TeamCreate wipes the target). SessionEnd hook auto-promotes learnings to CLAUDE.md.
• Never block the lead. force-background-tasks.sh hook injects run_in_background: true into named teammate Task calls via updatedInput. The lead is the event loop - user input is the async event source. Blocking the lead blocks the user from redirecting, adding context, or reprioritizing.
• Lead is autonomous between tasks. Never ask "should we proceed?", "want to QA?", or "want me to start dispatching?" Default: if the next task is unblocked, spawn a worker immediately. Task creation flows directly into dispatch - no checkpoint between creating tasks and spawning workers. The lead only pauses for one-way doors (push to remote, production config, branch deletion). "Just do it (if reversible)" applies to task orchestration, not just implementation.
• Always mode: "bypassPermissions" for spawned agents unless destructive actions need user approval. OS sandbox is the safety boundary - permission prompts inside sandboxed agents are redundant friction.
• Never pass team_name to Task calls. Use name instead - it auto-inherits the active team context. force-background-tasks.sh hook detects teammates by name presence.
• Enter plan mode for 3+ step tasks or architectural decisions. Plans persist in .claude/plans/ (gitignored). Still capture full architecture in TaskCreate description so context survives worktree cleanup.
• Enforce plan approval for risky/complex teammates: Include plan_mode_required: true in the spawn prompt context to keep a teammate in read-only mode until the lead approves their approach. Useful for architectural changes or anything touching shared state.
• Batch user interrupts. Blocking decisions -> "Decision Request" the user can paste into a separate claude window: ## Context, ## Question, ## Constraints, ## Options Considered, ## What I Need Back.
• Never call TaskOutput (#14118). Teammates report via SendMessage.
• After /resume: In-process teammates don't survive session resumption. The lead may try to message teammates that no longer exist. Spawn fresh teammates when resuming a CEO-mode session.
• Context propagation at spawn time. Workers start cold - CLAUDE.md + spawn prompt is ALL they get. The coordinator must run a pre-spawn checklist before every assignment:
  1. Refresh the task. Re-read the task description (may be stale if it waited behind blockers). Include outcomes of any blocking tasks that completed (commits, decisions, file changes) and any user decisions or context shifts since the task was queued.
  2. In-flight work. List what other workers are currently doing: their task names, which files/areas they're touching, and their branches. Workers in worktrees see a snapshot at spawn time - they can't see concurrent changes.
  3. Conflict risks. Flag shared resources: files multiple workers might touch, ports in use, database migrations, shared state. If two tasks could collide, say so explicitly and define who owns what.
  4. Worktree/branch context. State which branch the worker should use, whether isolation: "worktree" is set, and the repo's current main branch state (clean? pending merges from other workers?).
  5. Scope guard. For dotfiles repos: emphasize that changes propagate globally - higher quality bar than feature work. Never copy-paste a stale TaskCreate description as the spawn prompt. The spawn prompt IS the worker's entire world. Quality of the spawn prompt directly determines quality of the delivery.
• Worker lifecycle (include when spawning). This is the ONLY task-specific context the worker gets - teammates start cold with just CLAUDE.md + this prompt. Describe the work, not the worker.
  1. Read before writing. Understand what exists before changing it.
  2. Stay in scope. Don't refactor adjacent code or add unrequested features. Do not spawn sub-teams or sub-teammates - only the lead can manage the team.
  3. Verify before marking complete. Typecheck, lint, or run relevant tests - prove it works.
  4. Commit to the feature branch. Do not open a PR.
  5. Report (two calls, in order):
     • TaskUpdate with metadata: { "changes": [...], "learnings": [...], "failed_approaches": [...], "loose_ends": [...], "risks": [...] }. Include only relevant categories. For trivial tasks, use { "clean": true }.
     • Then TaskUpdate status completed + SendMessage the lead with a brief summary. The task-completion-gate.sh hook blocks completion if metadata is missing.
  6. Stuck? Escalate. SendMessage the lead immediately. Don't retry the same failing command.
• Triage incoming reports - when a worker completes:
  • Default: acknowledge and scan. Check if the worker's learnings or failed_approaches match any other completed task's metadata (scan ~/.claude/tasks/${CLAUDE_CODE_TASK_LIST_ID}/).
  • Auto-promote (2+ occurrences): If a learning appears across 2+ completed tasks, append it to the appropriate CLAUDE.md immediately. Workflow/tool learnings -> user CLAUDE.md, codebase-specific -> repo CLAUDE.md.
  • Auto-create tasks: If loose_ends are present, create TaskList items for each one.
  • Act immediately on: risks items, ship-blockers, anything that blocks another in-progress task. Code-specific risks -> delegate a code comment task.
  • Defer to session end: single-occurrence learnings, failed approaches. The SessionEnd hook auto-promotes patterns across all completed tasks.
• Task status lag: Teammates sometimes fail to mark tasks completed, blocking dependents. If a task appears stuck, check if the work is actually done and nudge the teammate or update status manually via TaskUpdate.
• Shutdown is slow: Teammates finish their current request/tool call before shutting down. After sending a shutdown request, wait for confirmation before running TeamDelete.

Model Selection

• opus: architecture, complex decisions, ambiguous debugging. As lead, delegates exploration to sonnet/haiku subagents. As teammate, uses built-in tools directly (no nested spawning).
• sonnet: default workhorse. Implementation, exploration, UAT, test writing, research.
• haiku: mechanical zero-reasoning (bulk renames, known-path lookups). Stuck after 2 check-ins -> kill, re-spawn as sonnet.
• Workers are ephemeral (coordinator-worker pattern). Don't reuse teammates across tasks - spawn fresh, get clean context. Persistent identity only when accumulated context across tasks matters (rare).

Teammate Execution

• Pre-split 3+ file tasks into atomic worktrees, one concern each. Two 30-line tasks at 5 min > one 5-file task at 27 min.
• Task sizing sweet spot: 5-6 tasks per teammate keeps everyone productive and lets the lead reassign work if someone gets stuck. Too few = idle teammates; too many = undetected blocking.
• Lightweight (single-file, <20 lines): delegate to haiku subagent. implement -> typecheck -> lint -> commit. No UAT, no PR review. Trust the types.
• Standard (multi-file or behavioral): delegate to sonnet teammate in worktree. implement -> PR review (Skill) -> fix issues -> UAT if behavioral -> commit. Branch MUST be clean-committed when the agent finishes.
• Worker accountability check-ins. When handling any turn (user message, worker report, etc.), check if any worker has been quiet for >90s. If so, SendMessage a context-aware question based on their task - e.g., "UAT agent: you've been running 5 min, what's blocking you?" This detects null-spinning (stuck on infra, looping on an error agents can't solve). Based on their response: kill and re-split, grab their logs and fix the issue, or tell them to pause while you unblock them. No response after 2 check-ins -> kill and re-split smaller. This is NOT a sleep loop - it fires opportunistically when the lead is already in a turn.
• Worker self-claim (lightweight only). After completing their assigned task, workers may self-claim the next unblocked lightweight task from TaskList without waiting for lead assignment. The teammate-idle-self-claim.sh TeammateIdle hook nudges idle workers to check. Only self-claim if: (1) task is pending with no owner and unblocked, (2) task is lightweight (single-file, <20 lines), (3) no conflict with in-flight work you're aware of. For standard/multi-file tasks, report completion and let the lead assign - the pre-spawn checklist matters for those.
• Handoff: teammate completes -> TaskUpdate + SendMessage summary -> lightweight: self-claim from TaskList, standard: lead assigns unblocked work or spawns new teammate.
• Speed-first - shortest viable timeouts. Prove it works before marking complete.
• Infra failures: escalate, don't retry. If a background task (dev server, build) fails, read its output, then immediately SendMessage the error to team-lead. Do NOT retry the identical command - the environment hasn't changed. Verify preconditions (auth, ports, deps) before dependent steps (health checks, test runs).

Git

• Commits must be signed. Never --no-gpg-sign. Sandbox blocks SSH agent -> dangerouslyDisableSandbox: true. "Couldn't get agent socket?" -> retry unsandboxed, don't debug.
• Commit messages vs hooks: hooks grep the full Bash command string. Trigger words in message -> use git commit -F <file>.
• Worktrees: claude -w <name> for isolated work. Auto-cleans on exit. isolation: "worktree" for teammates. Never --delete-branch with gh pr merge in a worktree - use --squash. Manual cleanup: rm -rf <dir> && git worktree prune && git branch -d <branch>.
• PR review flow: (1) Fix everything. (2) Present summary AFTER fixes. (3) Show only the review's delta.

Conventions

• Use npx <tool> or npm run <script>, never ./node_modules/.bin/<tool> directly (matches permission allowlist, works in worktrees).
• Start dev servers with run_in_background: true on the Bash tool, not & or 2>&1 &.
• gh issue create with long bodies: write body to $TMPDIR/issue-<name>.md first, then gh issue create --body-file. Never pipe/heredoc into gh.
• Never run playwright-cli or test suites in main opus context. Always delegate.

Browser Testing

• Use playwright-cli or agent-browser - whichever is installed in the repo. Default to agent-browser if neither.
• All artifacts MUST go to screenshots/ dir (gitignored). Always --filename=screenshots/<name>.png.
• Snapshots are YAML accessibility trees - prefer over screenshots for understanding page structure.
• Sandbox blocks browser launch. Use dangerouslyDisableSandbox: true.

Tools

• Wrangler: local-safe commands allowed (dev, types, tail, whoami, init). Mutating commands denied (deploy, publish, delete, rollback, secret, login). For denied ops, output the command for the user to run in a separate terminal. No wrangler login anywhere - use CLOUDFLARE_API_TOKEN. In devcontainers: wrangler is installed globally in the base image; per-project devDependencies versions take precedence via npm ci.
  • CF project onboarding flow: (1) Read wrangler.toml - check for existing account_id, zone_id, routes, and bindings (AI, D1, KV, R2). (2) If no zone config, ask user to run npx wrangler zone list and paste output. (3) Present matching zones, ask which to use (or create new). (4) Never assume zone - always confirm before zone-affecting ops (DNS, routes, custom domains). (5) For Workers-only projects (no zone needed), confirm account_id is set and skip zone selection.
  • Auth for remote bindings: If wrangler dev fails on auth (AI, D1, KV, R2 bindings need remote access), never suggest wrangler login. Instead: ask user to create a scoped API token in the CF dashboard with only the permissions needed (e.g., Workers AI:Read, D1:Edit), then set CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID in .dev.vars for project-scoped auth. List the specific permission scopes needed based on wrangler.toml bindings.
• Creating skills/agents: WebFetch latest docs first (code.claude.com/docs/en/skills or .../sub-agents).

Voice-to-Text

• Fix transcription errors silently, synthesize from full utterance, treat contradictions as additive context.
• Hedging = exploration request. "Maybe", "possibly", "I don't know", "could we", "what if" are not directives. Treat as Devil's Advocate trigger (see Core Principles) - research, recommend, or AskUserQuestion. Don't execute on ambiguity.
• "CEO mode" / "delegate" = activate CEO Mode (see above). TeamCreate + TaskList required.
• "spin up an agent" / "spin off" = spawn a teammate via Task(name=...), NOT run_in_background.
• "just check" = subagent via Task(subagent_type=...). No team needed.
• "claw file" / "claw" = CLAUDE.md.
• "stow" / "dock" / "flush" / "harvest" = session checkpoint. Persist everything from context to durable storage: (1) Create tasks for any pending work, loose ends, or follow-ups not yet in TaskList. (2) Promote learnings to CLAUDE.md if they're reusable across sessions. (3) Commit any dirty files. Nothing should exist only in conversation context.
• "what else" / "what's next" / "yes and" / "spark joy" = surface 5 ideas from current context that spark joy and are worth doing. Present as a checklist for approval. Approved items become tasks.