dot_files/dot_claude/rules/execution.md

Execution (applies to ALL agents)

Once a plan is approved (via ExitPlanMode or explicit user go-ahead), execute end-to-end. This file governs what happens AFTER planning — see planning.md for the interview/research/challenger flow that precedes it.

1. Default posture — run through, no mid-task gates

Keep working until the user's request is satisfied.

• Don't stop after research, after a single commit, after each "phase" or "batch" — keep going.
• No "Should I proceed with X?" / "Want me to continue?" prompts between steps of an approved plan.
• No mid-task checkpoints or batch approvals. The user interrupts if something drifts.
• Course-correct on user interruption, not by polling.

Stopping is the exception that needs a reason. The ONLY reasons to stop mid-execution are listed in §2.

2. When to stop and ask (the ONLY ASK FIRST list)

Pause and surface to the user (or, if you're a subagent, to the session that spawned you) for:

• Destructive ops — force-push, git reset --hard, rm -rf, dropping DB tables, killing processes the user didn't start
• Schema / public API changes — REST, GraphQL, gRPC, DB schema
• Deleting tested code — anything that has tests covering it
• Interface / contract changes that affect other teams
• Live network devices — routers, switches, firewalls (confirmed preference)
• Scope changes — work beyond the approved plan
• New genuine ambiguity discovered mid-execution that the research didn't resolve
• Configuration changes with external impact — credentials, DNS, firewall rules, production configs

Anything NOT on this list → just do it. Don't invent new reasons to pause.

3. Push / merge behaviour

On personal repositories (this monorepo and similar):

• Push after every commit — don't batch, don't wait for approval
• Direct to master — no feature branches, no PRs unless the user explicitly asks
• Wait for CI / deployment to complete before marking the task done — a green local build isn't the finish line if CI still runs
• git add specific files by name — never git add -A or git add ., which can sweep in secrets, worktree cruft, or untracked experiments
• Never skip hooks (--no-verify, --no-gpg-sign) unless the user explicitly requests it
• Never force-push to master — warn the user if they request it

Shared / corporate repos follow whatever PR flow the project uses; when in doubt, ask.

4. When to dispatch subagents

Default: do the work inline. The main session reads files, writes code, runs tests, commits. Every handoff costs clarity and context.

Spawn a subagent only when one of these is true:

• Parallel independent work — two or more genuinely independent investigations can run at the same time
• Context protection — raw output would be huge (wide codebase sweeps, long log dumps, 50+ files) and would pollute the main context; let a subagent digest and summarise
• User asked — the user explicitly requested an agent
• Long-running stand-alone task — something that runs for a while and doesn't need your attention (use run_in_background: true)

Dispatch table

Task pattern	Agent type	Background?
Write code / fix code / refactor	coder	foreground
Debug error / test failure	debugger	foreground
Review code / plan scrutiny	reviewer	background
Explore codebase / research	researcher	foreground
System design / architecture	architect	foreground
Run verification commands	verifier	foreground

Rules when you DO dispatch

1. Parallel when independent — 2+ independent subtasks = spawn agents in parallel in one message
2. Background for long-running — agents marked "background" in the table use run_in_background: true
3. Context protection — keep raw output inside the subagent; ask for a concise summary
4. Prompt quality — every agent prompt MUST:
   • Be 50+ words
   • Start with a clear task description (action verbs: implement, fix, add, refactor)
   • Include acceptance criteria (checkboxes or "Done when" conditions)
   • Include specific file/path references
5. Failed agent recovery — one retry with a refined prompt; second failure → escalate to the user with a summary

5. NEVER do these — no exceptions

• Create files without asking
• Use any / untyped types when a specific type exists
• Refactor adjacent code (only touch what's requested)
• Add lint-ignore or type-error suppression comments
• Edit generated / auto-generated files
• Write implementation before tests (see quality.md)
• Commit temp / one-off / test scripts to the repo — store them outside the repo instead

6. Before touching any directory

Check if it (or any parent up to repo root) contains project-specific rules (e.g., .claude/CLAUDE.md, .cursor/rules). If found, read those files first — they may override anything in this file.

7. Docs — keep infra/docs/ current

For any infra change that alters state described in infra/docs/architecture/ or infra/docs/runbooks/:

• Update affected docs in the same commit. Never land infra changes that leave docs stale.
• New architecture-visible component (new service, storage class, module, integration) → add or extend the relevant architecture/*.md doc.
• New operational procedure (restore flow, upgrade path, recovery step) → add a runbooks/*.md entry.
• Medium/large designed changes — write a plans/YYYY-MM-DD-<topic>-{design,plan}.md pair while designing, not after.
• Incidents → post-mortem in post-mortems/YYYY-MM-DD-<topic>.md.

If you can't tell which docs are affected, grep for the service or resource name across infra/docs/ — treat every match as a candidate for update. This rule is infra/-scoped; other repos may or may not have docs/ directories.

See also: infra/.claude/CLAUDE.md "Update docs with every change" for the full list of doc surfaces (includes .claude/CLAUDE.md, AGENTS.md, .claude/reference/service-catalog.md).

8. Wrapping up a session

Triggered by the user saying anything like "let's wrap up", "wrap up the session", "we're done", "end of session", or similar. When you hear this, run this checklist end-to-end (no mid-checklist gates):

1. Close beads tasks you touched this session.
   • Completed work → bd close <id>, or add Closes: <id> / Fixes: <id> trailer to the wrap-up commit (the post-commit hook auto-closes).
   • Partial work → drop back to open with bd note <id> "progress summary — where to pick up". Never leave in_progress tasks stale across sessions.
   • Check with bd list --status in_progress to confirm nothing of yours is still flagged.
2. Update docs per §7 — any infra/docs/ surfaces touched by the session's work. Don't land the wrap-up commit with stale docs.
3. Commit outstanding work. Stage specific files by name (§3). Write a commit message that explains the session's goal and result, not a file-by-file changelog.
4. Push to remote per §3 — direct to master for personal repos, PR flow for shared.
5. Wait for CI / deployment to finish before declaring done (§3).
6. Persist learnings to memory. For any non-obvious decisions, patterns, or gotchas discovered during the session, call mcp__claude_memory__memory_store with a concise summary. This is what future sessions will recall — skip the obvious, keep the surprising.

Stop only for items on §2's ASK-FIRST list.