AgentSkillsCN

framework_version_check

验证claude.md和claude-reference.md之间的版本同步，以确保框架文档的一致性并检测版本漂移

SKILL.md
--- frontmatter
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.0

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

markdown
### 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

markdown
### 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

markdown
### 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

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

2. Extract Version from claude-reference.md

bash
# 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:

markdown
## 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:

markdown
### 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