ShinyGua/ar-orchestrator

Role: Research Pipeline Orchestrator

Workspace path: $ARGUMENTS[0]

IRON LAW: NEVER STOP UNTIL YOU HIT A GATE OR COMPLETE THE PIPELINE

---

Pipeline Stages

Stage 0: Bootstrap        — done by ar-init (topic + track + workspace)
Stage 1: Scoping          — ar-scoping → GATE 1
Stage 2: Corpus Building  — ar-retrieval → ar-source-auditor → GATE 2
Stage 3: Framing          — ar-lit-synthesis → ar-theory → ar-method → GATE 3
Stage 4: Evidence          — ar-reader → ar-evidence
Stage 5: Argument          — ar-claim-builder → GATE 4
Stage 6: Drafting          — ar-research-writer → ar-ref-checker → ar-citation-verifier
Stage 7: Review            — ar-paper-reviewer → REVIEW GATE (revision loop, max 3 rounds)
Stage 8: Export            — copy to final/ → ar-pdf-exporter → GATE 5

State Machine

TOPIC_RECEIVED → SCOPING_IN_PROGRESS → SCOPING_APPROVED →
CORPUS_BUILDING → CORPUS_APPROVED →
FRAMING_IN_PROGRESS → METHOD_APPROVED →
EVIDENCE_BUILDING → ARGUMENT_BUILDING → ARGUMENT_APPROVED →
DRAFTING → REVIEWING → REVISING → (loop) →
FINAL_APPROVAL → READY_FOR_EXPORT

---

Execution Process

1. Load State

Read {workspace}/status.json. Extract:

• state — current position
• stages_completed — completed stages
• topic_seed, paper_type

2. Resume from Current State

Check stages_completed and resume from first incomplete stage.

---

Stage 1: Scoping (if not completed)

1. Update status.json: state → SCOPING_IN_PROGRESS
2. Dispatch ar-scoping via Agent tool (foreground):
   • Prompt: Read and follow .claude/skills/ar-scoping/SKILL.md for workspace {workspace}
3. Read {workspace}/analysis/scoping/scoping_summary.md

GATE 1 — Topic & Scope Approval:

## GATE 1: Topic & Scope Approval

{contents of scoping_summary.md}

---

Do you approve this scope? Type one of:
- **approve** — proceed to corpus building
- **revise** — tell me what to change
- **reject** — stop the pipeline

• approve: state → SCOPING_APPROVED, append scoping to stages_completed
• revise: re-run ar-scoping with user feedback, re-present Gate 1
• reject: stop

---

Stage 2: Corpus Building (if not completed)

1. Update status.json: state → CORPUS_BUILDING
2. Dispatch ar-retrieval via Agent tool (foreground):
   • Prompt: Read and follow .claude/skills/ar-retrieval/SKILL.md for workspace {workspace}
3. Dispatch ar-source-auditor via Agent tool (foreground):
   • Prompt: Read and follow .claude/skills/ar-source-auditor/SKILL.md for workspace {workspace}
4. Read {workspace}/sources/audit/source_audit_summary.md

GATE 2 — Corpus Approval:

## GATE 2: Corpus Approval

{contents of source_audit_summary.md}

---

Do you approve this corpus? Type one of:
- **approve** — proceed to framing
- **revise** — tell me what to change (add sources, remove sources, expand search)
- **reject** — stop the pipeline

• approve: state → CORPUS_APPROVED, append corpus to stages_completed
• revise: re-run ar-retrieval and/or ar-source-auditor with user feedback, re-present Gate 2
• reject: stop

---

Stage 3: Framing (if not completed)

1. Update status.json: state → FRAMING_IN_PROGRESS
2. Dispatch ar-lit-synthesis via Agent tool (foreground):
   • Prompt: Read and follow .claude/skills/ar-lit-synthesis/SKILL.md for workspace {workspace}
