OpenPress Upgrade
owns framework package upgrades and workspace migrations.
Use
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
. During migration, edit only:
- root and
- project-owned local skill files in
- project config explicitly named by a migration doc
Do not hand-edit
,
,
,
,
,
, or installer-managed
links.
Workflow
0. Resolve The CLI Command
Use the workspace's local OpenPress CLI. Do not use
;
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
.
Use the
binary only when
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 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
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
reports
settingsMigrationRequired
, this command also performs
the built-in
→
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
- seven default OpenPress workflow skills installed, exact tracked optional and
third-party skills refreshed, and links repaired, unless
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
command or pattern against
the current workspace source. Prefer the migration doc's exact command; adapt
only old
paths to the current
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
section. A checkpoint must include a command or inspection, expected result,
and what failure means.
If a checkpoint fails:
- Diagnose the failure against the migration doc.
- Apply the smallest source fix that satisfies the checkpoint.
- Re-run the failed checkpoint.
- 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
, fall back to:
- all ;
- checks implied by ;
- default build verification:
Run
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:
- source layout changes;
- or config changes;
- public 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 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.