Upforge

CLI-driven upgrade orchestration for AI Agents. Automates Java framework upgrades using OpenRewrite for bulk transformations and AI Agent for analysis, judgment, and non-standard fixes.

Requirements

• Node.js 20+
• npm 10+
• A target Java project with the build tools needed for its own compile/test commands

Install

Use npx upforge when you want the CLI to run in any environment without a preinstalled global package:

npx upforge --help
npx upforge init --project /path/to/java-project

For local development or repeated use on one machine, link the package once and use the upforge bin to avoid re-installing on every run (skills assume this path):

npm install
npm link

upforge --help
upforge init --project /path/to/java-project

The published package exposes one bin name:

• upforge

Install For Codex

Install the CLI on your machine and register the bundled skills into Codex:

npm install
npm link
node scripts/install-skills.mjs --target=codex

npx upforge --help

If you want automatic detection instead of a Codex-only install:

node scripts/install-skills.mjs --target=auto

Skills Install

postinstall automatically detects local Cursor and Codex directories and copies the bundled skills when those roots already exist.

Bundled skill names:

• upforge
• upforge-plan
• upforge-execute
• upforge-verify

You can also run skill installation manually:

node scripts/install-skills.mjs --target=auto
node scripts/install-skills.mjs --target=cursor
node scripts/install-skills.mjs --target=codex

All bundled skills use npx upforge ..., so they work in Cursor, Codex, and clean environments.

Quick Start

The default entrypoint is now bare upforge. It first checks the requested project's .upforge/, then falls back to matching git worktrees for the same project path so repo-root invocations can resume unfinished work created by init. The orchestrator only prompts at major workflow boundaries such as entering plan, entering execute, continuing to the next module, and entering verify.

upforge --project /path/to/repo/.worktrees/upforge-2026-04-04

Use --yes when you want to auto-approve those prompts in automation:

upforge --project /path/to/repo/.worktrees/upforge-2026-04-04 --yes

If you need a fresh isolated worktree first, start with:

upforge init --project /path/to/java-project

init creates an isolated git worktree under .worktrees/upforge-YYYY-MM-DD[-N] and prints the worktree path to reuse:

{
  "phase": "init",
  "sourceProjectRoot": "/path/to/java-project",
  "worktreePath": "/path/to/repo/.worktrees/upforge-2026-04-04",
  "projectRoot": "/path/to/repo/.worktrees/upforge-2026-04-04",
  "branch": "upforge/2026-04-04"
}

If init finds an unfinished matching run first, it does not create a new worktree. Instead it returns the existing projectRoot and the next resume command.

Use the returned projectRoot for all later commands. If you accidentally run stateful commands such as scan, plan, or execute from the source repo after init, Upforge resolves the matching active worktree and runs there; without an initialized worktree it refuses to touch the source repo.

Staged verification now uses npx upforge verify init --project <path>, npx upforge verify advance --project <path> --result=pass|fail, and npx upforge verify finalize --project <path>.

npx upforge scan --project /path/to/repo/.worktrees/upforge-2026-04-04
npx upforge baseline --project /path/to/repo/.worktrees/upforge-2026-04-04
npx upforge plan --project /path/to/repo/.worktrees/upforge-2026-04-04
npx upforge plan --finalize --project /path/to/repo/.worktrees/upforge-2026-04-04
npx upforge execute --project /path/to/repo/.worktrees/upforge-2026-04-04
npx upforge verify init --project /path/to/repo/.worktrees/upforge-2026-04-04
npx upforge verify advance --project /path/to/repo/.worktrees/upforge-2026-04-04 --result=pass
npx upforge verify finalize --project /path/to/repo/.worktrees/upforge-2026-04-04
npx upforge status --project /path/to/repo/.worktrees/upforge-2026-04-04

For multi-module upgrades, narrow execution during finalize:

npx upforge plan --finalize --project /path/to/repo/.worktrees/upforge-2026-04-04 --modules core-service,web-api
npx upforge plan --finalize --project /path/to/repo/.worktrees/upforge-2026-04-04 --skip-modules legacy-admin

If the original project path is a subdirectory inside a larger git repo, projectRoot points to the matching subdirectory inside the new worktree. Use that returned path directly.

