framework-version-check

name	framework_version_check
description	Validate version synchronization between claude.md and claude-reference.md to ensure framework documentation consistency and detect version drift
schema_version	1

framework_version_check

Type: ANALYSIS-ONLY DAIC Modes: DISCUSS, ALIGN, IMPLEMENT, CHECK (all modes) Priority: Medium

Trigger Reference

This skill activates on:

• Keywords: "framework version", "claude.md version", "version mismatch", "version sync", "framework sync"
• Intent patterns: "check.?framework.?version", "version.*?(mismatch|sync|drift)"

From: skill-rules.json - framework_version_check configuration

Purpose

Validate version synchronization between claude.md and claude-reference.md to ensure framework documentation consistency. This is an ANALYSIS-ONLY skill that detects version drift and recommends REPAIR tasks when needed.

Core Behavior

In any DAIC mode (DISCUSS, ALIGN, IMPLEMENT, CHECK):

1. Version Sync Validation

   • Read claude.md header for Framework Version and Last Updated
   • Read claude-reference.md header for Framework Version and Last Updated
   • Compare versions and dates for consistency
   • Report sync status (matched, mismatched, or missing file)

2. Drift Detection

   • Identify which file has newer version
   • Detect date mismatches even if version matches
   • Flag missing claude-reference.md file
   • Warn about partial version information

3. REPAIR Task Recommendation

   • Suggest creating REPAIR- task for version drift
   • Provide context for the REPAIR task
   • Recommend which file should be authoritative
   • Guide conflict resolution process

4. Preventive Guidance

   • Remind to update both files when framework changes
   • Suggest version bump strategy (2.0 → 2.1, etc.)
   • Recommend including version in LCMP decisions.md

Safety Guardrails

ANALYSIS-ONLY RULES:

• ✓ NEVER call write tools (Edit, Write, MultiEdit)
• ✓ NEVER auto-fix version mismatches
• ✓ NEVER modify framework files directly
• ✓ Only provide analysis and recommendations
• ✓ Safe to run in any DAIC mode

Version Checking Rules:

• Always check BOTH files before reporting
• Handle missing files gracefully
• Never assume which file is authoritative
• Always recommend user decide resolution path
• Log version checks in context when significant

Examples

When to Activate

✓ "Check framework version sync" ✓ "Are claude.md and claude-reference.md in sync?" ✓ "I updated claude.md, did I forget something?" ✓ User is starting a new task (auto-check from Section 0.1) ✓ "Validate framework version"

Typical Output

Scenario 1: Versions Match

### Framework Version Check: ✓ SYNCED

**claude.md**
- Framework Version: 2.0
- Last Updated: 2025-11-15

**claude-reference.md**
- Framework Version: 2.0
- Last Updated: 2025-11-15

**Status:** Both files are synchronized. Proceeding normally.

Scenario 2: Version Drift Detected

### Framework Version Check: ⚠️ DRIFT DETECTED

**claude.md**
- Framework Version: 2.1
- Last Updated: 2025-11-15

**claude-reference.md**
- Framework Version: 2.0
- Last Updated: 2025-11-10

**Issue:** Framework docs appear out of sync. claude.md is newer (v2.1) while claude-reference.md is still v2.0.

**Recommendation:**
Create a REPAIR-framework-sync task to:
1. Compare both files to understand what changed
2. Determine which version is authoritative
3. Update the other file to match
4. Log the resolution in context/gotchas.md

**Action:**
Would you like me to suggest a REPAIR task manifest?

Scenario 3: Missing claude-reference.md

### Framework Version Check: ⚠️ INCOMPLETE

**claude.md**
- Framework Version: 2.0
- Last Updated: 2025-11-15

**claude-reference.md**
- Status: File not found

**Issue:** claude-reference.md is missing. The framework expects both files to exist.

**Recommendations:**
1. **If intentional:** Document in claude.md why claude-reference.md is not needed
2. **If unintentional:** Create claude-reference.md or locate it
3. **If renamed/moved:** Update claude.md Section 0.1 with new path

**Next Steps:**
- Verify if claude-reference.md should exist
- Create REPAIR task if framework structure changed

When NOT to Activate

✗ User is asking about application version (not framework version) ✗ Question is about git version/commits ✗ Focus is on dependency versions (package.json) ✗ General version control questions

Version Check Procedure

1. Extract Version from claude.md

# Line 2-3 format:
# Framework Version: 2.0
# Last Updated: 2025-11-15

2. Extract Version from claude-reference.md

# Same format in header

3. Compare

• Version numbers must match exactly (e.g., "2.0" === "2.0")
• Dates should match or be very close
• Both fields must be present

4. Report Findings

• Match: ✓ Proceed normally
• Mismatch: ⚠️ Suggest REPAIR task
• Missing: ⚠️ Explain issue, suggest resolution

REPAIR Task Template

When version drift detected, suggest this task structure:

## Task: REPAIR-framework-sync-2025-11-15

### Problem
Framework version mismatch detected:
- claude.md: v2.1 (2025-11-15)
- claude-reference.md: v2.0 (2025-11-10)

### Goals
1. Determine which version is authoritative
2. Identify what changed between versions
3. Update out-of-sync file to match
4. Document resolution

### Approach
1. Read both files completely
2. Diff to find changes
3. Decide: Is v2.1 correct? Or is v2.0 correct?
4. Update the other file
5. Log in context/gotchas.md what caused the drift
6. Suggest preventive measures

### Success Criteria
- Both files show same version and date
- Changes are semantically consistent
- Drift cause documented
- Prevention strategy noted

Integration with Task Startup

Per claude.md Section 0.1, this skill should activate automatically when:

• Starting a new cc-sessions task
• User explicitly requests version check
• Framework files are being modified

Decision Logging

When significant version drift is detected:

### Framework Version Drift: [Date]
- **Detected:** claude.md v2.1, claude-reference.md v2.0
- **Resolution:** Created REPAIR-framework-sync task
- **Root Cause:** claude.md updated during REPAIR-write-gating but claude-reference.md forgotten
- **Prevention:** Add to REPAIR task checklist: "Update both framework files"

Related Skills

• framework_health_check - For broader framework validation
• framework_repair_suggester - To create REPAIR tasks for drift
• skill-developer - If skill system version checking needed
• cc-sessions-core - If version checking logic needs enhancement

---

Last Updated: 2025-11-15 Framework Version: 2.0