claude-code-workflow 6.0.0

package/CLAUDE.md

@@ -0,0 +1,91 @@
+# Development Guidelines
+
+## Overview
+
+This document defines project-specific coding standards and development principles.
+### CLI Tool Context Protocols
+For all CLI tool usage, command syntax, and integration guidelines:
+- **Tool Strategy**: @~/.claude/workflows/tool-strategy.md
+- **Intelligent Context Strategy**: @~/.claude/workflows/intelligent-tools-strategy.md
+- **Context Search Commands**: @~/.claude/workflows/context-search-strategy.md
+
+**Context Requirements**:
+- Identify 3+ existing similar patterns before implementation
+- Map dependencies and integration points
+- Understand testing framework and coding conventions
+
+
+## Philosophy
+
+### Core Beliefs
+
+- **Pursue good taste** - Eliminate edge cases to make code logic natural and elegant
+- **Embrace extreme simplicity** - Complexity is the root of all evil
+- **Be pragmatic** - Code must solve real-world problems, not hypothetical ones
+- **Data structures first** - Bad programmers worry about code; good programmers worry about data structures
+- **Never break backward compatibility** - Existing functionality is sacred and inviolable
+- **Incremental progress over big bangs** - Small changes that compile and pass tests
+- **Learning from existing code** - Study and plan before implementing
+- **Clear intent over clever code** - Be boring and obvious
+- **Follow existing code style** - Match import patterns, naming conventions, and formatting of existing codebase
+- **Minimize changes** - Only modify what's directly required; avoid refactoring, adding features, or "improving" code beyond the request
+- **No unsolicited documentation** - NEVER generate reports, documentation files, or summaries without explicit user request. If required, save to .workflow/.scratchpad/
+
+### Simplicity Means
+
+- Single responsibility per function/class
+- Avoid premature abstractions
+- No clever tricks - choose the boring solution
+- If you need to explain it, it's too complex
+
+## Project Integration
+
+### Learning the Codebase
+
+- Find 3 similar features/components
+- Identify common patterns and conventions
+- Use same libraries/utilities when possible
+- Follow existing test patterns
+
+### Tooling
+
+- Use project's existing build system
+- Use project's test framework  
+- Use project's formatter/linter settings
+- Don't introduce new tools without strong justification
+
+
+### Fix, Don't Hide
+
+- **Solve problems, don't silence symptoms** - Skipped tests, `@ts-ignore`, empty catch, `as any`, excessive timeouts = hiding bugs, not fixing them
+
+**NEVER**:
+- Make assumptions - verify with existing code
+- Generate reports, summaries, or documentation files without explicit user request
+- Use suppression mechanisms (`skip`, `ignore`, `disable`) without fixing root cause
+
+**ALWAYS**:
+- Plan complex tasks thoroughly before implementation
+- Generate task decomposition for multi-module work (>3 modules or >5 subtasks)
+- Track progress using TODO checklists for complex tasks
+- Validate planning documents before starting development
+- Commit working code incrementally
+- Update plan documentation and progress tracking as you go
+- Learn from existing implementations
+- Stop after 3 failed attempts and reassess
+- **Edit fallback**: When Edit tool fails 2+ times on same file, try Bash sed/awk first, then Write to recreate if still failing
+
+## Platform-Specific Guidelines
+
+### Windows Path Format Guidelines
+- **MCP Tools**: Double backslash `D:\\path\\file.txt`
+- **Bash Commands**: Forward slash `D:/path/file.txt` or `/d/path/file.txt`
+- **Relative Paths**: Universal (works in both)
+
+#### **Content Uniqueness Rules**
+
+- **Each layer owns its abstraction level** - no content sharing between layers
+- **Reference, don't duplicate** - point to other layers, never copy content
+- **Maintain perspective** - each layer sees the system at its appropriate scale
+- **Avoid implementation creep** - higher layers stay architectural
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Claude Development Guidelines
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,219 @@
+# 🚀 Claude Code Workflow (CCW)
+
+<div align="center">
+
+[![Version](https://img.shields.io/badge/version-v5.9.6-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)]()
+
+**Languages:** [English](README.md) | [中文](README_CN.md)
+
+</div>
+
+---
+
+**Claude Code Workflow (CCW)** transforms AI development from simple prompt chaining into a powerful, context-first orchestration system. It solves execution uncertainty and error accumulation through structured planning, deterministic execution, and intelligent multi-model orchestration.
+
+> **🎉 Version 5.9.6: Review Cycle Enhancement & Dashboard Automation**
+>
+> **Core Improvements**:
+> - ✨ **Enhanced Review Dashboard**: The `review-cycle` dashboard now supports real-time progress tracking and advanced filtering for better visibility into code reviews.
+> - 🎯 **New Fix-Tracking Dashboard**: Introduced a new, independent `fix-dashboard.html` to monitor the progress of bug fixes with rich data integration.
+> - 🚀 **`lite-fix` Workflow**: Added a new `lite-fix` command for intelligent, streamlined bug diagnosis and resolution.
+> - 🛠️ **`lite-plan` Optimization**: Significantly optimized the `lite-plan` workflow with cost-aware parallel execution, better complexity analysis, and robust context protection.
+> - 🧠 **Intelligent Test Cycles**: Improved the `test-cycle-execute` command with smart iteration strategies and a universal `@test-fix-agent` for more effective testing.
+>
+> See [CHANGELOG.md](CHANGELOG.md) for complete details.
+
+> 📚 **New to CCW?** Check out the [**Getting Started Guide**](GETTING_STARTED.md) for a beginner-friendly 5-minute tutorial!
+
+---
+
+## ✨ Core Concepts
+
+CCW is built on a set of core principles that distinguish it from traditional AI development approaches:
+
+- **Context-First Architecture**: Eliminates uncertainty during execution through pre-defined context gathering, ensuring agents have the right information *before* implementation.
+- **JSON-First State Management**: Task state is fully stored in `.task/IMPL-*.json` files as the single source of truth, enabling programmatic orchestration without state drift.
+- **Autonomous Multi-Stage Orchestration**: Commands chain-invoke specialized sub-commands and agents to automate complex workflows with zero user intervention.
+- **Multi-Model Strategy**: Leverages the unique strengths of different AI models (e.g., Gemini for analysis, Codex for implementation) for superior results.
+- **Layered Memory System**: A 4-tier documentation system that provides context at the appropriate abstraction level, preventing information overload.
+- **Specialized Role-Based Agents**: A suite of agents (`@code-developer`, `@test-fix-agent`, etc.) that emulate a real software team for diverse tasks.
+
+---
+
+## ⚙️ Installation
+
+For detailed installation instructions, refer to the [**INSTALL.md**](INSTALL.md) guide.
+
+### **🚀 One-Click Quick Install**
+
+**Windows (PowerShell):**
+```powershell
+Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1" -UseBasicParsing).Content
+```
+
+**Linux/macOS (Bash/Zsh):**
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.sh)
+```
+
+### **✅ Verify Installation**
+After installation, open **Claude Code** and verify that workflow commands are available by running:
+```bash
+/workflow:session:list
+```
+If slash commands (e.g., `/workflow:*`) are recognized, the installation was successful.
+
+---
+
+## 🛠️ Command Reference
+
+CCW provides a rich set of commands for managing workflows, tasks, and interactions with AI tools. For a complete list and detailed descriptions of all available commands, please refer to the [**COMMAND_REFERENCE.md**](COMMAND_REFERENCE.md) file.
+
+For detailed technical specifications of each command, see [**COMMAND_SPEC.md**](COMMAND_SPEC.md).
+
+---
+
+### 💡 **Need Help? Use the Interactive Command Guide**
+
+CCW includes a built-in **Command Guide Skill** to help you discover and use commands effectively:
+
+- **`CCW-help`** - Get interactive help and command recommendations
+- **`CCW-issue`** - Report bugs or request features using guided templates
+
+The Command Guide provides:
+- 🔍 **Smart Command Search** - Find commands by keyword, category, or use case
+- 🤖 **Next-Step Recommendations** - Get suggestions for what to do after any command
+- 📖 **Detailed Documentation** - View arguments, examples, and best practices
+- 🎓 **Beginner Onboarding** - Learn the 14 core commands through guided learning paths
+- 📝 **Issue Reporting** - Generate standardized bug reports and feature requests
+
+**Usage Examples**:
+```
+User: "CCW-help"
+→ Interactive menu with command search, recommendations, and documentation
+
+User: "What should I do after /workflow:plan?"
+→ Recommends /workflow:execute, /workflow:action-plan-verify with workflow patterns
+
+User: "CCW-issue"
+→ Guided template generation for bugs, features, or question inquiries
+```
+
+---
+
+## 🚀 Quick Start
+
+The best way to get started is by following the 5-minute tutorial in the [**Getting Started Guide**](GETTING_STARTED.md).
+
+Here's a quick example of a common development workflow:
+
+### **Option 1: Lite-Plan Workflow** (⚡ Recommended for Quick Tasks)
+
+Lightweight interactive workflow with in-memory planning and immediate execution:
+
+```bash
+# Basic usage with auto-detection
+/workflow:lite-plan "Add JWT authentication to user login"
+
+# Force code exploration
+/workflow:lite-plan -e "Refactor logging module for better performance"
+
+# Basic usage
+/workflow:lite-plan "Add unit tests for authentication service"
+```
+
+**Interactive Flow**:
+1. **Phase 1**: Automatic task analysis and smart code exploration (if needed)
+2. **Phase 2**: Answer clarification questions (if any)
+3. **Phase 3**: Review generated plan and task breakdown
+4. **Phase 4**: Three-dimensional confirmation:
+   - ✅ Confirm/Modify/Cancel task
+   - 🔧 Choose execution: Agent / Provide Plan Only / CLI (Gemini/Qwen/Codex)
+   - 🔍 Optional code review: No / Claude / Gemini / Qwen / Codex
+5. **Phase 5**: Watch live execution and task tracking
+
+### **Option 2: Lite-Fix Workflow** (🐛 Recommended for Bug Fixes)
+
+Intelligent bug diagnosis and fix workflow with adaptive severity assessment:
+
+```bash
+# Standard bug fix (auto-adapts based on severity)
+/workflow:lite-fix "User avatar upload fails with 413 error"
+
+# Production hotfix mode
+/workflow:lite-fix --hotfix "Payment gateway 5xx errors"
+```
+
+**Workflow Features**:
+- **Phase 1**: Intelligent root cause diagnosis with adaptive search
+- **Phase 2**: Automatic impact assessment and risk scoring
+- **Phase 3**: Fix strategy generation based on complexity
+- **Phase 4**: Risk-aware verification planning
+- **Phase 5**: User confirmation with execution selection
+- **Phase 6**: Execution dispatch with complete artifact tracking
+
+**Session Artifacts** (saved to `.workflow/.lite-fix/{bug-slug}-{timestamp}/`):
+- `diagnosis.json` - Root cause analysis and reproduction steps
+- `impact.json` - Risk score, severity, and workflow adaptations
+- `fix-plan.json` - Fix strategy and implementation tasks
+- `task.json` - Enhanced Task JSON with complete context
+- `followup.json` - Auto-generated follow-up tasks (hotfix mode only)
+
+### **Option 3: Full Workflow** (📋 Comprehensive Planning)
+
+Traditional multi-stage workflow for complex projects:
+
+1.  **Create Plan** (auto-starts session):
+    ```bash
+    /workflow:plan "Implement JWT-based user login and registration"
+    ```
+2.  **Execute Plan**:
+    ```bash
+    /workflow:execute
+    ```
+3.  **View Status** (optional):
+    ```bash
+    /workflow:status
+    ```
+
+---
+
+## 📚 Documentation
+
+CCW provides comprehensive documentation to help you get started quickly and master advanced features:
+
+### 📖 **Getting Started**
+- [**Getting Started Guide**](GETTING_STARTED.md) - 5-minute quick start tutorial
+- [**Installation Guide**](INSTALL.md) - Detailed installation instructions ([中文](INSTALL_CN.md))
+- [**Workflow Decision Guide**](WORKFLOW_DECISION_GUIDE.md) - 🌳 Interactive flowchart to choose the right command
+- [**Examples**](EXAMPLES.md) - Real-world use cases and practical examples
+- [**FAQ**](FAQ.md) - Common questions and troubleshooting
+
+### 🏗️ **Architecture & Design**
+- [**Architecture Overview**](ARCHITECTURE.md) - System design and core components
+- [**Project Introduction**](PROJECT_INTRODUCTION.md) - Detailed project overview
+- [**Workflow Diagrams**](WORKFLOW_DIAGRAMS.md) - Visual workflow representations
+
+### 📋 **Command Reference**
+- [**Command Reference**](COMMAND_REFERENCE.md) - Complete list of all commands
+- [**Command Spec**](COMMAND_SPEC.md) - Detailed technical specifications
+- [**Command Flow Standard**](COMMAND_FLOW_STANDARD.md) - Command design patterns
+
+### 🤝 **Contributing**
+- [**Contributing Guide**](CONTRIBUTING.md) - How to contribute to CCW
+- [**Changelog**](CHANGELOG.md) - Version history and release notes
+
+---
+
+## 🤝 Contributing & Support
+
+- **Repository**: [GitHub - Claude-Code-Workflow](https://github.com/catlog22/Claude-Code-Workflow)
+- **Issues**: Report bugs or request features on [GitHub Issues](https://github.com/catlog22/Claude-Code-Workflow/issues).
+- **Discussions**: Join the [Community Forum](https://github.com/catlog22/Claude-Code-Workflow/discussions).
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
+
+## 📄 License
+
+This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.

package/ccw/README.md

@@ -0,0 +1,121 @@
+# CCW - Claude Code Workflow CLI
+
+A command-line tool for viewing workflow sessions and code review results from the Claude Code Workflow system.
+
+## Installation
+
+```bash
+# Install globally
+npm install -g ccw
+
+# Or install from local source
+cd path/to/ccw
+npm install
+npm link
+```
+
+## Usage
+
+### View Dashboard
+
+```bash
+# Open workflow dashboard in browser
+ccw view
+
+# Specify project path
+ccw view -p /path/to/project
+
+# Generate dashboard without opening browser
+ccw view --no-browser
+
+# Custom output path
+ccw view -o report.html
+```
+
+## Features
+
+### Workflow Dashboard
+- **Active Sessions**: View all active workflow sessions with task progress
+- **Archived Sessions**: Browse completed/archived sessions
+- **Task Tracking**: See individual task status (pending/in_progress/completed)
+- **Progress Bars**: Visual progress indicators for each session
+
+### Review Integration
+- **Code Review Findings**: View results from `review-module-cycle`
+- **Severity Distribution**: Critical/High/Medium/Low finding counts
+- **Dimension Analysis**: Findings by review dimension (Security, Architecture, Quality, etc.)
+- **Tabbed Interface**: Switch between Workflow and Reviews tabs
+
+## Dashboard Data Sources
+
+The CLI reads data from the `.workflow/` directory structure:
+
+```
+.workflow/
+├── active/
+│   └── WFS-{session-id}/
+│       ├── workflow-session.json    # Session metadata
+│       ├── .task/
+│       │   └── IMPL-*.json          # Task definitions
+│       └── .review/
+│           ├── review-progress.json # Review progress
+│           └── dimensions/
+│               └── *.json           # Dimension findings
+└── archives/
+    └── WFS-{session-id}/            # Archived sessions
+```
+
+## Bundled Templates
+
+The CLI includes bundled dashboard templates:
+- `workflow-dashboard.html` - Workflow session and task visualization
+- `review-cycle-dashboard.html` - Code review findings display
+
+No external template installation required - templates are included in the npm package.
+
+## Requirements
+
+- Node.js >= 16.0.0
+- npm or yarn
+
+## Integration with Claude Code Workflow
+
+This CLI is a standalone tool that works with the Claude Code Workflow system:
+
+1. **Install CCW CLI** (via npm)
+   - `npm install -g ccw`
+   - Provides `ccw view` command for dashboard viewing
+   - Templates are bundled - no additional installation required
+
+2. **Optional: Install Claude Code Workflow** (via `Install-Claude.ps1`)
+   - Provides workflow commands, agents, and automation
+   - CCW will automatically detect and display workflow sessions
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `-p, --path <path>` | Path to project directory (default: current directory) |
+| `--no-browser` | Generate dashboard without opening browser |
+| `-o, --output <file>` | Custom output path for HTML file |
+| `-V, --version` | Display version number |
+| `-h, --help` | Display help information |
+
+## Development
+
+```bash
+# Clone and install dependencies
+git clone <repo-url>
+cd ccw
+npm install
+
+# Link for local testing
+npm link
+
+# Test the CLI
+ccw view -p /path/to/test/project
+```
+
+## License
+
+MIT

package/ccw/bin/ccw.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+/**
+ * CCW CLI - Claude Code Workflow Dashboard
+ * Entry point for global CLI installation
+ */
+
+import { run } from '../src/cli.js';
+
+run(process.argv);

package/ccw/src/cli.js

@@ -0,0 +1,100 @@
+import { Command } from 'commander';
+import { viewCommand } from './commands/view.js';
+import { serveCommand } from './commands/serve.js';
+import { installCommand } from './commands/install.js';
+import { uninstallCommand } from './commands/uninstall.js';
+import { upgradeCommand } from './commands/upgrade.js';
+import { listCommand } from './commands/list.js';
+import { readFileSync, existsSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Load package.json with error handling
+ * @returns {Object} - Package info with version
+ */
+function loadPackageInfo() {
+  const pkgPath = join(__dirname, '../package.json');
+
+  try {
+    if (!existsSync(pkgPath)) {
+      console.error('Fatal Error: package.json not found.');
+      console.error(`Expected location: ${pkgPath}`);
+      process.exit(1);
+    }
+
+    const content = readFileSync(pkgPath, 'utf8');
+    return JSON.parse(content);
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      console.error('Fatal Error: package.json contains invalid JSON.');
+      console.error(`Parse error: ${error.message}`);
+    } else {
+      console.error('Fatal Error: Could not read package.json.');
+      console.error(`Error: ${error.message}`);
+    }
+    process.exit(1);
+  }
+}
+
+const pkg = loadPackageInfo();
+
+export function run(argv) {
+  const program = new Command();
+
+  program
+    .name('ccw')
+    .description('Claude Code Workflow CLI - Dashboard and workflow tools')
+    .version(pkg.version);
+
+  // View command (server mode with live path switching)
+  program
+    .command('view')
+    .description('Open workflow dashboard server with live path switching')
+    .option('-p, --path <path>', 'Path to project directory', '.')
+    .option('--port <port>', 'Server port', '3456')
+    .option('--no-browser', 'Start server without opening browser')
+    .action(viewCommand);
+
+  // Serve command (alias for view)
+  program
+    .command('serve')
+    .description('Alias for view command')
+    .option('-p, --path <path>', 'Initial project directory')
+    .option('--port <port>', 'Server port', '3456')
+    .option('--no-browser', 'Start server without opening browser')
+    .action(serveCommand);
+
+  // Install command
+  program
+    .command('install')
+    .description('Install Claude Code Workflow to your system')
+    .option('-m, --mode <mode>', 'Installation mode: Global or Path')
+    .option('-p, --path <path>', 'Installation path (for Path mode)')
+    .option('-f, --force', 'Force installation without prompts')
+    .action(installCommand);
+
+  // Uninstall command
+  program
+    .command('uninstall')
+    .description('Uninstall Claude Code Workflow')
+    .action(uninstallCommand);
+
+  // Upgrade command
+  program
+    .command('upgrade')
+    .description('Upgrade Claude Code Workflow installations')
+    .option('-a, --all', 'Upgrade all installations without prompting')
+    .action(upgradeCommand);
+
+  // List command
+  program
+    .command('list')
+    .description('List all installed Claude Code Workflow instances')
+    .action(listCommand);
+
+  program.parse(argv);
+}