.forge.json Reference

Every settable key in the per-project Plan Forge configuration file, type, default, example, and what changes when the value is touched. The canonical source of truth for this reference is CONFIG_SCHEMA in pforge-mcp/capabilities.mjs; this appendix mirrors that schema in human-readable form.

Orientation

The file lives at the repo root as .forge.json. It is read at startup by the orchestrator, the dashboard, and most MCP tools. The schema is intentionally shallow at the top and grouped by subsystem, each top-level key controls one slice of Plan Forge behavior:

The next sections describe each group in detail. Every field row uses the same five columns, Key, Type, Default, Example, Change impact, so the table reads the same way no matter which subsystem you land on.

Project identity

Four fields tell Plan Forge what kind of project it is looking at. projectName is the most important one, it scopes memory in OpenBrain (so two projects with the same plan name do not collide) and is the default project tag for traces and replay.

updateSource — how pforge update finds the framework

Controls where the pforge update command pulls framework files from. Defaults to auto, which picks the newer of a local sibling clone (if present) and the latest GitHub tag. See Appendix G — Update Source Modes for the full mode-selection story; this entry is the bare schema reference.

meta — meta-defect routing

Where Plan Forge files bugs against itself. When forge_meta_bug_file runs without an explicit target, it reads meta.selfRepairRepo. If the key is missing, it falls back to srnichols/plan-forge.

agents — multi-agent adapters

Which AI agents have native config files generated alongside the GitHub Copilot defaults. See Chapter 13 — Multi-Agent Setup for what each adapter writes.

modelRouting — default model selection

Where slices go by default when no plan-level Model: directive is present. default is the catch-all; execute and review override it for those phases. See Advanced Execution — Model Routing for the routing precedence (plan front-matter > flag > execute/review > default).

forgeMaster — Forge-Master reasoning loop

Configuration for the Forge-Master intent-routing layer. The routerModel is the small, cheap model that classifies intent; reasoningModel is the heavier model that synthesises the answer.

forgeMaster.observer

v3.8+ — Background hub subscriber that batches live Plan Forge events and narrates notable patterns. Mute-by-default: enabled must be explicitly set to true. Control via forge_master_observe MCP tool or pforge master observe CLI. Observer is strictly read-only; it cannot invoke write tools or create PRs.

forgeMaster.auditor

v3.8+ — Configuration for the A4 plan-health-auditor auto-invocation. The auditor is triggered via hooks.postRun.invokeAuditor. Tokens are attributed to a separate forge-master cost entry; the parent run's budget is never charged.

Execution limits

Three numeric caps the orchestrator enforces during pforge run-plan.

quorum — multi-model consensus

Configuration for quorum mode. Master switch is enabled; with auto: true the orchestrator only quorums slices whose complexity score crosses threshold. See Advanced Execution — Quorum Mode for the scoring rubric and worked examples, and Complexity Scoring Rubric for the seven signals that drive the score. The CLI --quorum= flag accepts values from the QUORUM_MODES array in pforge-mcp/enums.mjs.

extensions — installed extensions

Names of extensions installed via pforge ext add <name>. Managed by the CLI; rarely edited by hand. See Chapter 12 — Extensions.

hooks — LiveGuard lifecycle hooks

Five hook configurations live under this object: preDeploy (before deploy slices), postSlice (after every slice), preAgentHandoff (multi-agent turn), preCommit (ordered commit-time guard chain), and postRun (after a run completes — auditor auto-invoke). Each section is independent; omit any subsection to accept its defaults.

For the full eight-hook picture, including the Copilot session hooks (SessionStart, PreToolUse, PostToolUse, Stop) configured separately in .github/hooks/plan-forge.json and the PreCommit chain runner, see Customization — Lifecycle Hooks Reference.

hooks.preDeploy

hooks.postSlice

hooks.preAgentHandoff

hooks.preCommit.chain[]

Ordered commit-time validation chain executed by .github/hooks/PreCommit.mjs during pforge run-plan. The built-in entries are master-branch-reject first and diff-classify second; the first non-zero exit stops the commit.

hooks.postRun.invokeAuditor

v3.8+ — Automatically invoke the A4 plan-health-auditor after a run completes. Two trigger modes: fire on every failure (onFailure), or fire periodically after N runs (everyNRuns). Both are off by default. When both conditions fire on the same run, the auditor is invoked exactly once.

