/forge

name: forge
description: "Ore in, steel out. Planning pipeline with independent verification, persistent memory, and compounding knowledge. Use for 3+ files or unclear scope."

Forge — Ore In, Steel Out

Two machines: **Plan Forge** (refine until bulletproof) + **Verification Chain** (prove it's actually done). Ralph provides persistence.

When to Use

• Task touches 3+ files or has unclear scope
• Architecture decisions needed
• User says "forge", "forge plan", or task needs verified planning
• Previous attempt failed — need to reassess

Scaling

Quick fix (<3 files, clear)    → skip forge, direct executor + MICRO-VERIFY
Standard (3-10 files)          → PLAN FORGE → EXECUTE → VERIFICATION CHAIN
Complex (10+, architectural)   → PLAN FORGE --full → EXECUTE with checkpoints → CHAIN
Vague input                    → PLAN FORGE --discuss → rest as standard

State

Use `mode: "ralph"` with session_id. Phase prefix `bf-` distinguishes from plain ralph.

{"mode":"ralph","session_id":"<session>","current_phase":"bf-forge|bf-execute|bf-verify",
 "state":{"planning_mode":"forge","forge_iteration":1,
  "gates":{"skeptic":null,"integration":null,"second_opinion":null},
  "verify":{"evidence":null,"auditor":null},
  "completed_steps":[],"slug":"task-name"}}

HUD Integration

Forge writes status to **two channels** on every phase transition:

1. Statusline (via `state_write`)

Shows `ralph:N/M` in the terminal statusbar. N = current forge iteration, M = max (default 5).

Call `state_write` at each phase transition:

state_write(
  mode: "ralph",
  active: true,
  iteration: <forge_iteration>,
  max_iterations: <total_phases>,
  current_phase: "bf-<phase>",
  task_description: "<slug>",
  session_id: <session_id>,
  state: {
    planning_mode: "forge",
    gates: { skeptic: "PASS"|"FAIL"|null, integration: ..., second_opinion: ... },
    steps_done: N,
    steps_total: M
  }
)

2. Rich status (via `notepad_write_priority`)

Shows detailed progress in notepad (visible via `notepad_read`). Update at each transition:

notepad_write_priority(
  content: "[FORGE] <PHASE> v<iter> | <gate_summary> | <steps_done>/<steps_total> steps"
)

**Examples at each stage:**

[FORGE] PRECEDENT          | — | 0/8 stages
[FORGE] RESEARCH           | — | 1/8 stages
[FORGE] CHALLENGE          | — | 2/8 stages
[FORGE] PLAN v1            | — | 3/8 stages
[FORGE] REVIEW v1          | Skeptic:PASS Integration:— 2nd:— | 3/8 stages
[FORGE] REVIEW v1          | Skeptic:PASS Integration:PASS 2nd:FAIL | 3/8 stages
[FORGE] PLAN v2            | ↑ revising: 2nd opinion found P1 issue | 3/8 stages
[FORGE] REVIEW v2          | Skeptic:PASS Integration:PASS 2nd:PASS | 3/8 stages
[FORGE] EXECUTE            | ALL GATES PASSED | 5/7 steps done | 5/8 stages
[FORGE] VERIFY             | Evidence:— Auditor:— | 6/8 stages
[FORGE] VERIFY             | Evidence:PASS Auditor:PASS | 7/8 stages
[FORGE] DOCS-REFRESH       | VERIFIED | 8/8 stages

Phase map (for progress tracking)

| # | Phase | Description | |---|-------|-------------| | 1 | PRECEDENT | Search institutional knowledge | | 2 | RESEARCH | Read files, spike assumptions (top-3 mandatory) | | 3 | CHALLENGE | Independent review of approach | | 4 | CLARIFY | User questions + visionary mode selection | | 5 | PLAN-DRAFT | Write plan with typed claims | | 6 | VISIONARY | N parallel passes (optional) | | 7 | COMPARATOR | 3-tier classify + reality-check (if visionary ran) | | 8 | USER-DECIDE | Pick standard / visionary / merge | | 9 | PLAN-FINAL | Rewrite plan per decision | | 10 | REVIEW | Sealed blind parallel + stacked meta | | 11 | EXECUTE | Cascade gemini->opus, TDD | | 12 | VERIFY | Evidence + Auditor | | 13 | DOCS-REFRESH | Docs + DB sweep |

For the statusline `max_iterations`: use forge iteration cap (default 5) during PLAN/REVIEW loop. Switch to `13` (total stages) during EXECUTE onward.

On completion/failure

state_write(mode: "ralph", active: false, completed_at: <ISO>)
notepad_write_priority(content: "[FORGE] DONE ✓ | <slug> | <total_time>")
mempalace_diary_write(
  agent_name: "claude-code",
  topic: "forge-<slug>",
  entry: "FORGE:<slug>|iters:N|gates:PASS|spikes:M|drawers:K|lesson:<AAAK summary>"
)

On failure:

notepad_write_priority(content: "[FORGE] BLOCKED | <slug> | <reason>")

**Non-blocking diary guarantee (D):** `mempalace_diary_write` failure (timeout, MCP error, palace unavailable) MUST NOT block forge completion. Per the A runtime degradation contract: catch the failure, log `[palace-degraded] diary_write failed: <reason>` to notepad, mark forge completed in `forge.db` regardless. Forge completion is the source of truth; the diary entry is a secondary write.

---

Machine 1: Plan Forge

Refinement loop. Two phases: draft the plan, then gate it. Cycles until all 3 gates pass.

PRECEDENT → RESEARCH (+top-3 mandatory spikes) → CHALLENGE → CLARIFY (+visionary?) →
  PLAN-DRAFT (typed claims) → [VISIONARY STREAM] → [COMPARATOR] → USER DECISION →
  PLAN-FINAL → REVIEW (blind parallel + stacked meta) →
  EXECUTE (cascade: gemini→opus) → VERIFY → DOCS-REFRESH (+DB sweep)

PRECEDENT — search institutional knowledge first

Before touching code, search what the project already knows: 1. **Grep CLAUDE.md** for gotchas mentioning touched files/systems. Surface them explicitly. 2. **Grep `.omc/plans/`** (if exists) for past plans touching same systems. Note approach + outcome. 3. **Read `docs/architecture/{system}.md`** (if exists) to understand current design. 4. **Read CLAUDE.md `## Common Failures`** section (if exists) for known failure patterns. 5. **Query `.omc/forge.db`** (if exists) — past forge runs, risk scores, cached spikes:

   -- Past runs on these systems
   SELECT slug, status, iteration, json_extract(context, '$.lesson') as lesson
   FROM forges WHERE systems LIKE '%<system>%' AND status IN ('completed','abandoned')
   ORDER BY completed_at DESC LIMIT 5;