@hanzlaa/rcode 3.6.16 → 4.1.0

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.

package/rcode/skills/actions/4-implementation/rcode-herdr-orchestration/rules/integration-branch.md

@@ -0,0 +1,191 @@
+# Campaign Integration Branch
+
+The orchestrator maintains its own long-lived parent branch for the campaign. Sub-agents fork from it, merges land on it, master stays untouched until the user explicitly lands the whole campaign.
+
+## Purpose
+
+A prior campaign session (2026-05-26) revealed the failure mode this rule prevents:
+
+- Sub-agents in Wave-1 forked directly from `master`. They committed.
+- Wave-1 merges landed on `master`.
+- Wave-2 sub-agents forked from `master` again — at a HEAD that already had Wave-1's merges.
+- **But the worktrees were created with `git worktree add ... master` at slightly different times, and some Wave-1 work was still in flight on its own branches.**
+- Wave-2 branches overlapped with Wave-1 branches' files → cross-wave merge conflicts.
+- The orchestrator spent multiple ticks resolving those conflicts instead of shipping new work.
+- Some branches couldn't be auto-merged at all and got queued for a rebase agent, who introduced TSC regressions of its own.
+
+The fix: **one campaign integration branch**, serially advanced. Sub-agents always fork from the integration branch's CURRENT TIP (not a snapshot, not master). When a wave's merges land on the integration branch, the next wave's sub-agents inherit them automatically.
+
+## Rules
+
+### Naming
+
+| Branch | When to use |
+|---|---|
+| `campaign-integration` | Default for unnamed campaigns. |
+| `campaign-<topic>` | When the campaign has a coherent theme (e.g. `campaign-crm-cleanup`, `campaign-q2-tech-debt`). |
+| `campaign-<topic>-<wave>` | Don't use. The integration branch is one branch across all waves. Per-wave naming defeats the purpose. |
+
+Sub-agent branches stay named `campaign-<area>` and live as short-lived feature branches that merge into the integration branch.
+
+### Lifecycle
+
+```
+master                              ┐
+  ├─ campaign-integration (branch)  │  <-- orchestrator stays here
+  │   ├─ campaign-area-1            │  <-- sub-agent Wave 1
+  │   ├─ campaign-area-2            │
+  │   ├─ campaign-area-3            │
+  │   │
+  │   │   <-- Wave 1 merged into campaign-integration
+  │   │
+  │   ├─ campaign-area-4            │  <-- Wave 2 forks from updated integration
+  │   ├─ campaign-area-5            │
+  │   │
+  │   │   <-- Wave 2 merged
+  │   │
+  │   └─ (continues...)             │
+  │                                 │
+  └─ (Phase 3: integration → master)│
+```
+
+### Pre-flight (Phase 0)
+
+```bash
+git checkout master && git pull origin master   # start fresh
+git checkout -b campaign-integration master
+git push -u origin campaign-integration         # OPTIONAL — only the integration branch may be auto-pushed
+```
+
+The integration branch can be auto-pushed because:
+- It is **not master** — pushing it does not affect production.
+- It enables PR-style review via GitHub.
+- It survives orchestrator crashes (work lives on origin).
+
+If the user says "no push of anything ever" — respect that. Don't push the integration branch either.
+
+### Sub-agent worktree creation
+
+```bash
+# WRONG — direct fork from master, cross-wave conflict risk
+git worktree add ../sm-worktrees/camp-<area> -b campaign-<area> master
+
+# RIGHT — fork from integration branch
+git worktree add ../sm-worktrees/camp-<area> -b campaign-<area> campaign-integration
+```
+
+### Merging during a wave (Phase 2)
+
+```bash
+# orchestrator's main worktree is checked out on campaign-integration
+git merge campaign-<area> --no-edit
+NEW_TSC=$(pnpm tsc --noEmit 2>&1 | grep -c "error TS")
+if [ "$NEW_TSC" -gt "$INTEGRATION_BASELINE_TSC" ]; then
+  git reset --hard HEAD~1   # back out of integration branch, NOT master
+fi
+```
+
+Master never enters the picture during merges. The TSC gate compares against the integration branch's recorded baseline, not master's.
+
+### Sync from master during long campaigns
+
+If the campaign runs for hours and other work lands on master from outside, periodically pull master into the integration branch:
+
+```bash
+# orchestrator on campaign-integration
+git fetch origin
+git merge origin/master --no-edit   # fast-forward when possible, conflict-resolve when not
+```
+
+Do this between waves, NEVER mid-wave (would disrupt in-flight sub-agents whose branches were forked from the older integration tip).
+
+### Landing (Phase 3)
+
+When BACKLOG.md is empty and all sub-agent branches have merged into the integration branch:
+
+```bash
+git checkout campaign-integration
+git diff master..campaign-integration --stat   # show user the change set
+git log master..campaign-integration --oneline  # show user the commit list
+```
+
+Then **ask the user**:
+
+```
+Campaign-integration is N commits ahead of master.
+How do you want to land it?
+  (a) Open a PR: gh pr create --base master --head campaign-integration
+  (b) Merge to master locally (--no-ff for a clean merge commit)
+  (c) Squash-merge to master (one tidy commit, history compressed)
+  (d) Leave campaign-integration as-is — I'll review later
+```
+
+Do NOT default to any of these. Wait for the user's answer.
+
+## Examples
+
+### Three-wave campaign with integration branch
+
+```
+T+0:    git checkout -b campaign-integration master    # Phase 0
+T+1:    wave 1: 4 sub-agents fork from campaign-integration
+T+15m:  wave 1 merges land on campaign-integration (NOT master)
+T+15m:  wave 2: 4 sub-agents fork from updated campaign-integration
+                ↑ inherits wave 1's work automatically
+T+30m:  wave 2 merges land on campaign-integration
+T+30m:  wave 3: 4 sub-agents fork from updated campaign-integration
+T+45m:  wave 3 merges land
+T+45m:  BACKLOG empty. Ask user how to land. (PR / merge / squash / leave)
+```
+
+Cross-wave conflicts disappear because every sub-agent sees the previous waves' merged work.
+
+### Sync from master mid-campaign (rare)
+
+```
+T+0h:    Start campaign-integration from master.
+T+2h:    Wave 1, 2 done on integration branch.
+T+2h:    Notice another team merged "fix(auth): X" to master.
+T+2h:    Between waves: orchestrator on campaign-integration runs
+         `git merge origin/master --no-edit` → fast-forward succeeds.
+T+2h:    Wave 3 forks from now-up-to-date integration branch.
+```
+
+## Anti-Patterns
+
+### Forking sub-agents from master directly
+
+**Problem**: Cross-wave conflicts pile up — sibling branches stomp on the same files because they both fork from the same parent without seeing each other's work.
+**Instead**: Sub-agents always fork from `campaign-integration`.
+
+### Treating the integration branch as just-another-branch and merging it to master mid-campaign
+
+**Problem**: Defeats the isolation. If you ship integration → master on every wave, you're back to the old direct-on-master pattern.
+**Instead**: Merge integration → master only once, at Phase 3, with explicit user consent.
+
+### Per-wave integration branches (`campaign-wave1-integration`, `campaign-wave2-integration`)
+
+**Problem**: Now you have to merge the wave integrations together at the end — adds a layer of merge work for no benefit. The whole point of integration is one durable line.
+**Instead**: One integration branch, serially advanced across all waves.
+
+### Skipping the Phase-3 "how do you want to land it" question
+
+**Problem**: Auto-merging integration → master at campaign end repeats the no-consent-push mistake at the local level.
+**Instead**: Always ask. Present PR / merge / squash / leave as explicit options.
+
+### Pushing campaign-integration without checking first
+
+**Problem**: User may have a "no push" preference that covers ALL refs, not just master.
+**Instead**: For the very first push of the integration branch, ask once. Subsequent pushes of the same branch can use that answer.
+
+## Related
+
+- `orchestrator-rhythm.md` — heartbeat continues while integration branch has open waves
+- `wave-design.md` — wave size still 3-5; integration branch doesn't change wave structure
+- `merge-strategy.md` — TSC gate is now against integration baseline, not master
+- `backlog-building.md` — BACKLOG and STATE files live on the integration branch
+- `composition-with-herdr.md` — herdr panes still own per-sub-agent worktrees; orchestrator owns the integration branch's main worktree
+
+## Changelog
+
+- 2026-05-26: Initial. Codified from the session that revealed cross-wave conflict explosions — the orchestrator was merging sub-agent branches into master directly, which forced parallel waves to fight over the same files. The integration-branch pattern eliminates that.

