ForgeFlow / Reference

Branch Trial

Shell examples run from the target project root. For scripts/forgeflow/ commands, use the helper path from your ForgeFlow checkout, or replace that prefix with "${CODEX_HOME:-$HOME/.codex}/forgeflow/scripts/forgeflow/" for Codex and "$HOME/.claude/forgeflow/scripts/forgeflow/" for Claude Code. Run JavaScript helpers with node and shell helpers with bash. Replace <project> with the actual project folder name before running a placeholder example.

Use this flow to try Forgeflow on one real branch without committing generated local state. It is meant for adoption trials, demos, and side-by-side comparisons against no-agent or single-agent review.

Setup

Start from a git branch with the change you want to evaluate:

git status --short
git branch --show-current

If the project does not already ignore Forgeflow local state, add these patterns to a local exclude file instead of changing the repo:

printf ".forgeflow/\n.forgeflow-budget.json\n" >> "$(git rev-parse --git-path info/exclude)"

This keeps trial artifacts local while avoiding a repository change.

Verify Install

From Claude Code:

/forgeflow-version
/forgeflow-health

From a checkout or installed helper root:

scripts/forgeflow/ensure-forgeflow-state.sh
scripts/forgeflow/health-check.js --fix --json

If you installed without a checkout, replace scripts/forgeflow/ with:

~/.claude/forgeflow/scripts/forgeflow/

Run The Trial

For Claude Code, run one review on the branch:

/review

For Codex use $forge-review review the current changes; /review is a Codex built-in.

For a narrower Claude trial, pass a commit range or paths:

/review HEAD~3..HEAD
/review src/auth.ts src/db.ts

Then inspect local context and budget signals:

scripts/forgeflow/advise-context.js --root .forgeflow --record --json
scripts/forgeflow/summarize-context-telemetry.js --root .forgeflow --json
scripts/forgeflow/check-context-budget.js --root .forgeflow --warn-only --json

Compare Results

Record the outcome after human triage. Use review.workflow to compare workflows:

{
  "schema_version": "1",
  "change_id": "local-branch-name",
  "review": {
    "workflow": "forgeflow",
    "mode": "full-mode",
    "agents_used": ["builder_reviewer", "guardian_reviewer"],
    "verifier_decisions": []
  },
  "outcome": {
    "findings_total": 2,
    "findings_confirmed": 1,
    "findings_rejected": 1,
    "review_minutes": 18,
    "auto_fix_success": false,
    "post_merge_regression": false,
    "finding_classes": [
      { "class": "auth/session/permissions", "total": 1, "confirmed": 1, "rejected": 0 },
      { "class": "missing-transaction", "total": 1, "confirmed": 0, "rejected": 1 }
    ]
  }
}

Append and summarize locally:

scripts/forgeflow/record-review-outcome.js --input outcome.json --out ".forgeflow/$(basename "$PWD")/review-outcomes.jsonl" --json
scripts/forgeflow/render-evaluation-report.js --outcomes ".forgeflow/$(basename "$PWD")/review-outcomes.jsonl" --context-root .forgeflow --public

For a side-by-side comparison, repeat the same change with review.workflow set to no-agent, single-agent, and forgeflow. See Workflow Comparison for the full comparison flow.

Clean Up

Review generated local state:

git status --short
find .forgeflow -maxdepth 3 -type f | sort

Leave .forgeflow/ in place to preserve memory and trend history. If the trial is done, identify the files created by this trial and remove only those after reviewing them. Do not delete the entire state directory or budget configuration in an existing project: they can predate the trial. A disposable clone is the simplest place to test a complete clean-state lifecycle.

Do not commit trial output unless the project explicitly wants those local records in version control.