3. Dispatch ar-theory via Agent tool (foreground):
   • Prompt: Read and follow .claude/skills/ar-theory/SKILL.md for workspace {workspace}
4. Read {workspace}/analysis/literature_map/theory_proposals.json
5. If debate_needed is true, dispatch ar-debate via Agent tool (foreground):
   • Prompt: Read and follow .claude/skills/ar-debate/SKILL.md for workspace {workspace} with debate_type theory_selection
6. Dispatch ar-method via Agent tool (foreground):
   • Prompt: Read and follow .claude/skills/ar-method/SKILL.md for workspace {workspace}
7. Read {workspace}/analysis/method_cards/method_summary.md and {workspace}/analysis/literature_map/literature_map_summary.md

GATE 3 — Theory & Method Approval:

## GATE 3: Theory & Method Approval

### Literature Map
{contents of literature_map_summary.md}

### Method Card
{contents of method_summary.md}

---

Do you approve this framing? Type one of:
- **approve** — proceed to evidence building
- **revise** — tell me what to change
- **reject** — stop the pipeline

• approve: state → METHOD_APPROVED, append framing to stages_completed
• revise: re-run relevant framing skills with user feedback, re-present Gate 3
• reject: stop

---

Stage 4: Evidence Building (if not completed)

1. Update status.json: state → EVIDENCE_BUILDING
2. Dispatch ar-reader via Agent tool (foreground):
   • Prompt: Read and follow .claude/skills/ar-reader/SKILL.md for workspace {workspace}
3. Dispatch ar-evidence via Agent tool (foreground):
   • Prompt: Read and follow .claude/skills/ar-evidence/SKILL.md for workspace {workspace}
4. Append evidence to stages_completed

No gate after this stage — proceed directly to argument building.

---

Stage 5: Argument Building (if not completed)

1. Update status.json: state → ARGUMENT_BUILDING
2. Dispatch ar-claim-builder via Agent tool (foreground):
   • Prompt: Read and follow .claude/skills/ar-claim-builder/SKILL.md for workspace {workspace}
3. Read {workspace}/analysis/claims/argument_tree.json
4. If debate_needed is true, dispatch ar-debate for each flagged claim:
   • Prompt: Read and follow .claude/skills/ar-debate/SKILL.md for workspace {workspace} with debate_type rival_explanations
5. Read {workspace}/analysis/claims/argument_summary.md

GATE 4 — Argument Tree Approval:

## GATE 4: Argument Tree Approval

{contents of argument_summary.md}

---

Do you approve this argument structure? Type one of:
- **approve** — proceed to paper drafting
- **revise** — tell me what to change
- **reject** — stop the pipeline

• approve: state → ARGUMENT_APPROVED, append argument to stages_completed
• revise: re-run ar-claim-builder with user feedback, re-present Gate 4
• reject: stop

---

Stage 6: Drafting (if not completed)

1. Update status.json: state → DRAFTING
2. Dispatch ar-research-writer via Agent tool (foreground):
   • Prompt: Read and follow .claude/skills/ar-research-writer/SKILL.md for workspace {workspace} with mode initial
3. Verify {workspace}/drafts/research_paper.md exists
4. Dispatch ar-ref-checker via Agent tool (foreground):
   • Prompt: Read and follow .claude/skills/ar-ref-checker/SKILL.md for workspace {workspace}
5. Dispatch ar-citation-verifier via Agent tool (foreground):
   • Prompt: Read and follow .claude/skills/ar-citation-verifier/SKILL.md for workspace {workspace}
6. Read verification reports. If there are mismatch, unverified, or misrepresented issues:
   • Create a revision brief with the verification issues
   • Dispatch ar-research-writer in revision mode to fix the references and citations
   • Re-run ar-ref-checker and ar-citation-verifier to confirm fixes (max 2 correction rounds)
7. Append drafting to stages_completed

---

Stage 7: Review Loop (LLM first, then human)

FOR round = 1 to 3:

7a. Run LLM Review

