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

docs: add comprehensive project documentation

Browse Source 
Add four new comprehensive documentation files and update READMEs:

New Documentation:
- ARCHITECTURE.md: High-level system architecture overview
  * Design philosophy and core principles
  * System components and data flow
  * Multi-agent system details
  * CLI tool integration strategy
  * Session and memory management
  * Performance optimizations and best practices

- CONTRIBUTING.md: Contributor guidelines
  * Code of conduct
  * Development setup instructions
  * Coding standards and best practices
  * Testing guidelines
  * Documentation requirements
  * Pull request process
  * Release process

- FAQ.md: Frequently asked questions
  * General questions about CCW
  * Installation and setup
  * Usage and workflows
  * Commands and syntax
  * Sessions and tasks
  * Agents and tools
  * Memory system
  * Troubleshooting
  * Advanced topics

- EXAMPLES.md: Real-world use cases
  * Quick start examples
  * Web development (Express, React, e-commerce)
  * API development (REST, GraphQL)
  * Testing & quality assurance (TDD, test generation)
  * Refactoring (monolith to microservices)
  * UI/UX design (design systems, landing pages)
  * Bug fixes (simple and complex)
  * Documentation generation
  * DevOps & automation (CI/CD, Docker)
  * Complex projects (chat app, analytics dashboard)

Updated Documentation:
- README.md: Added comprehensive documentation section
  * Organized docs into categories
  * Links to all new documentation files
  * Improved navigation structure

- README_CN.md: Added documentation section (Chinese)
  * Same organization as English version
  * Links to all documentation resources

Benefits:
- Provides clear entry points for new users
- Comprehensive reference for all features
- Real-world examples for practical learning
- Complete contributor onboarding
- Better project discoverability
This commit is contained in:
Claude
2025-11-20 04:44:15 +00:00
parent 2a63ab5e0a
commit fbd41a0851
6 changed files with 2897 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

