medcore-fanout

name

medcore-fanout

description

Dispatch multiple parallel foreground Agent calls to close non-overlapping MedCore gaps in one shot — closing several E2E backlog routes at once, writing several test files at once, fixing several bugs at once, or any "do these N things in parallel" request. Use when the user wants concurrent work on tasks that touch different files / directories. Do NOT use for sequential dependencies, single-task work, or tasks that need bg dispatch (this skill exists specifically because bg agents are broken on this VSCode harness build).

medcore-fanout

The codified pattern for actually-parallel work in this MedCore session.

Why this skill exists

run_in_background: true Agent calls are broken on Claude Code VSCode v2.1.126: every Read/Edit/Write/Glob/Grep fires an interactive permission popup, and the 600s watchdog kills the agent if no click. See reference_worktree_bg_agent_perms.md for the full diagnosis. Foreground Agent calls in a single tool-use message DO run concurrently — that's the only proven parallelism path right now. This skill codifies that pattern with the MedCore-specific guard rails.

When to invoke

Invoke when:

• The user explicitly asks for parallel work ("close these 4 routes in parallel", "fan out", "spin agents on these").
• You are about to ship 2+ independent items and they touch non-overlapping directories.
• The user says "do these N things" and they are clearly independent (E2E specs for 4 different routes, snapshots for 4 different generators, etc.).

Do NOT invoke when:

• The work is sequential (dependency between steps).
• Only one task — just do it.
• Tasks touch the same file or the same package.json / lockfile (race risk).
• The user wants async / "fire and forget" work — bg agents are broken; explain that and suggest foreground or DIY.

Two dispatch modes

Pick the mode up-front, before writing any agent prompt — the commit instructions diverge.

Mode A — per-agent commits (default). Each agent commits + pushes its own work. Best when lanes are clean and the wave reads as N independent shippable units (e.g. four E2E specs, four route-test scaffolds). Fastest to merge; surfaces individual agent failure cleanly.

Mode B — single bundled commit. Agents stage their changes, validate, and report back; the parent merges everything into one commit. Best when the wave reads as one logical unit — a single audit follow-up, a coordinated security migration, a refactor that's only half-meaningful in isolation. Used by the May 2026 security audit follow-up (commit e7ca04d — 4 agents, 1 commit covering #457 + F-ABDM-1 + F-INJ-1 + 9-route AI audit).

In Mode B, the per-agent prompts must say "do NOT commit, do NOT push — stage your files and report", and the parent runs the unified typecheck + impacted-test sweep + single git commit -- <all files> + single git push after the wave returns. The lane-discipline checklist still applies (non-overlapping files), but the rebase-retry loop becomes a single push at the end and the -- scoping argument matters less.

How to dispatch

Single message, multiple Agent tool calls in parallel. All foreground (no run_in_background parameter, no isolation: "worktree" — both have known issues).

Each Agent call must include:

1. Strict file scope — the directories/files this agent owns. Other agents touch nothing there.
2. The MedCore commit discipline (verbatim — paste this into every prompt):
   • Conventional commits (test(...), fix(...), feat(...), docs(...), chore(...), perf(...), ci(...)).
   • NO Co-Authored-By: Claude trailer (forbidden by user's global CLAUDE.md).
   • Stage with git add <specific files> — never git add -A.
   • Commit with git commit -m "<msg>" -- <files> (the trailing -- <files> scopes the commit even if other files are staged from concurrent agents).
   • Push with rebase-retry loop:

     for i in 1 2 3 4 5; do
       if git push origin main; then break; fi
       git fetch origin main
       git rebase origin/main
     done
     

3. The descriptive-headers convention for any new test or new entry-point file (per docs/README.md "Tests & feature code"):
   • Top-of-file 2-4 line block comment: what / which modules / why.
   • describe(...) strings should be specific behaviour-and-surface descriptions, not single words.
4. A short, concrete deliverable the agent must report (commit SHA, test count, what was skipped + why). Cap final response at ~200 words.
5. Time discipline — "If a sub-task is hard to mock / blocked, skip it and move on. N solid items shipped > N+M items half-done."

Lane-discipline checklist

Before dispatching, verify the lanes are non-overlapping:

Risk	Mitigation
Two agents modify apps/api/package.json	Only one agent can touch each package.json per batch; route the script-entry change to that one.
Two agents touch root package-lock.json	Only one agent runs npm install in a batch.
Two agents add tests to the same dir	Pre-assign distinct test filenames; explicit "do NOT touch " in each prompt.
Concurrent git commit clobbers staged files	The git commit -m "<msg>" -- <files> form scopes by file, not by index — safe under contention.
Concurrent git push rejects	Rebase-retry loop (above) is mandatory in every prompt.

Per-agent prompt template

Use this skeleton for each agent's prompt. Replace the <…> placeholders.

You are working in the MedCore HMS monorepo at `c:\Users\Admin\gbs-projects\medcore`. Goal: <one-sentence outcome>.

**This is a parallel-fanout run.** N other agents are working concurrently in the same repo, each in a different directory. Your scope:

- Files you may write to: <explicit list>
- Files you may NOT touch: <explicit list of others' lanes + lockfiles + shared package.json files>
- You may read anything.

## Steps
<3-7 concrete steps>

## Validate
- <test command(s) that must be green>
- `npx turbo run lint --filter=<scope>` must be green.

## Commit (concurrency-safe)
- Conventional commit, NO Co-Authored-By trailer.
- `git add <your files>` (never `-A`).
- `git commit -m "<msg>" -- <your files>` (the `--` scopes the commit).
- Push with rebase-retry:
  ```bash
  for i in 1 2 3 4 5; do
    if git push origin main; then break; fi
    git fetch origin main
    git rebase origin/main
  done

Descriptive headers (mandatory for new test / entry-point files)

Top-of-file 2-4 line block comment: what / which modules / why. describe(...) strings should be specific. See docs/README.md "Tests & feature code".

Deliverable

Single commit. Report under 200 words: commit SHA, what shipped, anything skipped + why. Ship — don't narrate.

## Post-launch

After the parallel batch completes:

1. Summarize each agent's commit in a single table for the user (commit SHA, what landed, any skips).
2. If any agent failed, surface the failure prominently and ask the user whether to retry, redirect, or skip.
3. If race-related rebase happened, note it (audit-friendly).
4. **Chain `/medcore-doc-roll` next** — capture this wave's commits + agent-surfaced findings into TODO.md + CHANGELOG.md before any new wave starts. Skipping this between waves loses the architectural findings agents surface in commit bodies. Idempotent and safe — just always do it.
5. After the doc-roll lands, recommend the next move (e.g., "all four E2E routes shipped + docs rolled — kick off release.yml to validate?").

## Common batches for MedCore

These bundles have been validated in past sessions. Use them as templates:

- **E2E backlog batch**: 3-4 agents, each closing one zero-coverage route. Lanes: `e2e/<route-1>.spec.ts`, `e2e/<route-2>.spec.ts`, etc. Each may also touch `docs/E2E_COVERAGE_BACKLOG.md` (the closure-annotation line is per-route, low race risk; rebase-retry handles it).
- **P-list test batch**: P9 (`apps/api/src/services/__snapshots__`), P3 (`apps/web/src/components/**/*.a11y.test.tsx`), P10 (`apps/api/src/services/ai/*.bench.ts`), P2 (`packages/db/src/__tests__/migrations.test.ts`).
- **Source-fix batch**: each agent owns one route handler. Lanes: `apps/api/src/routes/<a>.ts`, `apps/api/src/routes/<b>.ts`, etc.
- **Bundled security audit (Mode B)**: 4 agents covering tenant-FK / rate-limit / prompt-injection / per-route audit-row retrofits, all merged into one commit. Lanes: `packages/db/prisma/**`, `apps/api/src/routes/abdm.*`, `apps/api/src/routes/ai-{er-triage,letters,chart-search,report-explainer}.*`, `apps/api/src/routes/ai-{adherence,knowledge,pharmacy,predictions,transcribe}.*`. Pair Mode B with `/medcore-ai-route-audit` for the AI lanes.

## Anti-patterns observed

- **Don't dispatch with `isolation: "worktree"`.** Worktree paths under `.claude/worktrees/` trigger the same permission-popup gate; the harness needs the user to click for every Read.
- **Don't dispatch with `run_in_background: true` for file-write tasks.** Bash-only tasks ("run this test, report exit code") work in bg; anything that reads source files stalls.
- **Don't skip the rebase-retry loop.** Concurrent pushes WILL race; the second one fails with "rejected".
- **Don't let agents `git add -A`.** Concurrent staging will pull other agents' files into a single commit.

## Known artifact: working-tree mutation by concurrent agents

Multiple agents in a fanout share the SAME working tree (no worktree isolation, see above). When agent A writes file X and agent B writes file Y simultaneously, both files coexist in the working tree, but each agent's view-of-the-tree is whatever the shell sampled when it last ran a command. **This means an agent's edits CAN appear to be transiently reverted mid-task** if another agent modifies the same file slice between the first agent's `Read` and `Edit`.

Observed across 3 separate agents in the 2026-05-05 fanouts:
- Agent saw "expected revert" of edits to its own target file.
- Recovery pattern (used successfully in commits `d76669d`, `478325e`, `75a5ccc`):
  1. `git stash push -m "agent-$ID"` to snapshot the agent's intended changes.
  2. `git checkout 'stash@{0}' -- <agent's target files>` to extract ONLY the agent's intended files from the stash.
  3. `git commit -m "..." -- <agent's target files>` to commit ONLY those files (the trailing `-- <files>` scopes the commit even if other agents' uncommitted work is in the index).

**This is expected, not a bug** — the cost of skipping worktree isolation. Each agent prompt should include this recovery pattern in its commit instructions when concurrent file overlap is plausible. Agents that own truly non-overlapping file lanes (e.g., 4 different `e2e/<route>.spec.ts` files) won't trigger this and don't need the stash dance.