package/rcode/skills/actions/4-implementation/rcode-herdr-orchestration/rules/merge-strategy.md

@@ -0,0 +1,113 @@
+# Merge Strategy + TSC Gate
+
+How to merge wave output **into the campaign integration branch** without regressing. Master is never touched during the campaign — see `integration-branch.md`.
+
+## Purpose
+Parallel branches stomp on shared files. Merging requires a discipline: smallest first, TSC at every step, abort on first sign of trouble.
+
+## Rules
+
+### Order: smallest first
+Sort campaign branches by `git rev-list --count campaign-integration..<branch>` ascending. Merge the smallest one first.
+- Validates the merge flow on low-risk content.
+- Lets big branches rebase on top of small ones (less conflict per merge step).
+
+### TSC baseline gate
+Before any wave:
+```bash
+TSC_BASELINE=$(pnpm tsc --noEmit 2>&1 | grep -c "error TS")
+```
+After every merge:
+```bash
+TSC_NEW=$(pnpm tsc --noEmit 2>&1 | grep -c "error TS")
+if [ "$TSC_NEW" -gt "$TSC_BASELINE" ]; then
+  echo "Regression on this merge — reverting"
+  git reset --hard HEAD~1
+fi
+```
+**Never compound regressions across waves.**
+
+### Conflict resolution (delegates to herdr-orchestration)
+- Content conflicts: read both sides, keep the **more-complete superset side**, remove markers, syntax-check, stage, commit. (See herdr-orchestration rules.)
+- AA conflicts (add/add): peek both versions; if nearly identical, keep the canonical owner's version. The "owner" is the branch whose audit doc claimed the feature.
+- Unable to resolve safely: `git merge --abort`, mark the branch as `[needs-rebase]` in STATE.md, queue for next wave's resolution pass.
+
+### Push policy
+**During the campaign**: NEVER `git push origin campaign-integration`. The orchestrator is on the integration branch, not master.
+
+Pushing the integration branch itself is permitted (it's not master, it's isolated), but ASK ONCE at Phase 0:
+```bash
+git push -u origin campaign-integration 2>&1 | tail -3
+```
+Once that question is answered yes, the orchestrator may push the integration branch silently after each wave merge (helpful for PR previews and survival across restarts).
+
+**At Phase 3 only**: ask the user how to land the campaign. Options: PR, local merge to master, squash, or leave. Push master ONLY if they say "yes, merge and push to master" — explicit, never inferred. Never rely on `git push 2>/dev/null || true` patterns (they swallow auth failures and diverge silently).
+
+### Worktree cleanup
+After a branch is merged AND pushed:
+```bash
+git worktree remove --force ../sm-worktrees/camp-<area>
+git branch -d campaign-<area>
+```
+Frees space and keeps `git worktree list` readable.
+
+## Examples
+
+### Single-wave merge sweep
+
+```bash
+for B in $(git branch --format="%(refname:short)" | grep "^campaign-"); do
+  C=$(git rev-list --count master..$B 2>/dev/null)
+  [ "$C" = "0" ] && continue
+  echo "=== merging $B ($C commits) ==="
+  if git merge "$B" --no-edit 2>&1 | tail -5 | grep -q "CONFLICT"; then
+    echo "CONFLICT — aborting and queueing $B for resolution"
+    git merge --abort
+    echo "$B" >> .planning/campaign/NEEDS-REBASE.md
+  else
+    NEW=$(pnpm tsc --noEmit 2>&1 | grep -c "error TS")
+    if [ "$NEW" -gt "$TSC_BASELINE" ]; then
+      echo "TSC regressed ($TSC_BASELINE → $NEW) — reverting $B"
+      git reset --hard HEAD~1
+    fi
+  fi
+done
+git push origin campaign-integration
+```
+
+### Aborted merge handling
+
+When a conflict aborts:
+1. The branch stays alive — work isn't lost.
+2. The orchestrator's next turn dispatches a single rebase agent specifically for `NEEDS-REBASE.md` items.
+3. After rebase, retry merge.
+
+## Anti-Patterns
+
+### Auto-resolving conflicts with `-X theirs` or `-X ours`
+
+**Problem**: Strategy options pick a whole side, discarding the other branch's work without inspection.
+**Instead**: Read both sides; superset rule; if uncertain, abort and queue.
+
+### Merging while sub-agents are still active on overlapping files
+
+**Problem**: Sub-agent's later commit invalidates the merge you just made.
+**Instead**: Only merge branches whose status is `idle`/`done`. `working` branches stay queued.
+
+### Skipping the TSC check
+
+**Problem**: A type error silently lands on master, next wave forks from broken master, regression compounds.
+**Instead**: TSC after every merge. Revert immediately on regression.
+
+### Force-pushing master to "fix" a regression
+
+**Problem**: Destroys local work, can lose unpushed wave output.
+**Instead**: `git reset --hard HEAD~1` (no force-push) to undo a bad local merge before pushing.
+
+## Related
+- `orchestrator-rhythm.md` — merges happen during heartbeat ticks, not in the middle of dispatch
+- `wave-design.md` — wave composition determines conflict surface area
+- `composition-with-herdr.md` — herdr conflict-resolution superset rule
+
+## Changelog
+- 2026-05-26: Initial.

