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 fourteen front-ends: Python, Java, TypeScript, JavaScript, C#, C, C++, Go, Rust, 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.57.1 (current) — OpenSpec drafts preserve the stated problem, users, outcome, non-goals, and structured source title. The feature runner excludes benchmark test scratch from application coverage, and acceptance review sees the tracked changed lines before bounded source excerpts. See the CHANGELOG.

3.57.0 — blast_radius and explain_symbol stop hiding what they cannot trace. A name shared by many symbols now details the first 7 and reports match_count and truncated, and a qualified name such as FactStore.summary selects one; the "Called by" line says it counts only callers the graph can type; and for a Python function both tools return unresolved_calls — same-named call sites the graph could not bind to a receiver type, each with its receiver's source text — a hint that never changes caller_count. Other languages report null and a note, never 0. Upgrade note: the first run after upgrading re-extracts each cached repository, and the new data is a .unbound.json file beside each cache entry. See the CHANGELOG.

3.56.0 — Spine checks requirements, not only builds from them. orchestrator openspec check is a deterministic clarity gate (stated problem, named users, observable outcome, every open question answered or deferred to a named owner) that also lists which criteria already name code that exists; openspec answer records an answer under its question with the channel Spine observed; both are available as MCP tools. No new model call anywhere in it. A malformed structured response from the model now gets a bounded corrective retry instead of ending a codegen run. Upgrade note: a cache entry written with why-fields is a miss for an older Spine, so an approval granted on that spec goes stale there; caches without why-fields read and write exactly as before. See the CHANGELOG.

3.55.0 — Extensive Rust support on supported hosts. Async/Tokio, procedural-macro source boundaries, no_std, and one non-default Cargo feature have pinned corpus and real-repository evidence; Rust facts retain 1.00 precision across all 14 hand-labelled cases. Cargo codegen now identifies missing targets, linkers, and custom JSON target files before running. The three known cross-module CALLS misses, macro expansion, type-aware dispatch, full feature matrices, and embedded firmware execution remain explicit limits. See the validation record.

3.54.0 — required-behavior gates, and Core Rust support signed off. A project opts in by committing .spine/required-behavior.yaml: checks the model does not author and cannot edit away, re-verified after every refinement in sdlc feature's native loop — closing the ONTM-4 gap where a generated test passed without exercising a feature's real default wiring. [rust] comprehension (Cargo topology, precision-safe local calls) and Cargo-aware codegen/build/test are both signed off for supported hosts; the installed parser's upstream grammar error is closed by pinning tree-sitter-rust-orchard. Upgrade notes: a legacy project without a manifest takes the exact code path it took before — opting in is additive, not a breaking change.

3.53.0 — Python's call graph reaches through a typed variable, and a locked pyjwt closes ten published advisories. A parameter annotation, a local assigned once from a constructor, or a self.attr typed by a class annotation now gives a method a caller in the graph (blast_radius, impact_of, docs_for and codegen's refine all see it): +2,077 CALLS edges on this repository, precision held at 1.00 with a decoy-backed corpus case. Concurrent sdlc features on one worker no longer switch each other's codegen guards off. Upgrade notes: a plan grounded in a method that gained callers can read as changed — re-approve it; pyjwt moves to 2.15.1 (ten advisories against the old pin).

3.52.0 — docs in the blast radius, and codegen that stays in scope. blast_radius, explain_symbol and docs_for list the doc sections that describe a symbol: the repository's own, plus Confluence and Jira pages and any RAG system's chunks pulled over MCP (orchestrator mcp ingest-docs, a docs: block in .spine/repos.yaml). ${VAR} in mcp.json headers and urls is read from the environment, so a token need not sit in the file. Codegen no longer edits files a ticket is not about (on OpenAI models it used to touch 6–9 per run), and refine can fix lint and type errors in the tests it wrote without dropping their asserts. Upgrade notes: a plan whose ticket names a module can read as changed and needs approving again; a literal ${NAME} in an mcp.json header or url now needs NAME set, or $${NAME}.

