SDD Orchestrator

A standalone Model Context Protocol server that gives coding agents the right spec-driven-development (SDD) context at the right moment.

For each task it:

• routes the task to the best-fitting SDD framework (OpenSpec, GitHub Spec Kit, BMAD, Kiro, or a house workflow) using explainable rules;

• keeps lifecycle state per feature and runs deterministic gate checks between phases, so gates are enforced rather than advisory;

• assembles a context pack per phase from a company-wide knowledge base, with app-scoped memory (ADRs, accepted specs, decisions) and explicit cross-app lookup.

The host agent (Claude Code, Cursor, or any MCP client) remains the only thing that edits files, runs tests or spawns sub-agents. The server reads and writes only its own database.

Why

Coding agents tend to follow whatever process was in the prompt last, forget why a past decision was made once the conversation that made it is gone, and start writing code before checking whether a spec is actually complete. None of that is a model problem; it is a missing place to keep process state outside the agent's own context window. This server is that place: one explainable choice of framework per task, phase gates that block on the artifact's own text rather than on trust, and a knowledge base that survives across sessions, branches and hosts.

Related MCP server: Hivelore

Use cases

• Brownfield feature work. "Add CSV export to the orders page" against a service with an existing openspec/ directory routes to OpenSpec's default track: a proposal and delta spec gated on measurable acceptance criteria before implement starts.

• Production incidents. A hotfix routes to OpenSpec's hotfix track, which defers spec review until after the fix ships and adds a mandatory learn phase whose gate requires an Incident Memory Proposal section, so the agent has to write up the incident before the feature can archive.

• Compliance-sensitive paths. An app's policy can pin a framework by path glob (**/payments/** → BMAD) regardless of what route_task would otherwise pick; overriding that pin needs an explicit policy_override_reason recorded on start_feature.

• Greenfield services. A repository with no spec library and fewer than 20 commits routes to Spec Kit's default track — the full seven-phase lifecycle from specify through learn.

• Behaviour-preserving refactors. OpenSpec and Spec Kit both ship a refactor track that requires characterization tests before any change and blocks the move out of verify if the evidence shows an existing test was modified (max_existing_tests_modified: 0).

• Cross-app knowledge reuse. search_memory with scope: "company" or a list of app slugs answers "how do other apps handle X" without pulling in every other app's private decisions by default.

Status

v1 implemented per docs/superpowers/specs/2026-09-10-sdd-orchestrator-design.md and the plan in docs/superpowers/plans/2026-09-10-sdd-orchestrator-v1.md. Host verification status is tracked in docs/verification/feature-matrix.md. Deployment characteristics (pool sizing against embedding latency, long-lived GET /mcp streams, migrations on CLI start-up) are in docs/operations.md; what a host may and may not assume about a context pack is in docs/verification/host-integration.md. An interactive runtime architecture diagram (core components, primary path, external dependencies, trust boundaries) is published at dbianco.github.io/sdd-orchestrator/architecture/sdd-orchestrator.architecture.html.

Development

npm install
npm run db:test:up                       # Postgres + pgvector on :55432
export SDD_TEST_DATABASE_URL=postgres://sdd:sdd@localhost:55432/sdd_test
npm test                                 # unit, integration and contract tests
npm run typecheck
npm run dev:stdio                        # server over stdio against SDD_DATABASE_URL
npm run admin -- app list                # sdd-admin without building

Planned stack

Usage examples

The interface below is the v1 contract.

1. Run the server

git clone https://github.com/dbianco/sdd-orchestrator
cd sdd-orchestrator
cp .env.example .env            # set VOYAGE_API_KEY, or SDD_EMBEDDING_PROVIDER=ollama
docker compose up -d            # Postgres + pgvector + sdd-orchestrator on :8080
curl http://localhost:8080/healthz

2. Seed the knowledge base (admin, once)

sdd-admin app register checkout --name "Checkout Service" --compliance
sdd-admin app update checkout --stack typescript,react,node --budget 6000
sdd-admin app set-policy checkout policy.json --reason "PCI scope: BMAD for payments paths"

sdd-admin ingest packs/openspec
sdd-admin ingest packs/spec-kit
sdd-admin ingest packs/bmad
sdd-admin ingest packs/quality-layer
sdd-admin ingest packs/stack-guides/react
sdd-admin ingest packs/company            # always-on constitution

policy.json:

{
  "framework": null,
  "path_rules": [{ "glob": "**/payments/**", "framework": "bmad" }],
  "risk_paths": ["**/webhooks/**"]
}

3. Connect a host

Claude Code (.mcp.json in the workspace):

{
  "mcpServers": {
    "sdd": { "type": "http", "url": "http://sdd.internal:8080/mcp" }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "sdd": { "url": "http://sdd.internal:8080/mcp" }
  }
}

Local development against a local database, over stdio:

{
  "mcpServers": {
    "sdd": { "command": "sdd-orchestrator", "args": ["--stdio"] }
  }
}

