forge

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:

```sql -- 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;

-- Risk scores SELECT system, fail_rate, avg_iterations FROM system_risk WHERE system IN ('<system1>', '<system2>');

-- Cached spikes (don't re-test confirmed assumptions) SELECT assumption, result, actual FROM spikes WHERE permanent = 1 OR tested_at > datetime('now', '-30 days');

-- Co-failure warnings SELECT system_a, system_b, gate, ROUND(1.0 * fail_count / total_count, 2) as fail_rate FROM co_failures WHERE (system_a IN ('<systems>') OR system_b IN ('<systems>')) AND CAST(fail_count AS REAL) / total_count > 0.3; ``` Surface: "reply-worker + engage-scheduler fail Integration 60% — include both in scope?"

1. For large codebase scans, prefer ctx_batch_execute to keep research results in sandbox.
2. MemPalace palace + KG recall (A). In the same message, spawn a parallel fan-out:
3. mempalace_search(query="<touched-systems keywords>", wing="<project slug>", limit=5) — semantic recall across code + docs + convos
4. mempalace_kg_query(entity="<system>") — one call per touched system for typed facts (deps, status, models, incidents)
5. mempalace_diary_read(agent_name="claude-code", last_n=3) — recent agent diary entries for cross-session context

Summarize results into a ## Prior institutional context section that is prepended to PLAN-DRAFT. Runtime degradation contract: each palace call has a 10s soft timeout. On timeout, error, or MCP-unavailable, log one line via notepad_write_priority prefixed [palace-degraded] <call> failed: <reason>, skip the failing call, and continue PRECEDENT with file-based sources only. NEVER block or retry-loop on a palace call — forge must remain forward-progressable when MCP is flaky. The same contract applies to every palace call mentioned elsewhere in this skill (Skeptic kg_query, draft commits, completion diary_write, spike mirror). If the --no-mempalace flag is set, skip steps 7 entirely.

RESEARCH — verify everything, assume nothing

• Read EVERY file being touched. Grep ALL usages: calls, type refs, imports, re-exports, barrel files, mocks, string references.
• scc --by-file <dirs> (if installed) — flag high-complexity files for ca