3.51.1 — a sandbox fix. run_python_analysis on the local sandbox enforces its time limit twice, as wall-clock time and as a CPU-time limit, and a busy loop reaches both at once. When the CPU limit won, about one run in six, the tool raised ProcessLookupError or returned exit -24 with an empty stderr. It now reports exit 124 and timeout after Ns either way, adding of CPU time when the CPU limit stopped it.

3.51.0 — --layout auto never scaffolds a second project beside code it cannot place, in any language but SQL. 3.50.0 stopped this for Python; C#, TypeScript, Java, Kotlin, Go, C and C++ now stop too, with exit 2 and the build file they looked for (no .csproj, no go.mod, …). A TypeScript, Go, C or C++ project below the root (frontend/package.json, svc/go.mod, native/CMakeLists.txt) is followed rather than refused, and its dependencies install and tests run in that directory. sdlc plan warns before the Build that it would stop. Upgrade notes: a Build that used to scaffold beside existing code now exits 2 — pass --layout existing or --layout new; plans for such repositories gain a finding and need approving again.

3.50.0 — field fixes for .NET and Python builds. A workspace base that git can no longer read is rebuilt instead of failing every run, and bases move from /tmp to ~/.cache/orchestrator/sdlc-workspaces, one per repository. C# code declares the project's own namespace (its <RootNamespace>), an illegal namespace/using line is refused before it is written, and refine leads with the compiler's first error. A Python run takes a test baseline first and judges only the failures it caused, and follows AWS SAM and top-level-module repositories. Plans report files the spec invents and criteria nobody stated, and stop rating a keyword guess "high". Upgrade notes: --layout auto on Python now stops rather than scaffold beside existing code; approvals made before the upgrade read as stale once; run sdlc plan --refresh for tickets cached earlier.

3.49.0 — plans that say what they were built from, and a way to rebuild them. --follow-links now reports how many linked Confluence pages actually reached the spec — whole, cut, or left out by the extractor's 60,000-char budget — instead of how many were fetched, with a warning when any did not fit; autorun and investigate report it too. New sdlc plan --refresh re-extracts a cached spec (ticket-only or --follow-links) and says when that stales an approval. Past 20 attachments the extractor again reads exactly what 3.44.0 did. Upgrade note: Spine 3.44 or older deletes --follow-links cache entries if run on the same cache.

3.48.0 — sdlc autorun --live opens its pull request after its own review, with the review's fixes committed in it; a review that does not finish clean opens a draft PR saying why and exits 1 instead of ending done. SDLC_RUN_BUDGET_USD now caps sdlc feature and sdlc autorun too ($25 by default, 0 disables) — upgrade note: an uncapped run that spends more now stops; set the variable to raise the cap. The Java/C# type lookup also sees every binding closer than the one it used to find (local classes, anonymous-class bodies, qualified heads, member types an external base declares) — on guava 16 edges moved, all 16 now right.

3.47.0 — Java and C# graphs that say who calls what. A call through a typed receiver — _service.Do() through a field, repo.Load(id) through a parameter, a typed local — now lands on the member the declared type means (on a .NET service, 2,427 of 2,427 resolvable calls, from 0), and new Foo() is a call to Foo, so a class's blast_radius lists who creates it. ASP.NET Core DI registrations become PROVIDES, and blast_radius reaches an implementation's callers through the interface it implements — reported apart, since they may reach it. Anything the compiler would find ambiguous, or whose type is not written, is refused rather than guessed.

3.46.0 — graphs that say who really calls what. A Python call through a re-export (from app import Store) now lands on the symbol that defines it instead of a phantom third-party twin — on Spine's own graph that moved 1,271 calls to their real targets — and pkg verify warns on any phantom-symbol left. Kotlin: a file whose one-line body tripped the parser is recovered instead of losing everything after it; wildcard-imported Room entities and cross-file same-package extensions resolve; and a bare call inside with(x) { } is no longer pinned on the enclosing class (17 invented self-calls gone from the Android validation app).

3.45.0 — a plan's criteria are checked against the whole ticket. sdlc plan --source now reads the ticket fresh at every plan with every attachment in full (up to 20), while the AI that writes the spec still reads the same bounded summary — so nothing already approved moves. --follow-links also reads the Confluence pages a ticket links to (at most 5, refusing without Confluence access rather than reading less than you asked for). A Jira ticket read through an MCP server now carries its comments, links and attachments like one read over REST. An unreadable ticket is a clean error, not a traceback. Removed: sdlc plan --out and sdlc approve --out, as 3.44.0 announced.