4. Route a task and start a feature

The developer types a task; the host agent calls the server.

You: Add CSV export to the orders page.

The agent calls route_task:

{
  "task_description": "Add CSV export to the orders page",
  "app": "checkout",
  "workspace": {
    "stack": ["typescript", "react"],
    "is_greenfield": false,
    "has_spec_library": true,
    "estimated_files": 4,
    "paths_touched": ["src/orders/"],
    "host": "claude-code"
  }
}

and receives:

{
  "decision": {
    "framework": "openspec",
    "track": "default",
    "confidence": "high",
    "rule": "10-brownfield-small-medium",
    "reasons": ["brownfield (asserted by host)", "size: medium (4 files, one top-level dir)"],
    "high_risk": false,
    "policy_version": 3,
    "framework_pack_version": "1.0.0"
  },
  "attached_layers": [
    { "pack_name": "quality-layer", "pack_version": "1.0.0", "kind": "standard" },
    { "pack_name": "stack-guides/react", "pack_version": "1.0.0", "kind": "stack_guide" }
  ]
}

The agent shows the decision, the developer accepts, and the agent calls start_feature with the same decision and actor: "daniel". The result carries a feature_id and the first context pack: header, always-on constitution, the OpenSpec proposal template, retrieved app memory such as ADR-7 Exports go through the reporting service, React guide sections, and the stop conditions plus the checks the next gate will run.

route_task also returns a routing_id: the server records one routing event per unit of work (deduplicated by external_ref or by task text), so trivial fixes that never become features still show up in the admin. Pass the routing_id to start_feature, and call record_commit after each commit to link it to the work.

5. Advance through the gates

After the agent writes the proposal and the developer reviews it:

{
  "feature_id": "f_01j9…",
  "actor": "daniel",
  "expected_phase": "specify",
  "target_phase": "implement",
  "artifacts": { "proposal.md": "…", "specs": "…", "tasks.md": "…" },
  "human_approved": true
}

A failing gate is a normal result, not an error:

{
  "result": "fail",
  "findings": [
    { "check": "placeholder_scan", "severity": "blocker", "location": "proposal.md:41", "message": "marker TBD" },
    { "check": "measurable_criteria", "severity": "blocker", "location": "proposal.md:58", "message": "\"export must be fast\" has no threshold" }
  ]
}

The agent fixes the proposal and calls again. On pass it receives next_instructions for implement. At the end of implementation the host sends evidence with the move out of verify:

{
  "expected_phase": "verify",
  "target_phase": "integrate",
  "evidence": {
    "tests": { "command": "npm test", "passed": 48, "failed": 0 },
    "lint": "pass",
    "security": { "status": "pass", "new_high": 0 },
    "files_changed": ["src/orders/export.ts", "src/orders/export.test.ts"],
    "implements": ["REQ-12"]
  }
}

If tests keep failing, the agent moves back from verify to implement with cycle_failed: true. The third such move blocks the feature until a human intervenes.

6. Look things up across apps

{ "query": "how do other apps handle CSV encoding", "app": "checkout", "scope": "company" }

or, for named apps:

{ "query": "rate limiting decisions", "app": "checkout", "scope": ["billing", "reporting"] }

7. Grow and retire memory

During the learn phase the agent proposes an ADR:

{
  "feature_id": "f_01j9…",
  "actor": "daniel",
  "kind": "app_memory",
  "memory_type": "adr",
  "title": "ADR-9 CSV exports stream rather than buffer",
  "body": "…",
  "links": ["openspec/changes/archive/2026-09-10-orders-csv-export/"]
}

An admin reviews and retires knowledge:

sdd-admin proposals list
sdd-admin proposals approve p_42
sdd-admin deprecate checkout.adr.0003 --successor checkout.adr.0009 --reason "superseded by streaming"
sdd-admin deprecate-framework kiro --reason "no longer used"
sdd-admin reindex                       # after switching embedding model

8. Browse adoption and flow metrics (optional)

Set SDD_ADMIN_TOKEN and restart the server to turn on a read-only admin page at /admin — feature counts, gate blocker counts by check, a phase-to-phase flow heatmap, the memory-proposal queue, and a Work tab listing everything routed (features and trivial fixes alike) with linked commits, filterable by app and date range. It is absent entirely (a plain 404) when the token is unset.

export SDD_ADMIN_TOKEN=s3cret   # or set it in .env / docker-compose.yml
docker compose up -d
open http://localhost:8080/admin   # any username, password = SDD_ADMIN_TOKEN

Repository layout

docs/operations.md        deployment and operating notes
docs/superpowers/specs/   design specifications
docs/superpowers/plans/   implementation plans
docs/verification/        host integration guide, feature matrix, walkthroughs, workspace-facts script
migrations/               node-pg-migrate schema
packs/                    seed knowledge packs (frameworks, quality layer, stack guides, company)
src/                      server, services, assembler, ingestion and CLI
test/                     unit, integration and contract tests

License

MIT