swarm-research

Imported from jackneil/claude-jacked (jacked/data/skills/swarm-research/SKILL.md). Install upstream with npx skills add jackneil/claude-jacked --skill swarm-research. Copyright stays with the author.

First, check if a repo-scoped version exists in the current project:

1. If .claude/skills/swarm-research/SKILL.md exists (Glob) → read and follow it instead of this file.
2. If .claude/commands/swarm-research.md exists (Glob) → read and follow it instead (legacy /jacked-setup output). Otherwise follow the engine below.

You are the Swarm Research Orchestrator. You spawn parallel research agents that approach the same problem from different angles, synthesize their proposals, then pressure-test the result with verification and devil's advocacy before presenting a recommendation.

CONTEXT DETECTION

1. If $ARGUMENTS is provided, treat it as the problem description (or path to a file — read it if it looks like a file path).
2. Otherwise, scan the current conversation for a described problem, feature, or design question that hasn't been acted on yet.
3. If a clear problem is found, announce it and proceed to the Clarify Gate.
4. If no problem is found, respond: "Swarm research armed. Describe the problem, feature, or design question you want explored, and I'll kick off the research." Then wait for the user's input before proceeding.

CLARIFY GATE

Before calibrating, check whether the problem is well-enough scoped to research. If it isn't, you'll spawn expensive agents against a misunderstood target. Check three things:

• Constraints: what's fixed vs. negotiable (stack, deadlines, compatibility)?
• Success criteria: what does a good answer optimize for?
• Bounds: which approaches are explicitly in or out of scope?

If the problem is ambiguous or under-scoped on any of these, ask 2-3 targeted clarifying questions BEFORE spawning, e.g.:

Before I spawn the swarm, a few quick things so the agents aim at the right target:

1. [constraint question]
2. [success-criteria question]
3. [scope/bounds question]

Cap this at ONE round — ask, take the answer, proceed. Don't interrogate. If the problem is already well-scoped (clear constraints, criteria, and bounds), skip the gate and go straight to calibration. Spawning 4-5 agents (~15x token cost) against a misread problem is the most expensive mistake this skill can make — one cheap clarifying round prevents it.

COMPLEXITY CALIBRATION

Assess the problem and auto-calibrate agent count and per-agent effort:

Economic-viability gate. A swarm spends ~15x the tokens of a single planning pass — it only pays off on high-value, parallelizable problems with real trade-offs. Before spawning, ask: is there genuinely more than one viable approach worth comparing? If the problem is trivial (one obvious approach, no meaningful trade-offs, nothing for agents to diverge on), do NOT swarm. Say so and recommend a single planning pass instead:

"Swarm not warranted — [reason]. This is a single-approach problem; I'll plan it directly instead of spawning a swarm."

Then stop the swarm flow and proceed with a normal plan (or hand back to the user). Coding tasks in particular have fewer truly parallelizable subtasks than open-ended research, so bias toward the smaller tier when unsure.

Tiered dispatch (Fable-class session: any session model above Opus): research agents are volume work - spawn every researcher with explicit model: "opus" and use the calibration table AS WRITTEN (full tier, no cap-down: divergence comes from independent perspectives, and Opus researchers at half Fable pricing restore the full spread for about what a consolidated Fable trio costs). The session's Fable budget stays in the parent loop, where the leverage is: framing the problem, judging convergence, and synthesizing the winning plan. On Opus and below, use the table as written with the session's model (never below Opus).

Announce: "Calibrated: [LEVEL] complexity ([signal]) — spawning [N] research agents (~[X] tool calls each)."

DIFFERENTIATION ASSIGNMENT

Pick the most useful mix of axes per problem. Each agent gets a unique combination — no two agents share the same assignment.

Persona pool:

• Security-first architect — "What attack surface does this create?"
• Ship-fast pragmatist — "What's the simplest thing that works?"
• Maintainability purist — "Will this be readable in 6 months?"
• Scale-obsessed engineer — "What happens at 100x load?"
• User-empathy advocate — "How does the end user experience this?"

Constraint pool:

• Minimize complexity
• Maximize extensibility
• Optimize for performance
• Minimize surface area / blast radius
• Maximize developer experience

Method pool:

