Advanced Execution

Model routing, quorum mode, cost optimization, CI integration, and resume strategies.

Model Routing

Assign different models per role in .forge.json:

Same principle as a human team: let the junior do the legwork, the senior does the final check. Costs less, catches more.

{
  "modelRouting": {
    "default": "grok-4",
    "execute": "claude-sonnet-4.6",
    "review": "claude-opus-4.6"
  }
}

Use a fast/cheap model for execution and a more capable model for review. The orchestrator routes each slice to the appropriate model based on its role.

DIRECT_API_ONLY vs COPILOT_SERVABLE v2.81+

Models are split into two routing classes that determine how the orchestrator reaches them:

This split (Phase-34, fixes #103) means gpt-* models no longer drop from auto-quorum when OPENAI_API_KEY is unset but gh-copilot is installed. The old pattern conflated “requires direct API” with “routed via HTTP” and unfairly penalized Copilot users.

Escalation Chains

When a model fails a slice, the orchestrator automatically escalates to the next model in the chain:

{
  "escalationChain": ["grok-4", "claude-opus-4.6", "gpt-5.2-codex"]
}

Model A fails → Model B retries the same slice → Model C if B fails too. Emits slice-escalated WebSocket event at each step. No manual intervention required.

Quorum Mode

Multi-model consensus for complex slices. Multiple models analyze the same problem independently, then a reviewer synthesizes the best approach.

# Force quorum on all slices
pforge run-plan docs/plans/Phase-7.md --quorum

# Auto-quorum: only trigger for complex slices (threshold ≥ 6)
pforge run-plan docs/plans/Phase-7.md --quorum=auto

# Custom threshold (1-10, higher = fewer slices use quorum)
pforge run-plan docs/plans/Phase-7.md --quorum=auto --quorum-threshold 8

# Flagship preset (Opus + GPT-5.3-Codex + Grok 4.20, threshold 5)
pforge run-plan docs/plans/Phase-7.md --quorum=power

# Fast preset (Sonnet + GPT-5.4-mini + Grok 4.1 Fast, threshold 7)
pforge run-plan docs/plans/Phase-7.md --quorum=speed

Worked Example — 2× Copilot CLI + 1× Grok API v2.83+

The most common production setup: ride your Copilot subscription for the bulk of the quorum, add one direct-API leg (Grok or OpenAI) for diversity. Both kinds of leg run in the same Promise.all, no special config to "merge" them.

Step 1: declare the model mix in .forge.json:

{
  "quorum": {
    "models": [
      "gpt-5.3-codex",                  // → copilot CLI subprocess
      "claude-sonnet-4.6",              // → copilot CLI subprocess
      "grok-4.20-0309-reasoning"        // → direct-API worker (XAI_API_KEY)
    ],
    "reviewerModel": "claude-opus-4.7"  // → copilot CLI subprocess
  }
}

Step 2: provision the Grok key (one of):

# Option A: env var (per-shell)
$env:XAI_API_KEY = "xai-..."

# Option B: project-local secrets file (gitignored)
# .forge/secrets.json
{ "XAI_API_KEY": "xai-..." }

Step 3: run with quorum:

# See the projected cost across all four modes first (always tool-backed)
pforge run-plan --estimate docs/plans/Phase-7.md

# Then run, quorum-eligible slices fan out to all three models in parallel
pforge run-plan docs/plans/Phase-7.md --quorum=auto

What happens at slice dispatch:

• quorumDispatch sees three models in the config.
• spawnWorker is called three times concurrently. The first two route to the local copilot CLI (no key needed, rides your Copilot subscription); the third routes to the xAI HTTP worker using XAI_API_KEY.
• All three return their dry-run analyses. quorumReview synthesises them via the reviewer model into a single enhancedPrompt.
• The actual slice execution runs once with that synthesised prompt, not three concurrent edits.

If the Grok key is missing, filterQuorumModels drops Grok from the list at run-plan startup and the quorum proceeds with the two Copilot-served legs, no failure, just a smaller jury.

Quorum Mode vs Quorum Advisory — What's the Difference? v2.78+

Two surfaces use the word "quorum." They're related but operate at different scopes:

You can use both. Quorum Mode runs slice execution; Quorum Advisory helps you decide what to put in the slice in the first place.

Estimating Quorum Cost — forge_estimate_quorum v2.83+

forge_estimate_quorum projects the cost of a plan under all four quorum modes in one round-trip, no need to call --estimate four separate times. It returns per-mode totals plus a per-slice breakdown showing which slices cleared the threshold.

Calling the tool

// Direct MCP call
forge_estimate_quorum({
  planPath: "docs/plans/Phase-7.md",
  resumeFrom: 1   // optional, only estimate slices ≥ N
})

// CLI equivalent (runs all four modes under the hood)
pforge run-plan docs/plans/Phase-7.md --estimate --quorum-compare

Response shape

{
  "false":  { "totalCostUSD": 0.28, "baseCostUSD": 0.28, "overheadUSD": 0,
              "quorumSliceCount": 0, "totalSliceCount": 7, "confidence": "historical" },
  "auto":   { "totalCostUSD": 0.42, "baseCostUSD": 0.28, "overheadUSD": 0.14,
              "quorumSliceCount": 1, "totalSliceCount": 7, "confidence": "historical" },
  "power":  { "totalCostUSD": 12.50, "baseCostUSD": 0.42, "overheadUSD": 12.08,
              "quorumSliceCount": 3, "totalSliceCount": 7, "confidence": "historical" },
  "speed":  { "totalCostUSD": 1.20, "baseCostUSD": 0.31, "overheadUSD": 0.89,
              "quorumSliceCount": 1, "totalSliceCount": 7, "confidence": "historical" },
  "slices": [
    { "sliceNumber": 1, "complexityScore": 3, "projectedCostUSD": 0.04, "quorumEligible": false },
    { "sliceNumber": 2, "complexityScore": 6, "projectedCostUSD": 4.18, "quorumEligible": true  },
    { "sliceNumber": 3, "complexityScore": 7, "projectedCostUSD": 4.22, "quorumEligible": true  },
    ...
  ]
}

Worked cost example: 7-slice fixture plan

The numbers above come from the heuristic fixture used in capabilities.mjs, illustrative, not measured. For a typical mid-size plan (10–15 slices, 1–3 quorum-eligible), real-world numbers from the Plan Forge dogfood corpus look like:

Numbers are order-of-magnitude, actual cost depends on slice scope size, host (subscription-covered vs pay-per-token), and the cost-calibration ratio in .forge/cost-history.json. Always estimate before running.

Complexity Scoring Rubric — How a Slice Earns Its Score v2.83+

What makes a slice "complex enough to need quorum"? The orchestrator's scoreSliceComplexity() function (see orchestrator.mjs) reads seven weighted signals from the parsed slice and produces an integer 1–10. Modes then compare that score against their threshold to decide whether to fan out.

The seven signals

The raw weighted sum (0–1) is mapped to the final integer via clamp(1, 10, round(raw × 9) + 1).

Threshold mapping

Worked example

Consider a slice titled "Add JWT refresh-token rotation with Redis backing" with 4 scope files, depends on slices 2 and 5, 7 tasks, a 12-line validation gate, and 1 prior failure in 8 historical matches:

scope    = min(4/5, 1.0)   × 0.20 = 0.16
depends  = min(2/4, 1.0)   × 0.20 = 0.10
security = min(2/3, 1.0)   × 0.15 = 0.10   // "jwt", "token"
database = min(0/3, 1.0)   × 0.15 = 0.00
gate     = min(12/5, 1.0)  × 0.10 = 0.10
tasks    = min(7/10, 1.0)  × 0.10 = 0.07
history  = (1/8)           × 0.10 = 0.0125
                                    ──────
raw                              = 0.5425
score = clamp(1, 10, round(0.5425 × 9) + 1) = 6

→ clears threshold for: power (≥5), auto (≥6)
→ does NOT clear:        speed (≥7)

Multi-Agent Quorum Turns — PFORGE_QUORUM_TURN v2.78+

When quorum runs in multi-agent mode (Claude → Codex → Cursor handoffs), the orchestrator sets the PFORGE_QUORUM_TURN environment variable for the duration of each quorum-leg invocation. This is a coordination signal, not user-facing config, but it shows up in logs and matters when debugging hook behavior.

What the variable controls

Why skip context injection?

Quorum exists to get independent analyses from each model. If PreAgentHandoff injected the same drift / MTTR / open-incident context into every leg, the models would converge, defeating the whole point. The reviewer (the synthesizing model) does get the full handoff context when it merges the proposals, because that's where the project-wide state actually matters.

📄 Cross-references: Chapter 13 — Multi-Agent for the handoff model · Chapter 20 — Remote Bridge for the OpenClaw snapshot path · Forge-Master Quorum Advisory for the per-prompt counterpart.

Quorum Quality Examples — What 3 Models Catch That 1 Doesn't

The argument for quorum mode is mostly abstract, "synthesis effect," "independent analyses," "reviewer picks the cleaner approach." A single side-by-side run of the same task makes the argument concrete. The numbers below come from a controlled A/B run on a real C# invoicing slice: same plan, same gates, same acceptance criteria; one execution with the default single-model worker, one with three-model quorum. Both passed all gates and the independent reviewer. The difference is in how they passed.

$0.22 of additional spend, both pass review, and the quorum run is measurably more maintainable. Four named patterns drive the difference.

Pattern 1 — DRY helper extraction

The single-model run inlined volume-discount math in three call sites with slight variations. The quorum run extracted reusable helpers because the synthesizer saw multiple proposals and picked the one that didn't repeat itself.

// Single model, inlined at three call sites
var discount = quantity >= 100 ? 0.15m : quantity >= 50 ? 0.10m : quantity >= 10 ? 0.05m : 0m;

// Quorum, extracted helper
private static decimal CalculateVolumeDiscount(int quantity) => quantity switch
{
    >= 100 => 0.15m,
    >= 50  => 0.10m,
    >= 10  => 0.05m,
    _      => 0m,
};

Pattern 2 — Robust test dates

Single-model tests pinned dates to literal calendar days. Those tests will fail when those dates pass and the business logic correctly refuses future invoices. Quorum tests used relative offsets that stay green forever.

// Single model, breaks on April 16th
var invoice = new Invoice { Date = new DateTime(2026, 3, 15) };

// Quorum, stays green forever
var invoice = new Invoice { Date = DateTime.Now.AddDays(-7) };

Pattern 3 — Modern .NET patterns

Validation guard clauses are a tell. The control run used the generic exception path; the quorum run reached for the modern static-helper API that ships better error messages and is the current recommended pattern.

// Single model, generic, manual message
if (string.IsNullOrWhiteSpace(customerName))
    throw new ValidationException("Customer name is required");

// Quorum, modern .NET 7+ helper, auto-generated message including parameter name
ArgumentException.ThrowIfNullOrWhiteSpace(customerName);

Pattern 4 — Edge-case coverage the control missed entirely

The +3 tests in the quorum run weren't padding. They were edge cases the single model never wrote because no one model considered both the happy path and the failure mode at the same time. With three independent analyses, edge cases that one model thinks of get surfaced into the synthesis.

The synthesis mechanism

The pattern across all four examples is the same: one model proposes one thing, another model proposes a cleaner version, the reviewer picks the cleaner one. Inline code vs extracted helper, extraction wins. Hardcoded date vs relative offset, relative offset wins. Generic exception vs modern helper, modern helper wins. Standard tests vs edge-case tests, edge-case tests win. The quorum doesn't make any individual model smarter; it makes the worst-case output of each model less likely to be what ships.

When this pays off

--quorum=auto applies this judgment per slice using the complexity scoring rubric. Manual --quorum=power and --quorum=speed let you force the call when you already know which slices are which. The discovery harness uses single-model dispatch by default because audit findings are mechanical; the auto-smelt loop is the place to catch defects, not the discovery pass.

📄 Source: Quorum Mode — What 3 Models Catch That 1 Doesn't on the Plan Forge blog (the controlled A/B run that produced this comparison).

Host-Aware Routing v2.82+

Plan Forge runs in different IDEs and CLI hosts (VS Code + Copilot, Claude Code, Cursor, Windsurf, Zed, the bare CLI). Each host has its own billing surface. The host-aware routing preference (added v2.82, fixes #104) ensures users on non-Copilot hosts don't silently double-pay against subscriptions they're already paying for.

The four modes

Configuration

{
  "routing": {
    "hostPreference": "auto"   // "auto" \| "gh-copilot" \| "direct-api" \| "drop"
  }
}

Pre-run summary table

Before any model fires in quorum mode, the orchestrator emits a per-model billing surface table to stdout:

Quorum Pre-Run Summary (host: claude-code, preference: auto)
  ✓ claude-opus-4.7   → anthropic-direct      ($0.0061/req)
  ✓ gpt-5.3-codex     → openai-direct         ($0.0048/req)
  ⚠ grok-4.20         → xai-direct            ($0.0033/req)  needs XAI_API_KEY
  ✓ claude-sonnet-4.6 → anthropic-direct      ($0.0019/req)

Per-slice telemetry now records host, billingSurface, and billingWarning in slice-N.json so cost aggregation can distinguish subscription-covered vs pay-per-token spend in the Cost Report.

Cost Optimization

The orchestrator tracks model performance in .forge/model-performance.json, success rate, average cost, and duration per model. It auto-selects the cheapest model with >80% historical pass rate.

• Preview costs: pforge run-plan --estimate docs/plans/Phase-7.md
• Review spend: pforge cost or Dashboard Cost tab
• Agent-per-slice routing: Override model per slice with --model flag
• Reduce context: Use targeted Context: lists per slice (see Chapter 4)

API Key Configuration

API keys for external providers (xAI Grok, OpenAI) are resolved in order: environment variable → .forge/secrets.json → null.

For local development, store keys in the gitignored .forge/secrets.json:

{
  "XAI_API_KEY": "xai-...",
  "OPENAI_API_KEY": "sk-..."
}

The .forge/ directory is in .gitignore by default, secrets are never committed.

CI Integration

Add Plan Forge validation to your GitHub Actions PR workflow:

- uses: srnichols/plan-forge-validate@v1
  with:
    analyze: true          # Run consistency scoring
    sweep: true            # Check for TODO/FIXME markers
    threshold: 60          # Minimum analyze score to pass

PRs that fail the threshold are blocked from merging. The action validates file counts, checks for unresolved placeholders, and runs pforge analyze.

Cloud Agent Execution

GitHub's Copilot cloud agent works on issues autonomously. Plan Forge integrates via .github/copilot-setup-steps.yml, which provisions the agent with Node.js, guardrails, MCP tools, and smith verification before it starts coding.

Parallel Execution

The orchestrator builds a DAG from [P] tags and [depends: Slice N] declarations. Independent slices run concurrently when workers are available. Merge checkpoints validate that all parallel branches resolved cleanly.

Resume and Retry

# Resume from slice 3 after fixing a failure
pforge run-plan docs/plans/Phase-7.md --resume-from 3

# Dry run, parse and validate without executing
pforge run-plan docs/plans/Phase-7.md --dry-run

When a gate fails, fix the issue manually, then resume. Completed slices are skipped, only remaining slices execute.

OpenBrain Memory

The OpenBrain integration bridges the 4-session pipeline with long-term, cross-session context. Prior decisions, patterns, and postmortems are automatically searched and injected at the start of each session. After every run, lessons are captured for future phases.

As of v3.6, OpenBrain is the documented L3 memory layer, still optional, but loud and easy to enable. Check status with pforge brain status; see install options with pforge brain hint. Plan Forge works without it; the inner loop (Reflexion, Auto-skills, Federation) only improves over time with it. See Project History → v3.6.

Install via extension: pforge ext add plan-forge-memory

LiveGuard Lifecycle Hooks

Three hooks fire automatically during agent sessions to enforce operational safety:

Configure in .forge.json:

{
  "hooks": {
    "preDeploy": { "blockOnSecrets": true, "warnOnEnvGaps": true, "scanSince": "HEAD~1" },
    "postSlice": { "silentDeltaThreshold": 5, "warnDeltaThreshold": 10, "scoreFloor": 70 },
    "preAgentHandoff": { "injectContext": true, "cacheMaxAgeMinutes": 30, "minAlertSeverity": "medium" }
  }
}

See Chapter 16 — What Is LiveGuard? for the full operational intelligence overview.

📄 Full reference: capabilities, CLI Reference — run-plan