Thanks to visit codestin.com
Credit goes to github.com

Skip to content

docs(plans): add Agent Hub 22-agent enablement spec#1457

Merged
kovtcharov-amd merged 3 commits into
mainfrom
docs/agent-hub-22-agents-spec
Jun 4, 2026
Merged

docs(plans): add Agent Hub 22-agent enablement spec#1457
kovtcharov-amd merged 3 commits into
mainfrom
docs/agent-hub-22-agents-spec

Conversation

@kovtcharov-amd

@kovtcharov-amd kovtcharov-amd commented Jun 4, 2026

Copy link
Copy Markdown
Collaborator

Why this matters

GAIA's roadmap names ~22 purpose-built agents (email, smart home, knowledge, finance, etc.) but had no single plan for how to build and ship them consistently. This spec closes that gap: it defines a repeatable model so each agent is a thin, Hub-native package over shared infrastructure — not 22 bespoke codebases. The payoff is that adding an agent becomes ~150–500 LOC of glue plus a manifest, and every agent ships with the same packaging, autonomy, and personalization guarantees.

The spec turns "we want these agents" into an executable, waved plan with a concrete issue breakdown.

What's in it

  • Two-layer model — 7 shared infrastructure layers (memory, web search, connectors, VLM/media, filesystem, notifications, autonomy) + 22 thin agent packages.
  • 5-interface packaging standard — every agent is one compiled package exposing TUI / CLI / pipe / API server (+OpenAPI) / MCP server, published to R2 and surfaced on the website + Agent UI. Python now, C++ supersession path that keeps id/manifest/interfaces unchanged.
  • Autonomy Model — default posture (observe/prepare autonomous, commit gated), trigger taxonomy, the autonomous loop, graduated trust, and a per-agent user journey from install to steady state.
  • Personalization Model — memory-vs-datastore architecture, explicit/implicit/bootstrap capture, scoped retrieval, the cold-start→personalized lifecycle, privacy/control, and a per-agent personalization table.
  • Waved sequencing + full issue breakdown (§9), with memory tier (essential/enhance/optional) and datastore type per agent.

Test plan

  • Render-check the Markdown (tables, code fences, section numbering 1–12 sequential).
  • Confirm no dangling internal references (the companion issues doc / strategic analysis are intentionally not in this PR).
  • Maintainer review of the layer/wave sequencing and the per-agent autonomy + personalization tables.

Scope note: this PR adds the spec only (docs/plans/agent-hub-22-agents-spec.md). The companion issue-set doc and the milestone/issues are handled separately.

docs(plans): add Agent Hub 22-agent enablement spec
c52d9b5 
Implementation spec for shipping 22 purpose-built, proactive agents as
Hub-native packages. Defines the two-layer model (7 shared infrastructure
layers + thin agent packages), the 5-interface packaging standard
(TUI/CLI/pipe/API/MCP, compiled and published to R2, surfaced on the
website + Agent UI), and the memory-vs-datastore split per agent.

Adds an Autonomy Model (default posture, trigger taxonomy, graduated
trust, per-agent user journeys) and a Personalization Model (memory
architecture, capture/retrieval, lifecycle, per-agent personalization),
plus a full issue breakdown across waves.
@github-actions github-actions Bot added the documentation Documentation changes label Jun 4, 2026
@github-actions

github-actions Bot commented Jun 4, 2026

Copy link
Copy Markdown
Contributor

Summary

This is a planning-only PR: one new Markdown file (docs/plans/agent-hub-22-agents-spec.md, 779 lines) laying out how to ship 22 Hub-native agents over 7 shared infrastructure layers. It's a strong, well-structured spec — the internal arithmetic checks out, the manifest template matches the real hub/agents/python/*/gaia-agent.yaml format, and the version/path references are accurate against the current tree. No code, no security surface, no tests needed. The one thing worth fixing before merge is a dangling reference to a companion doc that isn't in the repo. Approve with one minor suggestion.

