v0.0.2 pre-release · Apache-2.0

SeamSpec

Build first; every seam that works gets a spec.

An open-source governance layer for AI coding agents. When you and your agent get something working, SeamSpec turns it into a small, human-approved, executable invariant, then blocks anything that breaks it.

uv tool install seamspec
How it works

Built forClaude CodeVS Code CopilotCursorany MCP client

Illustration of the planned 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.

Long agent sessions hit an entropy wall: earlier decisions quietly erode, fixes reintroduce old bugs, failed approaches get retried. SeamSpec lets the spec harden behind you, one working seam at a time.

  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 a behavior works, the agent proposes an invariant backed by a test that already passes. You approve in batches 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.

Planned workflow · previewNo 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 decision is recorded. The failed Redis attempt becomes a dead end straight away. The streak rule waits, because that code doesn't exist yet. 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

    Four keystrokes of review.

    Maya runs seamspec review, approves three proposals 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

Memory your agent can't forget.

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 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 first, then Copilot and Cursor. SeamSpec plugs into each app's own hooks: the first release targets Claude Code, and Copilot and Cursor are planned next with the same five checkpoints. Other AI tools that don't offer hooks yet are still covered by git pre-commit and CI. These gates stop accidental regressions; a deliberate bypass still needs human review of the pull request.

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.

vs spec-first

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

Tools such as Spec Kit, Kiro and OpenSpec 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

Claim your seat early.

SeamSpec is in pre-release. Today's package reserves the name and ships a placeholder CLI; the first working release is under active development.

  • 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, /seamspec:lock and /seamspec:dead-end
  • CI workflow, public repository and first release
  • Next: Cursor and Copilot, braindump scratchpad with /seamspec:drain, more runners
View on PyPI GitHub: coming soon
1 · install the CLI
uv tool install seamspec

or pipx install seamspec · requires Python 3.11+

2 · say hello 
$ seamspec
seamspec 0.0.2 (pre-release)
Executable specs for AI coding agents. Build first; every seam that works gets a spec.
Under active development: https://seamspec.github.io