Skip to content
Feature Forge

Driving with the forge Navigator

The forge navigator is the read-only status view and the cockpit for driving a feature end-to-end. Reach for it any time you’re unsure what stage a feature is at, what to run next, or you just want to continue where you left off.

Commands

Section titled “Commands”
/feature-forge:forge                 # list active features, most recent first
/feature-forge:forge <feature-name>  # show one feature's status and next command

What it shows

Section titled “What it shows”
  • The current stage, per-stage status, and verification status
  • For epics, the epic dashboard (member features and their states)

It reads .pipeline-state.json (and epic-manifest.json for epics).

Pick up where you left off

Section titled “Pick up where you left off”

With no feature named, the navigator lists active features sorted by how recently they were touched (updatedAt descending) and recommends the one at the top — usually the feature you were last working on.

  • If exactly one active standalone pipeline exists, the navigator skips the list and opens straight to that feature’s dashboard.
  • If several are active, it shows them most-recent-first so the recommended pick is always at hand.
  • If the current branch has no features, the navigator looks across branches (local and remote-tracking) and surfaces any features whose pipeline state lives elsewhere — so a fresh clone or a default-branch session finds work scattered on topic branches instead of concluding nothing exists. It never switches branches on its own.

Drive to the next stage

Section titled “Drive to the next stage”

After rendering a feature’s dashboard, the navigator offers the next pipeline stage. How it hands you off depends on autoInvokeNextStage (see forge.config.json):

  • autoInvokeNextStage: true (default) — the navigator launches the next stage in the same session via the Skill tool the moment you confirm. No retyping, no paste.
  • autoInvokeNextStage: false, or a non-Claude host — the navigator prints the next command (e.g. /feature-forge:forge-3-specs <feature>) for you to run yourself.

When a verification gate is pending for the current stage, the navigator offers to verify first. With autoVerify enabled for that stage, it skips the prompt and runs verify automatically (in a fresh subagent), surfacing only the findings digest. An explicitly skipped verify is respected — the navigator does not re-offer or auto-run it — and a verified stage is re-checked only if its artifact is later revised.

Context-window awareness

Section titled “Context-window awareness”

Long pipelines accumulate context. The navigator recommends starting each stage in a clean session — /clear, then re-run the navigator — at every stage boundary on its own merits, so each heavy stage starts fresh. Before sending you into the next stage it also checks how full the current session is, but that fullness only modulates how emphatically it recommends the clear, never whether.

  • It reads the live session’s token usage and compares it to the context window.
  • Past contextWarnThreshold (default 0.7, i.e. 70% full), it strengthens that recommendation and adds mid-stage compaction advice — the threshold is a secondary signal, not the reason to clear.
  • The window is inferred from the session model and falls back to 200k. Once observed usage exceeds 200k, the navigator auto-bumps the assumed window to 1M (usage above 200k proves a 1M-beta window is active), avoiding a nonsensical >100% reading.

See Sessions & monitoring for how this fits the broader picture of session state and clean-session handoffs.

Lifecycle controls

Section titled “Lifecycle controls”

The navigator can pause, resume, or abandon a feature’s pipeline via the pause, resume, and abandon sub-commands, and record free-form notes. It is otherwise read-only — it never edits your specs.

When to use it

Section titled “When to use it”

Use it whenever you’re unsure what stage you’re at, want to resume the most recent feature, or are ready to advance to the next stage.