1. Purpose
Capability Documentation is the implementation- and technology-agnostic framework through which humans, agents, applications, and developers can understand, use, build, compose, and operate capabilities.
Its canonical artifact is a Capability Requirements Document (CRD): the requirement document for one Capability MLE. A CRD defines what must remain meaningful and true regardless of whether the capability is realized through software, an agent, MCP, an API, UI, or a future mechanism.
A CRD can be related to a PRD but does not depend on one. It can exist independently in a reusable or open Capability Inventory.
2. Normative terms
MUST means required for a conforming Capability Requirements Document (CRD). SHOULD means recommended unless a documented reason exists not to follow it. MAY means optional.
3. Model
Capability MLE
A Capability MLE is the smallest complete ability that retains sufficient contextual logical meaning and produces a meaningful outcome.
It may be user-facing, agent-facing, application-facing, or internal. It must not be enlarged merely because a larger grouping is possible.
Interaction Contract MLE
An Interaction Contract MLE is the smallest contextually meaningful executable behaviour within a capability.
Actor + Command + Current State
-- subject to Policies/Invariants -->
New State + Result + Events/EffectsIt is independent of whether it is exposed through a UI, API, MCP tool, workflow, event consumer, function, or agent.
Realization and operational documentation
A realization is a particular implementation of a capability or interaction contract. Operational Capability Documentation describes a CRD's current realization in a particular service or system without changing the reusable CRD itself.
Capability Inventory
A Capability Inventory is a catalogue of available or planned Capability MLEs. Each entry should link to a CRD when one exists. A CRD may exist independently in a reusable or open inventory.
Cardinality
A capability may have one or many interaction contracts. A contract may have one or many realizations. Components, endpoints, functions, and tools may support multiple capabilities. No one-to-one mapping is implied.
4. Capability Requirements Document (CRD): required core
A conforming Capability Requirements Document (CRD) must contain the following:
| Field | Meaning |
|---|---|
name | Stable, concise capability name. |
definition | What the ability is, without implementation detail. |
capability purpose | The general outcome the ability exists to enable. |
boundaries | What belongs inside the capability and what explicitly does not. |
meaningful outcome | The condition or result that makes the ability complete. |
interaction contracts | At least one named contract, or an explicit unknown explaining why none is defined yet. |
rules/invariants | Binding statements, or an explicit statement that none are known. |
recommended defaults | Normal behaviour when no explicit choice overrides it, or an explicit statement that none are known. |
unknowns/unresolved questions | Deliberately unspecified, uncertain, or pending information. |
The definition should be independently understandable and meaningfully invokable. Split it when the parts retain the same purpose context independently; combine it when isolated parts lose that context.
5. Interaction Contract: required core
Each defined Interaction Contract must include:
| Field | Meaning |
|---|---|
name | Concise behaviour name. |
actor | Who or what initiates it; use unknown if not established. |
command/intent | The requested action or intent. |
current state | Required starting state or context. |
policies/invariants | Conditions that govern validity. |
transition | State change, or an explicit statement that no state changes. |
result | Direct outcome delivered to the actor or caller. |
events/effects | Material emitted events, side effects, or an explicit none known. |
6. Documentation semantics
Every substantive statement should receive a semantic class:
capability purpose must remain distinct from rationale/intent. For example, the purpose of Convert currency is enabling conversion of monetary values; a particular product rationale may be that the organization serves international customers.
7. Optional extensions
The following are optional and must not be required merely to classify something as a capability:
- Operational realization and availability
- Ownership, lifecycle, and implementation/business rationale
- API, MCP, tool, event, or UI exposure
- Implementation and dependency references
- UX representations and user stories
- Test evidence, telemetry, SLOs, or audit trail
- Provenance and source links
- Authorization, agent authority, grounding/context, and approval gates
8. Boundary rules
Boundaries must identify included and excluded concerns. They should distinguish a capability from adjacent capabilities, reusable primitives, and implementation detail. Boundaries are the primary protection against a capability expanding into a vague feature bucket.
9. Conformance
A document conforms as a Capability Requirements Document (CRD) when it satisfies the required core and its defined contracts include their required core. It conforms as an Operational Capability Realization when it additionally documents realization-specific constraints, references, and evidence it chooses to expose.
Draft 0.4 controls
Execution mode
Every realization declares who controls runtime flow: software-primary, agent-primary-using-software, software-primary-calling-agents, or unknown. Agent-built software is construction provenance, not runtime control. The distinction between agent-primary and software-primary control determines authority, fallback, observability, and failure handling.
Decision precedence
1. Rule / invariant
2. Explicit implementation requirement
3. Explicit owner or user choice
4. Recommended default
5. Agent judgmentA lower-precedence item cannot override a higher-precedence item. Same-level conflicts or unclear scope are unknown/unresolved until decided.
Shared reuse, skills, tools, and projections
CRDs may optionally declare a shared element's created-for capability and approved reuse, map skills and tools to capabilities or contracts, and link audience projections. A skill may realize one capability or bundle several; a tool is an executable primitive, not automatically a capability. A candidate that only passes the MLE test because "a developer running it for pre-release verification" counts as its actor, with no recurring operational role and no exposure beyond that developer, is presumptively a tool or test scaffolding, not a capability — good documentation and test coverage make it good engineering, not a capability. A CRD may also declare optional universal tags for a dimension not already derivable from another field — never for something a field like exposure or a contract's transition already settles. Pick the tag whose dimension a statement is actually about, not the nearest-sounding one: the most common mistake is reaching for network-touching whenever something involves an API call or a network-triggered side effect like a notification, when network-touching/local-only is only meaningful for a local-first/hybrid system where some capabilities genuinely differ on this — inside a uniformly hosted product every capability is network-touching by construction, so the tag adds nothing and notification-triggering (or data-sensitive, identity-related) is very likely the real dimension. A realization may separately declare implementation tags (product-specific groupings), always visually distinguishable from universal tags (e.g. an "impl:" prefix). A rendered projection should keep the visual tag/badge convention exclusive to implementation tags — a universal tag conventionally drives structure instead (a grouping/section key, e.g. its own tab) or appears as plain text. See Working with CRDs for the complete guidance.
Related MLEs by Dimension (§7.4)
A CRD may optionally trace its Capability MLE to lower-level, discipline-specific MLEs across eleven dimensions — Business/Domain, UX/Experience, Communication, Interaction/Behaviour, Frontend/Interface, Backend/Execution, Data/Information, API/Interoperability, Agentic, Verification, Operations — using relationship types defines, implements, supports, constrains, verifies, exposes, or reused_by. This is traceability, not required coverage: a capability must not be required to have an entry in every dimension, and a dimension with no genuine content must be omitted rather than filled to appear complete.
Communication is a first-class dimension, not a UX subcategory, because a message's meaning is typically shaped by business rules, rendered by frontend or delivery infrastructure, and localized independently — no single discipline owns it. A Communication MLE is the smallest contextually meaningful communication unit whose intended meaning should remain consistent across channels, interfaces, actors, and languages; its required core is name, purpose, trigger, audience, required meaning, and possible realizations. Its realization chain is canonical meaning → channel realization → language realization — stronger than a string-key → translation model because it separates meaning from both channel and language, not just from source code.
A Communication MLE is owned by the capability whose trigger produces it. Cross-cutting tone/terminology conventions that many messages should follow may instead live in a product's Source Context Reference, referenced rather than restated — the two are complementary, not competing. See the worked trial in Reconcile payments.