~/code.benoitguivarch.fr / posts/2026-09-29-the-spec-is-where-a-signal-becomes-shared-context.md

The spec is where a signal becomes shared context

2026-09-29 · 1400 words

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.78 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.

---
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:

- [ ] **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: 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.1011 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

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 ↩↩