A demo showing how Claude Code subagents collaborate to build a comprehensive document from raw data — without a human writing a single sentence.
This repo contains everything needed to demonstrate a multi-agent document authoring workflow using Claude Code's subagents. Five specialized agents coordinate via the Task tool to transform raw research data into a polished industry report:
You (Human)
│
▼
┌─────────────┐
│ Architect │ ◄── You talk to this agent. It runs the show.
└──────┬──────┘
│ Uses the Task tool to spawn subagents, collects results between phases
│
├── Phase 1: Research
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
├──►│ Researcher 1 │ │ Researcher 2 │ │ Researcher 3 │ (parallel subagents)
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ └──── results return to Architect ───┘
│ ▼
├── Phase 2: Design ┌──────────────┐
├────────────────────►│ Designer │
│ └──────┬───────┘
│ returns outline
│ ▼
├── Phase 3: Writing
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐
├──►│ Writer §1 │ │ Writer §2 │ │ Writer §3 │ │ Writer §N │ (parallel subagents)
│ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘
│ └──── results return to Architect ────────────┘
│ ▼
├── Phase 4: Editing ┌──────────────┐
├────────────────────►│ Editor │ ── consistency, dedup, polish
│ └──────┬───────┘
│ returns revised doc
│ ▼
└── Phase 5: Delivery ──► output/report.md ──► You
Document: "The State of AI in Healthcare 2026" — a comprehensive industry report
Raw data (all fabricated for this demo):
| File | Description |
|---|---|
data/survey_results.csv |
Survey of 50 healthcare organizations on AI adoption |
data/market_analysis.json |
Market sizing, growth rates, investment data, competitive landscape |
data/case_studies.md |
5 detailed case studies of AI deployments in healthcare |
data/regulatory_filings.md |
FDA authorizations, state legislation, international regulatory comparison |
data/expert_interviews.md |
Interview transcripts with 5 industry experts |
data/clinical_trials.csv |
15 AI-related clinical trials with status and interim results |
data/technology_trends.md |
Technical landscape: LLMs, multimodal AI, federated learning, edge AI |
All agent definitions live in .claude/agents/:
- Entry point for the human user
- Coordinates the full 5-phase workflow
- Delegates to all other agents via Task tool subagent calls
- Never writes document content itself
- Reads and analyzes raw data files
- Extracts statistics, trends, quotes, and examples
- Produces structured research summaries to
output/research/ - Multiple instances run in parallel on different data sources
- Takes research summaries and designs the document outline
- Defines sections, assigns content to each, and prevents duplication
- Specifies tone, audience, word counts, and transitions
- Produces the blueprint that writers follow
- Writes one section of the document at a time
- Receives the full outline (for context) plus section-specific research
- Multiple instances run in parallel on different sections
- Stays strictly within content boundaries to avoid duplication
- Reviews the complete assembled document
- Scans for duplication, inconsistency, and flow problems
- Fixes issues directly and reports what changed
- Makes the patchwork read like a single-author document
- Claude Code installed and configured
- Clone this repo
- Open it in Claude Code:
claude - Start the Architect agent:
/agents architect - Give it a prompt like:
Build me a comprehensive report on "The State of AI in Healthcare" using the data in the data/ directory. The audience is healthcare executives. Tone should be professional but accessible. - Watch the agents work through the 5 phases
- Find the finished report in
output/report.md
The Architect will:
- Research phase — Launch 3-4 Researcher subagents in parallel, each analyzing different data files and writing summaries to
output/research/ - Design phase — Launch a Designer subagent that reads all research and produces an outline at
output/outline.md - Writing phase — Launch one Section Writer subagent per section in parallel, each writing to
output/sections/ - Editing phase — Assemble the draft at
output/draft.md, then launch an Editor subagent for consistency review and polish - Delivery phase — Copy the final document to
output/report.mdand present a summary
Researchers work simultaneously on different data sources. Writers work simultaneously on different sections. The work that can be parallelized is parallelized — by launching multiple Task tool calls in a single response.
Each agent has a clear, bounded responsibility:
- Researchers don't write prose
- The Designer doesn't analyze data
- Writers don't decide what to cover
- The Editor doesn't add new content
The biggest risk in multi-agent document creation is content duplication. This is addressed at two levels:
- The Designer explicitly assigns every piece of content to exactly one section
- The Editor scans the assembled document and removes any duplication that slipped through
The Editor can flag sections needing revision. The Architect can re-launch Section Writer subagents for specific sections, then re-edit. Quality emerges from the loop, not from any single agent being perfect.
authorless-docs/
├── .claude/
│ ├── settings.json # Permissions config for subagents
│ └── agents/
│ ├── architect.md # Orchestrator agent
│ ├── researcher.md # Data analysis subagent
│ ├── designer.md # Document structure subagent
│ ├── section-writer.md # Content writing subagent
│ └── editor.md # Review & consistency subagent
├── data/
│ ├── survey_results.csv # Healthcare AI adoption survey
│ ├── market_analysis.json # Market sizing & investment data
│ ├── case_studies.md # Real-world deployment case studies
│ ├── regulatory_filings.md # Regulatory landscape data
│ ├── expert_interviews.md # Expert interview transcripts
│ ├── clinical_trials.csv # AI clinical trial tracker
│ └── technology_trends.md # Technical landscape overview
├── output/ # All generated files go here
│ ├── research/ # Research summaries (Phase 1)
│ ├── sections/ # Individual sections (Phase 3)
│ ├── outline.md # Document outline (Phase 2)
│ ├── draft.md # Assembled draft (Phase 4)
│ ├── edited.md # Editor's revised draft (Phase 4)
│ ├── editorial-report.md # Editor's change log (Phase 4)
│ ├── report.md # Final deliverable (Phase 5)
│ └── .gitkeep
└── README.md # You are here
Claude Code's subagents let you spawn focused worker agents within your session using the Task tool. Each subagent:
- Has its own context window — it runs independently with the prompt you give it
- Returns results directly to the calling agent when finished
- Can read and write files — subagents write their outputs to disk so other phases can use them
- Runs with the agent persona defined in
.claude/agents/Markdown files
Agents are defined as Markdown files in .claude/agents/. Each agent:
- Has a system prompt (the Markdown content) that defines its role, capabilities, and instructions
- Can be invoked directly by the user with
/agents <name> - Can be spawned as a subagent by another agent using the Task tool
- Orchestrator pattern — The Architect coordinates all others, acting as the single point of control
- Fan-out/fan-in — Multiple Researcher or Writer subagents run in parallel, then their outputs are collected
- Pipeline pattern — Data flows through stages: Research → Design → Writing → Editing → Delivery
- Quality gate — The Editor acts as a gate before delivery, sending work back if quality is insufficient
- File-based handoff — Subagents share work products through files in
output/, keeping context windows lean
Replace the files in data/ with data about any topic. The agents are designed to work with whatever data they're given. The Architect will adapt its approach based on what's available.
Modify section-writer.md and editor.md to output a different format (e.g., HTML, LaTeX, presentation outline).
Some ideas:
- Fact-checker agent — Verifies claims against source data
- Visualization agent — Suggests or generates charts and diagrams
- Summarizer agent — Creates an executive brief from the full report
- Translator agent — Produces the report in multiple languages