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. Load details: Read("${CLAUDE_SKILL_DIR}/rules/detection-checks.md") 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. Load details: Read("${CLAUDE_SKILL_DIR}/rules/codebase-scan-patterns.md") for grep patterns and severity classification.

Phase 4: Scoring

Rate readiness 0-10 across 6 dimensions using the scoring rubric from platform-upgrade-knowledge . Load details: Read("${CLAUDE_SKILL_DIR}/references/scoring-rubric.md") for per-dimension thresholds, weights, and score interpretation.

Phase 5: Recommendations

Generate prioritized action items based on Phase 3 findings and Phase 4 scores. Load details: Read("${CLAUDE_SKILL_DIR}/references/recommendation-format.md") for priority assignment algorithm, effort estimation, and recommendation structure.

Output Format

The assessment produces a structured JSON report. Load details: Read("${CLAUDE_SKILL_DIR}/references/output-format.md") 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

Load on demand with Read("${CLAUDE_SKILL_DIR}/rules/<file>") :

Rule Impact What It Covers

detection-checks.md

HIGH Precondition checks, environment detection scripts

codebase-scan-patterns.md

HIGH Grep patterns, severity classification

knowledge-evaluation.md

HIGH 6-dimension scoring rubric, severity classification

knowledge-compatibility.md

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

Load on demand with Read("${CLAUDE_SKILL_DIR}/references/<file>") :

File Content

scoring-rubric.md

Detailed dimension scoring thresholds

recommendation-format.md

Priority assignment and effort estimation

output-format.md

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