Upgrade Assessment

Evaluate platform upgrade readiness for Claude model transitions, Claude Code version bumps, and OrchestKit plugin updates. Produces a structured JSON assessment report with a 0-10 readiness score across 6 dimensions.

When to Use

Before upgrading the Claude model (e.g., Sonnet 4 to Opus 4.6)
Before upgrading Claude Code to a new major/minor version
Before upgrading OrchestKit to a new major version
When evaluating whether a team environment is ready for a platform change
As part of release planning for model or platform migrations

Quick Start

/ork:upgrade-assessment           # Interactive assessment
/ork:upgrade-assessment --json    # Machine-readable output

6-Phase Workflow

Phase 0: Scope Definition

Tool: AskUserQuestion

Determine the assessment scope before scanning. Ask the user:

What type of upgrade are you assessing?

Full platform - Model + CC version + OrchestKit (comprehensive)

Model only - Switching Claude model (e.g., Sonnet 4.5 to Opus 4.6)

CC version only - Claude Code version bump (e.g., 2.1.32 to 2.1.33)

OrchestKit only - Plugin version upgrade (e.g., 5.x to 6.x)

Record the scope and target versions. If the user does not specify target versions, research the latest available in Phase 2.

Phase 1: Detection

Tools: Bash, Read, Grep, Glob

Run precondition checks and environment detection. See Detection Checks for verification scripts and expected output format.

Phase 2: Research

Tools: WebSearch, WebFetch

Research the target versions for new capabilities and breaking changes:

Model changes: Search for target model capabilities, breaking changes, new tool support
CC version changes: Search for changelog, new hook types, skill format changes, deprecated fields
OrchestKit changes: Read CHANGELOG.md, identify new/removed/renamed skills, hook migration needs

Research queries:

"Claude {target_model} capabilities release notes"
"Claude Code {target_version} changelog breaking changes"
"Claude {target_model} vs {current_model} differences"

Phase 3: Codebase Scan

Tools: Grep, Glob, Read

Scan the codebase for patterns affected by the upgrade. See Codebase Scan Patterns for grep patterns and severity classification.

Phase 4: Scoring

Rate readiness 0-10 across 6 dimensions using the scoring rubric from platform-upgrade-knowledge. See Scoring Rubric for per-dimension thresholds, weights, and score interpretation.

Phase 5: Recommendations

Generate prioritized action items based on Phase 3 findings and Phase 4 scores. See Recommendation Format for priority assignment algorithm, effort estimation, and recommendation structure.

Output Format

The assessment produces a structured JSON report. See Output Format for the full schema and example.

Execution Notes

For Model-Only Upgrades

Focus on Phases 1, 2, and 3. Key areas:

Agent model: fields
Context window / output token assumptions
Capability-dependent skill content (e.g., vision, audio)

For CC Version Upgrades

Focus on hook compatibility and skill format:

Hook type registry changes
Skill frontmatter field additions/removals
Permission rule format changes
New built-in tools or removed tools

For OrchestKit Upgrades

Focus on plugin structure:

Manifest schema changes
Build system changes
Skill/agent rename or removal
Hook source reorganization

Rules Quick Reference

Rule	Impact	What It Covers
detection-checks	HIGH	Precondition checks, environment detection scripts
codebase-scan-patterns	HIGH	Grep patterns, severity classification
knowledge-evaluation	HIGH	6-dimension scoring rubric, severity classification
knowledge-compatibility	HIGH	Version compatibility matrix, breaking change detection

Related Skills

platform-upgrade-knowledge - Scoring rubric details and compatibility matrix
ork:doctor - Post-upgrade health validation
ork:explore - Codebase exploration for impact analysis
ork:verify - Verification of changes after migration
ork:devops-deployment - CI/CD pipeline updates

References

Scoring Rubric - Detailed dimension scoring thresholds
Recommendation Format - Priority assignment and effort estimation
Output Format - JSON report schema and example
See platform-upgrade-knowledge/references/scoring-rubric.md for additional scoring details
See platform-upgrade-knowledge/references/compatibility-matrix.md for version compatibility tracking