Spine

Governed, provenance-grounded autonomous delivery — turn requirements into reviewed, tested pull requests, with a human in control.

Naming. Spine is the product. It's distributed as the synaptixs-spine package and its command is orchestrator — those names stay in install lines and commands throughout the docs.

Spine reads a requirement (from Confluence, Notion, a Markdown file, or an OpenSpec spec-driven change), understands your target repo, generates code grounded in that repo's own conventions, writes and runs tests, and opens a pull request for you to review. It pauses for your approval before it starts and before anything merges. Nothing is pushed, merged, or written to your tracker unless you say so.

It's built for teams who want agents that are inspectable, reproducible, and safe to run on real code — not demos.

How it fits together. Everything starts from one deterministic graph of your repo — built from the code and its docs — and every surface is a read of that graph:

flowchart LR
    repo["Your repo<br/>(code + docs)"]
    pkg["Product Knowledge Graph<br/>(deterministic, file:line)"]
    know["understand / state<br/>(episteme + health)"]
    ask["What breaks if I<br/>change X? What's<br/>untested?"]
    build["sdlc feature<br/>(grounded codegen)"]
    pr["Reviewed PR"]
    repo --> pkg
    pkg --> know
    pkg --> ask
    pkg --> build
    build --> pr

pip install synaptixs-spine
orchestrator init && orchestrator doctor                  # scaffold .env, check readiness
orchestrator sdlc feature --source file://./spec.md --safe   # build locally — no pushes, no PRs

👉 See it work end to end — one ticket, start to finish

A real bug, in a real public codebase you can clone yourself (pallets/click) — from "where does this even live?" to a reviewed PR. Every command is one you can run, and the output is real. It finds the four functions in the blast radius that no test covers, in about a minute, with no API key.

🔒 Security

Spine runs on real code, clones untrusted repositories, and executes generated code — so we hold its own source to the same bar.

• Checks run in CI on every pull request: CodeQL (Python + JavaScript), pip-audit over the locked dependency set, bandit-class static analysis, and Dependabot.
• We security-reviewed our own source with a multi-model adversarial pass — 7 confirmed issues fixed, each with a regression test (path traversal, an SSRF backstop gap, prompt-injection hardening in the review pipeline, and a web-UI XSS). Details in the changelog.
• All patchable dependency CVEs are resolved, and the audit fails CI on any new one.

Found something? Please follow our coordinated-disclosure policy in SECURITY.md — don't open a public issue.

Documentation

New here? Install → User Guide Steps 1–4. That's the whole everyday workflow in about ten minutes.

Features & capabilities

Requirements → reviewed PR. Point it at a requirements source and a code repo. It extracts a backlog of intents, writes a spec, generates the implementation and tests, gets them green, and opens a PR — with two human gates (before building, before merging). A safe mode builds entirely locally (branch + diff, no external writes) so you can inspect everything first.

Code-grounded understanding. Before generating, it builds a Product Knowledge Graph of your repo — modules, types, functions, call sites, blast radius — and grounds new code in what already exists, so output reads like your team wrote it. Works across Python, Java, TypeScript, C#, C, C++, and Go, plus SQL data-layer comprehension (schema, queries, stored procedures, migration folding). Java JAX-RS and Jakarta REST resources are captured as grounded API endpoints. It even reads your documentation — Markdown, reST, plain text, and PDF — folding it into the graph as Doc nodes linked to the code they describe, so you can ask which docs cover this symbol, how documented the code is, and where the docs have drifted from the code. orchestrator understand writes a committed, code-true episteme/ your whole team (and any AI tool) can read — epistēmē, knowledge grounded in evidence, because every word of it is derived from the code rather than written by hand.

Governed autonomy. The workflow itself is a typed, validated artifact. A planner decomposes the objective, a runtime executes it, and per-edge verifiers check every step against schemas, evidence, and policy. Failures trigger replan, a human approval, or a clean stop. Every tool call, approval, and decision lands in an append-only audit log, and each run is capped by a spend budget.

Learns across runs. Cross-run semantic memory lets the agent recall conventions, pitfalls, and decisions from past runs — each memory cites the run it came from.

You can see inside it. Live OpenTelemetry tracing covers every LLM call, loop step, and tool call, joined to the audit log — so you can debug a run, not just read its result.

Use it your way. A CLI for scripting and CI, a web dashboard (delegate runs, watch them live, approve gates inline), a terminal UI, and MCP in both directions — consume external MCP tools, or expose the whole pipeline as an MCP server to Claude Code, Codex, or your IDE.

Bring your own model. Multi-provider via LiteLLM (Anthropic, OpenAI, Bedrock), or run fully offline on a local model (Ollama). Mix models per stage.

Durable. Long-running pipelines are checkpointed (Temporal + Postgres) — they survive restarts and resume across human approval pauses.

How it works

A request flows top to bottom — through comprehension and planning, into a governed execution loop that pauses at two human gates — and out as a reviewed PR. The full architecture, with an animated diagram, is in ARCHITECTURE.md.

  requirement (Confluence / Notion / Markdown)
        │
        ▼
   plan ──► validate ──► generate code ──► run tests ──► review ──► open PR
        │        (grounded in your repo's knowledge graph)        │
        └──────────── per-edge verifiers + audit ────────────────┘
                 human gate 1 ▲                    ▲ human gate 2
                 (before build)                    (before merge)

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? Code generation and comprehension cover Python, Java, TypeScript, C#, C, C++, and Go (Java also extracts JAX-RS / Jakarta REST endpoints; C# extracts ASP.NET Core endpoints and EF Core entities; C builds the #include graph and merges header declarations with their source definitions; C++ is a superset of the C front-end that adds classes, namespaces, inheritance, member functions, and templates, and shares C's CMake/Meson + ctest codegen; Go models a package as its directory, extracts calls and — via method-set matching — interface satisfaction (IMPLEMENTS), and generates code built + tested with go build/go test, multi-module aware). SQL ([sql] extra) adds data-layer comprehension — schema, foreign keys, views, queries, stored procedures, and ordered-migration folding, grounded from .sql source — plus greenfield codegen (sdlc feature --language sql): it generates a migration and validates it by applying it to an ephemeral database (in-memory SQLite by default). Documentation is folded in automatically on understand/state (Markdown/reST/text and HTML need nothing; PDF needs [docs], Word/Excel need [office]). Media — diagrams, screenshots, recorded design reviews — join the graph too via the opt-in orchestrator media extract (image OCR with [media], audio/video transcription with [asr]); the model runs only in that command, never in the deterministic build. Any LiteLLM-supported provider (Anthropic, OpenAI, Bedrock) or a local Ollama model; you can set a different model per stage.

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 (or terminal UI) for watching runs and approving gates by hand.

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).

Contributing & feedback

We'd love your input. Pick the channel that fits:

• 🐛 Bug? Open a bug report.
• 💡 Feature idea / enhancement? Open a feature request.
• 💬 Question, feedback, or idea to discuss? Start a Discussion.
• 🔒 Security issue? Please follow SECURITY.md — don't open a public issue.

See CONTRIBUTING.md and the CODE_OF_CONDUCT.md for how contributions are reviewed.

License

MIT License. See LICENSE.