@hanzlaa/rcode 4.0.0 → 4.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "4.0.0",
+  "version": "4.1.1",
   "description": "rcode — the AI team that never forgets. Persistent memory, specialist agents, and slash commands for AI IDEs. Works in Claude Code, Cursor, Gemini, VS Code, and Antigravity.",
   "main": "cli/index.js",
   "bin": {

package/rcode/bin/lib/config.cjs

@@ -142,12 +142,13 @@ function cmdSet(projectRoot, dottedKey, value) {
   fs.mkdirSync(path.dirname(cp), { recursive: true });
   const existing = fs.existsSync(cp) ? fs.readFileSync(cp, 'utf8') : '';
   const config = parseNestedYaml(existing);
-  setAt(config, dottedKey, value);
+  const normalizedValue = stripQuotes(String(value).trim());
+  setAt(config, dottedKey, normalizedValue);
   const out = serialise(config);
   const tmp = cp + '.tmp';
   fs.writeFileSync(tmp, out, 'utf8');
   fs.renameSync(tmp, cp);
-  return { ok: true, key: dottedKey, value, path: cp };
+  return { ok: true, key: dottedKey, value: normalizedValue, path: cp };
 }
 
 module.exports = {

package/rcode/bin/rcode-tools.cjs

@@ -3170,7 +3170,9 @@ function cmdState(subArgs) {
       }
     }
 
-    // Walk .rcode/phases/*/sprint-*.md — parse sprints into state.sprints[] (issue #135).
+    // Walk phase sprint artifacts into state.sprints[] (issue #135).
+    // Support both legacy `sprint-1.md` and workflow-generated
+    // `01-01-SPRINT.md` / `1-1-SPRINT.md` names.
     const phasesDir = path.join(PLANNING_DIR, 'phases');
     const rcodePhasesDir = path.join(RCODE_DIR, 'phases');
     const sprintRoot = fs.existsSync(phasesDir) ? phasesDir : (fs.existsSync(rcodePhasesDir) ? rcodePhasesDir : null);
@@ -3182,9 +3184,11 @@ function cmdState(subArgs) {
         const phaseNumMatch = phaseEntry.match(/^(\d+(?:\.\d+)?)/);
         const phaseNum = phaseNumMatch ? phaseNumMatch[1] : phaseEntry;
         for (const file of fs.readdirSync(phaseDir)) {
-          const sprintMatch = file.match(/^sprint-(\d+)\.md$/);
+          const sprintMatch =
+            file.match(/^sprint-(\d+)\.md$/i) ||
+            file.match(/^(?:\d+(?:\.\d+)?[-_.])?(\d+)[-_.].*SPRINT\.md$/i);
           if (!sprintMatch) continue;
-          const sprintNum = sprintMatch[1];
+          const sprintNum = String(parseInt(sprintMatch[1], 10));
           const sprintKey = `${phaseNum}/${sprintNum}`;
           parsed.sprints_found += 1;
           const sprintPath = path.join(phaseDir, file);
@@ -6795,6 +6799,7 @@ function cmdGitignore(args) {
     '.rcode/brain/best-practices/',
     '',
     '# Runtime noise',
+    'node_modules/',
     '.rcode/state.json.lock',
     '.planning/debug/',
     '.planning/_backup/',

package/rcode/skills/SKILLS_INDEX.md

@@ -1,6 +1,6 @@
 # rcode — Skills Index
 
-All 85 skills in rcode, organized by category: 23 agent skills, 37 action skills, 25 core skills, plus 2 shared modules.
+All 86 skills in rcode, organized by category: 23 agent skills, 38 action skills, 25 core skills, plus 2 shared modules.
 
 ## Agent Skills (23)
 
@@ -36,7 +36,7 @@ Note: Hussain has two hats — **PM** (strategic product management) and **SM**
 
 ---
 
-## Action Skills (37)
+## Action Skills (38)
 
 Invoked by agents via the capabilities table in their SKILL.md. Organized by SDLC phase.
 
@@ -63,7 +63,7 @@ Invoked by agents via the capabilities table in their SKILL.md. Organized by SDL
 - `actions/3-solutioning/rcode-check-implementation-readiness` — verify PRD/UX/arch alignment
 - `actions/3-solutioning/rcode-generate-project-context` — generate project-context.md
 
-### 4 — Implementation (20)
+### 4 — Implementation (21)
 - `actions/4-implementation/rcode-dev-story` — execute a story (write tests + code)
 - `actions/4-implementation/rcode-review` — comprehensive code review
 - `actions/4-implementation/rcode-qa-generate-e2e-tests` — generate e2e test suite
@@ -84,6 +84,7 @@ Invoked by agents via the capabilities table in their SKILL.md. Organized by SDL
 - `actions/4-implementation/rcode-prove-it` — test-first development
 - `actions/4-implementation/rcode-source-truth` — cite official docs before writing framework code
 - `actions/4-implementation/rcode-trim` — code simplification
+- `actions/4-implementation/rcode-herdr-orchestration` — orchestrate parallel cld agents in herdr; single-shot fan-out OR long-running autonomous wave-based fix campaign with durable backlog + integration branch + heartbeat
 
 ---
 

package/rcode/skills/actions/1-analysis/rcode-document-project/SKILL.md

@@ -27,6 +27,12 @@ Analyze an existing codebase and produce documentation for both human and LLM co
 
 Follow the instructions in ./workflow.md.
 
+## When NOT to use this skill
+
+Do NOT use for writing net-new documentation from scratch (use a write-document prompt).
+Do NOT invoke when the user wants to document a single file or function — scope this skill
+to whole-codebase or whole-module brownfield analysis only.
+
 ## Output Format
 
 - Produces multi-file documentation: README summary, ARCHITECTURE.md, CONVENTIONS.md, project-context.md

package/rcode/skills/actions/3-solutioning/rcode-check-implementation-readiness/SKILL.md

@@ -28,6 +28,12 @@ Verify that PRD, UX designs, architecture decisions, and epics/stories are all a
 
 Follow the instructions in ./workflow.md.
 
+## When NOT to use this skill
+
+Do NOT use during active implementation — if work is already in progress, use
+`rcode-correct-course` instead. Do NOT invoke for a single-artifact review (e.g. "check
+this PRD"); scope this skill to cross-artifact alignment checks before a phase starts.
+
 ## Output Format
 
 - Produces an alignment report with checklist format

package/rcode/skills/actions/3-solutioning/rcode-create-architecture/steps/step-01-init.md

@@ -70,7 +70,7 @@ Try to discover the following:
 - Project Documentation (generally multiple documents might be found for this in the `{project_knowledge}` or `{project-root}/docs` folder.)
 - Project Context (`**/project-context.md`)
 
-<critical>Confirm what you have found with the user, along with asking if the user wants to provide anything else. Only after this confirmation will you proceed to follow the loading rules</critical>
+<critical>If auto mode is active (--auto flag or config.mode == "yolo"): skip user confirmation — log "Auto mode: proceeding with discovered documents: [list]" and continue directly to Loading Rules. Otherwise: confirm what you have found with the user, ask if they want to provide anything else, and only proceed after confirmation.</critical>
 
 **Loading Rules:**
 

package/rcode/skills/actions/3-solutioning/rcode-create-architecture/workflow.md

@@ -18,14 +18,26 @@ This uses **micro-file architecture** for disciplined execution:
 
 ---
 
+## AUTO MODE
+
+**If `--auto` was passed in ARGUMENTS OR `config.mode == "yolo"`:**
+- Skip all user-confirmation gates throughout the workflow.
+- In step-01-init: discover input documents automatically, proceed without asking the user to confirm or add files.
+- In all subsequent steps: choose the recommended option at every decision point without prompting.
+- Log each auto-selected choice inline so the output is auditable.
+- This flag persists for the entire workflow invocation (all steps see it).
+
+---
+
 ## INITIALIZATION
 
 ### Configuration Loading
 
-Load config from `{project-root}/.rcode/config.json` and resolve:
+Load config from `{project-root}/.rcode/config.yaml` and resolve:
 
 - `project_name`, `output_folder`, `planning_artifacts`, `user_name`
 - `communication_language`, `document_output_language`, `user_skill_level`
+- `mode` — if `yolo`, treat as `--auto` for this entire invocation
 - `date` as system-generated current datetime
 - ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
 

package/rcode/skills/actions/4-implementation/rcode-herdr-orchestration/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: rcode-herdr-orchestration
+description: Orchestrate parallel cld agents in herdr — fan-out or autonomous wave campaign.
+triggers:
+  # English — single-shot orchestration
+  - "orchestrate agents"
+  - "run agents in herdr"
+  - "parallel audit"
+  - "spin up agents"
+  - "use herdr to do"
+  - "split work across panes"
+  - "fan out work in herdr"
+  - "multi-agent in herdr"
+  # English — autonomous campaign mode
+  - "autonomous fix campaign"
+  - "auto mode"
+  - "auto loop"
+  - "run waves of agents"
+  - "dispatch waves"
+  - "100+ commits"
+  - "keep working until done"
+  - "complete site audit and fix"
+  # Roman Urdu / Hindi
+  - "herdr mein chalao"
+  - "parallel agents lagao"
+  - "panes mein todo"
+  - "ek saath kai agents"
+  - "auto mode chalao"
+  - "waves mein fix karo"
+  - "campaign chalao"
+  # Arabic native
+  - "شغّل وكلاء بالتوازي"
+  - "وزّع العمل على عدة وكلاء"
+  - "استخدم herdr"
+  - "حملة إصلاح تلقائية"
+  - "موجات من الوكلاء"
+  - "وضع تلقائي"
+user-invocable: true
+---
+
+# rcode-herdr-orchestration
+
+## Overview
+
+Run many Claude agents in parallel inside `herdr` (terminal agent multiplexer), monitor
+them, and merge their work back safely.
+
+Two modes: **single-shot** (bounded fan-out, one sitting, merge back done) and
+**autonomous campaign** (100+ commits across waves with durable backlog and integration
+branch). Both share the same golden rules and pane mechanics. See `references.md` for
+the full campaign workflow and deep-dive rules.
+
+**Do NOT use for a single quick task** — invoke the work directly without herdr for that.
+Orchestration overhead (worktrees, panes, monitoring) only pays off across multiple
+independent agents.
+
+---
+
+## Golden rules (NON-NEGOTIABLE — apply to BOTH modes)
+
+1. **Use `cld`, never `claude`.** `cld` is the alias for
+   `claude --dangerously-skip-permissions`. Send it via `herdr pane send-text` + `send-keys Enter`
+   so the shell alias resolves. Do NOT use `herdr pane run` for `cld`.
+2. **If you must invoke `claude` directly** (alias unavailable): pass
+   `--dangerously-skip-permissions` AND run in **interactive mode** (no `-p`/`--print`).
+   A non-interactive `claude -p` call is invisible to herdr.
+3. **One git worktree per agent.** Never share a working tree between orchestrated agents.
+4. **Work locally, commit locally. Never push to origin or deploy** during an
+   orchestration run unless the user explicitly authorizes it afterward.
+5. **The orchestrator NEVER claims a wakeup it cannot fire.** `ScheduleWakeup` only
+   fires when `/loop` is active — clarify the heartbeat path with the user first.
+6. **Ignore stray buffer text in panes.** Leftover user text at an idle prompt is NOT
+   an agent question — do not Enter it.
+
+---
+
+## herdr CLI reference
+
+```bash
+herdr workspace list
+herdr tab list --workspace <wid>
+herdr tab create --workspace <wid> --label "X" --cwd PATH --focus
+herdr tab close <tab_id>               # IDs RENUMBER after a close — re-list
+herdr pane list --workspace <wid>      # pane_id, label, agent_status
+herdr pane split <pane_id> --direction right|down --cwd PATH --no-focus
+herdr pane rename <pane_id> "Label"
+herdr pane read <pane_id> --source visible|recent --lines N --format text
+herdr pane send-text <pane_id> "text"  # types text (no newline)
+herdr pane send-keys <pane_id> Enter|C-c|BSpace
+```
+
+`agent_status`: `working`, `blocked` (waiting on question/permission), `idle`/`done`, `unknown`.
+
+---
+
+## MODE 1 — Single-shot orchestration
+
+Use when work is bounded and can finish in one batch.
+
+**Steps:**
+1. Decide N areas (4 per tab default — 2×2 grid). Each area = one agent = one worktree = one branch.
+2. Create worktrees: `git worktree add ../sm-worktrees/$A -b audit-$A master` for each area.
+3. Create tab + split panes, one per worktree.
+4. Launch `cld` in every pane (`send-text "cld"` + `send-keys Enter`). Sleep 7s after.
+5. Send each agent a self-contained prompt with worktree path, branch, and task.
+   - Audits: diagnose-only first. Fixes: incremental edits, no rewrites, commit each fix.
+6. Monitor: `herdr pane list` every ~2 min. Unblock stuck panes via `send-keys`/`send-text`.
+7. Merge back: `git add -f .planning/audits/*.md && git commit` inside each worktree, then
+   `git merge <branch> --no-edit` from main repo. Verify `pnpm tsc --noEmit` count unchanged.
+8. Cleanup: `git worktree remove --force` each tree. Close herdr tab (re-list IDs first).
+
+---
+
+## MODE 2 — Autonomous campaign (summary)
+
+Use for `100+ commits`, `keep working until done`, `complete site audit and fix`.
+Full Phase 0-3 protocol, integration-branch rules, wave cadence, and anti-patterns are
+in **`references.md`** (sibling file). Key constraints:
+
+- Maintain one `campaign-integration` branch; sub-agents fork from it, never master.
+- Wave size: 3-5 agents, 10-15 min per wave. ScheduleWakeup ends EVERY turn.
+- Phase 3: show user the full diff + ask explicitly how to land (PR / merge / squash / leave).
+- Never push to origin master without an explicit yes — per campaign, not per session.
+
+---
+
+## When NOT to use this skill
+
+- A single, quick, one-agent task — just run it directly on the main tree, no herdr.
+- Anything the user wants to step through interactively — orchestration is for parallel,
+  hands-off batches.
+
+---
+
+## Output Format
+
+**Single-shot:** one worktree per agent on `audit-<area>` branch, per-area audit doc at
+`.planning/audits/AUDIT-<area>.md` (committed via `git add -f`), work merged back to
+calling branch with commits preserved.
+
+**Campaign:** durable backlog at `.planning/campaign/BACKLOG.md`, state log at
+`.planning/campaign/STATE.md`, one long-lived `campaign-integration` branch accumulating
+wave merges — master NOT touched until Phase 3 with explicit user consent.
+
+In both modes, orchestrator chat output is concise wave/pane status only.
+
+---
+
+## Examples
+
+**Happy path — single-shot 4-area parallel audit:**
+User: "Fan out a security audit across the auth, API, DB, and frontend areas in parallel."
+Orchestrator creates 4 worktrees on branches `audit-auth`, `audit-api`, `audit-db`,
+`audit-frontend`. Sends each agent: "You are in `../sm-worktrees/auth` on branch
+`audit-auth`. Diagnose security issues — report findings to `.planning/audits/AUDIT-auth.md`,
+no code changes yet." Monitors until all idle, merges branches, confirms TSC count stable.
+
+**Edge case — sub-agent goes silent past wave duration:**
+If `herdr pane list` shows a pane stuck `working` past 25 min: `herdr pane read <id>` —
+usually an AskUserQuestion blocking. Pick the safe option via `send-keys`. If still stuck
+after another 10 min, `C-c` the pane, note the partial work, revert the branch, and
+re-dispatch the item in the next wave.
+
+**Negative example — when NOT to invoke this skill:**
+User: "Fix the typo in README line 4." This is a one-line edit. Invoke herdr orchestration
+for this is overkill — just edit the file directly on the current branch.

package/rcode/skills/actions/4-implementation/rcode-herdr-orchestration/references.md

@@ -0,0 +1,136 @@
+# rcode-herdr-orchestration — References
+
+Overflow content split from SKILL.md per the 200-line budget. Read SKILL.md first.
+
+---
+
+## MODE 2 — Full campaign workflow
+
+### Extra hard rules (rules 7-11, in addition to the 6 golden rules in SKILL.md)
+
+7. **Durable backlog.** Commit `.planning/campaign/BACKLOG.md` at campaign start so the
+   campaign survives auto-compact. Don't keep the work list in conversation memory only.
+8. **Campaign integration branch.** Maintain ONE long-lived branch (default
+   `campaign-integration`). Sub-agents always fork from it — never directly from master.
+   Wave-N merges land on the integration branch; master only sees the campaign via a
+   single explicit merge at Phase 3. See `rules/integration-branch.md`.
+9. **Merge into the integration branch as you go.** Wave-N branches merge into the
+   integration branch BEFORE wave-(N+1) dispatches.
+10. **TSC stays at integration baseline.** Capture `pnpm tsc --noEmit | grep -c "error TS"`
+    at campaign start. Any wave that breaks the baseline is reverted before the next wave.
+11. **No push without explicit user consent — per campaign, not per session.** Per-change
+    consents earlier in the session do NOT extend.
+
+### Wave cadence
+
+- **Wave size**: 3-5 sub-agents. More than 5 = harder to merge, more conflicts.
+- **Wave duration**: 10-15 min target. If a wave runs past 25 min, peek for stuck agents.
+- **Heartbeat**: orchestrator wakes every 10-15 min. Cache-window math: 270s, 720s, 1200s.
+
+### Backlog pipeline
+
+```
+.planning/audits/AUDIT-*.md  ──┐
+grep TODO/FIXME/HACK         ──┼──▶  .planning/campaign/BACKLOG.md  ──▶  wave-1, wave-2, …
+existing pending P1/P2 items ──┘                    ▲
+                                                    │
+                              wave-N findings append back ↑
+```
+
+### Phase 0 — Initialize (one-time)
+
+1. Confirm baseline: `git branch --show-current` = master, clean tree, capture TSC count.
+2. Create the campaign integration branch:
+   ```bash
+   git checkout -b campaign-integration master
+   ```
+3. Mine the backlog into `.planning/campaign/BACKLOG.md` from audit docs +
+   `grep -rn "TODO\|FIXME\|HACK\|XXX"`. Commit it on the integration branch.
+4. Start the bash heartbeat (`bash templates/heartbeat.sh &`).
+
+### Phase 1 — Wave dispatch
+
+1. Read next 3-5 items from BACKLOG.md → move to STATE.md "In flight (wave N)".
+2. Create worktree + branch **forked from integration branch**:
+   ```bash
+   git worktree add ../sm-worktrees/camp-<area> -b campaign-<area> campaign-integration
+   ```
+3. Create/reuse herdr tab, split panes, launch `cld --model sonnet` in each.
+4. Send each agent a wave prompt (use `templates/wave-prompt.md`):
+   - Worktree path + branch + parent = `campaign-integration`
+   - Specific backlog item + audit doc reference
+   - "Do not push. Do not merge. Do not touch master or the integration branch directly."
+5. **End the turn with ScheduleWakeup. Always.**
+
+### Phase 2 — Heartbeat loop (every 10-15 min)
+
+1. `herdr pane list` — count panes in `working` vs `idle`/`done`.
+2. For every branch with new commits: merge into the integration branch (NOT master).
+3. After each merge: `pnpm tsc --noEmit` regression check. Bumped count = revert from integration.
+4. Do NOT push to origin master. Do NOT touch master.
+5. Move shipped items from STATE.md "in flight" → "shipped".
+6. If BACKLOG.md still has items → dispatch wave-(N+1). Else → Phase 3.
+7. **End the turn with ScheduleWakeup** while any pane is working OR BACKLOG.md is non-empty.
+
+### Phase 3 — Drain & Land
+
+1. When BACKLOG.md empty AND all panes idle: kill heartbeat bash loop.
+2. Show user the full diff of integration branch vs master.
+3. Ask explicitly: "Campaign work is on `campaign-integration` (N commits ahead of
+   master). How do you want to land it?" Options:
+   - PR: `gh pr create --base master --head campaign-integration`
+   - Merge to master locally (explicit yes required)
+   - Squash-merge for one tidy commit
+   - Leave the integration branch for human review
+4. Never `git push origin master` without an explicit yes.
+
+---
+
+## Key files (campaign mode)
+
+| File | Purpose |
+|------|---------|
+| `.planning/campaign/BACKLOG.md` | Durable work list. Committed at campaign start. |
+| `.planning/campaign/STATE.md` | Waves shipped, in-flight, TSC drift per wave. |
+| `.planning/campaign/HEARTBEAT` | `touch`ed by bash loop every 30s — mtime proves orchestrator alive. |
+| `templates/BACKLOG-template.md` | Starter for the backlog file. |
+| `templates/STATE-template.md` | Starter for the state file. |
+| `templates/heartbeat.sh` | Background heartbeat script template. |
+| `templates/wave-prompt.md` | Per-agent prompt boilerplate. |
+
+---
+
+## Rules deep-dive
+
+- **`rules/integration-branch.md`** ← READ FIRST for campaign mode
+- `rules/orchestrator-rhythm.md` — heartbeat / ScheduleWakeup decision tree
+- `rules/wave-design.md` — wave sizing
+- `rules/backlog-building.md` — audit mining, TODO scan, dedup
+- `rules/merge-strategy.md` — TSC gate
+- `rules/composition-with-herdr.md` — how campaign mode layers on single-shot mechanics
+
+---
+
+## Gotchas (field-tested, both modes)
+
+- **herdr renumbers tab IDs on close.** Always re-list before the next close.
+- **Parallel agents tangle branches** if they share a working tree — one worktree per agent always.
+- **`.planning/` is often gitignored** — audit docs need `git add -f`.
+- **`make brain`'s `git push` is `|| true`** — it silently fails on a diverged branch.
+  Never assume a deploy shipped your local commits without checking.
+- **Diverged local vs origin master** is the #1 risk after a long parallel run. Do NOT
+  auto-resolve conflicts unattended — surface to the user.
+- Capture extra `sleep` after launching `cld` — it takes ~5-7s to boot.
+
+---
+
+## Anti-patterns (campaign mode)
+
+| Failure | Prevented by |
+|---|---|
+| Cross-wave merge conflicts pile up | Integration branch — every wave inherits prior waves' work |
+| Orchestrator goes silent mid-campaign | Hard rule 5 + heartbeat template |
+| Lost backlog after auto-compact | Phase 0 commits BACKLOG.md on integration branch |
+| Silent push to master without consent | Hard rule 11 + Phase 3 ask-before-land |
+| TSC drift compounds | Phase 2 regression check + revert from integration branch |
+| Integration branch never lands | Phase 3 mandatory "how to land it" question |

package/rcode/skills/actions/4-implementation/rcode-herdr-orchestration/rules/backlog-building.md

@@ -0,0 +1,113 @@
+# Backlog Building
+
+How to build a durable, prioritized, committed campaign backlog.
+
+## Purpose
+The backlog is the campaign's spine. Without a durable file-on-disk backlog, an auto-compact erases the work plan and the campaign collapses. This rule encodes the build + maintain pipeline.
+
+## Rules
+
+### Source priority (highest signal first)
+
+1. **Existing audit docs** at `.planning/audits/AUDIT-*.md` — these are human-curated and already prioritized P1/P2. Most reliable source.
+2. **`/audit-fix` skill outputs** if available — Rihal projects often have these pre-generated.
+3. **Pending items** in the project's CHANGELOG / ROADMAP / `.planning/state.md`.
+4. **Code-level TODOs**: `grep -rn -E "// *(TODO|FIXME|HACK|XXX)[: ]"` in `server/` + `src/` — lowest signal, often stale.
+5. **CI failures / open GitHub issues** — only if explicit user request.
+
+### Backlog format
+
+```markdown
+# CAMPAIGN BACKLOG
+Generated: <ISO timestamp>
+Baseline TSC errors: <count>
+
+## Open items
+- [ ] **<area>** (P<priority>): <one-line description>. Source: <audit-doc>:<line>
+- [ ] **<area>** (P<priority>): …
+
+## In flight (wave N)
+- [~] **<area>**: assigned to pane <pane-id>, branch <branch>, started <time>
+
+## Shipped
+- [x] **<area>**: commit <sha>, wave <N>, finished <time>
+```
+
+### Dedup rules
+Before adding an item to the backlog, check:
+- Is there an existing master commit covering it? `git log --oneline | grep -i <keyword>`
+- Is there an in-flight branch covering it? `git branch | grep -i <keyword>`
+- Is it identical to another backlog item with a different file:line? Merge them.
+
+### Maintenance during the campaign
+- Every wave merge: move items from "In flight" → "Shipped" with the commit SHA.
+- Every wave dispatch: move items from "Open" → "In flight" with pane + branch.
+- New findings from a sub-agent's audit phase: append to "Open" with source attribution.
+- Item rejected by a wave-agent (out of scope, blocked, etc.): mark `[skip]` with reason — do not delete.
+
+### Commit the backlog
+```bash
+git add -f .planning/campaign/BACKLOG.md .planning/campaign/STATE.md
+git commit -m "chore(campaign): backlog snapshot at wave <N>"
+```
+The `-f` is required if `.planning/` is gitignored (common in Rihal projects).
+
+## Examples
+
+### Building backlog from audit docs
+
+```bash
+{
+  echo "# CAMPAIGN BACKLOG"
+  echo "Generated: $(date -u +%FT%TZ)"
+  echo "Baseline TSC: $(pnpm tsc --noEmit 2>&1 | grep -c 'error TS')"
+  echo
+  echo "## Open items"
+  for f in .planning/audits/AUDIT-*.md; do
+    area=$(basename "$f" .md | sed 's/^AUDIT-//')
+    pending=$(grep -nE "(⏳|^- \[ \]|^### P[12])" "$f" 2>/dev/null | head -5)
+    [ -n "$pending" ] && echo "$pending" | sed "s|^|- [ ] **$area** (from $f) |"
+  done
+} > .planning/campaign/BACKLOG.md
+```
+
+### State transition
+
+```diff
+- [ ] **call-update-flow** (P1): add Sentry capture on EventBus handler errors. Source: AUDIT-call-update-flow.md:142
++ [~] **call-update-flow**: assigned to pane w65..-8, branch campaign-call-update-flow, started 2026-05-26T14:32Z
+```
+later:
+```diff
+- [~] **call-update-flow**: assigned to pane w65..-8, branch campaign-call-update-flow, started 2026-05-26T14:32Z
++ [x] **call-update-flow**: commit 40b908d9, wave 2, finished 2026-05-26T14:51Z
+```
+
+## Anti-Patterns
+
+### Backlog only in conversation memory
+
+**Problem**: Auto-compact wipes it; the next turn can't resume.
+**Instead**: File on disk, committed.
+
+### Massive backlog dumped once
+
+**Problem**: A 200-item backlog overwhelms wave selection — orchestrator picks badly because it can't see the whole context.
+**Instead**: Build in chunks. Top 20-30 items as "Open"; lower-priority items as a footnote or separate file.
+
+### Mining TODOs from test files
+
+**Problem**: Test TODOs are often "this case is unimplemented" — they're test scaffolding, not real bugs.
+**Instead**: `grep ... | grep -v "\.test\.\|\.spec\."` to filter them out.
+
+### Skipping dedup
+
+**Problem**: Same bug fixed 3 times by 3 waves because none knew the others were working on it.
+**Instead**: Always check master log + in-flight branches before adding.
+
+## Related
+- `wave-design.md` — backlog drives wave composition
+- `composition-with-herdr.md` — STATE.md ties to herdr pane labels
+
+## Changelog
+- 2026-05-26: Initial.

package/rcode/skills/actions/4-implementation/rcode-herdr-orchestration/rules/composition-with-herdr.md

@@ -0,0 +1,85 @@
+# Composition with herdr-orchestration
+
+This skill is a layer ON TOP OF `herdr-orchestration`. It does not replace it.
+
+## Purpose
+Make the boundary explicit so the orchestrator never reinvents herdr mechanics inside this skill.
+
+## Rules
+
+### Always read herdr-orchestration first
+At the start of any campaign session, load the `herdr-orchestration` skill BEFORE dispatching the first wave. Its golden rules (use `cld` not `claude`, worktree per agent, no push during run, interactive mode required) apply to every wave.
+
+### Division of responsibility
+
+| Concern | Skill that owns it |
+|---|---|
+| Worktree creation | herdr-orchestration |
+| Pane splitting + naming | herdr-orchestration |
+| `cld --model sonnet` launch via shell alias | herdr-orchestration |
+| Sending prompts via `send-text` + `send-keys` | herdr-orchestration |
+| Polling `herdr pane list` for status | herdr-orchestration |
+| Reading stale buffer text, ignoring stray "merge to master" | herdr-orchestration |
+| Conflict resolution (superset rule) | herdr-orchestration |
+| **Wave cadence (when to dispatch / merge / pause)** | **this skill** |
+| **Backlog management (BACKLOG.md, STATE.md)** | **this skill** |
+| **Heartbeat (ScheduleWakeup + bash file)** | **this skill** |
+| **TSC baseline gate** | **this skill** |
+| **Push-to-origin policy** | **this skill** |
+
+### Pane status mapping → campaign action
+
+| herdr pane status | Campaign action |
+|---|---|
+| `working` | Leave alone. Re-check on next heartbeat. |
+| `blocked` | Read the pane, answer the menu (per herdr-orchestration), continue. |
+| `idle` with commits ahead of master | Merge candidate — try to merge this wave. |
+| `idle` with 0 commits | Either still warming up or wave failed — peek and decide. |
+| `done` | Same as idle-with-commits. Merge if any, then clean up. |
+| `unknown` | Recently created; wait one heartbeat. |
+
+### Worktree path convention
+Use `../sm-worktrees/camp-<area>` (project-relative `../sm-worktrees`). This matches the convention in herdr-orchestration examples and keeps a single shared place for all campaign worktrees.
+
+### Branch naming convention
+- Wave fix branches: `campaign-<area>` (e.g. `campaign-crm-pipeline`)
+- Rebase pass branches: `rebase-<area>`
+- Post-merge cleanup: delete the branch after push lands
+
+## Examples
+
+### Correct skill load order (start of session)
+
+```
+1. Load herdr-orchestration (read SKILL.md, understand golden rules)
+2. Load autonomous-fix-campaign (this skill — wave cadence + backlog)
+3. Apply both: herdr mechanics for the per-wave dispatch, this skill for the campaign loop
+```
+
+### Correct cld invocation (delegated to herdr-orchestration)
+
+```
+herdr pane send-text $P "cld --model sonnet"
+herdr pane send-keys $P Enter
+```
+NOT `claude -p` (would be invisible to herdr; see herdr-orchestration golden rule 2).
+
+## Anti-Patterns
+
+### Reimplementing herdr mechanics inside a campaign prompt
+
+**Problem**: Drift between this skill and the upstream herdr-orchestration rules.
+**Instead**: Reference herdr-orchestration; do not duplicate.
+
+### Skipping the herdr golden rules because "the campaign is special"
+
+**Problem**: Campaigns still need worktree isolation, still need `cld` alias, still need to ignore stray buffer text.
+**Instead**: Treat herdr-orchestration's rules as inviolable.
+
+## Related
+- `~/.claude/skills/herdr-orchestration/SKILL.md` (upstream skill)
+- `orchestrator-rhythm.md` (this skill — campaign cadence)
+- `merge-strategy.md` (this skill — conflict resolution delegates to herdr)
+
+## Changelog
+- 2026-05-26: Initial.