{
  "skill": "alterlab-workflow-orchestration",
  "evals": [
    {
      "id": "parallel-fan-out-citations",
      "prompt": "I have four chapter bibliographies and I want to check them all at once rather than one after another. Can you fan these out to parallel agents that each existence-check one chapter's references, then merge everything into a single report of bad citations?",
      "expected_output": "Invokes alterlab-workflow-orchestration with the parallel fan-out pattern (P1): explains dispatching one subagent per independent bibliography (each in its own context window), has each subagent run the alterlab-citation-verifier skill on a single input and return only its verdict table, then merges into one manuscript-wide report. References that parallel subagents work best when inputs are independent. Provides a copyable delegation prompt and optionally a reusable subagent definition; does not itself perform the verification.",
      "assertions": [
        { "type": "should_trigger", "value": true },
        { "type": "output_contains", "value": "alterlab-citation-verifier" },
        { "type": "behavior", "value": "Treats this as an orchestration question (how to fan out and merge across separate subagents), not as a single verification task, and grounds the parallelism in Claude Code subagent behavior." }
      ]
    },
    {
      "id": "adversarial-verification-debate",
      "prompt": "Before I submit, I want my three biggest empirical claims stress-tested by a separate agent whose whole job is to try to break them and prove the citations don't actually support them. Set up that adversarial verification workflow for me.",
      "expected_output": "Invokes alterlab-workflow-orchestration with the adversarial verification pattern (P4): a FRESH skeptic agent per claim (producer != verifier), tasked solely with finding disconfirming evidence and checking claim-faithfulness via alterlab-citation-verifier (and alterlab-deep-research fact-check mode). Distinguishes 'citation exists' from 'citation supports the claim'. Mentions the agent-team escalation (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS) for sustained debate where agents challenge each other. Returns copyable delegation prompts.",
      "assertions": [
        { "type": "should_trigger", "value": true },
        { "type": "output_contains", "value": "alterlab-citation-verifier" },
        { "type": "output_contains", "value": "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS" },
        { "type": "behavior", "value": "Insists the verifier be a separate/fresh agent from the producer, and frames the workflow around competing-hypotheses / scientific-debate structure rather than answering the factual question itself." }
      ]
    },
    {
      "id": "judge-panel-independent-reviewers",
      "prompt": "I want a manuscript reviewed by three genuinely independent reviewer agents — methodology, domain contribution, and reproducibility — that can't see each other's opinions, and then have their verdicts synthesized into one decision. How do I wire that up?",
      "expected_output": "Invokes alterlab-workflow-orchestration with the judge-panel pattern (P3): spawns three independent reviewer subagents (each its own isolated context so they cannot anchor on each other), keeps them read-only, composes alterlab-paper-reviewer / alterlab-peer-review, and adds a synthesis step that reconciles agreement and disagreement into a single editorial decision. Notes that alterlab-paper-reviewer already runs a panel inside one context, and that this pattern is for genuinely separate agents.",
      "assertions": [
        { "type": "should_trigger", "value": true },
        { "type": "output_contains", "value": "alterlab-paper-reviewer" },
        { "type": "behavior", "value": "Emphasizes independence/isolated contexts to avoid anchoring and adds an explicit synthesis step, rather than just running a single in-context reviewer panel." }
      ]
    },
    {
      "id": "loop-until-clean-revision",
      "prompt": "Can you set up a loop where a reviewer agent comments, the draft gets revised, and it re-reviews only the flagged items, repeating until there are no unresolved comments left — but make sure it actually stops?",
      "expected_output": "Invokes alterlab-workflow-orchestration with the loop-until-clean pattern (P5): a bounded validator->fix->repeat cycle composing alterlab-paper-reviewer/alterlab-peer-review plus a revision step, with BOTH an explicit success gate (zero unresolved comments) AND a max-iteration cap (e.g. 3 rounds) so the loop terminates. Reports rounds taken and residual issues. Provides a copyable loop prompt.",
      "assertions": [
        { "type": "should_trigger", "value": true },
        { "type": "output_contains", "value": "alterlab-paper-reviewer" },
        { "type": "behavior", "value": "Always pairs a success/quality gate with a max-iteration cap so the loop is bounded, and frames it as orchestration of existing review/revise skills." }
      ]
    },
    {
      "id": "near-miss-research-pipeline",
      "prompt": "I want to write a research paper from scratch on the impact of AI tutoring on undergraduate writing — take me all the way from research to a reviewed, revised final manuscript.",
      "expected_output": "Does NOT invoke this skill; defers to alterlab-research-pipeline. The user wants the already-packaged end-to-end research->write->integrity->review->revise flow executed for them, not guidance on how to compose skills into a custom workflow. alterlab-workflow-orchestration is for designing custom multi-agent compositions, not for running the standard pipeline that alterlab-research-pipeline already orchestrates.",
      "assertions": [
        { "type": "should_not_trigger", "value": true },
        { "type": "output_contains", "value": "alterlab-research-pipeline" }
      ]
    },
    {
      "id": "near-miss-single-citation-verifier",
      "prompt": "Here's my reference list — can you just check whether each of these citations actually exists before I submit?",
      "expected_output": "Does NOT invoke this skill; defers to alterlab-citation-verifier. This is a single, self-contained existence-check task with no multi-agent composition, parallelism, panel, or loop involved. alterlab-workflow-orchestration only triggers when the user wants to COMPOSE skills into a multi-agent workflow, not when one atomic skill already does the job.",
      "assertions": [
        { "type": "should_not_trigger", "value": true },
        { "type": "output_contains", "value": "alterlab-citation-verifier" }
      ]
    },
    {
      "id": "near-miss-claude-api-billing",
      "prompt": "How much does the Claude Agent SDK cost per token, and which model id should I use for cheap background subagents?",
      "expected_output": "Does NOT invoke this skill; defers to the claude-api skill. The question is about API/SDK pricing and model-id selection, not about designing an academic multi-agent workflow. alterlab-workflow-orchestration teaches orchestration patterns and composition, and does not answer pricing/model-catalog questions.",
      "assertions": [
        { "type": "should_not_trigger", "value": true },
        { "type": "output_contains", "value": "claude-api" }
      ]
    }
  ]
}

