From 7bbe2035786496fc10a5d870efdb648c61a438df Mon Sep 17 00:00:00 2001 From: Viktor Barzin Date: Sun, 19 Apr 2026 12:58:39 +0000 Subject: [PATCH] Add ~/.claude/rules/ workflow files to chezmoi MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit planning.md, execution.md, quality.md — the agent workflow rules loaded into every session via ~/.claude/rules/. Previously untracked locally. planning.md now includes an "For infra changes" subsection directing researchers to infra/docs/architecture/ and infra/docs/runbooks/ before dispatching researcher subagents. execution.md now includes §7 "Docs — keep infra/docs/ current" covering doc upkeep for architecture-visible changes and new operational procedures. Co-Authored-By: Claude Opus 4.7 (1M context) --- dot_claude/rules/execution.md | 117 ++++++++++++++++++++++++++++ dot_claude/rules/planning.md | 141 ++++++++++++++++++++++++++++++++++ dot_claude/rules/quality.md | 72 +++++++++++++++++ 3 files changed, 330 insertions(+) create mode 100644 dot_claude/rules/execution.md create mode 100644 dot_claude/rules/planning.md create mode 100644 dot_claude/rules/quality.md diff --git a/dot_claude/rules/execution.md b/dot_claude/rules/execution.md new file mode 100644 index 0000000..f458606 --- /dev/null +++ b/dot_claude/rules/execution.md @@ -0,0 +1,117 @@ +# 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--{design,plan}.md` pair while designing, + not after. +- **Incidents** → post-mortem in + `post-mortems/YYYY-MM-DD-.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`). diff --git a/dot_claude/rules/planning.md b/dot_claude/rules/planning.md new file mode 100644 index 0000000..5ccbd9e --- /dev/null +++ b/dot_claude/rules/planning.md @@ -0,0 +1,141 @@ +# Planning (applies to ALL agents) + +**No implementation without completed research.** This flow MUST run before implementation begins. + +The approval gate at the end of planning is **ExitPlanMode** — there is no second user-gate step once the plan is accepted. See `execution.md` for what happens after approval. + +## Phase 1: Interview the User + +**Interview relentlessly. Make sure that all ambiguities are resolved before execution.** + +Before dispatching any researcher, ask targeted questions: + +- **What exactly should change?** — not "add feature X" but the specific behavior expected +- **What are the constraints?** — backward compatibility, performance requirements, scope limits +- **What should NOT change?** — explicit out-of-scope items +- **Who are the consumers?** — who calls this code, who depends on it, who will be affected +- **What edge cases worry you?** — empty input, timeouts, stale data, concurrent access + +**Gates — do NOT proceed to Phase 2 until ALL of these are true:** +- [ ] Every question has been answered by the user (not assumed) +- [ ] If any answer raised new questions, those were asked and answered too +- [ ] Zero ambiguity remains — you can describe the exact change without "probably", "maybe", "might" +- [ ] The user has not said "I'm not sure" about any critical decision — if they did, resolve it + +**Longer planning = fewer fixes later.** + +## Phase 2: Code Exploration + +Dispatch `researcher` subagents: + +### Mandatory investigations + +| Investigation | How | Blocker if skipped | +|---|---|---| +| **All callers + blast radius** | Claude Code `Grep` tool for references, IDE "find all references" | Cannot assess risk of change | +| **Existing patterns + reusable code** | Search for similar implementations before creating new | May duplicate existing utility | +| **Edge cases + failure modes** | Trace error handling paths, check null/empty/stale input | Bugs ship to production | +| **Current data state** | Query real data to understand current behavior with numbers | Assumptions may be wrong | + +### For 2-3 parallel researchers + +| Researcher | Focus | +|---|---| +| R1: Existing code + patterns | Trace the code path being modified. Find all callers. Identify existing abstractions to reuse. | +| R2: Blast radius + dependencies | Who depends on this? Cross-team callers? What breaks if we change the interface? | +| R3: Data + edge cases | Query real data to validate assumptions. Identify failure modes. | + +### For infra changes + +If the work touches state described in `infra/docs/architecture/` or +`infra/docs/runbooks/`, read the relevant files BEFORE dispatching +researchers. These docs are the authoritative starting point for +current infra state — what's deployed, how it's wired, which +conventions apply. + +- `infra/docs/architecture/` — long-lived state (networking, storage, + auth, databases, CI/CD, monitoring, backup-dr, etc.) +- `infra/docs/runbooks/` — operational procedures (restores, upgrades, + recoveries) +- `infra/docs/plans/` — dated design/plan pairs for prior changes; + grep here first when a similar change has been done before +- `infra/docs/post-mortems/` — incident analyses; relevant when work + touches a past failure surface + +If the docs contradict the live state, that mismatch is itself a +finding — surface it and resolve before proceeding. + +## Phase 2b: Challenge, Verify, and Counter-Propose + +**Always required.** After researchers report back, spawn **2 independent challenger subagents** in parallel. Each works INDEPENDENTLY — they do NOT see each other's output. + +### Challenger mandate: + +``` +## Role: Independent Research Challenger + +You are reviewing research findings. Your job has THREE parts: + +### 1. Scrutinize +- Challenge the root cause analysis — what else could explain this? +- Question assumptions — what is assumed without evidence? +- Find missed edge cases — what happens with empty/null/stale/concurrent? +- Identify missing investigations — what callers/consumers were NOT checked? + +### 2. Verify every reference +- For every FILE PATH cited: confirm it exists +- For every FUNCTION/CLASS cited: confirm it exists +- For every DATA CLAIM: confirm the data source exists and the query is valid +- Flag ANY reference that cannot be verified as UNVERIFIED + +### 3. Counter-propose +- Propose at least ONE alternative approach to the problem +- Your alternative must ALSO be backed by verified code/data references +- Explain trade-offs: why your approach might be better or worse + +Report: +- VERIFIED: claims you confirmed exist +- UNVERIFIED: claims you could not confirm +- ISSUES: genuine problems with the findings (not nitpicks) +- COUNTER-PROPOSAL: your alternative approach with references +- VERDICT: AGREE (approach is sound) or DISAGREE (significant issues remain) +``` + +### Convergence check + +After challengers return, evaluate: + +1. **Unverified claims** — if any reference was flagged UNVERIFIED, dispatch a researcher to verify or remove it +2. **Genuine issues** — if challengers found real problems, dispatch a new research round → back to Phase 2b +3. **Agreement** — if both challengers AGREE the approach is sound, proceed to Phase 3 +4. **Counter-proposals** — if a counter-proposal is clearly better, adopt it and re-validate + +**Never present unvetted findings to the user.** All claims must be verified. + +## Phase 3: Resolve All Ambiguities + +After researchers report back AND challengers have agreed on the approach: + +1. **List every open question** — anything the researchers couldn't answer or disagreed on +2. **Ask the user** (via AskUserQuestion) to resolve each one — do NOT guess, do NOT assume +3. **Present the plan via ExitPlanMode** with: + - **Goal**: what we're doing and why + - **Research Decisions**: callers, blast radius, patterns to reuse, edge cases + - **Plan**: ordered steps with checkboxes + +ExitPlanMode is the approval gate. Once the user accepts, hand off to `execution.md` — no further "should I proceed?" check. + +## Research completeness checklist + +Research is NOT complete if any of these are true: +- [ ] Callers were not traced +- [ ] No search for existing patterns +- [ ] Edge cases not identified +- [ ] Assumptions not validated with data +- [ ] Open questions remain +- [ ] No blast radius assessment +- [ ] References not verified (file paths, functions cited without confirming they exist) +- [ ] No challenge round completed +- [ ] Challengers did not agree + +If any box is checked, research is incomplete. Go back and fill the gaps before surfacing a plan. diff --git a/dot_claude/rules/quality.md b/dot_claude/rules/quality.md new file mode 100644 index 0000000..681a4e1 --- /dev/null +++ b/dot_claude/rules/quality.md @@ -0,0 +1,72 @@ +# Quality (applies to ALL agents) + +**If you are writing code, this applies to YOU. No exceptions.** + +## 1. TDD cycle — test-first + +1. **RED** — Write a failing test. Run it. Confirm it fails. +2. **GREEN** — Write minimal code to pass. Only enough to make the test green. +3. **REFACTOR** — Clean up. Tests stay green. +4. **VERIFY** — All must pass before committing: + - Run tests: `pytest` (Python) / `npm test` (JS/TS) + - Type check: `mypy .` (Python) / `tsc --noEmit` (TS) + - Format: `yapf` (Python) / `prettier` (JS/TS) + - Lint: `ruff check` (Python) / `eslint` (JS/TS) — **check the output**. Fix ALL errors before proceeding. +5. **COMMIT** — commit the verified change. +6. **REPEAT** — back to step 1. + +## 2. Blockers — non-negotiable + +- Writing implementation before a failing test exists = **BLOCKED** +- Skipping tests (with any excuse) = **BLOCKED** +- Writing tests after implementation = **BLOCKED** +- Lint errors (unused variables, missing imports) = **BLOCKED** — run linter and fix before proceeding. + +## 3. Test quality rules + +- Each test verifies ONE behavior +- Test behavior, not implementation (don't mock internals you own) +- Use data providers / parameterized tests for multi-scenario coverage +- Prefer property-based tests over example-based where the language supports it + +## 4. Code quality checklist + +Use this checklist for all code reviews and for your own output before committing. Evaluate each section and assign a verdict. + +### AI slop detection + +- [ ] No comments restating code (e.g., `// increment counter`, `// set the value`) +- [ ] No unnecessary docstrings (e.g., `/** Gets the value */` on a getter) +- [ ] No filler phrases (e.g., `This function is responsible for...`) +- [ ] No wrapper functions adding no value +- [ ] No commented-out code +- [ ] No redundant type annotations in comments +- [ ] No over-explained variable names — context comes from scope + +### Engineering principles + +- [ ] SRP: each function has a single responsibility (can describe without "and") +- [ ] DRY: existing utilities reused (searched before creating new) +- [ ] No premature abstractions or "just in case" parameters +- [ ] Functions ≤20 lines (excluding type signatures) +- [ ] Functions ≤3 parameters (more = use a struct/shape/object) +- [ ] Functions ≤1 nesting level (early return over nested if/else) +- [ ] No boolean parameters — named constants or enums instead +- [ ] No magic values — named constants used +- [ ] Error handling: fail fast, fail loud — no silent `catch {}` + +### Idiomatic patterns + +Write idiomatic code for each language. Common AI-generated anti-patterns: +- [ ] Sequential awaits on independent calls → use concurrent/parallel execution +- [ ] Loop + await → use async map/batch operations +- [ ] Loading all data into memory then filtering → use server-side/query-level filtering +- [ ] Acronyms in names (`ra`, `exp`) → use full names (`resource_account`, `experiment`) + +### Verdicts + +| Verdict | Criteria | +|---------|----------| +| **PASS** | All checks pass | +| **REVISE** | Non-critical issues (naming, minor DRY, style nits) | +| **BLOCK** | AI slop present, no tests for new behavior, or SOLID violation |