Research Orchestrator

Evidence-grounded implementation research. Give it a high-level feature goal — it searches GitHub, scores candidate repositories, reads exact source evidence, and writes planning artifacts (research.md, plan.md, evidence.json, implementation-checklist.md) you can build from. Runs as a CLI and as an MCP server, with Octocode as the evidence engine and optional DeepWiki enrichment.

"Find examples of a Next.js + Convex app using email magic links, extract the implementation pattern, and produce a grounded plan."

"Find examples of a Next.js + Convex app using email magic links, extract the implementation pattern, and produce a grounded plan."

into a repeatable workflow. New work uses a validated v2 research brief and question-scoped evidence ledger. Candidate scores and selected-repository lists help discovery but do not verify claims.

The original candidate-oriented pipeline remains available as a compatibility projection. Its stages describe discovery and artifact production, not the current evidence authority.

The compatibility workflow can:

1. Normalize the user's goal into a structured feature spec.

2. Generate high-precision and high-recall GitHub/Octocode probes.

3. Collect candidate repositories.

4. Rank candidates for further inspection.

5. Read exact source evidence.

6. Optionally enrich with DeepWiki when available and fresh.

7. Fall back to Octocode/local repo understanding when DeepWiki is unavailable or stale.

8. Produce reusable planning artifacts with evidence anchors.

9. Expose the workflow as an MCP server and/or CLI.

Install

npm install -g research-orchestrator   # or: npx research-orchestrator

Requirements

• Node 20+ (enforced via engines; the Octocode server also needs 20+)

• npx available for live --mode octocode (bundled with npm — it spawns @octocodeai/mcp as a subprocess; first call downloads the package)

• Network access to GitHub for live modes; no config, no network for --mode mock

• No native modules, no postinstall scripts — runtime deps are just @modelcontextprotocol/sdk and zod

Per-mode configuration

For --mode octocode, copy .env.example → .env and set the bridge config:

• Local clone: put .env at the package root (next to package.json) — the CLI self-loads it from its install location regardless of your cwd.

• Global install: either export the variables directly (they always win):

  export RESEARCH_OCTOCODE_BRIDGE="$(npm root -g)/research-orchestrator/dist/bridges/octocode-mcp.js"
  export RESEARCH_OCTOCODE_COMMAND=npx
  export RESEARCH_OCTOCODE_ARGS='["-y","@octocodeai/mcp@latest"]'

  …or place the .env at the installed package root ($(npm root -g)/research-orchestrator/.env).

• SSE/HTTP transport (Octocode server already running elsewhere): RESEARCH_OCTOCODE_TRANSPORT=sse + RESEARCH_OCTOCODE_URL + RESEARCH_OCTOCODE_API_KEY instead of the stdio vars.

For stdio, the bridge forwards the token from gh auth token to Octocode as GH_TOKEN when no token environment variable is set. Both live providers check authentication before starting research and return a configuration error if it is unavailable.

Full variable reference: .env.example and docs/RUNBOOK.md §7.

Related MCP server: Stargraph

Quickstart

# 1. Offline smoke run — no config, deterministic
research-orchestrator find \
  --goal "Next.js + Convex app with email magic links via Resend" \
  --out ./my-research --mode mock

# 2. Read the artifacts
ls ./my-research   # research.md plan.md evidence.json implementation-checklist.md

# 3. Live run with real GitHub evidence (one-time setup: docs/RUNBOOK.md §7)
research-orchestrator find --goal "..." --out ./my-research --mode octocode

The CLI self-loads a .env at the package root (see .env.example) for the Octocode bridge; explicit environment variables always win. Exit codes: 0 plan ready · 2 inconclusive (warnings explain why) · 1 error.

Full details — docs/RUNBOOK.md covers the verified mock-mode quickstart, live Octocode setup, MCP server registration, tests, output artifacts, and troubleshooting.

Brief-based research

Use plan to validate a structured request before provider calls, then execute the resulting brief. A needs_input result includes vocabulary work for a host to perform and cite; planning itself does not claim that a lookup occurred.

npm run cli -- plan --request request.json --out brief.json
npm run cli -- find --brief brief.json --out .research/run --mode mock
npm run cli -- find --resume RUN_ID --brief revised-brief.json --out .research/resume --mode mock

find --goal remains available as a compatibility adapter, with intentionally stricter handling of vague goals. Mock is synthetic fixture data, not live repository research; its mode and synthetic origin are shown in receipts.

Offline evaluation

npm run eval replays six frozen synthetic corpora, reports separate discovery, support precision, unsupported verification, coverage, costs, provider events, and compatibility-loss metrics, and labels tuning versus held-out fixtures. It makes no live provider calls. See docs/10_eval_benchmarks.md and committed demo receipts under examples/receipts/.

Suggested reading order

1. docs/RUNBOOK.md

2. PROMPT_FOR_CODING_AGENT.md

3. docs/00_project_brief.md

4. docs/01_architecture.md

5. docs/02_mvp_roadmap.md

6. docs/03_research_workflow.md

7. docs/08_mcp_tool_spec.md

8. docs/12_build_tasks.md

Directory map

.
├── src/            # TypeScript source (core engine, adapters, MCP server, schemas)
│   ├── core/       # goal normalization, probe generation, pipeline, scoring
│   ├── adapters/   # evidence providers (Octocode bridge, mock, GitHub)
│   ├── mcp/        # MCP server exposing the research.* tools
│   ├── cache/      # run cache
│   └── eval/       # deterministic eval harness
├── bridges/        # Octocode MCP bridge (stdio/SSE/HTTP transports)
├── tests/          # vitest suite (unit + golden snapshots) and fixtures
├── scripts/        # bridge smoke test and wiring verification
├── docs/           # RUNBOOK + design docs (00–12)
├── schemas/        # JSON schemas for feature specs and artifacts
├── templates/      # artifact templates
├── examples/       # sample feature spec, probes, and research run
├── prompts/        # subagent prompts used by the workflow
└── backlog/        # roadmap: milestones and issues

Implementation bias

Start with a TypeScript/Node project exposing:

• a CLI for local/manual iteration

• a small library core

• an MCP server after the first vertical slice works

• file-based cache initially, SQLite later if needed

Do not rebuild Octocode primitives first. Treat Octocode as the evidence engine and build the orchestration/scoring/artifact layer on top.

Acknowledgments

Research Orchestrator stands on the shoulders of:

• Octocode — the evidence engine this tool is built around, and the project that shaped its architecture. Studying Octocode's thin-interface/engine-split design and performance characteristics drove the core decision: layer orchestration, scoring, and artifact generation on top of a long-lived evidence provider — never re-implement code search. Design notes in docs/SOURCE_NOTES.md.

• DeepWiki — optional repo-explanation enrichment. Useful when a repo wiki is indexed and fresh; never treated as proof — critical claims are always verified against exact source.

• Model Context Protocol — the MCP server (research.scoreRepos, research.explainRepoPattern, research.writePlanArtifact) is built on the official MCP TypeScript SDK.

• GitHub code search — its practical limits (result caps, rate limits, snippets-aren't-proof) directly informed probe sharding, result caching, and the proof-grade evidence-anchor model.

License

MIT