package/rcode/skills/actions/4-implementation/rcode-herdr-orchestration/rules/orchestrator-rhythm.md

@@ -0,0 +1,119 @@
+# Orchestrator Rhythm + Heartbeat
+
+The orchestrator must never go silent while sub-agents are still working.
+
+## Purpose
+A long-running campaign hits two failure modes that this rule prevents:
+1. **Silent assistant**: orchestrator answers a question, then never wakes back up — sub-agents finish, their commits sit unmerged.
+2. **Polling waste**: orchestrator wakes too often (every 60s), burning cache misses and tokens.
+
+## Rules
+
+### Heartbeat sources — IMPORTANT distinctions
+
+**`ScheduleWakeup` only fires when `/loop` mode is active.** Outside `/loop`, it is effectively a no-op — the harness will NOT re-invoke the assistant after the delay. The assistant must verify this before relying on it.
+
+**To actually auto-wake the orchestrator during a campaign, pick ONE of these:**
+
+1. **`/loop` mode (RECOMMENDED for long campaigns)** — User invokes `/loop` at the start of the campaign. After that, the assistant's `ScheduleWakeup` calls actually fire and re-invoke autonomously. The user can ctrl-c the loop at any time. This is the only built-in path to true autonomous re-invocation.
+
+2. **`/schedule` (cron-based)** — User creates a scheduled routine that pings the assistant at fixed intervals (e.g. every 15 min). Survives session restarts. Requires Anthropic's scheduled-agents feature. Best for multi-hour campaigns where the user closes the terminal.
+
+3. **Manual pinging** — User types `<<autonomous-loop-dynamic>>` (or just "check status") each time they want progress. Most honest default if `/loop` and `/schedule` aren't available. The orchestrator should be honest with the user that nothing auto-fires.
+
+4. **Bash heartbeat file** — Only an EXTERNAL liveness signal. `touch .planning/campaign/HEARTBEAT` every 30s in a background bash loop. **This does NOT wake the assistant** — it only tells an external watcher (you, a monitor script) that the campaign hasn't crashed. Useful as a secondary check, never as the primary heartbeat.
+
+### Be honest at campaign start
+
+At Phase 0, the orchestrator MUST clarify with the user which heartbeat path is in effect:
+
+```
+Heartbeat options for this campaign:
+  (a) Wrap the campaign in /loop so auto-wakeup actually fires (recommended for >1h work)
+  (b) Use /schedule to ping every N minutes (best for multi-hour, can-close-terminal campaigns)
+  (c) Manual mode — you ping me with "check status" whenever you want progress
+
+Which would you like? (a/b/c)
+```
+
+If the user picks (c) or skips: NEVER claim "Scheduling 20-min wakeup" in chat — that's a lie. Say instead: "12 agents detached and running. Ping me back with 'check status' when you want me to merge results."
+
+### Cadence by phase (only relevant under /loop or /schedule)
+
+| Phase | Heartbeat interval | Rationale |
+|---|---|---|
+| Phase 1 (wave just dispatched) | 720s | Sub-agents need 10-15 min to produce a commit |
+| Phase 2 (multiple waves running) | 540-720s | Slightly tighter — more chances to merge |
+| Phase 3 (draining last waves) | 270s | Sub-agents finishing close to each other; don't miss the last |
+| Idle (waiting on stuck pane) | 1200s | Sub-agent stuck — give it room or surface it |
+
+### Cadence by phase
+
+| Phase | Heartbeat interval | Rationale |
+|---|---|---|
+| Phase 1 (wave just dispatched) | 720s | Sub-agents need 10-15 min to produce a commit |
+| Phase 2 (multiple waves running) | 540-720s | Slightly tighter — more chances to merge |
+| Phase 3 (draining last waves) | 270s | Sub-agents finishing close to each other; don't miss the last |
+| Idle (waiting on stuck pane) | 1200s | Sub-agent stuck — give it room or surface it |
+
+### Stop conditions
+The heartbeat should stop ONLY when ALL three are true:
+- Every herdr pane is `idle` or `done`
+- Every campaign branch has been merged or marked rejected
+- `.planning/campaign/BACKLOG.md` is empty (or only contains items marked `[skip]`)
+
+## Examples
+
+### End-of-turn pattern (every campaign turn)
+
+```
+ScheduleWakeup(
+  delaySeconds=720,
+  reason="Wave-3 in flight; expect commits within 10 min then merge + dispatch wave-4",
+  prompt="<<autonomous-loop-dynamic>>"
+)
+```
+
+### Heartbeat bash template
+
+```bash
+#!/bin/bash
+# Run with: bash heartbeat.sh & echo $! > .planning/campaign/HEARTBEAT.pid
+HEARTBEAT=.planning/campaign/HEARTBEAT
+while true; do
+  date -u +%FT%TZ > "$HEARTBEAT"
+  sleep 30
+done
+```
+
+### Resuming after auto-compact
+
+If the orchestrator hits auto-compact mid-campaign, the first turn after must:
+1. Read `.planning/campaign/STATE.md` — figure out which wave is in flight.
+2. Run `herdr pane list` — find which panes are still working.
+3. Run `git branch | grep campaign-` + `git rev-list --count master..<each>` — find unmerged commits.
+4. Resume from Phase 2 of the workflow. Do not redispatch waves that are already in flight.
+
+## Anti-Patterns
+
+### Polling every 60s
+
+**Problem**: Wakeup interval shorter than 270s burns the Anthropic prompt cache repeatedly without any real work happening (sub-agents need minutes between commits).
+**Instead**: 540-720s default. Drop to 270s only when wrapping the last wave.
+
+### Bash `sleep && check` loop instead of ScheduleWakeup
+
+**Problem**: A blocking `sleep` in the assistant's own session ties up the conversation slot. The harness blocks long leading sleeps anyway.
+**Instead**: Use ScheduleWakeup. The bash heartbeat is for a SEPARATE background process, not for sleeping in the assistant's bash.
+
+### Ending a turn without scheduling wakeup while sub-agents are working
+
+**Problem**: Orchestrator returns control to user, user doesn't reply, sub-agents complete, no one merges, work rots.
+**Instead**: Last action of every campaign turn = `ScheduleWakeup`. Non-negotiable.
+
+## Related
+- `wave-design.md` — how wave size affects cadence
+- `composition-with-herdr.md` — herdr pane status states (`working`/`idle`/`done`) drive the loop exit
+
+## Changelog
+- 2026-05-26: Initial. Codified from session that shipped 200+ commits across ~12 waves.

