Spine

Turn requirements into reviewed, tested pull requests, with a human in control.

Spine reads requirements from Confluence, Notion, Markdown or OpenSpec, builds a deterministic graph of your target repo, and generates code grounded in its existing structure and conventions. You can inspect the graph and a build plan before spending model tokens, build locally, then choose when to push a pull request for human review.

The product is Spine, its package is synaptixs-spine, and its command is orchestrator. Comprehension supports ten front-ends: Python, Java, TypeScript, C#, C, C++, Go, PHP, Perl and SQL, with the matching parser extras installed.

uv tool install synaptixs-spine

SETUP.md owns prerequisites, extras, credentials and troubleshooting. The base install is enough for the Python worked example; add [sdlc] for builds or [all] for the agent plugin and all language parsers.

Start here

1. Run the worked example. Follow one real ticket in a public codebase, with reproducible output. Its comprehension steps need no credentials; the model-dependent build is marked.

2. Build a feature locally. Configure a model, inspect the plan, and use --safe for a local branch and diff.

3. Go live after review. Use --live to open a PR, then close the tracker loop after a human merges it.

To look at your own repo first, run orchestrator state /path/to/repo. It writes nothing unless you request an output file. orchestrator understand builds the reviewable episteme/ knowledge base; it is the comprehension command that writes.

The optional [clang] extra adds C/C++ member-call edges between existing symbols. Installing it enables the pass automatically, including through [all]. For extraction without clang, use a fresh environment with [languages] or [c,cpp]. Installation details and limits are in SETUP.md.

Related MCP server: MCP SDD Server

What is measured

The graph comes from parsers, with file:line provenance. CI scores its precision and recall against a hand-labelled corpus, and checks for regressions. Those fixture scores are bounds on the tested cases, not a promise that arbitrary code has no missing or incorrect edge. On the corpus, TypeScript CALLS recall is 0.86; CI re-derives this figure from the committed scoreboard.

On a pinned five-project bug corpus, the fixing file appears in the top ten for 27 of 38 tickets; the first guess is right for 12. The method, confidence intervals, graph accuracy and limits are in BENCHMARK.md.

Controlled codegen runs measure whether grounding improves integration, including an arm without the graph and tickets that already name their target file. Read the internal results and external replication for the models, commands, counts and limits.

C/C++ semantic recovery and runtime vary widely by repository. Repository-local include roots can improve resolution, while missing standard/generated headers and unsupported identities still limit it. Recovered pending-site fractions are not whole-repository recall. OpenCV's measured median extraction takes 300.296 s with clang versus 29.501 s without it; this suits batch work only when that cost is acceptable. Some measured profiles gain no useful relationships. See the support contract and five-repository evaluation.

What's new

3.35.0 (current) — two additive features. An optional C/C++ semantic pass (pip install 'synaptixs-spine[clang]') resolves member calls the CST cannot, adding edges only between symbols already in the graph — ids, nodes and determinism unchanged; the standard library stays out of reach. And pkg export --format cypher loads the graph into Neo4j, Memgraph or any openCypher store for the traversal questions the flat projections cannot answer — transitive closure, cycles, shortest path.

3.34.2 — maintainer tooling: a generic plan skeleton every development plan starts from, and a roadmap-currency gate that can check a plan kept outside the checkout. No engine changes.

3.34.1 — documentation has one home per task: AGENT_GUIDE.md replaces the two host guides (its MCP tool inventory is generated and gated), SETUP.md owns installation and credentials, USER_GUIDE.md the everyday build, and OPERATIONS.md the pipeline and dashboard walkthrough. No engine changes — the wheel is identical to 3.34.0.

3.34.0 — Perl ships comprehension and codegen: packages, inheritance, calls, Mojolicious/Dancer2 routes and DBIx::Class entities; builds use perl -c, configured Perl::Critic, then prove, with optional cpanm. A single toolchain registry now owns language dispatch, protected by 8 of 8 caught mutations. Greenfield and brownfield validation is recorded in the Perl roadmap.

Full release history: CHANGELOG.

Capabilities

✅ shipped · 🟡 partial or operator-gated · 🔬 experimental, off by default. Commands below use the orchestrator prefix. All flags and detailed behavior are in CLI_REFERENCE.md.

Documentation

FAQ

Does it merge code on its own? No. It opens a PR; a human reviews and merges. There are two approval gates — before building and before merging — and safe mode makes no external writes at all.

Where does my code/data go? To whichever LLM provider you configure — or nowhere external, if you run a local model (Ollama). Generated code stays in a local branch until you choose --live.

Do I need Docker or a database? Not for the everyday path (sdlc feature --safe builds one requirement locally). The autonomous multi-feature pipeline + web dashboard needs Temporal + Postgres — see the Setup guide.

Which languages and models? Comprehension and codegen cover Python, Java, TypeScript, C#, C, C++, Go, PHP and Perl — each front-end going beyond structure into what that stack actually does (Java and C# REST endpoints, EF Core entities, C's #include graph, C++ templates and namespaces, Go interface satisfaction by method-set matching). PHP adds a call graph too (namespaces, classes, interfaces, traits, CALLS), plus Composer/PHAR PHPUnit codegen with changed-file lint. Perl adds a call graph too (packages, inheritance across its five spellings, $self/SUPER::/qualified/bare CALLS) — codegen uses perl -c then prove, with optional cpanm for dependencies. SQL adds data-layer comprehension plus greenfield migration codegen validated against an ephemeral database. Docs fold in automatically; media (diagrams, screenshots, recorded reviews) via the opt-in media extract. Any LiteLLM provider — Anthropic, OpenAI, Bedrock — or a local Ollama model, and you can set a different model per stage. Extras and details: SETUP.md.

How is it safe to run on real repos? Write guards on generated files, allow-listed + write-gated external tools, a per-run spend budget, an append-only audit trail, and human approval before any push or merge.

CLI or web UI? Either — they drive the same engine and the same API. Use the CLI for scripting/CI, the web UI for watching runs and approving gates by hand — or ask your assistant, which has the same operator tools over MCP.

Can other tools call it? Yes. It speaks MCP both ways: it can use external MCP servers, and it can run as an MCP server so Claude Code / Codex / your IDE can call the pipeline (with the same gates).

Security and contributing

Spine clones repositories and executes generated code. CI runs code and dependency security checks; report vulnerabilities through SECURITY.md.

Work from develop, add a failing fixture for changed behavior, and run the gate in CONTRIBUTING.md. Useful starting points are language front-ends (pkg/*_extractor.py), accuracy fixtures (corpus/), and the tracked gaps in STATE-OF-SPINE. Measure what changed and state what was not checked.

• Report a bug

• Request a feature

• Ask a question

• Code of Conduct

License

MIT License. See LICENSE.