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 twelve front-ends: Python, Java, TypeScript, C#, C, C++, Go, PHP, Perl, Kotlin and SQL — plus a Gradle reader that turns .kts build scripts into the module graph an Android app is assembled from — 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.

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.36.0 (current) — Kotlin, as the 11th language and the 12th front-end: .kt comprehension and a typed-receiver call graph, Room entities and Retrofit calls (so an Android app joins a backend as a cross-repo consumer), Compose navigation as routes, Hilt wiring through a new PROVIDES edge kind, Ktor and Spring MVC routes — the Spring half shared with the Java front-end, which had read JAX-RS only — Kotlin Multiplatform source sets, and codegen for both Kotlin/JVM and Android on a new Gradle test runner that also gives Java codegen its first Gradle support. .kts build scripts are read as a module graph rather than parsed as source. Install with pip install 'synaptixs-spine[kotlin]'.

3.35.0 — 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, Perl and Kotlin — 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. Kotlin covers comprehension and the data layer (classes and objects in every flavour, companions folded onto their class, extension and top-level functions, constructor properties, a CALLS graph built on Kotlin's declared types — dao.getTopics() resolves exactly, with no inference — plus Room entities, DAO reads/writes parsed from the SQL, and Retrofit calls that make an Android app a consumer in the multi-repo join). A Kotlin service is read the other way round: Ktor and Spring MVC routes become Endpoints, so a Kotlin backend is a provider the same join can pair against. Spring is read by a module the Java front-end shares, which is how Java gained Spring endpoints at the same time — it had only ever read JAX-RS. sdlc feature --language kotlin generates and tests code in Kotlin/JVM and Android projects, picking the Gradle module from the target package and running that module's own unit tests — never an emulator. 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.