# Openpress Upgrade

> Use when upgrading an OpenPress workspace, checking or applying a newer framework version, responding to update notices, preparing before migration, reading migration notes, generating or implementing a migration plan, or looping through migration QA checkpoints until the workspace passes.

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

---


# OpenPress Upgrade

`openpress-upgrade` owns framework package upgrades and workspace migrations.
Use `openpress` for command/source-boundary routing, then use this skill for
the upgrade and migration workflow.

## Responsibilities

- Detect installed and target OpenPress versions.
- Refresh framework packages and installed OpenPress skills after confirmation.
- Select applicable migration docs from the OpenPress repo.
- Scan workspace source before editing.
- Generate and implement migration plans from the docs.
- Run migration QA checkpoints in a loop until all pass or a blocker needs user input.

## Source Boundaries

Use the source/generated boundary from `openpress`. During migration, edit only:

- `press/`
- root `package.json` and `openpress/settings.json`
- project-owned local skill files in `.agents/skills/`
- project config explicitly named by a migration doc

Do not hand-edit `node_modules/`, `public/openpress/`, `dist-react/`,
`.deploy/`, `.openpress/`, `.turbo/cache/`, or installer-managed
`.claude/skills/` links.

## Workflow

### 0. Resolve The CLI Command

Use the workspace's local OpenPress CLI. Do not use `npx open-press`; `open-press`
is a binary name, not the npm package name.

Use one of these forms:

```bash
open-press <command> .
npm run openpress:skills
node node_modules/@open-press/core/engine/cli.mjs <command> .
```

Prefer the core CLI path in workspaces that only install `@open-press/core`.
Use the `open-press` binary only when `@open-press/cli` is installed and
`node_modules/.bin/open-press` exists.

### 1. Inspect

Run:

```bash
git status --short
node node_modules/@open-press/core/engine/cli.mjs doctor . --json
```

Record:

- current `@open-press/core` version;
- target/latest version from doctor;
- installed and tracked skills, all lockfile sources, missing canonical skills,
  and broken or missing agent links;
- unrelated dirty files that must not be touched.

Doctor is informational and exits 0 even when stale. If latest version cannot
be checked, report the network limitation and do not guess the migration range.

### 2. Preview

Run:

```bash
node node_modules/@open-press/core/engine/cli.mjs upgrade . --dry-run
```

Explain that the local OpenPress CLI `upgrade` command updates dependencies and skills. It does
not rewrite workspace content.

### 3. Confirm Before Mutation

Ask before running commands or edits that mutate dependencies, skills, or
workspace source.

After confirmation, run:

```bash
node node_modules/@open-press/core/engine/cli.mjs upgrade .
```

When `doctor` reports `settingsMigrationRequired`, this command also performs
the built-in `package.json#openpress` → `openpress/settings.json` migration.
It validates the complete result, writes settings atomically, and only then
removes the legacy package field. Do not manually delete the legacy field
first. Unsupported fields or conflicting values require user resolution.

Useful variants when the user asks for a narrower update:

```bash
node node_modules/@open-press/core/engine/cli.mjs upgrade . --no-skills
node node_modules/@open-press/core/engine/cli.mjs upgrade . --no-deps
```

After the command completes, confirm:

- framework version before -> after, reading from
  `node_modules/@open-press/core/package.json` when available;
- seven default OpenPress workflow skills installed, exact tracked optional and
  third-party skills refreshed, and `.claude/skills/` links repaired, unless
  `--no-skills` was used.

### 4. Select Migration Docs

Migration docs live in the OpenPress repo under `docs/migrations/<version>.md`.
Select each doc where:

```txt
currentVersion < version <= targetVersion
```

If a release has no migration doc, treat it as no workspace migration required.
Do not invent migration steps from changelog text.

### 5. Scan Workspace Source

For each selected migration doc, run every `Find` command or pattern against
the current workspace source. Prefer the migration doc's exact command; adapt
only old `document/` paths to the current `press/` tree when the workspace uses
the modern source layout.

Scan at least:

```bash
rg '<pattern-from-migration-doc>' press openpress/settings.json package.json .agents/skills .claude/skills
```

Skip missing optional directories without treating them as failure.

### 6. Generate And Apply Plan

Summarize matched migration work before editing:

- affected migration versions;
- matched files and patterns;
- proposed source edits;
- manual steps the agent cannot perform;
- QA checkpoints that must pass.

Apply workspace source edits only after the user confirms the migration plan.
Keep edits limited to the migration doc. Do not bundle unrelated refactors,
design changes, content rewrites, or deploy work.

### 7. Migration QA Loop

Run every checkpoint in each selected migration doc's `## Migration QA`
section. A checkpoint must include a command or inspection, expected result,
and what failure means.

If a checkpoint fails:

1. Diagnose the failure against the migration doc.
2. Apply the smallest source fix that satisfies the checkpoint.
3. Re-run the failed checkpoint.
4. Re-run any later checkpoints that could be affected by the fix.

Do not report migration complete until every applicable checkpoint passes.
If a checkpoint cannot pass without user input or an external change, report
the blocker with the exact failing command and output.

For older migration docs without `## Migration QA`, fall back to:

- all `Manual steps`;
- checks implied by `Runtime / API changes`;
- default build verification:

```bash
npm run build
```

Run `npm run openpress:pdf` only when PDF output is part of the user's delivery
path or a migration doc explicitly requires it.

## Migration Doc Policy

Create `docs/migrations/<version>.md` only when a release affects existing
workspaces. A migration doc is required for:

- `press/` source layout changes;
- `package.json` or `openpress/settings.json` config changes;
- public `@open-press/core` API changes;
- CLI command, flag, or behavior changes;
- bundled skill catalog or routing changes;
- generated workspace/document schema changes;
- deploy, PDF, render, pagination, or page-contract behavior that may require
  source edits or output verification.

A migration doc is not required for:

- internal system bug fixes with no workspace action;
- workbench-only UI polish;
- docs-only changes;
- tests or package metadata;
- new-template-only design updates that do not change existing workspaces.

If a release can visually shift existing output without requiring a source
rewrite, write a verify-only migration doc with QA checkpoints.

## Do Not

- Do not use `npm create @open-press` or a fresh template diff as the source of
  migration truth.
- Do not auto-deploy after upgrade.
- Do not use force overwrites on workspace files.
- Do not edit generated output.
- Do not claim upgrade or migration readiness without fresh command output.