v0.1.0 first release · Apache-2.0

SeamSpec

Build first; every seam that works gets a spec.

Your AI agent can't quietly renegotiate what your team agreed. Say what must stay true, and SeamSpec turns it into a small rule with a test that you approve, then stops any change that breaks it, whoever makes it: when the agent finishes, at commit, and in CI.

uv tool install seamspec
How it works

Built forClaude CodeCursorVS Code CopilotAntigravity

Illustration of the workflow: a working change is proposed as an invariant, approved with seamspec review, then a later regression is blocked before the agent can finish.

How it works

Vibe. Lock. Enforced.

What you agree with your agent lives in one chat, and is gone by the next session. A notes file helps, but it is advice to whichever agent reads it. SeamSpec captures what you agree as tested rules, one working seam at a time, and lets the spec harden behind you.

  1. Vibe build freely

    Build with your agent the way you already do. No upfront spec, no ceremony. SeamSpec stays out of the way while you explore.

    no spec-first stepkeep your flow

  2. Lock capture what works

    When you state an agreement, or a behavior works, the agent proposes an invariant backed by a test that already passes. Nobody writes it by hand; you approve it with one keystroke.

    seamspec reviewhuman-approved

  3. Enforced never silently break

    Locked invariants are checked by editor hooks while the agent works, by git pre-commit, and in CI. Regressions get blocked, not discovered later.

    hookspre-commitCI

A day with SeamSpec

Meet Maya. Scroll through her day.

Maya is building a habit tracker with her coding agent. Here is one ordinary day, and the moment a week later when SeamSpec pays off.

The workflow as builtNo commands to memorise: just ask in plain words

  1. 1Mon 9:00 · Dump

    Maya dumps her thoughts.

    Before coding, she types messy notes into BRAINDUMP.md: a rule, a choice, something that failed yesterday. No format, no ceremony. It's her file, and SeamSpec never rewrites it.

  2. 2Mon 9:05 · Drain

    Her agent offers to sort the mess.

    When her session starts, the agent notices 4 new notes and asks to sort them. She says yes; no command needed. The SQLite decision is proposed, with its why. The failed Redis attempt becomes a dead end straight away. The streak rule becomes planned: that code doesn't exist yet, so the agent is shown the rule while it builds and proposes it once the code works. Ideas stay in the braindump.

  3. 3Mon 11:00 · Build

    She vibes. The agent builds.

    Maya asks for the streak feature. Before the first edit, the agent is handed the history that matters: use SQLite, Redis already failed. It doesn't repeat yesterday's mistake.

  4. 4Mon 14:00 · Lock

    It works, so it gets a spec.

    Streaks now reset correctly. The agent proposes a spec: a plain-language rule plus the test that proves it. Nothing is locked yet.

  5. 5Mon 18:00 · Review

    One command, a few minutes of review.

    Maya runs seamspec review. She reads each rule and its test, sees that it fails without the change, and answers with one key: she accepts the decision, approves three rules and rejects one. It's the one command she runs herself, and she's reminded when it's due. Only what she approves becomes locked.

  6. 6A week later · Enforced

    The agent breaks it. Maya never notices.

    A refactor quietly moves streak resets to UTC. The locked test fails, and the agent can't finish until it's fixed, so it fixes it. Anything that slips past is caught by git pre-commit and CI.

A living ledger

Agreements that live in your repository.

Plain files in your repo, one record per file, reviewable in pull requests. No chat history required.

Invariants

Behavioral rules, each backed by an executable test and scoped to the files it governs. Changing one on purpose means an explicit supersede.

Dead ends

Approaches that were tried and failed, with the symptom. The agent records them directly, so it stops retrying what already didn't work.

Decisions

The why behind each invariant, as lightweight ADRs. Future sessions, and future teammates, inherit the reasoning, not just the rule.

Enforcement

Enforce outcomes, not prompts.

Agents can change files in many ways. The gates that matter check results (tests pass, hashes match) regardless of how the change was made.

  1. 01 Context Constraints served to the agent via MCP or CLI soft
  2. 02 Edit-time context Before the agent edits a governed file, it is shown the rules and past dead ends (Claude Code; in the other tools, at the start of every chat) early warning
  3. 03 Completion gate The agent can't finish while a locked invariant fails hard
  4. 04 git pre-commit Runs locked invariants before every commit hard
  5. 05 CI Full verification, ledger integrity and a list of retired rules on every push final gate

Claude Code, Cursor, VS Code Copilot and Antigravity. SeamSpec plugs into each app's own hooks, and the check when the agent finishes runs in all four; it has been tried hands-on in each. Tools without hooks are still covered by git pre-commit and CI. For a team, CI as a required check is the gate that guards main, whoever made the change.

