forge

The Forge — multi-agent demo

A four-agent engineering team that lives inside Optio as Persistent Agents and coordinates by passing messages.

Slug	Name	Role
vesper	Vesper	Architect — receives feature requests, breaks them into specs, dispatches
forge	Forge	Implementer — receives specs, drafts code, reports back to Vesper
sentinel	Sentinel	Reviewer — receives PR-opened messages, runs review, posts findings
chronicler	Chronicler	Scribe — listens to broadcasts, maintains a running team journal

How it works

1. You message Vesper with a feature request via the chat in /agents/vesper.
2. Vesper decomposes it into one or more spec messages and sends them to Forge.
3. Forge drafts the implementation (just code in this demo — no real PR yet) and sends a "PR opened" message back to Vesper and a broadcast to the team.
4. Sentinel hears the broadcast, reviews the proposal, and sends comments back to Forge.
5. Chronicler hears every broadcast and appends an entry to the team journal, which it returns when anyone messages it journal.

This shows off three messaging patterns from the Scion / Athenaeum playbook: direct messages (Vesper → Forge), broadcasts (Forge → all), and file-based handoff (Chronicler → journal).

Setup

Requires a running Optio API (default http://localhost:30400). See ../../README.md for setup-local.sh.

# Default API base — override with $OPTIO_API_URL
./demos/the-forge/setup.sh

The script creates all four agents in your current workspace, idempotent (re-runs are safe — slug uniqueness is enforced server-side).

Try it

1. Open /agents — you should see all four.
2. Open /agents/vesper, send a message: Add a /healthz endpoint to the api server that returns OK.
3. Watch the activity feed — Vesper drafts a spec and sends it to Forge.
4. Open /agents/forge to see the spec arrive in its inbox and the work it does.
5. Open /agents/chronicler to see the journal grow.

Cleanup

for slug in vesper forge sentinel chronicler; do
  id=$(curl -s "$OPTIO_API_URL/api/persistent-agents" \
        | jq -r ".agents[] | select(.slug==\"$slug\") | .id")
  [ -n "$id" ] && curl -s -X DELETE "$OPTIO_API_URL/api/persistent-agents/$id"
done