| name | dispatching-parallel-agent-wave |
| description | Orchestrates a wave of parallel closer agents to ship multiple independent gate specs / unit tests / fixes in one round. Use when the user asks to "fire up parallel agents" or when there's a batch of disjoint pickups (R-1/R-4 small-route specs, R-5 cron-engine vitests, G-x engine specs) and waiting for them sequentially would be slow. Encodes the patterns that worked in v3.4.x — disjoint-files invariant (no two agents touching the same route or workflow YAML), max 4-5 concurrent agents (5 worked; 8 had merge collisions), when to spawn a discovery agent first vs jump straight to closers, the standing-rule preamble that points agents at the existing skills, and the rebase-on-collision recovery pattern. |
Dispatching a parallel agent wave
When to use
The user asks for parallel work, or you've identified a batch of disjoint pickups. Typical triggers:
- "Fire up parallel agents on G-X / R-Y / etc."
- "Find more gaps and close them"
- After a wave lands, you want to spin the next round
- You see ≥3 unblocked items in
docs/E2E_GAPS.md or TODOS.md Tier 2
NOT this skill:
- A SINGLE focused task — just dispatch one agent (or do it yourself)
- A multi-day pickup that needs sequencing (e.g. G-20 tenant-isolation, G-9/G-10/G-11 trigger-endpoint trio) — those get ONE agent doing all of them sequentially. This skill is for genuinely-parallel work.
The disjoint-files invariant
Every agent in a wave must touch FILES no other agent touches. If two agents both edit routes/marketing.js or .github/workflows/deploy.yml concurrently, you'll get merge collisions or — worse — silently-bundled commits where one agent's git add -A sweeps in another agent's WIP.
Files that ALL gate-spec agents need to touch (collision-prone):
.github/workflows/deploy.yml (gate-spec list).github/workflows/coverage.yml (mirror)e2e/global-teardown.js (when a new entity needs sweeping)docs/E2E_GAPS.md (status markers)
Strategies for the workflow files:
- Tell each agent to
git pull --rebase if push rejects. Idempotent — the wire-in.sh script in .claude/skills/wiring-spec-into-gate/ is safe to re-run.
- Or have the parent agent batch the wire-ins as ONE follow-up commit after all closers report green. Pros: one clean commit. Cons: more orchestration overhead.
- Or split the wave — half the agents in batch 1 (with wire-ins), the rest in batch 2 after batch 1 lands.
Pattern from v3.4.3: 8 agents in a wave hit collisions on .github/workflows/* and e2e/global-teardown.js. Resulted in 515c316 — a "multi-agent collision commit" titled accounting-api gate (R-1) that secretly contained G-13 + G-15 work. Functional but messy. 5-agent waves stay clean; 8-agent waves bundle.
Cap: 4-5 concurrent agents
Empirical from v3.4.x:
| Wave size | Result |
|---|
| 3 agents (G-2/G-3/G-5) | Clean. All 3 had separate clean commits. |
| 4 agents (G-7/G-14/G-16 + something) | Clean if files are disjoint. |
| 5 agents (engine-fixes + cleanups + G-24 + R-2/R-3 + R-1 + R-5 = ran 8) | Worked but 515c316 bundle commit. |
| 8+ agents | Don't. Even with disjoint per-spec work, the workflow-file collisions get unmanageable. |
Default to 4 per wave. If you have more than 4 candidates, run sequential waves of 4.
Verify each issue before dispatch (added v3.4.8)
Run the verifying-issue-before-pickup skill on EACH issue in the planned batch BEFORE writing the agent prompts. 5 minutes of code-grep by the parent agent saves ~10 minutes × N agents of in-flight re-derivation.
The v3.4.8 4-agent wave shipped clean but 3 of 4 agents (#180, #398, #443) found doc-vs-reality drift — the implementation was already shipped; the actual gap was test-coverage. Each agent recovered, but the parent agent could have narrowed each prompt accordingly ("the route is already sanitized; write a contract spec, no impl needed") if it had grepped first. See .claude/skills/verifying-issue-before-pickup/SKILL.md for the grep checklist + the four common drift patterns (impl-shipped-spec-missing, impl-shipped-audit-missing, partial-fix-second-bug, framing-wrong).
When the verification surfaces drift on a row, rewrite the agent prompt to match the actual gap — don't pass the original issue framing through. The agent will re-derive faster from a tight prompt than from "the issue says X but actually Y."
Discovery-first vs jump-to-closers
Two patterns:
Pattern A: jump to closers — when the work is well-defined in docs/E2E_GAPS.md and you can pick disjoint items off the table without exploration. Used for G-2/G-3/G-5, G-7/G-14/G-16, G-9/G-10/G-11, R-1 trio. Default for most rounds — but always after running the verifying-issue-before-pickup skill on each item.
Pattern B: discovery agent first — when the user says "find more gaps and close them" or you've shipped the obvious E2E_GAPS items. Spawn ONE Explore agent (read-only) to survey:
docs/regression-coverage-backlog.md — closed-bug auditTODOS.md Tier 2 / Tier 3backend/cron/ cross-referenced with backend/test/cron/ (engines without unit tests)backend/lib/ and backend/middleware/ cross-referenced with backend/test/backend/routes/ cross-referenced with e2e/tests/*-api.spec.js (routes without specs)
Discovery agent returns a prioritized list (R-1 / R-4 / R-5 / etc.). You then pick 3-5 from its top recommendations as the closer batch.
This is what produced today's R-1 + R-2/R-3 + R-5 batch. ~5 minutes of discovery saved hours of agents re-discovering the same gaps independently.
The standing prompt preamble (now: skill references)
Pre-skills, every agent prompt had ~150 lines of "Standing rules: JWT key is userId not id, body strips id/createdAt/etc, header JSDoc, RUN_TAG, afterAll patterns, no Co-Authored-By, ..." This duplication cost tokens and drifted (different agents got slightly-different rules).
Post-skills: point agents at .claude/skills/<skill-name>/SKILL.md and let them read it on demand. The agent prompt becomes ~30 lines:
Use the writing-api-gate-spec skill (.claude/skills/writing-api-gate-spec/SKILL.md).
Target: backend/routes/<area>.js
Pattern: clone <reference-spec> per the skill's selection table.
Acceptance: standard 7-criterion set per the skill.
After spec is green, use the wiring-spec-into-gate skill (run
.claude/skills/wiring-spec-into-gate/wire-in.sh tests/<area>-api.spec.js).
If you find a contract drift while writing this, file as [regression]
issue per the filing-contract-drift-issue skill (when that exists);
for now just document in your final report.
Authority: full — run scripts, edit, commit, push to origin/main. If
push rejects (sibling agent collision), git pull --rebase and retry.
Final report: test count, runtime green-state, commit hash, any
contract drift findings.
The skills carry the rules. The prompt carries the task.
Per-agent prompt template
See AGENT_PROMPT_TEMPLATE.md for the full skeleton with placeholder slots.
Key elements every agent prompt should have:
- Skill reference — points at the relevant skill(s)
- Target — exact file paths to read first (the route file, the engine file, etc.)
- Pattern — which existing spec/test to clone (if not obvious from the skill)
- Acceptance criteria — the standard set + any task-specific extras
- Wire-in handoff — explicit pointer to the wire-in skill / script
- Coordinate-with-siblings note — names the other concurrent agents and which files they touch (so this agent can avoid)
- Progress-reporting block (mandatory) — every agent prompt MUST include the bash invocations from
reporting-agent-progress (start / milestone / commit / done events via .claude/skills/reporting-agent-progress/log.sh). Without this, the user can't see anything until each agent finishes — the wave is opaque. The block is canned in AGENT_PROMPT_TEMPLATE.md's "Progress reporting (mandatory)" section; copy it verbatim into each agent's prompt.
Tell the user to open /developer BEFORE launching the wave
Before invoking the Agent tool with run_in_background: true, the dispatching parent should output:
Open https://crm.globusdemos.com/developer (or your local frontend's /developer page) to watch the agents in real time. Newest entries first; color-coded by status. The page polls every 3s.
Do this once per wave dispatch, in the same response that fires the agents. The Live Agent Activity widget at the top of /developer surfaces every start / milestone / commit / done log line within 3 seconds. Without this prompt the user has no idea the page exists; without the agent-side log calls the page stays empty. Both halves of the contract are needed.
7. Authority statement — "full" / "no commits" / "no pushes"
8. Final-report shape — test count, runtime, commit hash, contract-drift findings
Coordinating wire-ins across the wave
Tell each agent: "Sibling agents (X, Y, Z) are also working on disjoint files. You'll all need to wire into deploy.yml + coverage.yml. If your git push rejects with non-fast-forward, git pull --rebase and retry. The wire-in.sh script is idempotent so a re-run after rebase is safe."
This solves 90% of collisions. The remaining 10% are the bundled-commit case (515c316) which is annoying but functional.
Cap iterations on heal loops
If a closer agent reports failures and asks to retry: cap at 5 iterations per failing spec. If still red after 5, the agent reports the blocker and stops — don't let it commit dubious workarounds. (This rule lives in local-heal-loop skill when that's authored; for now, repeat in the prompt.)
When to use background mode vs synchronous
- Background mode (
run_in_background: true): parallel waves, where you'll do other work while agents run. Get notified on completion.
- Synchronous: single agent whose output you need immediately to inform the next decision (e.g. a discovery agent before dispatching closers).
Mix both: discovery agent synchronous, then dispatch closers in background.
Final-report consolidation
When all agents in a wave return:
- Pull origin to sync (one or more pushed)
- Verify the gate is still green (
cd backend && npm test for vitest; spot-check a few new specs locally)
- Run
capturing-wave-findings skill over the combined per-agent finding lists — every drift / bug / missing route / shipped spec / standing-rule pattern lands in the right doc (TODOS.md, docs/E2E_GAPS.md, CHANGELOG.md) or a fresh GitHub issue. Do this BEFORE the doc bump so the captured items are reflected.
- Run
bumping-version-docs skill to capture the wave in CHANGELOG / README / CLAUDE.md / TODOS / E2E_GAPS at release time (only on version-bump waves)
- Recommend next wave's batch in your message back to user
Pitfalls
- Don't dispatch >5 agents at once. Workflow-file collisions get bundled-commit messy.
- Don't have two agents both touch the same route file. Even if they're "different specs", they'll fight over the route.js edits. Pick disjoint files.
- Don't skip the discovery step when the user says "find more gaps". Without discovery, you're guessing at gaps and may pick already-shipped items.
- Don't bundle the wire-in commits with the spec commits if you're worried about collisions. Sometimes a separate wire-in commit AFTER all spec commits land is cleaner.
- Don't forget to update TODOS.md after a wave. The next session's pickup depends on it.
When to bundle multiple fixes into ONE commit (added 2026-05-05)
A single closer agent often lands N fixes in M files. Two valid commit shapes:
1 commit covering all N fixes — right when:
- The fixes touch DIFFERENT files with no shared touchpoint
- They're being dispatched together as a coherent "fix this cluster" ask from the user
- You want one closing-comment SHA to point all N closed issues at
- The commit body can structure each fix into a per-issue section with "Closes #N" trailers
The 2026-05-05 #439/#440/#441/#448/#452/#456-partial cluster (4e116ad) hit this shape — 6 issues in 6 files, no overlap, single commit, GitHub auto-closed each via the trailers.
N separate commits (one per fix) — right when:
- The fixes touch the SAME file and you want clean
git bisect
- One fix is significantly more invasive than the others and the others can ship without it
- You want each issue's closing-comment SHA to point at its own targeted commit
Rule of thumb: N fixes in M files with no shared touchpoint → 1 commit. N fixes you want to bisect-isolate → N commits.
The autonomous bug-fix-cluster pattern (when the user says "fix these issues" with a list of 5+) is shape 1 by default: pre-grep each candidate first (catches Pattern A drift in 30s/issue, often more than half qualify per the v3.4.8 → v3.4.11 arc), cluster the genuine fixes by file-locality, ship as a structured single commit. This is faster and easier for closing-comment hygiene than N sequential commits.
Concurrent-agent git hygiene (added 2026-05-06)
Multiple agents in the same repo share two mutexes that are easy to forget:
- Working tree — every agent reads + writes the same files. Avoided by the disjoint-files invariant (above).
- Git index — every agent's
git add file mutates the same staging area. A parent's later git commit (no pathspec) sweeps up whatever is currently staged, which may include sibling agents' WIP from in-flight work.
The 2026-05-05 5-agent QA wave hit this twice:
- A parent's
git commit of the #413 schema fix bundled 6 unrelated files (Agent B's e2e specs + the deduplication helper). Caught pre-push, soft-reset, re-staged with explicit pathspec.
- Agent F's first commit (
cfb9973) accidentally captured 7 of Agent J's files via the same race. They soft-reset and recovered.
Mandatory mitigation pattern — use git commit --only <pathspec> -F msg.txt:
git add backend/routes/foo.js e2e/tests/foo.spec.js
git commit -m "fix(foo): close #N"
git commit --only backend/routes/foo.js e2e/tests/foo.spec.js -F /tmp/msg.txt
The --only flag bypasses the staging area entirely for the commit step. Even if a sibling agent ran git add unrelated_file.js between your add and commit, the commit still includes only your two files.
Rule of thumb: if there's any chance another agent might be touching the repo concurrently, use --only. The dispatching parent should also use it for any consolidation commits.
-o is the short form of --only — same semantics, fewer keystrokes, more pleasant to retain in agent prompts. Use either:
git commit -o backend/routes/foo.js -o e2e/tests/foo.spec.js -F msg.txt
git commit --only backend/routes/foo.js e2e/tests/foo.spec.js -F msg.txt
Empirical confirmation — v3.4.12 closure wave (2026-05-05): the W1/W2/W3 waves dispatched 7 agents across 27 issues with -o baked into the per-agent prompt template from the start (see AGENT_PROMPT_TEMPLATE.md "Commit hygiene"). Zero index-race collisions across the entire wave. The pattern that bit the 2026-05-05 morning waves twice (Agent F sweeping 7 of Agent J's files; #413 bundling 6 unrelated) didn't recur once the template required -o. Bake the -o rule into the per-agent prompt — relying on the agent to remember the existing skill section is unreliable; making it canned in the template is what converted the pattern from "occasionally bit us" to "zero incidents."
When --only is NOT sufficient — overlapping-file scenarios (added 2026-05-12 after 6 instances)
git commit --only <pathspec> solves the index-race problem (two agents call git add in overlapping windows; the second's commit accidentally captures the first's staged files). It does not solve the working-tree-state problem: when two agents have uncommitted local edits in the SAME file, --only captures the full working-tree state of that file at commit time — including the sibling's edits — not just your local diff.
2026-05-12 saw 6 instances of this in one day (mostly on shared files like backend/prisma/schema.prisma, .github/workflows/deploy.yml, .github/workflows/coverage.yml, backend/middleware/security.js, frontend/src/index.css):
- w-B1's
f85dc45 (#665 date-range validation) committed deploy.yml + coverage.yml — captured sibling w-C's WIP csp-stepup-api.spec.js workflow line that hadn't been committed yet. Caused the next CI run to red on "spec not found"; required a follow-up 96ff706 to drop the dangling ref.
- w-B2's
a30a40d (#657 CSRF) swept up w-D1's 10 frontend/src/components/ui/* files + frontend/src/index.css btn-danger + animation hunks. Build still passed (lucky case), but w-D1 had to ship 1364fea as a docs-only commit to claim the Closes #N trailers.
- w-B3's
ab046d4 (#653 GiftCard bcrypt) needed git commit --only <my-5-files> to isolate around unresolved merge conflicts and sibling WIP in 12+ files.
- w-D1 was "swept into" w-B2's
a30a40d; recovered via git reset --soft + patch-isolation via git apply --cached to extract only the agent's own hunks.
- w-D2 stalled mid-flight at "wire tenant-aware document.title" with 5 shared frontend files in working tree; parent agent took over the recovery in
feb0fcc.
- w-D3's
2a4e21e (PII masking) was the only Wave-D agent to commit cleanly because by the time it ran, siblings had already drained — the timing-based "luck" pattern.
What to do instead
For each shared-file category, use the targeted mitigation below INSTEAD of --only alone:
backend/prisma/schema.prisma (Prisma model additions):
Use a one-shot Node patcher that anchors on grep-locatable insertion points. Write something like .tmp-apply-<agent>-schema.js that:
- Reads
schema.prisma content
- Finds your insertion point via a deterministic anchor (e.g. end of file, or after a specific known model's closing
})
- Splices in your new model block
- Writes the file
- Runs
git add schema.prisma && git commit -m '...' schema.prisma immediately in the same script
The patcher runs atomically — there's no window where another agent's WIP can land in the file between your splice and your commit. Canonical example: 2026-05-09 Wave 2 Agent II for schema.prisma.
.github/workflows/deploy.yml + coverage.yml (gate-spec list additions):
Use the existing .claude/skills/wiring-spec-into-gate/wire-in.sh script — it's idempotent: it greps for your spec name first and no-ops if already present. After git pull --rebase on push collision, re-run it to claim your slot. Don't hand-edit the YAML; the script handles ordering + comments.
frontend/src/index.css + shared CSS files:
Append your agent's section at the END of the file, fenced with a clear boundary marker so siblings can split them apart later if needed:
.your-class { ... }
On collision (push rejected after rebase), git apply --cached <patch-with-your-section> extracts only your hunk. Don't try to merge — appended sections are commutative.
backend/server.js mount block + middleware-chain edits:
These are the riskiest because order matters AND multiple agents append to the same regions. Mitigation: each agent writes a .tmp-server-patch-<agent>.js script that does a targeted String.prototype.replace() against a specific known anchor line, then commits server.js atomically (same pattern as the prisma patcher).
General principle: when in doubt, dispatch to a single agent serially rather than parallel. The schema-sweep cost (lost work + recovery commits) usually exceeds the wall-clock savings of parallelism for 3+ agents sharing one file.
Detection — how to know which scenario you're in
Before dispatching, run:
echo "Schema additions:" && grep -lE "schema.prisma" .tmp-agent-plans/*.md 2>/dev/null | wc -l
echo "Workflow additions:" && grep -lE "deploy.yml|coverage.yml" .tmp-agent-plans/*.md 2>/dev/null | wc -l
If ≥2 agents will edit the same file, mandate the patcher pattern in those agents' prompts OR sequence them serially.
Verify each issue's auto-close after multi-issue commits (added 2026-05-06)
GitHub's auto-close-on-trailer behavior has TWO silent failure modes that bit the 2026-05-05 5-agent wave:
- Shortform
Closes #N + #M only auto-closes the FIRST issue. Per GitHub's grammar, the keyword must immediately precede each #N. Closes #462 + #463 closes #462 but NOT #463.
- Per-commit auto-close cap. Even with one
Closes #N per line (the correct grammar), commits with 5+ trailers appear to silently cap. Agent J's ecb4ae0 had 7 separate Closes #N lines; only 6 fired (#476 stayed OPEN). Agent I's fc9898e (multi-fix) had #465 and #473 stay OPEN despite explicit trailers.
Mandatory verification step after any commit that's supposed to auto-close 2+ issues:
for n in 462 463 466 467 468 473 474 475 476; do
echo -n "#$n: "; gh issue view $n --json state --jq '.state'
done
Any issue still showing OPEN → close manually with citation:
gh issue close 463 --reason completed --comment "Fixed in commit \`a2895d8\` — auto-close trailer didn't fire (GitHub cap). [<root-cause-summary>]. See <SHA> commit body."
The bumping-version-docs companion skill should encode this verify-then-manual-close step too.
Stop-before-push when a local CI-equivalent gate fails (added 2026-05-06)
Agents have access to local equivalents of every CI gate (npm test, eslint, node backend/scripts/check-migration-safety.js, cd e2e && npx playwright test). When one of those flags an issue an agent can't trivially resolve, STOP and report — don't push and hope the gate is wrong.
The 2026-05-05 5-agent wave's Agent C demonstrated this perfectly: completed the #413 schema work but check-migration-safety.js flagged 6 false-positive risks (FK_WITHOUT_ON_DELETE matching DROP-FOREIGN-KEY statements that can't carry ON DELETE). Agent C reported the flag, asked for direction, and waited rather than push. The parent confirmed the false-positive analysis and shipped a one-line detector bug-fix bundled with the schema change in the same commit (1ef4ba5). Had the agent pushed anyway, migration-check.yml would have gone red on main and blocked all subsequent schema work until manually cleared.
Rule for every dispatched agent prompt: "If a local CI-equivalent gate (eslint, vitest, migration-safety, prisma validate, etc.) flags an issue you can't trivially resolve in 5 minutes, STOP, report the failure with the full error output, and wait for parent direction. Do NOT push and hope the gate is wrong; do NOT skip-the-check (--no-verify, --ignore-scripts) to bypass it."
This complements the existing "5-iteration heal cap" rule (which applies to test failures); the same shape applies to all non-test gates.
NEW spec authored by an agent? Run it locally before commit (added 2026-05-06)
Build / lint / node --check do not catch a class of spec bug that only fires when the spec is actually executed: wrong-field reads in fixture-loading helpers (e.g. j.user?.tenantId when the response shape is j.tenant?.id), missing assertions on async resource creation, etc.
The 2026-05-05 wave's Agent A landed landing-page-upload-api.spec.js that compiled clean (build green, eslint clean, node --check green) but failed every per-push api_tests run because genericTenantId was captured from the wrong response field — assertions read tenant-${null}/. Result: 4 consecutive failed deploys (9abbafe → 51e8891 → 1ef4ba5 → cc1a0ca), demo stuck for ~50 min.
Rule for every dispatched agent prompt that authors a NEW spec (not editing existing ones): before commit, run the new spec locally against the local stack:
cd e2e && BASE_URL=http://127.0.0.1:5000 npx playwright test --project=chromium tests/<new-spec>.spec.js
(Boot the local stack first with .\scripts\local-stack-up.ps1 if needed.) The spec must be all-green against local before the agent commits. If a sibling agent is currently using the local stack for their own spec run, queue or use a freshly-named project to avoid races.
For spec EDITS (not new files), running locally is recommended but not mandatory — the diff is small and easier to reason about statically.
Graceful concurrent recovery (added 2026-05-07 after 6+ instances)
The "disjoint files" invariant is necessary but NOT sufficient. Even when no two agents touch the same file, they share a working directory and a remote main branch. Three recovery sub-patterns have been observed working cleanly when sibling-collision arises mid-flight; encode all three into agent prompts so the agent recovers without parent intervention.
Sub-pattern (a) — Detect dirty state at start, refuse to commit
When an agent starts and finds the working tree dirty (someone else's WIP files), it must NOT commit anything until the tree is clean. Canonical instance: Wave 2 Agent D (dashboard discovery) inherited Agent E's revert-and-prove dirty state. D ran read-only investigation, intentionally did not commit any of its own TODOS edits, and completed cleanly. Without this discipline D would have shipped Agent E's half-done revert as part of D's commit.
# Agent prompt addition for shared-CWD waves:
"At task start, run `git status --short`. If the tree has uncommitted
changes that you didn't make, do NOT commit anything yourself
unless your work is purely read-only investigation. Restore working
state on exit (git checkout -- <files> any changes you made)."
Sub-pattern (b) — Detect file-collision mid-task, back off + file follow-up TODOS
When an agent realizes it needs to edit a file a sibling is currently editing (shared CWD has the sibling's mid-flight changes), it should NOT block waiting and NOT commit on top. Instead: revert its own changes to the contended file, file a TODOS user-attention follow-up describing the specific edit needed, and ship the rest of its work.
Canonical instance: Wave 7 Agent P needed to wire junkSourceFilter into routes/wellness.js computeAttribution() but Agent O was mid-flight on the datetime sweep in the same file. Agent P reverted its wellness.js change, filed a 5-min wire-in as a TODOS row, and shipped the rest. Parent picked up the deferred wire-in inline once O released the file (commit 4e8e45f).
# Agent prompt addition:
"If you mid-task discover that a file you need to edit is being
edited by a sibling (look for unstaged changes you didn't make),
revert your own edits to that file (`git checkout -- <file>`),
file a TODOS user-attention follow-up describing the exact section
+ edit needed, and ship the rest of your task. The parent picks up
the follow-up after siblings release the file."
Sub-pattern (c) — Stash → pull → pop on push collision
When an agent is ready to push but a sibling pushed first, the rebase will fail if the agent's tree has unstaged changes from its own concurrent work. Standard recovery:
git stash push -m "agent-pre-push-stash"
git pull --rebase origin main
git stash pop
git push origin main
Confirmed working across multiple waves today: Wave 9 Agent T past Agent S's WIP; Wave 10 Agent V; Wave 14 Agents A + B + C (multiple stash/pop cycles when 5 agents shipped within ~25 min wall time). Push went through clean on first or second attempt in every case.
# Agent prompt addition:
"If `git push origin main` fails with non-fast-forward, recover
via: `git stash push -m agent-pre-push` → `git pull --rebase
origin main` → `git stash pop` → resolve conflicts on YOUR files
only → push again. If the conflict is on a sibling's file
(unexpected — disjoint-files invariant should prevent this),
STOP and report — do not commit a merged version of someone
else's file."
When NONE of these recover cleanly
If you've tried (a) → (b) → (c) and the work still won't ship, the dispatch was probably mis-scoped (sibling DID need to touch the same file). Recovery: stash your work, post a comment on the wave-orchestrator side describing the contended file + the specific edit you couldn't ship, and exit. The parent re-dispatches your work as a follow-up after the original sibling completes.
This has happened 0 times in the 14-wave session on 2026-05-07; all collisions resolved via (a)–(c).
Templates
See AGENT_PROMPT_TEMPLATE.md for the full per-agent prompt skeleton with placeholder slots.