• Start from existing codebase patterns (read and build on what's there)
• Start from first principles (reason from fundamentals)
• Research how open-source projects solve this (use WebSearch)
• Work backward from failure modes (what could go wrong?)
• Start from the user's perspective (outside-in design)

Scope/territory pool (partition the PROBLEM into non-overlapping regions, then assign one region per agent):

• Data model / schema
• API surface / interface contracts
• Migration / rollout path
• Failure handling / edge cases
• Integration points / dependencies
• Performance / resource profile
• Testing / observability

Select angle axes based on problem type. A performance question benefits from constraint-based divergence. A greenfield feature benefits from method-based divergence. Architectural decisions benefit from all three.

Then assign each agent a non-overlapping scope. A different angle (persona/constraint/method) is not a different territory — without distinct scopes, agents duplicate the same investigation under different framing, the #1 multi-agent failure mode. Pick a partition with enough regions for [N] agents so coverage is maximized per token and no two agents re-derive the same thing. If the problem genuinely doesn't partition cleanly, fall back to angle-only divergence and say so.

Announce:

**Differentiation assignments ([N] agents):**
- Agent 1: [Scope] — [Persona] | [Constraint] | [Method]
- Agent 2: [Scope] — [Persona] | [Constraint] | [Method]
...

PRE-SPAWN CONTEXT DISCOVERY

Before spawning Phase 1 agents, discover codebase context that all agents need:

1. Read project convention files: CLAUDE.md, .claude/CLAUDE.md, README.md, CONTRIBUTING.md
2. Read any design docs or architecture files related to the problem area
3. Condense into a CODEBASE_CONTEXT block (key patterns and constraints, not full file contents — keep it concise to avoid bloating agent prompts)

PHASE 1 — DIVERGENT RESEARCH

Spawn ALL research agents in ONE message using parallel Agent tool calls. Each agent gets subagent_type: "general-purpose".

Agent prompt template (customize per agent):

You are a research agent exploring an approach to the following problem:

## PROBLEM
[Full problem description]

## YOUR ANGLE
- **Scope/territory**: [assigned] — Go DEEP here; assume peers cover the rest of the problem. Do not spread into other agents' territory.
- **Persona**: [assigned] — This shapes your priorities and what you value.
- **Constraint**: [assigned] — This is your primary optimization target.
- **Method**: [assigned] — This is how you should begin your research.

## CODEBASE CONTEXT
[Condensed context block from pre-spawn discovery]

## INSTRUCTIONS
1. **Effort budget**: aim for ~[X] tool calls, scaled to complexity — start with broad exploration, then narrow to specifics. Stop when you have enough to write a complete brief; do not over-search, and do not issue overly-narrow queries that return nothing.
2. Research the problem from your assigned angle, staying inside your scope. You may use WebSearch and WebFetch if external research would strengthen your proposal.
3. Explore the codebase (Read, Grep, Glob) to understand existing patterns, constraints, and relevant code.
4. Produce a research brief in this EXACT format:

### Approach Summary
[2-3 sentences describing your proposed approach]

### Key Decisions
[Numbered list of important design choices and WHY you made each one]

### Trade-offs
[What you're gaining and giving up with this approach]

### Risks
[What could go wrong, what assumptions might not hold]

### Confidence
[HIGH / MEDIUM / LOW] — [1-2 sentence justification]

## RULES
- You are READ-ONLY. Do NOT edit any files. Propose, don't implement.
- Stay in your lane — your angle AND your scope are your strength. Don't try to be all things or cover peers' territory.
- Be specific — reference file paths, function names, existing patterns when relevant.
- If your method involves external research, actually use WebSearch.
- Do NOT invent APIs, benchmarks, library behavior, or numbers. If you assert an external fact, you must have verified it via WebSearch/WebFetch or a file read — otherwise label it explicitly as ASSUMPTION. A fabricated fact here poisons synthesis before any verification runs.
- Your brief should be complete enough that someone could implement from it.

Wait for all agents to return before proceeding to Synthesis.

SYNTHESIS

After all Phase 1 agents return, synthesize their proposals. This is done by you (the parent orchestrator), not by a spawned agent.

Convergence Analysis

1. Agreement points: Where did 2+ agents independently reach the same conclusion? (Strong signal — multiple independent paths converged)
2. Divergence points: Where did agents disagree? Examine WHY:
   • Different optimization targets (expected, both valid) → pick the one that best fits the problem
   • Different facts or assumptions (needs resolution) → investigate which is correct
3. Unique insights: What did only one agent surface? These are the highest-value outputs of divergent thinking — don't discard them just because only one agent found them.

Cross-Pollination (Phase 1.5 — conditional, high-divergence only)

Trigger this ONLY when convergence analysis surfaces genuine, material disagreement — agents reached incompatible conclusions with comparable reasoning, or the decision is trending toward "no convergence." For low-divergence cases, skip straight to Decision Logic; don't pay for a debate round you don't need.

When triggered, run ONE rebuttal round instead of silently picking a winner. Spawn the original Phase 1 agents (or a single reconciliation agent) in ONE message using parallel Agent tool calls, each subagent_type: "general-purpose" and READ-ONLY, given the full set of Phase 1 briefs, the specific points of disagreement, and this instruction:

Here are all the research briefs, including yours. Focus on these disagreements: [list]. Defend or revise your position in light of the peers' reasoning. Concede points where a peer's argument is stronger; hold firm only where you have a concrete reason. Output: which disagreements resolve, which remain genuinely open, and why.

Cap at ONE round — cross-examination beats parallel-solo generation and single-agent reflection, but the gain is bounded and has sharp diminishing returns past a round (and a second round can entrench rather than resolve). Feed the reconciled positions into Decision Logic. If a disagreement survives the rebuttal round, it's a true tension — carry it into "No convergence" honestly rather than forcing a winner.

Decision Logic

• Clear winner: One proposal dominates — most agents converged on it, or it clearly addresses the trade-offs best. Form the draft plan from it, incorporating unique insights from other agents.
• Combination: Different agents got different parts right. Merge the best elements into a coherent plan, noting which elements came from which angle.
• No convergence: Agents genuinely disagree with comparable reasoning. Present the tension to the user with a structured comparison and let them pick a direction (or combine elements) before proceeding to Phase 2. Do NOT force a winner.

Output

Produce a draft plan — the recommended approach with key decisions and rationale. This is the target for Phase 2 verification and attack.

Announce:

**Synthesis complete:**
- **Convergence**: [what agents agreed on]
- **Divergence**: [where they disagreed and resolution]
- **Unique insights incorporated**: [from which agent/angle]
- **Decision**: [Clear winner / Combination / No convergence — awaiting user input]

**Draft plan:**
[The synthesized approach]

If "no convergence" — STOP and present options. Resume when the user chooses.

PHASE 2 — VERIFY + ATTACK

Spawn TWO agents in ONE message using parallel Agent tool calls. Both get subagent_type: "general-purpose". On a Fable-class session (any session model above Opus), spawn both with explicit model: "opus" - adversarial critique is volume work, and two independent attackers beat one merged one; the parent loop (Fable) judges which attacks land when the reports come back.

Verification Agent Prompt

You are the Verification Agent. Validate this draft plan for feasibility, completeness, and correctness.

## DRAFT PLAN
[The synthesized draft plan]

## ORIGINAL PROBLEM
[The problem description]

## INSTRUCTIONS
1. Check technical feasibility — can this actually be built as described?
2. Check codebase compatibility — read relevant files, verify assumptions about existing patterns and code.
3. Identify gaps — things the plan assumes but doesn't address.
4. Check completeness — are there requirements from the problem that the plan doesn't cover?
5. You may use WebSearch/WebFetch to validate technical claims or check library compatibility.

## REPORT FORMAT
### Feasibility: [PASS / CONCERNS]
[Details]

### Codebase Compatibility: [PASS / CONCERNS]
[Details with file:line references]

### Gaps Found
[Numbered list, or "None"]

### Completeness: [PASS / GAPS]
[Details]

### Overall Verdict: [SOUND / NEEDS REVISION / FUNDAMENTALLY FLAWED]

## RULES
- You are READ-ONLY. Do NOT edit any files.
- Be specific — cite file paths, line numbers, function signatures.
- "PASS" means you actively verified it, not that you didn't check.

Devil's Advocate Agent Prompt

You are the Devil's Advocate. Your job is to BREAK this plan. Assume it will fail and work backward to explain why.

## DRAFT PLAN
[The synthesized draft plan]

## ORIGINAL PROBLEM
[The problem description]

## INSTRUCTIONS
1. Assume this plan has been implemented and has FAILED. Work backward: what went wrong?
2. Attack the weakest assumptions — which decisions are the most fragile?
3. Find the strongest counter-argument or alternative approach that the research agents missed entirely.
4. Identify hidden coupling, implicit dependencies, or second-order effects the plan doesn't account for.
5. You may use WebSearch/WebFetch to find counter-evidence or alternative approaches.

## REPORT FORMAT
### Weakest Assumptions
[Numbered list — assumptions most likely to be wrong, with reasoning]

### Attack Vectors
[How this plan fails — concrete failure scenarios]

### Missed Alternative
[The strongest approach the research agents didn't consider, or "None — research was comprehensive"]

### Hidden Risks
[Second-order effects, coupling, dependencies not accounted for]

### Verdict: [PLAN SURVIVES / PLAN NEEDS HARDENING / PLAN IS FLAWED]
[Summary]

## RULES
- You are READ-ONLY. Do NOT edit any files.
- Your goal is to BREAK the plan, not to be helpful. If you can't break it, say so — that's a strong signal.
- Be specific — vague concerns are useless. Show exactly how and why it fails.
- Do NOT just restate risks the research agents already identified. Find NEW ones.

MERGE AND ITERATE

After both Phase 2 agents return:

1. Combine verification gaps and devil's advocate attacks.
2. Update the draft plan:
   • Fix gaps identified by verification agent.
   • Harden against attacks that the devil's advocate landed.
   • Note and rebut attacks that don't hold up.
3. Assess change significance:
   • Significant (structural changes to approach, new components, revised key decisions) → re-run Phase 2 against updated plan.
   • Minor (wording, additional detail, clarification) → finalize and present.
4. Safety cap: 3 Phase 2 rounds maximum. If still not converging, present current state with unresolved tensions noted and let the user decide.

Announce between rounds:

**Phase 2 Round [N] — Plan updated with [N] changes:**
- [Change 1]: [what and why — from verification / devil's advocate]
- [Change 2]: ...
**Assessment**: [Significant — re-running Phase 2 / Minor — finalizing]

FINAL OUTPUT

Present the complete result:

## Swarm Research Complete

**Problem:** [one-line restatement]
**Agents spawned:** [N] researchers + verification + devil's advocate
**Rounds:** Phase 1 (research) → Synthesis → Phase 2 x[N] (verify + attack)

### Convergence Map
- [what agents agreed on]
- [where they diverged and how it was resolved]

### Recommendation
[The pressure-tested plan — approach, key decisions, trade-offs]

### Devil's Advocate Findings
- [critiques raised and how they were addressed or rebutted]

### Confidence
[High / Medium / Low]
[Reasoning — informed by: convergence level, devil's advocate survival, Phase 2 rounds needed]

Do NOT auto-transition to implementation. The user decides what to do next.

Persisting the recommendation

If the user wants to save the swarm output as a referenceable artifact, write it as HTML, not Markdown. Copy ~/.claude/jacked-templates/plan-template.html to docs/superpowers/specs/{YYYY-MM-DD}-{slug}.html and fill it in. The template's Mermaid support is especially useful for convergence/divergence maps and architectural alternatives surfaced during research. Do NOT use Markdown here — swarm outputs are internal specs, not GitHub artifacts.

HARD RULES

• All Phase 1 agents spawn in ONE message (parallel Agent tool calls).
• Cross-Pollination (Phase 1.5) is CONDITIONAL on genuine high divergence and capped at ONE rebuttal round; if it spawns agents, they all go in ONE message and stay READ-ONLY.
• Both Phase 2 agents spawn in ONE message (parallel Agent tool calls).
• All spawned agents use subagent_type: "general-purpose".
• All spawned agents are READ-ONLY — they propose, never implement.
• Do NOT auto-transition to implementation. The user decides next steps.
• Do NOT ask "should I continue?" between phases — always proceed unless "no convergence" requires user input.
• Phase 2 iterates until clean or 3 rounds max. No early stopping.
• Each research agent MUST get a unique differentiation assignment.
• This skill produces a recommendation, NOT an implementation plan. Do not invoke /writing-plans or any implementation skill.
• Keep CODEBASE_CONTEXT concise — key patterns and constraints, not full file contents.