# Claude Code + Agent SDK Orchestration Primitives (verified reference)

Verified against the official documentation on **2026-09-23** (Claude Code v2.1.280):

- `code.claude.com/docs/en/agents` — Run agents in parallel (the overview)
- `code.claude.com/docs/en/sub-agents` — Create custom subagents
- `code.claude.com/docs/en/workflows` — Orchestrate subagents at scale with dynamic workflows
- `code.claude.com/docs/en/agent-teams` — Orchestrate teams of Claude Code sessions
- `code.claude.com/docs/en/plugins-reference` — plugin components, including `workflows`
- `code.claude.com/docs/en/agent-sdk/overview` — Agent SDK

Load this file and quote it rather than restating orchestration mechanics from memory; version
gates are noted inline because the behavior changed several times during 2026.

## Table of Contents

1. [Choosing a mechanism](#1-choosing-a-mechanism)
2. [Subagents](#2-subagents)
3. [Subagent frontmatter fields](#3-subagent-frontmatter-fields)
4. [Built-in subagents](#4-built-in-subagents)
5. [Nesting, background, and fork mode](#5-nesting-background-and-fork-mode)
6. [Dynamic workflows](#6-dynamic-workflows)
7. [Agent teams (experimental)](#7-agent-teams-experimental)
8. [Claude Agent SDK](#8-claude-agent-sdk)
9. [Limits and gotchas](#9-limits-and-gotchas)

---

## 1. Choosing a mechanism

The overview page lists five ways to run work in parallel. The deciding question is **who holds
the plan**:

| Mechanism | Who decides what runs next | Where intermediate results live | Scale |
|---|---|---|---|
| Subagents | Claude, turn by turn | Claude's context (summaries) | a few delegated tasks per turn |
| Agent view (`claude agents`, research preview) | you | each background session | independent sessions you dispatch |
| Agent teams (experimental) | a lead agent, turn by turn | a shared task list + messages | a handful of long-running peers |
| **Dynamic workflows** | **the script** | **script variables** | **dozens to hundreds of agents per run** |
| Projects (claude.ai/code, beta) | Claude, across cloud threads | the project | long-running work over days |

> "A workflow moves the plan into code. … A workflow script holds the loop, the branching, and
> the intermediate results itself, so Claude's context holds only the final answer."

## 2. Subagents

> "Each subagent runs in its own context window with a custom system prompt, specific tool
> access, and independent permissions."

Defined as Markdown files with YAML frontmatter. Scopes, highest priority first: managed
settings, the `--agents` CLI flag (JSON), project `.claude/agents/` (every such directory between
the working directory and the repo root; the closest wins), user `~/.claude/agents/`, and a
plugin's agents (namespaced `plugin-name:agent-name`). Identity comes from the `name` field, which
may not contain `:` (reserved for plugin scoping). `/agents` no longer opens an editor panel
(v2.1.198+); ask Claude or edit the files.

Claude delegates when a task matches a subagent's `description`; you can also name it, @-mention
it, or run a whole session as it with `claude --agent <name>`.

## 3. Subagent frontmatter fields

Only `name` and `description` are required.

| Field | Notes |
|---|---|
| `tools` | Comma-separated string (`Read, Grep, Bash`) or YAML list; inherits all tools if omitted. `allowed-tools` is a **skill** field, not a subagent field |
| `disallowedTools` | Removed from the inherited or listed set |
| `model` | `sonnet`, `opus`, `haiku`, `fable`, a full ID such as `claude-opus-5-5`, or `inherit` |
| `permissionMode` | `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan` (`manual` = `default`, v2.1.200+); **ignored for plugin subagents** |
| `maxTurns` | Cap on agentic turns; output returned as partial and resumable (v2.1.246+) |
| `skills` | Skills preloaded in full at startup; unlisted skills stay invocable via the Skill tool |
| `mcpServers`, `hooks` | Scoped to the subagent; **ignored for plugin subagents** |
| `memory` | `user`, `project`, or `local` persistent memory |
| `background` | Always run in the background |
| `effort` | `low` … `max`, overriding the session effort |
| `isolation` | `worktree` for an isolated git checkout |
| `omitClaudeMd` | Start without CLAUDE.md files (v2.1.271+) |
| `color`, `initialPrompt`, `experimental.cacheTtl` | Display color; first turn when run via `--agent` (ignored for plugin subagents); prompt-cache TTL `5m`/`1h` (v2.1.248+) |

> "Subagents receive only this system prompt (plus basic environment details like working
> directory), not the full Claude Code system prompt."

## 4. Built-in subagents

| Agent | Model | Tools | Purpose |
|---|---|---|---|
| **Explore** | inherits the main model (v2.1.198+; on the Claude API capped at Opus) | read-only | file discovery, code search |
| **Plan** | inherits | read-only | research for plan mode |
| **general-purpose** | inherits | all | multi-step exploration and action |

Explore and Plan skip CLAUDE.md. To keep exploration cheap, define a project subagent named
`Explore` with `model: haiku` — it overrides the built-in.

## 5. Nesting, background, and fork mode

- **Nesting is on.** "By default, a subagent can spawn subagents of its own, up to three layers
  below the main conversation." Change with `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` (`1` turns
  nesting off). Keep a subagent from spawning by omitting `Agent` from its `tools`. (History:
  five layers fixed in v2.1.172–216; one layer in v2.1.217–218; three since v2.1.219.)
- **Fork mode** is on by default in interactive sessions (v2.1.232+) and off in `-p` and the
  Agent SDK; `CLAUDE_CODE_FORK_SUBAGENT=1|0` overrides. With it on, Claude can spawn a `fork`
  subagent that inherits the whole conversation (and reuses its prompt cache), and all subagents
  run in the background. Start a forked subagent yourself with `/subtask` (or `/fork` when agent
  view is off); with agent view on, `/fork` copies the session into a new background session.
- **Background vs. foreground**: background subagents run concurrently with permissions already
  granted; `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1` forces the foreground.

## 6. Dynamic workflows

> "A dynamic workflow is a JavaScript script that orchestrates many subagents at once. Claude
> writes the script for the task you describe, and a runtime executes it in the background while
> your session stays responsive."

- **Availability:** all paid plans, API access, Bedrock, Google Cloud, Foundry; on Pro, enable in
  `/config`. Disable with `disableWorkflows` / `CLAUDE_CODE_DISABLE_WORKFLOWS=1`.
- **Starting one:** ask for a workflow in your own words, include the keyword `ultracode`, or set
  `/effort ultracode` (v2.1.203+) so Claude plans workflows for every substantive task. Bundled:
  `/deep-research <question>`.
- **Saved workflows:** from `/workflows`, press `s` to save a run's script to
  `.claude/workflows/` (shared with the repo) or `~/.claude/workflows/`; it then runs as
  `/<name>`. **Plugins** ship scripts in a `workflows/` directory (or the `workflows` manifest
  field); they run as `/<plugin>:<meta.name>` — e.g. `/alterlab-workflows:citation-audit`.
- **Script shape:** `export const meta = { name, description, whenToUse?, phases? }` must be the
  first statement and a pure literal. The body is plain JavaScript with top-level `await`:
  `agent(prompt, {schema?, label?, phase?, model?, effort?, isolation?, agentType?})`,
  `parallel(thunks)` (barrier), `pipeline(items, ...stages)` (no barrier), `phase()`, `log()`,
  the `args` global, `budget`, and one-level `workflow()` composition. A `schema` makes the agent
  return validated JSON. `Date.now()`, `Math.random()`, argless `new Date()`, and `import()` are
  unavailable (they would break resume); there is no direct filesystem access — agents read and
  write files.
- **Approval:** a per-run prompt lists the phases (auto mode asks once); in `-p`/SDK use a
  `Workflow` or `Workflow(<name>)` allow rule.
- **Limits:** up to 16 concurrent agents by default (`CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS`,
  v2.1.269+), 4,096 items per `parallel()`/`pipeline()` call, 1,000 agents per run. A size
  guideline (`workflowSizeGuideline`: small < 5, medium < 10, large < 50 agents; default medium)
  steers how big Claude writes them. No mid-run user input: for sign-off between stages, run each
  stage as its own workflow.
- **Resume:** relaunching a stopped run in the same session replays finished agents from cache.

## 7. Agent teams (experimental)

> "Agent teams are experimental and disabled by default. Enable them by setting
> `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`."

A lead session coordinates teammates (separate Claude Code instances, each with its own context)
through a shared task list and direct messaging; you can talk to teammates directly. Teams need an
interactive session — in `-p` and the SDK a named subagent runs as an ordinary subagent. While
enabled, a subagent that Claude *names* launches as a teammate, so teams can form unasked.

The docs' adversarial example (verbatim):

> "Spawn 5 agent teammates to investigate different hypotheses. Have them talk to each other to
> try to disprove each other's theories, like a scientific debate. Update the findings doc with
> whatever consensus emerges."

Teams "use significantly more tokens than a single session"; for sequential or tightly coupled
work, a single session or subagents are more effective.

## 8. Claude Agent SDK

> "The Agent SDK gives you the same tools, agent loop, and context management that power Claude
> Code, programmable in Python and TypeScript."

- Python `claude-agent-sdk` (`query(...)` + `ClaudeAgentOptions`); TypeScript
  `@anthropic-ai/claude-agent-sdk` (`query({ prompt, options })`).
- Subagents: the `agents` option maps names to `AgentDefinition(description, prompt, tools)`;
  include `"Agent"` in `allowed_tools` to auto-approve delegation. Messages from a subagent carry
  `parent_tool_use_id`.
- Sessions: capture `session_id` from the `init` message and `resume` it.
- The SDK loads `.claude/` configuration by default (restrict with `setting_sources` /
  `settingSources`); fork mode and agent teams are off by default there; workflows run through
  the same `Workflow` tool with permission rules instead of a prompt.

```python
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Use the methodology-reviewer agent to review paper.md",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Agent"],
            agents={
                "methodology-reviewer": AgentDefinition(
                    description="Reviews study design, measurement, and analysis choices.",
                    prompt="Review the methods of the manuscript you are given; quote the text you critique.",
                    tools=["Read", "Glob", "Grep"],
                )
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())
```

## 9. Limits and gotchas

- **Fresh context:** a non-fork subagent sees only its delegation prompt — pass the paths,
  criteria, and output format it needs.
- **Results re-enter context:** many verbose subagents still flood the main conversation; ask
  for summaries, or move the loop into a workflow so intermediate results stay in script variables.
- **Plugin subagents ignore** `permissionMode`, `hooks`, `mcpServers`, and `initialPrompt`.
- **Teams:** one team per session, no nested teams, fixed lead, no resumption of in-process
  teammates, split panes need tmux or iTerm2.
- **Workflows:** no mid-run input, no filesystem access from the script, deterministic scripts
  only (no clock or randomness).
- **Match degrees of freedom to fragility:** prose for open exploration; explicit ordered stages,
  a stop condition, and an iteration cap for fragile sequences.

# Composition Recipes — Wiring AlterLab Skills into Workflows (P1–P5)

Five worked recipes, one per pattern in SKILL.md. Each gives a copyable
delegation prompt, the subagent mechanism it uses, and the real AlterLab skills
it composes. Orchestration mechanics are verified in
`references/claude-orchestration-primitives.md`. The skills referenced here are
real and present in this suite:

- `alterlab-research-pipeline` — packaged 9-stage research→write→review flow
- `alterlab-deep-research` — multi-agent research / lit-review / fact-check
- `alterlab-citation-verifier` — existence-check citations against scholarly APIs
- `alterlab-paper-reviewer` — 5-reviewer panel (core)
- `alterlab-peer-review` — peer-review skill (writing-tools)

**Packaged as dynamic workflows.** Four of these recipes also ship ready to run in the
`alterlab-workflows` plugin (Claude Code): P1 + P4 → `/alterlab-workflows:citation-audit`,
P3 → `/alterlab-workflows:review-panel`, P4 → `/alterlab-workflows:claim-stress-test`, and
the dual-coder variant of P3 → `/alterlab-workflows:systematic-review-screening`. Their
scripts (`skills/workflows/workflows/*.js`) are readable starting points when a recipe needs
to become a rerunnable workflow; use the prompts below when a few subagents in one
conversation are enough.

## Table of Contents

- [P1 — Parallel fan-out: batch citation verification](#p1--parallel-fan-out-batch-citation-verification)
- [P2 — Sequential pipeline: custom research→verify→review chain](#p2--sequential-pipeline-custom-researchverifyreview-chain)
- [P3 — Judge panel: independent reviewer subagents](#p3--judge-panel-independent-reviewer-subagents)
- [P4 — Adversarial verification: produce then break](#p4--adversarial-verification-produce-then-break)
- [P5 — Loop until clean: revise→re-review cycle](#p5--loop-until-clean-reviserereview-cycle)
- [Scripting it with the Agent SDK](#scripting-it-with-the-agent-sdk)
- [Anti-patterns](#anti-patterns)

---

## P1 — Parallel fan-out: batch citation verification

**Mechanism**: parallel subagents (one per independent input). **Composes**:
`alterlab-citation-verifier`.

When inputs are independent, dispatch one worker per input so each verbose API
session stays in its own context window, then merge.

```text
I have 4 chapter reference lists (chapter1.bib … chapter4.bib). Verify them in
parallel using separate subagents — each subagent runs the
alterlab-citation-verifier skill over exactly one .bib file and returns only its
per-entry verdict table. When all four finish, merge the tables into one
manuscript-wide report and flag every TF / IH / SH entry across all chapters.
Do not start any chapter's analysis until the inputs are split.
```

Optionally pin the worker as a reusable subagent definition
(`.claude/agents/cite-checker.md`):

```markdown
---
name: cite-checker
description: Existence-checks one bibliography file against scholarly APIs. Use proactively when verifying references in parallel.
tools: Read, Bash, WebFetch, WebSearch
model: inherit
skills:
  - alterlab-citation-verifier
---

Run the alterlab-citation-verifier workflow over the single bibliography file
named in the task. Return ONLY the per-entry verdict table — no preamble.
```

Stop condition: every input has a verdict; merge is a single table. This honors
the docs' rule that parallel research "works best when the research paths don't
depend on each other."

## P2 — Sequential pipeline: custom research→verify→review chain

**Mechanism**: subagent chaining (each stage's summary feeds the next).
**Composes**: `alterlab-deep-research` → `alterlab-citation-verifier` →
`alterlab-peer-review`.

> First check whether `alterlab-research-pipeline` already covers the need — it
> packages research→write→integrity→review→revise. Use this custom chain only
> when the user's flow differs (e.g. they bring their own draft, or want
> verification *between* synthesis and review).

```text
Build a 3-stage pipeline on the topic "micro-credentials in vocational
education", carrying forward only each stage's summary:
1. Use alterlab-deep-research in lit-review mode to produce a thematic synthesis
   + annotated bibliography.
2. Chain that bibliography into alterlab-citation-verifier; existence-check every
   entry and drop or flag anything that is NOT_FOUND.
3. Pass the verified synthesis to alterlab-peer-review for a section-by-section
   critique with a revise/accept recommendation.
Report the three summaries plus a final go/no-go.
```

Each handoff passes only the relevant artifact (synthesis, verdict table,
critique), not the full transcript — subagents start fresh, so the delegation
prompt must carry the needed context.

## P3 — Judge panel: independent reviewer subagents

**Mechanism**: parallel subagents (independent contexts) + a synthesis step.
**Composes**: `alterlab-paper-reviewer` and/or `alterlab-peer-review`.

`alterlab-paper-reviewer` already simulates a 5-reviewer panel **inside one
context**. Use this pattern instead when independence matters — separate agents
that cannot anchor on each other's opinions.

```text
Review manuscript.pdf with an independent panel. Spawn three separate reviewer
subagents, each working from the paper alone with no knowledge of the others:
- Reviewer A: methodology and statistics rigor
- Reviewer B: domain contribution and novelty
- Reviewer C: reproducibility (data/code availability, reporting standards)
Each returns an independent verdict + top-3 issues. Then synthesize a single
editorial decision that explicitly notes where the three agree and disagree.
```

Why independent agents: running all three in one context lets the first opinion
anchor the others. For a panel that should also **debate**, escalate to an agent
team (P4). Keep each reviewer read-only (`tools: Read, Grep, Glob`) so none can
edit the manuscript.

## P4 — Adversarial verification: produce then break

**Mechanism**: a fresh skeptic subagent per claim; or an agent team for sustained
debate. **Composes**: `alterlab-citation-verifier` (claim-faithfulness) +
`alterlab-deep-research` (fact-check mode).

The single highest-value integrity pattern: the producer and the verifier must be
**different agents** so the verifier has no stake in the claim being true.

Subagent form (per-claim skeptic):

```text
Extract the three headline empirical claims from my draft. For EACH claim, spawn
a skeptic subagent whose only job is to disprove it:
- search for disconfirming evidence (alterlab-deep-research fact-check mode), and
- check the cited source actually supports the claim, not just that it exists
  (alterlab-citation-verifier claim-faithfulness).
Report each claim as SURVIVES or BREAKS with the evidence. Treat "real citation"
and "citation supports the claim" as separate questions.
```

Agent-team form (debate), gated behind
`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`:

```text
Create an agent team of 3 teammates to stress-test my draft's central argument.
Each teammate adopts a competing interpretation of the evidence and they talk to
each other to try to disprove each other's reading, like a scientific debate.
Converge on which interpretation the evidence actually supports and write the
consensus (and any unresolved disagreement) to a findings doc.
```

This mirrors the docs' competing-hypotheses example verbatim in structure. Agent
teams cost significantly more tokens — reserve for high-stakes claims.

## P5 — Loop until clean: revise→re-review cycle

**Mechanism**: bounded validator→fix→repeat loop in the main conversation.
**Composes**: `alterlab-paper-reviewer` (or `alterlab-peer-review`), plus the
revision step.

```text
Run a bounded revision loop on draft.md:
1. alterlab-paper-reviewer produces reviewer comments.
2. Revise the draft to address every actionable comment.
3. Re-review ONLY the previously-flagged items (verification pass).
4. Repeat from step 2 until there are zero unresolved comments OR after at most
   3 rounds.
Then stop and report: rounds taken, comments resolved, and any residual issues
you could not fix. Do not loop indefinitely.
```

Two non-negotiables: an explicit **success gate** (zero unresolved comments) AND a
**max-iteration cap** (3 rounds). Open loops burn context and tokens. The same
shape works for verify→fix→re-verify until a bibliography is 100% resolvable.

## Scripting it with the Agent SDK

To run P1/P3 in CI or a batch job, the Python Agent SDK (`claude-agent-sdk`,
Python 3.10+) expresses the same delegation. `query()` runs the agent loop; the
`agents` option defines the workers; `"Agent"` in `allowed_tools` auto-approves
delegation. (Per-skill skill-loading is configured via your `.claude/` settings,
which the SDK loads by default.)

```python
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt=(
            "Review manuscript.pdf with an independent panel: a methodology "
            "reviewer, a domain reviewer, and a reproducibility reviewer, each "
            "working from the paper alone. Then synthesize one editorial decision."
        ),
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Agent"],
            agents={
                "methodology-reviewer": AgentDefinition(
                    description="Reviews methodology and statistical rigor only.",
                    prompt="Critique methods and statistics. Report a verdict + top-3 issues.",
                    tools=["Read", "Grep", "Glob"],
                ),
                "domain-reviewer": AgentDefinition(
                    description="Reviews domain contribution and novelty only.",
                    prompt="Assess contribution and novelty. Report a verdict + top-3 issues.",
                    tools=["Read", "Grep", "Glob"],
                ),
                "repro-reviewer": AgentDefinition(
                    description="Reviews reproducibility and reporting standards only.",
                    prompt="Check data/code availability and reporting. Report a verdict + top-3 issues.",
                    tools=["Read", "Grep", "Glob"],
                ),
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())
```

TypeScript is equivalent via `@anthropic-ai/claude-agent-sdk` (`query({ prompt,
options: { allowedTools, agents } })`). Capture `session_id` from the `init`
system message and pass `resume=session_id` to continue a multi-turn pipeline.

## Anti-patterns

- **Rebuilding a packaged skill.** If the user wants research→write→review, use
  `alterlab-research-pipeline`; don't hand-wire the whole chain.
- **Producer = verifier.** Adversarial verification only works when a fresh agent
  checks the claim (P4). Self-checking re-confirms the original bias.
- **Unbounded loops.** Always pair a success gate with a max-iteration cap (P5).
- **Over-parallelizing dependent work.** Parallel fan-out needs independent
  inputs; chained stages must run sequentially.
- **Fat handoffs.** Pass each stage's summary, not the entire transcript —
  subagents start fresh and the delegation prompt is the channel.
- **Reaching for agent teams by default.** They cost significantly more tokens;
  use subagents unless the workers genuinely need to message each other.