Integration knowledgeas code.

SYZYGY

(siz-ih-jee)

Align every artefact — from requirements to results

Integration knowledge

Your team's integration knowledge lives in a Postman collection, a stale Confluence page, and one senior engineer's head. SYZYGY turns it into a versioned plugin your whole organisation installs — with AI-authored tests, deterministic execution, and a requirements-traceability matrix that's always current.

Test at any level — component, integration, E2E — from the same artefacts. Switch environments with one flag. Nothing duplicated, nothing drifting.

Runs entirely on your own machine or CI runner: your payloads, credentials, and results never leave your network. Free to use, including commercially.

\~/projects/checkout-api syz · latest

``

Most organisations carry their integration knowledge in five places at once: a Postman collection on one engineer's laptop, a Confluence page two years out of date, a custom test framework someone built and left behind, a folder of CI scripts no one owns, and the head of the senior engineer who is about to take a different job. None of those things are wrong. None of them are aligned.

The Framework Trap

Every team automates testing the same way: they build a framework first. Then the people who knew how the systems integrated leave, and the knowledge leaves with them. What follows is always the same pattern — a custom runner no one fully understands, a folder of "helpers" that grew organically, credentials stored in places they shouldn't be, a Confluence page two years out of date, and one engineer everyone defers to about which endpoint to call in what order. That engineer becomes a bottleneck. When that engineer leaves, so does the knowledge.

The Real Challenge Isn't Writing Assertions

The hard part of testing modern software has never been writing assertions. The hard part is where your integration knowledge lives: the endpoints, the request shapes, the order of operations, the negative-path expectations, the rules a manager calls "how we actually work." Frameworks let you write tests. They don't help you keep the knowledge that makes those tests worth writing.

SYZYGY: Integration Knowledge as a Durable Artefact

SYZYGY treats integration knowledge as the artefact. It packages that knowledge into one durable, versioned form — a plugin — and gives every developer, every test phase, and every environment the same source of truth. You version it (a git tag). You install it (`syz install`). You reuse it across every level of testing your team does, against every environment, by every developer. When the engineer leaves, the plugin stays.

SCATTERED — UNALIGNED

The old loop vs. what SYZYGY replaces it with

The old loop

What SYZYGY replaces it with

• What "correct" means lives in one person's head — written down nowhere concrete.
Captured as schema-validated `PLUGIN-GUIDE.yaml` / `DOMAIN.yaml`, in plain language, before a plugin exists.
• Build a framework first. Argue about folder conventions.
One folder, `.syz/`. Convention over config.
• Endpoints and payloads live in a doc, a Postman collection, or a senior engineer's head.
A versioned plugin per integration. Installed via `syz install`.
• Component, integration, e2e, UAT each get their own scripts.
Same plugin, same scenarios — switch the environment file.
• New team members onboard for weeks before writing a test.
`syz init` lays down the framework. The AI assistant they already use is configured automatically.
• When the integration owner leaves, the knowledge leaves.
The knowledge is committed. Versioned. Reviewed in PRs like any other code.

SYZYGY runs the whole testing lifecycle from one place — and it starts with knowledge, not code. The people who know what a system must do capture it in plain domain language as a concrete, schema-validated spec, before a single plugin exists. `syz generate` turns an API spec into a runnable plugin. Scenarios wire those plugins into tests. The runtime executes them deterministically and writes a report anyone can read. `syz rtm` ties every result back to the requirement it proves. The lifecycle below renders that path, stage by stage.

Underneath it is a single Node.js CLI (`syz`, package `syzs-cli`) that runs declarative YAML scenarios against versioned plugins that encode how your systems integrate. Scenarios, plugins, test data, and environments all live in your git repo as plain text — no server, no database, no central registry, and nothing about your work leaves your network: no cloud, no account, no telemetry. That is what makes SYZYGY usable inside a bank, a hospital, or a government department without a vendor security review.

Plain YAML, and it works without AI. Execution is fully deterministic; only the authoring conveniences — drafting specs, payloads, and semantic checks — call a model, and only when you configure a provider. AI is the recommended fast path, never a requirement.

