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.8)
• 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.8)

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>"):

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>"):

• See platform-upgrade-knowledge/references/scoring-rubric.md for additional scoring details
• See platform-upgrade-knowledge/references/compatibility-matrix.md for version compatibility tracking

CC 2.1.47 Upgrade Guide

What Changed

CC 2.1.47 is the new minimum version for OrchestKit 6.0.x. This release includes platform fixes, new hook fields, and UX improvements.

Breaking Changes

None. CC 2.1.47 is backwards-compatible with all OrchestKit hooks and skills.

New Hook Input Fields

These fields are optional — hooks should always use input.field ?? fallback patterns.

Platform Fixes

Windows Support

• Hooks now execute on Windows via Git Bash (previously silently failed)
• Windows worktree session matching fixed (drive letter casing)
• PR #645 added Windows-safe spawning to prevent console flashing

Worktree Support

• Skills and agents are now discovered from worktrees (previously main checkout only)
• Background tasks (Task tool) complete successfully from worktrees
• Heartbeat and cleanup hooks work reliably in worktrees

SessionStart Deferral

• SessionStart hooks now fire ~500ms after session init
• All OrchestKit SessionStart hooks are compatible with this deferral
• Async hooks (unified-dispatcher, pr-status-enricher) are unaffected (already fire-and-forget)
• Sync hooks (session-context-loader, prefill-guard, mcp-health-check) still run before first prompt

UX Improvements

Agent Teams Improvements

• model field in agent frontmatter is now respected in team spawns
• Improved agent memory provides larger context for spawned agents
• TeammateIdle and TaskCompleted events available since CC 2.1.33

OrchestKit Adoption Summary

Hooks Updated

• monorepo-detector: Skips --add-dir suggestion when added_dirs already active
• session-summary: Tracks added_dirs_count and classifies session_outcome
• session-tracking: Passes added_dirs_count to session context
• session-cleanup: Includes last_msg_len and added_dirs_count in analytics
• session-context-loader: Scans added directories for context files
• subagent-stop/unified-dispatcher: Tracks last_msg_len in agent analytics
• auto-approve-project-writes: Already supports added_dirs (reference implementation)

Skills Updated

• doctor: Version compatibility matrix with all CC 2.1.47 features
• configure: Team plugin distribution docs
• worktree-coordination: CC 2.1.47 platform support table
• help: CC keyboard shortcuts reference

Runtime Utilities

