From d53e7e18db793e7aa536105531a0b5e822d6e3bb Mon Sep 17 00:00:00 2001 From: catlog22 Date: Sun, 23 Nov 2025 20:11:48 +0800 Subject: [PATCH] docs: update README files to version 5.9.2 with lite-fix enhancements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add English README.md based on Chinese version - Update version badges to v5.9.2 in both README files - Add Lite-Fix workflow documentation and examples - Document session artifact structure and management - Include lite-fix quick start examples (standard and hotfix modes) - Align with latest lite-fix session management features 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- README.md | 223 +++++++++++++++++++++++++++++++++++++++++++++++++++ README_CN.md | 53 ++++++++---- 2 files changed, 262 insertions(+), 14 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 00000000..4d78010b --- /dev/null +++ b/README.md @@ -0,0 +1,223 @@ +# 🚀 Claude Code Workflow (CCW) + +
+ +[![Version](https://img.shields.io/badge/version-v5.9.2-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) + +
+ +--- + +**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.2: Lite-Fix Workflow Enhancement & Session Management** +> +> **Core Improvements**: +> - ✨ **Lite-Fix Session Artifacts** (`/workflow:lite-fix`) - Complete bug fix workflow tracking +> - **Session Folder Structure**: Organized artifact storage in `.workflow/.lite-fix/{bug-slug}-{timestamp}/` +> - **Phase Artifacts**: `diagnosis.json`, `impact.json`, `fix-plan.json`, `task.json` +> - **CLI/Agent Access**: All intermediate results accessible for execution tools +> - **Follow-up Tasks**: Auto-generated comprehensive fix and postmortem tasks (hotfix mode) +> - **Enhanced Task JSON**: Complete context package with diagnosis, impact, and fix plan +> - 🔄 **Consistent Architecture** - Aligned with lite-plan session management patterns +> - 📊 **Better Audit Trail** - Natural history tracking for all bug fixes +> - 🎯 **Improved Reusability** - Task JSON files can be re-executed with `/workflow:lite-execute` +> +> 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. diff --git a/README_CN.md b/README_CN.md index e0770002..c432f584 100644 --- a/README_CN.md +++ b/README_CN.md @@ -2,7 +2,7 @@
-[![Version](https://img.shields.io/badge/version-v5.8.1-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases) +[![Version](https://img.shields.io/badge/version-v5.9.2-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)]() @@ -14,20 +14,18 @@ **Claude Code Workflow (CCW)** 将 AI 开发从简单的提示词链接转变为一个强大的、上下文优先的编排系统。它通过结构化规划、确定性执行和智能多模型编排，解决了执行不确定性和误差累积的问题。 -> **🎉 版本 5.8.1: Lite-Plan 工作流与 CLI 工具增强** +> **🎉 版本 5.9.2: Lite-Fix 工作流增强与会话管理** > > **核心改进**: -> - ✨ **Lite-Plan 工作流** (`/workflow:lite-plan`) - 轻量级交互式规划与智能自动化 -> - **三维多选确认**: 任务批准 + 执行方法 + 代码审查工具 -> - **智能代码探索**: 自动检测何时需要代码库上下文（使用 `-e` 标志强制探索） -> - **并行任务执行**: 识别独立任务以实现并发执行 -> - **灵活执行**: 选择智能体（@code-developer）或 CLI（Gemini/Qwen/Codex） -> - **可选后置审查**: 内置代码质量分析，可选择 AI 工具 -> - ✨ **CLI 工具优化** - 简化命令语法，自动模型选择 -> - 移除 Gemini、Qwen 和 Codex 的 `-m` 参数要求（自动选择最佳模型） -> - 更清晰的命令结构和改进的文档 -> - 🔄 **执行工作流增强** - 简化阶段，采用延迟加载策略 -> - 🎨 **CLI Explore Agent** - 改进可见性，采用黄色配色方案 +> - ✨ **Lite-Fix 会话产物** (`/workflow:lite-fix`) - 完整的 Bug 修复工作流跟踪 +> - **会话文件夹结构**: 在 `.workflow/.lite-fix/{bug-slug}-{timestamp}/` 中组织产物存储 +> - **阶段产物**: `diagnosis.json`、`impact.json`、`fix-plan.json`、`task.json` +> - **CLI/智能体访问**: 所有中间结果可供执行工具访问 +> - **跟进任务**: 自动生成全面修复和事后分析任务（热修复模式） +> - **增强任务 JSON**: 包含诊断、影响和修复计划的完整上下文包 +> - 🔄 **统一架构** - 与 lite-plan 会话管理模式保持一致 +> - 📊 **更好的审计跟踪** - 所有 Bug 修复的自然历史记录 +> - 🎯 **改进的可重用性** - 任务 JSON 文件可通过 `/workflow:lite-execute` 重新执行 > > 详见 [CHANGELOG.md](CHANGELOG.md)。 @@ -140,7 +138,34 @@ CCW 包含内置的**命令指南技能**，帮助您有效地发现和使用命 - 🔍 可选代码审查: 否 / Claude / Gemini / Qwen / Codex 5. **阶段 5**: 观察实时执行和任务跟踪 -### **选项 2: 完整工作流** (综合规划) +### **选项 2: Lite-Fix 工作流** (🐛 推荐用于 Bug 修复) + +智能 Bug 诊断和修复工作流，具有自适应严重性评估： + +```bash +# 标准 Bug 修复（根据严重性自动适应） +/workflow:lite-fix "用户头像上传失败，返回 413 错误" + +# 生产热修复模式 +/workflow:lite-fix --hotfix "支付网关 5xx 错误" +``` + +**工作流特性**: +- **阶段 1**: 智能根因诊断，采用自适应搜索 +- **阶段 2**: 自动影响评估和风险评分 +- **阶段 3**: 基于复杂度的修复策略生成 +- **阶段 4**: 风险感知的验证计划 +- **阶段 5**: 用户确认与执行选择 +- **阶段 6**: 执行调度，完整产物跟踪 + +**会话产物** (保存到 `.workflow/.lite-fix/{bug-slug}-{timestamp}/`): +- `diagnosis.json` - 根因分析和复现步骤 +- `impact.json` - 风险评分、严重性和工作流适应 +- `fix-plan.json` - 修复策略和实现任务 +- `task.json` - 包含完整上下文的增强任务 JSON +- `followup.json` - 自动生成的跟进任务（仅热修复模式） + +### **选项 3: 完整工作流** (📋 综合规划) 适用于复杂项目的传统多阶段工作流：