Amplifier skill forge

Amplifier + Forge: Terminal & Agent Orchestration

All commands below use the helper at tools/forge.py relative to this skill's directory (the folder containing this SKILL.md — resolve it first and export FORGE=<skill-dir>/tools/forge.py). It is stdlib-only python3; it talks to the forge daemon over HTTP, so it works even where forge's MCP tools are not connected.

For artifact-gated multi-agent work, also resolve RELAY=<skill-dir>/tools/relay.py. It maintains a private, resumable ledger and drives forge.py; use it instead of reconstructing relay state in chat.

Before the first Forge operation

Run doctor before creating or driving a Forge session. Skip it when only reading this skill's references or reviewing source files.

python3 "$FORGE" doctor  # starts daemon if down; auto-fixes node-pty spawn-helper exec bit

doctor may start a local daemon and write its MCP session cache under the user's cache directory. If Codex blocks localhost access or an out-of-workspace repair, request only the permission needed for that operation. Do not bypass the Codex sandbox globally.

Core loop: spawn → drive → observe → assert → teardown

SID=$(python3 "$FORGE" new --name myapp --cwd /repo --tag batch1) # sleep 2 before first cmd
python3 "$FORGE" run "$SID" "npm run dev" --wait 5      # type + enter + cleaned output
python3 "$FORGE" screen "$SID"                          # rendered viewport — TUIs
python3 "$FORGE" read "$SID"                            # incremental stream — logs
python3 "$FORGE" wait "$SID" "Ready in" --timeout 29000 # regex; exit 1 on timeout
python3 "$FORGE" grep "$SID" "error" --max 20           # single words only: ANSI can
                                                            # split phrases in the buffer
python3 "$FORGE" close "$SID"                            # or: close-tag batch1

Rules:

• wait timeouts are capped ~30s server-side — loop wait calls for longer waits.
• One-shot build/test commands: use exec (real exit code, auto-cleanup), not a session: python3 "$FORGE" exec "pytest -q" --cwd /repo --timeout 300000
• TUIs: drive with type + key (enter, escape, ctrl+c, up, down, tab...). key has a fixed list; other control chars via type raw bytes: "$(printf '\x11')".
• Fan-out: tag every session in a batch; give each parallel worker one session id; reap the whole batch with close-tag.

Orchestrating coding agents

Forge natively wraps Claude Code, Codex, and Gemini (interactive or one-shot, optional isolated git worktrees). OpenCode is driven as a generic PTY.

Inside Codex, prefer native subagents for ordinary parallel code work. Use Forge when the task specifically needs persistent PTYs, TUI interaction, cross-harness agents, isolated terminal sessions, or processes that must survive a turn. Loading this skill alone does not authorize delegation; follow the user's request and the active AGENTS.md delegation policy.

# Fire-and-collect (blocks up to --timeout, returns output + sessionId):
python3 "$FORGE" delegate claude "fix the failing test" --cwd /repo --model haiku
python3 "$FORGE" delegate codex "review this diff" --cwd /repo # permissions not explicit
python3 "$FORGE" codex-exec "fix the failing test" --cwd /repo --sandbox workspace-write
python3 "$FORGE" delegate claude "start refactor" --cwd /repo --mode interactive
AGENT_SID=SESSION_ID # copy sessionId from the JSON result above
python3 "$FORGE" delegate claude "now add tests" --session "$AGENT_SID" # follow-up

# Long-lived interactive agents (returns session id immediately):
SID=$(python3 "$FORGE" spawn-claude --cwd /repo --prompt "audit this repo" --tag agents)
python3 "$FORGE" submit "$SID" "focus on the auth module" # Claude: Escape+Enter
SID=$(python3 "$FORGE" new --cwd /repo --program "$(command -v codex)" \
  --arg=--sandbox --arg=workspace-write --tag agents) # explicit Codex permissions
python3 "$FORGE" history "$SID"                           # agent tool-call history

# Isolated parallel work: --worktree --branch feature/x  (per agent git worktree)
# OpenCode (generic PTY; headless run is simplest):
python3 "$FORGE" exec "opencode run 'explain this codebase'" --cwd /repo --timeout 300000

Gotchas (verified):

