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
- 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.
- Build a feature locally.
Configure a model, inspect the plan, and use
--safefor a local branch and diff. - Go live after review.
Use
--liveto 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.
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.
What's new
3.34.1 (current) — 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.
| Capability | Status | Command or reference |
|---|---|---|
| Requirements → specs → tracked backlog; OpenSpec intake and write-back drafts | ✅ | ingest, backlog, openspec draft |
| Reviewable build document; digest-bound human approval before code | ✅ | sdlc plan, sdlc approve, sdlc autorun |
| Research evidence, code-bound acceptance criteria, validated design references | ✅ | sdlc autorun; evidence persists even when a run parks |
| Local feature build, live PR, review feedback, post-merge tracker completion | ✅ | sdlc feature --safe / --live, address-review, complete |
| Durable multi-feature pipeline and approval dashboard | ✅ | sdlc run, up; Operations |
| Inspect the execution graph, node results and selected workflow | ✅ | sdlc explain, sdlc workflow |
| Python, Java, TypeScript, C#, C, C++, Go, PHP and Perl comprehension/codegen | ✅ | pkg extract, sdlc feature --language; toolchains |
SQL schema/query/procedure comprehension, migration folding, UTF-16 and SQL Server GO batches |
✅ | [sql]; pkg extract, understand |
| SQL migration codegen validated in SQLite or opt-in Docker Postgres | ✅ | sdlc feature --language sql; [sql-postgres] |
| Framework endpoints and data-layer edges, including JAX-RS, ASP.NET Core and EF Core | ✅ | Knowledge Graph |
| C/C++ include graphs and header/source merging; CMake or brownfield Meson builds | ✅ | sdlc feature --language c / cpp |
| Go packages, calls and interface satisfaction; multi-module build/test selection | ✅ | sdlc feature --language go |
| PHP namespaces/traits/calls, Laravel/Slim/Symfony routes, Eloquent/Doctrine entities; Composer/PHAR PHPUnit | ✅ | PHP workflow |
Perl packages/inheritance/fields/calls, routes and data layer; syntax checks and prove |
✅ | Perl workflow |
| Multi-repo graph across HTTP calls, shared tables and library imports; evidence-derived joins | ✅ | .spine/repos.yaml; pkg joins --propose / --check, investigate --repos |
| Markdown, reST, text and HTML docs bound to code; PDF and Word/Excel with extras | ✅ | understand, state, pkg docs; [docs], [office] |
OCR diagrams and transcribe audio/video into reviewed .spine-media/ artifacts |
✅ opt-in | media extract; [media] + Tesseract, [asr] for local Whisper |
Document-grounded codegen and committed episteme/ with a currency check |
✅ | sdlc feature, understand --check |
| State report: infrastructure, structure, architecture, coverage and doc drift | ✅ | state --lens developer / stakeholder |
| Graph extraction/export, repo profile and model-assisted audit | ✅ | pkg extract, pkg export, profile, audit |
| Measured graph accuracy, regression gate and language-specific caveats in build plans | ✅ | pkg accuracy, pkg accuracy --check, sdlc plan |
| Per-file route/table parity and invented-call detection | 🟡 oracle-dependent | pkg accuracy --oracle parity / invention; see CLI limits |
| Runtime call recall by executing the repository's tests | 🟡 Python only | pkg accuracy --oracle runtime (explicit test execution) |
Ticket provenance from blame: Intent nodes and SERVES edges |
✅ opt-in | understand --intents, state --intents, investigate --intents, pkg export --intents |
| Human gates, policy, spend budgets, append-only audit, run export/replay | ✅ | Operations; registry trace/export |
| RBAC and multi-tenancy | 🟡 partial | ORCHESTRATOR_PRINCIPALS, ORCHESTRATOR_TENANT_ID |
| Profile-based capability catalog, convention learning and clarifying questions | ✅ | catalog plan |
| Agentic tool-use codegen with approved external tools | 🔬 | SDLC_AGENTIC_CODEGEN=1 |
| Local/offline or mixed-provider models, selected per stage | ✅ | models; configuration |
| PR reviewer/auditor personas, eval harness and cross-run semantic memory | ✅ | Persona registry, evals; ORCHESTRATOR_SEMANTIC_MEMORY=1 |
| Live OpenTelemetry tracing joined to the audit log | ✅ opt-in | OTEL_EXPORTER_OTLP_ENDPOINT; Setup |
| Consume external MCP tools and database schema | ✅ | mcp list, mcp call, mcp contracts, mcp ingest-db |
| Expose Spine tools, prompts and resources to Claude Code, Codex or other MCP hosts | ✅ | Agent guide; stdio or authenticated HTTP |
| Domain-grounded build through ontomesh (semantic-spine seam 1) | ✅ opt-in | SPINE_ONTOMESH_URL, SPINE_ONTOMESH_FLAVOR |
| Drift remediation and shipped-unit registration (seams 3 and 2) | 🟡 operator-gated | sdlc remediate; deployment sequence and gaps |
Documentation
| Question | Guide |
|---|---|
| What does a real run look like? | Worked example |
| How do I install, configure or troubleshoot? | Setup |
| How do I build and deliver a feature? | User Guide |
| How do I use Spine from an assistant? | Agent Guide |
| How do I run the pipeline and connect tools? | Operations |
| What does each command and flag do? | CLI Reference |
| How is the graph built and persisted? | Knowledge Graph |
| How do the platform layers fit together? | Architecture |
| What is measured, and what are the limits? | Benchmark |
| What can I share with others? | Community one-pager |
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.
License
MIT License. See LICENSE.
1 maintainer
Release files for synaptixs-spine 3.34.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| synaptixs_spine-3.34.1.tar.gz | 5.6 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| synaptixs_spine-3.34.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 6.9 MB
Release files / synaptixs_spine-3.34.1.tar.gz
| Download URL | synaptixs_spine-3.34.1.tar.gz |
|---|---|
| Size | 5.6 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d1de1911d3a2dfff2279c39fd4715406fb50f977ce12323f50762f936a03fd61
|
|
BLAKE2b-256 checksum How to use checksums |
84f176c4ed597d0e964ea3e2f3b3db095950512df498ae5a5eb3da7d2c5008ea
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.
Transparency logRelease files / synaptixs_spine-3.34.1-py3-none-any.whl
| Download URL | synaptixs_spine-3.34.1-py3-none-any.whl |
|---|---|
| Size | 1.3 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0b5adba7b2f4b5fe3aaf7b212c9482b093dedaf5f1cd0e632a70c29fc18abb6f
|
|
BLAKE2b-256 checksum How to use checksums |
2f7f7b6688b3b98d752e8756d476bf7815e9950a5083459bc34cb5bda559e099
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.
Transparency log
