LiveSpec is an open file format for product specifications. Plain markdown, organized by convention, versioned in git. It captures what a product is, why it exists, and how it should behave, in a form that people, agents, and tools can all maintain together.
Draft v0.1.0 · Open for review
Word docs, Notion pages, tickets: each of them assumes a spec is written once and then left behind. The code moves on; the document does not. For years that was a tolerable cost. In an agent-first workflow it stops being one.
Coding agents are exceptional at completing patterns and poor at reading minds. Every session that starts without durable context spends its first minutes rebuilding what the last one already knew. Intent has to live somewhere both people and machines can find it, in a form that travels from one session, one tool, one teammate to the next.
LiveSpec starts from the opposite premise to the documents it replaces: a spec should be maintained continuously, by humans and agents working on the same files.
A LiveSpec project is a folder of markdown files. Four directories hold everything: what the product is for, how it looks and behaves, how it is built, and the features that tie them together.
my-product/ ├── livespec.yaml ├── product/ personas, goals, principles, the domain ├── ux/ components, patterns, design principles ├── tech/ standards, architecture decisions, systems └── features/ what the product actually does
Every concept has a known shape. A persona, a constraint, a requirement, an architecture decision: each reads the same way in any project. Enough structure for a tool or an agent to parse without ceremony, little enough that a person can write it in any editor and read it on GitHub.
# Full-text Search As a power user, I want to search across all my documents so that I can find content without remembering where I put it. ## Requirements - [ ] REQ-1: Search bar visible in main navigation - [ ] AC-1.1: Search input renders in header on all pages - [ ] REQ-2: Results returned within 300ms
A complete, valid feature. That is the whole format.
A spec is only worth trusting if you can tell when it has drifted. LiveSpec keeps the two sides linked with a single marker, dropped in an ordinary code comment:
// livespec: full-text-search#REQ-3
Spec and code are written independently and stay that way. The marker is the thread between them: it shows which requirement a piece of code answers to, and turns drift into something you catch in a diff and a review, rather than discover months later.
It sits deliberately between two extremes. A spec you write once and abandon loses its value the moment coding begins. A spec the code is generated from trades one kind of rigidity for another. LiveSpec keeps the spec as a living reference, maintained alongside code that people and agents still write by hand.
Plain text files. No proprietary editor, no database, no vendor between you and your spec.
YAML for metadata, conventional sections for the body, checkboxes for what is tracked. Strict enough to parse, loose enough to write by hand.
Specs live in the repo, evolve through pull requests, and get reviewed like code.
Compact layout, slug-based links, predictable structure: built for a model to read efficiently and a person to follow.
A small set of universal types; everything else through a documented extension, never a new folder.
Teams building software with AI coding agents, where the quality of the spec sets a ceiling on the quality of the generated code. And anyone who has ever wanted one honest answer to a simple question: what does this product actually do, and why?
Status. LiveSpec is an early draft, version 0.1.0. The format is not yet stable: types, sections, and rules can still change before a stable 1.0. It is shared now for reading, criticism, and proposals to simplify it. The full specification, a cheatsheet, JSON schemas, and a worked example live in the repository.