Clarity Agent Protocol (CAP)
``` ┌─────────────────────────┐ │ CONTRACT REGISTRY │ │ (schemas + traits) │ └───────────┬─────────────┘ │ ┌───────────────────┼───────────────────┐ ↓ ↓ ↓ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ Task Contract │ │ Task Contract │ │ Task Contract │ │ schema: X │ │ schema: Y │ │ schema: Z │ │ traits: [a,b] │ │ traits: [b,c] │ │ traits: [a,c] │ └───────┬───────┘ └───────┬───────┘ └───────┬───────┘ │ │ │ ↓ ↓ ↓ ┌───────────────────────────────────────────────────────┐ │ AGENT DISPATCHER │ │ Matches contra
Full Public Reader
Clarity Agent Protocol (CAP)
## What This Is
An agent-agnostic governance protocol for AI agent task execution. Inspired by Stacks/Clarity smart contracts — tasks are structured as contracts with traits, schemas, and validation rules. Any agent, any model, any system can submit work. The protocol validates conformance and rejects non-compliant output with structured feedback.
## Core Concept
Just as Clarity smart contracts on Stacks enforce trait conformance at the chain level, CAP enforces task conformance at the agent orchestration level. Agents don't just "do work" — they fulfill contracts. Contracts define what success looks like. Non-conforming work gets rejected with specific feedback, not vague "try again."
Architecture
┌─────────────────────────┐
│ CONTRACT REGISTRY │
│ (schemas + traits) │
└───────────┬─────────────┘
│
┌───────────────────┼───────────────────┐
↓ ↓ ↓
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ Task Contract │ │ Task Contract │ │ Task Contract │
│ schema: X │ │ schema: Y │ │ schema: Z │
│ traits: [a,b] │ │ traits: [b,c] │ │ traits: [a,c] │
└───────┬───────┘ └───────┬───────┘ └───────┬───────┘
│ │ │
↓ ↓ ↓
┌───────────────────────────────────────────────────────┐
│ AGENT DISPATCHER │
│ Matches contracts to agents by trait capability │
└───────────────────────┬───────────────────────────────┘
│
┌───────────────────┼───────────────────┐
↓ ↓ ↓
Claude Max Codex CLI Gemini Pro
Custom Bot Human Dev Any Agent
│ │ │
↓ ↓ ↓
┌───────────────────────────────────────────────────────┐
│ VALIDATION ENGINE │
│ Checks output against contract schema + traits │
│ CONFORM → Accept + merge/deploy │
│ REJECT → Structured feedback + re-queue │
└───────────────────────────────────────────────────────┘Key Abstractions
### Contracts
A contract defines a unit of work with:
- Schema: Expected input/output structure
- Traits: Capabilities required (`buildable`, `testable`, `deployable`)
- Validation rules: How to check conformance
- Governance: Who can approve, auto-merge thresholds
### Traits (from Clarity)
Composable interfaces agents declare they can fulfill:
- `impl-buildable` — output compiles/builds without errors
- `impl-testable` — includes tests that pass
- `impl-deployable` — ready for production deployment
- `impl-reviewable` — structured for code review
- `impl-documented` — includes documentation
- Custom traits per project
### Governance
- Auto-accept threshold: contracts that score above N
- Review gate: below threshold → human or senior agent review
- Escalation: repeated failures bump to higher-tier agent
- Rejection feedback: structured, actionable — not "try again" but "trait X failed because Y, fix by doing Z"
## Tech Stack
- Runtime: TypeScript/Node.js (portable, runs anywhere)
- Schema: JSON Schema for contract definitions
- Storage: SQLite for local, Supabase for distributed
- Transport: HTTP webhooks + WebSocket for real-time
- CLI: `cap validate`, `cap submit`, `cap status`
Directory Structure
clarity-agent-protocol/
├── CLAUDE.md # This file
├── README.md # Public-facing docs
├── package.json
├── tsconfig.json
├── src/
│ ├── index.ts # Entry point + CLI
│ ├── core/
│ │ ├── contract.ts # Contract definition + parsing
│ │ ├── trait.ts # Trait system (impl-trait pattern)
│ │ ├── schema.ts # JSON Schema validation
│ │ └── governance.ts # Approval rules, thresholds
│ ├── engine/
│ │ ├── validator.ts # Validation engine
│ │ ├── dispatcher.ts # Agent-agnostic dispatch
│ │ ├── rejector.ts # Structured rejection feedback
│ │ └── escalator.ts # Auto-escalation logic
│ ├── adapters/
│ │ ├── github.ts # GitHub webhook adapter
│ │ ├── clawdbot.ts # Clawdbot session adapter
│ │ ├── claude-code.ts # Claude Code CLI adapter
│ │ ├── codex.ts # Codex CLI adapter
│ │ └── generic.ts # Generic HTTP adapter
│ ├── registry/
│ │ ├── contracts/ # Contract definitions (YAML/JSON)
│ │ └── traits/ # Trait definitions
│ └── storage/
│ ├── sqlite.ts # Local storage
│ └── supabase.ts # Distributed storage
├── contracts/ # Example contract definitions
│ ├── feature.yaml # Feature implementation contract
│ ├── bugfix.yaml # Bug fix contract
│ ├── refactor.yaml # Refactor contract
│ └── ios-build.yaml # iOS build + TestFlight contract
└── tests/Contract Example (YAML)
name: feature-implementation
version: "1.0"
traits:
required:
- buildable
- testable
- documented
optional:
- deployable
schema:
input:
title: string
description: string
project: string
branch: string
output:
commits: array
files_changed: array
build_status: enum[pass, fail]
test_results:
passed: number
failed: number
coverage: number
documentation: string
validation:
build_status: "must equal 'pass'"
test_results.failed: "must equal 0"
test_results.coverage: "must be >= 60"
files_changed: "must not be empty"
governance:
auto_accept:
coverage_threshold: 80
all_tests_pass: true
build_clean: true
escalation:
max_rejections: 3
escalate_to: "human-review"
rejection_feedback:
format: "structured"
include_fix_suggestions: true## Design Principles
1. Agent-agnostic — works with any AI model, any CLI, any API, any human
2. Clarity-inspired — traits, conformance, structured validation (not fuzzy LLM judging)
3. Rejection is data — every rejection teaches the agent what to fix
4. Governance scales — from solo dev to team to enterprise
5. Composable — traits combine, contracts compose, adapters plug in
6. Local-first — runs on a laptop, scales to distributed
Promotion Decision
Attach run IDs, datasets, metrics, and reproduction commands.
Source Anchor
clarity-agent-protocol/CLAUDE.md
Detected Structure
Method · Evaluation · Code Anchors · Architecture