Capability Spec

The Complete Agent Contract

This is the complete agent contract for a hypothetical spec-writer capability at L2 maturity. It illustrates all 9 surfaces declared together. For reference: Section 5 — Agent Contract.

identity:
  name: spec-writer
  version: 2.1.0
  capability: spec-writer@2.1
  maturity: L2
  owner:
    individual: tarek.fawaz@example.com
    team: platform-architecture

input_schema:
  format: json_schema
  required: [feature_description, target_codebase]
  feature_description: { type: string, minLength: 50, maxLength: 5000 }
  unstructured_input: false

output_schema:
  required: [specification, confidence, decision_trace]
  confidence:     { $ref: kernel://schemas/confidence/v2 }
  decision_trace: { $ref: kernel://schemas/decision_trace/v2 }

declared_tools:
  - name: read_codebase
    blast_radius: read
    private_data_access: true
  - name: read_ticket_descriptions
    blast_radius: read
    untrusted_content: true        # tickets can contain prompt injection

cost_envelope:
  expected_tokens_in: 8000
  max_tokens_in: 20000
  context_efficiency: 0.65
  expected_cost_usd: 0.08
  max_cost_usd: 0.30

hitl_hotl:
  default_mode: HITL
  hotl_eligibility: { requires_maturity: L2, minimum_trust_score: 0.75 }
  hotl_revoke_triggers: [confidence_below: 0.7, trifecta_detected: true]

observability:
  events: [invocation_start, tool_call, invocation_complete]
  traces: { decision_trace: required, sampling_rate: 100 }

What to Notice

• Identity names a human — owner.individual is a person, not a team alias. Accountability requires a named human.
• Input schema is bounded — feature_description has minLength and maxLength; unbounded inputs are rejected.
• Output schema includes the cognitive layer — confidence and decision_trace are required and reference kernel schemas.
• Tools are categorized for trifecta detection — only read_ticket_descriptions touches untrusted content, and no tool communicates externally, so the agent is NOT lethal-trifecta and can be eligible for HOTL.
• Observability is mandatory — the decision trace is required with sampling_rate 100: no sampling at L2.