ForgeFlow / Reference

Package And Release Onboarding

Upgrading from legacy agent names: follow the source-checkout migration procedure before using an old installed updater. It explains how to preserve edited legacy agents and recover the previous installation.

Use this when you arrive at Forgeflow from a package listing, release page, marketplace entry, or shared install link. The goal is to get from first install to a verified first review without needing prior project context.

Choose Your Entry Point

You are using	Start here	What it installs
Claude Code	`install-template.js --target claude` from a checkout	Claude agents, commands, hooks, templates, project rules, patterns, and runtime helpers
Codex	`install-template.js --target codex`	Codex agents, skills, and Forgeflow command metadata
Both	`install-template.js --target both`	Claude Code and Codex files from one local checkout

For a clean release verification pass, use Clean Checkout Install Verification.

Claude Code First Run

From the ForgeFlow checkout (see Quick Start for cloning and prerequisites):

node scripts/forgeflow/install-template.js --target claude --dry-run --json
node scripts/forgeflow/install-template.js --target claude

Once installed, /update-forgeflow updates the Claude managed runtime. It is not a bootstrap command on a clean host.

Restart Claude Code after the installer finishes. Then verify:

/forgeflow-version
/forgeflow-health

If /forgeflow-health reports a manual settings issue, edit ~/.claude/settings.json and rerun the health check. Ember setup can register its prompt hook with a settings backup; other hooks and the status line remain user-managed. See Settings And Recovery for statusline, hook, restart, repair, and rollback guidance.

The installed runtime helpers live at:

~/.claude/forgeflow/scripts/forgeflow/

Codex First Run

From a Forgeflow checkout:

node scripts/forgeflow/install-template.js --target codex --dry-run --json
node scripts/forgeflow/install-template.js --target codex

Restart Codex so the new agents and skills are discovered, then run:

scripts/forgeflow/render-first-run-guide.js --runtime codex

Use the Forgeflow review skill:

$forge-review review the current changes

Use $forge-review instead of /review in Codex because /review is a Codex built-in command.

First Useful Review

Pick a real branch with a small to medium change. Run:

/review

In Codex, run:

$forge-review review the current changes

Pass criteria:

Forgeflow explains its routing decision.
Findings include file references and evidence.
High-risk findings are specific enough to verify.
Local .forgeflow/ state is created or repaired only inside the target repo.

Where To Go Next

Quick Start for the normal install and workflow path.
Codex First Run for Codex-specific discovery checks.
Workflow Commands for the full command list.
Public-Safe Examples for example install, health, review, and evaluation output.
Migration Guide for existing Claude installs.
Settings And Recovery for manual settings, restarts, repair, and rollback.