research-orchestrator

Research Orchestrator

You are orchestrating a savage-research run on a local repository.

Announce at start: "Using research-orchestrator to run the 8-stage savage-research pipeline on <path>."

Precondition checks (abort on failure)

1. The argument <path> was provided. If missing → print error: /research requires a local path argument and stop.
2. <path> exists and is a directory. If not → print error: <path> is not a directory and stop.
3. The path is a local filesystem path, not a URL. If it starts with http://, https://, or git@ → print error: only local paths are supported in v1; clone the repo locally first and stop.

Setup

1. Resolve <path> to an absolute path; store as $REPO.
2. Compute $TS = current timestamp as YYYY-MM-DD-HHMM (local time).
3. Compute $REPO_NAME = basename of $REPO.
4. Create directories:
   • $REPO/.research/runs/$TS/scratchpads/
5. The final report path is $REPO/.research/$TS-$REPO_NAME.md.

Stage 1 — Ingest (you perform this directly; no subagent)

Read:

• $REPO/README* (any casing, any extension)
• $REPO/docs/**/*.md (up to reasonable depth; if enormous, summarize by file)
• Top-level .md files matching LANDING*, PITCH*, ABOUT*, OVERVIEW*
• Project-metadata files: package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, Gemfile, etc. — extract stated purpose/description and dependency list only.
• Directory listing at depth 2 (for structural shape only).

Do not read source files line-by-line.

Write a neutral summary to $REPO/.research/runs/$TS/ingest-summary.md. The summary states, in the repo's own framing:

• What the repo says it is
• Who it says it is for
• What it claims to do
• What tech it uses (from metadata)
• Its overall structural shape

If no README and no pitch material exists, the summary says so explicitly and proceeds from metadata + structure alone.

Stage 2 — Claim extraction (subagent: claim-extractor)

Dispatch the claim-extractor subagent with the task:

Read $REPO/.research/runs/$TS/ingest-summary.md and produce a structured claim list at $REPO/.research/runs/$TS/claims.md conforming to the schema in plugin/skills/claim-extraction/SKILL.md. Also read plugin/skills/research-rubric/SKILL.md first.

Wait for completion signal claims-extracted: <path>.

Stage 3 — Parallel specialists

Dispatch all five in one batch (parallel tool calls, single message):

• prior-art-hunter → writes $REPO/.research/runs/$TS/scratchpads/prior-art.md
• claim-auditor → writes $REPO/.research/runs/$TS/scratchpads/claim-audit.md
• failure-mode-hunter → writes $REPO/.research/runs/$TS/scratchpads/failure-modes.md
• traction-checker → writes $REPO/.research/runs/$TS/scratchpads/traction.md
• question-critic → writes $REPO/.research/runs/$TS/scratchpads/question-critique.md

Each gets the same core prompt: "Run your agent on the repo at $REPO. Your inputs are at $REPO/.research/runs/$TS/. Your output goes to the path named in your agent file. Read plugin/skills/research-rubric/SKILL.md before producing output."

Wait for all five completion signals.

Stage 4 — Initial synthesis (subagent: synthesizer, stage=4)

Dispatch synthesizer with stage=4:

Read all inputs at $REPO/.research/runs/$TS/ (ingest-summary, claims, all five scratchpads). Follow plugin/skills/savage-synthesis/SKILL.md Stage 4 rules. Write draft to $REPO/.research/runs/$TS/draft-v1.md.

Wait for completion.

Stage 5 — Adversary (subagent: adversary)

Dispatch adversary:

Read $REPO/.research/runs/$TS/draft-v1.md and all scratchpads at $REPO/.research/runs/$TS/scratchpads/. Produce kill-list at $REPO/.research/runs/$TS/kill-list.md.

Wait for completion.

Stage 6 — Revision (subagent: synthesizer, stage=6)

Dispatch synthesizer with stage=6:

Read draft-v1.md and kill-list.md at $REPO/.research/runs/$TS/. Follow Stage 6 rules in savage-synthesis. Write draft-v2.md.

Wait for completion.

Stage 7 — Self-audit (subagent: self-auditor)

Dispatch self-auditor:

Audit $REPO/.research/runs/$TS/draft-v2.md against kill-list.md. Write audit to $REPO/.research/runs/$TS/audit-v1.md.

Wait for completion signal audit-result: <PASS|FAIL>.

Branch

• PASS → promote draft-v2.md to final. Go to Stage 8.
• FAIL → dispatch synthesizer with stage=6 again, but this time reading draft-v2.md + audit-v1.md as the kill-list, producing draft-v3.md. Then dispatch self-auditor again producing audit-v2.md.
  • If PASS on audit-v2 → promote draft-v3.md.
  • If FAIL on audit-v2 → promote draft-v3.md anyway, but prepend a ## Remaining Flaws section at the top of the final report copying the Violations list from audit-v2.md.

Stage 8 — Emit

1. Copy the promoted draft to $REPO/.research/$TS-$REPO_NAME.md. If Remaining Flaws were prepended, do that during the copy.

2. Print a terminal summary:

   ============================================================
   Savage research complete: <REPO_NAME>
   ============================================================
   
   Verdict:
   <paste the Verdict section content>
   
   Top 3 red flags:
   <first 3 bullets from Red flags>
   
   Full report: <absolute path to final report>
   ============================================================
   

Error handling

• Any subagent fails / times out → record the failure in $REPO/.research/runs/$TS/run.log, and continue if the pipeline can proceed without that input (the synthesizer treats missing scratchpads as "unavailable — this category could not be assessed"). If the synthesizer itself fails, abort and print the run directory path so the user can inspect scratchpads.
• Any web tool fails → the affected specialist records the failure in its own scratchpad; downstream agents handle gracefully (downgrade to Unverifiable).
• Empty repo → Stage 1 produces a summary saying "nothing to evaluate"; downstream stages still run; the verdict is "Nothing to evaluate."