DurableSpec
One shared spec for your team and every AI it works with.
A free, open-source spec that gives every engineer and every AI session the same context, draws and
maintains your C4 architecture diagrams, and builds a lasting product specification, in plain Markdown
next to your code.
- Shared context across people and AI sessions. What one person's session works out, every later
session knows, whoever runs it. Nobody re-explains the system.
- Architecture diagrams that maintain themselves. C4 Context and Container diagrams in Mermaid,
drawn from your code and redrawn in the commit that changes them.
- A product spec that lasts. Purpose, customers, business rules and the decisions behind the
design: the context that isn't in the code, in plain language product owners can read and write.
- Drift gets caught. Each document names the code it describes, so a stale document is flagged.
- Free and simple. Plain Markdown, two Agent Skills and one Python script. Works with Claude Code,
Codex, Copilot, Cursor and Gemini CLI.
Try it on any repository (you need git and Python 3.8+), then ask your agent to "create the spec":
git clone https://github.com/pikelabs-ai/durablespec.git
python3 durablespec/install.py /path/to/your/repo
Status: beta. The practice is in daily use across nine repositories; the packaging is new. Every
release is tagged.
More at pikelabs.ai/durablespec.
Why
Every AI session starts from zero. You spend the first part of it re-explaining the system, the
customer, and what was decided last week, and when the session ends, what you worked out together
goes with it. With several people each running their own sessions, the loss multiplies: nobody's
agent knows what anyone else's agent learned.
DurableSpec fixes that with a small folder of plain-Markdown documents, doc/spec/, kept next to the
code. It records what the system is for, how it is shaped, and why it was built that way. Every
session, human or AI, starts by reading it, and the work that matters gets written back before the
session ends. The knowledge carries forward from one session to the next, and from one person to
the next.
Continuity beyond the session is the main point.
- Working alone, a new session starts at full speed. The agent reads a few pages instead of
re-deriving the system from the code, so it uses little of its context window getting oriented
and has more left for the actual work. What you decide today is waiting for tomorrow's session.
- Working as a team, the spec carries everyone's relevant work. When a colleague's session
settled a design question yesterday, your session knows the answer today, without anyone
writing a hand-off note or remembering to mention it.
Not just for engineers
Some of the most valuable content in a spec is business context: who the customers are, what
problem the system solves for them, what a term means in this business, which constraints come
from contracts or regulation. Engineers often don't have that knowledge. Product owners and
business people do.
DurableSpec is written in plain language so they can read it and write in it, especially the
purpose/ section, which is where that context lives. This matters more every year: a growing
share of the people building software with coding agents are business people, not career
engineers. The spec is how their knowledge reaches every session, including the ones they never
see.
How a session goes
This is the habit that makes it work. It is not obvious, so here it is step by step.
1. Start with the problem, and have the agent read the spec first. For example:
Today we're going to extend billing so it can handle Acme's invoices in euros and pounds.
Before we start, read doc/spec, and also the storefront repo's doc/spec to see how the
storefront uses billing. Then let's brainstorm. I was thinking we could store each amount in its
original currency and convert only when reporting. Will that work, and what else would it
affect?
The problem can be deeply technical or purely about the business, such as growing a system to
meet a new customer's needs. Either way, the agent starts from the recorded purpose, design and
past decisions, not from guesses. It reads the index and the few documents that matter, not the
whole codebase.
2. Brainstorm. Talk it through. Let the agent push back, raise consequences you hadn't
considered, and suggest alternatives. This is where the real thinking happens, and it goes better
when the agent knows why the system is the way it is.
3. Update the spec. Once you've settled on an approach, ask the agent to record it: a new
decision record for the choice and why, and changes to the design documents it affects. Do this
before building, while the reasons are fresh.
4. Build it. Now the agent builds, with the agreed design written down in front of it.
5. Check the spec before you commit. Ask the agent to update the spec (the durablespec-update skill). Usually
nothing more needs to change. Sometimes building taught you something the spec should know.
The next session, yours or a teammate's, starts at step 1 with everything this one learned.
Getting started
You need git and Python 3.8 or later; nothing else is installed. Clone this repo once, then run the
installer against any repository:
git clone https://github.com/pikelabs-ai/durablespec.git
python3 durablespec/install.py /path/to/your/repo
It adds two Agent Skills, durablespec-create and durablespec-update, in
.agents/skills/ (read by Codex, Gemini CLI, GitHub Copilot and others) with links in .claude/skills/
for Claude Code. It also adds doc/spec/durablespec.py (the mechanical checks), the rules in
doc/spec/README.md if you have none, a marked section in AGENTS.md, and an @AGENTS.md line in
CLAUDE.md. It never touches anything else, and running it again upgrades in place. Add --dry-run to see what
it would do first.
main is the latest code; to install a specific release, add --branch and a release tag
to the clone (for example --branch v0.5.0). Later, upgrade from inside your repo with python3 doc/spec/durablespec.py upgrade
(Upgrading).
Commit what it adds. On Windows, Git may check out the .claude/skills/ links as plain text files;
running the installer again on that machine replaces them with copies.
Then ask your agent to create the spec. It works like a session in the previous section: a
conversation, not a form.
- Existing code, no spec. The agent reads the code and drafts the overview, the architecture,
and the decisions it can see evidence for. Then it asks you what the code can't tell it: who the
system is for, why the odd parts are odd, which decisions were deliberate. You correct the draft
together. Bring a product owner for the purpose section if you can.
- New project. Start with the problem and brainstorm as above. As the design firms up, the
agent records the purpose, the architecture and each decision as it is made.
- A design already written elsewhere. Point the agent at it. It turns the design into the
overview, architecture and decision records, so the design stays current once code lands
instead of becoming a document nobody reopens.
The shape
doc/spec/
README.md the rules for this repo (the one rule, what goes where)
INDEX.md generated map: one line per document, read this first
RELATED.md optional: specs in other repos this one depends on
backlog.md known work you owe but haven't scheduled (changes freely)
purpose/ why the system exists: overview, customers, glossary
constitution/ how we build here: conventions, tech stack, standing rules
design/ what we're building: architecture, one doc per area, status
adr/ why this over that: numbered decision records, never edited
Everything else in doc/ stays free-form. The rules apply only inside doc/spec/.
Each document starts with a few lines saying what it is for. The index is built from them, so an
agent can find the right document without opening every one:
---
purpose: "How invoices are created, priced and sent; currency handling."
concepts: [invoice, pricing, currency, tax]
owns: [src/billing/invoice/, src/billing/currency/]
---
# Invoicing
A few conventions carry most of the weight:
- Each design document names the code it governs (
owns:), so a changed file can be traced to
the document that describes it, and a document pointing at deleted code gets caught.
- Build status lives in one place,
design/status.md. Status notes scattered through design
documents are the first thing to go stale.
- Diagrams follow the C4 model, drawn in Mermaid (see Architecture that stays true).
- Decision records are never edited. To change a decision, write a new record that replaces
the old one. When you cite a record from another repo, name the repo:
billing ADR-0004, never
a bare number.
Architecture that stays true
The spec draws your system with the C4 model: a System Context diagram in the
overview (who uses it, what it talks to), a Container diagram in the architecture (the running parts and
how they connect), and Component diagrams for areas complex enough to need one. They are Mermaid, so
GitHub shows them as pictures and they live as plain text beside the code:
flowchart LR
clerk(["👤<br/><b>Billing clerk</b><br/>[Person]<br/>Issues and corrects invoices"])
subgraph billing["Billing (this system)"]
app["<b>Web app</b><br/>[Container: React]<br/>Invoice screens"]
api["<b>API</b><br/>[Container: Java]<br/>Prices and sends invoices"]
db[("<b>Database</b><br/>[Container: PostgreSQL]<br/>Amounts in original currency")]
end
bank["<b>Bank</b><br/>[External system]<br/>Daily exchange rates"]
clerk -- "uses" --> app
app -- "JSON over HTTPS" --> api
api -- "reads and writes" --> db
api -- "fetches rates" --> bank
The agent draws them when it creates the spec. On every change, it checks whether an app, service,
database, user or outside system was added, removed or reconnected, even when the change only touched a
compose or Terraform file, and if so redraws the picture in the same commit. This repo's own
architecture is a worked example.
The one rule
Touch the spec only if a reader tomorrow would form a materially different picture of the
system without the change.
The default is no. Bug fixes, refactors, renames, new tests and dependency updates almost never
qualify. New components, new connections between parts, reversed decisions, new customers'
requirements and new conventions usually do. The rule is as much about when not to write as when
to, and it is what keeps the spec short enough to read at the start of every session.
What it is not
DurableSpec does not tell an AI how to plan, think, or break down work. Some spec tools walk the model
through a fixed sequence (specify, plan, task, implement). That kind of scaffolding gets in the
way as models improve.
DurableSpec manages what the team knows, not how the work gets done. Better models make that
more valuable, not less: no model, however capable, can recover a decision that was never written
down. And the better models get at writing, the more a project needs a rule about when not to
write.
The test for every feature in this project: would it still be useful if models were ten times
smarter?
Day to day
Agents read before they decide. The section the installer adds to AGENTS.md tells every agent
to check the spec before settling any design question, and to answer from it rather than re-derive
it. Agents still forget mid-session; when one starts guessing, point it back at the spec.
Agents write before you commit. Ask the agent to update the spec. The durablespec-update skill
reads the change and the conversation behind it, applies the one rule, and either edits the one or
two documents that should move or tells you nothing needs to change. "Nothing needs to change" is the
common, correct answer. Put [skip-spec] in the commit message to record that.
The mechanical checks need no AI. doc/spec/durablespec.py checks that every document has its
opening lines, INDEX.md is current, every owns: path still exists, every diagram is listed at the
top of architecture.md, no two decision records share a number, and nothing looks like a secret. Run
it locally, in a git hook, or in CI.
python3 doc/spec/durablespec.py index # rebuild INDEX.md
python3 doc/spec/durablespec.py check # exit 1 on any problem
Teams and branches
Because the spec is plain files in the repo, it branches and merges with the code. When two branches
both changed it, merge as usual, then run check: it catches clashing decision-record numbers and a
stale index. Where the two branches made opposing decisions, don't pick a winner in the merge; put
the conflict in front of the people who made them. A skill to help with this is planned.
Large repos
A monorepo gets one spec, at the root, like any other repo. Each part is an area in design/,
and its owns: line names the part's folders, so a change anywhere still traces to the document
that describes it. Decision records share one sequence. Monorepos differ too much for a fixed
recipe: one holding several complex, high-throughput modules is a different thing from one that is
a plain REST application split into folders. Start with one spec for both; if a part later earns
its own, record that as a decision.
Alongside other spec tools
Per-change spec tools (GitHub Spec Kit, OpenSpec, Kiro, or a team's own story specs) plan and record
individual changes. DurableSpec holds the standing picture those changes add up to. They don't
overlap; keep both. The spec always lives at doc/spec/, even in a repo that already has a docs/
folder, so every tool and agent finds it in the same place.
Works with any agent
The rules are written for any reader, not for one product. The skills follow the open
Agent Skills format, and the standing instruction lives in AGENTS.md,
which most coding agents read; Claude Code reads it through the @AGENTS.md line in CLAUDE.md.
Nothing is written twice.
Upgrading, and stopping
From the repo you want to upgrade (repos on 0.3.2 or later; for older ones, run the installer once from a
fresh clone):
python3 doc/spec/durablespec.py upgrade # add --dry-run to see what it would change
It finds the newest release with git, fetches it, checks that the release is signed by a DurableSpec
release key, and only then runs its installer against your repo, printing anything new that it can't
apply by itself. python3 doc/spec/durablespec.py version shows which
version a repo has. Running the installer from a fresh clone of this repo does the same thing.
To stop using DurableSpec, delete doc/spec/, the two skills, and the marked section of
AGENTS.md. Nothing else depends on it.
Security
DurableSpec is plain files that agents read before they act, so it is built to be safe to put in front
of them:
- No dependencies, no telemetry, no network except an upgrade you run, and that runs only releases
signed by a DurableSpec release key.
- The spec is knowledge, not commands. It shapes how an agent does what you asked; it can't give it
a new task or widen what it may do. Anything in the spec, or in code and docs the skills read, that
tries to is reported to you instead.
- Secrets stay out. The skills never open or quote them, and
check fails on anything shaped like a
key or token. It also notes hidden comments, encoded blobs, private IP addresses and cloud account
ids; check --strict fails on those for CI.
- The installer writes only its own files, and refuses to follow links out of your repo.
See SECURITY.md to report a problem.
Status
Beta. The practice has been in daily use since spring 2026 across nine repositories, from a
coding-agent harness to a production data service, with specs written before the code, alongside
it, and after it. The tooling around it is new.
More at pikelabs.ai/durablespec.
License
Apache License 2.0. Copyright 2026 Pike Labs, Inc.
