agent-capability-standard

Agent Capability Standard

Grounded Agency: A framework for building AI agents that know what they don't know.

Versioning: The spec version (v1.0.0) tracks the standard itself. The plugin version (v1.2.0) tracks the Claude Code implementation. The Python package (grounded-agency) uses its own SemVer. See GOVERNANCE.md for the versioning policy.

# Install as Claude Code plugin
claude plugin marketplace add synaptiai/synapti-marketplace
claude plugin install agent-capability-standard

---

What Is This?

Agent Capability Standard is the technical specification. Grounded Agency is the philosophy behind it.

Most AI agent systems fail in production because:

• Composition is implicit (no contracts between capabilities)
• State is ungrounded (no provenance for claims)
• Conflict resolution is undefined (no trust model)
• Safety is retrofitted (no checkpoints or rollback)

This standard fixes that by making reliability structural—not optional.

The Core Idea

Every agent action should be:

1. Grounded — backed by evidence, not hallucination
2. Auditable — with provenance and lineage
3. Safe — mutations require checkpoints
4. Composable — typed contracts between capabilities

---

The Periodic Table of Agent Capabilities

Just as chemistry has ~118 elements that compose into infinite molecules, this standard defines 36 atomic capabilities that compose into infinite workflows.

┌─────────────────────────────────────────────────────────────────────────┐
│ CAPABILITIES (atoms)              →  WORKFLOWS (molecules)              │
│                                                                         │
│  observe + search + plan          →  debug_code_change                  │
│  + checkpoint + execute                                                 │
│  + verify + rollback                                                    │
│                                                                         │
│  receive + transform + integrate  →  digital_twin_sync_loop             │
│  + detect + plan                                                        │
│  + checkpoint + mutate + audit                                          │
└─────────────────────────────────────────────────────────────────────────┘

Capabilities are atoms: Irreducible primitives with defined I/O contracts.

Workflows are molecules: Compositions that solve real problems.

The goal isn't more atoms—it's better molecules.

Why 36?

The 36 capabilities were systematically derived from first principles:

1. Cognitive architecture analysis (BDI, SOAR, ReAct patterns)
2. Industry tool patterns (MCP, LangChain, Claude Skills)
3. Rigorous atomicity testing (cannot be decomposed further)

Each capability:

• Performs exactly one irreducible cognitive operation
• Has a well-defined I/O contract with evidence anchors
• Maps to how agents actually work in production

Domain specializations become parameters, not separate capabilities. detect(domain: anomaly) rather than detect-anomaly.

For the full derivation methodology, see docs/methodology/FIRST_PRINCIPLES_REASSESSMENT.md.

---

Why This Matters

The Problem

AI agents in production fail silently. When a retrieval step hallucinates, downstream actions proceed with bad data. When conflicts arise between sources, there's no resolution strategy. When mutations fail, there's no rollback.

These aren't edge cases—they're the norm. Most agent systems lack structural safeguards, so failures are discovered after the damage is done.

The Cost

• Debug time: Hours tracing why an agent made a decision with no audit trail
• Data corruption: Unrecoverable state from failed mutations without checkpoints
• Trust erosion: Users lose confidence after unexplained failures
• Compliance risk: Auditors ask "why did the agent do X?" and you can't answer

The Solution

This standard makes failures visible and recoverable:

• Every claim traces to evidence (or explicitly marks uncertainty)
• Every mutation has a checkpoint (rollback is always possible)
• Every conflict has a resolution strategy (trust model decides)
• Every decision has lineage (audit answers "why")

When to Use This