Docs / Guides

Map your first capability

Turn a real-world ability into a capability ID, host boundary, policy rule, invocation context, result, and evidence expectation.

Plain English

Start with something someone can do, then name the host that owns it and the rules for calling it.

Why it exists

Good capability maps prevent demos from hiding lifecycle, authorization, and failure semantics.

Formal definition

A capability map is an implementation planning artifact that identifies actor, capability, host, policy, context, result, lifecycle, version, and evidence.

Concrete example

Ground the concept before the schema.

Map schedule_technician before writing the host so denial and unavailable outcomes are known up front.

schedule_technicianInvokable

Finds an available qualified technician and reserves a service window.

host: ServiceOpsHostpolicy: approval_requiredv1.0.0

Policy boundary

Approval required

manager_approval

A manager must approve technician scheduling before the host returns a confirmed appointment.

Invocation trace

  1. 01 Actor

    Planning Agent

  2. 02 Capability

    schedule_technician

  3. 03 Host

    ServiceOpsHost

  4. 04 Policy

    manager_approval

  5. 05 Context

    job_context

  6. 06 Result

    Confirmed Appointment

mapped-capability.json
json
{  "id": "service-ops-host",  "version": "0.1.0",  "protocol_version": "0.1",  "kind": "service",  "capabilities": [{    "id": "schedule_technician",    "version": "1.0.0",    "description": "Finds an available qualified technician and reserves a service window.",    "status": "experimental",    "modes": ["sync"],    "emits": ["execution_started", "execution_completed", "execution_denied"],    "policy": {      "risk_tier": "high",      "auth_required": true,      "approval_required": true,      "allowed_actors": ["agent://planning-assistant"]    },    "metadata": {      "required_permissions": ["service:dispatch"],      "lifecycle": "invokable"    }  }],  "evidence": {    "store": "local-append-only",    "append_only": true  }}

Relationships

Where this sits in the protocol.

Each concept should explain its neighbors so implementation teams can preserve the boundary across manifests, invocation, evidence, and tests.

Capability mapping feeds manifest design.

Policy mapping feeds invocation safety.

Result mapping feeds composition and evidence.

Visual model

  1. 01Name the actor and ability.
  2. 02Assign a host and policy boundary.
  3. 03Define result, lifecycle, version, and evidence.

Implementation notes

  • Use the interactive mapper for the first pass.
  • Write one unavailable-path test and one policy-denial test.
  • Move the map into a manifest only after the boundary is clear.

Common mistakes

  • Starting with a framework tool schema before naming the host.
  • Treating approvals as comments instead of protocol outcomes.
  • Skipping the result contract.

Related concepts

Keep reading through the boundary.

Use the mapper →Define capability contracts →Conformance →