The auditor is spawned as its own Forge-Master process so its token costs land in forge_cost_report under the forge-master source. Use forge_testbed_findings to query any defects the auditor surfaces. For the full auditor configuration (model tier, output path), see forgeMaster.auditor.

openclaw — OpenClaw analytics bridge (optional)

Optional outbound POST on every PreAgentHandoff. Configures the analytics ingest endpoint. Leave unset to disable.

runtime — inner-loop subsystems

Opt-in subsystems added by Phase-25. Both default to off or advisory; existing users see no behavior change without explicit configuration.

runtime.gateSynthesis

L6, adaptive gate synthesis from Tempering minima. Suggest-only by default; the orchestrator never mutates plans.

runtime.reviewer

L4, opt-in speed-quorum reviewer that scores slice diffs inside brain.gate-check. Advisory-only by default.

brain — memory and federation

OpenBrain federation configuration. Off by default; opt-in via brain.federation.enabled.

testbed — testbed path

Where the reference testbed repo lives. Required for the forge_testbed_* tools and the --testbedPath override.

Full annotated example

A realistic .forge.json for a TypeScript project that has opted into Claude as a secondary agent, runs quorum on high-complexity slices, and uses OpenBrain federation to read from a sibling repo:

{
  "projectName": "myapp",
  "preset": "typescript",
  "templateVersion": "2.56.0",
  "updateSource": "auto",

  "agents": ["claude"],

  "modelRouting": {
    "default": "auto",
    "execute": "gpt-5.3-codex",
    "review": "claude-opus-4.7"
  },

  "forgeMaster": {
    "reasoningModel": "gpt-4o-mini",
    "reasoningProvider": "githubCopilot",
    "routerModel": "gpt-4o-mini",
    "defaultProvider": "githubCopilot",
    "observer": {
      "enabled": false,
      "maxUsdPerDay": 0.10,
      "maxNarrationsPerHour": 6,
      "batchWindowMs": 60000,
      "modelTier": null
    },
    "auditor": {
      "modelTier": null,
      "outputPath": ".forge/health/latest.md"
    }
  },

  "maxParallelism": 3,
  "maxRetries": 1,
  "maxRunHistory": 50,

  "quorum": {
    "enabled": true,
    "auto": true,
    "threshold": 6,
    "models": ["claude-opus-4.7", "gpt-5.3-codex", "gemini-3.1-pro"],
    "reviewerModel": "claude-opus-4.7",
    "dryRunTimeout": 300000,
    "strictAvailability": false
  },

  "extensions": ["notify-slack"],

  "hooks": {
    "preDeploy": { "enabled": true, "blockOnSecrets": true, "warnOnEnvGaps": true, "scanSince": "HEAD~1" },
    "postSlice": { "silentDeltaThreshold": 5, "warnDeltaThreshold": 10, "scoreFloor": 70 },
    "preAgentHandoff": { "injectContext": true, "runRegressionGuard": true, "cacheMaxAgeMinutes": 30, "minAlertSeverity": "medium" },
    "postRun": { "invokeAuditor": { "onFailure": true, "everyNRuns": null } }
  },

  "brain": {
    "federation": {
      "enabled": true,
      "repos": ["E:/GitHub/shared-platform-memory"]
    }
  },

  "meta": { "selfRepairRepo": "srnichols/plan-forge" }
}

See also

• Customization — Configuration Hierarchy, how .forge.json interacts with copilot-instructions.md and instruction files when settings conflict.
• Appendix U — Environment Variables Reference, the companion reference for everything that lives outside .forge.json: provider API keys, server ports, orchestrator timing, telemetry. Includes the full resolution precedence when flags, env vars, secrets, and .forge.json overlap.
• Appendix G — Update Source Modes, the full story behind updateSource: auto | github-tags | local-sibling.
• Chapter 14 — Quorum Mode, what each quorum.* key does in practice; the complexity scoring rubric that drives auto.
• Chapter 13 — Multi-Agent Setup, what each entry in agents generates.
• Chapter 22 — How the Shop Remembers, how brain.federation shapes cross-project memory recall.
• pforge-mcp/capabilities.mjs — CONFIG_SCHEMA, the machine-readable JSON Schema this appendix mirrors. If they disagree, the schema wins; please file an issue.