Claude-Code-Workflow/CHANGELOG.md

Changelog

All notable changes to Claude Code Workflow (CCW) will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[5.4.0] - 2025-11-06

🎯 CLI Template System Reorganization

This release introduces a comprehensive reorganization of the CLI template system with priority-based naming and enhanced error handling for Gemini models.

✨ Added

Template Priority System:

• ✨ Priority-Based Naming - All templates now use priority prefixes for better organization
  • 01-* prefix: Universal, high-frequency templates (e.g., trace-code-execution, diagnose-bug-root-cause)
  • 02-* prefix: Common specialized templates (e.g., implement-feature, analyze-code-patterns)
  • 03-* prefix: Domain-specific, less frequent templates (e.g., assess-security-risks, debug-runtime-issues)
• ✨ 19 Templates Reorganized - Complete template system restructure across 4 directories
  • analysis/ (8 templates): Code analysis, bug diagnosis, architecture review, security assessment
  • development/ (5 templates): Feature implementation, refactoring, testing, UI components
  • planning/ (5 templates): Architecture design, task breakdown, component specs, migration
  • memory/ (1 template): Module documentation
• ✨ Template Selection Guidance - Choose templates based on task needs, not sequence numbers

Error Handling Enhancement:

• ✨ Gemini 404 Fallback Strategy - Automatic model fallback for improved reliability
  • If gemini-3-pro-preview-11-2025 returns 404 error, automatically fallback to gemini-2.5-pro
  • Comprehensive error handling documentation for HTTP 429 and HTTP 404 errors
  • Added to both Model Selection and Tool Specifications sections

🔄 Changed

Template File Reorganization (19 files):

Analysis Templates:

• code-execution-tracing.txt → 01-trace-code-execution.txt
• bug-diagnosis.txt → 01-diagnose-bug-root-cause.txt (moved from development/)
• pattern.txt → 02-analyze-code-patterns.txt
• architecture.txt → 02-review-architecture.txt
• code-review.txt → 02-review-code-quality.txt (moved from review/)
• performance.txt → 03-analyze-performance.txt
• security.txt → 03-assess-security-risks.txt
• quality.txt → 03-review-quality-standards.txt

Development Templates:

• feature.txt → 02-implement-feature.txt
• refactor.txt → 02-refactor-codebase.txt
• testing.txt → 02-generate-tests.txt
• component.txt → 02-implement-component-ui.txt
• debugging.txt → 03-debug-runtime-issues.txt

Planning Templates:

• architecture-planning.txt → 01-plan-architecture-design.txt
• task-breakdown.txt → 02-breakdown-task-steps.txt
• component.txt → 02-design-component-spec.txt (moved from implementation/)
• concept-eval.txt → 03-evaluate-concept-feasibility.txt
• migration.txt → 03-plan-migration-strategy.txt

Memory Templates:

• claude-module-unified.txt → 02-document-module-structure.txt

Directory Structure Optimization:

• 🔄 Bug Diagnosis Reclassified - Moved from development/ to analysis/ (diagnostic work, not implementation)
• 🔄 Removed Redundant Directories - Eliminated implementation/ and review/ folders
• 🔄 Unified Path References - All command files now use full path format

Command File Updates (21 references across 5 files):

• cli/mode/bug-diagnosis.md - 6 template references updated
• cli/mode/code-analysis.md - 6 template references updated
• cli/mode/plan.md - 6 template references updated
• task/execute.md - 1 template reference updated
• workflow/tools/test-task-generate.md - 2 template references updated

📝 Documentation

Updated Files:

• 🔄 intelligent-tools-strategy.md - Complete template system guide with new naming convention
  • Updated Available Templates section with all new template names
  • Enhanced Task-Template Matrix with priority-based organization
  • Added Gemini error handling documentation (404 and 429)
  • Removed star symbols (⭐) - redundant with priority numbers
• ✨ command-template-update-summary.md - New file documenting all template reference changes

🎯 Benefits

Template System Improvements:

• 📦 Better Discoverability - Priority prefixes make it easy to find appropriate templates
• 📦 Clearer Organization - Templates grouped by usage frequency and specialization
• 📦 Consistent Naming - Descriptive names following [Priority]-[Action]-[Object]-[Context].txt pattern
• 📦 No Breaking Changes - All command references updated, backward compatible

