A small CLI that takes a question, researches it on the web, and writes a cited Markdown report.

Two reasons:

1. Port Open Deep Research from LangChain to the Vercel AI SDK. The original is a great example of multi-agent research orchestration. This is a from-scratch reimplementation on top of the Vercel AI SDK to see how the same ideas translate.
2. Practice Matt Pocock's Claude skills. The skills under .claude/skills/ (tdd, grill-with-docs, to-prd, to-issues, setup-matt-pocock-skills) were used throughout to plan, document, and implement features.

One run goes through these phases:

1. Clarify — optionally ask one follow-up question to sharpen the input.
2. Brief — turn the question into a precise research target.
3. Plan — split the brief into sub-topics.
4. Research — run one researcher per sub-topic in parallel. Each does a bounded web-search loop and returns compressed findings with sources.
5. Gap-fill — at most one extra round to cover anything missing.
6. Write — produce the final Markdown report with numbered citations.

Each run is saved under reports/<timestamp>/ as state.json plus report.md.

See CONTEXT.md for the full vocabulary and docs/adr/ for design decisions.

Requires pnpm and an Vercel AI Gateway API key.

pnpm install
export AI_GATEWAY_API_KEY=...

pnpm research "What are the tradeoffs of SQLite vs Postgres for small SaaS apps?"

Options:

• --no-clarify — skip the clarification turn
• --max-parallel <n> — cap concurrent researchers (default 4, max 32)
• --out-dir <path> — override the output directory
• --from-state <path> — resume from a saved state.json
• --debug — verbose logs

• pnpm research "<question>" — run the CLI
• pnpm test — run tests
• pnpm test:live — live smoke test (needs RUN_LIVE=1 and AI_GATEWAY_API_KEY)
• pnpm typecheck — type check
• pnpm lint / pnpm format — eslint / prettier

• Scripts run via node --strip-types — no build step.
• Tests live next to source files (foo.ts / foo.spec.ts).