• cc-version-matrix.ts: CC version constants (MIN_CC_VERSION, LATEST_KNOWN_CC) + compareCCVersions(). (The per-feature catalogue + hasFeature/getAvailableFeatures helpers were removed in #2229 — they had zero production callers; ork adopts features by use, not runtime gating.)

Verification

Run the doctor skill to verify your CC version:

/ork:doctor

Check 10 (Claude Code Version) validates CC >= 2.1.47 and reports missing features for older versions.

Rollback

If you need to downgrade below CC 2.1.47:

• OrchestKit hooks will continue to work in degraded mode
• added_dirs and last_assistant_message fields will be undefined (hooks handle this gracefully)
• Windows hook execution will fail silently
• Worktree discovery will not find skills/agents from worktrees

Output Format

The upgrade assessment produces a structured JSON report with the following schema.

JSON Report Schema

{
  "assessment": {
    "id": "upgrade-assessment-{timestamp}",
    "scope": "full|model-only|cc-only|ork-only",
    "timestamp": "2026-02-06T12:00:00Z"
  },
  "environment": {
    "current": {
      "model": "claude-sonnet-4-6",
      "ccVersion": "2.1.32",
      "orkVersion": "6.0.0",
      "hooks": 121,
      "skills": 199,
      "agents": 38
    },
    "target": {
      "model": "claude-opus-4-6",
      "ccVersion": "2.1.33",
      "orkVersion": "6.1.0"
    }
  },
  "scores": {
    "overall": 7.4,
    "dimensions": {
      "modelCompatibility": { "score": 8, "weight": 0.25, "weighted": 2.0 },
      "hookCompatibility": { "score": 9, "weight": 0.20, "weighted": 1.8 },
      "skillCoverage": { "score": 7, "weight": 0.15, "weighted": 1.05 },
      "agentReadiness": { "score": 7, "weight": 0.15, "weighted": 1.05 },
      "memoryArchitecture": { "score": 6, "weight": 0.10, "weighted": 0.6 },
      "cicdPipeline": { "score": 6, "weight": 0.15, "weighted": 0.9 }
    }
  },
  "findings": [
    {
      "severity": "CRITICAL",
      "dimension": "modelCompatibility",
      "description": "Hardcoded model ID 'claude-sonnet-4' in 3 agent files",
      "files": ["src/agents/code-reviewer.md", "src/agents/architect.md"],
      "recommendation": "Update model field to 'claude-opus-4-6' or use 'sonnet' alias"
    },
    {
      "severity": "WARNING",
      "dimension": "skillCoverage",
      "description": "Context window references assume 200K tokens, Opus 4.6 supports 1M",
      "files": ["src/skills/context-engineering/SKILL.md"],
      "recommendation": "Update token budget calculations for 1M context window"
    }
  ],
  "recommendations": [
    {
      "priority": "P0",
      "action": "Update hardcoded model references",
      "effort": "low",
      "files": ["src/agents/*.md"],
      "steps": [
        "Grep for 'claude-sonnet-4' and 'claude-opus-4' in src/",
        "Replace with target model ID or use alias",
        "Run npm run test:agents to validate"
      ]
    },
    {
      "priority": "P2",
      "action": "Update context budget calculations",
      "effort": "medium",
      "files": ["src/skills/context-engineering/SKILL.md"],
      "steps": [
        "Update MAX_CONTEXT values for new model",
        "Adjust compression triggers if context window changed",
        "Update documentation examples"
      ]
    }
  ],
  "summary": {
    "readiness": "Low Risk",
    "overallScore": 7.4,
    "blockers": 0,
    "criticalItems": 1,
    "totalFindings": 5,
    "estimatedEffort": "4-6 hours"
  }
}

Recommendation Format

Priority assignment, effort estimation, and recommendation structure for Phase 5 of upgrade assessment.

Priority Assignment Algorithm

Map dimension scores to priority levels:

For each finding from Phase 3:
  dimension_score = Phase 4 score for the finding's dimension

  if dimension_score <= 2:  priority = "P0"  # Blocker
  if dimension_score <= 4:  priority = "P1"  # Critical
  if dimension_score <= 6:  priority = "P2"  # Important
  if dimension_score <= 8:  priority = "P3"  # Nice-to-Have
  if dimension_score > 8:   # No action needed

Priority Levels

Effort Estimation

effort = "low"     # Single file, < 5 lines changed
effort = "medium"  # 2-5 files, or schema migration
effort = "high"    # 6+ files, or architectural change

Recommendation Structure

Each recommendation includes: 1. What: Description of the change needed 2. Why: Impact if not addressed 3. How: Specific steps or code changes 4. Effort: Low (< 1 hour), Medium (1-4 hours), High (4+ hours) 5. Files: List of affected files

Scoring Rubric

Detailed per-dimension scoring thresholds for Phase 4 of upgrade assessment.

Dimensions and Weights

Score Interpretation

Weighted Score Calculation

overall_score = sum(dimension_score * weight for each dimension)

Per-Dimension Scoring Thresholds

Score each dimension 0-10 based on Phase 3 findings:

Model Compatibility (weight: 0.25)

• 10: No hardcoded model IDs, no capability assumptions
• 8: Documentation-only model references (non-functional)
• 6: 1-3 hardcoded model IDs in functional code
• 4: Output token limits or context window hardcoded
• 2: Model-specific API patterns (e.g., prefilling for Claude, function calling format)
• 0: Core logic depends on model-specific behavior

Hook Compatibility (weight: 0.20)

• 10: All hooks use current event types and async patterns
• 8: Minor deprecation warnings, no functional impact
• 6: 1-3 hooks use deprecated event types
• 4: Hook input/output schema changed
• 2: Hook lifecycle order changed
• 0: Hook system replaced or fundamentally restructured

Skill Coverage (weight: 0.15)

• 10: All skills use current frontmatter format, no stale references
• 8: Minor version references outdated in skill content
• 6: 1-5 skills reference deprecated features or removed capabilities
• 4: Skill frontmatter schema changed (new required fields)
• 2: Skill loading mechanism changed
• 0: Skill format incompatible

Agent Readiness (weight: 0.15)

• 10: All agents use valid model aliases, tools, and frontmatter
• 8: 1-2 agents reference removed tools or deprecated fields
• 6: Agent model field values changed meaning
• 4: Agent frontmatter schema requires migration
• 2: Agent tool availability significantly changed
• 0: Agent system incompatible

Memory Architecture (weight: 0.10)

• 10: Memory tiers unchanged, storage format stable
• 8: New optional memory tier available
• 6: Memory storage format changed (migration available)
• 4: Memory tier behavior changed (e.g., scope semantics)
• 2: Memory migration required with data transformation
• 0: Memory system replaced

CI/CD Pipeline (weight: 0.15)

• 10: All tests pass, build system unchanged
• 8: Minor test assertion updates needed
• 6: Test framework or runner version update needed
• 4: Build configuration changes required
• 2: CI pipeline restructure needed
• 0: Build system incompatible

Rule Categories

1. Knowledge Evaluation (evaluation) — HIGH — 1 rule

Evaluating platform upgrade readiness with structured scoring across model, hooks, skills, agents, memory, and CI/CD dimensions.

• knowledge-evaluation.md — 6-dimension scoring rubric, weighted calculation, severity classification

2. Knowledge Compatibility (compatibility) — HIGH — 1 rule

Tracking compatibility across model versions, CC versions, and OrchestKit versions. Migration patterns and breaking change detection.

• knowledge-compatibility.md — Version compatibility matrix, breaking change patterns, migration effort estimation

3. Detection (detection) — HIGH — 1 rule

Precondition checks and environment detection scripts to verify upgrade readiness before scanning.

• detection-checks.md — Environment detection, version checks, precondition validation

4. Scanning (scanning) — HIGH — 1 rule

Grep patterns and severity classification for finding upgrade-impacted code across the codebase.

• codebase-scan-patterns.md — Pattern-based codebase scanning, severity classification, grep templates

[Rule Name]

[Brief description — 1-2 sentences.]

Incorrect:

// Bad pattern

Correct:

// Good pattern

Key rules:

• [Rule 1]
• [Rule 2]
• [Rule 3]

Reference: [link]

Codebase Scan Patterns

Grep patterns and severity classification for Phase 3 of upgrade assessment.

Scan Patterns

# 1. Model references (hardcoded model IDs)
grep -r "claude-opus-4\b\|claude-sonnet-4\b\|claude-haiku-3\b" src/ --include="*.md" --include="*.ts" --include="*.json"

# 2. Deprecated API patterns
grep -r "max_tokens_to_sample\|stop_sequences\|model.*claude-2" src/ --include="*.ts" --include="*.py"

# 3. CC version-gated features
grep -r "CC 2\.1\.\|claude-code.*2\.1\." src/ --include="*.md"

# 4. Hook compatibility (check for removed or renamed hook types)
grep -r "PreToolUse\|PostToolUse\|PermissionRequest\|Stop\|Notification" src/hooks/ --include="*.ts" --include="*.json"

# 5. Context window assumptions
grep -r "200000\|200_000\|128000\|128_000\|context.*window\|max_context" src/ --include="*.ts" --include="*.md" --include="*.py"

# 6. Output token assumptions
grep -r "max_tokens.*4096\|max_tokens.*8192\|max_output\|output.*limit" src/ --include="*.ts" --include="*.py"

Severity Classification

Classify each finding by severity:

• CRITICAL: Hardcoded model IDs, removed API fields, breaking hook changes
• WARNING: Outdated context window assumptions, deprecated patterns
• INFO: Version references in documentation, optional feature flags

Incorrect — Generic grep without severity classification creates unactionable scan reports:

grep -r "claude" src/
# 2000 matches with no classification or context

Correct — Targeted grep with severity classification produces actionable findings:

# CRITICAL: Hardcoded model IDs
grep -r "claude-opus-4\b\|claude-sonnet-4\b" src/ --include="*.ts"
# WARNING: Context window assumptions
grep -r "200000\|200_000" src/ --include="*.ts" --include="*.md"
# Each finding gets severity label for prioritization

Detection Checks

Precondition checks and environment detection for Phase 1 of upgrade assessment.

Precondition Checks

Before scanning, verify the environment is assessable:

# Verify we're in an OrchestKit project
[ -f CLAUDE.md ] || { echo "ERROR: No CLAUDE.md found — not an OrchestKit project"; exit 1; }
[ -d src/skills ] || { echo "ERROR: No src/skills/ directory"; exit 1; }
[ -d src/agents ] || { echo "ERROR: No src/agents/ directory"; exit 1; }
[ -f src/hooks/hooks.json ] || { echo "WARNING: No hooks.json — hook assessment will be skipped"; }

If any required directory is missing, abort with a clear error. If optional components (hooks) are missing, continue with reduced scope and note it in the report.

Environment Detection

Detect the current environment state:

# 1. Current Claude model
# Check CLAUDE.md, settings, or environment for model references
grep -r "claude-" CLAUDE.md .claude/ 2>/dev/null | head -20

# 2. Claude Code version
claude --version 2>/dev/null || echo "CC version not detectable from CLI"

# 3. OrchestKit version
# Check CLAUDE.md or package.json for version field
grep "Current.*:" CLAUDE.md | head -5

# 4. Hooks configuration
cat src/hooks/hooks.json | python3 -c "import sys,json; d=json.load(sys.stdin); print(f'Hooks: {len(d.get(\"hooks\",[]))} entries')" 2>/dev/null

# 5. Skill and agent counts
ls src/skills/ | wc -l
ls src/agents/ | wc -l

Expected Output

Environment snapshot including:

• Current model ID (e.g., claude-sonnet-4-6)
• Current CC version (e.g., 2.1.33)
• Current OrchestKit version (e.g., 6.0.0)
• Hook count and bundle count
• Skill count and agent count

Incorrect — Running scans without precondition checks produces invalid results:

# No environment verification
grep -r "claude-" src/  # Scans in non-OrchestKit project
# False positives and missed files

Correct — Precondition checks ensure valid assessment environment:

# Verify OrchestKit project structure
[ -f CLAUDE.md ] && [ -d src/skills ] || exit 1
# Only scan if structure is valid
grep -r "claude-" src/skills/ --include="*.md"

Platform Compatibility Knowledge

Track compatibility across three independent upgrade axes: Claude model, Claude Code version, and OrchestKit version.

Model ID Breaking Pattern

Model ID format changed from claude-{version}-{variant} to claude-{variant}-{version} starting with Claude 4:

Common Breaking Changes

Migration Effort Estimation

Effort Formula

total_hours = sum(
  count[CRITICAL] * 2.0 +
  count[WARNING]  * 0.5 +
  count[INFO]     * 0.1
)

Key Rules

• Scan first, upgrade second — run codebase scan before making any changes
• Hardcoded model IDs are always CRITICAL — use aliases where possible
• Context window and output limits change across models — never hardcode
• Hook type and format changes can silently break — test all hooks after upgrade
• Use the detection patterns above as a pre-upgrade checklist
• Track each axis independently — model, CC version, and OrchestKit can upgrade separately
• CC 2.1.50 includes 8 memory leak fixes — long sessions (4+ hours) that previously degraded should be retested after upgrading
• CC 2.1.63 adds HTTP hooks, worktree config sharing, /simplify (renamed /code-review in 2.1.146), /batch, teammate memory fix, and ENABLE_CLAUDEAI_MCP_SERVERS env var
• See the full CC version matrix for feature-by-feature compatibility

Incorrect — Hardcoded model ID breaks when upgrading to new Claude version:

const response = await anthropic.messages.create({
  model: "claude-opus-4-20250514",  // Breaks when 4.6 becomes default
  max_tokens: 4096,
});

Correct — Model alias and variable config survives upgrades:

const response = await anthropic.messages.create({
  model: process.env.CLAUDE_MODEL || "claude-opus-latest",
  max_tokens: settings.maxOutputTokens,
});

Platform Upgrade Evaluation

Score upgrade readiness 0-10 across 6 weighted dimensions. Produces a composite score that determines go/no-go.

Scoring Dimensions

Score Interpretation

Severity Classification

Priority Assignment

dimension_score <= 2:  priority = P0 (Blocker)    — Before upgrade
dimension_score <= 4:  priority = P1 (Critical)   — Same sprint
dimension_score <= 6:  priority = P2 (Important)  — Next sprint
dimension_score <= 8:  priority = P3 (Nice-to-Have) — Backlog
dimension_score > 8:   No action needed

Key Rules

• Score every dimension even if it seems fine — assumptions hide breaking changes
• CRITICAL findings are blockers — do not upgrade until resolved
• Weighted composite score determines overall readiness
• P0 items must be addressed before starting the upgrade
• Re-score after addressing findings to verify improvement

Incorrect — Upgrading without evaluation causes production breakage:

# Just upgrade without assessment
npm install @anthropic-ai/claude-code@latest
git commit -m "upgrade claude"
# Production breaks: hardcoded model IDs, hook changes, context limits

Correct — Structured evaluation identifies blockers before upgrade:

# Phase 1: Detect environment
./detect-environment.sh
# Phase 2: Score dimensions (finds 3 CRITICAL issues)
./score-compatibility.sh
# Phase 3: Fix P0 blockers BEFORE upgrade
./fix-model-refs.sh && ./migrate-hooks.sh
# Then upgrade safely