// Safely upgrade Project Governor by showing new features, planning migrations, preserving project customizations, and applying only safe operations.
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | plugin-upgrade-migrator |
| description | Safely upgrade Project Governor by showing new features, planning migrations, preserving project customizations, and applying only safe operations. |
Upgrade Project Governor safely after a project has already been initialized.
This skill distinguishes plugin source updates from initialized project governance-file migrations.
Never overwrite initialized project governance files blindly.
Before applying anything, show:
After applying an approved user-level plugin update or initialized-project migration, prove the Codex runtime is not still loading an older local marketplace cache before calling the upgrade complete.
CHANGELOG.mdreleases/FEATURE_MATRIX.jsonreleases/MIGRATIONS.json.project-governor/INSTALL_MANIFEST.json in the target project when presentpython3 skills/plugin-upgrade-migrator/scripts/inspect_installation.py --project /path/to/project
python3 skills/plugin-upgrade-migrator/scripts/compare_features.py --current-version 0.4.1 --target-version 0.4.3 --feature-matrix releases/FEATURE_MATRIX.json
python3 skills/plugin-upgrade-migrator/scripts/plan_migration.py --project /path/to/project --plugin-root /path/to/codex-project-governor --current-version 0.4.1 --target-version 0.4.3
python3 skills/plugin-upgrade-migrator/scripts/apply_safe_migration.py --plan .project-governor/upgrade/0.4.1-to-0.4.3/UPGRADE_PLAN.json --apply
codex debug prompt-input '$codex-project-governor:gpt55-auto-orchestrator'
Run the Codex CLI smoke from the upgraded project context after the plugin checkout, project governance files, or runtime-mode state has been refreshed:
codex debug prompt-input '$codex-project-governor:gpt55-auto-orchestrator'
Record the observed Harness/plugin version, plugin cache path, or newly expected capability in evidence. If the output still shows an older version/path or lacks the expected new capability, stop before declaring success, refresh the user-level plugin checkout/cache, restart Codex when needed, and rerun the smoke.
Git tags, release pages, plugin manifests, and .project-governor/INSTALL_MANIFEST.json are necessary evidence, but they are not sufficient without this CLI load check.
| File class | Policy |
|---|---|
| plugin source files | replace through git/patch |
| templates | update in plugin only; do not auto-overwrite project copies |
AGENTS.md | three-way merge/manual review |
docs/conventions/*.md | three-way merge/manual review |
docs/quality/*.md | add-if-missing; merge if modified |
docs/memory/*.md | append-only; never overwrite |
docs/decisions/*.md | never overwrite existing decisions |
.codex/agents/*.toml | add-if-missing; merge by agent name if modified |
.codex/config.toml | merge by section/key; never replace blindly |
.codex/prompts/*.md | add-if-missing or three-way merge |
tasks/_template/*.md | add-if-missing or three-way merge |
AGENTS.md is a rule-bearing template. If the latest plugin template differs from the template hash recorded in .project-governor/INSTALL_MANIFEST.json, the migration plan must surface AGENTS.md even when no release migration explicitly names it. Unmodified installed AGENTS.md files may be replaced from the latest template; user-modified files stay manual review or three-way merge items.
Return an upgrade panel with feature diff, migration plan, safe operations, manual-review items, Codex CLI verification result, and next choices.
Before planning migrations, run project-hygiene-doctor when the target project contains .codex/agents/, .codex/prompts/, .codex/config.toml, .codex-plugin/, skills/, templates/, releases/, or Project Governor bundled examples/tests. These may indicate plugin-global assets were initialized into a project.