feat(sdk): DevSwarm-style swarm example — orchestrator/workers/synthesizer [DSP-1]

[justrach]

Summary

Thin slice of #55 (DSP-1 Agents) — a single-file TypeScript SDK example at sdk/typescript/examples/swarm.ts that implements the orchestrator → parallel workers → synthesizer pattern from justrach/devswarm using only existing @codegraff/sdk primitives.

Three stages:

1. Orchestrator — decomposes the task into N independent JSON-array subtasks.
2. N workers — each spawns its own Graff.init() and runs its subtask in parallel (Promise.all). Separate Graff instances are the cheap stand-in for the worktree isolation devswarm uses (their ADR-001). Worker prompt does NOT embed the orchestrator preamble (lesson from devswarm #389).
3. Synthesizer — merges worker outputs into one response.

Env knobs: GRAFF_CWD, SWARM_N (clamped [1, 8]), SWARM_MODEL.

Default task is a small read-only ask against this repo so the demo is cheap to smoke. Wired up as npm run swarm -- "your task".

What this PR is NOT

Future PRs against #55 own:

• Role+mode routing (8 roles × 4 modes per devswarm)
• Role-specific model tiers (Opus orchestrator / Sonnet workers / Haiku monitor)
• Preset task chains (finder_fixer, reviewer_fixer, explore_report, architect_build)
• NO_ISSUES_FOUND review-fix termination
• Real worktree isolation (vs separate-Graff stand-in)

This PR targets release/0.1.6 per the long-lived release-branch workflow.

Test plan

• Type-checks pass under the same tsc/tsx config the existing examples use (verified locally with npx tsc --noEmit --target es2022 --module esnext --moduleResolution bundler --strict --skipLibCheck examples/{swarm,agent-demo,compare}.ts).
• Manual smoke run (makes real LLM calls — gated to reviewer):

  cd sdk/typescript
  npm run swarm
  # or with overrides:
  SWARM_N=3 npm run swarm -- "your task here"
  

• Verify the stderr trace shows: orchestrator → 3 parallel worker[N] conv=... lines → synthesizer.

DSP-1 acceptance criteria addressed

From #55:

• run_swarm-equivalent runs N parallel workers in isolated conversations (separate Graff instances, not worktrees yet)
• Workers receive only their own task text, not the orchestrator preamble — encoded in the worker prompt (devswarm #389)
• Workers run the role assigned, not a default fixer (devswarm #388) — no roles yet in this slice
• Workers see a scoped tool set (devswarm #374) — no tool scoping yet
• review_fix_loop terminates on NO_ISSUES_FOUND or max_iter — deferred
• Role+mode routing configurable per-call and via .codegraff/swarm.toml — deferred
• One end-to-end demo: spawn N workers on a real task and synthesize

Refs

• Epic: [Epic] Port DevSwarm into forge — swarm orchestration + 37 MCP tools #53
• Issue: [DSP-1] Agents: port run_swarm / run_task / review_fix_loop + role+mode routing from devswarm #55 ([DSP-1] Agents)
• Base PR for release/0.1.6 collector branch: future PR will collect 0.1.6 features.

🤖 Generated with Claude Code

[github-actions]

Action required: PR inactive for 5 days.
Status update or closure in 10 days.

[justrach]

Closing: this PR was opened against release/0.1.6 (frozen, last touched May 11) and depends on unmerged SDK infrastructure that lives on that release line. Specifically sdk/typescript/package.json doesn't exist on main yet \u2014 the file is part of #87 (release: sdk/typescript v0.2.0), which is currently failing CI on three platforms.

When #87 lands on main, this swarm example can be reopened as a fresh PR targeting main. The 261-line TS example itself is fine; it's the dependency chain that's the blocker.

Tracked alongside DSP-1 (#55), which is the larger Rust port this example previews.