Claude-Code-Workflow/GETTING_STARTED.md

# 🚀 Claude Code Workflow (CCW) - Getting Started Guide

Welcome to Claude Code Workflow (CCW) v7.0! This guide will help you get up and running in 5 minutes and experience AI-driven automated software development with team orchestration, queue scheduling, and intelligent CLI orchestration.

**Project Repository**: [catlog22/Claude-Code-Workflow](https://github.com/catlog22/Claude-Code-Workflow)

> **🎉 What's New in v7.0**:
> - 🤖 **Team Architecture v2**: team-coordinate-v2 / team-executor-v2 with unified team-worker agent architecture
> - 📋 **Queue Scheduler**: Background queue execution service with dependency resolution and session pooling
> - 🖥️ **New Dashboard Views**: Analysis Viewer, Terminal Dashboard with multi-terminal grid, Orchestrator Template Editor
> - 🔄 **Workflow Session Commands**: start/resume/complete/sync for complete session lifecycle management
> - 🌐 **A2UI v2**: Multi-select questions, RadioGroup components, WebSocket real-time communication

---

## ⏱️ 5-Minute Quick Start

Let's build a "Hello World" web application from scratch with a simple example.

### Step 1: Install CCW

First, make sure you have installed CCW according to the [Installation Guide](INSTALL.md).

### Step 2: Create an Execution Plan (Automatically Starts a Session)

Now, 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"
```

> **💡 Note**: `/workflow:plan` automatically creates and starts a workflow session. No need to manually run `/workflow:session:start`. The session will be auto-named based on your task description, e.g., `WFS-create-a-simple-express-api`.

This command kicks off a fully automated planning process, which includes:
1.  **Context Gathering**: Analyzing your project environment.
2.  **Agent Analysis**: AI agents think about the best implementation path.
3.  **Task Generation**: Creating specific task files (in `.json` format).

### Step 3: Execute the Plan

Once the plan is created, you can command the AI agents to start working.

```bash
/workflow:execute
```

You will see CCW's agents (like `@code-developer`) begin to execute tasks one by one. It will automatically create files, write code, and install dependencies.

### Step 4: Check the Status

Want to know the progress? You can check the status of the current workflow at any time.

```bash
/workflow:status
```

This will show the completion status of tasks, the currently executing task, and the next steps.

### Step 5: Complete the Session

When all tasks are done, mark the session as complete:

```bash
/workflow:session:complete
```

This archives the session, extracts lessons learned, and optionally syncs project state.

---

## 🧠 Core Concepts Explained

Understanding these concepts will help you use CCW more effectively:

-   **Workflow Session**
    > Like an independent sandbox or project space, used to isolate the context, files, and history of different tasks. All related files are stored in the `.workflow/WFS-<session-name>/` directory.

-   **Task**
    > An atomic unit of work, such as "create API route" or "write test case." Each task is a `.json` file that defines the goal, context, and execution steps in detail.

-   **Agent**
    > An AI assistant specialized in a specific domain. For example:
    > -   `@code-developer`: Responsible for writing and implementing code.
    > -   `@test-fix-agent`: Responsible for running tests and automatically fixing failures.
    > -   `@ui-design-agent`: Responsible for UI design and prototype creation.
    > -   `@cli-execution-agent`: Responsible for autonomous CLI task handling (v4.5.0+).
    > -   **team-worker**: Unified worker agent for team orchestration (v7.0+).

-   **Workflow**
    > A series of predefined, collaborative commands used to orchestrate different agents and tools to achieve a complex development goal (e.g., `plan`, `execute`, `test-gen`).

---

## 🆕 v7.0 New Features Overview

### Workflow Session Management (v7.0)

CCW v7.0 introduces comprehensive session lifecycle commands:

```bash
# Start a new session with automatic naming
/workflow:session:start --auto "Implement user authentication"

# Resume a paused session
/workflow:session:resume

# Complete and archive the current session
/workflow:session:complete

# Sync session work to project specs
/workflow:session:sync "What was accomplished"
```

### Team Architecture v2 (v7.0)

For complex projects requiring multiple specialized roles, use Team Architecture v2:

```bash
# Coordinate a team with auto-generated role specs
/team-coordinate "Build a real-time collaboration system"

# Execute a pre-planned team session
/team-executor <session-folder>

# Team members include: analyst, planner, executor, tester, reviewer, architect
```

**Key Features**:
- **Dynamic role-spec generation**: Creates role-specific instructions at runtime
- **team-worker agent**: Unified worker handling Phase 1-5 orchestration
- **Inner loop processing**: Handles multiple same-prefix tasks in a single agent
- **Discuss & Explore subagents**: Multi-perspective critique and code exploration

### Queue Scheduler (v7.0)

For background task execution with dependency management:

```bash
# Access via Dashboard → Terminal Dashboard → Queue Panel
# Or use API endpoints for programmatic control
```

**Features**:
- Dependency resolution with topological sorting
- Session pooling with 3-tier allocation strategy
- Real-time WebSocket state updates
- Concurrent execution with configurable limits

### New Dashboard Views (v7.0)

**Analysis Viewer Page** (`/analysis`):
- Grid layout for concurrent analysis sessions
- Filtering, pagination, and fullscreen mode
- Real-time progress tracking

**Terminal Dashboard** (`/terminal-dashboard`):
- Multi-terminal grid layout (tmux-style split panes)
- Execution monitor panel with agent orchestration
- Session group tree with drag-and-drop management
- Queue scheduler controls

**Orchestrator Template Editor** (`/orchestrator`):
- Visual template editing for orchestration plans
- Slash command execution with terminal integration
- Observability panel for debugging

---

## 🛠️ Common Scenarios

### Scenario 1: Quick Feature Development

For simple, well-defined features, use the direct "plan → execute" pattern:

```bash
# Create plan (auto-creates session)
/workflow:plan "Implement JWT-based user login and registration"

# Execute
/workflow:execute
```

> **💡 Note**: `/workflow:plan` automatically creates a session. You can also manually start a session first with `/workflow:session:start "Feature Name"`.

### Scenario 2: UI Design Exploration

For UI-focused projects, start with design exploration before implementation: **ui-design → update → plan → execute**

```bash
# Step 1: Generate UI design variations (auto-creates session)
/workflow:ui-design:explore-auto --prompt "A modern, clean admin dashboard login page"

# Step 2: Review designs in compare.html, then sync design system to brainstorming artifacts
/workflow:ui-design:design-sync --session <session-id> --selected-prototypes "login-v1,login-v2"

# Step 3: Generate implementation plan with design references
/workflow:plan

# Step 4: Execute the implementation
/workflow:execute
```

> **💡 Tip**: The `update` command integrates selected design prototypes into brainstorming artifacts, ensuring implementation follows the approved designs.

### Scenario 3: Complex Feature with Multi-Agent Brainstorming

**Use brainstorming when you know WHAT to build, but don't know HOW to build it.** The complete workflow: **brainstorm → plan → execute**

```bash
# Step 1: Multi-agent brainstorming (auto-creates session)
/workflow:brainstorm:auto-parallel "Design a real-time collaborative document editing system with conflict resolution"

# Optional: Specify number of expert roles (default: 3, max: 9)
/workflow:brainstorm:auto-parallel "Build scalable microservices platform" --count 5

# Step 2: Generate implementation plan from brainstorming results
/workflow:plan

# Step 3: Execute the plan
/workflow:execute
```

**When to Use Brainstorming**:
- **You know WHAT to build, but NOT HOW** - Need to explore solution approaches
- **Multiple solution paths exist** - Need expert analysis to choose the best approach
- **Unclear technical requirements** - Need to clarify architecture, data models, APIs
- **Significant architectural decisions** - Need multi-perspective analysis before committing

**When to Skip Brainstorming** (use `/workflow:plan` directly):
- You already know the implementation approach
- Clear technical requirements from the start
- Simple, straightforward features
- Similar to existing implementations in your codebase

### Scenario 4: Quality Assurance - Action Plan Verification

After planning, validate your implementation plan for consistency and completeness:

```bash
# After /workflow:plan completes, verify task quality
/workflow:plan-verify

# The command will:
# 1. Check requirements coverage (all requirements have tasks)
# 2. Validate task dependencies (no circular or broken dependencies)
# 3. Ensure synthesis alignment (tasks match architectural decisions)
# 4. Assess task specification quality
# 5. Generate detailed verification report with remediation todos
```

**The verification report includes**:
- Requirements coverage analysis
- Dependency graph validation
- Synthesis alignment checks
- Task specification quality assessment
- Prioritized remediation recommendations

**When to Use**:
- After `/workflow:plan` generates IMPL_PLAN.md and task files
- Before starting `/workflow:execute`
- When working on complex projects with many dependencies
- When you want to ensure high-quality task specifications



### Scenario 5: Bug Fixing

Quick bug analysis and fix workflow:

```bash
# Lightweight bug fix workflow with intelligent diagnosis
/workflow:lite-fix "Incorrect success message with wrong password"

# Claude will analyze severity, diagnose root cause, and implement the fix
```

### Scenario 6: Team-Based Development (v7.0)

For complex projects requiring multiple specialized perspectives:

```bash
# Coordinate a team with automatic role generation
/team-coordinate "Design and implement a microservices architecture"

# The workflow:
# 1. Analyze requirements and detect needed capabilities
# 2. Generate dynamic role-specs (analyst, planner, executor, tester, reviewer)
# 3. Create tasks with proper dependencies
# 4. Dispatch to team-worker agents
# 5. Monitor progress via callbacks
# 6. Complete with comprehensive report

# Resume a paused team session
/team-executor .workflow/.team/TLS-xxx-2026-02-27 resume
```

---

## 🔧 Lightweight Commands

Beyond the full workflow mode, CCW provides lightweight commands suitable for quick analysis and routine tasks.

### Workflow Commands for Quick Tasks

Use workflow commands for integrated planning and bug fixing:

```bash
# Lightweight planning workflow
/workflow:lite-plan "Design a scalable microservices architecture"

# Bug fix workflow with intelligent diagnosis
/workflow:lite-fix "Analyze potential causes of memory leak"

# Initialize CLI tool configurations
/cli:cli-init
```

### Semantic Tool Invocation (Replaces Direct CLI Commands)

> **Important**: Direct CLI commands (`/cli:analyze`, `/cli:chat`, `/cli:execute`, etc.) have been replaced by **semantic invocation**. Simply describe your needs in natural language, and Claude will automatically select and execute the appropriate CLI tools (Gemini/Qwen/Codex) with optimized templates.

Users can tell Claude to use specific tools through natural language, and Claude will understand the intent and automatically execute the appropriate commands.

#### Semantic Invocation Examples

Describe needs directly in conversation using natural language:

**Example 1: Code Analysis**
```
User: "Use gemini to analyze the modular architecture of this project"
→ Claude will automatically execute gemini for analysis
```

**Example 2: Document Generation**
```
User: "Use gemini to generate API documentation with all endpoint descriptions"
→ Claude will understand the need and automatically invoke gemini's write mode
```

**Example 3: Code Implementation**
```
User: "Use codex to implement user login functionality"
→ Claude will invoke the codex tool for autonomous development
```

#### Advantages of Semantic Invocation

- **Natural Interaction**: No need to memorize complex command syntax
- **Intelligent Understanding**: Claude selects appropriate tools and parameters based on context
- **Automatic Optimization**: Claude automatically adds necessary context and configuration

### Memory Management: CLAUDE.md Updates

CCW uses a hierarchical CLAUDE.md documentation system to maintain project context. Regular updates to these documents are critical for ensuring high-quality AI outputs.

#### Full Project Index Rebuild

Suitable for large-scale refactoring, architectural changes, or first-time CCW usage:

```bash
# Rebuild entire project documentation index
/memory:update-full

# Use specific tool for indexing
/memory:update-full --tool gemini   # Comprehensive analysis (recommended)
/memory:update-full --tool qwen     # Architecture focus
/memory:update-full --tool codex    # Implementation details
```

**When to Execute**:
- During project initialization
- After major architectural changes
- Weekly routine maintenance
- When AI output drift is detected

#### Quick Context Loading for Specific Tasks

When you need immediate, task-specific context without updating documentation:

```bash
# Load context for a specific task into memory
/memory:load "在当前前端基础上开发用户认证功能"

# Use alternative CLI tool for analysis
/memory:load --tool qwen "重构支付模块API"
```

**How It Works**:
- Delegates to an AI agent for autonomous project analysis
- Discovers relevant files and extracts task-specific keywords
- Uses CLI tools (Gemini/Qwen) for deep analysis to save tokens
- Returns a structured "Core Content Pack" loaded into memory
- Provides context for subsequent agent operations

**When to Use**:
- Before starting a new feature or task
- When you need quick context without full documentation rebuild
- For task-specific architectural or pattern discovery
- As preparation for agent-based development workflows

#### Incremental Related Module Updates

Suitable for daily development, updating only modules affected by changes:

```bash
# Update recently modified related documentation
/memory:update-related

# Specify tool for update
/memory:update-related --tool gemini
```

**When to Execute**:
- After feature development completion
- After module refactoring
- After API interface updates
- After data model modifications

#### Memory Quality Impact

| Update Frequency | Result |
|-----------------|--------|
| ❌ Never update | Outdated API references, incorrect architectural assumptions, low-quality output |
| ⚠️ Occasional updates | Partial context accuracy, potential inconsistencies |
| ✅ Timely updates | High-quality output, precise context, correct pattern references |

### CLI Tool Initialization

When using external CLI tools for the first time, initialization commands provide quick configuration:

```bash
# Auto-configure all tools
/cli:cli-init

# Configure specific tools only
/cli:cli-init --tool gemini
/cli:cli-init --tool qwen
```

This command will:
- Analyze project structure
- Generate tool configuration files
- Set up `.geminiignore` / `.qwenignore`
- Create context file references

---

## Advanced Usage: Agent Skills

Agent Skills are modular, reusable capabilities that extend the AI's functionality. They are stored in the `.claude/skills/` directory and are invoked through specific trigger mechanisms.

### How Skills Work

-   **Model-Invoked**: Unlike slash commands, you don't call Skills directly. The AI decides when to use a Skill based on its understanding of your goal.
-   **Contextual**: Skills provide specific instructions, scripts, and templates to the AI for specialized tasks.
-   **Trigger Mechanisms**:
    -   **Conversational Trigger**: Use `-e` or `--enhance` flag in **natural conversation** to trigger the `prompt-enhancer` skill
    -   **CLI Command Enhancement**: Use `--enhance` flag in **CLI commands** for prompt refinement (this is a CLI feature, not a skill trigger)

### Examples

**Conversational Trigger** (activates prompt-enhancer skill):
```
User: "Analyze authentication module -e"
→ AI uses prompt-enhancer skill to expand the request
```

**Important Note**: The `-e` flag works in natural conversation to trigger the prompt-enhancer skill.

---

## Advanced Usage: UI Design Workflow

CCW includes a powerful, multi-phase workflow for UI design and prototyping, capable of generating complete design systems and interactive prototypes from simple descriptions or reference images.

### Key Commands

-   `/workflow:ui-design:explore-auto`: An exploratory workflow that generates multiple, distinct design variations based on a prompt.
-   `/workflow:ui-design:imitate-auto`: A design workflow that creates prototypes from local reference files (images, code) or text prompts.

### Example: Generating a UI from a Prompt

You can generate multiple design options for a web page with a single command:

```bash
# This command will generate 3 different style and layout variations for a login page.
/workflow:ui-design:explore-auto --prompt "A modern, clean login page for a SaaS application" --targets "login" --style-variants 3 --layout-variants 3
```

After the workflow completes, it provides a `compare.html` file, allowing you to visually review and select the best design combination.

---

## ❓ Troubleshooting

-   **Problem: Prompt shows "No active session found"**
    > **Reason**: You haven't started a workflow session, or the current session is complete.
    > **Solution**: Use `/workflow:session:start "Your task description"` to start a new session.

-   **Problem: Command execution fails or gets stuck**
    > **Reason**: It could be a network issue, AI model limitation, or the task is too complex.
    > **Solution**:
    > 1.  First, try using `/workflow:status` to check the current state.
    > 2.  Check the log files in the `.workflow/WFS-<session-name>/.chat/` directory for detailed error messages.
    > 3.  If the task is too complex, try breaking it down into smaller tasks and then use `/workflow:plan` to create a new plan.

---

## 📚 Next Steps for Advanced Learning

Once you've mastered the basics, you can explore CCW's more powerful features:

1.  **Test-Driven Development (TDD)**: Use `/workflow:tdd-plan` to create a complete TDD workflow. The AI will first write failing tests, then write code to make them pass, and finally refactor.

2.  **Multi-Agent Brainstorming**: Use `/workflow:brainstorm:auto-parallel` to have multiple AI agents with different roles (like System Architect, Product Manager, Security Expert) analyze a topic simultaneously and generate a comprehensive report.

3.  **Custom Agents and Commands**: You can modify the files in the `.claude/agents/` and `.claude/commands/` directories to customize agent behavior and workflows to fit your team's specific needs.


Hope this guide helps you get started smoothly with CCW!