oc-agent-forge

# Agent Forge

**On first invocation, read `references/orchestrator.md` and follow its welcome protocol** (if present; otherwise fall back to the shared `skills/orchestrator.md`).

Tri-agent build harness for Claude Agent SDK apps: the **Planner** decides the
agent topology (single-agent vs orchestrator-worker vs pipeline vs hierarchical),
the tool budget, and the harness loop shape → the **Builder** materialises the
harness, tool allowlist, and termination logic against the Claude Agent SDK → the
**Evaluator** runs the agent against a task fixture suite with isolated context and
gates it on task-success / trajectory / tool-efficiency thresholds.

An agent is not "give the model some tools and a while-loop." Every default — how
many subagents, which tools are in the allowlist, when the loop stops, how much
context is carried turn-to-turn — moves a measurable number: task success, token
cost, tool-call count, or wall-clock latency. The only honest way to set those
defaults is to run the agent against fixtures and score the trajectory. This skill
exists to make the agent harness an *evaluated* artifact, not a vibe.

This is the agent-harness counterpart to `oc-claude-api`. **Model routing — which
model runs the orchestrator, which runs a worker, effort levels, prompt caching,
thinking mode — comes FROM `oc-claude-api`.** Agent Forge owns the layer above the
model: topology, tool budget, loop shape, and the eval. The two skills compose;
they do not overlap.

---

## /oc-agent — Command Reference

```
AGENT FORGE COMMANDS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  TRI-AGENT HARNESS
  /oc-agent              Design + build an agent end-to-end (Planner → Builder → Evaluator)
  /oc-agent plan         Pick topology, tool budget, loop shape (Planner)
  /oc-agent build        Materialise the harness + tool allowlist (Builder)
  /oc-agent eval         Score the agent against a task fixture suite (Evaluator)

  HARNESS DESIGN
  /oc-agent topology     Choose single-agent / orchestrator-worker / pipeline / hierarchical
  /oc-agent tools        Design the tool allowlist + call ceilings + deferred-load
  /oc-agent loop         Design / tune the harness loop (react / plan-execute / reflect)

  EVALUATION
  /oc-agent fixtures     Build or extend the task fixture suite (input → expected outcome)
  /oc-agent trace        Replay one fixture and dump the full trajectory (debug)
  /oc-agent regress      Re-run the fixture suite and gate on success/cost regression

  UTILITIES
  /checkpoint            Show checkpoint status

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Type any command to begin. /oc-agent to see this again.
```

---

## Tri-Agent Architecture

```
AGENT INTENT
(from oc-app-architect: "this app needs an agent / does multi-step work / uses tools")
        │
        ▼
┌──────────────────┐
│   AGENT          │  Picks topology (single / orchestrator-worker / pipeline /
│   PLANNER        │  hierarchical), tool budget (allowlist + ceilings), loop
│                  │  shape (react / plan-execute / reflect). Declares targets.
└────────┬─────────┘   Pulls model routing from oc-claude-api.
         │
         ▼
┌──────────────────────────────────────────────┐
│       AGENT LOOP (per harness / config)      │
│                                              │
│  ┌────────────┐  config     ┌─────────────┐  │
│  │   AGENT    │◄─negotiate──►│   AGENT     │  │
│  │  BUILDER   │             │  EVALUATOR  │  │
│  │            │──harness───►│             │  │
│  │  Builds    │             │  Runs the   │  │
│  │  loop +    │             │  fixture    │  │
│  │  tools +   │◄──failures──│  suite,     │  │
│  │  topology  │             │  scores     │  │
│  └────────────┘             └─────────────┘  │
│       │                           │          │
│       │  Task-success ≥ target?   │          │
│       └───────────────────────────┘          │
└──────────────────────────────────────────────┘
         │
         └──► Regression gating (ongoing, in CI)
```

### Why Three Agents for an Agent?

1. **Self-graded agents always pass.** Whoever builds the harness picks the
   topology, the tool list, and the stop condition — then watches it complete one
   happy-path task and calls it done. The Evaluator runs a *fixture suite* (input →
   known-correct outcome) with isolated context and reports task-success rate,
   trajectory validity, and tool-efficiency. "It worked when I tried it" is not a
   measurement. See `references/agent-eval.md`.

2. **A working trajectory hides an expensive one.** An agent can reach the right
   answer via 40 tool calls, three redundant subagents, and a context window that
   compacts twice — and a success-only metric calls that a pass. Token cost,
   tool-call count, and step count are first-class metrics, because the difference
   between a shippable agent and an unshippable one is usually cost and latency, not
   correctness.

3. **Every knob is a tradeoff with no obvious default.** More subagents raise
   parallelism but multiply token cost and add coordination failure modes; a larger
   tool allowlist raises capability but bloats the context and slows tool selection;
   a reflect loop raises quality but doubles latency. The only honest way to set
   these is to move one knob, re-run the fixtures, and keep the change if the metric
   improved. That is the Builder ↔ Evaluator loop.

---

## Phase 1: Agent Planner (`/oc-agent plan`)

### Planner Persona

The Planner is an agent engineer who has shipped production agents and has the
scars to prove that the simplest topology that works is almost always right. Key
behaviors:

- **Start at the simplest tier and earn every escalation.** A single agent with a
  tight tool loop handles most tasks. Reach for orchestrator-worker only when the
  task genuinely fans out into independent subtasks; reach for a pipeline only when
  the stages are fixed and ordered; reach for hierarchical only when subtasks
  themselves decompose. Each added subagent is a