3.44.0 — an approved plan is the plan that builds. sdlc plan → sdlc approve → sdlc autorun could refuse a plan nobody had changed. Writing the plan into .spine/plans/ made the repo look modified, so the gate refused the approval it had just been given — the exact sequence the spine-sdlc.yml build job runs. A Bug that matched no code lost its approval because the gate forgot the issue type. --spec with --source crashed. All three are fixed: the spec stays the requirements and the ticket is read, with no model call, for the criteria check. A Jira ticket read through an MCP server now says it is the description only. sdlc plan --out and sdlc approve --out are deprecated — a plan written elsewhere is one autorun can never build — and go in 3.45.

3.43.1 — a Python fix. A repository whose src/ is a package — it has an __init__.py, and the code imports from src.services.x import … — got a graph with no in-repo imports: module ids dropped src., the imports kept it, and nothing joined, so pkg verify reported nearly every module as imported by nothing. src/ is now stripped only when it is a plain source root; a package src/ keeps its name. The standard src layout is unchanged.

3.43.0 — JavaScript, the 13th front-end. .js, .jsx, .mjs and .cjs used to reach the walker with no front-end and produce nothing: express and react-boilerplate extracted to zero nodes. They now extract CommonJS require and exports, JSX, Express routes and a Sequelize data layer, on the existing typescript extra — no new install. A .ts file importing a .js one resolves across the pair.

The hard part is CommonJS: a module's exports are whatever its code assigns, so each module is read into one of three tiers — readable, names-known or opaque — and a call into it is trusted only as far as its own file says. Twenty hand-labelled corpus cases: precision 1.00 on every node and edge kind, CALLS recall 0.97, and zero dangling edges on four real repositories. Codegen for JavaScript is not part of this.

Also fixed, in TypeScript as well: import './mod.js' and from '..' no longer mint modules no file declares, and a member call on a rebound name no longer resolves through the file's namespace. sdlc plan now prices from the LiteLLM map that ships, so the same commit always writes the same build document.

3.42.0 — a round of Kotlin precision work, and a gate that was punishing honesty. Six reported Kotlin defects are closed, including an extension call that resolved onto an id nothing declares: comparing receiver names refused every subtype receiver, so fun NavController.navigateToSearch() called on a NavHostController — the standard Compose pattern — lost its real edge and gained an invented one. Four of those on the Android validation app, with every gate green, because the fabricated edges replaced true ones rather than adding to the count.

Alongside them, the accuracy gate no longer fails a build for writing down a known limitation. Labelling a known_gaps entry lowered the recall ratio with nothing about the extractor having changed, and the only remedy was regenerating the baseline — which accepts everything that moved. Corpus recall is now gated on unexplained misses instead, the published score is untouched, and enforcing that a gap must name an edge actually missed turned up four dead entries, three of which were quietly paying for two real misses nobody could see.

scoreboard.json is version 2 as a result: run orchestrator pkg accuracy --scoreboard once after upgrading.

3.41.0 — a drafted spec now ships with the code's facts. openspec draft could not see a repository: its whole signature was --source/--out/--refresh/--overwrite, so a draft could only restate the ticket more formally, and its task list was the same two checkboxes for every change ever drafted. Pass a repo path (or --repos) and the proposal carries where the change lands with file:line, each stated criterion bound against the graph, and the criteria that name code which already exists — evidence for a human, never a verdict, because a run reporting a criterion met having changed nothing is the failure this is built to catch. The task list becomes one checkbox per criterion, with the model's own suggestions kept in their own labelled group. It does not improve the prose: the requirements are still written from the source document alone, and the point is that you can now tell which half is which — a line with no file:line has been checked by nothing. Absence is stated in four distinguishable ways, because a reader who cannot tell "we looked and found nothing" from "we never looked" will assume the flattering one: a language Spine has no front-end for yields zero nodes and looks exactly like a repository with nothing to find, and a draft taken from an uncommitted tree says so in the file, where a stderr warning would have scrolled away.