Error Handling Enhancements:

• ⚡ Improved Reliability - Automatic fallback prevents workflow interruption
• ⚡ Better Documentation - Clear guidance for both HTTP 429 and 404 errors
• ⚡ User-Friendly - Transparent error handling without manual intervention

Workflow Integration:

• 🔗 All 5 command files seamlessly updated with new template paths
• 🔗 Full path references ensure clarity and maintainability
• 🔗 No user action required - all updates applied systematically

📦 Modified Files

Templates (19 renames, 2 directory removals):

• .claude/workflows/cli-templates/prompts/analysis/ - 8 templates reorganized
• .claude/workflows/cli-templates/prompts/development/ - 5 templates reorganized
• .claude/workflows/cli-templates/prompts/planning/ - 5 templates reorganized
• .claude/workflows/cli-templates/prompts/memory/ - 1 template reorganized
• Removed: implementation/, review/ directories

Commands (5 files, 21 references):

• .claude/commands/cli/mode/bug-diagnosis.md
• .claude/commands/cli/mode/code-analysis.md
• .claude/commands/cli/mode/plan.md
• .claude/commands/task/execute.md
• .claude/commands/workflow/tools/test-task-generate.md

Documentation:

• .claude/workflows/intelligent-tools-strategy.md
• .claude/workflows/command-template-update-summary.md (new)

🔗 Upgrade Notes

No User Action Required:

• All template references automatically updated
• Commands work with new template paths
• No breaking changes to existing workflows

Template Selection:

• Use priority prefix as a guide, not a requirement
• Choose templates based on your specific task needs
• Number indicates category and frequency, not usage order

Error Handling:

• Gemini 404 errors now automatically fallback to gemini-2.5-pro
• HTTP 429 errors continue with existing handling (check results existence)

---

[5.2.2] - 2025-11-03

✨ Added

/memory:skill-memory Intelligent Skip Logic:

• ✨ Smart Documentation Generation - Automatically detects existing documentation and skips regeneration
  • If docs exist AND no --regenerate flag: Skip Phase 2 (planning) and Phase 3 (generation)
  • Jump directly to Phase 4 (SKILL.md index generation) for fast SKILL updates
  • If docs exist AND --regenerate flag: Delete existing docs and regenerate from scratch
  • If no docs exist: Run full 4-phase workflow
• ✨ Phase 4 Always Executes - SKILL.md index is never skipped, always generated or updated
  • Ensures SKILL index stays synchronized with documentation structure
  • Lightweight operation suitable for frequent execution
• ✨ Skip Path Documentation - Added comprehensive TodoWrite patterns for both execution paths
  • Full Path: All 4 phases (no existing docs or --regenerate specified)
  • Skip Path: Phase 1 → Phase 4 (existing docs found, no --regenerate)
  • Auto-Continue flow diagrams for both paths

🔄 Changed

Parameter Naming Correction:

• 🔄 --regenerate Flag - Reverted --update back to --regenerate in /memory:skill-memory
  • More accurate naming: "regenerate" means delete and recreate (destructive)
  • "update" was misleading as it implied incremental update (not implemented)
  • Fixed naming consistency across all documentation and examples

Phase 1 Enhancement:

• 🔄 Step 4: Determine Execution Path - Added decision logic to Phase 1
  • Checks existing documentation count
  • Evaluates --regenerate flag presence
  • Sets SKIP_DOCS_GENERATION flag based on conditions
  • Displays appropriate skip or regeneration messages

🎯 Benefits

Performance Optimization:

• ⚡ Faster SKILL Updates - Skip documentation generation when docs already exist (~5-10x faster)
• ⚡ Always Fresh Index - SKILL.md regenerated every time to reflect current documentation structure
• ⚡ Conditional Regeneration - Explicit --regenerate flag for full documentation refresh

Workflow Efficiency:

• 🔗 Smart detection reduces unnecessary documentation regeneration
• 🔗 Clear separation between SKILL index updates and documentation generation
• 🔗 Explicit control via --regenerate flag when full refresh needed

📦 Modified Files

• .claude/commands/memory/skill-memory.md - Added skip logic, reverted parameter naming, comprehensive execution path documentation

