forge

/forge — Evolutionary Multi-AI Code Forge (v2)

Three AI engines independently implement the same task, compete on automated fitness tests, then the best solution is refined through critique-based synthesis. Claude is a pure orchestrator — it dispatches, scores, and judges but never competes.

How to invoke

Direct forge — user specifies a focused task:

/forge "Add NaN guard to scoring" --fitness "npx jest"

Optional flags:

• --timeout SECS — override the safety cap (default: 600s from config key forge_timeout)
• --async — run in background, continue conversation
• --engines claude,codex — limit which engines compete (default: all available)
• --starter codex — override which engine runs first

Using forge inside existing planning workflows

/forge works as a tool within any plan — /build-guard, /plan-guarded, plan mode, or any task list.

The [forge] tag

When building a plan, Claude can tag tasks:

• [forge] — algorithmic, tricky, multiple valid approaches
• No tag or [direct] — straightforward, Claude handles normally

What to tag [forge]

• Algorithms, scoring logic, data transformations
• Race condition fixes, concurrency patterns
• Performance-critical code paths
• Anything with multiple valid approaches where three perspectives help

What NOT to tag [forge]

• Types, imports, config, UI layout, wiring
• Boilerplate, glue code — one obvious answer
• Anything without a runnable fitness test

---

Step-by-step workflow

Phase 0: Setup

1. Parse args. Extract the task, --fitness command, optional --timeout, --async, --engines, --starter.
2. Detect engines. Source lib.sh and use the dynamic registry:

source "${CLAUDE_PLUGIN_ROOT}/hooks/lib.sh"
AVAILABLE=$(ai_buddies_available_buddies)  # CSV: "claude,codex,gemini,aider,..."
FORGE_TIMEOUT=$(ai_buddies_forge_timeout)

Any registered buddy with an installed binary will participate.

1. Create forge directory:

FORGE_ID="$(date +%s)-${RANDOM}"
FORGE_DIR="/tmp/ai-buddies-${CLAUDE_SESSION_ID:-default}/forge-${FORGE_ID}"
mkdir -p "$FORGE_DIR"