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](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [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**:
```bash
/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**:
```bash
# 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`)

---