# 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

```bash
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

| Mode | Needs |
| --- | --- |
| `mock` (default) | Nothing — offline, deterministic |
| `octocode` (live GitHub evidence) | Bridge env vars (below) + `gh auth login` or `GITHUB_TOKEN`/`GH_TOKEN` |
| `github` (built-in REST provider) | `gh auth login` or `GITHUB_TOKEN`/`GH_TOKEN` |

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):

  ```bash
  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`](.env.example) and
[`docs/RUNBOOK.md`](docs/RUNBOOK.md) §7.

## Quickstart

```bash
# 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`](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.

```sh
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`](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

```text
.
├── 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](https://github.com/bgauryy/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`](docs/SOURCE_NOTES.md).
- **[DeepWiki](https://deepwiki.com/)** — 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](https://modelcontextprotocol.io/)** — the MCP
  server (`research.scoreRepos`, `research.explainRepoPattern`,
  `research.writePlanArtifact`) is built on the official MCP TypeScript SDK.
- **[GitHub code search](https://docs.github.com/en/search-github/github-code-search/understanding-github-code-search-syntax)** —
  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](LICENSE)