Alterlab workflow orchestration

Workflow Orchestration — Compose AlterLab Skills into Multi-Agent Workflows

This skill is the orchestration layer. It does not do research, write, or review itself — it teaches how to wire the skills that do into agentic workflows using Claude Code's native subagent machinery and the Claude Agent SDK. Pick a pattern, point it at real AlterLab skills, copy the delegation prompt.

The five patterns below are the high-leverage shapes for academic work: fan-out parallel investigation, a sequential pipeline, a judge panel, adversarial verification, and a loop-until-clean review cycle. Each is grounded in the current docs (see references/claude-orchestration-primitives.md for the verified primitives, and references/composition-recipes.md for full worked recipes with copyable prompts).

When to Use This Skill

Use this skill when the user wants to:

• Run several AlterLab skills at once over independent inputs (e.g. verify 4 bibliographies, or research 3 sub-questions in parallel) and merge the results
• Chain skills into a pipeline where each stage hands off to the next
• Get multiple independent perspectives on one artifact (a judge / reviewer panel)
• Adversarially verify an output — one agent produces, a fresh agent tries to break it
• Iterate a loop until a quality gate passes (e.g. re-review until zero unresolved comments)
• Understand Claude Code subagents, agent teams, forks, or the Agent SDK well enough to author their own academic orchestration

Does NOT Trigger

Scenario	Use Instead
The user wants the full research→write→review pipeline run for them	alterlab-research-pipeline (it already orchestrates the 9-stage flow)
The user wants original research / a cited report	alterlab-deep-research
The user wants one manuscript peer-reviewed	alterlab-paper-reviewer or alterlab-peer-review
The user wants citations existence-checked	alterlab-citation-verifier
The user asks about Claude API pricing / model ids / SDK billing	the claude-api skill

This skill is for how to compose; the named skills are what to compose. If a single existing skill already does the job end to end, defer to it.

Verified Orchestration Primitives (Claude Code + Agent SDK)

All claims below are verified against code.claude.com/docs on 2026-06-08. See references/claude-orchestration-primitives.md for quotes and field tables.

• Subagents are Markdown + YAML files in .claude/agents/ (project) or ~/.claude/agents/ (user). Only name and description are required; optional fields include tools, disallowedTools, model (sonnet/opus/haiku/full id/inherit), permissionMode, skills, and background. Each subagent runs in its own context window and returns only a summary to the main conversation. Claude auto-delegates by matching the task to the subagent's description.
• Subagents cannot spawn other subagents (no nesting). For nested delegation, chain from the main conversation or use Skills. Built-in subagents: Explore (read-only, Haiku), Plan (read-only), general-purpose (all tools).
• Parallel fan-out: ask the main agent to run independent investigations "in parallel using separate subagents"; results return and the main agent synthesizes. Chaining: ask it to use subagent A, then pass results to subagent B.
• Background vs foreground: background subagents run concurrently and auto-deny prompts; foreground blocks and passes prompts through.
• Agent teams (experimental, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, v2.1.32+) differ from subagents: teammates have independent contexts, a shared task list, and message each other directly — ideal for adversarial debate. Recommended size 3–5; higher token cost.
• Forks (/fork, CLAUDE_CODE_FORK_SUBAGENT=1, v2.1.117+): a subagent that inherits the full conversation instead of starting fresh — cheap because it reuses the parent prompt cache.
• Claude Agent SDK (Python claude-agent-sdk, TypeScript @anthropic-ai/claude-agent-sdk) packages the same agent loop programmatically via query(...) with ClaudeAgentOptions/options; define subagents through the agents option (AgentDefinition), and capture/resume session_id for multi-turn state. Use it to script the patterns below in CI or batch jobs.

The Five Patterns

1. Parallel fan-out (map)

When N inputs are independent, dispatch one worker per input and merge. Classic academic uses: verify several bibliographies at once, or research distinct sub-questions concurrently.

I have 4 reference lists (one per chapter). Verify them in parallel using
separate subagents — each subagent runs the alterlab-citation-verifier skill
on one list — then merge the per-entry verdicts into one table flagging every
TF/IH/SH problem across all four chapters.

