ma-agent-teams

name: ma-agent-teams description: Orchestrate agent team for meta-analysis pipeline. Creates team, spawns teammates, manages task list and handoffs between pipeline stages.

Agent Teams Orchestration

Coordinate multiple Claude Code instances as a team for parallel meta-analysis work.

Prerequisites

• Claude Code v2.1.32+
• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in .claude/settings.local.json

When to Use

• User says "create a team for [project]" or "start team mode"
• User says "parallel screen [project]" (dual-review only)
• Project has passed feasibility assessment (Stage 00 complete)
• Parallel work adds real value (≥2 independent stages ready)

When NOT to Use

• Small projects (< 5 studies expected)
• Sequential-only work (single stage at a time)
• User prefers single-session mode (existing ma-end-to-end workflow)

Team Composition

Note: Not all roles are needed for every run. The lead selects roles based on which stages need work.

Phased Spawning Strategy

Phase 1: Sequential Foundation (Stages 00-02)

These stages have hard sequential dependencies — spawn one at a time.

1. Spawn protocol-architect → wait for completion
2. Validate: 01_protocol/pico.yaml and 01_protocol/eligibility.md exist
3. Spawn search-specialist → wait for completion
4. Validate: 02_search/round-01/dedupe.bib exists with > 0 entries

Phase 2: Parallel Screening (Stage 03)

Dual-review requires two independent reviewers working simultaneously.

1. Spawn screener-a AND screener-b simultaneously
2. Critical: screener-a and screener-b must NOT message each other until BOTH complete
3. Lead waits for both to finish
4. Lead computes kappa agreement:

   uv run ma-screening-quality/scripts/dual_review_agreement.py \
     --file projects/{{project-name}}/03_screening/round-01/decisions.csv \
     --col-a Reviewer1_Decision --col-b Reviewer2_Decision \
     --out projects/{{project-name}}/03_screening/round-01/agreement.md
   

5. Quality gate: kappa ≥ 0.60 required. If failed, lead resolves conflicts and re-runs.

Phase 3: Sequential Processing (Stages 04-06)

These stages depend on prior outputs.

1. Spawn fulltext-manager → wait for completion
2. Validate: 04_fulltext/manifest.csv and 04_fulltext/fulltext_decisions.csv exist
3. Spawn data-extractor → wait for completion
4. Validate: 05_extraction/round-01/extraction.csv exists
5. Spawn statistician → wait for completion
6. Validate: 06_analysis/figures/ and 06_analysis/tables/ exist

Phase 4: Parallel Synthesis (Stages 07-09)

Manuscript and QA can work in parallel.

1. Spawn manuscript-writer AND qa-auditor simultaneously
2. manuscript-writer drafts sections from analysis outputs
3. qa-auditor runs GRADE assessment and PRISMA checklist
4. They message each other for revision cycles
5. Lead synthesizes final outputs

Task List Template

Create these tasks at team start. The lead creates all tasks, teammates claim them.

1. "Develop protocol and PICO" [no dependencies]
   → owner: protocol-architect
   → done when: 01_protocol/pico.yaml, eligibility.md, search-plan.md exist

2. "Run literature search and deduplication" [depends: 1]
   → owner: search-specialist
   → done when: 02_search/round-01/dedupe.bib exists

3. "Screen titles/abstracts - Reviewer 1" [depends: 2]
   → owner: screener-a
   → done when: Reviewer1_Decision column populated in decisions.csv

4. "Screen titles/abstracts - Reviewer 2" [depends: 2]
   → owner: screener-b
   → done when: Reviewer2_Decision column populated in decisions.csv

5. "Reconcile screening and compute kappa" [depends: 3, 4]
   → owner: lead
   → done when: agreement.md shows kappa ≥ 0.60, included.bib created

6. "Retrieve full-text PDFs" [depends: 5]
   → owner: fulltext-manager
   → done when: 04_fulltext/manifest.csv exists

7. "Full-text eligibility screening" [depends: 6]
   → owner: fulltext-manager
   → done when: fulltext_decisions.csv and ft_agreement.md exist

8. "Extract study data and assess RoB" [depends: 7]
   → owner: data-extractor
   → done when: 05_extraction/round-01/extraction.csv exists

9. "Run meta-analysis in R" [depends: 8]
   → owner: statistician
   → done when: 06_analysis/figures/ and tables/ populated

10. "Draft manuscript" [depends: 9]
    → owner: manuscript-writer
    → done when: 07_manuscript/index.qmd exists

11. "GRADE assessment and peer review" [depends: 9]
    → owner: qa-auditor
    → done when: 08_reviews/grade_summary.csv exists

12. "Publication QA and PRISMA checklist" [depends: 10, 11]
    → owner: qa-auditor
    → done when: 09_qa/pipeline-checklist.md complete

Handoff Protocol

Each stage produces specific artifacts that the next stage consumes.

Spawn Instructions for Lead

To spawn a teammate:

1. Generate the spawn prompt:

   uv run tooling/python/team_spawn_helper.py --project {{project-name}} --role {{role-name}}
   

2. Use the output as the teammate's spawn prompt
3. Specify the model from the Team Composition table
4. Optionally require plan approval for complex stages (statistician, manuscript-writer)

Available roles: protocol-architect, search-specialist, screening-reviewer, fulltext-manager, data-extractor, statistician, manuscript-writer, qa-auditor

Messaging Patterns

Lead → Teammate

• Task assignment: "Your next task is ready: [task description]"
• Handoff data: "Stage N outputs are at: [paths]. Proceed with your stage."
• Quality feedback: "Validation failed: [details]. Please fix and resubmit."

Teammate → Lead

• Stage complete: "Stage N complete. Outputs at: [paths]. Ready for validation."
• Blocker found: "Blocked: [description]. Need [resolution]."
• Question: "Clarification needed: [question about methodology/scope]"

Teammate → Teammate (rare)

• manuscript-writer → qa-auditor: "Draft ready for review at 07_manuscript/index.qmd"
• qa-auditor → manuscript-writer: "Revision needed: [specific feedback]"

Broadcast (use sparingly)

• Lead broadcasts only for: team-wide status updates, project scope changes

Quality Gates (Lead Enforces)

Team Templates

Full Pipeline Team

All 8 roles. Use for complete meta-analysis from TOPIC.txt to manuscript.

Parallel Screening Team

Only screener-a + screener-b. Use when Stage 02 is complete and dual-review is needed. Lead handles kappa computation and conflict resolution.

Analysis + Writing Team

Only statistician + manuscript-writer + qa-auditor. Use when Stage 05 is complete. Three teammates work in parallel on analysis, writing, and review.

Resuming After Interruption

If a team session is interrupted:

1. Check project status:

   uv run tooling/python/project_status.py --project {{project-name}} --verbose
   

2. Identify which stages are complete vs incomplete
3. Spawn new teammates for incomplete stages (old teammates cannot be resumed)
4. Provide checkpoint context in spawn prompts: "Stage N was partially complete. Files already created: [list]"

Edge Cases