Runs over HTTP today; the executor registry is built so Kafka, SQL, SFTP, gRPC and more drop in without changing how you author a test — see the full roadmap.

The SYZYGY lifecycle, from requirement capture to requirements traceability

Authoring Execution Audit + Review

1. 01 Authoring Capture PLUGIN-GUIDE.yaml · DOMAIN.yaml Describe how each system must behave, in plain language — before a plugin exists. 2. 02 Authoring Generate syz generate Turn an API spec into a complete, runnable plugin — deterministically. 3. 03 Authoring Author scenarios in YAML Wire plugins into declarative test flows your AI assistant drafts for you. 4. 04 Execution Execute syz run Resolve, send, validate — one deterministic lifecycle, every environment. 5. 05 Audit + Review Report index.html · ledger.json A self-contained report and an immutable ledger anyone can read. 6. 06 Audit + Review Trace syz rtm Every result tied back to the requirement it proves — a matrix that's always current.

Day one, `.syz/dossier/` already ships the knowledge layer that supports the first three stages — so capturing requirements and authoring scenarios in plain language works from the very first command.

·01

Runs on your machine

`npm install -g syzs-cli` — anywhere Node.js 20 runs. No server, no account, no telemetry. Payloads, credentials and reports never leave your network.

·02

Plugins in git

Share integration knowledge the way you share libraries. Versioned by tag, installed with `syz install`, pinned in `dependency.json`.

·03

Scenarios in YAML

Declarative, diffable, reviewable in code review. Same scenario across every test phase — switch the environment file.

·04

AI where it earns its keep

Deterministic runtime; bring any OpenAI-compatible provider for the parts that genuinely benefit from reasoning.

• 
01 · CaptureStage one: what the system must do, in plain language — before any plugin exists.
• 
02 · GenerateOne command against an OpenAPI spec produced all of this.
• 
03 · ExecuteEvery run writes this. Opens with a double-click; no server.
• 
04 · DebugA failed assertion, with what was sent, what came back, and which rule decided.
• 
05 · TraceRequirements, and the tests that prove them. Derived, never hand-maintained.

Where it bites hardest. SYZYGY earns its keep fastest in regulated, REST-heavy organisations — financial services, healthcare, insurance, government — where two costs are already being paid in full: proving to an auditor which test covers which requirement, and losing a decade of integration knowledge every time a senior engineer resigns. Teams outside those industries get the same mechanics; teams inside them have a budget line for the pain.

Start here

01 / Product owner · BA · SME

The people who own what the system is supposed to do — and rarely write code

Document each integration's behaviour and the cross-service journeys as a concrete, schema-validated spec — `PLUGIN-GUIDE.yaml` and `DOMAIN.yaml` — in plain domain language, drafted with any AI assistant out of the box, before a single plugin exists. Every requirement gets a stable ID; `covers:` links the tests to it; `syz rtm` proves the coverage. The knowledge that used to live in one person's head becomes a reviewed, versioned, traceable artefact.

02 / Platform team

The platform team owning an API used by twelve other teams

You own a payments API (or an orders API, or an auth API). Twelve other teams call it. You spend a non-trivial fraction of every sprint answering "what's the right payload for endpoint X" and "we got a 400, what does that mean". Today, every consumer team has their own ad-hoc test setup. With SYZYGY, you publish a `payments` plugin — one git repo, one `syz install` line for every consumer. Endpoints, payloads, validators, negative-test expectations, common workflows — all versioned, all in one place, all reused. New consumers onboard in an afternoon. Breaking changes propagate via a version bump.

03 / Integration team

The integration team running a multi-environment test stack

You have component tests against mocks, integration tests against a shared staging instance, end-to-end tests against a production-like environment, and UAT against a stakeholder-facing slice. Today, you maintain four different test suites. With SYZYGY, you maintain one set of scenarios and four environment files. Same plugins, same scenarios, different `--env` flag. When the API changes, you update the plugin in one place, bump the version, and re-pin in every consumer's `dependency.json`.

04 / QA lead · test manager in a regulated environment