---

[5.2.1] - 2025-11-03

🔄 Changed

/memory:load-skill-memory Command Redesign:

• 🔄 Manual Activation - Changed from automatic SKILL discovery to manual activation tool
  • User explicitly specifies SKILL name: /memory:load-skill-memory <skill_name> "intent"
  • Removed complex 3-tier matching algorithm (path/keyword/action scoring)
  • Complements automatic SKILL triggering system (use when auto-activation doesn't occur)
• 🔄 Intent-Driven Documentation Loading - Intelligently loads docs based on task description
  • Quick Understanding: "了解" → README.md (~2K)
  • Module Analysis: "分析XXX模块" → Module README+API (~5K)
  • Architecture Review: "架构" → README+ARCHITECTURE (~10K)
  • Implementation: "修改", "增强" → Module+EXAMPLES (~15K)
  • Comprehensive: "完整", "深入" → All docs (~40K)
• 🔄 Memory-Based Validation - Removed bash validation, uses conversation memory to check SKILL existence
• 🔄 Simplified Structure - Reduced from 355 lines to 132 lines (-62.8%)
  • Single representative example instead of 4 examples
  • Generic use case (OAuth authentication) instead of domain-specific examples
  • Removed verbose error handling, integration notes, and confirmation outputs

Context Search Strategy Enhancement:

• ✨ SKILL Packages First Priority - Added to Core Search Tools with highest priority
  • Fastest way to understand projects - use BEFORE Gemini analysis
  • Intelligent activation via Skill() tool with automatic discovery
  • Emphasized in Tool Selection Matrix and Quick Command Reference

Parameter Naming Consistency:

• 🔄 --update Flag - Renamed --regenerate to --update in /memory:skill-memory
  • Consistent naming convention across documentation commands
  • Updated all references and examples

🎯 Benefits

Improved SKILL Workflow:

• ⚡ Clearer Purpose - Distinction between automatic (normal) and manual (override) SKILL activation
• ⚡ Token Optimization - Loads only relevant documentation scope based on intent
• ⚡ Better Discoverability - SKILL packages now prominently featured as first-priority search tool
• ⚡ Simpler Execution - Removed unnecessary validation steps, relies on memory

[5.2.0] - 2025-11-03

🎉 New Command: /memory:skill-memory - SKILL Package Generator

This release introduces a powerful new command that automatically generates progressive-loading SKILL packages from project documentation with intelligent orchestration and path mirroring.

✅ Added

New /memory:skill-memory Command:

• ✨ 4-Phase Orchestrator - Automated workflow from documentation to SKILL package
  • Phase 1: Parse arguments and prepare environment
  • Phase 2: Call /memory:docs to plan documentation
  • Phase 3: Call /workflow:execute to generate documentation
  • Phase 4: Generate SKILL.md index with progressive loading
• ✨ Auto-Continue Mechanism - All phases run autonomously via TodoList tracking
• ✨ Path Mirroring - SKILL knowledge structure mirrors source code hierarchy
• ✨ Progressive Loading - 4-level token-budgeted documentation access
  • Level 0: Quick Start (~2K tokens) - README only
  • Level 1: Core Modules (~8K tokens) - Module READMEs
  • Level 2: Complete (~25K tokens) - All modules + Architecture
  • Level 3: Deep Dive (~40K tokens) - Everything + Examples
• ✨ Intelligent Description Generation - Auto-extracts capabilities and triggers from documentation
• ✨ Regeneration Support - --regenerate flag to force fresh documentation
• ✨ Multi-Tool Support - Supports gemini, qwen, and codex for documentation generation

Command Parameters:

/memory:skill-memory [path] [--tool <gemini|qwen|codex>] [--regenerate] [--mode <full|partial>] [--cli-execute]

Path Mirroring Strategy:

Source: my_app/src/modules/auth/
  ↓
Docs: .workflow/docs/my_app/src/modules/auth/API.md
  ↓
SKILL: .claude/skills/my_app/knowledge/src/modules/auth/API.md

4-Phase Workflow:

1. Prepare: Parse arguments, check existing docs, handle --regenerate
2. Plan: Call /memory:docs to create documentation tasks
3. Execute: Call /workflow:execute to generate documentation files
4. Index: Generate SKILL.md with progressive loading structure

SKILL Package Output:

• .claude/skills/{project_name}/SKILL.md - Index with progressive loading levels
• .claude/skills/{project_name}/knowledge/ - Mirrored documentation structure
• Automatic capability detection and trigger phrase generation

📝 Changed

Enhanced /memory:docs Command:

• 🔄 Smart Task Grouping - ≤7 documents per task (up from 5)
• 🔄 Context Sharing - Prefer grouping 2 top-level directories for shared Gemini analysis
• 🔄 Batch Processing - Reduced task count through intelligent grouping
• 🔄 Dual Execution Modes - Agent Mode (default) and CLI Mode (--cli-execute)
• 🔄 Pre-computed Analysis - Phase 2 unified analysis eliminates redundant CLI calls
• 🔄 Conflict Resolution - Automatic splitting when exceeding document limit

Documentation Workflow Improvements:

• 🔄 CLI Execute Support - Direct documentation generation via CLI tools (gemini/qwen/codex)
• 🔄 workflow-session.json - Unified session metadata storage
• 🔄 Improved Structure Quality - Enhanced documentation generation guidelines

🎯 Benefits

SKILL Package Features:

• 📦 Progressive Loading - Load only what you need (2K → 40K tokens)
• 📦 Path Mirroring - Easy navigation matching source structure
• 📦 Auto-Discovery - Intelligent capability and trigger detection
• 📦 Regeneration - Force fresh docs with single flag
• 📦 Zero Manual Steps - Fully automated 4-phase workflow

Performance Optimization:

• ⚡ Parallel Processing - Multiple directory groups execute concurrently
• ⚡ Context Sharing - Single Gemini call per task group (2 directories)
• ⚡ Efficient Analysis - One-time analysis in Phase 2, reused by all tasks
• ⚡ Predictable Sizing - ≤7 docs per task ensures reliable completion
• ⚡ Failure Isolation - Task-level failures don't block entire workflow

Workflow Integration:

• 🔗 Seamless integration with existing /memory:docs command
• 🔗 Compatible with /workflow:execute system
• 🔗 Auto-continue mechanism eliminates manual steps
• 🔗 TodoList progress tracking throughout workflow

📦 New/Modified Files

New:

• .claude/commands/memory/skill-memory.md - Complete command specification (822 lines)

Modified:

• .claude/commands/memory/docs.md - Enhanced with batch processing and smart grouping
• .claude/agents/doc-generator.md - Mode-aware execution support

🔗 Usage Examples

Basic Usage:

# Generate SKILL package for current project
/memory:skill-memory

# Specify target directory
/memory:skill-memory /path/to/project

# Force regeneration with Qwen
/memory:skill-memory --tool qwen --regenerate

# Partial mode (modules only)
/memory:skill-memory --mode partial

# CLI execution mode
/memory:skill-memory --cli-execute

Output:

✅ SKILL Package Generation Complete

Project: my_project
Documentation: .workflow/docs/my_project/ (15 files)
SKILL Index: .claude/skills/my_project/SKILL.md

Generated:
- 4 documentation tasks completed
- SKILL.md with progressive loading (4 levels)
- Module index with 8 modules

Usage:
- Load Level 0: Quick project overview (~2K tokens)
- Load Level 1: Core modules (~8K tokens)
- Load Level 2: Complete docs (~25K tokens)
- Load Level 3: Everything (~40K tokens)

---

[5.1.0] - 2025-10-27

🔄 Agent Architecture Consolidation

This release consolidates the agent architecture and enhances workflow commands for better reliability and clarity.

✅ Added

Agent System:

• ✅ Universal Executor Agent - New consolidated agent replacing general-purpose agent
• ✅ Enhanced agent specialization - Better separation of concerns across agent types

Workflow Improvements:

• ✅ Advanced context filtering - Context-gather command now supports more sophisticated validation
• ✅ Session state management - Enhanced session completion with better cleanup logic

📝 Changed

Agent Architecture:

• 🔄 Removed general-purpose agent - Consolidated into universal-executor for clarity
• 🔄 Improved agent naming - More descriptive agent names matching their specific roles

Command Enhancements:

• 🔄 /workflow:session:complete - Better state management and cleanup procedures
• 🔄 /workflow:tools:context-gather - Enhanced filtering and validation capabilities

🗂️ Maintenance

Code Organization:

• 📦 Archived legacy templates - Moved outdated prompt templates to archive folder
• 📦 Documentation cleanup - Improved consistency across workflow documentation

📦 Updated Files

• .claude/agents/universal-executor.md - New consolidated agent definition
• .claude/commands/workflow/session/complete.md - Enhanced session management
• .claude/commands/workflow/tools/context-gather.md - Improved context filtering
• .claude/workflows/cli-templates/prompts/archive/ - Legacy template archive

---

[5.0.0] - 2025-10-24

🎉 Less is More - Simplified Architecture Release

This major release embraces the "less is more" philosophy, removing external dependencies, streamlining workflows, and focusing on core functionality with standard, proven tools.

🚀 Breaking Changes

Removed Features:

• ❌ /workflow:concept-clarify - Concept enhancement feature removed for simplification
• ❌ MCP code-index dependency - Replaced with standard ripgrep and find tools
• ❌ synthesis-specification.md workflow - Replaced with direct role analysis approach

Command Changes:

• ⚠️ Memory commands renamed for consistency:
  • /update-memory-full → /memory:update-full
  • /update-memory-related → /memory:update-related

✅ Added

Standard Tool Integration:

• ✅ ripgrep (rg) - Fast content search replacing MCP code-index
• ✅ find - Native filesystem discovery for better cross-platform compatibility
• ✅ Multi-tier fallback - Graceful degradation when advanced tools unavailable

Enhanced TDD Workflow:

• ✅ Conflict resolution mechanism - Better handling of test-implementation conflicts
• ✅ Improved task generation - Enhanced phase coordination and quality gates
• ✅ Updated workflow phases - Clearer separation of concerns

Role-Based Planning:

• ✅ Direct role analysis - Simplified brainstorming focused on role documents
• ✅ Removed synthesis layer - Less abstraction, clearer intent
• ✅ Better documentation flow - From role analysis directly to action planning

📝 Changed

Documentation Updates:

• ✅ All docs updated to v5.0.0 - Consistent versioning across all files
• ✅ Removed MCP badge - No longer advertising experimental MCP features
• ✅ Clarified test workflows - Better explanation of generate → execute pattern
• ✅ Fixed command references - Corrected all memory command names
• ✅ Updated UI design notes - Clarified MCP Chrome DevTools retention for UI workflows

File Discovery:

• ✅ /memory:load - Now uses ripgrep/find instead of MCP code-index
• ✅ Faster search - Native tools provide better performance
• ✅ Better reliability - No external service dependencies

UI Design Workflows:

• ℹ️ MCP Chrome DevTools retained - Specialized tool for browser automation
• ℹ️ Multi-tier fallback - MCP → Playwright → Chrome → Manual
• ℹ️ Purpose-built integration - UI workflows require browser control

🐛 Fixed

Documentation Inconsistencies:

• 🔧 Removed references to deprecated /workflow:concept-clarify command
• 🔧 Fixed incorrect memory command names in getting started guides
• 🔧 Clarified test workflow execution patterns
• 🔧 Updated MCP dependency references throughout specs
• 🔧 Corrected UI design tool descriptions

📦 Updated Files

• README.md / README_CN.md - v5.0 version badge and core improvements
• COMMAND_REFERENCE.md - Updated command descriptions, removed deprecated commands
• COMMAND_SPEC.md - v5.0 technical specifications, clarified implementations
• GETTING_STARTED.md / GETTING_STARTED_CN.md - v5.0 features, fixed command names
• INSTALL_CN.md - v5.0 simplified installation notes

🔍 Technical Details

Performance Improvements:

• Faster file discovery using native ripgrep
• Reduced external dependencies improves installation reliability
• Better cross-platform compatibility with standard Unix tools

Architectural Benefits:

• Simpler dependency tree
• Easier troubleshooting with standard tools
• More predictable behavior without external services

Migration Notes:

• Update memory command usage (see command changes above)
• Remove any usage of /workflow:concept-clarify
• No changes needed for core workflow commands (/workflow:plan, /workflow:execute)

---