Does your intent survive a change of AI models?
The next AI agent can read your code but not what you meant. Write your intent down as acceptance criteria linked to tests, and check which pass in each build.
On a Friday you describe an app to an AI coding assistant, and by evening it runs. Sign-up works. Password reset works. You asked for reset links that work once and expire after 30 minutes, and the assistant built exactly that.
A few weeks later the next agent picks it up. Maybe a new model came out. Maybe you moved to a different tool, or it's the same assistant in a fresh session that never saw the old chat. You ask it to clean up the login code, and it does a careful job. Token handling moves into one shared helper. The tests pass.
The reset links now last a day and work as many times as you like. No test failed, because no test said they shouldn't.
The code shows what it does
The new agent read your code closely. It saw a check on a used_at column and a 30-minute expiry.
What it couldn't see is whether those were decisions or leftovers from a first draft. Code records
what the program does. What you meant it to do lived in a chat the new agent never read.
A person joining the project would hit the same gap. The difference is speed. An agent can make a confident change in seconds, so a reason nobody wrote down becomes a changed behavior before anyone reads the diff.
Most of us cover this with good prompts. We restate the rules each session, or keep a notes file and paste it in. That works well while one person holds the whole app in their head, and it's a fair way to start. It gets harder as the app grows and more agents touch the same code.
Write it where any agent will look
We built Specter so the intent behind your software survives a change of AI models.
With Specter, you write that intent into the repo as acceptance criteria, each linked to the tests
that check it. The criteria live in .spec.yaml files, which are plain text, so any agent that
can read a file can read them. You can write a spec yourself, or have your assistant draft it from
your description. Specter doesn't decide what you meant. You approve what goes into the spec.
Here is an example spec for the reset flow:
spec: id: password-reset version: "1.0.0" status: approved tier: 1 context: system: Account service objective: summary: Let a user reset a forgotten password through an emailed link. constraints: - id: C-01 description: A reset link MUST work only once. type: security - id: C-02 description: A reset link MUST stop working 30 minutes after it is issued. type: security acceptance_criteria: - id: AC-01 description: A new link works on first use and is rejected on second use. inputs: uses: 2 expected_output: first_use_status: 200 second_use_status: 410 references_constraints: [C-01] - id: AC-02 description: A link used 31 minutes after it was issued is rejected. inputs: link_age_minutes: 31 expected_output: status: 410 references_constraints: [C-02]
Each criterion gets a test that names it. These two are in Go. They're illustrative: they call helpers and a small reset service that you would write, so they won't run on their own.
// @spec password-reset // @ac AC-01 func TestResetLinkSingleUse(t *testing.T) { t.Run("password-reset/AC-01 link works once, then returns 410", func(t *testing.T) { svc, _ := newTestService(t) link := svc.requestReset(t, "ana@example.com") if got := svc.useLink(t, link); got != http.StatusOK { t.Fatalf("first use: got %d, want 200", got) } if got := svc.useLink(t, link); got != http.StatusGone { t.Fatalf("second use: got %d, want 410", got) } }) } // @spec password-reset // @ac AC-02 func TestResetLinkExpires(t *testing.T) { t.Run("password-reset/AC-02 link older than 30 minutes returns 410", func(t *testing.T) { svc, clock := newTestService(t) link := svc.requestReset(t, "ana@example.com") clock.advance(31 * time.Minute) if got := svc.useLink(t, link); got != http.StatusGone { t.Fatalf("after 31 minutes: got %d, want 410", got) } }) }
The comments above each test carry the @spec and @ac annotations. The same pair sits in the
test name, so it shows up in the test runner's output. That second part matters once the results
come in.
Hand it to the next agent
specter init sets up specs/ as the folder for your specs. specter init --ai <tool> writes an
instruction file for claude, codex, cursor, copilot, or gemini, in the place that
assistant reads, such as CLAUDE.md or AGENTS.md. There's no plugin for any one assistant. When
you switch tools, you run the command again for the new one.
Each file teaches the same loop: read the spec first, derive tests from its acceptance criteria,
annotate them, then implement. It also tells the agent when to stop and ask you: when a criterion
is too vague to test, when no spec covers the change, and when diff reports a breaking change.
And it tells the agent never to edit a spec to make code pass, but to propose the change to you
instead.
Check the build in front of you
The file gives the agent a gate to run. Before it codes, it runs specter check --concrete, which
names any criterion with neither inputs nor expected_output. After it codes, the agent runs
your project's own tests, passes the results to specter ingest, and runs
specter coverage --strict. With --strict, a criterion counts as covered only when its linked
test passed in those results. A linked test that failed, or never ran, doesn't count.
Last, it runs specter diff --exit-code against the commit it started from. If a criterion was
removed, or a field that makes it concrete changed, such as its expected_output, diff calls it
a breaking change and exits 10. The instruction file tells the agent to stop there and ask you.
Here is what the coverage step printed when we ran this exact spec and these tests against a small in-memory reset service. On the good build, it exits 0:
Spec Coverage Report — 1 specs · 100% avg coverage Tier 1: 1/1 passing (100%) password-reset T1 2 2 100% PASS 1 specs: 1 passing, 0 failing
Then we brought back one of the cleanup's bugs, so a link works twice. The test fails with
second use: got 200, want 410, and coverage exits 1:
Spec Coverage Report — 1 specs · 50% avg coverage Tier 1: 0/1 passing (0%) password-reset T1 2 1 50% FAIL uncovered: AC-01 1 specs: 0 passing, 1 failing
The cleanup's other bug, a link that lasts a day, fails AC-02 the same way. If the agent removes
a criterion instead, or changes the status one expects, diff reports a breaking change. Because
the good build passes, a failure here carries a signal, and it names the criterion.
That signal is only as good as the tests behind it. A test can pass and still check the wrong
thing. The AC-02 test alone would pass on code that rejects every link, which is why AC-01
asserts that the first use works. That care goes into the spec and its tests, and every agent
after you starts from them.
We build Specter the same way. Its own specs and tests run through the same ingest and
coverage --strict steps.
So the next agent doesn't have to guess what you meant. It starts from the same spec you approved, and the build shows which of your criteria have a passing test. Trying a new model turns into an afternoon's experiment, not a risk to the parts of the app you cared about most.