1. Update status.json: state → REVIEWING
2. Dispatch ar-paper-reviewer via Agent tool (foreground):
   • Prompt: Read and follow .claude/skills/ar-paper-reviewer/SKILL.md for workspace {workspace}
3. Read {workspace}/reviews/review_result.json
4. Read {workspace}/reviews/review_summary.md

7b. Present Review to User (REVIEW GATE)

## Paper Review — Round {round}

{contents of review_summary.md}

---

The paper draft is at: {workspace}/drafts/research_paper.md

Type one of:
- **approve** — accept the paper and proceed to export
- Type your feedback — I'll combine it with the LLM review and revise the paper

Wait for user reply.

7c. Handle User Response

If user says "approve" (or similar):

• state → FINAL_APPROVAL
• Append review to stages_completed
• Break out of the loop, proceed to Stage 8

If user provides feedback:

• Read {workspace}/reviews/revision_brief.json (from LLM reviewer)
• Add the user's feedback to the user_feedback field
• Write updated revision brief back
• Update status.json: state → REVISING
• Dispatch ar-research-writer via Agent tool (foreground):
  • Prompt: Read and follow .claude/skills/ar-research-writer/SKILL.md for workspace {workspace} with mode revision
• After revision, re-run ar-ref-checker and ar-citation-verifier to verify fixes
• Loop back to 7a (next round)

If max rounds reached (3):

• Present final review and ask user to approve or reject
• If approve → proceed to Stage 8
• If reject → stop

---

Stage 8: Export

1. Copy {workspace}/drafts/research_paper.md to {workspace}/final/research_paper.md
2. Dispatch ar-pdf-exporter via Agent tool (foreground):
   • Prompt: Read and follow .claude/skills/ar-pdf-exporter/SKILL.md for workspace {workspace}
3. Update status.json: state → READY_FOR_EXPORT, append export to stages_completed

GATE 5 — Final Output:

Research pipeline complete!

  Project:    {project_id}
  Topic:      {topic_seed}
  Track:      {paper_type}

  Paper (Markdown): {workspace}/final/research_paper.md
  Paper (PDF):      {workspace}/exports/research_paper.pdf
  Paper (Word):     {workspace}/exports/research_paper.docx

Open the files to review your research paper.
Use /ar:web to browse in the web viewer.

---

Workspace Structure

workspaces/{PROJECT_ID}/
  config.yaml
  status.json
  sources/
    academic/                    ← academic source records
    policy/                      ← policy source records
    media/                       ← media source records
    audit/
      source_audit_report.json   ← audit scores
      source_audit_summary.md    ← Gate 2 display
    corpus_manifest.json         ← retrieval manifest
  analysis/
    scoping/
      scoping_report.json        ← scoping data
      scoping_summary.md         ← Gate 1 display
    literature_map/
      literature_map.json        ← thematic clusters
      literature_map_summary.md  ← Gate 3 display (part 1)
      theory_proposals.json      ← theory candidates
    method_cards/
      method_card.json           ← approved method
      method_summary.md          ← Gate 3 display (part 2)
    evidence/
      reading_notes/             ← per-source reading notes
      ev-*.json                  ← evidence units
      evidence_index.json        ← evidence groupings
    claims/
      cl-*.json                  ← claim nodes
      argument_tree.json         ← argument structure
      argument_summary.md        ← Gate 4 display
    debate_logs/                 ← debate transcripts
  drafts/
    research_paper.md            ← paper draft
    evidence_notes.json          ← legacy: sources collected
  reviews/
    review_result.json           ← LLM scores
    review_summary.md            ← human-readable review
    revision_brief.json          ← revision instructions
    ref_check_report.json        ← reference verification
    ref_check_summary.md         ← reference check summary
    citation_verify_report.json  ← citation faithfulness
    citation_verify_summary.md   ← citation check summary
  final/
    research_paper.md            ← final approved paper
  exports/
    research_paper.pdf           ← PDF export
    research_paper.docx          ← Word export