@hanzlaa/rcode 4.0.0 → 4.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "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/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/4-implementation/rcode-herdr-orchestration/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: rcode-herdr-orchestration
+description: Orchestrate parallel cld agents in herdr — single-shot fan-out OR long-running autonomous wave-based fix campaign with durable backlog and integration branch. Do NOT use for a single quick task; invoke directly without herdr for that.
+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.
+
+---
+
+## 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.