Ability-Anchored Spec-Driven Development
A methodology for building software from language-agnostic specifications structured around abilities — discrete, composable units of behavior with defined contracts. The specification is the single source of truth. Implementation follows.
Version: v1
Documents
| Document | Contents |
|---|---|
| METHODOLOGY.md | What AASDD is, how specs are structured, authoring rules, and versioning |
| CONVENTIONS.md | Naming conventions, file naming, formatting rules, and canonical file templates |
| IMPLEMENTATION.md | Translating specs to code: ordering, testing, development cycle, and agent instructions |
Examples
| Example | Description |
|---|---|
| examples/link-checker/ | Simple spec: one root ability, HTTP transport decision, sub-ability decomposition |
| examples/content-moderation/ | Spec with a state machine, multiple abilities, and a gRPC interaction channel decision |
Tooling
| Tool | Description |
|---|---|
| aasdd-cli | CLI for working with AASDD specs: validate spec directories against conventions, parse specs to/from a JSON representation, scaffold empty or example spec directories, and list supported AASDD versions |
Wiki
The wiki has practical guidance, tips, and best practices for using AASDD:
- Why “Abilities” — Why this term instead of component, service, or module
- What AASDD Is Not — Common misconceptions and boundaries
- Using Agents — Spec authoring vs. spec-driven implementation
- Authoring Specs with Agents — Why one-pass generation fails and how to work iteratively
- Iterative Decomposition — Worked example of decomposing abilities from rough idea to leaf specs
- From Spec to Implementation — How a completed spec translates to working code
- Recovering from Spec Drift — How to detect and fix divergence between spec and implementation
- Spec Coverage — Drift, unimplemented constructs, and how to measure both
- Custom Sections — Author-defined sections for figures, notes, and references
- Structured Representations — JSON and YAML equivalents of a markdown spec