# Outfitter Upgrade

> Manages @outfitter/* package upgrades — handles version detection, dependency bumps, mechanical codemods, and test verification. Use when upgrading dependencies, migrating breaking changes, or running outfitter upgrade.

- Skill: `outfitter-dev/outfitter-upgrade` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add outfitter-dev/outfitter-upgrade`
- Raw SKILL.md: https://api.skillmd.com/api/skills/outfitter-dev/outfitter-upgrade/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: outfitter-dev (https://skillmd.com/u/outfitter-dev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/outfitter-dev/outfitter-upgrade

---


# 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

```bash
# 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

```typescript
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`:

```yaml
---
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