Migration Guide

Migration Guide

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 moving an existing local Claude install to the current Forgeflow layout.

What The Current Layout Uses

Managed Forgeflow files live under:

~/.claude/agents/
~/.claude/commands/
~/.claude/hooks/
~/.claude/templates/
~/.claude/project-rules/
~/.claude/forgeflow-patterns/
~/.claude/forgeflow/scripts/forgeflow/

The installed commit is tracked at:

~/.claude/forgeflow-version

Custom agents named custom-*.md are preserved by the updater.

Before Migrating

Check what is installed:

/forgeflow-version
/forgeflow-health

If /forgeflow-version is unavailable, run from a repo checkout:

scripts/forgeflow/forgeflow-version.js --offline

Optional backup (the archive may contain private configuration or custom prompts; keep it local):

tar -czf ~/forgeflow-claude-backup.tgz \
  ~/.claude/agents \
  ~/.claude/commands \
  ~/.claude/hooks \
  ~/.claude/templates \
  ~/.claude/project-rules \
  ~/.claude/forgeflow-patterns \
  ~/.claude/forgeflow-version

Standard Migration

From Claude Code:

/update-forgeflow

Restart Claude Code, then run:

/forgeflow-version
/forgeflow-health

Expected result:

Status: up-to-date
Summary: 0 failures

If commands or hooks are installed on disk but unavailable in the current Claude session, restart Claude Code again.

Repair A Partial Install

Use repair mode when a managed command, agent, hook, template, pattern, or runtime helper is missing or corrupted:

/update-forgeflow --repair

Repair reinstalls all managed Forgeflow files from upstream main, even when the installed SHA already matches upstream.

It does not touch:

• ~/.claude/settings.json
• ~/.claude/agents/custom-*.md
• non-Forgeflow files

Roll Back The Previous Update

The script-backed updater preserves one managed-file snapshot before writes:

~/.claude/forgeflow/backups/previous/

To restore it:

/update-forgeflow --rollback

Rollback restores previous managed file contents and file modes, removes managed files that were newly created by the last update, and restores ~/.claude/forgeflow-version to the snapshot version.

Rollback does not mutate settings.json.

Settings Wiring

The template installer and updater can register Ember's prompt hook, preserving existing entries and a separate settings backup. Other hooks and the status line remain manual. If /forgeflow-health reports drift in those settings, follow Settings and Recovery.

Statusline:

"statusLine": {
  "type": "command",
  "command": "node \"$HOME/.claude/hooks/forgeflow-statusline.js\""
}

PostToolUse hooks:

{
  "type": "command",
  "command": "node \"$HOME/.claude/hooks/forgeflow-context-monitor.js\""
}

{
  "type": "command",
  "command": "node \"$HOME/.claude/hooks/forgeflow-gate.js\""
}

{
  "type": "command",
  "command": "node \"$HOME/.claude/hooks/forgeflow-telemetry.js\""
}

After settings changes, restart Claude Code and rerun:

/forgeflow-health

If You Previously Used GSD Hooks

/forgeflow-health may report a legacy gsd-statusline.js statusline. That is not automatically replaced.

To use Forgeflow context monitoring, set statusLine.command to:

node "$HOME/.claude/hooks/forgeflow-statusline.js"

Keep the old GSD hook file if you want a manual rollback reference. It is not a Forgeflow-managed file.

Project-Local State

Run this inside each git project where you want Forgeflow memory:

~/.claude/forgeflow/scripts/forgeflow/health-check.js --fix --json

This creates:

.forgeflow/<project-name>/
.forgeflow/<project-name>/agent-notes/
.forgeflow-budget.json

It also adds .forgeflow/ to .gitignore when needed.

Final Smoke Test

From a git project:

/forgeflow-version
/forgeflow-health
/quick summarize this repository structure
/review

For docs-only or empty diffs, /review may route to skip-mode or thin-mode. That is expected.