Asymmetric trust

Anything that constrains the future (an invariant) needs your approval. Anything that only warns (a dead end) the agent can record itself.

Model-free core

SeamSpec never calls an LLM. The agent already in your session does the language work; SeamSpec validates, stores, verifies and enforces.

Fail open in-session, fail closed at the gate

A crashing hook won't brick your agent. CI is the uncompromising backstop.

Any test runner

pytest and vitest first; jest, go test, cargo and a custom runner for everything else are planned next.

What we measured

Tested against the alternatives, ties included.

Three small projects with agreements that later requests tempt the agent to break, run with Claude Sonnet 5.5. Each plan and pass bar was fixed before its run; violations were checked by hidden tests the agent never saw.

SeamSpec Agent keeps its own notes Nothing
Agreements only said in chat: broken three sessions later 15 runs each0822
Agreements captured as tested rules, with nobody writing them39 of 40n/an/a
A teammate's agent, in a fresh clone: broken agreements that reached main 9 runs each0612

With plain tests and a stop hook instead, agents rewrote the rule tests 12 times; SeamSpec's locked tests stayed as approved. Every plan, result and allowed claim is published: capture, second actor, plain tests, long session, and the decision records.

Where SeamSpec doesn't win: notes a person wrote carefully in CLAUDE.md broke 0 agreements too, because a careful agent respects a good notes file. Within one long session, nothing slipped in any setup; agreements get lost between sessions. And the guard can be stricter than you meant: in 2 of 9 runs, CI blocked a change that broke nothing the benchmark checked, because a captured rule pinned a detail that had been stated. SeamSpec's difference is that its rules are tests, captured for you, enforced at commit and in CI, and changed only with your approval.

For teams

Whoever changes the code, a broken agreement doesn't reach main.

A teammate, their agent, another tool, or someone editing by hand: notes can only advise them. SeamSpec's rules are tests that CI runs on every pull request.

CI guards main

seamspec init --ci adds a workflow that runs every approved rule on each pull request. Make its check required, and a change that breaks an agreement can't be merged.

Changes need a yes

An agent can't quietly rewrite a rule or its test. A requirement that really changed goes through a supersede request a person approves, with the history kept.

Keep your notes too

A good CLAUDE.md still helps every agent understand the project. Use SeamSpec for the few agreements that would really hurt if broken: money, data contracts, public APIs.

vs spec-first

Specify, then build? Or build, and let the spec harden behind you.

Tools such as Spec Kit, OpenSpec and Kiro's spec mode take a spec-first approach: agree on the spec, then build to it. SeamSpec works the other way round: build, then capture what works as a spec.

Spec-firstapproach SeamSpecbuild-first
When the spec is writtenBefore code, describing intended behaviorAfter code works, recording proven behavior
What the spec isRequirements, design and tasks, mostly in proseSmall invariants, each backed by a test that already passes
Where the tests come fromPlanned from the spec, written during implementationCaptured from behavior you have already seen work
When you reviewBefore implementation, on the planAfter verification, on each proposed rule, in batches
Day-to-day flowAgree on the spec, then build to itBuild freely, then lock in what works
Best suited toFeatures where the design should be agreed up frontExploratory work where you find the design by building

This compares two approaches, not individual tools. Spec-first tools differ, and several also run tests, hooks or checks of their own.

The honest trade-off: SeamSpec prevents regressions, not bad designs. An up-front spec review can catch a wrong architecture before code exists; SeamSpec makes sure you never silently break what already works. The two approaches are complementary, and you can use both.

Install

Try it on your project.

SeamSpec 0.1.0 is out. You need Python 3.11+, uv and git, a project tested with pytest or vitest, and one of the four coding agents above. The getting-started guide goes from install to a team setup with CI.

  • Package name and CLI command reserved
  • Ledger, verifier and seamspec review, with pytest and vitest runners and a git pre-commit gate
  • Claude Code plugin: hooks, MCP server, workflow commands and a read-only reviewer
  • Cursor, VS Code Copilot and Antigravity, each tried hands-on
  • BRAINDUMP scratchpad with /seamspec:drain, and a CI workflow
  • Benchmarks: capture, a long session, and a second actor
  • Public repository and first release, 0.1.0
  • Next: more runners (jest, go test, cargo)
View on PyPI View on GitHub
1 · install the CLI
uv tool install seamspec

or pipx install seamspec · requires Python 3.11+

2 · set it up in your project
seamspec init

asks before it changes anything outside your project · add --hosts cursor,vscode,antigravity for the other tools

3 · work as usual, then approve its rules
seamspec review

say what must stay true, and the agent proposes it as a rule with a test · nothing is enforced until you approve it here