cc-devflow 4.1.6 → 4.3.0

package/.claude/skills/utility/npm-release/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: npm-release
-description: Use when ready to publish a new version of cc-devflow npm package to npm registry
+description: Use when ready to publish a new version of cc-devflow npm package to npm registry. Enforces semantic versioning rules, prevents arbitrary version jumps (e.g., 3.0.1→7.0.0), and ensures atomic synchronization across package.json, CHANGELOG.md, and git tags.
 ---
 
 # NPM Release Workflow
@@ -9,7 +9,10 @@ description: Use when ready to publish a new version of cc-devflow npm package t
 
 Standardized release process for cc-devflow npm package ensuring consistent versioning, changelog maintenance, and safe publishing.
 
-**Core Principle**: Atomic release - all version markers (package.json, CHANGELOG.md, git tag) must stay in sync.
+**Core Principles**:
+1. **Atomic release** - All version markers (package.json, CHANGELOG.md, git tag) stay in sync
+2. **Semantic versioning enforcement** - Prevents arbitrary jumps and format inconsistencies
+3. **Decision tree validation** - Every version bump follows explicit SemVer rules
 
 ## When to Use
 
@@ -24,18 +27,57 @@ Don't use when:
 - ❌ Not on main branch
 - ❌ Pre-release/beta versions (needs adaptation)
 
