User Story

As a user driving a portfolio of independent work items, I want a skill that spawns multiple specialised agents in parallel — each on its own task, optionally in its own worktree — so that I can progress several tickets at once without the framework silently serialising them behind a single agent's session.

Context

Claude Code's Agent tool supports multi-agent fan-out via a single message with multiple tool calls, optional isolation: worktree for independent file-space, and optional run_in_background for long-running work. Today, that power is only available to agents who happen to know the pattern. A typical session serialises tasks that don't need to be serial — refactors across N unrelated files, research across N unrelated areas, or implementation of N independent tickets.

Observed cost: conversations routinely do one ticket, wait for review, then start the next — when the tickets are genuinely independent and could have landed together. The framework should make parallel execution the default offer when it's safe, not a pattern each user rediscovers.

This ticket adds a skill (/fan-out) that does three things:

1. Detects when a request decomposes into independent work.
2. Offers the parallel plan with per-task agent type + isolation choice.
3. Executes and reconciles.

Acceptance Criteria

• New skill at .claude/skills/fan-out/SKILL.md with argument-hint: "<task1, task2, ...>".
• Step 1 — gather tasks: accept from args, from a file path, from a ticket list (--from-tickets apexyard#109,apexyard#110), or interactive entry. One task per line.
• Step 2 — for each task, ask once:
  • Agent type — general-purpose (default) / Explore (research) / code-reviewer / security-reviewer / Plan / custom subagent name.
  • Isolation — worktree (default if any agent writes code) / shared (default if all read-only).
  • Mode — foreground (default) / background (for long runs).
• Step 3 — show the fan-out plan for confirmation (table: task · agent · isolation · mode).
• Step 4 — spawn all agents in a single assistant message with multiple Agent tool calls (true parallelism, not serialised).
• Step 5 — collect results.
• Step 6 — if any agent used worktree isolation: list the created branches; offer to merge each back sequentially, handling conflicts interactively.
• Step 7 — summary report: per-task status + any follow-ups.
• Max 5 concurrent agents per invocation (configurable, but default cap to avoid overwhelming).
• Safety: if any task involves code edits and no active ticket marker exists for its target project, refuse and tell the user to /start-ticket first (per require-active-ticket.sh). Do this in step 3, not step 5.
• Refuse (with a clear message) to fan out tasks that share file targets — detect from the task descriptions heuristically, or ask the user to confirm.
• Dogfood: spawn 3 parallel Explore agents on 3 unrelated questions; confirm they return in roughly max(individual durations), not sum.

Design Notes

Offer-parallel discipline. This skill is one half of the pattern. The other half is a heuristic the agent uses to offer parallel work proactively — e.g. when the user asks to file N independent tickets, or implement N unrelated hooks, or audit N files. That heuristic belongs in a rule doc (.claude/rules/parallel-work.md) and in CLAUDE.md, not in the skill. The skill is the happy path; the rule is the trigger.

Why worktree for code edits. Without isolation, two agents editing in the same working directory race on git status, mixed stage, and file writes. Worktrees give each agent its own branch + filesystem view. Cost: the merge back into the main branch is manual. Benefit: no lost work.

Why one assistant message for spawns. Per Claude Code's Agent tool semantics, agents spawned from separate messages run sequentially, not concurrently. Parallelism requires one message with N tool calls. The skill's "Step 4" must emphasise this — any implementation that loops is wrong.

Agent-type selection. Some agents have narrow scopes (code-reviewer only reads + reviews; Explore only searches). If a task needs editing, the skill must refuse a read-only agent type and suggest general-purpose.

Out of Scope

• Cross-agent coordination (agents talking to each other mid-run). Fan-out is independent tasks, not a swarm.
• Resuming partial fan-outs after a session restart. First cut is one-session.
• Dynamic task generation (agent A spawns agent B). Static plan only.
• Automatic merge-conflict resolution. Skill pauses on conflict and asks.

Effort Estimate

Medium. ~250 lines of SKILL.md. Add a companion rule doc (.claude/rules/parallel-work.md, ~50 lines) defining when the agent should proactively offer fan-out. Plus a CLAUDE.md entry under Skills.