Handbook
Forge Agents
Forge Agents (forge-agents) is the private monorepo for channel agents — long-running Matrix and web participants that help operators ask questions, bridge Cursor sessions, and manage agent lifecycle on Granite.
Hub · Updated
This handbook hub sits in forge-platform (governance and contracts). Runnable code lives in forge-agents; batch runners stay in forge-workcells.
Channel agents vs workcells
| Concern | Channel agents (forge-agents) |
Workcells (forge-workcells) |
|---|---|---|
| Shape | Long-lived services (bots, orchestrator) | Bounded batch runners (WorkcellRequest → WorkcellResult) |
| Ingress | Matrix rooms, web UI, NATS bus | ForgeRun / harness / Fleet job argv |
| SoR | Projections only — Lenses owns ForgeRun | AgentRun records under a ForgeRun |
| Examples | communication, cursor_bridge, orchestrator |
local_llm_worker, fleet_ux_worker |
| Deploy | Fleet container-services on Granite | Fleet docker_argv or host CLI |
Channel agents do not replace workcells. ADR-0002 still applies: governed execution agents are bounded workcells. Channel agents are operator-facing gateways and lifecycle tooling.
Reading order
- forge-agents repo — monorepo layout, Granite deploy, boundaries
- Agent catalog — maintained agent id → package matrix
- Communication agent —
!commcommands, KB scope, 30-day store - Packaging agents —
agent.package.v1, Dockerfile templates - Orchestrator — registry, Matrix lifecycle, Fleet integration
Related platform docs
- Agent communication (Matrix guide) — operator setup for Matrix, Element, NATS
- Agents and workcells — ForgeRun, AgentRun, workcell catalog
- Ecosystem reference — repo topology including
forge-agents - ADR-0010 — channel agents monorepo decision
Contracts
| Schema | Purpose |
|---|---|
forge.agent_registry.v1 |
Orchestrator desired/actual agent state |
forge.communication_interaction.v1 |
Communication agent Q/A persistence |
forge.chat_intent.v1 |
Chat ingress (cursor_bridge) |
forge.agent_event.v1 |
Worker status events (cursor_bridge) |
PDCA program
Implementation phases A00–A14 are tracked in forge-agents PDCA prompts. Gate script: forge-agents/scripts/forge-agents-pdca/check-phase-gate.sh.
Documentation dual-wiki (fa)
Repo-local handbook (operator/system pairs, FA-* feature IDs) lives in forge-agents:
- Forge Agents handbook (fa) — start here for operator depth
- Dual wiki patterns — handbook pair (fa ↔ fp ↔ fpw) + documentation dual-wiki
- Feature index —
FA-COMM-001,FA-ORCH-001, …
fp (this section) carries governance, catalog, and contracts. fa carries runnable deploy detail and paired operator/system pages. Update both when behavior or boundaries change.