Troubleshooting & FAQ

Quick answers to the issues you’re most likely to hit while running the pipeline.

forge-bootstrap refuses: repo not empty

forge-bootstrap has a greenfield gate: it only runs against an empty repository and will not overwrite existing files. If you already have a project, don’t use bootstrap — run forge-init on the existing repo instead. See bootstrapping for the full distinction.

A stage says a prerequisite isn’t complete

The stages are sequential — each one needs the previous stage finished. The PRD must exist before the tech spec, the tech spec before the implementation specs, and so on. Check where you actually are with the dashboard.

Most stages accept a force mode (--force) that skips the prerequisite check while still loading any existing artifacts. Use it sparingly, since the prerequisite usually exists for a reason.

I re-ran a stage I’d already started — will it wipe my work?

No. On re-entry, an authoring stage (Stages 1–4) detects that the stage was already started and offers a choice rather than blindly re-running: resume from the artifacts already on disk (after an interrupted run), or start a new version (when the stage was already complete). Pass --force to skip the gate and restart from scratch.

Stage 5 won’t start

The loop stage has a few preconditions. Common causes when it refuses to launch:

• The backlog hasn’t been created and verified yet.
• The loop runner (rauf) is missing, or older than the required minRunnerVersion (0.6.0).
• The runner isn’t set up in the project — rauf needs a .rauf.json, created by running rauf install ..
• There are uncommitted changes. The runner refuses a dirty tree, so the stage commits pipeline state before launching.

What loop-runner settings will the loop actually use?

Most loopRunner fields have defaults, so the block in your forge.config.json is only the part you overrode — which makes “what will actually run?” hard to answer by reading it. Ask the pipeline instead:

python3 <plugin-root>/scripts/forge-session.py effective-config --config ./forge.config.json --json

That prints the effective configuration: every field’s default (read from the bundled references/forge-config-schema.json) with your overrides merged on top. Command templates come back with their {bin}, {backlogDir} and {iterations} placeholders intact, because that is exactly what the loop stage renders from. Drop --json for an aligned, readable table.

It is a diagnostic, so its exit codes are worth knowing:

• Exit 0 — resolved. A missing or corrupt forge.config.json is not an error: it resolves to pure defaults, which is what an unconfigured project should get.
• Exit 2 — the bundled schema itself is unreadable or unparseable. Nothing is printed, deliberately: with no defaults to resolve, a partial answer would be worse than none. This points at the install, not at your config — repair it with feature-forge update.

This is also the reason the loop stage no longer mis-reports its own settings: the defaults merge is computed by the script rather than assembled by the model reading a schema. See configuration for what each field means.

The loop stopped — what do the signals mean?

For each item, the agent emits one signal (see core concepts and the loop stage):

• RAUF_DONE — the item passed; the loop continues to the next item.
• RAUF_BLOCKED — a missing dependency or unclear requirement; the item is set aside.
• RAUF_NEEDS_HUMAN — a decision or secret (such as an API key) is needed; the loop waits for your answer.

The loop wants to switch me to a claude/… branch I didn’t create

That’s a stale branch record from a hosted surface. Claude.ai remote and cloud agents run each session on an imposed branch (e.g. claude/<slug>), which the pipeline records as the feature’s branch. If you then move the work to your own topic branch, the record is stale — and older builds would offer to switch you back to the imposed name.

Current builds reconcile this automatically: the loop pre-flight adopts the branch your pipeline state actually resolves on (updating the record, with a visible note) rather than pushing you back. If you’re on the repo’s default branch, it instead recommends creating a topic branch but still lets you proceed. Nothing is auto-switched without your consent.

How do I see what stage I’m at / read pipeline state?

Run the dashboard:

/feature-forge:forge <feature>

See the dashboard for what it reports. The underlying state lives in specs/<feature>/.pipeline-state.json.

Verification found problems

When forge-verify finds issues, it writes a findings document rather than changing anything. To apply the suggested fixes, run:

/feature-forge:forge-fix <feature>

Then re-verify to confirm the findings are resolved.

This verify → fix → re-verify loop can be automated with autoFix: true, but only when it’s safe to do so — the findings document must have no unresolved decision points, the working tree must be clean, and the mandatory re-verify must pass. If any precondition fails, the navigator falls back to surfacing the findings digest and asking you before running forge-fix. Because autoFix mutates artifacts without a human read, it stays off by default; leaving it off keeps you in the loop on every fix.