package/rcode/skills/actions/4-implementation/rcode-herdr-orchestration/rules/wave-design.md

@@ -0,0 +1,100 @@
+# Wave Design
+
+How to size, split, and sequence campaign waves.
+
+## Purpose
+A campaign with too few agents underuses parallelism; too many causes merge conflicts and stalls. This rule encodes the sizing + sequencing that worked across long sessions.
+
+## Rules
+
+### Wave size
+- **Default: 4 agents per wave.** 2x2 herdr grid, easy to monitor visually.
+- **Minimum: 3.** Below 3 the orchestrator overhead isn't justified — just do the work directly.
+- **Maximum: 5.** Above 5 the merge stage becomes painful and TSC regressions compound across simultaneous changes.
+- **Sequential or concurrent waves?** Concurrent only if you have >8 distinct unrelated areas AND the merge bookkeeping is automated. Default is sequential: dispatch wave → merge → dispatch wave.
+
+### Wave scope rules
+Each agent in a wave must:
+- Own a **distinct audit area** (no two agents touching the same file domain).
+- Have a **clear stop signal** — fix 3-5 items, then return. No "keep going until I say stop".
+- Be **diagnose-then-fix**, not "rewrite this area".
+
+Cross-agent overlap risks (use these to vet wave composition):
+
+| If wave includes both… | Conflict risk | Mitigation |
+|---|---|---|
+| `lead-types` + `call-update-flow` | Both touch `leadService.js`/`callService.js` | Run sequentially, not concurrent |
+| `crm-pipeline` + `deals-pipeline-forecast` | Both touch deal stage logic | Split: one schema, one UI |
+| `email-system` + `email-sequences` | Both touch templating | Run sequentially |
+| `oauth-callbacks` + `integrations-developer` | Both touch OAuth handlers | Different providers per agent |
+
+### Item picking heuristics
+
+For each backlog item, score before assigning to a wave:
+
+| Criterion | Good for wave | Bad for wave |
+|---|---|---|
+| Blast radius | 1-5 files | 20+ files |
+| Has Prisma schema change | OK with migration | Not OK without migration |
+| Cross-cuts auth/RBAC | Solo agent | Avoid |
+| Touches WebSocket/realtime | Solo agent | Avoid |
+| Pure UI/CSS | Great parallel target | — |
+| Pure backend logic in one service | Great parallel target | — |
+
+### Wave duration
+- Target: 10-15 min per wave.
+- Past 25 min: peek at all panes, identify stuck agents, decide kill-or-wait.
+- Hard stop: 45 min. If a wave hasn't produced commits in 45 min, something is wrong — abort and re-dispatch.
+
+## Examples
+
+### Good wave-1 composition (from real session)
+```
+camp-crm-pipeline      ← AUDIT-CRM-pipeline P1/P2
+camp-crm-reporting     ← AUDIT-CRM-reporting P1/P2
+camp-deals-forecast    ← AUDIT-deals-pipeline-forecast P1
+camp-crm-activity      ← AUDIT-CRM-activity P1
+```
+Distinct services, distinct schema tables, no overlap.
+
+### Bad wave composition
+```
+camp-leads-A           ← leadService refactor
+camp-leads-B           ← leadService bug fixes
+camp-leads-C           ← leadService new feature
+camp-leads-D           ← leadService perf
+```
+All four touch `leadService.js` — merge will be a conflict bloodbath.
+
+### Phased waves (when items naturally depend on each other)
+```
+Wave 1: schema additions (lead-types schema, conversation schema)
+Wave 2: backend wiring on top of Wave 1's schema
+Wave 3: UI on top of Wave 2's API
+```
+Each phase merges before the next dispatches.
+
+## Anti-Patterns
+
+### Dispatching all backlog items at once
+
+**Problem**: 17 audit docs × 4 items = 68 simultaneous agents. Herdr can't manage that; merge stage becomes O(N²).
+**Instead**: 4 agents at a time, 17 waves over the campaign.
+
+### Reusing a worktree across waves
+
+**Problem**: Worktree state lingers — uncommitted files, stale `node_modules` symlink, half-merged branch.
+**Instead**: Fresh worktree per wave-agent. Tear down after merge.
+
+### Wave with no audit doc backing
+
+**Problem**: Agent invents work that wasn't asked for; commits get rejected.
+**Instead**: Every wave-agent prompt must reference a specific audit doc with specific item numbers.
+
+## Related
+- `backlog-building.md` — what feeds wave selection
+- `merge-strategy.md` — what happens after a wave completes
+- `composition-with-herdr.md` — herdr 2x2 pane grid
+
+## Changelog
+- 2026-05-26: Initial.

