← index2026-04-30 14:05 (Beirut)(backfill from DOCUMENTATION/)

AGP → Brian Capability Registry: Formalization Plan

Date: 2026-04-30
Owner: Jonah / Brian
Goal: Restructure /opt/agent/data/capabilities.md (3,065 entries, flat text) and /cap-refresh into an Autogenesis-Protocol-compliant registry, ready to publish on GitHub as a public spec + reference implementation.

1. Source paper

Autogenesis: A Self-Evolving Agent Protocol
Wentao Zhang, Zhe Zhao, Haibin Wen, Yingcheng Wu, Ming Yin, Bo An, Mengdi Wang
arXiv:2604.15034v2 (Apr 2026) — https://arxiv.org/abs/2604.15034
Reference impl: https://github.com/DVampire/Autogenesis

Two-layer architecture

Layer	Concern	What it specifies
RSPL — Resource Substrate Protocol Layer	"What evolves"	Prompts, agents, tools, environments, memory all modeled as protocol-registered resources with explicit `state`, `lifecycle`, and `versioned` interfaces
SEPL — Self Evolution Protocol Layer	"How evolution occurs"	Closed-loop operator interface: propose → assess → commit — every change carries auditable lineage + rollback hook

Self-evolution loop (Act → Observe → Optimize → Remember)

Act — agent executes with current resources
Observe — capture outcome + traces + intermediate reasoning + env feedback
Optimize — reflection / GRPO / Reinforce++ updates prompts/solutions/variables
Remember — persist summaries/insights to memory for next session

Why it matters for us

The AGP critique of A2A and MCP — "under-specifies cross-entity lifecycle/context, version tracking, and safe-update interfaces, encouraging monolithic compositions and brittle glue code" — describes our capabilities.md exactly. We have 3,065 CAP_IDs across 38 layers in a single flat markdown file, regenerated wholesale by /cap-refresh --full. No lifecycle, no version, no rollback, no propose/assess/commit boundary. AGP gives us the formal spine to fix that without inventing one.

2. Current state — what we have today

2.1 Registry file

Path: /opt/agent/data/capabilities.md (21,919 lines, ~1.4 MB)
Format: flat markdown, ### header per entry
Fields per entry: layer, source, what, account, status, HARD (optional)
6 split files for sub-domains: caps_mcp.md, caps_cc.md, caps_oc.md, caps_delegates.md, caps_server.md, caps_infra.md, caps_access.md

2.2 Refresh skill

/cap-refresh — re-runs schema validator + deadpath scanner, re-seeds recent "I-can't" incidents, reports drift
/cap-refresh --full — regenerates the whole file via 7-agent parallel enumeration
/cap-refresh --weekly — grep-checks transcripts for tool calls in trigger scope without a preceding plan block

2.3 Planning loop

using-capabilities skill forces <capability-plan> block above first tool call
4 hard rules: ≥3 considered options, ≥1 composition, residual-constraint language gate, no filler

2.4 Gaps vs AGP

AGP requirement	Today	Gap
Resource has `state`	only flat `status` field	no state-machine; can't tell "registered-but-unverified" from "active-degraded"
Resource has `lifecycle`	none	no `propose / register / verify / activate / deprecate / archive` transitions
Resource has `versioned` interface	none	a CAP_ID either exists or doesn't; no semver, no breaking-change marker
Closed-loop propose	implicit (gap-patch passes)	not auditable; no PR-style review
Closed-loop assess	none	no validator runs against the proposed delta
Closed-loop commit with lineage	none	full-file regenerate erases attribution
Rollback	git revert only	no resource-level rollback; partial regen is impossible
Tracing across runs	session-scoped only	no per-CAP usage trace, no failure→amend feedback

3. Proposed formalization — `cap-protocol-v1`

3.1 Move from flat-file to per-resource files

/opt/agent/data/cap-registry/
  resources/
    <CAP_ID>.yaml          # one file per capability
  manifests/
    <layer>.yaml           # index per layer (cc-native, mcp, skill, ...)
  events/
    <YYYY-MM>/             # append-only event log
      <ISO-timestamp>_<CAP_ID>_<event>.yaml
  schema/
    resource.schema.json   # JSON Schema for resources/*.yaml
    event.schema.json      # JSON Schema for events/*.yaml
  HEAD                     # current registry version (semver)
  CHANGELOG.md             # human-readable lineage

3.2 Resource record (RSPL) — replaces flat `### CAP_ID`

cap_id: tool_read
schema_version: 1
layer: cc-native
source: Read
what: Read files from local filesystem (text, PDF, images, notebooks)
account: N/A
state:
  current: active           # one of: proposed, registered, verified, active, degraded, deprecated, archived
  since: 2026-04-20T00:00:00Z
  health: green             # green | yellow | red
  last_verified: 2026-04-30T07:42:00Z
  verifier: cap-refresh-v1.4.0
