This is learning material. It explains the motivation and interpretation of CRD; it does not add normative requirements. See the CRD Specification for conformance.
From fixed applications to fluid realizations
Traditional applications were often organized and documented around a known product, frontend, backend, database, and API. Agentic software makes the realization less fixed: the same capability can be performed by conventional software, an agent using tools, software calling an agent at selected steps, or software built by an agent.
Earlier: Product → Implementation → Documentation
Durable: Capability → Requirements → One or more realizationsThe implementation may change while the meaningful ability remains the same. CRD therefore asks: what can this system meaningfully accomplish, and what must remain true?
Agents expose an existing documentation problem
Agents did not create documentation fragmentation. Product intent, UX behavior, frontend components, backend functions, APIs, schemas, and operational constraints have long lived in separate artifacts. Human teams can often bridge that fragmentation through conversations and tacit knowledge. An agent expected to use, compose, modify, or build software needs the semantic context made explicit.
It needs to know the outcome, boundary, rules, defaults, examples, implementation choices, operational constraints, and unresolved questions—not merely an endpoint, screen, or function.
Make semantic authority visible
Agents and people need to know not only what a statement says, but how strongly it governs a capability. CRD distinguishes the categories below so an example or current implementation is not mistaken for a binding requirement.
| Semantic class | Meaning |
|---|---|
| Capability purpose | The general outcome the capability exists to enable. |
| Rationale / intent | Why an organization or realization chose to provide it. |
| Rule / invariant | Binding: must remain true unless the requirement changes. |
| Recommended default | Preferred behavior when no stronger guidance applies. |
| Example | Illustrative and non-binding unless explicitly promoted. |
| Implementation choice / operational constraint | Replaceable current design or a limitation of one realization. |
| Unknown / unresolved | Deliberately visible uncertainty rather than an invented answer. |
The missing middle ground
PRDs, user stories, Storybook, APIs, MCP, skills, tools, and code documentation all remain useful. Each describes part of the picture. CRD provides the technology- and implementation-agnostic capability layer that connects them.
A Capability MLE is the smallest complete, contextually meaningful ability that produces a meaningful outcome.
A Capability MLE is not simply the smallest technical fragment. If further decomposition leaves independently complete abilities, split it. If the pieces only make purpose-context sense together, keep them together.
From capability to executable behaviour
Under a Capability MLE, an Interaction Contract MLE describes the smallest contextually meaningful executable behaviour. A capability may have one or many contracts; a contract may have one or many realizations.
Actor + Command + Current State
-- subject to Policies / Invariants -->
New State + Result + Events / EffectsThe contract can be realized through a UI action, API, MCP tool, function, workflow, event consumer, or agent action without becoming tied to any one of them.
Capability is not a feature, interface, skill, or tool
| Concept | What it describes | What CRD adds |
|---|---|---|
| Feature | An informal product unit with variable boundary. | A contextual logical boundary and meaningful outcome. |
| PRD | Product or application intent. | A reusable, independently bounded ability. |
| Storybook or UI | An interface representation. | The complete purpose, policies, effects, and non-UI use. |
| API or MCP tool | A callable interface or technical operation. | The capability outcome and the contract it serves. |
| Skill | An agentic realization package or competency. | Whether it realizes one capability or bundles several. |
| Tool | An executable primitive. | The meaningful ability and boundary it supports. |
Interfaces are how a human, application, or agent accesses a capability. A realization is how that capability is currently produced. Neither is automatically the capability itself.
Capabilities give lower-level operations purpose
Capability Inventory
↓
Capability Requirements
↓
Interaction Contracts
↓
API / MCP / Tools
↓
ImplementationThis does not mean every endpoint or tool is a Capability MLE. It means lower-level operations remain traceable to meaningful abilities, so a person or agent can understand what useful outcomes the system enables before reverse-engineering its internals.
Meaning stays stable; realizations evolve
A reusable Capability Definition captures general purpose, boundaries, outcomes, interaction contracts, rules, defaults, and unknowns. An Operational Capability Realization records the current system’s implementation choices, exposures, dependencies, and constraints.
That separation lets a capability be understood, reused, composed, implemented, and evaluated without mistaking today’s implementation for the enduring requirement.
The goal
CRD does not replace existing documentation. It gives those artifacts a common semantic identity: a capability that can be understood by people and agents, exposed through APIs or MCP, realized by software or agents, composed into products, and evolved without losing its purpose.
Document capabilities as the stable semantic layer. Treat implementations as realizations of those capabilities.
As implementation becomes more fluid, meaning must remain stable.