3.40.0 — the briefs stop pointing at code and start showing it. investigate and root-cause rendered the graph's index — symbol names, file:line, caller counts — and contained zero lines of source, so a reader opened the files the brief had already located. Each landing site now carries the code at its line and says whether a test reaches it; a root-cause report quotes its fault site, so "ranked by evidence, not asserted" means the evidence is on the page. A landing the brief itself calls weak gets neither — on a real ticket the first attempt spent two excerpts on DTOs matched on a three-letter fragment and printed "no test reaches this" in bold on all ten rows, which is a signal that has stopped being one. Where the graph cannot answer, the brief says nothing rather than accusing: a front-end that emits no call edges has not proven an absence of tests. And a merged multi-repo brief reads each repository's own episteme/ under its key, so the mode a cross-cutting ticket needs is no longer the only one with no project knowledge.

3.39.0 — a run now builds in the project the ticket is about. In a solution with several projects the target used to be whichever one sorted first, so a WebApp ticket scaffolded into an API client and failed six test runs against a type that project cannot even see. Spine picks the project holding the files the plan names, else the one with the most source in that language, and says which rule it used; --package-name now retargets rather than merely renaming, so a human can overrule it. Java multi-module builds resolve at all — at any depth — and Kotlin scope functions are refused by name and shape, so r.run() keeps its edge while m.let { } stops inventing one. Two CI guards that could be skipped rather than passed are closed.

3.38.0 — two field reports from a React Native engagement, and the build document stops flattering itself. A vendored ios/Pods is no longer walked, and a symlinked file keeps its own path — so node_modules cannot return one header at a time through CocoaPods' public headers. --language auto weighs what most of the source is rather than what merely exists, so one build script no longer scaffolds a Python package into a React Native app. The coverage probe asks only what a test could answer and names what it excluded; a test the run itself wrote to cover a gap is withdrawn and said so rather than chased until the budget dies. Section 12 no longer scores the brief agreeing with a design taken from that brief, and section 8's stated is earned by matching a whole line of the ticket. Retrieval reads a ticket's inflections, so "account deletion" reaches DeleteAccountScreen.

3.37.0 — two field reports from a C#/.NET engagement, both diagnosed to defects and both now fixtures. Blazor components enter the graph: .razor is read as line-aligned C# through the C# front-end (no new grammar or extra), every symbol on its true line, with corpus/csharp/razor at precision 1.00 / recall 1.00. A file in a shared namespace is no longer reported "absent from the knowledge graph"; the spec writer no longer drops the identifiers a ticket named, and a ticket can name its file in any language, by path or bare name. Retrieval carries its evidence and floors weak hits, so an all-weak ticket says locate the change before building instead of proposing five confident wrong paths. Jira attachments are read on intake, not only named.

3.36.0 — 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, and comprehension alone covers JavaScript — 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). Rust comprehension and Cargo-aware codegen are signed off for supported hosts; async, macro-boundary, feature-gated and no_std source validation is recorded in the Extensive Rust evidence. 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.

{
  "name": "spine",
  "owner": {
    "name": "Synaptixs",
    "url": "https://github.com/synaptixs/spine"
  },
  "description": "Spine's Claude Code plugin marketplace — delegate a ticket, get a reviewed PR.",
  "plugins": [
    {
      "name": "spine",
      "source": "./plugins/spine",
      "description": "Understand any codebase, then ship changes to it. Read-only comprehension tools hand you engineering decisions (what breaks if you change X, what's untested, where a ticket lands) from a deterministic Product Knowledge Graph — across one repository or several. Then delegate a ticket and, on confirm, get a reviewed, tested PR. Greenfield + brownfield across Python, Java, Kotlin, TypeScript, C#, C, C++, Go, PHP, Perl, and SQL; Rust comprehension and Cargo-aware codegen are validated on supported hosts, exposed as MCP tools + an understand-codebase skill.",
      "version": "3.57.1",
      "category": "Engineering",
      "keywords": [
        "sdlc",
        "codegen",
        "mcp",
        "knowledge-graph",
        "greenfield",
        "brownfield",
        "pkg",
        "multi-repo"
      ]
    }
  ]
}