Architecture

OpenRewrite  --  bulk code transformations
Agent        --  analysis + judgment + manual fixes
Upforge      --  orchestration + checkpoints + context control

Agent-First Target Decisions

Upforge is an execution kernel for Agent-led upgrades. The Agent decides what the user means by an upgrade request, checks whether the local catalog already has a matching scenario, and enriches the catalog from official migration guides when it does not. The CLI then executes the selected catalog target through recoverable checkpoints.

For /upforge swagger2升级swagger3, the intended flow is:

1. Agent preserves the raw goal and enters the Upforge workflow.
2. Agent inspects catalog entries with npx upforge catalog list and npx upforge catalog inspect --id <target-id>.
3. If a catalog target fits, Agent uses that target for scan and plan.
4. If no target fits, Agent searches official migration guides, OpenRewrite recipes, and library docs, then registers or updates a catalog target.
5. Upforge CLI runs scan, baseline, plan, execute, and verify. The Agent must not bypass those checkpoints with an ad-hoc migration just because the task looks small.

Workflow

Init (create worktree) -> Scan -> Baseline -> Plan -> Execute (batch 1) -> Execute (batch 2) -> ... -> Verify

Upforge now keeps live runtime state in a single .upforge/state.json file. scan-result.json, test-strategy.json, verification-report.json, and archives are inputs or derived artifacts, not independent workflow authorities.

In interactive mode, upforge auto-runs the minor steps inside that workflow and pauses only at the major boundaries:

• before entering plan
• before entering execute
• after each completed module in execute
• before entering verify
• when a completed run is about to be restarted
• when advancing to the next recipe batch

Recipe Batching

Recipes are grouped into ordered batches to prevent OOM on large projects:

1. java-17 (if Java < 17) - Upgrade to Java 17 first
2. jakarta (if javax imports detected) - Migrate javax to jakarta
3. spring-boot-3 (always) - Upgrade to Spring Boot 3.3

Use npx upforge advance-batch --project <path> to advance between batches after completing all modules in the current batch.

Local Work Unit Scheduling

plan also creates .upforge/candidate-index.json and stores workUnits inside .upforge/rewrite-plan.json. Work units let Upforge keep execution local and speed-first:

• OpenRewrite starts with coarse recipe batch + module units.
• ast-grep fallback units use the candidate index to narrow broad transforms.
• Resource failures update the failed work unit and can split it into smaller children.
• status reports the current rewrite node and current work unit so a stalled migration can resume from the smallest known scope.

Command Summary

• upforge without a subcommand resumes or starts the interactive workflow
• init creates an isolated git worktree and initializes .upforge/ in that worktree
• init returns the existing unfinished run instead of creating a duplicate worktree when a matching unfinished run already exists
• scan inspects the target project and writes scan metadata
• baseline records compile/test expectations before rewrite execution
• plan matches recipes and generates dry-run, impact scaffolding, candidate index, and rewrite work units
• plan --finalize turns the reviewed impact graph into execution checkpoints
• execute returns the next command to run for the current module or batch, including rewrite work unit metadata when available
• recheck records pass/fail after a rewrite, compile, install, or test step and updates rewrite work unit state
• advance-layer advances batch execution after a full layer succeeds
• advance-batch advances to the next recipe batch
• verify init validates strategy and opens a staged verification session
• verify advance records one verification result with command evidence and health signals
• verify finalize archives the completed upgrade from .upforge/state.json
• context prints phase-specific guidance for the current project state
• status shows the current upforge phase and outstanding work, resolving matching worktrees when run from the repo root
• catalog list shows available upgrade targets for Agent review
• catalog inspect --id <target-id> prints a full catalog target so the Agent can judge fit before planning

Project Structure

• bin/ - CLI entry point
• lib/ - Core library modules
• catalog/ - Upgrade knowledge (scenarios, recipes, fix patterns)
• skills/ - Lightweight Agent skill files
• tests/ - Unit tests

npm Package Scope

The npm package ships with an explicit files whitelist so installation stays lightweight. Large generated sources such as catalog/generated/openrewrite-recipes.json and catalog/generated/openrewrite-categories.json are excluded from the published tarball.