lifecycle:
  proposed_by: jonah
  proposed_at: 2025-09-15T00:00:00Z
  registered_at: 2025-09-15T00:00:00Z
  verified_at: 2025-09-15T00:00:00Z
  activated_at: 2025-09-15T00:00:00Z
  deprecated_at: null
  archived_at: null
version: 1.0.0              # semver — bump on interface or behavior change
interface:
  inputs: { file_path: string, limit?: int, offset?: int, pages?: string }
  outputs: file_contents | error
  side_effects: none
constraints:
  HARD: null
  rate_limit: null
  account_lock: null
provenance:
  added_by: cap-refresh --full (run 2025-09-15)
  evidence: /opt/agent/data/cap-evidence/tool_read.txt
related:
  composes_with: [tool_edit, tool_write, tool_bash]
  superseded_by: null
  supersedes: null

3.3 Event record (SEPL) — append-only, every state change

event_id: 2026-04-30T07:42:00Z_tool_read_verify
cap_id: tool_read
operator: cap-refresh
phase: assess              # propose | assess | commit | rollback
result: pass               # pass | fail | warn
delta:
  before: { state.health: green, last_verified: 2026-04-23T... }
  after:  { state.health: green, last_verified: 2026-04-30T... }
trace:
  validator_run_id: cr-20260430-074200
  evidence_files: [validator_log.txt, deadpath_scan.json]
auditable: true
rollback_to: 2026-04-23T... (previous event_id)