package/rcode/skills/actions/4-implementation/rcode-herdr-orchestration/templates/BACKLOG-template.md

@@ -0,0 +1,34 @@
+# CAMPAIGN BACKLOG
+
+Generated: <ISO-TIMESTAMP>
+Repo: <REPO-NAME>
+Baseline TSC errors: <COUNT>
+Source: `<AUDIT-DOC-DIRECTORY>` + `grep TODO/FIXME/HACK` in `<SCAN-DIRS>`
+
+## Open items
+
+<!-- One bullet per atomic, mergeable unit of work. Order = priority. -->
+
+- [ ] **<area-1>** (P1): <short description>. Source: `<audit-doc>:<line>`
+- [ ] **<area-1>** (P2): <short description>. Source: `<audit-doc>:<line>`
+- [ ] **<area-2>** (P1): <short description>. Source: `<audit-doc>:<line>`
+- [ ] **<area-2>** (P2): <short description>. Source: `<audit-doc>:<line>`
+- …
+
+## In flight
+
+<!-- Updated by orchestrator at every wave dispatch. -->
+
+- [~] **<area>**: assigned to pane <pane-id>, branch `<branch>`, started <iso-time>, wave <N>
+
+## Shipped
+
+<!-- Updated by orchestrator at every merge. -->
+
+- [x] **<area>**: commit `<sha>`, wave <N>, merged <iso-time>, push <iso-time>
+
+## Skipped / blocked
+
+<!-- Items the campaign deliberately did NOT do. Always include reason. -->
+
+- [skip] **<area>**: <reason>. Re-evaluate after <blocker> is resolved.