567
ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,567 @@
# 🏗️ Claude Code Workflow (CCW) - Architecture Overview
This document provides a high-level overview of CCW's architecture, design principles, and system components.
---
## 📋 Table of Contents
- [Design Philosophy](#design-philosophy)
- [System Architecture](#system-architecture)
- [Core Components](#core-components)
- [Data Flow](#data-flow)
- [Multi-Agent System](#multi-agent-system)
- [CLI Tool Integration](#cli-tool-integration)
- [Session Management](#session-management)
- [Memory System](#memory-system)
---
## 🎯 Design Philosophy
CCW is built on several core design principles that differentiate it from traditional AI-assisted development tools:
### 1. **Context-First Architecture**
- Pre-defined context gathering eliminates execution uncertainty
- Agents receive the correct information *before* implementation
- Context is loaded dynamically based on task requirements
### 2. **JSON-First State Management**
- Task states live in `.task/IMPL-*.json` files as the single source of truth
- Markdown documents are read-only generated views
- Eliminates state drift and synchronization complexity
- Enables programmatic orchestration
### 3. **Autonomous Multi-Phase Orchestration**
- Commands chain specialized sub-commands and agents
- Automates complex workflows with zero user intervention
- Each phase validates its output before proceeding
### 4. **Multi-Model Strategy**
- Leverages unique strengths of different AI models
- Gemini for analysis and exploration
- Codex for implementation
- Qwen for architecture and planning
### 5. **Hierarchical Memory System**
- 4-layer documentation system (CLAUDE.md files)
- Provides context at the appropriate level of abstraction
- Prevents information overload
### 6. **Specialized Role-Based Agents**
- Suite of agents mirrors a real software team
- Each agent has specific responsibilities
- Agents collaborate to complete complex tasks
---
## 🏛️ System Architecture
```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**
The workflow engine orchestrates complex development processes through multiple phases:
- **Planning Phase**: Analyzes requirements and generates implementation plans
- **Execution Phase**: Coordinates agents to implement tasks
- **Verification Phase**: Validates implementation quality
- **Testing Phase**: Generates and executes tests
- **Review Phase**: Performs code review and quality analysis
**Key Features**:
- Multi-phase orchestration
- Automatic session management
- Context propagation between phases
- Quality gates at each phase transition
### 2. **Session Manager**
Manages isolated workflow contexts:
```
.workflow/
├── active/ # Active sessions
│ ├── WFS-user-auth/ # User authentication session
│ ├── WFS-payment/ # Payment integration session
│ └── WFS-dashboard/ # Dashboard redesign session
└── archives/ # Completed sessions
└── WFS-old-feature/ # Archived session
```
**Capabilities**:
- Directory-based session tracking
- Session state persistence
- Parallel session support
- Session archival and resumption
### 3. **Task Manager**
Handles hierarchical task structures:
```json
{
"id": "IMPL-1.2",
"title": "Implement JWT authentication",
"status": "pending",
"meta": {
"type": "feature",
"agent": "code-developer"
},
"context": {
"requirements": ["JWT authentication", "OAuth2 support"],
"focus_paths": ["src/auth", "tests/auth"],
"acceptance": ["JWT validation works", "OAuth flow complete"]
},
"flow_control": {
"pre_analysis": [...],
"implementation_approach": {...}
}
}
```
**Features**:
- JSON-first data model
- Hierarchical task decomposition (max 2 levels)
- Dynamic subtask creation
- Dependency tracking
### 4. **Memory System**
Four-layer hierarchical documentation:
```
CLAUDE.md (Project root - high-level overview)
├── src/CLAUDE.md (Source layer - module summaries)
│ ├── auth/CLAUDE.md (Module layer - component details)
│ │ └── jwt/CLAUDE.md (Component layer - implementation details)
```
**Memory Commands**:
- `/memory:update-full` - Complete project rebuild
- `/memory:update-related` - Incremental updates for changed modules
- `/memory:load` - Quick context loading for specific tasks
---
## 🔄 Data Flow
### Typical Workflow Execution Flow
```mermaid
sequenceDiagram
participant User
participant CLI
participant Workflow
participant Agent
participant Tool
participant Data
User->>CLI: /workflow:plan "Feature description"
CLI->>Workflow: Initialize planning workflow
Workflow->>Data: Create session
Workflow->>Agent: @action-planning-agent
Agent->>Tool: gemini-wrapper analyze
Tool->>Data: Update CLAUDE.md
Agent->>Data: Generate IMPL-*.json
Workflow->>User: Plan complete
User->>CLI: /workflow:execute
CLI->>Workflow: Start execution
Workflow->>Data: Load tasks from JSON
Workflow->>Agent: @code-developer
Agent->>Tool: Read context
Agent->>Tool: Implement code
Agent->>Data: Update task status
Workflow->>User: Execution complete
```
### Context Flow
```mermaid
graph LR
A[User Request] --> B[Context Gathering]
B --> C[CLAUDE.md Memory]
B --> D[Task JSON]
B --> E[Session State]
C --> F[Agent Context]
D --> F
E --> F
F --> G[Tool Execution]
G --> H[Implementation]
H --> I[Update State]
```
---
## 🤖 Multi-Agent System
### Agent Specialization
CCW uses specialized agents for different types of tasks:
| Agent | Responsibility | Tools Used |
|-------|---------------|------------|
| **@code-developer** | Code implementation | Gemini, Qwen, Codex, Bash |
| **@test-fix-agent** | Test generation and fixing | Codex, Bash |
| **@ui-design-agent** | UI design and prototyping | Gemini, Claude Vision |
| **@action-planning-agent** | Task planning and decomposition | Gemini |
| **@cli-execution-agent** | Autonomous CLI task handling | Codex, Gemini, Qwen |
| **@cli-explore-agent** | Codebase exploration | ripgrep, find |
| **@context-search-agent** | Context gathering | Grep, Glob |
| **@doc-generator** | Documentation generation | Gemini, Qwen |
| **@memory-bridge** | Memory system updates | Gemini, Qwen |
| **@universal-executor** | General task execution | All tools |
### Agent Communication
Agents communicate through:
1. **Shared Session State**: All agents can read/write session JSON
2. **Task JSON Files**: Tasks contain context for agent handoffs
3. **CLAUDE.md Memory**: Shared project knowledge base
4. **Flow Control**: Pre-analysis and implementation approach definitions
---
## 🛠️ CLI Tool Integration
### Three CLI Tools
CCW integrates three external AI tools, each optimized for specific tasks:
#### 1. **Gemini CLI** - Deep Analysis
- **Strengths**: Pattern recognition, architecture understanding, comprehensive analysis
- **Use Cases**:
- Codebase exploration
- Architecture analysis
- Bug diagnosis
- Memory system updates
#### 2. **Qwen CLI** - Architecture & Planning
- **Strengths**: System design, code generation, architectural planning
- **Use Cases**:
- Architecture design
- System planning
- Code generation
- Refactoring strategies
#### 3. **Codex CLI** - Autonomous Development
- **Strengths**: Self-directed implementation, error fixing, test generation
- **Use Cases**:
- Feature implementation
- Bug fixes
- Test generation
- Autonomous development
### Tool Selection Strategy
CCW automatically selects the best tool based on task type:
```
Analysis Task → Gemini CLI
Planning Task → Qwen CLI
Implementation Task → Codex CLI
```
Users can override with `--tool` parameter:
```bash
/cli:analyze --tool codex "Analyze authentication flow"
```
---
## 📦 Session Management
### Session Lifecycle
```mermaid
stateDiagram-v2
[*] --> Creating: /workflow:session:start
Creating --> Active: Session initialized
Active --> Paused: User pauses
Paused --> Active: /workflow:session:resume
Active --> Completed: /workflow:session:complete
Completed --> Archived: Move to archives/
Archived --> [*]
```
### Session Structure
```
.workflow/active/WFS-feature-name/
├── workflow-session.json # Session metadata
├── .task/ # Task JSON files
│ ├── IMPL-1.json
│ ├── IMPL-1.1.json
│ └── IMPL-2.json
├── .chat/ # Chat logs
├── brainstorming/ # Brainstorm artifacts
│ ├── guidance-specification.md
│ └── system-architect/analysis.md
└── artifacts/ # Generated files
├── IMPL_PLAN.md
└── verification-report.md
```
---
## 💾 Memory System
### Hierarchical CLAUDE.md Structure
The memory system maintains project knowledge across four layers:
#### **Layer 1: Project Root**
```markdown
# Project Overview
- High-level architecture
- Technology stack
- Key design decisions
- Entry points
```
#### **Layer 2: Source Directory**
```markdown
# Source Code Structure
- Module summaries
- Dependency relationships
- Common patterns
```
#### **Layer 3: Module Directory**
```markdown
# Module Details
- Component responsibilities
- API interfaces
- Internal structure
```
#### **Layer 4: Component Directory**
```markdown
# Component Implementation
- Function signatures
- Implementation details
- Usage examples
```
### Memory Update Strategies
#### Full Update (`/memory:update-full`)
- Rebuilds entire project documentation
- Uses layer-based execution (Layer 3 → 1)
- Batch processing (4 modules/agent)
- Fallback mechanism (gemini → qwen → codex)
#### Incremental Update (`/memory:update-related`)
- Updates only changed modules
- Analyzes git changes
- Efficient for daily development
#### Quick Load (`/memory:load`)
- No file updates
- Task-specific context gathering
- Returns JSON context package
- Fast context injection
---
## 🔐 Quality Assurance
### Quality Gates
CCW enforces quality at multiple levels:
1. **Planning Phase**:
- Requirements coverage check
- Dependency validation
- Task specification quality assessment
2. **Execution Phase**:
- Context validation before implementation
- Pattern consistency checks
- Test generation
3. **Review Phase**:
- Code quality analysis
- Security review
- Architecture review
### Verification Commands
- `/workflow:action-plan-verify` - Validates plan quality before execution
- `/workflow:tdd-verify` - Verifies TDD cycle compliance
- `/workflow:review` - Post-implementation review
---
## 🚀 Performance Optimizations
### 1. **Lazy Loading**
- Files created only when needed
- On-demand document generation
- Minimal upfront cost
### 2. **Parallel Execution**
- Independent tasks run concurrently
- Multi-agent parallel brainstorming
- Batch processing for memory updates
### 3. **Context Caching**
- CLAUDE.md acts as knowledge cache
- Reduces redundant analysis
- Faster context retrieval
### 4. **Atomic Session Management**
- Ultra-fast session switching (<10ms)
- Simple file marker system
- No database overhead
---
## 📊 Scalability
### Horizontal Scalability
- **Multiple Sessions**: Run parallel workflows for different features
- **Team Collaboration**: Session-based isolation prevents conflicts
- **Incremental Updates**: Only update affected modules
### Vertical Scalability
- **Hierarchical Tasks**: Efficient task decomposition (max 2 levels)
- **Selective Context**: Load only relevant context for each task
- **Batch Processing**: Process multiple modules per agent invocation
---
## 🔮 Extensibility
### Adding New Agents
Create agent definition in `.claude/agents/`:
```markdown
# Agent Name
## Role
Agent description
## Tools Available
- Tool 1
- Tool 2
## Prompt
Agent instructions...
```
### Adding New Commands
Create command in `.claude/commands/`:
```bash
#!/usr/bin/env bash
# Command implementation
```
### Custom Workflows
Combine existing commands to create custom workflows:
```bash
/workflow:brainstorm:auto-parallel "Topic"
/workflow:plan
/workflow:action-plan-verify
/workflow:execute
/workflow:review
```
---
## 🎓 Best Practices
### For Users
1. **Keep Memory Updated**: Run `/memory:update-related` after major changes
2. **Use Quality Gates**: Run `/workflow:action-plan-verify` before execution
3. **Session Management**: Complete sessions with `/workflow:session:complete`
4. **Tool Selection**: Let CCW auto-select tools unless you have specific needs
### For Developers
1. **Follow JSON-First**: Never modify markdown documents directly
2. **Agent Context**: Provide complete context in task JSON
3. **Error Handling**: Implement graceful fallbacks
4. **Testing**: Test agents independently before integration
---
## 📚 Further Reading
- [Getting Started Guide](GETTING_STARTED.md) - Quick start tutorial
- [Command Reference](COMMAND_REFERENCE.md) - All available commands
- [Command Specification](COMMAND_SPEC.md) - Detailed command specs
- [Workflow Diagrams](WORKFLOW_DIAGRAMS.md) - Visual workflow representations
- [Contributing Guide](CONTRIBUTING.md) - How to contribute
- [Examples](EXAMPLES.md) - Real-world use cases
---
**Last Updated**: 2025-11-20
**Version**: 5.8.1

712
CONTRIBUTING.md Normal file
View File

@@ -0,0 +1,712 @@
# 🤝 Contributing to Claude Code Workflow
Thank you for your interest in contributing to Claude Code Workflow (CCW)! This document provides guidelines and instructions for contributing to the project.
---
## 📋 Table of Contents
- [Code of Conduct](#code-of-conduct)
- [Getting Started](#getting-started)
- [Development Setup](#development-setup)
- [How to Contribute](#how-to-contribute)
- [Coding Standards](#coding-standards)
- [Testing Guidelines](#testing-guidelines)
- [Documentation Guidelines](#documentation-guidelines)
- [Submitting Changes](#submitting-changes)
- [Release Process](#release-process)
---
## 📜 Code of Conduct
### Our Pledge
We are committed to providing a welcoming and inclusive environment for all contributors, regardless of:
- Experience level
- Background
- Identity
- Perspective
### Our Standards
**Positive behaviors**:
- Using welcoming and inclusive language
- Being respectful of differing viewpoints
- Gracefully accepting constructive criticism
- Focusing on what is best for the community
- Showing empathy towards other community members
**Unacceptable behaviors**:
- Trolling, insulting/derogatory comments, and personal attacks
- Public or private harassment
- Publishing others' private information without permission
- Other conduct which could reasonably be considered inappropriate
---
## 🚀 Getting Started
### Prerequisites
Before contributing, ensure you have:
1. **Claude Code** - The latest version installed ([Installation Guide](INSTALL.md))
2. **Git** - For version control
3. **Text Editor** - VS Code, Vim, or your preferred editor
4. **Basic Knowledge**:
- Bash scripting
- Markdown formatting
- JSON structure
- Git workflow
### Understanding the Codebase
Start by reading:
1. [README.md](README.md) - Project overview
2. [ARCHITECTURE.md](ARCHITECTURE.md) - System architecture
3. [GETTING_STARTED.md](GETTING_STARTED.md) - Basic usage
4. [COMMAND_SPEC.md](COMMAND_SPEC.md) - Command specifications
---
## 💻 Development Setup
### 1. Fork and Clone
```bash
# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/YOUR_USERNAME/Claude-Code-Workflow.git
cd Claude-Code-Workflow
```
### 2. Set Up Upstream Remote
```bash
git remote add upstream https://github.com/catlog22/Claude-Code-Workflow.git
git fetch upstream
```
### 3. Create Development Branch
```bash
# Update your main branch
git checkout main
git pull upstream main
# Create feature branch
git checkout -b feature/your-feature-name
```
### 4. Install CCW for Testing
```bash
# Install your development version
bash Install-Claude.sh
# Or on Windows
powershell -ExecutionPolicy Bypass -File Install-Claude.ps1
```
---
## 🛠️ How to Contribute
### Types of Contributions
#### 1. **Bug Fixes**
- Report bugs via [GitHub Issues](https://github.com/catlog22/Claude-Code-Workflow/issues)
- Include reproduction steps
- Provide system information (OS, Claude Code version)
- Submit PR with fix
#### 2. **New Features**
- Discuss in [GitHub Discussions](https://github.com/catlog22/Claude-Code-Workflow/discussions)
- Create feature proposal issue
- Get community feedback
- Implement after approval
#### 3. **Documentation**
- Fix typos or clarify existing docs
- Add missing documentation
- Improve examples
- Translate to other languages
#### 4. **New Commands**
- Follow command template structure
- Include comprehensive documentation
- Add tests for command execution
- Update COMMAND_REFERENCE.md
#### 5. **New Agents**
- Define agent role clearly
- Specify tools required
- Provide usage examples
- Document in ARCHITECTURE.md
---
## 📏 Coding Standards
### General Principles
Follow the project's core beliefs (from [CLAUDE.md](CLAUDE.md)):
1. **Pursue good taste** - Eliminate edge cases for natural, elegant code
2. **Embrace extreme simplicity** - Avoid unnecessary complexity
3. **Be pragmatic** - Solve real-world problems
4. **Data structures first** - Focus on data design
5. **Never break backward compatibility** - Existing functionality is sacred
6. **Incremental progress** - Small changes that compile and pass tests
7. **Learn from existing code** - Study patterns before implementing
8. **Clear intent over clever code** - Be boring and obvious
### Bash Script Standards
```bash
#!/usr/bin/env bash
# Command: /workflow:example
# Description: Brief description of what this command does
set -euo pipefail # Exit on error, undefined vars, pipe failures
# Function definitions
function example_function() {
local param1="$1"
local param2="${2:-default}"
# Implementation
}
# Main execution
function main() {
# Validate inputs
# Execute logic
# Handle errors
}
# Run main if executed directly
if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
main "$@"
fi
```
### JSON Standards
```json
{
"id": "IMPL-1",
"title": "Task title",
"status": "pending",
"meta": {
"type": "feature",
"agent": "code-developer",
"priority": "high"
},
"context": {
"requirements": ["Requirement 1", "Requirement 2"],
"focus_paths": ["src/module/"],
"acceptance": ["Criterion 1", "Criterion 2"]
}
}
```
**Rules**:
- Use 2-space indentation
- Always validate JSON syntax
- Include all required fields
- Use clear, descriptive values
### Markdown Standards
```markdown
# Main Title (H1) - One per document
## Section Title (H2)
### Subsection (H3)
- Use bullet points for lists
- Use `code blocks` for commands
- Use **bold** for emphasis
- Use *italics* for technical terms
```bash
# Code blocks with language specification
command --flag value
```
> Use blockquotes for important notes
```
### File Organization
```
.claude/
├── agents/ # Agent definitions
│ ├── agent-name.md
├── commands/ # Slash commands
│ └── workflow/
│ ├── workflow-plan.md
├── skills/ # Agent skills
│ └── skill-name/
│ ├── SKILL.md
└── workflows/ # Workflow docs
├── workflow-architecture.md
```
---
## 🧪 Testing Guidelines
### Manual Testing
Before submitting PR:
1. **Test the Happy Path**
```bash
# Test basic functionality
/your:new:command "basic input"
```
2. **Test Error Handling**
```bash
# Test with invalid input
/your:new:command ""
/your:new:command --invalid-flag
```
3. **Test Edge Cases**
```bash
# Test with special characters
/your:new:command "input with 'quotes'"
# Test with long input
/your:new:command "very long input string..."
```
### Integration Testing
Test how your changes interact with existing commands:
```bash
# Example workflow test
/workflow:session:start "Test Feature"
/your:new:command "test input"
/workflow:status
/workflow:session:complete
```
### Testing Checklist
- [ ] Command executes without errors
- [ ] Error messages are clear and helpful
- [ ] Session state is preserved correctly
- [ ] JSON files are created with correct structure
- [ ] Memory system updates work correctly
- [ ] Works on both Linux and Windows
- [ ] Documentation is accurate
---
## 📚 Documentation Guidelines
### Command Documentation
Every new command must include:
#### 1. **Inline Documentation** (in command file)
```bash
#!/usr/bin/env bash
# Command: /workflow:example
# Description: One-line description
# Usage: /workflow:example [options] <arg>
#
# Options:
# --option1 Description of option1
# --option2 Description of option2
#
# Examples:
# /workflow:example "basic usage"
# /workflow:example --option1 value "advanced usage"
```
#### 2. **COMMAND_REFERENCE.md Entry**
Add entry to the appropriate section:
```markdown
| `/workflow:example` | Brief description of the command. |
```
#### 3. **COMMAND_SPEC.md Entry**
Add detailed specification:
```markdown
### `/workflow:example`
**Purpose**: Detailed description of what this command does and when to use it.
**Parameters**:
- `arg` (required): Description of argument
- `--option1` (optional): Description of option
**Workflow**:
1. Step 1
2. Step 2
3. Step 3
**Output**:
- Creates: Files created
- Updates: Files updated
- Returns: Return value
**Examples**:
```bash
/workflow:example "example input"
```
**Related Commands**:
- `/related:command1` - Description
- `/related:command2` - Description
```
### Agent Documentation
Every new agent must include:
```markdown
# Agent Name
## Role
Clear description of agent's responsibility and purpose.
## Specialization
What makes this agent unique and when to use it.
## Tools Available
- Tool 1: Usage
- Tool 2: Usage
- Tool 3: Usage
## Invocation
How the agent is typically invoked (manually or by workflow).
## Context Requirements
What context the agent needs to function effectively.
## Output
What the agent produces.
## Examples
Real usage examples.
## Prompt
The actual agent instructions...
```
---
## 📤 Submitting Changes
### Commit Message Guidelines
Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
```
<type>(<scope>): <subject>
<body>
<footer>
```
**Types**:
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Code style changes (formatting, etc.)
- `refactor`: Code refactoring
- `test`: Adding or updating tests
- `chore`: Maintenance tasks
**Examples**:
```
feat(workflow): add workflow:example command
Add new workflow command for example functionality.
Includes:
- Command implementation
- Documentation updates
- Test cases
Closes #123
```
```
fix(memory): resolve memory update race condition
Fix race condition when multiple agents update memory
simultaneously by adding file locking mechanism.
Fixes #456
```
```
docs(readme): update installation instructions
Clarify Windows installation steps and add troubleshooting
section for common issues.
```
### Pull Request Process
1. **Update your branch**
```bash
git fetch upstream
git rebase upstream/main
```
2. **Push to your fork**
```bash
git push origin feature/your-feature-name
```
3. **Create Pull Request**
- Go to GitHub and create PR
- Fill out PR template
- Link related issues
- Add screenshots/examples if applicable
4. **PR Title Format**
```
feat: Add workflow:example command
fix: Resolve memory update issue
docs: Update contributing guide
```
5. **PR Description Template**
```markdown
## Description
Brief description of changes
## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Refactoring
## Related Issues
Closes #123
## Testing
- [ ] Tested on Linux
- [ ] Tested on Windows
- [ ] Added/updated documentation
## Screenshots (if applicable)
## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No breaking changes (or documented)
```
6. **Address Review Comments**
- Respond to all comments
- Make requested changes
- Push updates to same branch
- Re-request review when ready
---
## 🎯 Development Workflow
### Feature Development
```bash
# 1. Create branch
git checkout -b feat/new-command
# 2. Implement feature
# - Write code
# - Add documentation
# - Test thoroughly
# 3. Commit changes
git add .
git commit -m "feat(workflow): add new command"
# 4. Push and create PR
git push origin feat/new-command
```
### Bug Fix
```bash
# 1. Create branch
git checkout -b fix/issue-123
# 2. Fix bug
# - Identify root cause
# - Implement fix
# - Add regression test
# 3. Commit fix
git commit -m "fix: resolve issue #123"
# 4. Push and create PR
git push origin fix/issue-123
```
---
## 🔄 Release Process
### Version Numbering
CCW follows [Semantic Versioning](https://semver.org/):
- **MAJOR**: Breaking changes
- **MINOR**: New features (backward compatible)
- **PATCH**: Bug fixes (backward compatible)
Example: `v5.8.1`
- `5`: Major version
- `8`: Minor version
- `1`: Patch version
### Release Checklist
Maintainers will:
1. Update version in:
- `README.md`
- `README_CN.md`
- All documentation headers
2. Update `CHANGELOG.md`:
```markdown
## [v5.9.0] - 2025-11-20
### Added
- New feature 1
- New feature 2
### Fixed
- Bug fix 1
- Bug fix 2
### Changed
- Change 1
```
3. Create release tag:
```bash
git tag -a v5.9.0 -m "Release v5.9.0"
git push origin v5.9.0
```
4. Create GitHub Release with:
- Release notes from CHANGELOG.md
- Installation scripts
- Migration guide (if breaking changes)
---
## 💡 Tips for Contributors
### Best Practices
1. **Start Small**
- Fix documentation typos
- Add examples
- Improve error messages
- Then move to larger features
2. **Ask Questions**
- Use GitHub Discussions for questions
- Ask before starting major work
- Clarify requirements early
3. **Follow Existing Patterns**
- Study similar commands before creating new ones
- Maintain consistency with existing code
- Reuse existing utilities
4. **Test Thoroughly**
- Test on both Linux and Windows if possible
- Test with different input types
- Test integration with existing workflows
5. **Document Everything**
- Clear commit messages
- Comprehensive PR descriptions
- Updated documentation
- Code comments where necessary
### Common Pitfalls to Avoid
❌ **Don't**:
- Break backward compatibility without discussion
- Add features without documentation
- Submit large PRs without prior discussion
- Ignore failing tests
- Copy code without attribution
✅ **Do**:
- Keep PRs focused and small
- Update documentation with code changes
- Add tests for new features
- Follow project coding standards
- Be responsive to review comments
---
## 📞 Getting Help
### Resources
- **Documentation**: Read all docs in repository
- **Discussions**: [GitHub Discussions](https://github.com/catlog22/Claude-Code-Workflow/discussions)
- **Issues**: [GitHub Issues](https://github.com/catlog22/Claude-Code-Workflow/issues)
- **Command Guide**: Use `CCW-help` within Claude Code
### Contact
- **Bug Reports**: GitHub Issues
- **Feature Requests**: GitHub Discussions
- **Questions**: GitHub Discussions
- **Security Issues**: Create private security advisory
---
## 🙏 Recognition
Contributors will be:
- Listed in CHANGELOG.md for their contributions
- Mentioned in release notes
- Credited in commit history
- Appreciated by the community!
---
## 📄 License
By contributing to CCW, you agree that your contributions will be licensed under the [MIT License](LICENSE).
---
**Thank you for contributing to Claude Code Workflow!** 🎉
Your contributions help make AI-assisted development better for everyone.
---
**Last Updated**: 2025-11-20
**Version**: 5.8.1

820
EXAMPLES.md Normal file
View File

@@ -0,0 +1,820 @@
# 📖 Claude Code Workflow - Real-World Examples
This document provides practical, real-world examples of using CCW for common development tasks.
---
## 📋 Table of Contents
- [Quick Start Examples](#quick-start-examples)
- [Web Development](#web-development)
- [API Development](#api-development)
- [Testing & Quality Assurance](#testing--quality-assurance)
- [Refactoring](#refactoring)
- [UI/UX Design](#uiux-design)
- [Bug Fixes](#bug-fixes)
- [Documentation](#documentation)
- [DevOps & Automation](#devops--automation)
- [Complex Projects](#complex-projects)
---
## 🚀 Quick Start Examples
### Example 1: Simple Express API
**Objective**: Create a basic Express.js API with CRUD operations
```bash
# Option 1: Lite workflow (fastest)
/workflow:lite-plan "Create Express API with CRUD endpoints for users (GET, POST, PUT, DELETE)"
# Option 2: Full workflow (more structured)
/workflow:plan "Create Express API with CRUD endpoints for users"
/workflow:execute
```
**What CCW does**:
1. Analyzes your project structure
2. Creates Express app setup
3. Implements CRUD routes
4. Adds error handling middleware
5. Creates basic tests
**Result**:
```
src/
├── app.js # Express app setup
├── routes/
│ └── users.js # User CRUD routes
├── controllers/
│ └── userController.js
└── tests/
└── users.test.js
```
### Example 2: React Component
**Objective**: Create a React login form component
```bash
/workflow:lite-plan "Create a React login form component with email and password fields, validation, and submit handling"
```
**What CCW does**:
1. Creates LoginForm component
2. Adds form validation (email format, password requirements)
3. Implements state management
4. Adds error display
5. Creates component tests
**Result**:
```jsx
// components/LoginForm.jsx
import React, { useState } from 'react';
export function LoginForm({ onSubmit }) {
const [email, setEmail] = useState('');
const [password, setPassword] = useState('');
const [errors, setErrors] = useState({});
// ... validation and submit logic
}
```
---
## 🌐 Web Development
### Example 3: Full-Stack Todo Application
**Objective**: Build a complete todo application with React frontend and Express backend
#### Phase 1: Planning with Brainstorming
```bash
# Multi-perspective analysis
/workflow:brainstorm:auto-parallel "Full-stack todo application with user authentication, real-time updates, and dark mode"
# Review brainstorming artifacts
# Then create implementation plan
/workflow:plan
# Verify plan quality
/workflow:action-plan-verify
```
**Brainstorming generates**:
- System architecture analysis
- UI/UX design recommendations
- Data model design
- Security considerations
- API design patterns
#### Phase 2: Implementation
```bash
# Execute the plan
/workflow:execute
# Monitor progress
/workflow:status
```
**What CCW implements**:
**Backend** (`server/`):
- Express server setup
- MongoDB/PostgreSQL integration
- JWT authentication
- RESTful API endpoints
- WebSocket for real-time updates
- Input validation middleware
**Frontend** (`client/`):
- React app with routing
- Authentication flow
- Todo CRUD operations
- Real-time updates via WebSocket
- Dark mode toggle
- Responsive design
#### Phase 3: Testing
```bash
# Generate comprehensive tests
/workflow:test-gen WFS-todo-application
# Execute test tasks
/workflow:execute
# Run iterative test-fix cycle
/workflow:test-cycle-execute
```
**Tests created**:
- Unit tests for components
- Integration tests for API
- E2E tests for user flows
- Authentication tests
- WebSocket connection tests
#### Phase 4: Quality Review
```bash
# Security review
/workflow:review --type security
# Architecture review
/workflow:review --type architecture
# General quality review
/workflow:review
```
**Complete session**:
```bash
/workflow:session:complete
```
---
### Example 4: E-commerce Product Catalog
**Objective**: Build product catalog with search, filters, and pagination
```bash
# Start with UI design exploration
/workflow:ui-design:explore-auto --prompt "Modern e-commerce product catalog with grid layout, filters sidebar, and search bar" --targets "catalog,product-card" --style-variants 3
# Review designs in compare.html
# Sync selected designs
/workflow:ui-design:design-sync --session <session-id> --selected-prototypes "catalog-v2,product-card-v1"
# Create implementation plan
/workflow:plan
# Execute
/workflow:execute
```
**Features implemented**:
- Product grid with responsive layout
- Search functionality with debounce
- Category/price/rating filters
- Pagination with infinite scroll option
- Product card with image, title, price, rating
- Sort options (price, popularity, newest)
---
## 🔌 API Development
### Example 5: RESTful API with Authentication
**Objective**: Create RESTful API with JWT authentication and role-based access control
```bash
# Detailed planning
/workflow:plan "RESTful API with JWT authentication, role-based access control (admin, user), and protected endpoints for posts resource"
# Verify plan
/workflow:action-plan-verify
# Execute
/workflow:execute
```
**Implementation includes**:
**Authentication**:
```javascript
// routes/auth.js
POST /api/auth/register
POST /api/auth/login
POST /api/auth/refresh
POST /api/auth/logout
```
**Protected Resources**:
```javascript
// routes/posts.js
GET /api/posts # Public
GET /api/posts/:id # Public
POST /api/posts # Authenticated
PUT /api/posts/:id # Authenticated (owner or admin)
DELETE /api/posts/:id # Authenticated (owner or admin)
```
**Middleware**:
- `authenticate` - Verifies JWT token
- `authorize(['admin'])` - Role-based access
- `validateRequest` - Input validation
- `errorHandler` - Centralized error handling
### Example 6: GraphQL API
**Objective**: Convert REST API to GraphQL
```bash
# Analyze existing REST API
/cli:analyze "Analyze REST API structure in src/routes/"
# Plan GraphQL migration
/workflow:plan "Migrate REST API to GraphQL with queries, mutations, and subscriptions for posts and users"
# Execute migration
/workflow:execute
```
**GraphQL schema created**:
```graphql
type Query {
posts(limit: Int, offset: Int): [Post!]!
post(id: ID!): Post
user(id: ID!): User
}
type Mutation {
createPost(input: CreatePostInput!): Post!
updatePost(id: ID!, input: UpdatePostInput!): Post!
deletePost(id: ID!): Boolean!
}
type Subscription {
postCreated: Post!
postUpdated: Post!
}
```
---
## 🧪 Testing & Quality Assurance
### Example 7: Test-Driven Development (TDD)
**Objective**: Implement user authentication using TDD approach
```bash
# Start TDD workflow
/workflow:tdd-plan "User authentication with email/password login, registration, and password reset"
# Execute (Red-Green-Refactor cycles)
/workflow:execute
# Verify TDD compliance
/workflow:tdd-verify
```
**TDD cycle tasks created**:
**Cycle 1: Registration**
1. `IMPL-1.1` - Write failing test for user registration
2. `IMPL-1.2` - Implement registration to pass test
3. `IMPL-1.3` - Refactor registration code
**Cycle 2: Login**
1. `IMPL-2.1` - Write failing test for login
2. `IMPL-2.2` - Implement login to pass test
3. `IMPL-2.3` - Refactor login code
**Cycle 3: Password Reset**
1. `IMPL-3.1` - Write failing test for password reset
2. `IMPL-3.2` - Implement password reset
3. `IMPL-3.3` - Refactor password reset
### Example 8: Adding Tests to Existing Code
**Objective**: Generate comprehensive tests for existing authentication module
```bash
# Create test generation workflow from existing code
/workflow:test-gen WFS-authentication-implementation
# Execute test tasks
/workflow:execute
# Run test-fix cycle until all tests pass
/workflow:test-cycle-execute --max-iterations 5
```
**Tests generated**:
- Unit tests for each function
- Integration tests for auth flow
- Edge case tests (invalid input, expired tokens, etc.)
- Security tests (SQL injection, XSS, etc.)
- Performance tests (load testing, rate limiting)
**Test coverage**: Aims for 80%+ coverage
---
## 🔄 Refactoring
### Example 9: Monolith to Microservices
**Objective**: Refactor monolithic application to microservices architecture
#### Phase 1: Analysis
```bash
# Deep architecture analysis
/cli:mode:plan --tool gemini "Analyze current monolithic architecture and create microservices migration strategy"
# Multi-role brainstorming
/workflow:brainstorm:auto-parallel "Migrate monolith to microservices with API gateway, service discovery, and message queue" --count 5
```
#### Phase 2: Planning
```bash
# Create detailed migration plan
/workflow:plan "Phase 1 microservices migration: Extract user service and auth service from monolith"
# Verify plan
/workflow:action-plan-verify
```
#### Phase 3: Implementation
```bash
# Execute migration
/workflow:execute
# Review architecture
/workflow:review --type architecture
```
**Microservices created**:
```
services/
├── user-service/
│ ├── src/
│ ├── Dockerfile
│ └── package.json
├── auth-service/
│ ├── src/
│ ├── Dockerfile
│ └── package.json
├── api-gateway/
│ ├── src/
│ └── config/
└── docker-compose.yml
```
### Example 10: Code Optimization
**Objective**: Optimize database queries for performance
```bash
# Analyze current performance
/cli:mode:code-analysis "Analyze database query performance in src/repositories/"
# Create optimization plan
/workflow:plan "Optimize database queries with indexing, query optimization, and caching"
# Execute optimizations
/workflow:execute
```
**Optimizations implemented**:
- Database indexing strategy
- N+1 query elimination
- Query result caching (Redis)
- Connection pooling
- Pagination for large datasets
- Database query monitoring
---
## 🎨 UI/UX Design
### Example 11: Design System Creation
**Objective**: Create a complete design system for a SaaS application
```bash
# Extract design from reference
/workflow:ui-design:imitate-auto --input "https://example-saas.com"
# Or create from scratch
/workflow:ui-design:explore-auto --prompt "Modern SaaS design system with primary components: buttons, inputs, cards, modals, navigation" --targets "button,input,card,modal,navbar" --style-variants 3
```
**Design system includes**:
- Color palette (primary, secondary, accent, neutral)
- Typography scale (headings, body, captions)
- Spacing system (4px grid)
- Component library:
- Buttons (primary, secondary, outline, ghost)
- Form inputs (text, select, checkbox, radio)
- Cards (basic, elevated, outlined)
- Modals (small, medium, large)
- Navigation (sidebar, topbar, breadcrumbs)
- Animation patterns
- Responsive breakpoints
**Output**:
```
design-system/
├── tokens/
│ ├── colors.json
│ ├── typography.json
│ └── spacing.json
├── components/
│ ├── Button.jsx
│ ├── Input.jsx
│ └── ...
└── documentation/
└── design-system.html
```
### Example 12: Responsive Landing Page
**Objective**: Design and implement a marketing landing page
```bash
# Design exploration
/workflow:ui-design:explore-auto --prompt "Modern SaaS landing page with hero section, features grid, pricing table, testimonials, and CTA" --targets "hero,features,pricing,testimonials" --style-variants 2 --layout-variants 3 --device-type responsive
# Select best designs and sync
/workflow:ui-design:design-sync --session <session-id> --selected-prototypes "hero-v2,features-v1,pricing-v3"
# Implement
/workflow:plan
/workflow:execute
```
**Sections implemented**:
- Hero section with animated background
- Feature cards with icons
- Pricing comparison table
- Customer testimonials carousel
- FAQ accordion
- Contact form
- Responsive navigation
- Dark mode support
---
## 🐛 Bug Fixes
### Example 13: Quick Bug Fix
**Objective**: Fix login button not working on mobile
```bash
# Analyze bug
/cli:mode:bug-index "Login button click event not firing on mobile Safari"
# Claude analyzes and implements fix
```
**Fix implemented**:
```javascript
// Before
button.onclick = handleLogin;
// After (adds touch event support)
button.addEventListener('click', handleLogin);
button.addEventListener('touchend', (e) => {
e.preventDefault();
handleLogin(e);
});
```
### Example 14: Complex Bug Investigation
**Objective**: Debug memory leak in React application
#### Investigation
```bash
# Start session for thorough investigation
/workflow:session:start "Memory Leak Investigation"
# Deep code analysis
/cli:mode:code-analysis --tool gemini "Analyze React component lifecycle and event listener management for potential memory leaks"
# Create fix plan
/workflow:plan "Fix memory leaks in React components: cleanup event listeners and cancel subscriptions"
```
#### Implementation
```bash
# Execute fixes
/workflow:execute
# Generate tests to prevent regression
/workflow:test-gen WFS-memory-leak-investigation
# Execute tests
/workflow:execute
```
**Issues found and fixed**:
1. Missing cleanup in `useEffect` hooks
2. Event listeners not removed
3. Uncancelled API requests on unmount
4. Large state objects not cleared
---
## 📝 Documentation
### Example 15: API Documentation Generation
**Objective**: Generate comprehensive API documentation
```bash
# Analyze existing API
/memory:load "Generate API documentation for all endpoints"
# Create documentation
/workflow:plan "Generate OpenAPI/Swagger documentation for REST API with examples and authentication info"
# Execute
/workflow:execute
```
**Documentation includes**:
- OpenAPI 3.0 specification
- Interactive Swagger UI
- Request/response examples
- Authentication guide
- Rate limiting info
- Error codes reference
### Example 16: Project README Generation
**Objective**: Create comprehensive README for open-source project
```bash
# Update project memory first
/memory:update-full --tool gemini
# Generate README
/workflow:plan "Create comprehensive README.md with installation, usage, examples, API reference, and contributing guidelines"
/workflow:execute
```
**README sections**:
- Project overview
- Features
- Installation instructions
- Quick start guide
- Usage examples
- API reference
- Configuration
- Contributing guidelines
- License
---
## ⚙️ DevOps & Automation
### Example 17: CI/CD Pipeline Setup
**Objective**: Set up GitHub Actions CI/CD pipeline
```bash
/workflow:plan "Create GitHub Actions workflow for Node.js app with linting, testing, building, and deployment to AWS"
/workflow:execute
```
**Pipeline created**:
```yaml
# .github/workflows/ci-cd.yml
name: CI/CD
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Run tests
run: npm test
build:
needs: test
runs-on: ubuntu-latest
steps:
- name: Build
run: npm run build
deploy:
needs: build
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
steps:
- name: Deploy to AWS
run: npm run deploy
```
### Example 18: Docker Containerization
**Objective**: Dockerize full-stack application
```bash
# Plan containerization
/workflow:plan "Dockerize full-stack app with React frontend, Express backend, PostgreSQL database, and Redis cache using docker-compose"
# Execute
/workflow:execute
# Review
/workflow:review --type architecture
```
**Created files**:
```
├── docker-compose.yml
├── frontend/
│ └── Dockerfile
├── backend/
│ └── Dockerfile
├── .dockerignore
└── README.docker.md
```
---
## 🏗️ Complex Projects
### Example 19: Real-Time Chat Application
**Objective**: Build real-time chat with WebSocket, message history, and file sharing
#### Complete Workflow
```bash
# 1. Brainstorm
/workflow:brainstorm:auto-parallel "Real-time chat application with WebSocket, message history, file upload, user presence, typing indicators" --count 5
# 2. UI Design
/workflow:ui-design:explore-auto --prompt "Modern chat interface with message list, input box, user sidebar, file preview" --targets "chat-window,message-bubble,user-list" --style-variants 2
# 3. Sync designs
/workflow:ui-design:design-sync --session <session-id>
# 4. Plan implementation
/workflow:plan
# 5. Verify plan
/workflow:action-plan-verify
# 6. Execute
/workflow:execute
# 7. Generate tests
/workflow:test-gen <session-id>
# 8. Execute tests
/workflow:execute
# 9. Review
/workflow:review --type security
/workflow:review --type architecture
# 10. Complete
/workflow:session:complete
```
**Features implemented**:
- WebSocket server (Socket.io)
- Real-time messaging
- Message persistence (MongoDB)
- File upload (S3/local storage)
- User authentication
- Typing indicators
- Read receipts
- User presence (online/offline)
- Message search
- Emoji support
- Mobile responsive
### Example 20: Data Analytics Dashboard
**Objective**: Build interactive dashboard with charts and real-time data
```bash
# Brainstorm data viz approach
/workflow:brainstorm:auto-parallel "Data analytics dashboard with real-time metrics, interactive charts, filters, and export functionality"
# Plan implementation
/workflow:plan "Analytics dashboard with Chart.js/D3.js, real-time data updates via WebSocket, date range filters, and CSV export"
# Execute
/workflow:execute
```
**Dashboard features**:
- Real-time metric cards (users, revenue, conversions)
- Line charts (trends over time)
- Bar charts (comparisons)
- Pie charts (distributions)
- Data tables with sorting/filtering
- Date range picker
- Export to CSV/PDF
- Responsive grid layout
- Dark mode
- WebSocket updates every 5 seconds
---
## 💡 Tips for Effective Examples
### Best Practices
1. **Start with clear objectives**
- Define what you want to build
- List key features
- Specify technologies if needed
2. **Use appropriate workflow**
- Simple tasks: `/workflow:lite-plan`
- Complex features: `/workflow:brainstorm` → `/workflow:plan`
- Existing code: `/workflow:test-gen` or `/cli:analyze`
3. **Leverage quality gates**
- Run `/workflow:action-plan-verify` before execution
- Use `/workflow:review` after implementation
- Generate tests with `/workflow:test-gen`
4. **Maintain memory**
- Update memory after major changes
- Use `/memory:load` for quick context
- Keep CLAUDE.md files up to date
5. **Complete sessions**
- Always run `/workflow:session:complete`
- Generates lessons learned
- Archives session for reference
---
## 🔗 Related Resources
- [Getting Started Guide](GETTING_STARTED.md) - Basics
- [Architecture](ARCHITECTURE.md) - How it works
- [Command Reference](COMMAND_REFERENCE.md) - All commands
- [FAQ](FAQ.md) - Common questions
- [Contributing](CONTRIBUTING.md) - How to contribute
---
## 📬 Share Your Examples
Have a great example to share? Contribute to this document!
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
---
**Last Updated**: 2025-11-20
**Version**: 5.8.1

744
FAQ.md Normal file
View File

@@ -0,0 +1,744 @@
# ❓ Frequently Asked Questions (FAQ)
This document answers common questions about Claude Code Workflow (CCW).
---
## 📋 Table of Contents
- [General Questions](#general-questions)
- [Installation & Setup](#installation--setup)
- [Usage & Workflows](#usage--workflows)
- [Commands & Syntax](#commands--syntax)
- [Sessions & Tasks](#sessions--tasks)
- [Agents & Tools](#agents--tools)
- [Memory System](#memory-system)
- [Troubleshooting](#troubleshooting)
- [Advanced Topics](#advanced-topics)
---
## 🌟 General Questions
### What is Claude Code Workflow (CCW)?
CCW is an advanced AI-powered development automation framework for Claude Code. It transforms AI development from simple prompt chaining into a robust, context-first orchestration system with structured planning, deterministic execution, and intelligent multi-model orchestration.
### How is CCW different from using Claude Code directly?
| Claude Code (Vanilla) | Claude Code with CCW |
|----------------------|---------------------|
| Manual task management | Automated workflow orchestration |
| No context preservation | Hierarchical memory system (CLAUDE.md) |
| Single conversation context | Session-based project isolation |
| Manual planning | Automated multi-phase planning |
| One model/approach | Multi-model strategy (Gemini, Qwen, Codex) |
| No quality gates | Built-in verification and review |
### Do I need external CLI tools (Gemini, Qwen, Codex)?
**No, they're optional.** CCW can work with Claude Code alone. External CLI tools enhance CCW's capabilities by:
- Providing specialized analysis (Gemini)
- Enabling autonomous development (Codex)
- Supporting architectural planning (Qwen)
But all core workflows function without them.
### Is CCW suitable for beginners?
**Yes!** CCW provides:
- Simple commands like `/workflow:plan` and `/workflow:execute`
- Interactive command guide (`CCW-help`)
- Comprehensive documentation
- Built-in examples and tutorials
Start with the [5-minute Quick Start](GETTING_STARTED.md) to get a feel for it.
### What languages/frameworks does CCW support?
CCW is **language-agnostic**. It works with any programming language or framework that Claude Code supports:
- JavaScript/TypeScript (Node.js, React, Vue, etc.)
- Python (Django, Flask, FastAPI, etc.)
- Java/Kotlin (Spring Boot, etc.)
- Go, Rust, C++, C#, Ruby, PHP, etc.
### Is CCW free?
**Yes!** CCW is open-source under the MIT License. However, you need:
- Claude Code subscription (for the base platform)
- Optional: API keys for external CLI tools (Gemini, Qwen, Codex)
---
## 🔧 Installation & Setup
### How do I install CCW?
**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
bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.sh)
```
See [INSTALL.md](INSTALL.md) for detailed instructions.
### How do I verify CCW is installed correctly?
Open Claude Code and run:
```bash
/workflow:session:list
```
If the command is recognized, installation succeeded.
### Where are CCW files installed?
CCW installs to your home directory:
```
~/.claude/
├── agents/ # Agent definitions
├── commands/ # Slash commands
├── skills/ # Agent skills
└── workflows/ # Workflow documentation
```
### Can I customize CCW after installation?
**Yes!** All files in `~/.claude/` can be customized:
- Modify agent prompts in `agents/`
- Add custom commands in `commands/`
- Adjust workflow templates in `workflows/`
### How do I update CCW to the latest version?
Run the installation command again. It will overwrite existing files with the latest version.
**Note**: Custom modifications in `~/.claude/` will be overwritten. Back up customizations first.
### Do I need to install CLI tools?
**Optional**. To use CLI tools:
1. **Gemini CLI**: Follow [setup instructions](https://github.com/your-repo)
2. **Qwen CLI**: Follow [setup instructions](https://github.com/your-repo)
3. **Codex CLI**: Follow [setup instructions](https://github.com/your-repo)
Then initialize with:
```bash
/cli:cli-init
```
---
## 🚀 Usage & Workflows
### What's the simplest way to use CCW?
**Two-command workflow**:
```bash
/workflow:plan "Your feature description"
/workflow:execute
```
That's it! CCW handles planning, task generation, and implementation.
### What's the difference between `/workflow:plan` and `/workflow:lite-plan`?
| `/workflow:plan` | `/workflow:lite-plan` |
|-----------------|---------------------|
| Full 5-phase planning | Lightweight interactive planning |
| Creates persistent artifacts | In-memory planning |
| Best for complex projects | Best for quick tasks |
| Includes verification phase | Streamlined flow |
| Suitable for team collaboration | Suitable for solo development |
**Use `/workflow:plan`** for: Complex features, team projects, when you need detailed documentation
**Use `/workflow:lite-plan`** for: Quick fixes, small features, rapid prototyping
### When should I use brainstorming workflows?
Use `/workflow:brainstorm:auto-parallel` when:
- Feature requires multiple perspectives (architecture, security, UX, etc.)
- You need thorough requirements analysis
- Architecture decisions have significant impact
- Starting a complex project from scratch
**Example**:
```bash
/workflow:brainstorm:auto-parallel "Build real-time collaborative document editing system"
/workflow:plan
/workflow:execute
```
### How do I check the status of my workflow?
```bash
/workflow:status
```
Shows:
- Current session
- Task completion status
- Currently executing task
- Next steps
### Can I run multiple workflows simultaneously?
**Yes!** CCW supports parallel sessions:
```bash
# Session 1: Authentication
/workflow:session:start "User Authentication"
/workflow:plan "JWT-based authentication"
# Session 2: Payment
/workflow:session:start "Payment Integration"
/workflow:plan "Stripe payment integration"
# Execute each session independently
/workflow:execute --session WFS-user-authentication
/workflow:execute --session WFS-payment-integration
```
### How do I resume a paused workflow?
```bash
/workflow:session:resume
```
Automatically detects and resumes the most recent paused session.
---
## 💬 Commands & Syntax
### Where can I find all available commands?
See [COMMAND_REFERENCE.md](COMMAND_REFERENCE.md) for a complete list.
Or use the interactive guide:
```bash
CCW-help
```
### What's the difference between `/cli:*` and `/workflow:*` commands?
**`/cli:*` commands**:
- Direct access to external AI tools
- No workflow session required
- Quick one-off tasks
- Examples: `/cli:analyze`, `/cli:chat`
**`/workflow:*` commands**:
- Multi-phase orchestration
- Session-based
- Complex development workflows
- Examples: `/workflow:plan`, `/workflow:execute`
### How do I use command flags?
Most commands support flags for customization:
```bash
# Basic usage
/workflow:plan "Feature description"
# With CLI execution flag
/workflow:plan --cli-execute "Feature description"
# With tool selection
/cli:analyze --tool gemini "Code analysis"
# With multiple flags
/workflow:ui-design:explore-auto --prompt "Login page" --style-variants 3 --layout-variants 2
```
### Can I use natural language instead of commands?
**Yes!** Claude understands semantic invocation:
Instead of:
```bash
/cli:analyze --tool gemini "Authentication module"
```
You can say:
```
"Use Gemini to analyze the authentication module architecture"
```
Claude will automatically execute the appropriate command.
### What does the `-e` or `--enhance` flag do?
The `-e` flag triggers the **prompt-enhancer** skill in natural conversation:
```
User: "Analyze authentication module -e"
```
Claude will expand and enhance your request for better results.
**Note**: `--enhance` in CLI commands (e.g., `/cli:analyze --enhance`) is a different feature built into CLI tools.
---
## 📦 Sessions & Tasks
### What is a workflow session?
A workflow session is an **isolated workspace** for a specific feature or project. It contains:
- Task definitions (JSON files)
- Brainstorming artifacts
- Generated plans
- Chat logs
- Session state
**Location**: `.workflow/active/WFS-<session-name>/`
### How are sessions created?
Sessions are created automatically when you run:
```bash
/workflow:session:start "Feature name"
/workflow:plan "Feature description"
/workflow:brainstorm:auto-parallel "Topic"
```
### How do I list all sessions?
```bash
/workflow:session:list
```
Shows all sessions with their status (active, paused, completed).
### What happens when I complete a session?
```bash
/workflow:session:complete
```
CCW will:
1. Archive session to `.workflow/archives/`
2. Remove active flag
3. Generate lessons learned
4. Update session manifest
### What are tasks in CCW?
Tasks are **atomic units of work** stored as JSON files in `.task/` directory:
```
.workflow/active/WFS-feature/.task/
├── IMPL-1.json # Main task
├── IMPL-1.1.json # Subtask
└── IMPL-2.json # Another task
```
Each task contains:
- Title and description
- Requirements and acceptance criteria
- Context and focus paths
- Implementation approach
- Status (pending, in_progress, completed)
### How deep can task hierarchies go?
**Maximum 2 levels**:
- `IMPL-1` - Main task
- `IMPL-1.1`, `IMPL-1.2` - Subtasks
- No further nesting (no `IMPL-1.1.1`)
### Can I manually edit task JSON files?
**Yes**, but:
- ⚠️ JSON files are the source of truth
- ⚠️ Markdown documents are read-only views
- ✅ Edit JSON directly for fine-grained control
- ✅ Validate JSON syntax after editing
- ✅ Use `/workflow:status` to regenerate views
---
## 🤖 Agents & Tools
### What agents are available in CCW?
| Agent | Purpose |
|-------|---------|
| `@code-developer` | Code implementation |
| `@test-fix-agent` | Test generation and fixing |
| `@ui-design-agent` | UI design and prototyping |
| `@action-planning-agent` | Task planning and decomposition |
| `@cli-execution-agent` | Autonomous CLI task handling |
| `@cli-explore-agent` | Codebase exploration |
| `@context-search-agent` | Context gathering |
| `@doc-generator` | Documentation generation |
| `@memory-bridge` | Memory system updates |
See [ARCHITECTURE.md](ARCHITECTURE.md#multi-agent-system) for details.
### How do agents get selected for tasks?
**Automatic selection** based on task type defined in JSON:
```json
{
"meta": {
"agent": "code-developer"
}
}
```
CCW automatically invokes the appropriate agent during `/workflow:execute`.
### What's the difference between Gemini, Qwen, and Codex?
| Tool | Strengths | Best For |
|------|-----------|----------|
| **Gemini** | Deep analysis, pattern recognition | Code exploration, architecture analysis |
| **Qwen** | System design, planning | Architectural planning, system design |
| **Codex** | Autonomous implementation | Feature development, bug fixes |
CCW auto-selects the best tool for each task, but you can override with `--tool` flag.
### Can I create custom agents?
**Yes!** Create a new file in `.claude/agents/`:
```markdown
# My Custom Agent
## Role
Agent description
## Tools Available
- Tool 1
- Tool 2
## Prompt
Agent instructions...
```
Then reference it in task JSON:
```json
{
"meta": {
"agent": "my-custom-agent"
}
}
```
---
## 💾 Memory System
### What is the CLAUDE.md memory system?
A **hierarchical documentation system** that maintains project knowledge across 4 layers:
```
CLAUDE.md (Project root)
└── src/CLAUDE.md (Source layer)
└── auth/CLAUDE.md (Module layer)
└── jwt/CLAUDE.md (Component layer)
```
Each layer provides context at the appropriate abstraction level.
### When should I update memory?
**Update memory when**:
- After completing a feature
- After refactoring modules
- After changing architecture
- Before starting complex tasks
- Weekly maintenance
### What's the difference between memory update commands?
| Command | Scope | When to Use |
|---------|-------|-------------|
| `/memory:update-full` | Entire project | Major changes, first-time setup, monthly maintenance |
| `/memory:update-related` | Changed modules only | Daily development, after feature completion |
| `/memory:load` | Task-specific, no files | Quick context for immediate task |
### How long does memory update take?
- **`/memory:update-full`**: 5-20 minutes (depends on project size)
- **`/memory:update-related`**: 1-5 minutes (only changed modules)
- **`/memory:load`**: <1 minute (no file updates)
### Do I need to update memory manually?
**Recommended but not required**. Benefits of regular updates:
- ✅ Higher quality AI outputs
- ✅ Accurate pattern recognition
- ✅ Better context understanding
- ✅ Reduced hallucinations
Without updates:
- ⚠️ AI may reference outdated code
- ⚠️ Incorrect architectural assumptions
- ⚠️ Lower output quality
### Can I exclude files from memory?
**Yes!** Use ignore files:
- `.geminiignore` - For Gemini CLI
- `.qwenignore` - For Qwen CLI
- `.gitignore` - Automatically respected
Example `.geminiignore`:
```
node_modules/
dist/
*.log
*.test.js
```
---
## 🔧 Troubleshooting
### "No active session found" error
**Cause**: No workflow session is currently active.
**Solution**:
```bash
# Option 1: Start new session
/workflow:session:start "Feature name"
# Option 2: Resume existing session
/workflow:session:resume
```
### Command execution fails or hangs
**Troubleshooting steps**:
1. **Check status**:
```bash
/workflow:status
```
2. **Review logs**:
```bash
# Session logs location
.workflow/active/WFS-<session>/.chat/
```
3. **Simplify task**:
Break complex requests into smaller tasks
4. **Check CLI tools**:
Ensure external tools (if used) are properly configured
### Task execution produces errors
**Common causes**:
1. **Outdated memory**: Run `/memory:update-related`
2. **Insufficient context**: Add more details to task requirements
3. **Tool misconfiguration**: Check CLI tool setup with `/cli:cli-init`
### Memory update fails
**Solutions**:
1. **Check file permissions**: Ensure write access to project
2. **Try different tool**:
```bash
/memory:update-full --tool qwen
```
3. **Update incrementally**:
```bash
/memory:update-related
```
### Workflow gets stuck in a phase
**Steps**:
1. **Check current phase**:
```bash
/workflow:status
```
2. **Review session JSON**:
```bash
cat .workflow/active/WFS-<session>/workflow-session.json
```
3. **Manually advance** (if needed):
Edit session JSON to update phase
4. **Restart session**:
```bash
/workflow:session:complete
/workflow:session:start "New attempt"
```
### CLI tools not working
**Checklist**:
1. ✅ Tools installed correctly?
2. ✅ API keys configured?
3. ✅ `.gemini/` or `.qwen/` directories exist?
4. ✅ Configuration files valid?
**Re-initialize**:
```bash
/cli:cli-init --tool gemini
```
### Performance is slow
**Optimization tips**:
1. **Use incremental updates**:
```bash
/memory:update-related # Instead of update-full
```
2. **Exclude unnecessary files**:
Add to `.geminiignore` or `.qwenignore`
3. **Break down large tasks**:
Smaller tasks = faster execution
4. **Use lite workflows**:
```bash
/workflow:lite-plan # Instead of full workflow:plan
```
---
## 🚀 Advanced Topics
### How does CCW handle dependencies between tasks?
Tasks can reference dependencies in their JSON:
```json
{
"id": "IMPL-2",
"dependencies": ["IMPL-1"],
"context": {
"inherited_from": "IMPL-1"
}
}
```
CCW ensures dependencies are completed before dependent tasks execute.
### Can I integrate CCW with CI/CD pipelines?
**Yes!** CCW can be used in automated workflows:
1. **Generate tests**:
```bash
/workflow:test-gen WFS-feature
/workflow:execute
```
2. **Run verification**:
```bash
/workflow:action-plan-verify
```
3. **Automated reviews**:
```bash
/workflow:review --type security
```
### How do I create custom workflows?
Combine existing commands:
```bash
# Custom TDD workflow
/workflow:tdd-plan "Feature"
/workflow:execute
/workflow:tdd-verify
/workflow:review --type quality
```
Or create custom command in `.claude/commands/`.
### What's the JSON-first architecture?
**Principle**: JSON files are the **single source of truth** for all task state.
- ✅ JSON files contain actual state
- ❌ Markdown documents are **read-only** generated views
- ✅ Edit JSON to change state
- ❌ Never edit markdown documents
**Benefits**:
- No synchronization complexity
- Programmatic access
- Clear data model
- Deterministic state
### How does context flow between agents?
Agents share context through:
1. **Session JSON**: Shared session state
2. **Task JSON**: Task-specific context
3. **CLAUDE.md**: Project knowledge base
4. **Flow Control**: Pre-analysis and implementation approach
### Can I use CCW for non-code projects?
**Yes!** CCW can manage any structured project:
- Documentation writing
- Content creation
- Data analysis
- Research projects
- Process automation
### How do I migrate from one CCW version to another?
1. **Backup customizations**: Save `.claude/` modifications
2. **Run installation**: Install new version
3. **Restore customizations**: Reapply your changes
4. **Check changelog**: Review breaking changes in [CHANGELOG.md](CHANGELOG.md)
5. **Test workflows**: Verify existing workflows work
### Where can I get more help?
- 📖 **Documentation**: [README.md](README.md), [GETTING_STARTED.md](GETTING_STARTED.md)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/catlog22/Claude-Code-Workflow/discussions)
- 🐛 **Issues**: [GitHub Issues](https://github.com/catlog22/Claude-Code-Workflow/issues)
- 🤖 **Command Guide**: `CCW-help` within Claude Code
- 📚 **Examples**: [EXAMPLES.md](EXAMPLES.md)
---
## 📚 Additional Resources
- [Getting Started Guide](GETTING_STARTED.md) - 5-minute tutorial
- [Architecture Overview](ARCHITECTURE.md) - System design
- [Command Reference](COMMAND_REFERENCE.md) - All commands
- [Contributing Guide](CONTRIBUTING.md) - How to contribute
- [Examples](EXAMPLES.md) - Real-world use cases
- [Changelog](CHANGELOG.md) - Version history
---
**Last Updated**: 2025-11-20
**Version**: 5.8.1
**Didn't find your question?** Ask in [GitHub Discussions](https://github.com/catlog22/Claude-Code-Workflow/discussions)!

27
README.md
View File

@@ -159,11 +159,38 @@ Traditional multi-phase workflow for complex projects:
--- ---
## 📚 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))
- [**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 ## 🤝 Contributing & Support
- **Repository**: [GitHub - Claude-Code-Workflow](https://github.com/catlog22/Claude-Code-Workflow) - **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). - **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). - **Discussions**: Join the [Community Forum](https://github.com/catlog22/Claude-Code-Workflow/discussions).
- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
## 📄 License ## 📄 License

27
README_CN.md
View File

@@ -159,11 +159,38 @@ CCW 包含内置的**命令指南技能**，帮助您有效地发现和使用命
--- ---
## 📚 文档
CCW 提供全面的文档，帮助您快速上手并掌握高级功能：
### 📖 **快速入门**
- [**快速上手指南**](GETTING_STARTED_CN.md) - 5 分钟快速入门教程
- [**安装指南**](INSTALL_CN.md) - 详细安装说明 ([English](INSTALL.md))
- [**示例**](EXAMPLES.md) - 真实世界用例和实践示例 (English)
- [**常见问题**](FAQ.md) - 常见问题和故障排除 (English)
### 🏗️ **架构与设计**
- [**架构概览**](ARCHITECTURE.md) - 系统设计和核心组件 (English)
- [**项目介绍**](PROJECT_INTRODUCTION.md) - 详细项目概览
- [**工作流图示**](WORKFLOW_DIAGRAMS.md) - 可视化工作流表示 (English)
### 📋 **命令参考**
- [**命令参考**](COMMAND_REFERENCE.md) - 所有命令的完整列表 (English)
- [**命令规范**](COMMAND_SPEC.md) - 详细技术规范 (English)
- [**命令流程标准**](COMMAND_FLOW_STANDARD.md) - 命令设计模式 (English)
### 🤝 **贡献**
- [**贡献指南**](CONTRIBUTING.md) - 如何为 CCW 做贡献 (English)
- [**更新日志**](CHANGELOG.md) - 版本历史和发布说明
---
## 🤝 贡献与支持 ## 🤝 贡献与支持
- **仓库**: [GitHub - Claude-Code-Workflow](https://github.com/catlog22/Claude-Code-Workflow) - **仓库**: [GitHub - Claude-Code-Workflow](https://github.com/catlog22/Claude-Code-Workflow)
- **问题**: 在 [GitHub Issues](https://github.com/catlog22/Claude-Code-Workflow/issues) 上报告错误或请求功能。 - **问题**: 在 [GitHub Issues](https://github.com/catlog22/Claude-Code-Workflow/issues) 上报告错误或请求功能。
- **讨论**: 加入 [社区论坛](https://github.com/catlog22/Claude-Code-Workflow/discussions)。 - **讨论**: 加入 [社区论坛](https://github.com/catlog22/Claude-Code-Workflow/discussions)。
- **贡献**: 查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解贡献指南。
## 📄 许可证 ## 📄 许可证