3.4 Refresh becomes a closed loop (matches AGP's propose→assess→commit)

/cap-refresh --propose          # diffs reality against registry, writes proposals/<run-id>/
/cap-refresh --assess <run-id>  # runs validator against the proposal, not the live registry
/cap-refresh --commit <run-id>  # writes resource files + event log + bumps HEAD
/cap-refresh --rollback <event-id>  # restores resource to pre-event state, logs counter-event

The current /cap-refresh --full becomes propose + assess + commit chained — but each phase is now separable and each step is auditable.

3.5 Lifecycle state machine

  proposed ──verify──▶ registered ──verify──▶ verified ──activate──▶ active
                          │                                            │
                          ▼                                            ▼
                       rejected                                    degraded
                                                                       │
                                                                  ┌────┼────┐
                                                                  ▼         ▼
                                                              recovered  deprecated
                                                                            │
                                                                            ▼
                                                                         archived

proposed — a --propose run found it; not yet validated
registered — schema validates; source resolves; not yet behavior-checked
verified — behavior check (one successful invocation or witness trace) passed
active — currently usable; default state for healthy CAP_IDs
degraded — fails health check but not removed (e.g., MCP server returning 503)
deprecated — superseded; still callable; will be archived after grace window
archived — removed from active surface; kept for historical lineage only

3.6 Versioning

Per-resource semver in version: field
Major bump = breaking interface change (input/output shape)
Minor bump = additive (new optional input, new sub-tool)
Patch bump = behavior fix without interface change
HEAD file holds registry-level version; CHANGELOG.md is the human view

3.7 What stays the same

The <capability-plan> block stays exactly as today — the user-facing planning contract is independent of registry structure
CAP_ID naming convention (lowercase, underscore-separated) unchanged
/cap-refresh --weekly transcript audit unchanged
The 4 hard rules of using-capabilities skill unchanged

4. Migration plan (single-pass, reversible)

Step	Action	Reversible	Owner
1	Author `schema/resource.schema.json` + `schema/event.schema.json`	yes	Brian
2	Write `cap-migrate-v1.py` — splits flat file into per-resource YAMLs, infers `state.current` from `status`, infers `version: 1.0.0` everywhere	yes (keeps flat file)	Brian
3	Run migration in `/tmp/cap-registry-staged/`, validate all 3,065 records against schema	yes	Brian
4	Side-by-side soak — `/cap-refresh` writes to BOTH old flat file AND new per-resource for 7 days	yes	Brian
5	Switch `using-capabilities` skill to read from new registry; flat file becomes read-only mirror	yes (one-line revert)	Brian
6	After 14 days clean, archive flat file under `cap-registry/legacy/`	yes (git history)	Brian
7	Implement `--propose / --assess / --commit / --rollback` phases	yes	Brian
8	Write `protocol-spec.md` — public-facing AGP-aligned spec	n/a	Brian
9	Open-source repo: `webspot/cap-protocol`	n/a	Jonah approval needed

Time estimate: Steps 1–3 fit in one focused Brian session (~2 hours). Steps 4–6 are passive (calendar). Steps 7–9 are a follow-up session each.

5. What the public GitHub repo would look like

webspot/cap-protocol/
  README.md                   # the pitch + 30-second example
  SPEC.md                     # the protocol — RSPL fields, SEPL phases, lifecycle FSM
  schema/
    resource.schema.json
    event.schema.json
  reference-impl/
    python/                   # cap-protocol Python package
      cap_protocol/
        models.py             # Pydantic Resource + Event
        validator.py
        operator.py           # propose/assess/commit/rollback
        cli.py                # `cap` CLI: cap propose / cap assess / cap commit
      tests/
    examples/
      brian-registry/         # sanitized excerpt of /opt/agent/data/cap-registry/
  docs/
    motivation.md             # why flat capability lists break down
    comparison-with-mcp.md    # how cap-protocol layers atop MCP
    comparison-with-agp.md    # what we kept, what we simplified, what we changed
    case-study-brian.md       # real numbers from 3,065 CAP_IDs
  LICENSE                     # MIT

Pitch angle

MCP says "here are the tools you can call right now"
A2A says "here is how agents talk"
AGP says "here is how the substrate evolves"
cap-protocol says "here is how an agent knows what it can do and proves it" — the missing capability registry layer that sits between MCP and the agent's planner

Differentiation from AGP

AGP is a research protocol with academic-style optimizers (GRPO, Reinforce++)
cap-protocol is a practitioner spec: no learning required, just structured registration + lifecycle + lineage. The optimizer slot is open — you can plug in reflection or human review or AGP's optimizers.

6. Open questions for Jonah

License — MIT or ELv2 (context-mode used ELv2)? Recommend MIT for adoption.
Brand — webspot/cap-protocol, brianserves/cap-protocol, or new org caprotocol?
Reference impl language — Python only, or Python + TypeScript? TS adds reach but doubles work.
Public registry excerpt — sanitize Brian's CAP_IDs (strip API key references, account names) and ship as the canonical example, or build a synthetic example registry?
Citation — cite AGP paper in SPEC.md? Recommend yes (intellectual honesty + SEO via cs.AI cross-reference).

7. Risk register

Risk	Mitigation
Migration corrupts `capabilities.md` mid-run	Step 3 stages in `/tmp/`, step 4 dual-writes — flat file is the source of truth until step 6
`<capability-plan>` skill breaks because schema differs	Skill reads via thin adapter; adapter swaps in one line at step 5
Open-sourcing exposes private CAP_IDs	Step 8 sanitization pass; only ship layer names + counts + a synthetic example
AGP authors object to spec resemblance	Cite paper, frame as "implementation-focused subset"; AGP is CC-BY-4.0 so no legal blocker
Repo gets zero traction	Pre-launch: one HN post + Matt Pocock-style newsletter mention; if no traction in 14 days, fold spec into Webspot internal docs

8. Recommended next action

Step 1 + 2 + 3 in one Brian session: author the two JSON schemas, write the migration script, run it staged. Output is a /tmp/cap-registry-staged/ tree with 3,065 validated YAML files — reversible, no production impact. Schedule a /loop review of the staged tree before promoting to step 4.

Sources
- arXiv:2604.15034v2 — Autogenesis paper (abstract + README)
- github.com/DVampire/Autogenesis — reference architecture, repo layout, optimizer list
- /opt/agent/data/capabilities.md — current registry (3,065 entries, 38 layers)
- /root/.claude/skills/using-capabilities/SKILL.md — current planning contract
- /root/.claude/commands/cap-refresh.md — current refresh skill

AGP → Brian Capability Registry: Formalization Plan

AGP → Brian Capability Registry: Formalization Plan

1. Source paper

Two-layer architecture

Self-evolution loop (Act → Observe → Optimize → Remember)

Why it matters for us

2. Current state — what we have today

2.1 Registry file

2.2 Refresh skill

2.3 Planning loop

2.4 Gaps vs AGP

3. Proposed formalization — cap-protocol-v1

3.1 Move from flat-file to per-resource files

3.2 Resource record (RSPL) — replaces flat ### CAP_ID

3.3 Event record (SEPL) — append-only, every state change

3.4 Refresh becomes a closed loop (matches AGP's propose→assess→commit)

3.5 Lifecycle state machine

3.6 Versioning

3.7 What stays the same

4. Migration plan (single-pass, reversible)

5. What the public GitHub repo would look like

Pitch angle

Differentiation from AGP

6. Open questions for Jonah

7. Risk register

8. Recommended next action

3. Proposed formalization — `cap-protocol-v1`

3.2 Resource record (RSPL) — replaces flat `### CAP_ID`