Best Practices

Getting the most out of Forge is less about configuration and more about leaning into the workflow. These practices help Forge do what it does best: keep your specs, code, and team in sync while protecting you from runaway loops and stale truth.

Let adaptive depth pick the ceremony

Adaptive depth triages each change and chooses how much of the spine it needs. Trust it — don't force a mode. A trivial docs fix fast-forwards; a payments change takes the full spine. Forcing every change to the same depth either adds friction to small work or under-scrutinizes risky work.

You can always go deeper

Adaptive depth only chooses a starting point. When a change deserves more scrutiny than the triage suggested, force a deeper path. See adaptive depth.

Keep the constitution current

The constitution is standing project truth, and it is load-bearing: constitution conflicts cap the analyze quality score. A stale constitution quietly drags down every quality assessment. Revisit it whenever your principles or constraints change, so the score reflects reality rather than drift against an outdated document.

Commit .forge/ so the team shares specs

Everything under .forge/ is plain files. Commit it so your whole team shares the same specs, changes, and memory. When .forge/ is versioned with the code, specs travel with the repository, in-flight changes can be resumed by anyone, and project memory compounds across the team.

Keep local config local

.forge/config.local.yaml is gitignored on purpose — it is per-machine. Keep machine-specific settings there and shared settings in .forge/config.yaml. See Configuration.

Run the dashboard while you work

Keep the generated dashboard open as you work:

forge docs serve

It gives you a live view of specs, changes, task status, budget, and timeline — so you always know where a change stands. See the dashboard overview.

Connect the harness to your agent via hooks

Wire the harness into your agent with hooks so the runtime guardrails auto-populate from live activity. Once connected, the circuit-breaker, budget ledger, and attributed timeline fill in automatically as your agent works — no manual recording. See live agent hooks.

Use the circuit-breaker to stop runaway loops

Verification runs under a circuit-breaker that halts runaway verify/implement loops before they burn time and budget. Let it do its job, and tune it when a change legitimately needs more attempts. See circuit-breaker.

Run analyze and drift periodically

Make analyze and drift part of your rhythm, not just a final gate:

• analyze gives a 100-point quality score for the current state.
• drift surfaces Ghost (code with no spec), Phantom (spec with no code), and Mutated (code and spec disagree) divergence.

Catching drift early keeps specs/ trustworthy. See cross-cutting commands.

Archive completed changes

Archive changes as soon as they pass verify. Archiving promotes the change's delta specs into canonical specs/ and freezes the change in the immutable audit trail. Leaving finished work un-archived lets specs/ fall behind what the code actually does.

Archive means done

archive is blocked while any task is blocked or not done, so a green archive is a real signal. See honest task status.

Migrate existing projects with forge import

Adopting Forge on an existing codebase? Migrate with forge import instead of rewriting. Import brings your project into Forge's model losslessly — anything that does not map cleanly lands in _imported/ rather than being lost — so you adopt the workflow without throwing away existing structure. See migration.

Summary

Practice	Why it matters
Let adaptive depth choose	Right ceremony per change
Keep the constitution current	Stale constitution caps analyze score
Commit .forge/	Team shares specs, changes, memory
Run forge docs serve	Live visibility while you work
Connect harness hooks	Breaker/budget/timeline auto-populate
Use the circuit-breaker	Stops runaway loops
Run analyze/drift periodically	Catch drift early
Archive completed changes	Keeps specs/ canonical
Import, don't rewrite	Lossless migration

Next steps

• The Workflow — the spine these practices support.
• Configuration — settings referenced above.
• Circuit-breaker — bound your verify loops.
• Migration — adopt Forge on existing projects.