A2A peer registry: discover skills from peer agent-card instead of duplicating in well-known-agents.json

[rockfordlhotka]

Problem

Today, RockBot's peer registry (well-known-agents.json) carries a full copy of each peer's skill list — id, name, description for every skill. This duplicates what the peer already publishes at /.well-known/agent-card.json (the A2A-spec-defined source of truth).

Surfaced while shipping Foragent milestone 5 (MarimerLLC/foragent#7). Every new Foragent capability now requires edits in three places:

1. Foragent's ForagentCapabilities.Skills (authoritative within Foragent).
2. RockBot's well-known-agents.json (duplicate copy of the skill array).
3. RockBot's agent-trust.json approvedSkills (local trust policy — this one is legitimately RockBot-owned).

Worse, in the docker-compose dev harness, (2) and (3) are seeded into a volume; the init script guards against overwriting agent-trust.json, so picking up a new peer skill requires wiping the entire rockbot-data volume (taking memory, conversations, and feedback with it) or editing the file in-place.

Proposal

Shrink well-known-agents.json entries to just the peer coordinates and trust/auth config that can't be discovered from the agent-card itself:

{
  \"agentName\": \"Foragent\",
  \"url\": \"http://foragent:8080\",
  \"authHeaderName\": \"X-Api-Key\",
  \"authHeaderValueBase64\": \"...\"
}

At first contact (or on a TTL / explicit refresh), RockBot's A2A client fetches {url}/.well-known/agent-card.json and caches the peer's skills/description/version/protocolVersion from there. Agent-card fetch is already mandated by the A2A v1 spec for discovery — the data is available; RockBot just isn't using it as the source of truth.

agent-trust.json stays as-is: approvedSkills is local policy, genuinely RockBot-owned, and gated changes there are a feature not a bug.

Migration

Back-compat can be preserved by treating an embedded skills array as an override (useful for offline/airgapped setups) and falling back to live fetch when absent. Or by bumping a schema version and migrating on first load.

Impact

• One source of truth for peer skills (the peer's own agent-card).
• Adding a skill to a peer propagates without reseeding RockBot's data volume.
• Matches the A2A v1 discovery model literally instead of shadowing it.

Cross-linked in Foragent's docs/framework-feedback.md §Step 5.