Claude-Code-Workflow/README.md

🚀 Claude Code Workflow (CCW)

Languages: English | 中文

---

1. Overview

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.

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.

---

2. System Architecture

CCW is built on a foundation of robust design principles and a multi-layered architecture to facilitate AI-driven software development.

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

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

---

3. Getting Started

This section provides a quick guide to installing, configuring, and running Claude Code Workflow.

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

🚀 Quick One-Line Installation

Windows (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 <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.sh)

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:

/workflow:session:list

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.

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.

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

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

/workflow:status

This command shows the completion status of tasks, the currently executing task, and next steps.

---

4. Development Workflow

This section outlines the development processes, coding standards, testing practices, and guidelines for contributing to CCW.

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

---

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 - A 5-minute quick start tutorial for new users.
• Installation Guide - Detailed instructions on how to install CCW.
• Command Reference - A complete list of all available CCW commands with brief descriptions.
• Command Specification - Detailed technical specifications for every command.
• Architecture Overview - An in-depth look at the system's design and core components.
• Workflow Decision Guide - An interactive flowchart to help choose the right commands and workflows.
• Changelog - A history of all notable changes and releases.
• Contributing Guide - Guidelines and instructions for contributing to the project.
• Examples - Real-world use cases and practical examples of CCW in action.
• FAQ - Frequently asked questions and troubleshooting tips.
• Workflow Diagrams - Visual representations of CCW's various workflows.
• Development Guidelines - 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.

Example Usage:

User: "CCW-help"
→ Interactive menu with command search, recommendations, and documentation

User: "What's next after /workflow:plan?"
→ Recommends /workflow:execute, /workflow:action-plan-verify, with workflow patterns

User: "CCW-issue"
→ Guided template generation for bugs, features, or questions

---

🤝 Contributing & Support

• Repository: GitHub - Claude-Code-Workflow
• Issues: Report bugs or request features on GitHub Issues.
• Discussions: Join the Community Forum.
• Contributing: See CONTRIBUTING.md for contribution guidelines.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.