Web Research Studio — instructions for Claude

This repo is a Claude Code-native multi-agent web research pipeline. The user runs it via skills (invoked as slash commands); you orchestrate.

What this project is

A pipeline that takes a free-form research topic and produces a markdown report with real citations — every claim tied to a URL the agents actually fetched in this run. It is explicitly not a "summarize from your training data" tool.

The pipeline runs symmetrically on Claude Code desktop CLI and on claude.ai/code (web), with a few graceful-degradation rules baked into the agents.

Main rule

Before giving any answer or decision, think about how you will test and prove that it is correct.

Pipeline at a glance

The pipeline is an adaptive plan → fan-out → reflect → drill-or-synth loop running in the main session. The user invokes one of three skills:

• /research <topic> [--depth N --breadth M --max-dispatches X --mode <lite|standard|deep>] — main entry point. Defaults depth=2 breadth=4 max-dispatches=15 mode=standard.
• /analyst <topic> — conversational. Turn 1 = /research auto-pass (default standard; --lite locks lite params: depth=1 breadth=2 max-dispatches=5 mode=lite). Per-turn drills classified as synthesis Q / clarification / verify / new angle / deep drill. Umbrella mode (--umbrella <id> --angle <slug>, --merge <id>) enables multi-session parallelism. --translate <lang> for post-pipeline translation.

The main session dispatches general-purpose subagents with role-specific prompt fragments inlined into each dispatch's prompt body. There are no persistent .claude/agents/*.md files — each dispatch specifies its model and inherits all tools. Reasoning roles (reflector, synthesizer, merger) use model: "opus"; fetching/rote roles (planner, scout, drill, translator) use model: "sonnet".

The dispatch steps:

1. planner.md — Layer 0: produces breadth angles + authoritative sources.
2. scout.md — Layer 1: one worker per angle, in parallel. Each scout self-rates coverage_score.
3. reflector.md — reads all findings, decides drill vs synthesize, writes targeted drill questions. Opus.
4. (Loop steps 2–3 until coverage_score ≥ threshold OR depth == max_depth OR dispatch_count >= max_dispatches.)
5. synthesizer.md — composes the final report with the density contract. Opus.
6. (Umbrella only:) merger.md — cross-session synth across reports/umbrellas/<id>/angle_*/. Opus.

Reports land in reports/<run-id>.md. Intermediate artifacts in reports/.work/<run-id>/. Umbrella artifacts in reports/umbrellas/<id>/.

Why no persistent agent files? Per-dispatch model and tool specification keeps each call explicit and self-contained — no shared agent definition to forget to update when a role's contract changes.

Why no research-orchestrator agent? CC v2.1.x forbids nested subagent dispatch. The orchestration logic lives in the skill body (/research/SKILL.md) and runs in the main session.

Why general-purpose subagents don't call Write. CC platform-level enforcement returns a tool_use_error when ANY general-purpose subagent invokes Write (scouts, drills, translators alike — the error text "Subagents should return findings as text..." is platform-generated). Every worker returns its full output as its final response text; the main session persists it via Write({ file_path, content: <verbatim worker response text> }). The orchestrator must NEVER paraphrase, abridge, or "tidy up" the worker's response between receiving it and writing it — that is a bug, not a feature. Mention this constraint explicitly in each dispatch's prompt body so workers don't waste a tool slot trying Write.

Hard rules — apply these in every research run

1. Never produce a claim without a source URL fetched in this run. No "as is well known". No URLs from training data.
2. Run the planner (Layer 0) first. Skipping it = surface-level results.
3. Spawn workers in parallel from the main session — multiple Agent tool calls in one message — whenever fanning out (Layer 1 scouts; Layer 2+ drills). Sequential dispatch wastes wall-clock time.
4. Reasoning roles run on Opus. Every Agent({subagent_type: "general-purpose", ...}) dispatch specifies an explicit model: field. Pass model: "opus" for reflector, synthesizer, merger. Pass model: "sonnet" for planner, scout, drill, translator.
5. Stay within tool budgets per role: planner 1/2/0, scout 4/8/3, reflector 0/0/0, drill 2/5/2, synth 0/0/0, merger 0/0/0 (WebSearch / WebFetch / Playwright deep).
6. Output language matches input language — don't translate.
7. Reports are immutable once written. To re-run, generate a new RUN_ID.
8. Honor the hard cap. Before each fan-out, check dispatch_count + planned <= max_dispatches. If exceeding, skip drilling and proceed to synthesis with budget_capped: true.
9. Verbatim worker-text → file Write. When a worker's contract is "final response IS the file" (scout findings, drill findings, translator output), the orchestrator MUST write the worker's response text byte-for-byte. No paraphrasing, no abridging, no "cleanup", no fixing of stray preambles. If a worker violates its no-preamble contract, surface it and re-dispatch — do not silently edit. This rule's failure mode is amplified in parallel batches (e.g., umbrella batch-translate), where multiple long worker outputs in the orchestrator's context tempt the model to "process" them.

Files you'll touch

• .claude/skills/research/SKILL.md — the adaptive-loop orchestrator. The main entry point.
• .claude/skills/research/prompts/{planner,scout,reflector,synthesizer}.md — role-specific worker prompts inlined into each dispatch.
• .claude/skills/analyst/SKILL.md — conversational drill skill (--lite, --deep, umbrella, --translate modes).
• .claude/skills/analyst/prompts/merger.md — cross-session umbrella synthesizer prompt.
• .claude/skills/analyst/prompts/translator.md — post-pipeline translation prompt.
• tools/searxng_query.py — stdlib-only SearXNG fallback search backend.
• config/searxng-instances.txt — public SearXNG instance list.
• reports/<run-id>.md — final report (immutable).
• reports/.work/<run-id>/ — per-run scratch (grounding, findings, reflections).
• reports/umbrellas/<umbrella-id>/ — multi-session shared state (manifest, per-angle subdirs, merged.md).

When the user asks general questions about the repo

Don't run the pipeline. Read this file and the relevant agent prompt. Answer concisely.

When something fails

• Search backend down: workers auto-fall-back from searxng_query.py → WebSearch → authoritative-list fetches. Don't try to fix the backend; just log and continue.
• A worker hits a tool budget: that worker stops, writes what it has, and reports back. Other workers continue. The synthesizer marks the gap in the report's "Open questions" section. Do not silently overrun budgets.
• Hard dispatch cap reached: skip remaining drills and proceed to synthesis with budget_capped: true in the reflector output.