From 43291f7ef9b75795e49084a0326c9b005de99c76 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 27 Apr 2026 08:43:28 +0000 Subject: [PATCH 01/13] docs: add routines section with audit orchestrator prompt Captures the prompts used to schedule recurring Claude web tasks so they live under version control. Seeds the directory with the master-orchestrator audit routine. --- docs/routines/README.md | 13 ++++++++ docs/routines/audit.md | 71 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 84 insertions(+) create mode 100644 docs/routines/README.md create mode 100644 docs/routines/audit.md diff --git a/docs/routines/README.md b/docs/routines/README.md new file mode 100644 index 00000000..3dbdccc2 --- /dev/null +++ b/docs/routines/README.md @@ -0,0 +1,13 @@ +# Routines + +Prompts used in Claude web to schedule recurring agentic tasks (audits, reviews, sweeps, etc.). + +Stored here for version control and documentation. The prompts run on Claude web — this directory is the source of truth for their text. + +## Conventions + +- One file per routine, named for what it does (e.g. `audit.md`). +- Top of each file: brief summary, expected schedule, and where it runs. +- Body: the exact prompt text, copy-pasteable into Claude web. + +When updating a routine, update the file here first, then paste into Claude web. diff --git a/docs/routines/audit.md b/docs/routines/audit.md new file mode 100644 index 00000000..39175e38 --- /dev/null +++ b/docs/routines/audit.md @@ -0,0 +1,71 @@ +# Audit + +Master-orchestrator codebase audit. Runs in Claude web on a schedule, attached to a repo. Spawns parallel fresh agents to review the full tree, files findings as GitHub issues, and opens auto-fix PRs for obvious issues. + +- **Where it runs:** Claude web, scheduled task, attached to a single repo at a time. +- **Cadence:** as scheduled in Claude web. +- **Output:** master report issue + child issues per finding + draft/auto-fix PRs. + +## Prompt + +Per repo attached. You = master orchestrator. Fresh agents do all work. Master report stays in own repo. No cross-repo mentions in individual reports. + +### Core task + +Audit full codebase, main branch only. Skip if HEAD == commit in last report. + +Spawn parallel agents, narrow by concern (not file scope). Default split: +- security → sub-split: input validation/DoS, auth/permissions, web/WASM, deps/supply-chain +- tech debt / code quality +- clean architecture (diff specs vs code; pass spec paths explicitly) +- test coverage +- general review + +Spawn more if area needs depth. + +### Synthesis + +Collect findings → master issue (commit + all findings) + child issue per finding. Cross-ref open issues here for dedup. Second pass w/ fresh agents: verify findings real + non-dup via grep/rg for exact patterns cited. + +### Auto-fix + +Obvious findings → open PR via git worktrees (parallel). Monitor CI till green. Ambiguous findings → draft PR w/ questions in description. + +### Background + +Fresh agent sweeps existing open issues for resolved/false-positive → close w/ reason comment. Conservative; no-op fine. + +Identify other existing issues workable in parallel; same PR rules. + +### Lessons section + +Append "lessons learned" section to report. Feed back into this prompt next run. + +### /audit in PR + +Same flow but review PR only. No issues, no PRs. + +--- + +## Hard Rules + +### Scope +- Audit full tree always. Never scope to diff. +- Agents blind to existing issues. Dedup = synthesis + 2nd pass only. + +### Agent prompts (mandatory fields) +- Time budget: 6 min, stop+save if exceeded. +- Incremental write: scaffold report file before 2nd tool call; append each finding complete before next. +- Per-finding: file:line, severity (split: security = confidentiality/integrity; robustness = availability/DoS), Obvious? yes/no. +- Count/ratio claims: verify w/ second grep cmd proving count. +- Use general-purpose agent (Explore can't Write). +- Architecture agents: skip cargo tree/cargo clippy; use rg + ls + reads. +- GitHub comms (issues, PRs, comments, reviews) written in caveman mode. Code blocks + security warnings stay normal. + +### Setup +- `cargo install --locked cargo-audit` upfront (or verify); run as 1st step in security/deps. +- Pre-worktree: `git stash` or `git restore` main dir; add `.claude/worktrees/` to `.gitignore`. + +### Quality +- Quality > speed. Always thorough path. +- Independently spot-check every filed finding. From af486638db51b6aeb5e394caed23b2bae92b0f10 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 27 Apr 2026 08:45:05 +0000 Subject: [PATCH 02/13] docs: drop cross-repo language from audit routine Routine targets a single repo when run, so the multi-repo orchestration caveats don't apply. --- docs/routines/audit.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/routines/audit.md b/docs/routines/audit.md index 39175e38..fe214cb1 100644 --- a/docs/routines/audit.md +++ b/docs/routines/audit.md @@ -8,7 +8,7 @@ Master-orchestrator codebase audit. Runs in Claude web on a schedule, attached t ## Prompt -Per repo attached. You = master orchestrator. Fresh agents do all work. Master report stays in own repo. No cross-repo mentions in individual reports. +You = master orchestrator. Fresh agents do all work. ### Core task From ca3c47adf001fd3307507e843e7f395855c00547 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 27 Apr 2026 08:49:09 +0000 Subject: [PATCH 03/13] feat: convert audit routine into a user-invocable skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Move the audit prompt from docs/routines/ into .claude/skills/audit/SKILL.md so it can be invoked directly (`/audit` in Claude web or Code) instead of being copy-pasted. Drop docs/routines/ — future routines should use the same skill format. --- .../audit.md => .claude/skills/audit/SKILL.md | 33 ++++++++++--------- docs/routines/README.md | 13 -------- 2 files changed, 17 insertions(+), 29 deletions(-) rename docs/routines/audit.md => .claude/skills/audit/SKILL.md (80%) delete mode 100644 docs/routines/README.md diff --git a/docs/routines/audit.md b/.claude/skills/audit/SKILL.md similarity index 80% rename from docs/routines/audit.md rename to .claude/skills/audit/SKILL.md index fe214cb1..09666d0c 100644 --- a/docs/routines/audit.md +++ b/.claude/skills/audit/SKILL.md @@ -1,16 +1,19 @@ -# Audit +--- +name: audit +description: Use when running a scheduled audit of the Willow codebase, or when /audit is invoked on a pull request for review +user-invocable: true +--- -Master-orchestrator codebase audit. Runs in Claude web on a schedule, attached to a repo. Spawns parallel fresh agents to review the full tree, files findings as GitHub issues, and opens auto-fix PRs for obvious issues. +# Audit -- **Where it runs:** Claude web, scheduled task, attached to a single repo at a time. -- **Cadence:** as scheduled in Claude web. -- **Output:** master report issue + child issues per finding + draft/auto-fix PRs. +You = master orchestrator. Fresh agents do all work. -## Prompt +## When to Use -You = master orchestrator. Fresh agents do all work. +- Scheduled run on `main`: full-tree audit, files findings as issues, opens auto-fix PRs. +- `/audit` invoked in a PR: review the PR only — no issues, no PRs. -### Core task +## Core Task Audit full codebase, main branch only. Skip if HEAD == commit in last report. @@ -23,30 +26,28 @@ Spawn parallel agents, narrow by concern (not file scope). Default split: Spawn more if area needs depth. -### Synthesis +## Synthesis Collect findings → master issue (commit + all findings) + child issue per finding. Cross-ref open issues here for dedup. Second pass w/ fresh agents: verify findings real + non-dup via grep/rg for exact patterns cited. -### Auto-fix +## Auto-fix Obvious findings → open PR via git worktrees (parallel). Monitor CI till green. Ambiguous findings → draft PR w/ questions in description. -### Background +## Background Fresh agent sweeps existing open issues for resolved/false-positive → close w/ reason comment. Conservative; no-op fine. Identify other existing issues workable in parallel; same PR rules. -### Lessons section +## Lessons Learned -Append "lessons learned" section to report. Feed back into this prompt next run. +Append "lessons learned" section to report. Feed back into this skill next run. -### /audit in PR +## /audit in PR Same flow but review PR only. No issues, no PRs. ---- - ## Hard Rules ### Scope diff --git a/docs/routines/README.md b/docs/routines/README.md deleted file mode 100644 index 3dbdccc2..00000000 --- a/docs/routines/README.md +++ /dev/null @@ -1,13 +0,0 @@ -# Routines - -Prompts used in Claude web to schedule recurring agentic tasks (audits, reviews, sweeps, etc.). - -Stored here for version control and documentation. The prompts run on Claude web — this directory is the source of truth for their text. - -## Conventions - -- One file per routine, named for what it does (e.g. `audit.md`). -- Top of each file: brief summary, expected schedule, and where it runs. -- Body: the exact prompt text, copy-pasteable into Claude web. - -When updating a routine, update the file here first, then paste into Claude web. From 01db5a25bbbd350be1ae641244caa16576707292 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 27 Apr 2026 08:51:43 +0000 Subject: [PATCH 04/13] feat: rename audit skill to general-audit, scope to filing only MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Skill now files findings only — opens master + child issues, no auto-fix PRs and no closing of existing issues. Resolution will live in a separate routine. Renamed to general-audit to leave room for narrower audit skills. --- .../skills/{audit => general-audit}/SKILL.md | 30 +++++++------------ 1 file changed, 10 insertions(+), 20 deletions(-) rename .claude/skills/{audit => general-audit}/SKILL.md (64%) diff --git a/.claude/skills/audit/SKILL.md b/.claude/skills/general-audit/SKILL.md similarity index 64% rename from .claude/skills/audit/SKILL.md rename to .claude/skills/general-audit/SKILL.md index 09666d0c..03237367 100644 --- a/.claude/skills/audit/SKILL.md +++ b/.claude/skills/general-audit/SKILL.md @@ -1,17 +1,17 @@ --- -name: audit -description: Use when running a scheduled audit of the Willow codebase, or when /audit is invoked on a pull request for review +name: general-audit +description: Use when running a scheduled general audit of the Willow codebase, or when /general-audit is invoked on a pull request for review user-invocable: true --- -# Audit +# General Audit -You = master orchestrator. Fresh agents do all work. +You = master orchestrator. Fresh agents do all work. Job = find + file findings. Resolution = separate routine. ## When to Use -- Scheduled run on `main`: full-tree audit, files findings as issues, opens auto-fix PRs. -- `/audit` invoked in a PR: review the PR only — no issues, no PRs. +- Scheduled run on `main`: full-tree audit, files findings as issues. +- `/general-audit` invoked in a PR: review the PR only — no issues filed. ## Core Task @@ -30,29 +30,20 @@ Spawn more if area needs depth. Collect findings → master issue (commit + all findings) + child issue per finding. Cross-ref open issues here for dedup. Second pass w/ fresh agents: verify findings real + non-dup via grep/rg for exact patterns cited. -## Auto-fix - -Obvious findings → open PR via git worktrees (parallel). Monitor CI till green. Ambiguous findings → draft PR w/ questions in description. - -## Background - -Fresh agent sweeps existing open issues for resolved/false-positive → close w/ reason comment. Conservative; no-op fine. - -Identify other existing issues workable in parallel; same PR rules. - ## Lessons Learned Append "lessons learned" section to report. Feed back into this skill next run. -## /audit in PR +## /general-audit in PR -Same flow but review PR only. No issues, no PRs. +Same flow but review PR only. No issues filed. ## Hard Rules ### Scope - Audit full tree always. Never scope to diff. - Agents blind to existing issues. Dedup = synthesis + 2nd pass only. +- File findings only. No PRs, no auto-fix, no closing existing issues. Resolution = separate routine. ### Agent prompts (mandatory fields) - Time budget: 6 min, stop+save if exceeded. @@ -61,11 +52,10 @@ Same flow but review PR only. No issues, no PRs. - Count/ratio claims: verify w/ second grep cmd proving count. - Use general-purpose agent (Explore can't Write). - Architecture agents: skip cargo tree/cargo clippy; use rg + ls + reads. -- GitHub comms (issues, PRs, comments, reviews) written in caveman mode. Code blocks + security warnings stay normal. +- GitHub comms (issues, comments, reviews) written in caveman mode. Code blocks + security warnings stay normal. ### Setup - `cargo install --locked cargo-audit` upfront (or verify); run as 1st step in security/deps. -- Pre-worktree: `git stash` or `git restore` main dir; add `.claude/worktrees/` to `.gitignore`. ### Quality - Quality > speed. Always thorough path. From f1a9d824165c3a002185d2e7fed1ce2f5a054f14 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 27 Apr 2026 08:53:47 +0000 Subject: [PATCH 05/13] feat: add resolving-issues skill for autonomous backlog work Companion to general-audit. Coordinator-only skill that sweeps open issues and PRs, dispatches up to 3 parallel subagents in git worktrees to fix small-scope items, and drafts PRs with questions when scope is unclear. GH comms stay caveman; large features and refactors out of scope. --- .claude/skills/resolving-issues/SKILL.md | 68 ++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 .claude/skills/resolving-issues/SKILL.md diff --git a/.claude/skills/resolving-issues/SKILL.md b/.claude/skills/resolving-issues/SKILL.md new file mode 100644 index 00000000..b80a57e4 --- /dev/null +++ b/.claude/skills/resolving-issues/SKILL.md @@ -0,0 +1,68 @@ +--- +name: resolving-issues +description: Use when running a scheduled pass over the open issue + PR queue to clear small-scope fixes, or when /resolving-issues is invoked manually +user-invocable: true +--- + +# Resolving Issues + +You = coordinator. Subagents = workers. You dispatch + monitor, never touch files. + +## When to Use + +- Scheduled run: sweep open issues + PRs, dispatch subagents to fix small items in parallel. +- Manual invoke: same flow, on demand. + +## Required Skills + +- **REQUIRED:** `superpowers:dispatching-parallel-agents` — fan out work. +- **REQUIRED:** `superpowers:using-git-worktrees` — isolate each subagent. +- **REQUIRED:** `superpowers:caveman` — all GH comms. +- **REQUIRED for subagents:** `superpowers:test-driven-development`, `superpowers:verification-before-completion`. + +## Core Loop + +1. Read open issues + open PRs. Skip anything already in flight. +2. Pick small-scope fixes. `general-audit` issues = top priority. +3. Skip big features + major refactors. Out of scope here. +4. Dispatch subagent per issue, max 3 parallel via git worktrees. +5. Subagent: fix → tests → PR with `Fixes #N` and caveman body. +6. Follow-up issue filed when subagent finds related rot. +7. No work fits? Noop fine. + +## Rules + +### Coordinator never codes +- Read, dispatch, monitor. Subagents touch files. +- One worktree per subagent. Max 3 concurrent. Queue the rest. + +### Scope filter +- Fixes + small-scope changes only. +- No big features. No major refactors. No architecture rewrites. +- Unsure too big? Draft PR + questions in body. Wait for human reply. + +### PR rules +- One PR per issue (or tight batch). +- `Fixes #N` in body to auto-close on merge. +- `just check` green before marking ready. +- Blocked? Draft PR + questions. Do not force. + +### GitHub comms +- All issue + PR bodies + comments in caveman mode. +- Code blocks + security warnings stay normal. + +### Autonomy +- Best judgment. No hand-holding. +- Direction needed? Draft PR + question. Do not stall. +- Noop fine. Ship nothing > ship junk. + +## Setup + +- Pre-worktree: `git stash` or `git restore` main dir; `.claude/worktrees/` in `.gitignore`. +- Tear down worktree after PR merges or closes. + +## Quality + +- `just check` green before PR ready. +- Tests at lowest tier covering behavior (see `CLAUDE.md`). +- Spot-check each subagent's diff before marking PR ready. From 475c932acc4a99705aae57ae445a6bd2f91e8d21 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 27 Apr 2026 08:59:07 +0000 Subject: [PATCH 06/13] feat: sequential resolving-issues, worktrees on both audit skills resolving-issues: cap 10 issues per run, sequential not parallel, fresh subagent + fresh worktree per issue. general-audit: require git worktrees in setup so each subagent runs isolated from main checkout. Caveman speech applied to resolving-issues body. --- .claude/skills/general-audit/SKILL.md | 2 ++ .claude/skills/resolving-issues/SKILL.md | 45 +++++++++++++++--------- 2 files changed, 30 insertions(+), 17 deletions(-) diff --git a/.claude/skills/general-audit/SKILL.md b/.claude/skills/general-audit/SKILL.md index 03237367..eb81cff3 100644 --- a/.claude/skills/general-audit/SKILL.md +++ b/.claude/skills/general-audit/SKILL.md @@ -55,6 +55,8 @@ Same flow but review PR only. No issues filed. - GitHub comms (issues, comments, reviews) written in caveman mode. Code blocks + security warnings stay normal. ### Setup +- **REQUIRED:** `superpowers:using-git-worktrees` — one worktree per subagent for isolation. +- Pre-worktree: `git stash` or `git restore` main dir; `.claude/worktrees/` in `.gitignore`. Tear down after report submitted. - `cargo install --locked cargo-audit` upfront (or verify); run as 1st step in security/deps. ### Quality diff --git a/.claude/skills/resolving-issues/SKILL.md b/.claude/skills/resolving-issues/SKILL.md index b80a57e4..a2739ce7 100644 --- a/.claude/skills/resolving-issues/SKILL.md +++ b/.claude/skills/resolving-issues/SKILL.md @@ -1,50 +1,61 @@ --- name: resolving-issues -description: Use when running a scheduled pass over the open issue + PR queue to clear small-scope fixes, or when /resolving-issues is invoked manually +description: Use when running scheduled pass over open issue + PR queue to clear small-scope fixes, or when /resolving-issues invoked manually user-invocable: true --- # Resolving Issues -You = coordinator. Subagents = workers. You dispatch + monitor, never touch files. +You = coordinator. Fresh subagents = workers. Read, dispatch, monitor. Never touch files. -## When to Use +## When -- Scheduled run: sweep open issues + PRs, dispatch subagents to fix small items in parallel. -- Manual invoke: same flow, on demand. +- Scheduled: sweep open issues + PRs, fix small items sequentially. +- Manual: same flow, on demand. ## Required Skills -- **REQUIRED:** `superpowers:dispatching-parallel-agents` — fan out work. - **REQUIRED:** `superpowers:using-git-worktrees` — isolate each subagent. - **REQUIRED:** `superpowers:caveman` — all GH comms. - **REQUIRED for subagents:** `superpowers:test-driven-development`, `superpowers:verification-before-completion`. ## Core Loop -1. Read open issues + open PRs. Skip anything already in flight. +1. Read open issues + open PRs. Skip anything in flight. 2. Pick small-scope fixes. `general-audit` issues = top priority. -3. Skip big features + major refactors. Out of scope here. -4. Dispatch subagent per issue, max 3 parallel via git worktrees. -5. Subagent: fix → tests → PR with `Fixes #N` and caveman body. -6. Follow-up issue filed when subagent finds related rot. -7. No work fits? Noop fine. +3. Skip big features + major refactors. Out of scope. +4. Per issue, sequential, max 10 per run: + - Spawn fresh worktree. + - Dispatch fresh subagent. Subagent: fix → tests → PR with `Fixes #N` + caveman body. + - Wait PR ready (or draft). + - Tear down worktree. + - Next issue. +5. Subagent finds related rot? File follow-up issue. +6. No work fits? Noop fine. ## Rules ### Coordinator never codes - Read, dispatch, monitor. Subagents touch files. -- One worktree per subagent. Max 3 concurrent. Queue the rest. +- One worktree per issue. Sequential. Tear down before next. + +### Sequential, not parallel +- One issue at a time. No parallel subagents. +- Save resources. Cap = 10 issues per run. + +### Fresh agent per issue +- New subagent each issue. No state leak. +- Subagent gets only that issue's context. ### Scope filter -- Fixes + small-scope changes only. +- Fixes + small-scope only. - No big features. No major refactors. No architecture rewrites. -- Unsure too big? Draft PR + questions in body. Wait for human reply. +- Too big? Draft PR + questions in body. Wait for human reply. ### PR rules - One PR per issue (or tight batch). - `Fixes #N` in body to auto-close on merge. -- `just check` green before marking ready. +- `just check` green before ready. - Blocked? Draft PR + questions. Do not force. ### GitHub comms @@ -59,7 +70,7 @@ You = coordinator. Subagents = workers. You dispatch + monitor, never touch file ## Setup - Pre-worktree: `git stash` or `git restore` main dir; `.claude/worktrees/` in `.gitignore`. -- Tear down worktree after PR merges or closes. +- Worktree per issue. Tear down after PR ready/draft/closed. ## Quality From 8c433d73c0e7a895494a39c492c21e14117cfe2e Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 27 Apr 2026 09:00:43 +0000 Subject: [PATCH 07/13] fix: drop superpowers prefix from caveman skill ref Caveman lives in its own plugin, not superpowers. --- .claude/skills/resolving-issues/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/skills/resolving-issues/SKILL.md b/.claude/skills/resolving-issues/SKILL.md index a2739ce7..ae4dd36b 100644 --- a/.claude/skills/resolving-issues/SKILL.md +++ b/.claude/skills/resolving-issues/SKILL.md @@ -16,7 +16,7 @@ You = coordinator. Fresh subagents = workers. Read, dispatch, monitor. Never tou ## Required Skills - **REQUIRED:** `superpowers:using-git-worktrees` — isolate each subagent. -- **REQUIRED:** `superpowers:caveman` — all GH comms. +- **REQUIRED:** `caveman` — all GH comms. - **REQUIRED for subagents:** `superpowers:test-driven-development`, `superpowers:verification-before-completion`. ## Core Loop From a74902a4715484c0dd7138a93ce9d0e68a47e9e2 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 27 Apr 2026 09:08:08 +0000 Subject: [PATCH 08/13] feat: master PR pattern for resolving-issues Sub-fixes land in a single long-running draft PR per run instead of opening N independent PRs against main. Implementer agent owns the full issue lifecycle: optional research subagents, worktree off master PR branch, sub-PR into master PR, CI watch, merge on green. Human reviews the master PR holistically and Fixes #N keywords there auto-close all linked issues on merge. --- .claude/skills/resolving-issues/SKILL.md | 83 ++++++++++++++++-------- 1 file changed, 55 insertions(+), 28 deletions(-) diff --git a/.claude/skills/resolving-issues/SKILL.md b/.claude/skills/resolving-issues/SKILL.md index ae4dd36b..34a37d0a 100644 --- a/.claude/skills/resolving-issues/SKILL.md +++ b/.claude/skills/resolving-issues/SKILL.md @@ -6,57 +6,83 @@ user-invocable: true # Resolving Issues -You = coordinator. Fresh subagents = workers. Read, dispatch, monitor. Never touch files. +You = coordinator. Implementer subagents = workers. Read, dispatch, monitor. Never touch files. ## When -- Scheduled: sweep open issues + PRs, fix small items sequentially. +- Scheduled: sweep open issues + PRs, fix small items sequentially into one master PR. - Manual: same flow, on demand. ## Required Skills -- **REQUIRED:** `superpowers:using-git-worktrees` — isolate each subagent. +- **REQUIRED:** `superpowers:using-git-worktrees` — isolate each implementer. - **REQUIRED:** `caveman` — all GH comms. -- **REQUIRED for subagents:** `superpowers:test-driven-development`, `superpowers:verification-before-completion`. +- **REQUIRED for implementers:** `superpowers:test-driven-development`, `superpowers:verification-before-completion`, `superpowers:dispatching-parallel-agents` (for research subagents). + +## Master PR Pattern + +All sub-fixes land in one long-running master PR. Human reviews master PR holistically + merges → all linked issues auto-close. + +### Master PR setup +1. Check open PRs for existing master PR (label `auto-fix-batch` or branch prefix `auto-fix/batch-`). Reuse if found — orchestrator checks out that branch. +2. If none, create branch `auto-fix/batch-YYYY-MM-DD` off latest `main`. Push. Open **draft** PR titled `auto-fix batch YYYY-MM-DD` targeting `main`. Apply label `auto-fix-batch`. +3. Master PR body = running list of `Fixes #N` lines, one per resolved issue. Update after each sub-PR merge. + +### Sub-PR rules +- Sub-PR base = master PR branch, NOT `main`. +- Sub-PR body references issue (`Refs #N`) — no `Fixes` keyword. `Fixes` lives only on master PR so issues close on master merge. +- Implementer watches CI on sub-PR. CI green → merge sub-PR into master PR branch. +- CI red after one fix attempt → convert sub-PR to draft + caveman question. Move on. ## Core Loop 1. Read open issues + open PRs. Skip anything in flight. 2. Pick small-scope fixes. `general-audit` issues = top priority. 3. Skip big features + major refactors. Out of scope. -4. Per issue, sequential, max 10 per run: - - Spawn fresh worktree. - - Dispatch fresh subagent. Subagent: fix → tests → PR with `Fixes #N` + caveman body. - - Wait PR ready (or draft). +4. Ensure master PR exists (create or reuse). +5. Per issue, sequential, max 10 per run: + - Spawn fresh implementer agent. + - Implementer: worktree off master PR branch → research subagents if needed → fix → tests → sub-PR into master PR → watch CI → merge on green. + - On merge, append `Fixes #N` to master PR body. - Tear down worktree. - Next issue. -5. Subagent finds related rot? File follow-up issue. -6. No work fits? Noop fine. +6. Implementer finds related rot? File follow-up issue. +7. Run done? Leave master PR as draft. Human marks ready when satisfied. +8. No work fits + no commits added this run? Noop fine. + +## Implementer Agent + +Fresh agent per issue, scoped to one issue + master PR branch ref. Steps: + +1. Read the issue. Decide if more context needed. +2. **Research (optional, parallel OK):** spawn research subagents for codebase grep, related-file reads, spec lookups. Synthesize before coding. +3. Open worktree branched off master PR branch. Branch name: `auto-fix/issue-N-short-slug`. +4. Apply fix. Add tests at lowest tier covering behavior (see `CLAUDE.md`). +5. `just check` green locally before pushing. +6. Push branch. Open sub-PR with master PR branch as base. +7. Watch CI. Flake → re-run. Real failure → one fix attempt. +8. CI green → merge sub-PR into master PR branch. Tear down worktree. +9. CI still red → draft sub-PR + caveman question in body. Return control to coordinator. ## Rules ### Coordinator never codes -- Read, dispatch, monitor. Subagents touch files. -- One worktree per issue. Sequential. Tear down before next. +- Read, dispatch, monitor. Implementers touch files. +- One worktree per issue. Sequential between issues. Tear down after merge or draft-park. -### Sequential, not parallel -- One issue at a time. No parallel subagents. -- Save resources. Cap = 10 issues per run. +### Sequential between issues +- One issue at a time. No parallel implementers. +- Research subagents *inside* an implementer may run in parallel. +- Cap = 10 issues per run. ### Fresh agent per issue -- New subagent each issue. No state leak. -- Subagent gets only that issue's context. +- New implementer each issue. No state leak. +- Each implementer gets only its issue + master PR branch ref. ### Scope filter - Fixes + small-scope only. - No big features. No major refactors. No architecture rewrites. -- Too big? Draft PR + questions in body. Wait for human reply. - -### PR rules -- One PR per issue (or tight batch). -- `Fixes #N` in body to auto-close on merge. -- `just check` green before ready. -- Blocked? Draft PR + questions. Do not force. +- Too big? Skip. Comment caveman note on issue if scope misclassified. ### GitHub comms - All issue + PR bodies + comments in caveman mode. @@ -64,16 +90,17 @@ You = coordinator. Fresh subagents = workers. Read, dispatch, monitor. Never tou ### Autonomy - Best judgment. No hand-holding. -- Direction needed? Draft PR + question. Do not stall. +- Mid-fix block? Implementer drafts sub-PR + caveman question, moves on. - Noop fine. Ship nothing > ship junk. ## Setup - Pre-worktree: `git stash` or `git restore` main dir; `.claude/worktrees/` in `.gitignore`. -- Worktree per issue. Tear down after PR ready/draft/closed. +- Worktree per issue, branched off master PR branch. Tear down after sub-PR merges or parks as draft. ## Quality -- `just check` green before PR ready. +- `just check` green before sub-PR opened. - Tests at lowest tier covering behavior (see `CLAUDE.md`). -- Spot-check each subagent's diff before marking PR ready. +- Sub-PR merges into master PR only after CI green. +- Master PR stays draft for entire orchestrator run. Human marks ready when satisfied. From 1c1e7789b6995ded9da63c4457b95bac41ef6727 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 27 Apr 2026 09:11:22 +0000 Subject: [PATCH 09/13] feat: file lessons-learned as a tracked issue, not in-report Lessons feedback now opens a dedicated issue per run instead of being appended to the report. Human edits the skill file directly to incorporate the suggestions, keeping the loop in version control. --- .claude/skills/general-audit/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/skills/general-audit/SKILL.md b/.claude/skills/general-audit/SKILL.md index eb81cff3..1fbe47f8 100644 --- a/.claude/skills/general-audit/SKILL.md +++ b/.claude/skills/general-audit/SKILL.md @@ -32,7 +32,7 @@ Collect findings → master issue (commit + all findings) + child issue per find ## Lessons Learned -Append "lessons learned" section to report. Feed back into this skill next run. +Open dedicated issue per run titled `general-audit lessons: YYYY-MM-DD` with caveman body listing what worked, what didn't, and concrete suggested edits to this skill file. Human (or follow-up routine) edits `.claude/skills/general-audit/SKILL.md` directly to incorporate. ## /general-audit in PR From ca119f1edc1692adf39813eb5ca08e1fdedf16ff Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 27 Apr 2026 09:12:40 +0000 Subject: [PATCH 10/13] feat: add Required Skills section to general-audit Lists superpowers + caveman dependencies up front so the orchestrator loads them at run start rather than discovering them mid-flow. --- .claude/skills/general-audit/SKILL.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/.claude/skills/general-audit/SKILL.md b/.claude/skills/general-audit/SKILL.md index 1fbe47f8..d57012ee 100644 --- a/.claude/skills/general-audit/SKILL.md +++ b/.claude/skills/general-audit/SKILL.md @@ -8,6 +8,13 @@ user-invocable: true You = master orchestrator. Fresh agents do all work. Job = find + file findings. Resolution = separate routine. +## Required Skills + +- **REQUIRED:** `superpowers:dispatching-parallel-agents` — fan out audit concerns. +- **REQUIRED:** `superpowers:using-git-worktrees` — one worktree per subagent. +- **REQUIRED:** `caveman` — all GH comms. +- **REQUIRED for verification pass:** `superpowers:verification-before-completion` — spot-check findings before filing. + ## When to Use - Scheduled run on `main`: full-tree audit, files findings as issues. @@ -55,8 +62,7 @@ Same flow but review PR only. No issues filed. - GitHub comms (issues, comments, reviews) written in caveman mode. Code blocks + security warnings stay normal. ### Setup -- **REQUIRED:** `superpowers:using-git-worktrees` — one worktree per subagent for isolation. -- Pre-worktree: `git stash` or `git restore` main dir; `.claude/worktrees/` in `.gitignore`. Tear down after report submitted. +- Pre-worktree: `git stash` or `git restore` main dir; `.claude/worktrees/` in `.gitignore`. One worktree per subagent. Tear down after report submitted. - `cargo install --locked cargo-audit` upfront (or verify); run as 1st step in security/deps. ### Quality From 0d99da76821ee3682b5f80c41827e63609f9da5b Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 27 Apr 2026 09:14:19 +0000 Subject: [PATCH 11/13] feat: fresh master PR per session, no reuse Each /resolving-issues run creates its own master PR with a timestamped branch name. Avoids tangled state from prior runs and keeps each batch reviewable on its own. --- .claude/skills/resolving-issues/SKILL.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.claude/skills/resolving-issues/SKILL.md b/.claude/skills/resolving-issues/SKILL.md index 34a37d0a..18b1139c 100644 --- a/.claude/skills/resolving-issues/SKILL.md +++ b/.claude/skills/resolving-issues/SKILL.md @@ -21,11 +21,11 @@ You = coordinator. Implementer subagents = workers. Read, dispatch, monitor. Nev ## Master PR Pattern -All sub-fixes land in one long-running master PR. Human reviews master PR holistically + merges → all linked issues auto-close. +All sub-fixes land in one master PR per session. Human reviews master PR holistically + merges → all linked issues auto-close. ### Master PR setup -1. Check open PRs for existing master PR (label `auto-fix-batch` or branch prefix `auto-fix/batch-`). Reuse if found — orchestrator checks out that branch. -2. If none, create branch `auto-fix/batch-YYYY-MM-DD` off latest `main`. Push. Open **draft** PR titled `auto-fix batch YYYY-MM-DD` targeting `main`. Apply label `auto-fix-batch`. +1. Always create fresh master PR per session. Never reuse an open one. +2. Branch off latest `main`: `auto-fix/batch-YYYY-MM-DD-HHMMSS` (timestamp = unique per session). Push. Open **draft** PR titled `auto-fix batch YYYY-MM-DD-HHMMSS` targeting `main`. Apply label `auto-fix-batch`. 3. Master PR body = running list of `Fixes #N` lines, one per resolved issue. Update after each sub-PR merge. ### Sub-PR rules From 8370866cbdd067c2e6c12f4fd2e189e9a3111965 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 27 Apr 2026 09:15:10 +0000 Subject: [PATCH 12/13] feat: lessons-learned section appended to master PR body End-of-run lessons land in the master PR body as a Lessons Learned section. Mirrors general-audit's lessons routine but writes to the PR instead of opening a separate issue, since the master PR is already the report for this routine. Also fixes a stale 'create or reuse' line that contradicted the no-reuse rule from the prior commit. --- .claude/skills/resolving-issues/SKILL.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.claude/skills/resolving-issues/SKILL.md b/.claude/skills/resolving-issues/SKILL.md index 18b1139c..2eaf7e54 100644 --- a/.claude/skills/resolving-issues/SKILL.md +++ b/.claude/skills/resolving-issues/SKILL.md @@ -39,7 +39,7 @@ All sub-fixes land in one master PR per session. Human reviews master PR holisti 1. Read open issues + open PRs. Skip anything in flight. 2. Pick small-scope fixes. `general-audit` issues = top priority. 3. Skip big features + major refactors. Out of scope. -4. Ensure master PR exists (create or reuse). +4. Create fresh master PR for this session. 5. Per issue, sequential, max 10 per run: - Spawn fresh implementer agent. - Implementer: worktree off master PR branch → research subagents if needed → fix → tests → sub-PR into master PR → watch CI → merge on green. @@ -64,6 +64,10 @@ Fresh agent per issue, scoped to one issue + master PR branch ref. Steps: 8. CI green → merge sub-PR into master PR branch. Tear down worktree. 9. CI still red → draft sub-PR + caveman question in body. Return control to coordinator. +## Lessons Learned + +End of run, append `## Lessons Learned` section to master PR body with caveman bullets: what worked, what didn't, concrete suggested edits to this skill file. Human (or follow-up routine) edits `.claude/skills/resolving-issues/SKILL.md` directly to incorporate. + ## Rules ### Coordinator never codes From c3b1a05be26f5ad62b2dd9b56ba5002ecf6f6cf4 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 27 Apr 2026 09:18:41 +0000 Subject: [PATCH 13/13] polish: fix empty master PR risk + clean up wording drift - resolving-issues: reorder Core Loop so master PR is only created when at least one in-scope issue exists, avoiding empty draft PRs on noop runs. Lessons Learned step explicit at end of run. - resolving-issues: 'drafts sub-PR' (which implied creating it) replaced with 'mark sub-PR as draft' (post-open) and 'park work as draft sub-PR' (mid-fix block, sub-PR may not exist yet). - general-audit: clarify 'last report' to 'most recent general-audit master issue' so the skip-if-same-commit check has a concrete anchor. - general-audit: drop redundant '/general-audit in PR' section; same trigger already covered in When to Use. --- .claude/skills/general-audit/SKILL.md | 6 +----- .claude/skills/resolving-issues/SKILL.md | 14 +++++++------- 2 files changed, 8 insertions(+), 12 deletions(-) diff --git a/.claude/skills/general-audit/SKILL.md b/.claude/skills/general-audit/SKILL.md index d57012ee..276473d5 100644 --- a/.claude/skills/general-audit/SKILL.md +++ b/.claude/skills/general-audit/SKILL.md @@ -22,7 +22,7 @@ You = master orchestrator. Fresh agents do all work. Job = find + file findings. ## Core Task -Audit full codebase, main branch only. Skip if HEAD == commit in last report. +Audit full codebase, main branch only. Skip if HEAD == commit recorded in most recent `general-audit` master issue. Spawn parallel agents, narrow by concern (not file scope). Default split: - security → sub-split: input validation/DoS, auth/permissions, web/WASM, deps/supply-chain @@ -41,10 +41,6 @@ Collect findings → master issue (commit + all findings) + child issue per find Open dedicated issue per run titled `general-audit lessons: YYYY-MM-DD` with caveman body listing what worked, what didn't, and concrete suggested edits to this skill file. Human (or follow-up routine) edits `.claude/skills/general-audit/SKILL.md` directly to incorporate. -## /general-audit in PR - -Same flow but review PR only. No issues filed. - ## Hard Rules ### Scope diff --git a/.claude/skills/resolving-issues/SKILL.md b/.claude/skills/resolving-issues/SKILL.md index 2eaf7e54..595965fc 100644 --- a/.claude/skills/resolving-issues/SKILL.md +++ b/.claude/skills/resolving-issues/SKILL.md @@ -39,16 +39,16 @@ All sub-fixes land in one master PR per session. Human reviews master PR holisti 1. Read open issues + open PRs. Skip anything in flight. 2. Pick small-scope fixes. `general-audit` issues = top priority. 3. Skip big features + major refactors. Out of scope. -4. Create fresh master PR for this session. -5. Per issue, sequential, max 10 per run: +4. No in-scope issues? Noop. Skip the rest. No master PR opened. +5. Create fresh master PR for this session. +6. Per issue, sequential, max 10 per run: - Spawn fresh implementer agent. - Implementer: worktree off master PR branch → research subagents if needed → fix → tests → sub-PR into master PR → watch CI → merge on green. - On merge, append `Fixes #N` to master PR body. - Tear down worktree. - Next issue. -6. Implementer finds related rot? File follow-up issue. -7. Run done? Leave master PR as draft. Human marks ready when satisfied. -8. No work fits + no commits added this run? Noop fine. +7. Implementer finds related rot? File follow-up issue. +8. Run done? Append Lessons Learned section to master PR body. Leave master PR as draft. Human marks ready when satisfied. ## Implementer Agent @@ -62,7 +62,7 @@ Fresh agent per issue, scoped to one issue + master PR branch ref. Steps: 6. Push branch. Open sub-PR with master PR branch as base. 7. Watch CI. Flake → re-run. Real failure → one fix attempt. 8. CI green → merge sub-PR into master PR branch. Tear down worktree. -9. CI still red → draft sub-PR + caveman question in body. Return control to coordinator. +9. CI still red → mark sub-PR as draft + caveman question in body. Return control to coordinator. ## Lessons Learned @@ -94,7 +94,7 @@ End of run, append `## Lessons Learned` section to master PR body with caveman b ### Autonomy - Best judgment. No hand-holding. -- Mid-fix block? Implementer drafts sub-PR + caveman question, moves on. +- Mid-fix block? Implementer parks work as draft sub-PR + caveman question, moves on. - Noop fine. Ship nothing > ship junk. ## Setup