-## Release Types
+## Version Decision Protocol
+
+**MANDATORY**: Before any version bump, determine change type using the decision tree.
+
+See [references/version-decision-guide.md](references/version-decision-guide.md) for detailed rules and examples.
+
+### Quick Decision Tree
+
+```
+Is this a breaking change?
+├─ YES → MAJOR bump (X.0.0)
+└─ NO → Is this a new feature?
+    ├─ YES → MINOR bump (X.Y.0)
+    └─ NO → PATCH bump (X.Y.Z)
+```
+
+### Release Types
 
 Follow [Semantic Versioning](https://semver.org/):
 
 | Type | Version Change | When |
 |------|---------------|------|
-| **Patch** | 2.4.3 → 2.4.4 | Bug fixes, minor improvements |
-| **Minor** | 2.4.4 → 2.5.0 | New features, backward compatible |
-| **Major** | 2.5.0 → 3.0.0 | Breaking changes |
+| **Patch** | 4.2.0 → 4.2.1 | Bug fixes, minor improvements |
+| **Minor** | 4.2.1 → 4.3.0 | New features, backward compatible |
+| **Major** | 4.3.0 → 5.0.0 | Breaking changes |
+
+### Anti-Patterns (FORBIDDEN)
+
+❌ **Arbitrary jumps**: 3.0.1 → 7.0.0 (no justification)
+❌ **Skipping versions**: 4.2.0 → 4.4.0 (skipped 4.3.0)
+❌ **Inconsistent formats**: v1.0, 1.0.0, release-1.0 (mixed formats)
 
 ## Complete Workflow
 
+### Phase 0: Version Validation (MANDATORY)
+
+**Before any changes**, validate current state and determine next version:
+
+```bash
+# 1. Validate version synchronization
+bash .claude/skills/utility/npm-release/scripts/validate-version-sync.sh
+
+# 2. Determine change type (patch/minor/major)
+# Use decision tree in references/version-decision-guide.md
+
+# 3. Calculate next version
+bash .claude/skills/utility/npm-release/scripts/version-decision-tree.sh $(grep -o '"version": *"[^"]*"' package.json | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+') <patch|minor|major>
+```
+
+**STOP if validation fails** - Fix inconsistencies before proceeding.
+
 ### Phase 1: Pre-Release Checks
 
 ```bash
@@ -45,7 +87,7 @@ git status
 
 # 2. Check current version
 cat package.json | grep version
-# e.g., "version": "2.4.3"
+# e.g., "version": "4.2.0"
 
 # 3. Review recent changes
 git log --oneline -10
@@ -56,9 +98,29 @@ git log --oneline -10
 - Uncommitted changes exist
 - Unpushed commits exist
 
-### Phase 2: Version Updates
+### Phase 2: Atomic Version Bump
+
+**Use the atomic bump script** (recommended):
+
+```bash
+# Automatically updates package.json + CHANGELOG.md
+bash .claude/skills/utility/npm-release/scripts/atomic-version-bump.sh <patch|minor|major> "Brief description"
+
+# Example:
+bash .claude/skills/utility/npm-release/scripts/atomic-version-bump.sh minor "Add export command"
+```
+
+**Or manual update** (if script unavailable):
+
+**Step 1: Update package.json**
+
+```bash
+npm version patch --no-git-tag-version  # For patch release
+npm version minor --no-git-tag-version  # For minor release
+npm version major --no-git-tag-version  # For major release
+```
 
-**Step 1: Update CHANGELOG.md**
+**Step 2: Update CHANGELOG.md**
 
 Add new version section at the top (after `---`):
 
@@ -78,22 +140,6 @@ Brief description of main changes.
 - ✅ Benefit 2
 ```
 
-**Step 2: Update package.json**
-
-```bash
-# Manually edit or use npm version
-npm version patch --no-git-tag-version  # For patch release
-npm version minor --no-git-tag-version  # For minor release
-npm version major --no-git-tag-version  # For major release
-```
-
-Or edit directly:
-```json
-{
-  "version": "X.Y.Z"
-}
-```
-
 ### Phase 3: Git Operations
 
 **Step 1: Create Release Commit**
@@ -188,56 +234,75 @@ npm view cc-devflow version
 
 | Step | Command | Purpose |
 |------|---------|---------|
+| **Validate sync** | `bash scripts/validate-version-sync.sh` | Check version consistency |
+| **Decide version** | `bash scripts/version-decision-tree.sh <current> <type>` | Calculate next version |
+| **Atomic bump** | `bash scripts/atomic-version-bump.sh <type> "desc"` | Update all markers |
 | Check status | `git status` | Verify clean state |
 | Check version | `grep version package.json` | Current version |
-| Bump version | Edit package.json | Update version number |
-| Update changelog | Edit CHANGELOG.md | Document changes |
 | Create commit | `git commit -m "chore(release): ..."` | Commit version bump |
 | Create tag | `git tag -a vX.Y.Z -m "..."` | Tag release |
 | Push commits | `git push origin main` | Push to GitHub |
 | Push tags | `git push origin vX.Y.Z` | Push tag to GitHub |
 | Publish npm | `npm publish` | Publish to registry |
 
+## Version Management Scripts
+
+Three scripts enforce version discipline:
+
+1. **validate-version-sync.sh** - Checks package.json, git tags, CHANGELOG.md consistency
+2. **version-decision-tree.sh** - Calculates next version following SemVer rules
+3. **atomic-version-bump.sh** - Updates all version markers atomically
+
+**Usage**:
+```bash
+# Check current state
+bash .claude/skills/utility/npm-release/scripts/validate-version-sync.sh
+
+# Calculate next version
+bash .claude/skills/utility/npm-release/scripts/version-decision-tree.sh 4.2.0 minor
+# Output: 4.3.0
+
+# Atomic bump (recommended)
+bash .claude/skills/utility/npm-release/scripts/atomic-version-bump.sh minor "Add export command"
+```
+
 ## Common Mistakes
 
-### ❌ Mistake 1: Forgetting to Update CHANGELOG.md
+### ❌ Mistake 1: Arbitrary Version Jumps
 
-**Problem**: Version bumped but no changelog entry
+**Problem**: Version jumps from 3.0.1 to 7.0.0 without justification
 
-**Fix**: Always update CHANGELOG.md BEFORE committing
+**Fix**: Use version-decision-tree.sh to calculate correct next version based on change type
 
 ### ❌ Mistake 2: Inconsistent Version Numbers
 
-**Problem**: package.json shows 2.4.4 but CHANGELOG.md shows 2.4.3
+**Problem**: package.json shows 4.2.1 but CHANGELOG.md shows 4.2.0
+
+**Fix**: Use atomic-version-bump.sh to update all markers simultaneously
+
+### ❌ Mistake 3: Forgetting to Update CHANGELOG.md
+
+**Problem**: Version bumped but no changelog entry
 
-**Fix**: Double-check all version numbers match before committing
+**Fix**: Always update CHANGELOG.md BEFORE committing (atomic-version-bump.sh does this automatically)
 
-### ❌ Mistake 3: Pushing Tag Before Commit
+### ❌ Mistake 4: Pushing Tag Before Commit
 
 **Problem**: Tag points to wrong commit
 
 **Fix**: Always commit first, then tag, then push both together
 
-### ❌ Mistake 4: Not Testing npm publish
+### ❌ Mistake 5: Not Testing npm publish
 
 **Problem**: Published package is broken
 
 **Fix**: Run `npm publish --dry-run` first to catch issues
 
-### ❌ Mistake 5: Network Timeout During Push
+### ❌ Mistake 6: Inconsistent Tag Format
 
-**Problem**: `Failed to connect to github.com port 443`
+**Problem**: Mixed formats like v1.0, 1.0.0, release-1.0
 
-**Fix**:
-```bash
-# Option 1: Retry after network stabilizes
-git push origin main
-git push origin vX.Y.Z
-
-# Option 2: Switch to SSH (if HTTPS blocked)
-git remote set-url origin git@github.com:Dimon94/cc-devflow.git
-git push origin main
-```
+**Fix**: Always use vX.Y.Z format (e.g., v4.2.0). validate-version-sync.sh detects format inconsistencies
 
 ## Network Troubleshooting
 

package/.claude/skills/utility/npm-release/references/version-decision-guide.md

@@ -0,0 +1,134 @@
+# Version Decision Reference
+
+## Semantic Versioning Rules
+
+**Format**: `MAJOR.MINOR.PATCH` (e.g., 4.2.0)
+
+### When to Bump Each Number
+
+| Version | Increment When | Examples |
+|---------|---------------|----------|
+| **MAJOR** | Breaking changes that require user action | API redesign, removed features, incompatible changes |
+| **MINOR** | New features, backward compatible | New commands, new options, enhanced functionality |
+| **PATCH** | Bug fixes, minor improvements | Fix crashes, improve error messages, documentation |
+
+### Decision Tree
+
+```
+Is this a breaking change?
+├─ YES → MAJOR bump (X.0.0)
+└─ NO → Is this a new feature?
+    ├─ YES → MINOR bump (X.Y.0)
+    └─ NO → PATCH bump (X.Y.Z)
+```
+
+## Common Scenarios
+
+### Scenario 1: Bug Fix
+**Current**: 4.2.0
+**Change**: Fix login crash
+**Decision**: PATCH → **4.2.1**
+
+### Scenario 2: New Feature (Compatible)
+**Current**: 4.2.1
+**Change**: Add `/flow:export` command
+**Decision**: MINOR → **4.3.0**
+
+### Scenario 3: Breaking Change
+**Current**: 4.3.0
+**Change**: Remove deprecated `/flow-new` command
+**Decision**: MAJOR → **5.0.0**
+
+### Scenario 4: Multiple Changes
+**Current**: 4.3.0
+**Changes**:
+- Fix 3 bugs (PATCH)
+- Add 2 new features (MINOR)
+- No breaking changes
+
+**Decision**: Take highest level → MINOR → **4.4.0**
+
+## Anti-Patterns (FORBIDDEN)
+
+### ❌ Arbitrary Jumps
+```
+3.0.1 → 7.0.0  # WRONG: No justification for jumping 4 major versions
+```
+
+**Correct**:
+```
+3.0.1 → 4.0.0  # If breaking change
+3.0.1 → 3.1.0  # If new feature
+3.0.1 → 3.0.2  # If bug fix
+```
+
+### ❌ Skipping Versions
+```
+4.2.0 → 4.4.0  # WRONG: Skipped 4.3.0
+```
+
+**Correct**:
+```
+4.2.0 → 4.3.0 → 4.4.0  # Sequential
+```
+
+### ❌ Inconsistent Formats
+```
+v1.0          # WRONG: Missing patch
+1.0.0         # WRONG: Missing 'v' prefix in git tag
+release-1.0   # WRONG: Non-standard format
+```
+
+**Correct**:
+```
+Git tag:      v4.2.0
+package.json: "version": "4.2.0"
+CHANGELOG:    ## [4.2.0] - 2026-03-12
+```
+
+## Version Validation Checklist
+
+Before bumping version, verify:
+
+- [ ] Change type is clear (patch/minor/major)
+- [ ] Version increment follows SemVer rules
+- [ ] No arbitrary jumps (e.g., 3.x → 7.x)
+- [ ] All version markers will be updated atomically
+- [ ] CHANGELOG.md entry prepared
+- [ ] Git tag format will be `vX.Y.Z`
+
+## Breaking Change Examples
+
+**Breaking changes require MAJOR bump**:
+
+- Removing commands or options
+- Changing command syntax
+- Changing output format (breaking scripts)
+- Removing configuration options
+- Changing default behavior significantly
+- Requiring new dependencies
+- Dropping support for Node versions
+
+**NOT breaking changes** (MINOR or PATCH):
+
+- Adding new commands (MINOR)
+- Adding new options with defaults (MINOR)
+- Deprecation warnings (MINOR)
+- Bug fixes (PATCH)
+- Performance improvements (PATCH)
+- Documentation updates (PATCH)
+
+## Version History Analysis
+
+Use this to understand past version decisions:
+
+```bash
+# View version history
+git tag --sort=v:refname
+
+# View changes between versions
+git log v4.1.0..v4.2.0 --oneline
+
+# Check CHANGELOG for version rationale
+grep -A 10 "## \[4.2.0\]" CHANGELOG.md
+```

package/.claude/skills/utility/npm-release/scripts/atomic-version-bump.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# Atomic Version Bump - Updates all version markers in one transaction
+# Ensures package.json, CHANGELOG.md stay in sync
+
+set -euo pipefail
+
+CHANGE_TYPE="${1:-}"
+CHANGE_DESCRIPTION="${2:-}"
+
+if [[ -z "$CHANGE_TYPE" ]]; then
+    echo "Usage: $0 <patch|minor|major> [description]"
+    echo ""
+    echo "Examples:"
+    echo "  $0 patch 'Fix login bug'"
+    echo "  $0 minor 'Add user dashboard'"
+    echo "  $0 major 'Redesign API'"
+    exit 1
+fi
+
+# Get script directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# 1. Get current version
+CURRENT_VERSION=$(grep -o '"version": *"[^"]*"' package.json | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+')
+echo "📦 Current version: $CURRENT_VERSION"
+
+# 2. Calculate next version using decision tree
+NEXT_VERSION=$("$SCRIPT_DIR/version-decision-tree.sh" "$CURRENT_VERSION" "$CHANGE_TYPE")
+echo "🎯 Next version: $NEXT_VERSION"
+
+# 3. Validate version sync before proceeding
+echo ""
+echo "🔍 Pre-flight validation..."
+if ! "$SCRIPT_DIR/validate-version-sync.sh"; then
+    echo ""
+    echo "❌ Version sync validation failed. Fix inconsistencies before bumping."
+    exit 1
+fi
+
+# 4. Update package.json
+echo ""
+echo "📝 Updating package.json..."
+sed -i.bak "s/\"version\": \"$CURRENT_VERSION\"/\"version\": \"$NEXT_VERSION\"/" package.json
+rm package.json.bak
+
+# 5. Prepare CHANGELOG.md entry
+CURRENT_DATE=$(date +%Y-%m-%d)
+CHANGELOG_ENTRY="## [$NEXT_VERSION] - $CURRENT_DATE
+
+### 🎯 ${CHANGE_DESCRIPTION:-Version $NEXT_VERSION}
+
+#### Changed
+- TODO: Add change details
+
+---
+
+"
+
+# Insert after the first "---" line in CHANGELOG.md
+if [[ -f "CHANGELOG.md" ]]; then
+    echo "📝 Updating CHANGELOG.md..."
+    # Create temp file with new entry
+    awk -v entry="$CHANGELOG_ENTRY" '
+        /^---$/ && !inserted {
+            print
+            print entry
+            inserted=1
+            next
+        }
+        {print}
+    ' CHANGELOG.md > CHANGELOG.md.tmp
+    mv CHANGELOG.md.tmp CHANGELOG.md
+else
+    echo "⚠️  CHANGELOG.md not found, skipping"
+fi
+
+# 6. Validate post-update
+echo ""
+echo "🔍 Post-update validation..."
+UPDATED_VERSION=$(grep -o '"version": *"[^"]*"' package.json | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+')
+
+if [[ "$UPDATED_VERSION" != "$NEXT_VERSION" ]]; then
+    echo "❌ Version update failed: expected $NEXT_VERSION, got $UPDATED_VERSION"
+    exit 1
+fi
+
+echo ""
+echo "✅ Version bumped successfully: $CURRENT_VERSION → $NEXT_VERSION"
+echo ""
+echo "📋 Next steps:"
+echo "   1. Edit CHANGELOG.md to add detailed changes"
+echo "   2. Review changes: git diff"
+echo "   3. Commit: git add package.json CHANGELOG.md && git commit -m 'chore(release): bump version to $NEXT_VERSION'"
+echo "   4. Tag: git tag -a v$NEXT_VERSION -m 'Release v$NEXT_VERSION'"
+echo "   5. Push: git push origin main && git push origin v$NEXT_VERSION"

package/.claude/skills/utility/npm-release/scripts/validate-version-sync.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# Version Sync Validator - Ensures all version markers are consistent
+# Checks: package.json, git tags, CHANGELOG.md
+
+set -euo pipefail
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+ERRORS=0
+
+echo "🔍 Validating version synchronization..."
+echo ""
+
+# 1. Extract version from package.json
+if [[ ! -f "package.json" ]]; then
+    echo -e "${RED}❌ package.json not found${NC}"
+    exit 1
+fi
+
+PKG_VERSION=$(grep -o '"version": *"[^"]*"' package.json | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+')
+echo "📦 package.json version: $PKG_VERSION"
+
+# 2. Check latest git tag
+LATEST_TAG=$(git tag --sort=-v:refname | head -1 || echo "")
+if [[ -z "$LATEST_TAG" ]]; then
+    echo -e "${YELLOW}⚠️  No git tags found${NC}"
+else
+    TAG_VERSION="${LATEST_TAG#v}"  # Remove 'v' prefix
+    echo "🏷️  Latest git tag: $LATEST_TAG ($TAG_VERSION)"
+
+    if [[ "$PKG_VERSION" != "$TAG_VERSION" ]]; then
+        echo -e "${RED}❌ Version mismatch: package.json ($PKG_VERSION) != git tag ($TAG_VERSION)${NC}"
+        ((ERRORS++))
+    else
+        echo -e "${GREEN}✅ package.json and git tag match${NC}"
+    fi
+fi
+
+# 3. Check CHANGELOG.md
+if [[ ! -f "CHANGELOG.md" ]]; then
+    echo -e "${YELLOW}⚠️  CHANGELOG.md not found${NC}"
+else
+    # Extract first version from CHANGELOG (after the header)
+    # macOS grep doesn't support -P, use sed instead
+    CHANGELOG_VERSION=$(sed -n 's/^## \[\([0-9]\+\.[0-9]\+\.[0-9]\+\)\].*/\1/p' CHANGELOG.md | head -1)
+
+    if [[ -z "$CHANGELOG_VERSION" ]]; then
+        echo -e "${YELLOW}⚠️  No version found in CHANGELOG.md${NC}"
+    else
+        echo "📝 CHANGELOG.md latest: $CHANGELOG_VERSION"
+
+        if [[ "$PKG_VERSION" != "$CHANGELOG_VERSION" ]]; then
+            echo -e "${RED}❌ Version mismatch: package.json ($PKG_VERSION) != CHANGELOG.md ($CHANGELOG_VERSION)${NC}"
+            ((ERRORS++))
+        else
+            echo -e "${GREEN}✅ package.json and CHANGELOG.md match${NC}"
+        fi
+    fi
+fi
+
+# 4. Check for version format consistency in git tags
+echo ""
+echo "🔍 Checking git tag format consistency..."
+INCONSISTENT_TAGS=$(git tag | grep -v '^v[0-9]\+\.[0-9]\+\.[0-9]\+$' || true)
+if [[ -n "$INCONSISTENT_TAGS" ]]; then
+    echo -e "${YELLOW}⚠️  Found tags with inconsistent format:${NC}"
+    echo "$INCONSISTENT_TAGS" | sed 's/^/   /'
+    echo -e "${YELLOW}   Expected format: vX.Y.Z (e.g., v4.2.0)${NC}"
+fi
+
+echo ""
+if [[ $ERRORS -eq 0 ]]; then
+    echo -e "${GREEN}✅ All version markers are synchronized${NC}"
+    exit 0
+else
+    echo -e "${RED}❌ Found $ERRORS version synchronization error(s)${NC}"
+    exit 1
+fi

package/.claude/skills/utility/npm-release/scripts/version-decision-tree.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Version Decision Tree - Semantic Versioning Enforcer
+# Prevents arbitrary version jumps by enforcing SemVer rules
+
+set -euo pipefail
+
+CURRENT_VERSION="${1:-}"
+CHANGE_TYPE="${2:-}"
+
+if [[ -z "$CURRENT_VERSION" || -z "$CHANGE_TYPE" ]]; then
+    echo "Usage: $0 <current-version> <patch|minor|major>"
+    exit 1
+fi
+
+# Parse current version
+if [[ ! "$CURRENT_VERSION" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)$ ]]; then
+    echo "❌ Invalid version format: $CURRENT_VERSION"
+    echo "   Expected: X.Y.Z (e.g., 4.2.0)"
+    exit 1
+fi
+
+MAJOR="${BASH_REMATCH[1]}"
+MINOR="${BASH_REMATCH[2]}"
+PATCH="${BASH_REMATCH[3]}"
+
+# Calculate next version based on change type
+case "$CHANGE_TYPE" in
+    patch)
+        NEXT_VERSION="$MAJOR.$MINOR.$((PATCH + 1))"
+        ;;
+    minor)
+        NEXT_VERSION="$MAJOR.$((MINOR + 1)).0"
+        ;;
+    major)
+        NEXT_VERSION="$((MAJOR + 1)).0.0"
+        ;;
+    *)
+        echo "❌ Invalid change type: $CHANGE_TYPE"
+        echo "   Expected: patch, minor, or major"
+        exit 1
+        ;;
+esac
+
+echo "$NEXT_VERSION"

package/.claude/tsc-cache/70d2fc6d-2936-429b-b529-429f1aae8c88/affected-repos.txt

@@ -0,0 +1 @@
+root

package/.claude/tsc-cache/70d2fc6d-2936-429b-b529-429f1aae8c88/edited-files.log

@@ -0,0 +1,2 @@
+1773366329	Edit	/Users/dimon/001Area/80-CodeWorld/002-devflow/cc-devflow/package.json	root
+1773366437	Edit	/Users/dimon/001Area/80-CodeWorld/002-devflow/cc-devflow/package.json	root