ForgeFlow / Reference

Context Budget Examples

Use /review in Claude Code or $forge-review in Codex for the normal workflow. Terminal examples below assume the ForgeFlow source checkout; in an application repository use the installed runtime helper paths. Token totals are estimates for the generated artifacts, not a measurement of your host model's complete session context.

Forgeflow context helpers keep agent prompts smaller by building compact packets before agents read files directly. The budget tools help decide when a packet is small enough to use as-is and when to trim or split work.

Starter Config

Seed the default config:

scripts/forgeflow/seed-budget-config.js --json

Default .forgeflow-budget.json:

{
  "max_compact_tokens": 16000,
  "warn_only": true,
  "kind_limits": {
    "context-pack": 16000,
    "code-topology": 12000,
    "memory-context": 8000,
    "scope-manifest": 6000
  }
}

Use warn_only: true while tuning. Change it to false when you want context budgets to fail release checks or CI wrappers.

Review Workflow

Before /review, build review packets and check their budget:

scripts/forgeflow/build-context-pack.js --json
scripts/forgeflow/check-context-budget.js --root .forgeflow --warn-only --json
scripts/forgeflow/advise-context.js --root .forgeflow --record --json

If the advisor reports context-healthy, use the generated packet as the primary review context.

If it reports trim-budget-violation, use /forgeflow-review-wave-prep --write-wave-files (Claude Code) or the render-review-wave-prep.js --write-wave-files runtime helper to prepare a focused wave. Inspect its recommended build and verification commands before spawning agents. Other scope choices include:

• pass fewer paths to /review
• split broad changes into directory-focused reviews
• lower build-context-pack.js --max-memory-chars when local memory hits dominate packet size
• review generated files separately from source changes
• move long logs, snapshots, or vendored files out of the review scope

Implementation Workflow

Before /implement, build memory and scope artifacts:

scripts/forgeflow/build-memory-context.js --json
scripts/forgeflow/build-scope-manifest.js --json
scripts/forgeflow/check-context-budget.js --root .forgeflow --warn-only --json
scripts/forgeflow/advise-context.js --root .forgeflow --record

If memory-context exceeds budget, narrow memory selection and remove duplicated context from the packet before asking implementation agents to proceed. Preserve source records and required proof; archive or edit historical handoffs only deliberately.

If scope-manifest exceeds budget, split the brief into smaller implementation waves and assign narrower file ownership.

Strict Release Gate

For release checks, switch from warnings to failures:

{
  "max_compact_tokens": 14000,
  "warn_only": false,
  "kind_limits": {
    "context-pack": 14000,
    "code-topology": 10000,
    "memory-context": 7000,
    "scope-manifest": 5000
  }
}

Then run:

scripts/forgeflow/check-context-budget.js --root .forgeflow --json

A fail status means the generated context should be trimmed before the work is reviewed or shipped.

Large Diff Example

For a broad change touching multiple subsystems:

scripts/forgeflow/build-context-pack.js --files changed-files.txt --json
scripts/forgeflow/check-context-budget.js --root .forgeflow --max-kind context-pack=12000 --warn-only
scripts/forgeflow/advise-context.js --root .forgeflow --record

If the packet is still large, split changed-files.txt by ownership:

changed-backend.txt
changed-frontend.txt
changed-docs.txt

Then review each slice separately:

/review changed-backend.txt
/review changed-frontend.txt

Docs-only slices often route to skip-mode or thin-mode, reducing review cost.

Low-Savings Example

The advisor may report:

WARN: context-pack saved only 12% versus baseline.
Action: Prefer scope packets and compact memory before full artifact reads; remove repeated low-signal sections from generated packets.

Typical fixes:

• remove repeated summaries from handoff files
• trim generated output, snapshots, and logs from changed-file lists
• prefer build-memory-context.js over asking agents to read full progress logs
• ask for a narrower review path or commit range

Trend Example

Use --record on repeated runs:

scripts/forgeflow/advise-context.js --root .forgeflow --record

The advisor appends:

.forgeflow/context-advisor-history.jsonl

On the next run it reports deltas:

Compact token delta: -2400
Saved token delta: 1800
Percent saved delta: 9.5
Budget violation delta: -1

That means trimming improved the packet: compact tokens decreased, saved tokens increased, and one violation was removed.

When code-map history exists, the same advisor output can include a Code Map Trends section. Use that section to spot new structural hotspots or unresolved import growth before starting the next review.