Intent Specification Layer
Intent Specification Layer
A repository-native specification layer for AI-assisted coding.
The core rule:
docs/ explains.
spec/ governs.
The layer is bidirectional:
- before implementation, it reduces AI and human guesswork;
- after implementation, it lets reviewers find missing UX, domain, and failure behavior without reading all the code first.
Start Here
- Agent operating rules
- Agent mode router
- Agent operating protocol
- Guide
- Spec as product standard
- Method update propagation
- Spec authoring quality
- Spec review loop
- Spec-to-test bridge
- Adoption playbook
- Naming and structure decision
- Feature spec template
- Experience review template
- Change proposal template
- Spec review finding template
- Review ledger template
- Agent task brief template
- Coupon-order example
- Heading-style EARS example
- Research notes
Model
| Layer | Purpose | Required when |
|---|---|---|
| L0 Constitution | Product-wide values, authorities, forbidden shortcuts | Always |
| L1 Domain Truth | Entities, states, vocabulary, invariants, ownership | Shared concepts or 2+ modules |
| L2 Behavior Spec | EARS requirements for system response | Every behavior change |
| L3 Interface Contract | Ordering, payloads, idempotency, rollback, partial failure | Multi-step or cross-resource mutation |
Evidence
Run the local experiments:
npm run check
Generate REQ-ID statement test stubs and the verification report:
npm run req:test:generate
Current diagnostic results:
| Method | Information sufficiency | LLM-style runtime simulation |
|---|---|---|
| PRD | 0.000 | 2/15 |
| BDD/Gherkin | 0.100 | 5/15 |
| EARS only | 0.513 | 11/15 |
| Domain + EARS | 0.750 | 12/15 |
| Full Spec Layer | 1.000 | 15/15 |