From f09c6e2a7a64cd698f2adbc93d8df208688181cb Mon Sep 17 00:00:00 2001 From: catlog22 Date: Sun, 23 Nov 2025 11:20:35 +0800 Subject: [PATCH] docs: Generate comprehensive project overview README.md --- README.md | 384 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 257 insertions(+), 127 deletions(-) diff --git a/README.md b/README.md index 51daa59d..fd368f34 100644 --- a/README.md +++ b/README.md @@ -12,47 +12,132 @@ --- -**Claude Code Workflow (CCW)** transforms AI development from simple prompt chaining into a robust, context-first orchestration system. It solves execution uncertainty and error accumulation through structured planning, deterministic execution, and intelligent multi-model orchestration. +## 1. Overview -> **πŸŽ‰ Version 5.8.1: Lite-Plan Workflow & CLI Tools Enhancement** -> -> **Core Improvements**: -> - ✨ **Lite-Plan Workflow** (`/workflow:lite-plan`) - Lightweight interactive planning with intelligent automation -> - **Three-Dimensional Multi-Select Confirmation**: Task approval + Execution method + Code review tool -> - **Smart Code Exploration**: Auto-detects when codebase context is needed (use `-e` flag to force) -> - **Parallel Task Execution**: Identifies independent tasks for concurrent execution -> - **Flexible Execution**: Choose between Agent (@code-developer) or CLI (Gemini/Qwen/Codex) -> - **Optional Post-Review**: Built-in code quality analysis with your choice of AI tool -> - ✨ **CLI Tools Optimization** - Simplified command syntax with auto-model-selection -> - Removed `-m` parameter requirement for Gemini, Qwen, and Codex (auto-selects best model) -> - Clearer command structure and improved documentation -> - πŸ”„ **Execution Workflow Enhancement** - Streamlined phases with lazy loading strategy -> - 🎨 **CLI Explore Agent** - Improved visibility with yellow color scheme -> -> See [CHANGELOG.md](CHANGELOG.md) for full details. +Claude Code Workflow (CCW) transforms AI development from simple prompt chaining into a robust, context-first orchestration system. It solves execution uncertainty and error accumulation through structured planning, deterministic execution, and intelligent multi-model orchestration. CCW is designed for AI developers and software engineers seeking to streamline their development processes. -> πŸ“š **New to CCW?** Check out the [**Getting Started Guide**](GETTING_STARTED.md) for a beginner-friendly 5-minute tutorial! +**Key Features**: +* **Context-First Architecture**: Ensures agents receive correct information before implementation. +* **JSON-First State Management**: Task states use `.task/IMPL-*.json` files as the single source of truth for programmatic orchestration. +* **Autonomous Multi-Phase Orchestration**: Commands chain specialized sub-commands and agents to automate complex workflows. +* **Multi-Model Strategy**: Leverages Gemini for analysis, Codex for implementation, and Qwen for architecture/planning. +* **Hierarchical Memory System**: A 4-layer CLAUDE.md documentation system provides context at appropriate abstraction levels. +* **Specialized Role-Based Agents**: A suite of agents (e.g., `@code-developer`, `@test-fix-agent`) mirrors a real software team. +* **Lite-Plan Workflow**: A lightweight interactive planning and execution workflow with in-memory planning, smart code exploration, three-dimensional multi-select confirmation, and parallel task execution support. +* **CLI Tools Optimization**: Simplified command syntax with auto-model-selection for Gemini, Qwen, and Codex. --- -## ✨ Core Concepts +## 2. System Architecture -CCW is built on a set of core principles that differentiate it from traditional AI development approaches: +CCW is built on a foundation of robust design principles and a multi-layered architecture to facilitate AI-driven software development. -- **Context-First Architecture**: Pre-defined context gathering eliminates execution uncertainty by ensuring agents have the correct information *before* implementation. -- **JSON-First State Management**: Task states live in `.task/IMPL-*.json` files as the single source of truth, enabling programmatic orchestration without state drift. -- **Autonomous Multi-Phase Orchestration**: Commands chain specialized sub-commands and agents to automate complex workflows with zero user intervention. -- **Multi-Model Strategy**: Leverages the unique strengths of different AI models (Gemini for analysis, Codex for implementation) for superior results. -- **Hierarchical Memory System**: A 4-layer documentation system provides context at the appropriate level of abstraction, preventing information overload. -- **Specialized Role-Based Agents**: A suite of agents (`@code-developer`, `@test-fix-agent`, etc.) mirrors a real software team to handle diverse tasks. +### Architectural Style and Design Principles + +**Design Philosophy**: +* **Context-First Architecture**: Pre-defined context gathering eliminates execution uncertainty. +* **JSON-First State Management**: Task states live in `.task/IMPL-*.json` files as the single source of truth. +* **Autonomous Multi-Phase Orchestration**: Commands chain specialized sub-commands and agents. +* **Multi-Model Strategy**: Leverages the unique strengths of different AI models (Gemini for analysis, Codex for implementation, Qwen for architecture and planning). +* **Hierarchical Memory System**: A 4-layer documentation system provides context at the appropriate level of abstraction. +* **Specialized Role-Based Agents**: A suite of agents mirrors a real software team. + +**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**: 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. + +### System Architecture Diagram + +```mermaid +graph TB + subgraph "User Interface Layer" + CLI[Slash Commands] + CHAT[Natural Language] + end + + subgraph "Orchestration Layer" + WF[Workflow Engine] + SM[Session Manager] + TM[Task Manager] + end + + subgraph "Agent Layer" + AG1[@code-developer] + AG2[@test-fix-agent] + AG3[@ui-design-agent] + AG4[@cli-execution-agent] + AG5[More Agents...] + end + + subgraph "Tool Layer" + GEMINI[Gemini CLI] + QWEN[Qwen CLI] + CODEX[Codex CLI] + BASH[Bash/System] + end + + subgraph "Data Layer" + JSON[Task JSON Files] + MEM[CLAUDE.md Memory] + STATE[Session State] + end + + CLI --> WF + CHAT --> WF + WF --> SM + WF --> TM + SM --> STATE + TM --> JSON + WF --> AG1 + WF --> AG2 + WF --> AG3 + WF --> AG4 + AG1 --> GEMINI + AG1 --> QWEN + AG1 --> CODEX + AG2 --> BASH + AG3 --> GEMINI + AG4 --> CODEX + GEMINI --> MEM + QWEN --> MEM + CODEX --> JSON +``` + +### Core Components + +1. **Workflow Engine**: Orchestrates complex development processes through planning, execution, verification, testing, and review phases. +2. **Session Manager**: Manages isolated workflow contexts, providing directory-based session tracking, persistence, parallel support, and archival. +3. **Task Manager**: Handles hierarchical task structures using a JSON-first data model, dynamic subtask creation, and dependency tracking. +4. **Memory System**: A four-layer hierarchical CLAUDE.md documentation system for project knowledge (`CLAUDE.md`, `src/CLAUDE.md`, `auth/CLAUDE.md`, `jwt/CLAUDE.md`). +5. **Multi-Agent System**: Specialized agents for different types of tasks, such as `@code-developer` (implementation), `@test-fix-agent` (testing), `@ui-design-agent` (UI design), `@action-planning-agent` (planning), and `@cli-execution-agent` (CLI task handling). +6. **CLI Tool Integration**: Seamlessly integrates Gemini CLI (for deep analysis), Qwen CLI (for architecture and planning), and Codex CLI (for autonomous development). --- -## βš™οΈ Installation +## 3. Getting Started -For detailed installation instructions, please refer to the [**INSTALL.md**](INSTALL.md) guide. +This section provides a quick guide to installing, configuring, and running Claude Code Workflow. -### **πŸš€ Quick One-Line Installation** +### Prerequisites + +Before you begin, ensure you have the following: +* **Claude Code**: The latest version installed. +* **Git**: For version control. +* **Text Editor**: VS Code, Vim, or your preferred editor. +* **Basic Knowledge**: Familiarity with Bash scripting, Markdown formatting, JSON structure, and Git workflow. + +### Installation + +For detailed installation instructions, please refer to the [INSTALL.md](INSTALL.md) guide. + +#### πŸš€ Quick One-Line Installation **Windows (PowerShell):** ```powershell @@ -64,36 +149,158 @@ Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/cat bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.sh) ``` -### **βœ… Verify Installation** +The installer provides an interactive menu for version selection (Latest Stable Release, Latest Development Version, or Specific Release Version). + +#### βœ… Verify Installation + After installation, open **Claude Code** and check if the workflow commands are available by running: ```bash /workflow:session:list ``` -If the slash commands (e.g., `/workflow:*`) are recognized, the installation was successful. +If slash commands like `/workflow:*` are recognized, the installation was successful. + +### Configuration + +CCW uses a **configuration-based tool control system** that makes external CLI tools optional. This allows for progressive enhancement, graceful degradation, and flexible configuration. + +**Configuration File**: `~/.claude/workflows/tool-control.yaml` + +**Optional CLI Tools** (for enhanced capabilities): +* **System Utilities**: `ripgrep (rg)` for fast code search, `jq` for JSON processing. +* **External AI Tools**: Gemini CLI, Codex CLI, Qwen Code. These need to be configured in `tool-control.yaml` after installation. + +### Running the Project (Quick Start) + +Let's build a "Hello World" web application from scratch with a simple example. For a more detailed tutorial, see the [Getting Started Guide](GETTING_STARTED.md). + +#### Step 1: Create an Execution Plan (Automatically Starts a Session) + +Tell CCW what you want to do. CCW will analyze your request and automatically generate a detailed, executable task plan. + +```bash +/workflow:plan "Create a simple Express API that returns Hello World at the root path" +``` +This command initiates a planning process including context gathering, AI agent analysis, and task generation. + +#### Step 2: Execute the Plan + +Once the plan is created, command the AI agents to start working. + +```bash +/workflow:execute +``` +CCW's agents (e.g., `@code-developer`) will execute tasks, create files, write code, and install dependencies. + +#### Step 3: Check the Status + +Check the progress of the current workflow at any time. + +```bash +/workflow:status +``` +This command shows the completion status of tasks, the currently executing task, and next steps. --- -## πŸ› οΈ Command Reference +## 4. Development Workflow -CCW provides a rich set of commands for managing workflows, tasks, and interacting with AI tools. For a complete list and detailed descriptions of all available commands, please see the [**COMMAND_REFERENCE.md**](COMMAND_REFERENCE.md) file. +This section outlines the development processes, coding standards, testing practices, and guidelines for contributing to CCW. -For a detailed technical specification of every command, see the [**COMMAND_SPEC.md**](COMMAND_SPEC.md). +### Development Setup + +1. **Fork and Clone**: Fork the repository on GitHub and then clone your fork. +2. **Set Up Upstream Remote**: Add the upstream remote to keep your fork in sync. +3. **Create Development Branch**: Create a feature branch for your work. +4. **Install CCW for Testing**: Install your development version of CCW. + +### How to Contribute + +CCW welcomes contributions in the form of bug fixes, new features, documentation improvements, new commands, and new agents. Refer to the [CONTRIBUTING.md](CONTRIBUTING.md) for detailed instructions. + +### Coding Standards + +**General Principles**: +* Follow the project's core beliefs (simplicity, clear intent, pragmatic solutions). +* Ensure single responsibility per function/class. +* Avoid premature abstractions and clever tricks. +* Maintain backward compatibility. +* Make incremental progress with small, testable changes. +* Learn from existing code and follow existing style/patterns. + +**Specific Standards**: +* **Bash Script Standards**: Use `set -euo pipefail`, function definitions, and a `main` function structure. +* **JSON Standards**: Use 2-space indentation, validate syntax, and include all required fields. +* **Markdown Standards**: Use clear headings, bullet points, code blocks, and proper emphasis. +* **File Organization**: Follow the established directory structure for agents, commands, skills, and workflows within `.claude/`. + +### Testing Guidelines + +* **Manual Testing**: Test happy paths, error handling, and edge cases. +* **Integration Testing**: Verify how your changes interact with existing commands and workflows. +* **Testing Checklist**: Ensure commands execute without errors, error messages are clear, session state is preserved, and documentation is accurate. + +### Submitting Changes + +* **Commit Message Guidelines**: Follow the Conventional Commits specification (e.g., `feat(workflow): add new command`). +* **Pull Request Process**: Create a pull request on GitHub, fill out the PR template, link related issues, and address review comments. --- -### πŸ’‘ **Need Help? Use the Interactive Command Guide** +## 5. Project Structure + +The project follows a modular and organized structure to manage agents, commands, skills, and workflows effectively. + +``` +. +β”œβ”€β”€ .claude/ # Internal Claude configurations, agents, commands, skills, and workflows +β”‚ β”œβ”€β”€ agents/ # Definitions and roles of AI agents +β”‚ β”œβ”€β”€ commands/ # Implementations of CCW slash commands +β”‚ β”œβ”€β”€ scripts/ # Utility scripts for various tasks +β”‚ β”œβ”€β”€ skills/ # Modular, reusable AI capabilities (e.g., command-guide) +β”‚ β”œβ”€β”€ templates/ # Generic templates for different workflows +β”‚ └── workflows/ # Workflow definitions, strategies, and related documentation +β”œβ”€β”€ .git/ # Git repository data +β”œβ”€β”€ .gemini/ # Gemini CLI tool configurations +β”œβ”€β”€ .codex/ # Codex CLI tool configurations +β”œβ”€β”€ ARCHITECTURE.md # High-level system architecture overview +β”œβ”€β”€ CHANGELOG.md # Detailed history of project changes and releases +β”œβ”€β”€ CLAUDE.md # Core development guidelines and philosophical principles +β”œβ”€β”€ COMMAND_REFERENCE.md # Comprehensive reference for all CCW commands +β”œβ”€β”€ COMMAND_SPEC.md # Detailed technical specifications for each command +β”œβ”€β”€ CONTRIBUTING.md # Guidelines for contributing to the project +β”œβ”€β”€ GETTING_STARTED.md # Quick start guide for new users +β”œβ”€β”€ INSTALL.md # Instructions for installing CCW +β”œβ”€β”€ LICENSE # Project's open-source license information +β”œβ”€β”€ README.md # This overview documentation file +└── WORKFLOW_DIAGRAMS.md # Visual diagrams illustrating CCW workflows and architecture +``` + +--- + +## 6. Navigation + +This section provides links to more detailed documentation for various aspects of Claude Code Workflow. + +### πŸ“– Documentation + +* [**Getting Started Guide**](GETTING_STARTED.md) - A 5-minute quick start tutorial for new users. +* [**Installation Guide**](INSTALL.md) - Detailed instructions on how to install CCW. +* [**Command Reference**](COMMAND_REFERENCE.md) - A complete list of all available CCW commands with brief descriptions. +* [**Command Specification**](COMMAND_SPEC.md) - Detailed technical specifications for every command. +* [**Architecture Overview**](ARCHITECTURE.md) - An in-depth look at the system's design and core components. +* [**Workflow Decision Guide**](WORKFLOW_DECISION_GUIDE.md) - An interactive flowchart to help choose the right commands and workflows. +* [**Changelog**](CHANGELOG.md) - A history of all notable changes and releases. +* [**Contributing Guide**](CONTRIBUTING.md) - Guidelines and instructions for contributing to the project. +* [**Examples**](EXAMPLES.md) - Real-world use cases and practical examples of CCW in action. +* [**FAQ**](FAQ.md) - Frequently asked questions and troubleshooting tips. +* [**Workflow Diagrams**](WORKFLOW_DIAGRAMS.md) - Visual representations of CCW's various workflows. +* [**Development Guidelines**](CLAUDE.md) - Core development principles and coding standards. + +### πŸ’‘ 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 with 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 parameters, examples, and best practices -- πŸŽ“ **Beginner Onboarding** - Learn the top 14 essential commands with a guided learning path -- πŸ“ **Issue Reporting** - Generate standardized bug reports and feature requests +* **`CCW-help`**: Get interactive help and command recommendations. +* **`CCW-issue`**: Report bugs or request features with guided templates. **Example Usage**: ``` @@ -109,90 +316,13 @@ User: "CCW-issue" --- -## πŸš€ Getting Started - -The best way to get started is to follow the 5-minute tutorial in the [**Getting Started Guide**](GETTING_STARTED.md). - -Here is 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 auth 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 with task breakdown -4. **Phase 4**: Three-dimensional confirmation: - - βœ… Confirm/Modify/Cancel task - - πŸ”§ Choose execution: Agent / Provide Plan / CLI (Gemini/Qwen/Codex) - - πŸ” Optional code review: No / Claude / Gemini / Qwen / Codex -5. **Phase 5**: Watch real-time execution with live task tracking - -### **Option 2: Full Workflow** (Comprehensive Planning) - -Traditional multi-phase workflow for complex projects: - -1. **Create a Plan** (automatically starts a session): - ```bash - /workflow:plan "Implement JWT-based user login and registration" - ``` -2. **Execute the Plan**: - ```bash - /workflow:execute - ``` -3. **Check Status** (optional): - ```bash - /workflow:status - ``` - ---- - -## πŸ“š Documentation - -CCW provides comprehensive documentation to help you get started 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_EN.md) - 🌳 Interactive flowchart for choosing the right commands -- [**Examples**](EXAMPLES.md) - Real-world use cases and practical examples -- [**FAQ**](FAQ.md) - Frequently asked 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 Specification**](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. +* **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. +This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details. \ No newline at end of file