• Forge 0.9.0's native Codex wrappers do not expose Codex sandbox flags; the interactive wrapper has been observed launching in YOLO mode. Do not use those wrappers when the permission boundary matters. Use codex-exec, a generic PTY with literal --arg=--sandbox, or relay start ... --sandbox; reserve danger-full-access for an externally isolated environment.
• Inspect screen after spawning an interactive agent. First-run trust, auth, update, or hook-review gates can consume the initial prompt; resolve the gate and resubmit only when the prompt is absent.
• codex exec refuses to run outside a git repo (--skip-git-repo-check or use a repo cwd).
• Claude one-shot prompts: delegate is more reliable than screen-scraping spawn --one-shot.
• Idle/busy detection and full flag references: see references/driving-claude-code.md and references/driving-codex-opencode.md.

Coordinating a real multi-agent relay

When the user asks agents to work together, use artifact-gated handoffs rather than marker-only demos or independent fan-out. Read references/multi-agent-relay.md and follow its planner → implementer → reviewer → resolver → acceptor protocol.

Initialize the controller with the exact files and test command, then retain the printed state path across turns:

STATE=$(python3 "$RELAY" init --cwd /repo --tag ticket-123 --goal "build X" \
  --implementation-artifact src/x.py --implementation-artifact tests/test_x.py \
  --test-command "python3 -m unittest discover -s tests -v")
python3 "$RELAY" preflight --state "$STATE" --harness claude --harness codex
python3 "$RELAY" start planner --state "$STATE" --harness claude
python3 "$RELAY" send planner --state "$STATE"
python3 "$RELAY" wait planner --state "$STATE" --attempts 10
python3 "$RELAY" gate planner --state "$STATE"

Repeat start → send → wait → gate for each role and harness. Codex starts require an explicit --sandbox value; use workspace-write only for authorized implementation roles and read-only for review. Use status to resume after interruption, cost for provider charges, evidence for the final report, and close unless the user wants dashboard sessions left open. Inspect the initial and post-send screens; resolve first-run gates before continuing. Never advance when gate exits nonzero.

Use a shared Git workspace for sequential roles and isolated worktrees for concurrent editors. Advance only when all three gates pass: the expected file exists, the agent emitted its completion marker, and an independent command verified the artifact. Freeze specifications with a hash, pass raw files rather than summaries, require a written review verdict and resolution, and leave a final acceptance ledger. A timeout is an observation point, not permission to advance: inspect screen, then continue waiting or intervene explicitly.

Driving Amplifier

SID=$(python3 "$FORGE" new --name amp --cwd /project); sleep 2
python3 "$FORGE" type "$SID" "amplifier"; python3 "$FORGE" key "$SID" enter
# boot composes bundles: 1-3 min cold
for i in 1 2 3 4 5 6; do python3 "$FORGE" wait "$SID" "Amplifier Interactive Session" --timeout 29000 && break; done
python3 "$FORGE" type "$SID" "/status"; python3 "$FORGE" key "$SID" enter
python3 "$FORGE" wait "$SID" 'Turn: \$' --timeout 29000 # cost footer = turn complete
# Scriptable (two separate examples, not a pipe):
#   amplifier run --output-format json "prompt"
#   amplifier run --bundle ./bundle.md "smoke"

Watch costs: heavy bundles can reach 100k+ token system prompts (>$1/turn uncached; the footer prints per-turn and session cost). Multi-line input: Ctrl-J newline, Enter submits. Long-running processes (attractor pipelines, evaluation batches, resolve instances): poll their file ledgers (checkpoint.json, state.json, events.jsonl) with exec, not the screen.

Reference library (load on demand)

Topic	File
Amplifier CLI: install, run/continue/resume, sessions, bundles, settings, JSON output	references/using-amplifier.md
Building bundles/agents/skills/modes/tools, mount plans, conformance	references/building-with-amplifier.md
Condensed expert-verified builder reference (exact schemas + CLI)	references/expert-bundle-reference.md
Long-running loops: evaluation, attractor, resolve	references/long-running-processes.md
Superpowers workflow: brainstorm→plan→execute→verify→finish, debug	references/superpowers-lifecycle.md
Claude Code CLI: headless flags, TUI keys, state detection, sessions	references/driving-claude-code.md
Codex CLI + OpenCode: exec/run modes, TUI keys, auth, comparison table	references/driving-codex-opencode.md
Multi-agent coordination: shared-artifact relay, gates, review, resolution, acceptance	references/multi-agent-relay.md
Deep orchestration playbook: TUI testing method, failure modes, ledger babysitting	references/orchestration-playbook.md

Fresher ground truth for Amplifier lives in ~/.amplifier/cache/amplifier-foundation-*/docs/ and the in-app experts (amplifier:amplifier-expert, foundation:foundation-expert, core:core-expert).