Capability-First Development
Capability-first development starts by declaring what should exist, not by writing how it works. Instead of building a function and then wiring it in, you declare a capability: its inputs, outputs, and intent. The system tracks that declaration as a node in the graph, even if no implementation exists yet.
Imagine you need a slugify transformation. You declare:
- Input: `text`
- Output: `slug`
- Behavior: “normalize and hyphenate”
This creates a capability node. The graph can then show that the capability is declared but unrealized. AI can propose an implementation, or you can route it through an external gate. Either way, the system now knows that this transformation should exist.
Why Capabilities First
Traditional development forces you to implement before you can reason about integration. Capabilities-first development inverts this:
- You describe the desired transformation.
- The graph records the intent.
- The system can reason about gaps.
This turns development into a map of desired truths rather than a list of incomplete functions.
The Capability Node
A capability node typically includes:
- Input schema
- Output schema
- Intent description
- Status (declared, implemented, external, stub)
- Links to tests or assertions
The node is not code. It is a declaration of necessity. It becomes part of the system’s cognitive map.
Tests as Truth Conditions
Capabilities often link to tests not as after-the-fact verification but as truth claims. You can declare:
- “This capability should exist.”
- “These outputs should result from these inputs.”
When you later implement the capability, the system can check whether it fulfills the declared truth. This is test-driven thinking at the level of meaning.
AI as Filler of Gaps
AI thrives in this mode. If the system tells it “here is a declared capability with no implementation,” it can propose one. The AI does not need to guess in the dark; it has a structural target. It can also search for similar capabilities in the graph and reuse patterns.
This makes AI a natural collaborator: it fills gaps between intent and implementation.
Routing and Gates
Some capabilities may be fulfilled by external systems. Instead of importing a library directly, you define a gate:
- A wrapper that maps the capability to an external function
- A recorded dependency with version and behavior
This keeps the dependency explicit and structural. You can compare multiple gates for the same capability, or replace one without changing the capability declaration.
Benefits
- Clarity: You always know what the system intends to provide.
- Coverage: Unimplemented capabilities are visible as graph gaps.
- Flexibility: You can choose how to fulfill a capability later.
- Traceability: Capabilities persist even if implementations change.
Example Workflow
- Declare capabilities for a new pipeline.
- Connect them in the graph to show intended flow.
- Ask AI to implement missing capabilities.
- Bind tests to capability declarations.
- Replace or refine implementations without changing the capability nodes.
This creates a development process where structure leads, and code follows.
How It Changes Thinking
- You think in terms of affordances, not functions.
- You design a language of transformations before you write them.
- The graph becomes your backlog of intent.
Scaling Capability-First Development
As the system grows, capability nodes become a catalog of what your system can do. You can query:
- “Show all capabilities with no implementation.”
- “Which capabilities are fulfilled externally?”
- “Which capabilities are used most often in successful pipelines?”
This turns your system into a map of declared truths and their realizations.
Capability-first development is a way to keep your system aligned with intent, not just with code. It makes meaning first-class and lets implementation follow with clarity.