| name | upgrading |
| description | Scan a PAS project and fix any gaps between its current state and what the installed plugin version expects. |
Upgrading PAS Projects
Declarative upgrade: define what PAS expects, scan the project, fix gaps. No version tracking needed — just "does your setup match what the current plugin expects?"
When to Use
- User says "upgrade", "update", "migrate", or "what's new"
- User reports errors that suggest outdated project layout
- After a PAS plugin update
Expected State Checklist
The current PAS plugin expects these conditions. Each item has a check and a fix.
1. Consumer layout (PAS ≥ 1.4.0 — marketplace-authoritative)
- Expected (consumer project): ONLY
.pas/workspace/ exists. No .pas/config.yaml, no .pas/processes/, no .pas/library/. Feedback defaults read from the plugin-level ${CLAUDE_PLUGIN_ROOT}/pas-config.yaml.
- Legacy (PAS ≤ 1.3.x consumer):
.pas/config.yaml + possibly .pas/processes/ with old process copies.
- Fix: Preserve
.pas/config.yaml (backward-compat still honored), but delete .pas/processes/ / .pas/library/ if they shadow skills that now come from an installed plugin. Back up first. Verify each process: if the plugin marketplace ships the same process, delete the consumer copy.
2. Workspace location (unchanged)
- Expected:
.pas/workspace/ exists and contains execution state.
- Legacy:
workspace/ at project root.
- Fix: Move
workspace/ to .pas/workspace/.
3. Marketplace context (new)
- Expected (maintainer workflow): When running
/pas:pas, cwd is inside a marketplace repository (has .claude-plugin/marketplace.json at its root).
- Legacy: cwd is inside a consumer project — PAS-the-skill refuses to run (use
/pas:pas from inside your marketplace instead; hooks still route feedback from anywhere).
- Fix: Either cd to your marketplace, or invoke the
bootstrap-marketplace skill to scaffold one.
4. No local library copy
- Expected: No
.pas/library/ directory (processes reference ${CLAUDE_PLUGIN_ROOT}/library/ directly)
- Legacy:
.pas/library/ or library/ with copied plugin skills
- Fix: Update thin launchers and process lifecycle sections to use
${CLAUDE_PLUGIN_ROOT}/library/, then remove the local library copy. Back up to .pas/library.bak/ before deleting.
5. Thin launcher references
- Expected:
.claude/skills/*/SKILL.md files reference ${CLAUDE_PLUGIN_ROOT}/library/orchestration/ for lifecycle and patterns
- Legacy: References to
.pas/library/orchestration/ or library/orchestration/
- Fix: Find and replace old library paths with
${CLAUDE_PLUGIN_ROOT}/library/ in each thin launcher
6. Process lifecycle references
- Expected:
process.md lifecycle sections reference ${CLAUDE_PLUGIN_ROOT}/library/orchestration/lifecycle.md
- Legacy: References to
.pas/library/orchestration/lifecycle.md
- Fix: Find and replace in each
process.md
Workflow
- Scan — Check each item in the checklist against the project
- Report — Show a table: item, status (OK/NEEDS FIX), what will change
- Confirm — Ask user: "Apply these fixes?" (never auto-apply without confirmation)
- Back up — Before modifying, copy affected files/dirs to
.bak suffixed locations
- Apply — Execute fixes in checklist order
- Verify — Re-scan to confirm all items now pass
- Report — Show final status: what changed, what was backed up
Key Principles
- Non-destructive: always back up before modifying
- Idempotent: running upgrade twice produces no changes the second time
- User confirms before any modifications
- Show before/after for each change
