---
title: The spec is where a signal becomes shared context
date: 2026-09-29
summary: one template per kind of work, acceptance criteria that say how they are proven, and front matter a pipeline can route on; free to install
---
My company helps teams shorten the path "entre un besoin client et le
logiciel en production", between a customer need and software in
production.[^1] In the model we describe, agents do the work and people set
the priorities.[^1] The pipeline I am building for my own repositories runs
each piece of work through several agents in turn. One writes the spec. A
second, on another model, reviews it. A third builds it. Specialist reviewers
read the PR, and a QA agent tests the result on a preview. None of them was
in the room when the issue was raised. The only thing they all read is the
spec.

So the spec is not paperwork before the real work. It is the moment a signal
(a customer request, a bug report, an error in the logs) becomes context that
people and agents share. The thesis behind our company says routing
information is now a solved problem for machines.[^2] That holds only if the
information has a shape a machine can route on. A spec is that shape, for
one piece of work.

## Why a prompt is not enough

GitHub's argument for spec-driven development is that agents fail on vague
intent, not on code: they are "exceptional at pattern completion, but not at
mind reading."[^3] In their words, "specs become the shared source of
truth."[^3] Anthropic's advice for Claude Code points the same way: the agent
"stops when the work looks done", so give it "something that produces a pass
or fail".[^4]

None of this is new. Dan North wrote in 2006 that "a story's behaviour is
simply its acceptance criteria", written as Given, When, Then.[^5] The format
was meant to be loose enough for analysts and "structured enough" to
automate.[^5] Martin Fowler notes that it works with any kind of test.[^6]
Twenty years later the readers have changed: business and developers have
become people and agents.

## What I needed that the existing kits don't cover

GitHub's Spec Kit and Kiro both structure specs for agents already. Spec Kit
has user stories with Given/When/Then scenarios and an optional bug-fixing
flow.[^7] Kiro writes requirements as `WHEN … THE SYSTEM SHALL …`, and its
bug specs say what must keep working as well as what is broken.[^8] I borrowed
that last idea directly. Both then take the spec on to a plan, tasks and
code.[^7][^8] I needed something else: a spec that a pipeline of agents can
act on without asking anyone. Four things were missing.

**One template per way work arrives.** Work does not only arrive as
features. My kit has five templates:

| Template | Use it for |
|---|---|
| `feature` | a capability that does not exist yet |
| `bug` | behaviour that differs from what was intended |
| `improvement` | behaviour that works but should be faster, clearer or cheaper |
| `error` | an error from logs or monitoring, before anyone knows what it is |
| `chore` | refactors, upgrades and tech debt, with no visible change |

The `error` template starts with a triage decision, because many errors are
not code bugs: a provider is down, credits ran out, or the error is noise.
Only two of the five decisions send the work to a developer agent.