Why subagents: each verification floods context with API lookups you won't reuse; isolating each in its own window keeps the main conversation clean. Best when paths don't depend on each other (the docs' stated condition for parallel research). See recipe P1 in references/composition-recipes.md.

2. Sequential pipeline (chain)

Stage outputs feed the next stage. The canonical academic chain — research → write → integrity-check → review → revise — is already packaged as alterlab-research-pipeline; prefer that skill rather than rebuilding it. Use this pattern when you need a custom chain it doesn't cover, e.g. deep-research → citation-verifier → peer-review on an externally supplied draft.

Use the alterlab-deep-research skill to produce a lit-review synthesis on X,
then chain its bibliography into alterlab-citation-verifier to existence-check
every entry, then pass the verified draft to alterlab-peer-review for a
section-by-section critique. Carry forward only each stage's summary.

See recipe P2 in references/composition-recipes.md.

3. Judge panel (independent multi-perspective)

Several independent reviewers each apply a different lens to one artifact, then a synthesizer reconciles. alterlab-paper-reviewer already simulates a 5-reviewer panel internally; use this pattern when you want the panelists to be genuinely separate agents (separate contexts, no cross-contamination) — e.g. a methodology reviewer, a domain reviewer, and a reproducibility reviewer that must not anchor on each other.

Spawn three independent reviewer subagents on this manuscript: one on
methodology, one on domain contribution, one on reproducibility/statistics.
Each works from the paper alone and reports independently; then synthesize a
single editorial decision noting where they agree and disagree.

Independence is the point — running them in one context lets the first opinion anchor the rest. See recipe P3 in references/composition-recipes.md.

4. Adversarial verification (produce → break)

One agent produces a claim or result; a fresh agent is tasked solely with disproving it. This is the highest-value pattern for research integrity. The docs' competing-hypotheses agent-team example is the reference implementation: teammates "talk to each other to try to disprove each other's theories, like a scientific debate."

Take the three headline claims in my draft. For each, spawn a skeptic subagent
whose only job is to find disconfirming evidence and check the supporting
citation actually supports the claim (via alterlab-citation-verifier). Report
any claim that survives and any that breaks.

For sustained debate where the skeptics challenge each other, escalate to an agent team (the env var above). See recipe P4 in references/composition-recipes.md.

5. Loop until clean (validator → fix → repeat)

Iterate a fix-and-recheck cycle until a quality gate passes — bounded by a turn cap so it terminates. Academic use: revise → re-review until zero unresolved reviewer comments, or verify → fix → re-verify until the bibliography is 100% resolvable.

Run a revision loop: alterlab-paper-reviewer produces comments; revise the
draft to address them; re-review only the previously-flagged items; repeat
until no unresolved comments remain or after at most 3 rounds, then stop and
report the residual issues.

Always set an explicit stop condition AND a max-iteration cap — open loops burn context and tokens. See recipe P5 in references/composition-recipes.md.

Choosing a Mechanism

Need	Mechanism	Why
Isolate verbose output, get a summary back	Subagent	Own context window; only summary returns
Independent investigations, no cross-talk	Parallel subagents	Each explores alone; main agent synthesizes
Side task that needs full current context	Fork (/fork)	Inherits conversation; reuses prompt cache
Workers must debate / challenge each other	Agent team (experimental)	Shared task list + direct messaging
Script the workflow in CI / batch	Agent SDK	query() + agents option, programmatic
It's already one packaged flow	Existing skill	Don't rebuild alterlab-research-pipeline

Match freedom to fragility: open-ended exploration gets prose prompts; fragile multi-step sequences get explicit, ordered instructions and a stop condition.

Resources

• references/claude-orchestration-primitives.md — verified Claude Code subagent
  • agent-team + fork + Agent SDK primitives, with field tables and doc-sourced quotes (load when you need exact frontmatter fields, env vars, or version gates)
• references/composition-recipes.md — five full worked recipes (P1–P5) mapping each pattern onto real AlterLab skills, with copyable delegation prompts, subagent-definition frontmatter, and a Python Agent SDK query() example (load when you need a complete, ready-to-run composition)

<!-- AUTHORING CHECKLIST (see CONTRIBUTING.md → Skill Quality Standards): - name == directory name, lowercase-hyphen, no 'claude'/'anthropic' - description: third person, leads with what + "Use when", suite label LAST, <=1024 chars (this one ~840) - body <500 lines; reference files exist and are one level deep - every factual orchestration claim verified against code.claude.com docs (2026-06-08) - validate: uv run python scripts/check_spec.py --skill workflow-orchestration && uv run python scripts/audit_skills.py -->