feat(#117): /fan-out skill + parallel-work rule for proactive parallel proposal#128
Conversation
- Add `.claude/skills/fan-out/SKILL.md` — spawns N parallel Agent calls in a single assistant message, with per-task agent type, worktree isolation, and foreground/background mode. Caps at 5 concurrent agents. Refuses fan-out when tasks share file write targets or have sequential dependencies. Includes pre-spawn active-ticket safety check and worktree merge-back flow that pauses on conflict. - Add `.claude/rules/parallel-work.md` — trigger heuristic for when an agent should proactively offer fan-out (>= 2 file-independent, context-independent, individually substantial work items). Pairs with the skill: rule says when, skill says how. - Update `CLAUDE.md` — bump rules count to 9, skills count to 34, add `/fan-out` row to the skills table. Refs #117
atlas-apex
left a comment
There was a problem hiding this comment.
Code Review: PR #128
Commit: a9a5d9cb9a1666cbc696cab069b210d0b5048fdb
Summary
Adds the /fan-out skill (.claude/skills/fan-out/SKILL.md) and the companion trigger-heuristic rule (.claude/rules/parallel-work.md) to formalise the "spawn N parallel agents in one message" pattern. Also bumps the rules count (8→9) and skills count (33→34) in CLAUDE.md and adds the /fan-out row to the skills table.
Checklist Results
- Architecture & Design: Pass — clean split between skill (the how) and rule (the when); both cross-link
- Code Quality: Pass — markdown only, no code
- Testing: N/A — markdown spec; PR description acknowledges the dogfood validation will come on the next ≥ 2-independent-tickets moment
- Security: Pass — no secrets, no auth surface touched
- Performance: N/A
- PR Description & Glossary: Pass — Glossary present with 4 terms (Fan-out, Worktree isolation, Background mode, Offer-parallel rule), ticket linked (
Closes #117), scope + caveats called out - Technical Decisions (AgDR): N/A — no new dependency, no architecture choice; this PR formalises an existing observed pattern (used 8x this hooks-wave per the PR body) rather than introducing a new one
Verification of all 8 reviewer-specified requirements
| # | Requirement | Result | Evidence |
|---|---|---|---|
| 1 | All Agent calls in same assistant message |
Pass | Step 6 (lines 107–117) plus Rule #1 (line 177): "All Agent tool calls for a single fan-out MUST be in the SAME assistant message. Multi-message loops do not get concurrency — they serialise. This is the most important rule in this skill." — explicitly named as the most important rule, with reasoning |
| 2 | Worktree default for code, shared for read-only | Pass | Step 2 (line 56): "default worktree if any agent will write code; shared if all agents are read-only research" — plus Rule #2 |
| 3 | Active-ticket fail-fast vs hook | Pass | Step 3 (lines 60–75): refuses the entire fan-out, with explicit rationale "Failing fast at fan-out time is kinder UX than letting 3 of 5 agents start, then 2 fail mid-run". Checks both per-project (session/tickets/<project>) and ops-fork (session/current-ticket) markers |
| 4 | File-collision guard | Pass | Step 4 (lines 77–89): heuristic detection on file paths / globs / implied scope; refuses parallel and recommends serial when collisions found |
| 5 | Cap at 5 concurrent agents | Pass | Rule #5 (line 181): "Cap at 5 concurrent agents per invocation. If the user wants more, ask them to split into batches." — with rationale (review fatigue, merge-back queue, rate limits, context dilution) |
| 6 | Sequential merge-back, conflict pause, ask user | Pass | Step 8 (lines 140–160) sequences merges one branch at a time; Rule #10 (line 186): "Pause on merge-back conflict — never auto-resolve. The user owns the merge." |
| 7 | parallel-work.md defines WHEN to offer |
Pass | Lines 9–13 list the three conditions explicitly: file-independent, context-independent, individually substantial (≥ 5 min each). Both positive examples (lines 15–20) and negative cases (lines 22–28) are concrete |
| 8 | CLAUDE.md updated | Pass | Rules count 8 → 9, skills count 33 → 34 (both in the layer table and the QUICK REFERENCE), /fan-out row added to the skills table |
Issues Found
None blocking.
Suggestions (non-blocking)
-
Cross-link from
parallel-work.mdback to the skill. The skill links to the rule (line 13), but the rule does not name the skill path. Adding "see.claude/skills/fan-out/SKILL.md" in the "How to offer" section would make the rule self-contained for someone landing on it via grep. -
Cap rationale on a separate line. Rule #5 packs the cap, the overflow protocol, and the rationale into one sentence. Splitting "Why 5?" onto its own line would make it scannable when someone is checking the rule under pressure (e.g. "the user just asked for 8 agents, what now?").
-
Step 2 "Mode" estimation heuristic is hand-wavy. "Estimate from task scope (single-file edit ≈ short; cross-cutting refactor ≈ long; full audit ≈ long)" — fine as a starting point, but the next iteration could pin a numeric proxy (e.g. "if the task description mentions ≥ 3 files or ≥ 200 LOC of expected change, treat as long"). Easy to defer until real usage exposes the right proxy.
-
Step 7 "Status" enum is underspecified. "success / failure / partial" —
partialneeds a definition. Is "I did 3 of 5 sub-steps and stopped on a question" partial? What about "I succeeded but the test I added fails"? Not blocking — fine to let usage shape this — but worth a note in a follow-up. -
PR description self-disclosed branch nonconformance. The original worktree branch was
worktree-agent-aac0660c. The author cherry-picked ontofeature/GH-117-fan-out-skillto comply. Worth noting in the skill itself (a "Caveats" or "Known limitations" section): the worktree branch names the skill produces by default may not match the{type}/{TICKET-ID}-{description}convention enforced byvalidate-branch-name.sh, so the merge-back step (Step 8) should suggest the user rebase/cherry-pick onto a properly-named branch before opening a PR. This is exactly the dogfood lesson from this PR — capture it where the next user will see it.
Verdict
APPROVED — ships a clean, well-structured spec for an observed, repeated pattern. All 8 reviewer-specified requirements verified. Suggestions are post-merge polish, not gates.
Reviewed by Rex (Code Reviewer Agent)
Reviewed commit: a9a5d9cb9a1666cbc696cab069b210d0b5048fdb
User Story
As an agent driving a portfolio of independent work, I want a skill that spawns N parallel
Agenttool calls in one assistant message — so that genuinely-independent tasks run concurrently instead of serially, and I have a clear pattern to recommend whenever the user's request decomposes that way.Summary
Two coupled artefacts that ship together:
/fan-outskill at.claude/skills/fan-out/SKILL.md— spec for spawning N parallelAgentcalls (single assistant message, withisolation: worktreefor code-writers,run_in_background: truefor long runs). Includes the active-ticket safety check, file-collision guard, plan confirmation, worktree merge-back, and 5-agent cap..claude/rules/parallel-work.md— rule doc defining WHEN an agent should proactively offer fan-out. The skill is the happy path; the rule is the trigger heuristic.Together they fix the "agent silently serialises independent work" failure mode that surfaces every time we have ≥ 2 independent tickets in flight (observed eight times this hooks-wave). The rule says "offer parallel"; the skill is what they invoke when the user accepts.
CLAUDE.md updated:
/fan-outadded to Skills tableparallel-work.mdTesting
Skills + rules are markdown — no shell test fixture. The dogfood for this PR is the work that produced the previous 8 hooks: those landed via parallel agent fan-out (with worktree isolation, sequential merge-back) under the prior session's ad-hoc pattern. This PR formalises that pattern as a reusable skill.
Verify spec quality:
Real validation will be the next "≥ 2 independent tickets" moment — the skill is followable as-is; rough edges surface there.
Scope — what this does NOT do
Caveats from the agent that built this
worktree-agent-aac0660c— notfeature/GH-117-…. I cherry-picked the commit onto a properly-named branch (feature/GH-117-fan-out-skill) for this PR.Glossary
isolation: worktreeon anAgentcall gives it its own git worktree + branch, so two agents writing code don't race on the filesystem.run_in_background: truelets the parent continue working while the agent runs. Required for >2-minute estimated work..claude/rules/parallel-work.md— proactively propose fan-out when work decomposes into ≥ 2 independent file-and-context-independent tasks.Closes #117