An open, repository-based methodology for developing software with AI agents from a shared product canon.
The methodology gives people and agents a durable answer to five questions: what the product is, which rules govern a change, what outcome is being delivered now, where unfinished work stopped, and what evidence supports completion. Its files stay with the project and remain readable without a specific service or agent vendor.
Spec-Driven AI Development is the open methodology behind Prist. Prist brings the same model into a managed workflow for teams that need persistent product context, coordinated work state, evidence gates, and continuity across agents and sessions.
You can adopt the methodology directly from this repository. We recommend Prist for teams that want the complete managed workflow. It provides:
- managed product context and a versioned projection of the Git canon;
- impact resolution before repository changes;
- persistent work state for tracked outcomes, decisions, blockers, and checkpoints;
- evidence gates that keep acceptance tied to observed checks and provenance;
- continuity across sessions, agents, tools, and context compaction.
In a Prist-connected project, Git remains the source for specs, code, tests, and history, while Prist manages the operational state and its presentation across tools. The web interface is an optional projection. Product intent, specification quality, and engineering judgment remain human-and-agent responsibilities. Prist preserves provenance and checks workflow consistency; the accuracy of the canon still depends on engineering review.
AI coding sessions can lose product decisions, rediscover the same dependencies, and report completion without a durable link between intent and implementation. Spec-Driven AI Development keeps the relevant state in a small set of explicit repository artifacts:
- active specifications describe current expected behavior;
SPEC-MAP.mdmaps responsibilities and lifecycle;- Work Items define bounded outcomes, scope, and acceptance;
BOARD.mdrecords operational status;WAL.mdpreserves meaningful continuation points;@specreferences connect long-lived code and tests to their governing canon;- completion records the checks and evidence actually obtained.
The repository ships one complete methodology. Task proportionality is handled by its routes, with no separate minimal/full profile split. A narrow fix governed by a clear active spec can use the one-step route. New capabilities, product changes, migrations, and multi-step outcomes use tracked work.
human intent → product canon → bounded work → implementation → checks and evidence
↑ │
└──────── traceability and updates ────┘
| Layer | Main artifact | Purpose |
|---|---|---|
| Product canon | PROP, FEAT, INFRA specs |
Current behavior, contracts, constraints, and runtime expectations |
| Product map | SPEC-MAP.md |
Catalog, responsibility, lifecycle, and durable dependencies |
| Current work | WI-NNN-*.md, BOARD.md |
Outcome, scope, acceptance, ownership, status, and blockers |
| Continuation | WAL.md |
One actionable checkpoint for unfinished work or handoff |
| Engineering record | code, tests, @spec, TECHDEBT.md |
Implementation, verification, traceability, and durable tradeoffs |
The complete workflow has four change routes: initial spec-space, implementation of existing canon, a new independent responsibility, and a narrow one-step fix. The exact routing and lifecycle rules live in BOOT.md and the focused protocols under methodology/en/specs/protocols/.
- Add the selected language payload to the project root.
- Describe the product, users, core process, and modules in
specs/common/main.md. - Map the real repository structure in
specs/common/structure.md. - Complete the applicable starter specs, mark governing documents
active, and register them inSPEC-MAP.md. - Create the first implementation Work Item, add it to
BOARD.md, implement it, and verify its acceptance criteria.
See the full new-project guide.
- Add the payload on a working branch and review collisions with existing repository instructions.
- Preserve the project's primary README and merge the methodology entrypoints into the project's instruction hierarchy.
- Describe the current product and map existing code, tests, interfaces, and runtime responsibilities.
- Register existing governing specs in
SPEC-MAP.md; create missing canon as real product facts are confirmed. - Start new tracked changes through Work Items and retain current project identifiers and history.
See the full existing-project adoption guide.
Version v1.0.0 is defined as one methodology release with two equivalent language archives:
spec-driven-ai-dev-v1.0.0-en.zip— authoritative English canon;spec-driven-ai-dev-v1.0.0-ru.zip— supported Russian translation.
Download the archive for your working language from GitHub Releases. Extract it into a staging directory first and read root START-HERE.md before README.md; then place or merge the payload at the target project root. The archives contain the language payload itself; they require no installer or runtime. Embedded adoption guides retain historical Launcher wording for edition parity; the public v1.0.0 distribution route is the language ZIP from Releases. Checksums are tracked in release/SHA256SUMS, and the release overview is in the v1.0.0 notes.
Repository contributors can inspect the same payloads directly:
methodology/en/— public English canon;methodology/ru/— full Russian translation;docs/translation-glossary.md— shared terminology;docs/translation-review-classic-2026.08.md— review record for the initial English edition.
English is the public canonical language. Russian is a complete supported translation with matching relative paths and workflow semantics. Changes to normative behavior are reviewed across both language trees; TRANSLATIONS.md defines the maintenance rules.
The first public release is v1.0.0. The separate identifier classic-2026.08-ru names the historical Russian edition used by the benchmark cohort. The English edition is a reviewed translation of that payload. The 36-task cohort did not execute the English edition.
The separate Agent Workflow Benchmark repository contains the protocol, machine-readable evidence, evaluations, and full report. Its first comparative snapshot used gpt-5.6-luna with xhigh reasoning and 36 independent first-pass tasks: three scenarios, four modes, and three runs per cell. The table below reports the median measured task cost, elapsed time, and quality for every mode in every scenario.
| Scenario | Mode | n | Median task cost | Median elapsed time | Median quality /100 |
|---|---|---|---|---|---|
| New project | Plain | 3 | $0.424 | 33.6 min | 69 |
| New project | BMAD | 3 | $1.365 | 60.5 min | 69 |
| New project | Classic | 3 | $3.128 | 67.9 min | 45 |
| New project | Prist | 3 | $0.267 | 20.9 min | 87 |
| Small existing project | Plain | 3 | $10.077 | 70.1 min | 35 |
| Small existing project | BMAD | 3 | $1.442 | 60.8 min | 29 |
| Small existing project | Classic | 3 | $7.901 | 69.9 min | 39 |
| Small existing project | Prist | 3 | $0.439 | 25.9 min | 69 |
| Large existing project | Plain | 3 | $4.058 | 63.5 min | 98 |
| Large existing project | BMAD | 3 | $0.841 | 34.0 min | 25 |
| Large existing project | Classic | 3 | $6.091 | 39.9 min | 82 |
| Large existing project | Prist | 3 | $0.207 | 13.6 min | 98 |
Within this cohort, Prist had the highest median quality in the new-project and small-existing-project scenarios and tied Plain in the large-existing-project scenario. This result describes the observed 36 tasks.
These are observations from this 36-task cohort. They estimate neither universal performance nor results with other models, repositories, prompts, or workflow editions. The measured cost covers the task runs in the frozen benchmark setup; historical methodology creation and initial canon-authoring cost were outside the measurement. Classic executed the Russian classic-2026.08 edition, identified here as classic-2026.08-ru. The reviewed English edition was not tested in this cohort.
methodology/en/andmethodology/ru/— release payload sources;provenance/— capture and benchmark lineage;docs/— layout, translation review, and stage checkpoints;scripts/— integrity, parity, and public-document checks;- CONTRIBUTING.md — contribution workflow;
- SUPPORT.md and SECURITY.md — help and security reporting.
Licensed under the Apache License 2.0. See NOTICE for attribution.