catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-05 01:50:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: Generate comprehensive project overview README.md

Browse Source
This commit is contained in:
catlog22
2025-11-23 11:20:35 +08:00
parent 65a204a563
commit f09c6e2a7a
1 changed files with 257 additions and 127 deletions
Download Patch File Download Diff File Expand all files Collapse all files

384
README.md
View File

@@ -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.