Handbook

forge-agents repository

Remote: git@github.com:autowww/forge-agents.git (private)

Updated 2026-07-26

forge-agents is the execution monorepo for channel agents, packaging templates, and the Fleet-hosted orchestrator. Platform owns contracts and handbook; this repo owns runnable code.

Documentation dual-wiki

Surface	Location	Role
fa (repo)	`forge-agents/docs/`	Operator/system handbook pairs (`FA-*` IDs), deploy runbooks
fp (platform)	`docs/agents/` (this tree)	Governance hub, catalog, schemas, ADR-0010
fpw	`forge-platform-website`	Published HTML

Start in fa: docs/index.md. Patterns: DUAL-WIKI.md. Gate: forge-agents/scripts/check-dual-wiki.sh (also run from PDCA A14).

Monorepo layout

forge-agents/
├── pyproject.toml              # workspace root; dev extras
├── packages/
│   ├── communication/          # !comm KB agent + 30d store
│   ├── cursor_bridge/          # Matrix adapter + Cursor CLI worker (ex forge-cursor-bridge)
│   └── packaging/              # agent.package.v1 manifest + Dockerfile templates
├── orchestrator/               # registry API, Matrix admin, Fleet lifecycle, web UI
├── shared/envelopes/           # chat_intent, agent_event, interaction (A11)
├── scripts/
│   ├── forge-agents-pdca/      # gate runner + SEQUENCE.yaml
│   └── install-granite.sh      # Granite production install
└── docs/deploy/
    └── granite-runbook.md      # Caddy/FAEP, secrets, rollback

Packages

Package	CLI entry	Role
`communication`	`forge-communication`	KB index, Matrix `!comm` bot, interaction store
`cursor_bridge`	`forge-cursor-bridge`	`!agent` Matrix commands, Cursor SDK worker, NATS transport
`packaging`	`forge-agents package`	Build agent images from `agent.package.v1` manifests
`orchestrator`	`forge-agents-orchestrator`	Registry, register/deregister, Fleet bridge, `/api/chat`

Quick start

python3 -m venv .venv
.venv/bin/pip install -e packages/communication -e packages/packaging \
  -e orchestrator -e 'packages/cursor_bridge[dev]' -e '.[dev]'
python3 -m pytest -q
./scripts/forge-agents-pdca/check-phase-gate.sh all

Granite deploy

Production path on Granite (Precision host):

./scripts/install-granite.sh — orchestrator service + agent containers
Follow docs/deploy/granite-runbook.md — Caddy/FAEP routes, secrets, rollback
Bootstrap Matrix rooms (#communication, #cursor, #ops) via forge-matrix
Smoke: register communication bot → Element !comm ask → store row → web UI chat

Orchestrator integrates with existing Fleet (docker_argv + container-services) — no parallel job plane.

Boundaries

Repo	Relationship
forge-platform	Schemas, ADRs, handbook (`docs/agents/`). Products must not submodule platform.
forge-workcells	Batch runners (`local_llm_worker`, …). Not migrated into forge-agents.
forge-lenses	ForgeRun SoR. Orchestrator emits projections only.
forge-fleet	Execution plane. Orchestrator POSTs jobs; Fleet never writes final ForgeRun decision.
forge-matrix	Synapse, Element, NATS compose on Granite.
forge-cursor-bridge	Deprecated — migrated to `packages/cursor_bridge/` (redirect README in old repo).

Forge Platform