**Front matter the pipeline routes on.** Every spec says which parts of the
system it touches, which risks it carries (a migration, auth, billing,
messages sent on a user's behalf, anything a user will notice), how QA tests
it, and its size. The reviewers who run, whether QA opens a browser and
whether a human must approve the release all follow from those few lines.

```yaml
---
type: bug
title: Daily recaps reach every product even when one is too large
source: github:acme/app#42
surfaces: [backend]
risk: [client-facing]
qa: none
size: s
---
```

**Acceptance criteria that say how they are proven.** Each criterion is one
line, and it names who proves it and when:

```markdown
- [ ] **AC-1** Given one product over the read budget, when the daily recap runs, then every other product still gets its recap. _verify: test_
- [ ] **AC-2** Given the fix is live for seven days, when the error is queried, then it has no new occurrence. _verify: logs_
```

`test` is proven in CI, `api` and `browser` by QA on a preview, and `logs` in
production after release. These are acceptance criteria, not a definition of
done. In Scrum, the definition of done is one quality bar for everything the
team ships.[^9] That bar belongs in the repository's config, not in each spec.

**A checker that is code.** As far as I could see in its repository, Spec
Kit asks the agent to check the spec against a checklist.[^7] My checker is
one TypeScript file with no dependencies. It refuses:
- a spec with an empty section;
- a bug without a regression test;
- a browser check when QA is not set to use one;
- an approved spec with an open blocking question.

It cannot tell whether the spec is right. That is the job of a second
agent, which rates the spec against a written checklist. In the pipeline I am
building, the writer and the reviewer get up to three rounds to agree before
a person steps in.

## What writing five specs taught me

To test the templates, I rewrote five pieces of already-merged work from my
own product repositories as specs. Three problems came up that were in none
of the original issues:
- a log line carrying a user's email address in clear;
- an alert firing on a case the code already handled correctly;
- a UI change merged without anyone opening it in a browser.

The template did not find them. It asked questions (what does this log
contain, is this a crash or an expected condition, how is this proven) that
nobody had asked while the work was being done.

## Install it

The kit is two [Agent Skills](https://agentskills.io): `write-spec` turns an
issue into a spec from the right template, and `review-spec` rates one
against the checklist. Both Claude Code and Codex follow the Agent Skills
standard.[^10][^11] The skills are published on this site under
`/.well-known/agent-skills/`, the discovery path proposed in Cloudflare's
RFC.[^12]

The quickest way is Vercel's `skills` CLI. It reads that path, checks each
archive's digest, and installs into Claude Code, Codex and other agents. It
needs Node 22.20 or later.[^13]

```sh
npx skills add https://code.benoitguivarch.fr
# or, without questions, for every project:
npx skills add https://code.benoitguivarch.fr --skill write-spec --skill review-spec -a claude-code -a codex -g -y
```

To install by hand, download the archives listed in
`/.well-known/agent-skills/index.json` and check their `sha256` digest. Then
unpack each one into a folder named after the skill:
- Claude Code reads `~/.claude/skills/` for every project, or
  `.claude/skills/` for one repository.[^10]
- Codex reads `~/.agents/skills/`, or `.agents/skills/` in the
  repository.[^11]

Then ask your agent to write a spec for an issue. Skills load only when the
task calls for them.[^14] The checker is a script, and the RFC says agents
must not run a skill's scripts by default, so expect yours to ask before it
does.[^12] Read a skill before you install it, as Anthropic recommends for
any skill.[^14] `npx skills add https://code.benoitguivarch.fr --list` shows
both without installing anything. They are markdown and one TypeScript file,
under the MIT license.

[^1]: The Worldmodel Company, home page (French), theworldmodelcompany.com, 2026. https://www.theworldmodelcompany.com/fr/
[^2]: The Worldmodel Company, "La thèse", theworldmodelcompany.com, 2026. https://www.theworldmodelcompany.com/fr/thesis
[^3]: Den Delimarsky, "Spec-driven development with AI: Get started with a new open source toolkit", The GitHub Blog, 2025-09-02. https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/
[^4]: Anthropic, "Best practices for Claude Code", Claude Code Docs, accessed 2026-09-29. https://code.claude.com/docs/en/best-practices
[^5]: Dan North, "Introducing BDD", dannorth.net (first in Better Software, March 2006), 2006-09-20. https://dannorth.net/blog/introducing-bdd/
[^6]: Martin Fowler, "GivenWhenThen", martinfowler.com, 2013-08-21. https://martinfowler.com/bliki/GivenWhenThen.html
[^7]: GitHub, "Spec Kit", github.com, v1.0.13, read 2026-09-29. https://github.com/github/spec-kit
[^8]: Kiro, "Specs" (overview, Feature Specs, Bugfix Specs), kiro.dev, 2026-08-27. https://kiro.dev/docs/specs/
[^9]: Ken Schwaber and Jeff Sutherland, "The 2020 Scrum Guide", scrumguides.org, 2020-11. https://scrumguides.org/scrum-guide.html
[^10]: Anthropic, "Extend Claude with skills", Claude Code Docs, accessed 2026-09-29. https://code.claude.com/docs/en/skills
[^11]: OpenAI, "Build skills", OpenAI Developers, accessed 2026-09-29. https://learn.chatgpt.com/docs/build-skills
[^12]: Cloudflare, "Agent Skills Discovery via Well-Known URIs" (RFC draft v0.2.0), github.com, 2026-03-12. https://github.com/cloudflare/agent-skills-discovery-rfc
[^13]: Vercel Labs, "skills", github.com, 2026-09-28. https://github.com/vercel-labs/skills
[^14]: Barry Zhang, Keith Lazuka and Mahesh Murag, "Equipping agents for the real world with Agent Skills", Anthropic Engineering, 2025-10-16. https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
