Intention-Driven Design
Making meaning explicit, executable, and continuously verified — so systems can scale without semantic drift.
Intention-Driven Design (IDD) is a methodology for building software where every artifact traces back to a declared human intent. Code is a downstream consequence of intent, never the starting point. We allow change, but we do not allow drift.
Why IDD exists
Agentic coding tools are remarkably capable at execution but have a subtle failure mode: they optimize locally without a global ground truth. They can write perfect code for the wrong thing. Spec-driven development moved the answer earlier in the process, but still asks "what should the system do?" — IDD asks "why should the system exist at all?" and makes that why a first-class, traceable artifact.
The result is a framework where AI agents can autonomously implement, verify, and evolve software while humans focus on meaning, tradeoffs, and creative decisions.
IDD can also be extended through explicit agent roles: bounded execution
contracts that let multiple agents develop the methodology or a target system in
parallel without breaking traceability.
How it works
┌──────────────────────────────────────────────────────────────┐
│ NARRATIVE LAYER │
│ Personas ──▶ Journeys ──▶ Stories │
│ (who/why) (experience) (what) │
│ /solution-narrative │
├──────────────────────────────────────────────────────────────┤
│ MODEL LAYER │
│ Domain Models │
│ (concepts, rules, lifecycles) │
│ /domain-modeling │
├─────────────────────────────────────────────────────────────┤
│ CONTRACT LAYER │
│ Features ◀── Contracts ──▶ Fixtures │
│ (Gherkin) (OpenAPI / AsyncAPI / JSON-RPC) │
│ /behavior-contract │
├──────────────────────────────────────────────────────────────┤
│ IMPLEMENTATION LAYER │
│ Backend ◀──────────────────────▶ Frontend │
│ (any stack) (any stack) │
│ │
├──────────────────────────────────────────────────────────────┤
│ VALIDATION LAYER │
│ Unit Tests ── Integration ── E2E Journey Tests │
│ (domain) (contract) (experience) │
│ /e2e-journey-testing │
├─────────────────────────────────────────────────────────────┤
│ CERTIFICATION LAYER │
│ Evidence tied to intent ── published before merge │
│ │
└──────────────────────────────────────────────────────────────┘
Every downstream artifact references its upstream source:
Persona → Journey → Story → Feature → Contract → Tests → Evidence
No link in the chain is optional.
Quick example: from intent to evidence
A stakeholder says: "Someone at a trade show should be able to sign up and start an audit on their phone while we're talking to them."
IDD breaks this into a traceable chain:
| Layer | Artifact | What it captures |
|---|
| Narrative | specs/personas/trade-show-prospect.md | Who: mobile, distracted, skeptical |
| Narrative | specs/journeys/trade-show-signup.md | Experience: QR scan → signup → first audit |
| Narrative | specs/stories/onboarding/mobile-signup.md | Capability: quick mobile account creation |
| Model | specs/models/audit/audit.model.yaml | Concept: Audit entity, states, rules |
| Contract | specs/features/onboarding/mobile-signup.feature | Behavior: Gherkin scenarios |
| Contract | specs/contracts/openapi/api.yaml | HTTP boundary: POST /accounts, POST /audits |
| Contract | specs/contracts/asyncapi/audit-events.yaml | Event boundary: publish audits/created |
| Contract | specs/contracts/json-rpc/account-service.yaml | RPC boundary: account.getQuickStartPrompt |
| Contract | specs/fixtures/onboarding/mobile-signup.json | Test data: request/response pairs |
| Implementation | Backend + Frontend code | Derived from contracts |
| Validation | frontend/e2e/journeys/trade-show-signup.spec.ts | E2E test following the journey |
| Certification | certification/trade-show-signup/ | Automated evidence tied to intent |
Every artifact in the chain references the one above it. An agent — or a human — can trace any line of code back to the persona goal that motivated it.
