forge.config.json Reference

forge.config.json lives at the project root and is created by forge-init or forge-bootstrap. All keys are optional; the defaults below apply when a key is absent.

Top-level keys

Key	Type	Default	Meaning
specsDir	string	./specs	Root directory for feature spec documents.
docsDir	string	./docs/architecture	Root directory for generated architecture docs.
backlogDir	string or null	null	If null, backlog lives at <specsDir>/<feature>/backlog.json; when set, at <backlogDir>/<feature>/backlog.json.
gitCommitAfterStage	boolean	true	Auto-commit after each stage completes.
commitPrefix	string	forge	Conventional-commit prefix; commits look like forge(<feature>): <action>.
branchPerFeature	boolean	true	Offer an isolated git branch when a feature/epic starts on the default branch. Gated only on the project using git (independent of gitCommitAfterStage); when false, forge never prompts and works on the current branch.
branchPrefix	string	forge/	Prefix for the Branch Setup name — forge/ yields forge/{feature} or forge/{epic}. Ignored when branchPerFeature is false.
stack	string or null	null	Project stack id; set during Stage 2 (tech spec).
typeCheckCommand	string or null	null	Type-check command (e.g. bun run typecheck, mypy .); resolved in Stage 2.
testCommand	string or null	null	Test command (e.g. bun test, pytest); resolved in Stage 2.
loopIterationMultiplier	number	1.5	Multiplier applied to the pending-item count to compute loop iterations (e.g. 10 items × 1.5 = 15).
autoInvokeNextStage	boolean	true	Navigator auto-invokes the next stage via the Skill tool after you confirm; false keeps copy-paste. Ignored on non-Claude hosts (always print). Navigator-only.
contextWindowTokens	integer or null	null	Context window used by the navigator’s context-usage check. null infers from the session model, falls back to 200000, and auto-bumps to 1000000 once usage exceeds 200000. Set explicitly (e.g. 1000000) for accurate readings below 200k. Navigator-only.
contextWarnThreshold	number	0.7	Fraction of the window (0–1) past which the navigator strengthens its clean-session recommendation and adds mid-stage compaction advice. Secondary signal only: a clean session is recommended at every stage boundary on its own merits — this modulates how emphatically, not whether. Navigator-only.
autoVerify	boolean	false	Auto-run forge-verify after a stage completes, with no prompt. Runs in a fresh clean-room subagent, so it never needs a /clear and costs the session only a digest. See Auto-verify below. Navigator-only.
autoVerifyStages	object	{}	Per-stage overrides for autoVerify, e.g. {"forge-1-prd": false}. Effective value = autoVerifyStages[stage] if present, else autoVerify. Keys are limited to the five verify-capable stages (forge-1-prd…forge-5-loop); an unknown key is a config error, not a silent no-op. Navigator-only.
autoFix	boolean	false	Chain forge-fix after an auto-verify that finds issues — honored only when autoVerify is on for the stage and preconditions hold. Mutates artifacts, so it stays off by default. See Auto-verify. Navigator-only.
workspaces	array	(absent)	Monorepo members; each has name, path, stack, and optional typeCheckCommand/testCommand.
loopRunner	object	(absent → rauf defaults)	Configures the Stage-5 loop runner. See below.

The loopRunner block

The Stage-5 loop runner is configured, not hardcoded. When the loopRunner block is absent, Feature Forge defaults to rauf. The most useful sub-keys:

Sub-key	Default	Meaning
name	rauf	Loop runner identifier.
bin	rauf	Executable used to invoke the runner.
defaultAgent	""	Empty string means use the runner’s own default agent.
minRunnerVersion	0.6.0	Minimum runner version required.
stateDir	.rauf	Directory for runner state.
logFile	rauf.log	Loop log file.
preconditionFile	.rauf.json	Precondition / config file checked before the loop runs.

All of the runner command keys are templates with {bin}, {backlogDir}, {specsDir}, and {iterations} substituted at call time; most users never need to set these. See Stage 5 for usage.

Session & usage monitoring

autoInvokeNextStage, contextWindowTokens, and contextWarnThreshold configure how the forge navigator drives you between stages and warns you about a filling context window:

• The navigator recommends /clear and a re-run before the next stage at every stage boundary on its own merits. It also measures the current session’s token usage against the context window; past contextWarnThreshold (default 70%) that measurement strengthens the recommendation — a secondary signal, never the gate.
• The window is inferred from the session model, falling back to 200k, and auto-bumps to 1M once usage exceeds 200k (usage above 200k proves a 1M-beta window is active).
• A 1M window can’t be detected until usage crosses 200k, so on a 1M-context model set contextWindowTokens to 1000000 for accurate readings below 200k too.

See Sessions & monitoring for the full picture.

Auto-verify

autoVerify, autoVerifyStages, and autoFix let the forge navigator run the verification gate for you. Verification is uniquely safe to automate: forge-verify delegates to the read-only forge-verifier subagent, which runs in a fresh window that inherits none of your session’s context. A /clear before it is pointless, and it is rarely a step worth skipping — so enabling autoVerify is the recommended default for hands-off runs.

• autoVerify: true — after each stage completes, the navigator dispatches the fresh subagent, which returns only a compact findings digest to your session. No prompt, no paste.
• autoVerifyStages — opt individual stages in or out, e.g. {"forge-3-specs": true, "forge-1-prd": false}. The effective value for a stage is its override if present, otherwise the global autoVerify.
• Freshness — a verify is considered fresh only while the stage artifact’s version matches what was verified. Revise an artifact and it is re-verified; leave it unchanged and it is not re-run. An explicitly skipped verify is respected and never auto-run.
• Clean-room guarantee — auto-verify runs unattended only when the fresh subagent can be dispatched. If it can’t (partial install, or a non-Claude host), it never runs inline in your session — it degrades to the manual verify gate, so a stage is never marked verified on false assurance.
• autoFix: true — chains forge-fix after an auto-verify that finds issues, but only when autoVerify is on for that stage and the findings have zero unresolved decisions, the working tree is clean, and a mandatory re-verify passes. Any miss falls back to a digest + prompt. Because it mutates artifacts without a human read, it’s a power-user opt-in; leaving it off keeps fixing human-gated.

See Verify & Fix → Auto-verify for the operator’s view.

Example

A minimal config:

{
  "specsDir": "./specs",
  "docsDir": "./docs/architecture",
  "gitCommitAfterStage": true,
  "commitPrefix": "forge",
  "loopIterationMultiplier": 1.5
}