I verified the cross-references rather than taking them on faith: the .md-not-.mdx choice and the decision not to touch docs/docs.json are both correct and explicitly justified in the closing section (matches the other docs/plans/*.md files); agent-hub-ui.mdx, agent-hub.mdx, and autonomy-engine.mdx all exist; min_gaia_version: "0.20.0" matches src/gaia/version.py; and the §9 totals (73 = 13+26+22+12), the layer-issue count (26), and the memory-tier split (essential 10 / enhance 11 / optional 1 = 22) all reconcile exactly.

Issues Found

🟢 Dangling reference to a doc not in the repo (§9)
The verification note and the totals footnote both point to agent-hub-22-agents-issues.md ("The bulk-create script in agent-hub-22-agents-issues.md lists the exact 12 create lines to delete…"). That file doesn't exist in the tree, and the PR description says the companion issue-set doc is intentionally separate. The reference reads as if the file is present alongside this spec. Suggest marking it as forthcoming so a reader doesn't go hunting for it — e.g. "the companion agent-hub-22-agents-issues.md (separate PR)".

🟢 Point-in-time GitHub claims will rot (§9, §3)
"Verified against live GitHub (this session)" plus the hardcoded issue states (#963 CLOSED, #660/#559 scope-mismatches) are a snapshot that drifts as issues change. It's already hedged with "verify before relying," so this is acceptable for a planning doc — flagging only so it's a conscious choice. No change required.

🟢 Unverifiable external market claim (§6)
"OpenClaw's single most-downloaded skill (419K)" is an outside-the-repo statistic I can't validate. Fine as a rhetorical market signal, but consider a source link or softening if this spec gets cited downstream.

Strengths

  • Self-consistent at a level most specs aren't. Every total, count, and tier breakdown reconciles — the §9 issue math (73 total, ~60 net-new, 12 duplicates) and the per-agent memory-tier counts add up exactly. That makes the issue-creation step mechanically trustworthy.
  • Grounded in the real packaging model. The §7 manifest template is a faithful superset of the existing gaia-agent.yaml schema (same id/language/python.entry_*/interfaces shape), with genuinely new fields (layers, connectors, proactive) clearly tagged # NEW. It correctly keeps agent definition in agent.py while using gaia-agent.yaml only as the Hub packaging manifest — no collision with the v0.17.5 removal of YAML agent definitions.
  • Honest about dependencies. Wave 0 is called a hard gate, "new" vs. existing-issue references are separated, and §5/§6 explicitly add "no new issues" — the spec resists scope creep against its own layer breakdown.

Verdict

Approve with suggestions. Documentation-only, internally consistent, and accurate against the codebase. The dangling agent-hub-22-agents-issues.md reference is the only thing worth touching up, and it's non-blocking. Nice work.

Ovtcharov added 2 commits June 4, 2026 15:49
docs(plans): add self-contained issue set for the 22-agent program
bae296e 
Companion to the enablement spec: full, self-contained GitHub issue
bodies (context, goal, scope, acceptance criteria, dependencies,
references) for the 7 layer epics, 5 wave epics, 13 net-new layer
issues, 22 agent packages, and 12 cross-cutting issues — plus move
directives for existing related issues. Each issue stands alone without
requiring the spec. Includes a machine-extractable generator format.
docs(plans): drop issue-set doc from the spec PR
e4d06a4 
The 22-agent issue set now lives as GitHub issues under milestone
"Agent Hub: 22 Agents [OSS]" (#48), making the in-repo markdown
redundant. Keep this PR focused on the enablement spec.
@kovtcharov-amd kovtcharov-amd enabled auto-merge June 4, 2026 23:27
@kovtcharov-amd kovtcharov-amd disabled auto-merge June 4, 2026 23:27
@kovtcharov-amd kovtcharov-amd merged commit 0c197ef into main Jun 4, 2026
22 of 23 checks passed
@kovtcharov-amd kovtcharov-amd deleted the docs/agent-hub-22-agents-spec branch June 4, 2026 23:27
This was referenced Jun 4, 2026
Open
Open
Open
Open
Open
Open
Open
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@itomek-amd itomek-amd Awaiting requested review from itomek-amd
@amd-pworfolk amd-pworfolk Awaiting requested review from amd-pworfolk

Assignees

No one assigned

Labels

documentation Documentation changes

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@kovtcharov-amd