Outfitter Upgrade

Upgrade @outfitter/* packages with structured migration — from version detection through codemod execution to test verification.

Steps

1. Detect — Run outfitter upgrade --json to discover installed versions and available updates.
2. Decide — Present findings. Choose interactive or autonomous mode based on scope.
3. Apply — Run outfitter upgrade to bump deps, install, and run mechanical codemods (interactive prompt by default; use --yes to skip).
4. Migrate — For remaining changes not covered by codemods, apply code transforms manually using structured change metadata.
5. Verify — Run tests. If failures, diagnose using migration docs as context, fix, re-verify.
6. Confirm — Load outfitter-check for final compliance scan.

Mode Selection

Condition	Mode	Rationale
No breaking changes	Auto	Bump, install, run tests — no code changes expected
Breaking changes with codemods	Autonomous	CLI handles mechanical transforms, agent verifies
Breaking changes, no codemods	Interactive	Agent needs judgment for code migration
Major version jump (>2 minor)	Interactive	Too many changes to auto-apply safely

Autonomous Loop

When in autonomous mode, follow this cycle:

detect → apply → codemod → migrate → test → fix → repeat
                                       ↓
                                    (green) → confirm → done

Step-by-step

1. Run outfitter upgrade --json to get structured output
2. Parse the packages array for updates, check hasBreaking
3. Run outfitter upgrade --yes (or --all --yes if breaking changes are expected)
4. CLI bumps deps, installs, discovers codemods, runs them automatically
5. Parse codemods summary from output — check errors array
6. Run outfitter upgrade --guide --json to fetch structured migration guides
7. For each guide in the guide output with changes:
   • Skip changes where change.codemod exists (already handled)
   • Apply remaining changes using the structured metadata (see Decision Framework)
8. Run bun test (or bun run test from repo root)
9. If tests fail: a. Read failure output b. Cross-reference with migration doc guidance (outfitter upgrade --guide) c. Fix the issue d. Re-run tests e. If still failing after 3 attempts, escalate to user
10. When green: load outfitter-check skill for compliance verification

CLI Reference

# Check installed versions
outfitter upgrade

# JSON output for programmatic parsing
outfitter upgrade --json

# Show migration instructions
outfitter upgrade --guide
outfitter upgrade --guide @outfitter/cli    # specific package

# Upgrade with interactive prompt (default)
outfitter upgrade

# Upgrade non-interactively (skip prompts)
outfitter upgrade --yes

# Include breaking changes
outfitter upgrade --all

# Preview without making changes
outfitter upgrade --dry-run

# Upgrade without running codemods
outfitter upgrade --no-codemods

JSON Output Shape

interface UpdateResult {
  packages: PackageVersionInfo[];
  total: number;
  updatesAvailable: number;
  hasBreaking: boolean;
  applied: boolean;
  appliedPackages: string[];
  skippedBreaking: string[];
  guides?: MigrationGuide[];
  codemods?: CodemodSummary;
}

See references/structured-changes.md for full type definitions and parsing examples.

Decision Framework

By Change Type

change.type	Agent Action
moved	Update import paths: from → to
renamed	Find-and-replace: from → to in imports and usages
removed	Find usages of from, replace with alternative from detail
signature-changed	Update call sites per detail description
deprecated	Optional: migrate now or add TODO for later
added	No action needed — informational

By Update Type

Update Type	Action
Patch (0.1.0 → 0.1.1)	Bump, test — no code changes expected
Minor (0.1.0 → 0.2.0)	Review migration doc for new APIs, adopt if beneficial
Breaking (flagged)	Follow migration guide, apply codemods, update code, test

Dependency Order

When updating multiple packages, follow the tier order:

1. Foundation: contracts, types
2. Runtime: cli, mcp, config, logging, file-ops, state, index, daemon, schema, tui
3. Tooling: testing, outfitter (umbrella CLI)

Update lower tiers first — runtime packages depend on foundation changes.

Migration Docs

Migration guides are at ${CLAUDE_PLUGIN_ROOT}/shared/migrations/ with naming:

outfitter-<package>-<version>.md

Each doc has YAML frontmatter with structured changes:

---
package: "@outfitter/cli"
version: 0.4.0
breaking: true
changes:
  - type: moved
    from: "@outfitter/cli/render"
    to: "@outfitter/tui/render"
    codemod: "cli/0.4.0-move-tui-imports.ts"
  - type: renamed
    from: "formatOutput"
    to: "renderOutput"
---

Changes with a codemod field are handled automatically during upgrade. The remaining changes need manual migration.

Codemods

Codemod scripts live at ${CLAUDE_PLUGIN_ROOT}/shared/codemods/ organized by package:

codemods/
  cli/
    0.4.0-move-tui-imports.ts
  contracts/
    adopt-result-types.ts

Each exports a transform(options) function. The CLI discovers and runs them automatically during upgrade. Agents should not run codemods directly — let the CLI handle it.

Error Recovery

Failure	Recovery
Upgrade fails on install	Check network, verify package exists on npm
Codemod reports errors	Read the errors array, fix manually, re-run
Tests fail after migration	Read failure, cross-reference migration doc, fix code
3+ test fix attempts fail	Escalate to user with evidence

Related Skills

• outfitter-atlas — Patterns and templates for current package versions
• outfitter-check — Compliance verification after updates
• outfitter-start — Full adoption workflow (for new or first-time setup)
• tdd-fieldguide — Test-driven development methodology for the verify loop