Forge Platform

Handbook

Communication agent

The communication package (packages/communication/) is a deterministic knowledge-base agent for operator questions about Forge products. It answers from an indexed corpus — not unconstrained generative chat.

Updated

Autonomy ceiling: A0_assisted — citations required; no outbound messages without an explicit inbound command.

Matrix commands (!comm)

The bot listens in #communication (and other operator-invited, unencrypted rooms). Commands use the !comm prefix:

Command Purpose
!comm help List commands and usage
!comm topics Show indexed topic areas
!comm ask <question> Route question to KB; response includes citations
!comm cite <topic> Return source references for a topic
!comm policy Show autonomy, retention, and scope boundaries

Rooms must remain unencrypted so the bot can read messages. Do not bridge #communication to WhatsApp or other relays.

Knowledge base scope

The KB corpus covers three handbook families:

Family Source repos Examples
Forge Intelligence forge-intelligence Problem-class packs, session dual-wiki
Forge Platform forge-platform Schemas, ADRs, workcell glossary
Blueprints blueprints SDLC policy, ceremonies, templates

Sources are landed in repo paths under packages/communication/knowledge/ and rebuilt by build_index. The KB does not treat chat threads as source of truth.

Routing uses confidence bands:

  • High — direct citation from one or more indexed chunks
  • Medium — best-effort match with explicit uncertainty note
  • Low — refuse with !comm topics pointer (no hallucinated policy)

Every !comm ask response includes citations (handbook path or schema id).

Interaction store (30 days)

Inbound commands and outbound replies persist to a SQLite store (forge.communication_interaction.v1 records):

  • Retention: 30-day rolling purge (mandatory unless ADR override)
  • Export: JSON/CSV stub for future analytics — no dashboard in MVP
  • Boundary: store is read-only for automation — stored interactions do not trigger outbound actions

Schema: communication_interaction.v1.schema.json.

Deploy

On Granite, the communication agent runs as a Fleet container-service registered by the orchestrator. Bootstrap #communication via forge-matrix room scripts.

Local dev:

cd forge-agents
.venv/bin/pip install -e packages/communication
.venv/bin/python -m forge_communication.kb.index --build