A methodology for building software with AI agents where the source of truth is the feature's promises, not the task spec.
Status: working draft v0.1. Terms and regulations are still settling. The working draft is now English-first; a Russian translation is kept for readers.
Documentation in Russian: README.ru.md, docs/ru/.
Code is the execution of intent. Intent doesn't live in tasks — it lives one level up, in the feature, written down as a set of promises: what the consumer can do in this aspect of the product. A task builds a tool and wires it into a specific promise.
A task is verified not only against its own acceptance criteria, but against all promises of the feature — including the ones it never touched. This flips the direction of verification:
| spec-driven | promise-driven | |
|---|---|---|
| unit of truth | the task spec, closed on itself | the feature's set of promises |
| verification looks | down, at its own task's acceptance | up, at all promises of the feature |
| structurally catches | "code doesn't match the spec" | "the task quietly betrayed a neighboring promise" |
An AI agent closes a task flawlessly by the task's own criteria — and silently breaks a neighboring capability of the feature that nobody asked it to touch. The task's tests are green, the diff review is clean, the defect is found by the consumer. The task spec cannot catch this class by construction: the betrayed promise isn't written in it. Promise-driven catches it by design — every task closure includes a pass over all promises of the feature.
Constitution what is untouchable: the project's values and priorities
↓
Feature spec the set of promises: consumption scenarios, no tools
↓
Task spec the implementation contract: narrow bounds for the agent's work
↓
Regulations how the agent and the author interact; rules of tone
Details — docs/core.md.
A pass over the promises when a task closes. Run not by the implementation's author but by a fresh judge; kept as a ledger, one promise at a time; a verdict without evidence is void; the honesty of the pass is measured periodically by planting a deliberate betrayal. Regulations — docs/uphold-pass.md.
A promise's number is an identifier, not a position in a list: the code points at it with a // PROMISE F003-P2 marker at the place that fulfils it. So the ## Promises section is mandatory, IDs are never renumbered or reused, and a withdrawn promise is retired on the record in HISTORY.md rather than deleted — an orphaned marker is a code defect. This gives the court a machine-findable locus and makes half of an UNTOUCHED verdict checkable: the marked files are what the diff must be shown to have stayed clear of. check-promises.sh enforces it; what it cannot see — whether every carrying place got marked — stays the job of calibration. Details — docs/workflow.md.
A promise is written as a consumption scenario (Cockburn's sea level), comes with "the one where …" examples, and is checked through falsifiability: a promise has an expectation holder, a witness scenario, and a conceivable mutation that would betray it. Rules and degeneration tests — docs/granularity.md.
The methodology grew out of our own practice; the neighboring axes it defines itself against:
- Goal levels (Cockburn) and Example Mapping (Wynne): granularity and witness examples.
- The feature interaction problem (telecom, 1990s): independently-correct features breaking each other — the closest studied relative of the target defect class.
- The frame problem (McCarthy, Hayes): how to know an action didn't touch everything else.
- Design by Contract (Meyer): invariants — here lifted from the class level to the feature level.
Annotated list — docs/references.md.
The methodology is distilled from practice: an Android VPN client written entirely by AI agents (hundreds of tasks, years of maintenance), where the author writes specs, invariants, and acceptance, the agents write the code, and CI catches regressions. The documents in this repository extract that practice into a reusable form.
In the target repository:
/path/to/promise-driven-development/install.sh . "ru en" # languages of the corpus; default enThis lays down the SPECS/ corpus (the author fills in the constitution and the regulations; .pdd.conf records the chosen languages), a copy of the framework in .pdd/, and the Claude Code slash commands: /feature → /task → implementation → /uphold (a fresh scripted judge on a fixed prompt) → /close; periodically — /calibrate and /audit (the second court: the engineering judge weighs ARCHITECTURE.md against the promises, the constitution, and the neighboring features). Adopting on an existing codebase: /inspect surveys the project and drafts its features, /backfill distills a single one. The full cycle — docs/workflow.md; a filled-in end-to-end example — examples/.
| Path | Contents |
|---|---|
| docs/core.md | Terms, the four layers, principles |
| docs/workflow.md | Lifecycle: corpus structure, statuses, the cycle, enforcement |
| docs/conception.md | How a feature is thought up: four stages, four views, the four fates of an idea |
| docs/uphold-pass.md | Regulations for an honest pass over the promises |
| docs/granularity.md | Promise sizing rules, degeneration tests |
| docs/references.md | Key works, annotated |
| docs/ru/ | Russian translation of the docs |
| templates/ | Templates: constitution, regulations, feature, task, plan, both ledgers (court and conception), report, history |
| prompts/ | The two judges' fixed prompts (consumer judge, engineering judge) — single sources, passed verbatim |
| lang/ | Language packs: markers, verdict vocabulary, labels — tokens as data |
| commands/ | Claude Code slash commands: /feature /task /uphold /close /calibrate /backfill /inspect /audit |
| scripts/ | Housekeeping: create a feature/task, build the judges' briefs, run the scripted judges, machine-check the ledger and the feature's promise markers, generate the corpus map with its verification queue |
| examples/ | End-to-end example: a feature, a task, a filled-in ledger with a caught betrayal |
| install.sh | Installs the kit into a target project (SPECS/ + .pdd/ + .claude/commands/) |