Skip to content
Forge Docs

Your First Workflow

import { Aside } from ‘@astrojs/starlight/components’;

The real power of Forge is the workflow tools — composite tools that compile everything an agent needs before it acts. Try forge_prepare before your next refactor. Watch what changes.

The exercise

Section titled “The exercise”

Open Claude Code in a repo you’ve indexed. Pick any file you’d like to refactor. Then paste this:

Before we refactor anything, please call forge_prepare on src/payments/checkout.ts and show me what it finds.

Claude’s response will include a structured pre-modification summary:

forge_prepare result for src/payments/checkout.ts:


  Dependents (12 files that import this):
    - src/checkout/page.tsx
    - src/api/orders.ts
    - src/api/cart.ts
    - ... (9 more)


  Imports (4 files this depends on):
    - src/lib/stripe.ts
    - src/models/cart.ts
    - src/utils/currency.ts
    - src/config/env.ts


  Health findings:
    P0 critical:  0
    P1 errors:    1
      dead_exports: export `legacyCheckout` has 0 consumers
    P2 warnings:  0


  Coverage:      84% (from .lcov ingested 2026-04-15)


  Git activity (last 30 days):
    Commits:     3
    Authors:     2
    Last change: 2026-04-14 (4 days ago)


  Assessment:    CAUTION
  Reason:        12 dependents — any signature change will cascade. The 1
                 dead export is a safe cleanup opportunity.

Now Claude knows — before touching a single line — that:

  • 12 other files depend on checkout.ts. Renaming any exported function will break all of them unless updated consistently.
  • There’s one dead export (legacyCheckout) that’s safe to delete.
  • This file was recently active (3 commits, 2 authors in 30 days), so there’s likely parallel work in progress.
  • Coverage is 84% — refactoring the uncovered 16% warrants new tests.

Why this matters

Section titled “Why this matters”

Without Forge, Claude Code would need to grep for imports, read files at random, and hope it catches all the callers. It often doesn’t.

With Forge, Claude calls one tool and gets a structured dependency report, health findings, coverage, and a GO/CAUTION/STOP recommendation — before it writes any code.

The result: refactors that account for all callers. Dead code identified upfront. Signature changes flagged before they cascade.

The three assessments

Section titled “The three assessments”

forge_prepare always ends with one of three assessments:

AssessmentMeaningWhat to do
GONo structural risks found. Proceed normally.Edit freely.
CAUTIONRisks present but not blockers (P1 warnings, many dependents).Note the risks in your plan. Proceed carefully.
STOPP0 findings — broken imports, secrets exposed, or circular deps that block safe editing.Fix P0s first, then re-run forge_prepare.

Forge’s own session-start instructions teach Claude Code this behavior automatically. You don’t need to remind it to call forge_prepare — when properly configured, it does.

After editing: validate

Section titled “After editing: validate”

Once the refactor is done, ask Claude:

Please call forge_validate on src/payments/checkout.ts and any files that were changed.

forge_validate runs the same health checks post-edit and verifies no new broken imports, dead exports, or cycles were introduced. Think of it as a fast, local pre-commit check.

forge_validate result:


  src/payments/checkout.ts — PASS
    No new broken imports
    Dead export `legacyCheckout` removed — P1 resolved
    Dependents count unchanged: 12


  src/checkout/page.tsx — PASS
    Import from checkout.ts updated correctly


  Assessment: CLEAN
  Previous P1 (dead export) resolved. No new findings.

What’s next

Section titled “What’s next”

You’ve completed the Getting Started flow. From here: