ForgeFlow / Reference

Maintainer Pilot

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 for the first small-team trial of Forgeflow on a real branch. The maintainer stays in control of what is installed, what is shared, and whether the workflow is ready for a broader team rollout.

Pilot Scope

Pick one branch that is real but bounded:

small to medium code change
one clear owner
no emergency production fix
no sensitive customer data in review notes
enough test surface for a human to judge whether findings are useful

Use one runtime first: Claude Code or Codex. Add the second runtime only after the first pass is understood.

Before The Review

Install and verify Forgeflow with Package And Release Onboarding.
Confirm manual settings and restart requirements with Settings And Recovery.
Run a clean health check:

/forgeflow-health

For Codex, confirm the skills are visible after restart:

$consult
$implement
$forge-review
$ship

Make sure .forgeflow/ and .forgeflow-budget.json are ignored or intentionally local.
Tell the branch owner that the pilot is evaluating review quality, friction, and time, not replacing maintainer judgment.
Choose a sharing level with Team Privacy Boundaries.

Run The Pilot

Print the short script for the selected runtime:

scripts/forgeflow/render-pilot-script.js --runtime codex

If the user is still deciding whether Forgeflow is a fit, print the adoption pack first:

scripts/forgeflow/render-adoption-pack.js --runtime codex

The adoption pack also summarizes existing local pilot-evidence rollups when they exist, so rerun it after recording evidence to see the current repeat, expand, stop-and-fix, or defer signal plus the recommended action, owner lane, blocker, runnable inspection command, and fix layer when available. The decision explanation includes setup friction, project-intelligence readiness, living project-map status, and agent-feedback signal. It also includes a public-safe aggregate summary and small-team handoff checklist for deciding whether to invite one or two additional maintainers.

From Claude Code:

/forgeflow-adoption --runtime claude-code

For a net-new user evaluating Forgeflow on a first real task, render the new-user path instead. This path is state-aware: it checks guided repair, release-readiness preview, project intelligence, living project-map status, project learnings, and agent-feedback signal before asking the user to decide whether Forgeflow should continue.

scripts/forgeflow/render-pilot-script.js --runtime codex --path new-user

From Claude Code:

/forgeflow-pilot --runtime claude-code

For the new-user path from Claude Code:

/forgeflow-pilot --runtime claude-code --path new-user

Use the generated script as the run order for install verification, baseline smoke, trends, report, code map, one bounded work item, final report, evidence capture, and rollup.

From Claude Code:

/review

From Codex:

$forge-review review the current changes

First record a real outcome using the JSON example and --input/--out command in Branch Trial. Then summarize the existing records (this command does not append an outcome):

scripts/forgeflow/record-review-outcome.js --summary ".forgeflow/$(basename "$PWD")/review-outcomes.jsonl" --json

Use optional outcome.learning_signals only for signals that are not already derivable from the review counts, such as stale_guidance or manual_promotion_candidate.

Create the local pilot evidence note, replacing example status values with what you actually observed:

scripts/forgeflow/record-pilot-evidence.js --runtime codex --health-result pass --json

If context telemetry is available, generate a public-safe summary:

scripts/forgeflow/render-evaluation-report.js \
  --outcomes ".forgeflow/$(basename "$PWD")/review-outcomes.jsonl" \
  --context-root .forgeflow \
  --public \
  --out ".forgeflow/$(basename "$PWD")/evaluation-summary.md"

What To Judge

Track these signals:

Were findings specific, evidenced, and actionable?
Did Forgeflow explain why it chose its review mode?
Did high-risk findings need Verifier verification?
How many findings were confirmed, rejected, or deferred?
How long did the review take compared with the normal maintainer review?
Did install, restart, settings, or discovery issues slow the trial?
Did generated local state stay inside expected local folders?

Pass Criteria

A maintainer pilot is successful enough to repeat when:

health and version checks pass after install or update
the maintainer accepts at least one material finding or validates that skip/thin routing was appropriate
false positives are low enough that the maintainer would run Forgeflow again
no private raw records need to be shared to explain the result
setup friction is captured in First-Run Friction or Friction To Fix
support issues are classified with Support Triage
expansion is decided with Team Adoption Criteria

Stop Criteria

Stop and fix before expanding the trial when:

settings or restart requirements are unclear after reading the docs
Forgeflow reports missing managed files after repair
findings repeatedly lack file evidence
routing is obviously wrong for the branch risk
raw local records would need to be shared outside the project to explain the outcome
Team Adoption Criteria would classify the pilot as stop-and-fix

Pilot Summary

Keep this summary local unless the project explicitly agrees to share it:

project_type:
runtime: claude-code | codex
branch_type:
install_path:
health_result: pass | warn | fail
review_mode:
confirmed_findings:
rejected_findings:
review_minutes:
setup_friction:
privacy_notes:
repeat_trial: yes | no
next_fix:

For repeatable local evidence capture, use Pilot Evidence Log.