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)

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;
   
   -- 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?"
6. For large codebase scans, prefer ctx_batch_execute to keep research results in sandbox.
7. MemPalace palace + KG recall (A). In the same message, spawn a parallel fan-out:
   • mempalace_search(query="<touched-systems keywords>", wing="<project slug>", limit=5) — semantic recall across code + docs + convos
   • mempalace_kg_query(entity="<system>") — one call per touched system for typed facts (deps, status, models, incidents)
   • 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 careful reading.
• External API/lib → fetch docs via context7 or WebSearch. Don't assume — verify.
• Spike anything testable in <5 minutes. One assumption per spike. Disposable.
  • Record: ✅ confirmed: [assumption] or ❌ refuted — actual: [reality]
  • Refuted spike = immediate adjustment. Never carry known-false assumptions.
• Spikes happen in ANY phase. If testable in <5 min → test it NOW.

CHALLENGE — challenge the approach BEFORE writing the plan

Self-challenge first: What am I assuming? What's the simplest approach? What breaks?

Then get an independent challenge on the APPROACH (not the plan yet — that comes at REVIEW):

• Check if codex is available: which codex
• If available: write approach summary to /tmp, run codex exec "Review this approach. What are the 3 most likely failure modes?" -C <repo> -s read-only -c 'model_reasoning_effort="high"'
• If unavailable: Agent(model="opus", prompt="You are a senior engineer who has NEVER seen this codebase. Here is the proposed approach: [approach]. Find the 3 most likely failure modes.")

If challenge reveals a fundamental flaw → revise approach before writing the plan.

CLARIFY — ask user only for genuine design decisions

• Classify unknowns: self-decidable vs needs user input.
• Self-decide where possible. Document decision + rationale in plan.
• Ask user ONLY for genuine design choices.
• Format: structured questions with 2-3 options + recommendation + reasoning.

Visionary stream question (ask at end of CLARIFY)

Adaptive default based on scope:

Visionary stream — search for a "significantly better" approach?
  a) skip        ← default if <3 files
  b) 1 pass      ← default if 3-10 files
  c) 3 passes    ← default if 10+ files
  d) N passes    (any number, no token limit)

Save choice to forges.context as visionary_mode. If --no-visionary flag, auto-select a.

Planner agent selection (v3 is default)

Before invoking the planner agent, select it inline from the

Content truncated.