upgrade-assessment

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?

1. Full platform - Model + CC version + OrchestKit (comprehensive)
2. Model only - Switching Claude model (e.g., Sonnet 4.5 to Opus 4.6)
3. CC version only - Claude Code version bump (e.g., 2.1.32 to 2.1.33)
4. 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:

1. Model changes: Search for target model capabilities, breaking changes, new tool support
2. CC version changes: Search for changelog, new hook types, skill format changes, deprecated fields
3. 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