The person who has to hand evidence to an auditor and trust the results in CI

You need exit codes that mean something, JUnit XML that GitHub Actions and Jenkins read natively, deterministic verdicts, and audit artefacts you can hand to compliance. With SYZYGY, every run produces an immutable ledger, a phase-by-phase debug log, a JUnit XML (`--reporter junit`), and a requirements-traceability matrix (`syz rtm`, with `--strict` as a CI gate that fails the build on any uncovered requirement). Every artefact is a plain file in git, reviewable in a pull request — so the evidence pack for a release is a commit range, not a screenshot folder assembled the week before the audit. Live progress panels are opt-in (`--live-stats`) for your local executions. Sensitive fields are masked everywhere, including the report. The exit code is a per-verdict signal CI can branch on — `0` all passed, `1` a check failed, `2` bad input or setup, `3` an upstream system faulted, `4` no verdict delivered, `130` interrupted.

• ### We already use an API test tool — for free. Why this?
The API-testing landscape is crowded and mostly free, and every tool in it is good at calling an API and asserting on the response:

* Postman · Insomnia · Bruno — API clients: explore endpoints, build collections, script assertions (Postman's Postbot even drafts them from the response it just saw). * SoapUI · Karate · REST Assured — functional API test frameworks and DSLs. * Pact — consumer-driven contract testing. * k6 · JMeter · Gatling — load and performance. * Schemathesis · Dredd — spec-conformance and property testing. Each is strong at its job. But they all start from the call, and at best codify the behaviour they just observed — there's no requirement to trace back to. SYZYGY isn't another entry in that list: it treats integration knowledge as the artefact. Requirements are first-class and schema-validated (`PLUGIN-GUIDE.yaml` / `DOMAIN.yaml`); tests link to them with `covers:`, and `syz rtm` derives the traceability matrix. Plugins are versioned and installed across your org like libraries, execution is deterministic, and nothing syncs to a vendor cloud. Keep the client you like for ad-hoc calls — SYZYGY is the durable, provable layer underneath.

• ### I already have an AI model that can write the tests. Why this?
A model can draft test scripts — but two problems remain. Generation drifts: ask twice and you get two different shapes, and you still own and maintain whatever it produced. `syz generate` is deterministic — no model in the path, reproducible on every run — and it emits a complete, enterprise-grade framework (runtime, immutable ledger, HTML + JUnit reporting, and the traceability matrix), so the framework is off your plate, not something a model reinvents per prompt.

And the knowledge takes the big seat. Raw model-written scripts bury what the system is supposed to do inside the script, where it drifts and can't be traced. SYZYGY inverts that — testing starts from knowledge captured as a durable, schema-validated artefact (`PLUGIN-GUIDE.yaml` / `DOMAIN.yaml`), and the tests derive from it and trace back to it with `covers:`. The model still helps you author — but against a versioned contract, with deterministic execution and a matrix proving coverage, not a pile of scripts no one owns.

• ### We already capture requirements in our Project Management tool. Why here again?
Yes — and keep it. Jira, Azure DevOps Boards, Confluence, Linear, monday.com, or a formal tool like Jama Connect or IBM DOORS are built to capture and triage work, and SYZYGY doesn't replace planning. Two problems, though. Mapping those tickets to the tests that prove them is manual, and deriving a requirements-traceability matrix from them is ongoing, hand-maintained effort. And those boards are organised around teams, not systems — scrum, squad, project. When a project closes or the org restructures, that work is archived; finding one system's requirements in an ocean of tickets, then migrating years of work, is heavy lifting few people ever finish. You end up with tests and no record of why each one exists. SYZYGY captures requirements as schema-validated artefacts tied to the system — `PLUGIN-GUIDE.yaml` per integration, `DOMAIN.yaml` for cross-service journeys — each carrying a stable id (`REQ-…`), versioned in git and linked to tests with `covers:` from day one. `syz rtm` derives the matrix on demand, never by hand.

And nothing is orphaned from where it started. Record the originating ticket — its id or URL — in the requirement's `references` field, and tag that ticket with the SYZYGY `REQ-…` id in your tracker: the two now point at each other, so anyone can trace a test back through its requirement to the original ask, and forward again. Unlike the ticket, that cross-reference lives in git history — it survives the requirement changing, the project closing, or the board being archived. Keep your planning tool for triage; SYZYGY is where the durable, system-aligned, test-linked requirement record lives.

• ### We already use Cucumber / BDD to write tests in business language. Why this?
BDD's promise is one shared, business-readable spec. In practice, the pressure to reuse and optimise step definitions bends the `Given` / `When` / `Then` to fit the technical flow — open your `.feature` files and ask honestly how much a non-technical domain owner can still read. The business language and the automation are welded into the same file, and the automation usually wins. SYZYGY splits them cleanly. Requirements are the business-language layer — `PLUGIN-GUIDE.yaml` records each behaviour as plain-English `given` / `when` / `then`, owned by the people who know the domain. Tests are the technical layer — scenarios in YAML, written however they need to be — and they simply link back to the requirements they exercise with `covers:`. `syz rtm` then shows precisely which test covers which requirement. Domain owners write requirements in plain language; engineers write tests without contorting them into a business-readable DSL. Neither side compromises to satisfy the other.
• ### What does it cost?
Nothing. The CLI is free to install and use — no paid tier, no seat count, no usage limit, and no trial clock. That includes use inside a commercial, for-profit company: a bank automating its integration testing pays nothing. The one boundary is monetising the software itself. You may not resell it, host it for third parties, offer it as a service, or use it to build a competing product. Use it as intended, free, forever; don't repackage it as your own. Anything outside that, email enquiry \[at\] syz.sh.
• ### Why isn't it open source?
Deliberately. SYZYGY is free to use, but proprietary — the source isn't public and it isn't open to community forks. That's a stewardship choice, not a commercial one. The method underneath it — knowledge as the artefact, every requirement aligned to a result — is easy to dilute, and we've watched respected test frameworks lose their way once they fragmented into a dozen incompatible flavours, each drifting from the intent that made the tool worth having. We'd rather nurture SYZYGY carefully, shaped by how real teams use it and what they tell us, than optimise for how many variants exist. Even the finest tool rusts into a liability when it's wielded without care — and the real world offers no shortage of examples. Free to use, yes; free to fragment, no. Ideas, needs, and requests genuinely steer it — that's what support \[at\] syz.sh is for.
• ### Where does my data go?
Nowhere. There is no SYZYGY cloud, no account, and no telemetry — nothing about you, your systems, or your tests is collected. Payloads, credentials, responses and reports stay on the machine that ran them. The CLI's only outbound calls are: your systems under test, your git remote on `syz install`, your own AI provider if you configure one, and a single npm-registry version check that sends no data about you, is dormant in CI, and is disabled with `SYZ_NO_UPDATE_CHECK=1`. Full detail on the depth page.
• ### Is it production-ready?
It's pre-1.0, early access, and honestly labelled. The execution model, ledger, reporting, and traceability are shipped and stable — everything shown on this site works today. What's not there yet is protocol breadth: HTTP is the only executor, with Kafka, SQL, SFTP and the rest on the roadmap and prioritised by what teams actually ask for. Sensible move today is a single-team pilot, not an org-wide rollout.
• ### Do I need to know how to code?
No, and that's a design goal rather than a slogan. `syz init` configures the AI assistant your team already uses with the full framework contract, so requirements capture and scenario authoring happen in plain language — see the AI-assistant capability on the depth page, and the plain-language playbook in the dossier. And the runtime doesn't require AI at all — it's plain YAML, executed deterministically; AI only assists authoring when you configure a provider. What you do need is someone comfortable reading YAML when a test fails: the artefacts are designed to be legible, not opaque.
• ### What is it not?

Aligned

Install it.

One command. Node.js 20+. No infrastructure to stand up.

$ `npm install -g syzs-cli`

Early access — first adopters being onboarded.

Questions, ideas, feedback, or a bug to report? Email support \[at\] syz.sh — we'll clarify, consider, learn, and resolve it.