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

Refactor and optimize various components and files

Browse Source 
- Removed deprecated `ccw-contentPattern-optimization-summary.md` and related files.
- Updated `A2UIPopupCard.tsx` to clarify comments on interaction handling.
- Enhanced `QueueListColumn.tsx` and `QueuePanel.tsx` to handle potential undefined values for `config`.
- Added `useEffect` in `QueuePanel.tsx` to load scheduler state on mount.
- Improved `SchedulerPanel.tsx` to handle potential undefined values for `sessionPool`.
- Introduced auto-initialization logic in `queueSchedulerStore.ts` to prevent multiple initialization calls.
- Updated `A2UIWebSocketHandler.ts` to refine selection handling logic.
- Enhanced `hooks-routes.ts` to support multi-question surfaces.
- Added submit and cancel buttons in `ask-question.ts` for better user interaction.
- Deleted `codex_prompt.md` and `contentPattern-library-options.md` as part of cleanup.
- Removed `status-reference.md` to streamline documentation.
This commit is contained in:
catlog22
2026-02-27 22:35:05 +08:00
parent 9be35ed5fb
commit be061dd2a2
34 changed files with 1543 additions and 8895 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
.claude/skills/team-coordinate-v2/roles/coordinator/commands/analyze-task.md
View File

@@ -154,6 +154,27 @@ Write `<session-folder>/task-analysis.json`:
}
```
## Complexity Interpretation
**CRITICAL**: Complexity score is for **role design optimization**, NOT for skipping team workflow.
| Complexity | Team Structure | Coordinator Action |
|------------|----------------|-------------------|
| Low (1-2 roles) | Minimal team | Generate 1-2 role-specs, create team, spawn workers |
| Medium (2-3 roles) | Standard team | Generate role-specs, create team, spawn workers |
| High (3-5 roles) | Full team | Generate role-specs, create team, spawn workers |
**All complexity levels use team-worker architecture**:
- Single-role tasks still spawn team-worker agent
- Coordinator NEVER executes task work directly
- Team infrastructure provides session management, message bus, fast-advance
**Purpose of complexity score**:
- ✅ Determine optimal role count (merge vs separate)
- ✅ Guide dependency graph design
- ✅ Inform user about task scope
- ❌ NOT for deciding whether to use team workflow
## Error Handling
| Scenario | Resolution |
@@ -161,4 +182,4 @@ Write `<session-folder>/task-analysis.json`:
| No capabilities detected | Default to single `general` role with TASK prefix |
| Circular dependency in graph | Break cycle at lowest-tier edge, warn |
| Task description too vague | Return minimal analysis, coordinator will AskUserQuestion |
| All capabilities merge into one | Valid -- single-role execution, no team overhead |
| All capabilities merge into one | Valid -- single-role execution via team-worker |

52
.claude/skills/team-coordinate-v2/roles/coordinator/role.md
View File

@@ -33,6 +33,27 @@ Orchestrate the team-coordinate workflow: task analysis, dynamic role-spec gener
---
## Command Execution Protocol
When coordinator needs to execute a command (analyze-task, dispatch, monitor):
1. **Read the command file**: `roles/coordinator/commands/<command-name>.md`
2. **Follow the workflow** defined in the command file (Phase 2-4 structure)
3. **Commands are inline execution guides** - NOT separate agents or subprocesses
4. **Execute synchronously** - complete the command workflow before proceeding
Example:
```
Phase 1 needs task analysis
-> Read roles/coordinator/commands/analyze-task.md
-> Execute Phase 2 (Context Loading)
-> Execute Phase 3 (Task Analysis)
-> Execute Phase 4 (Output)
-> Continue to Phase 2
```
---
## Entry Router
When coordinator is invoked, first detect the invocation type:
@@ -44,10 +65,24 @@ When coordinator is invoked, first detect the invocation type:
| Manual resume | Arguments contain "resume" or "continue" | -> handleResume |
| Capability gap | Message contains "capability_gap" | -> handleAdapt |
| Pipeline complete | All tasks completed, no pending/in_progress | -> handleComplete |
| New session | None of above | -> Phase 0 |
| Interrupted session | Active/paused session exists in `.workflow/.team/TC-*` | -> Phase 0 (Resume Check) |
| New session | None of above | -> Phase 1 (Task Analysis) |
For callback/check/resume/adapt/complete: load `commands/monitor.md` and execute the appropriate handler, then STOP.
### Router Implementation
1. **Load session context** (if exists):
- Scan `.workflow/.team/TC-*/team-session.json` for active/paused sessions
- If found, extract `session.roles[].name` for callback detection
2. **Parse $ARGUMENTS** for detection keywords
3. **Route to handler**:
- For monitor handlers: Read `commands/monitor.md`, execute matched handler section, STOP
- For Phase 0: Execute Session Resume Check below
- For Phase 1: Execute Task Analysis below
---
## Phase 0: Session Resume Check
@@ -103,6 +138,21 @@ For callback/check/resume/adapt/complete: load `commands/monitor.md` and execute
**Success**: Task analyzed, capabilities detected, dependency graph built, roles designed with role-spec metadata.
**CRITICAL - Team Workflow Enforcement**:
Regardless of complexity score or role count, coordinator MUST:
- ✅ **Always proceed to Phase 2** (generate role-specs)
- ✅ **Always create team** and spawn workers via team-worker agent
- ❌ **NEVER execute task work directly**, even for single-role low-complexity tasks
- ❌ **NEVER skip team workflow** based on complexity assessment
**Single-role execution is still team-based** - just with one worker. The team architecture provides:
- Consistent message bus communication
- Session state management
- Artifact tracking
- Fast-advance capability
- Resume/recovery mechanisms
---
## Phase 2: Generate Role-Specs + Initialize Session

28
.claude/skills/team-coordinate/roles/coordinator/commands/analyze-task.md
View File

@@ -98,7 +98,6 @@ Apply merging rules to reduce role count:
|------|-----------|--------|
| Absorb trivial | Capability has exactly 1 task AND no explore needed | Merge into nearest related role |
| Merge overlap | Two capabilities share >50% keywords from task description | Combine into single role |
| Coordinator inline | Planner capability with 1 task, no explore | Coordinator handles inline, no separate role |
| Cap at 5 | More than 5 roles after initial assignment | Merge lowest-priority pairs (priority: researcher > designer > developer > writer > analyst > planner > tester) |
**Merge priority** (when two must merge, keep the higher-priority one as the role name):
@@ -108,9 +107,11 @@ Apply merging rules to reduce role count:
3. writer (document generation has specific patterns)
4. designer (design has specific outputs)
5. analyst (analysis can be absorbed by reviewer pattern)
6. planner (can be absorbed by coordinator)
6. planner (planning can be merged with researcher or designer)
7. tester (can be absorbed by developer or analyst)
**IMPORTANT**: Even after merging, coordinator MUST spawn workers for all roles. Single-role tasks still use team architecture.
## Phase 4: Output
Write `<session-folder>/task-analysis.json`:
@@ -165,6 +166,27 @@ Write `<session-folder>/task-analysis.json`:
}
```
## Complexity Interpretation
**CRITICAL**: Complexity score is for **role design optimization**, NOT for skipping team workflow.
| Complexity | Team Structure | Coordinator Action |
|------------|----------------|-------------------|
| Low (1-2 roles) | Minimal team | Generate 1-2 roles, create team, spawn workers |
| Medium (2-3 roles) | Standard team | Generate roles, create team, spawn workers |
| High (3-5 roles) | Full team | Generate roles, create team, spawn workers |
**All complexity levels use team architecture**:
- Single-role tasks still spawn worker via Skill
- Coordinator NEVER executes task work directly
- Team infrastructure provides session management, message bus, fast-advance
**Purpose of complexity score**:
- ✅ Determine optimal role count (merge vs separate)
- ✅ Guide dependency graph design
- ✅ Inform user about task scope
- ❌ NOT for deciding whether to use team workflow
## Error Handling
| Scenario | Resolution |
@@ -172,4 +194,4 @@ Write `<session-folder>/task-analysis.json`:
| No capabilities detected | Default to single `general` role with TASK prefix |
| Circular dependency in graph | Break cycle at lowest-tier edge, warn |
| Task description too vague | Return minimal analysis, coordinator will AskUserQuestion |
| All capabilities merge into one | Valid -- single-role execution, no team overhead |
| All capabilities merge into one | Valid -- single-role execution via team worker |

52
.claude/skills/team-coordinate/roles/coordinator/role.md
View File

@@ -32,6 +32,27 @@ Orchestrate the team-coordinate workflow: task analysis, dynamic role generation
---
## Command Execution Protocol
When coordinator needs to execute a command (analyze-task, dispatch, monitor):
1. **Read the command file**: `roles/coordinator/commands/<command-name>.md`
2. **Follow the workflow** defined in the command file (Phase 2-4 structure)
3. **Commands are inline execution guides** - NOT separate agents or subprocesses
4. **Execute synchronously** - complete the command workflow before proceeding
Example:
```
Phase 1 needs task analysis
-> Read roles/coordinator/commands/analyze-task.md
-> Execute Phase 2 (Context Loading)
-> Execute Phase 3 (Task Analysis)
-> Execute Phase 4 (Output)
-> Continue to Phase 2
```
---
## Entry Router
When coordinator is invoked, first detect the invocation type:
@@ -42,10 +63,24 @@ When coordinator is invoked, first detect the invocation type:
| Status check | Arguments contain "check" or "status" | -> handleCheck |
| Manual resume | Arguments contain "resume" or "continue" | -> handleResume |
| Capability gap | Message contains "capability_gap" | -> handleAdapt |
| New session | None of above | -> Phase 0 |
| Interrupted session | Active/paused session exists in `.workflow/.team/TC-*` | -> Phase 0 (Resume Check) |
| New session | None of above | -> Phase 1 (Task Analysis) |
For callback/check/resume/adapt: load `commands/monitor.md` and execute the appropriate handler, then STOP.
### Router Implementation
1. **Load session context** (if exists):
- Scan `.workflow/.team/TC-*/team-session.json` for active/paused sessions
- If found, extract `session.roles[].name` for callback detection
2. **Parse $ARGUMENTS** for detection keywords
3. **Route to handler**:
- For monitor handlers: Read `commands/monitor.md`, execute matched handler section, STOP
- For Phase 0: Execute Session Resume Check below
- For Phase 1: Execute Task Analysis below
---
## Phase 0: Session Resume Check
@@ -96,6 +131,21 @@ For callback/check/resume/adapt: load `commands/monitor.md` and execute the appr
**Success**: Task analyzed, capabilities detected, dependency graph built, roles designed.
**CRITICAL - Team Workflow Enforcement**:
Regardless of complexity score or role count, coordinator MUST:
- ✅ **Always proceed to Phase 2** (generate roles)
- ✅ **Always create team** and spawn workers
- ❌ **NEVER execute task work directly**, even for single-role low-complexity tasks
- ❌ **NEVER skip team workflow** based on complexity assessment
**Single-role execution is still team-based** - just with one worker. The team architecture provides:
- Consistent message bus communication
- Session state management
- Artifact tracking
- Fast-advance capability
- Resume/recovery mechanisms
---
## Phase 2: Generate Roles + Initialize Session

37
.claude/skills/team-lifecycle-v5/roles/coordinator/role.md
View File

@@ -24,6 +24,27 @@ Orchestrate the team-lifecycle-v5 workflow: team creation, task dispatching, pro
---
## Command Execution Protocol
When coordinator needs to execute a command (dispatch, monitor):
1. **Read the command file**: `roles/coordinator/commands/<command-name>.md`
2. **Follow the workflow** defined in the command file (Phase 2-4 structure)
3. **Commands are inline execution guides** - NOT separate agents or subprocesses
4. **Execute synchronously** - complete the command workflow before proceeding
Example:
```
Phase 3 needs task dispatch
-> Read roles/coordinator/commands/dispatch.md
-> Execute Phase 2 (Context Loading)
-> Execute Phase 3 (Task Chain Creation)
-> Execute Phase 4 (Validation)
-> Continue to Phase 4
```
---
## Entry Router
When coordinator is invoked, detect invocation type:
@@ -33,10 +54,24 @@ When coordinator is invoked, detect invocation type:
| Worker callback | Message contains `[role-name]` tag from a known worker role | -> handleCallback |
| Status check | Arguments contain "check" or "status" | -> handleCheck |
| Manual resume | Arguments contain "resume" or "continue" | -> handleResume |
| New session | None of the above | -> Phase 0 |
| Interrupted session | Active/paused session exists in `.workflow/.team/TLS-*` | -> Phase 0 (Resume Check) |
| New session | None of above | -> Phase 1 (Requirement Clarification) |
For callback/check/resume: load `commands/monitor.md` and execute the appropriate handler, then STOP.
### Router Implementation
1. **Load session context** (if exists):
- Scan `.workflow/.team/TLS-*/team-session.json` for active/paused sessions
- If found, extract known worker roles from session or SKILL.md Role Registry
2. **Parse $ARGUMENTS** for detection keywords
3. **Route to handler**:
- For monitor handlers: Read `commands/monitor.md`, execute matched handler section, STOP
- For Phase 0: Execute Session Resume Check below
- For Phase 1: Execute Requirement Clarification below
---
## Phase 0: Session Resume Check

1283
CHANGELOG.md
View File

File diff suppressed because it is too large Load Diff

233
COMMAND_REFERENCE.md
View File

@@ -1,233 +0,0 @@
# Command Reference
This document provides a comprehensive reference for all commands available in the Claude Code Workflow (CCW) system.
> **Version 7.0.0 Update**: team-coordinate-v2/team-executor-v2/team-lifecycle-v5 architecture with unified team-worker agent, workflow session commands (start/resume/complete/sync), queue scheduler service, spec management enhancements, CLI multi-provider support, analysis viewer page, security enhancements, skill hub, terminal dashboard, orchestrator template editor, A2UI multi-select questions.
## CLI Commands (`/cli:*`)
| Command | Description |
|---|---|
| `/cli:cli-init`| Initialize CLI tool configurations (Gemini and Qwen) based on workspace analysis. |
> **Note**: For analysis, planning, and bug fixing, use workflow commands (`/workflow:lite-plan`, `/workflow:lite-fix`) or semantic invocation through natural language.
## Workflow Commands (`/workflow:*`)
These commands orchestrate complex, multi-phase development processes, from planning to execution.
### Session Management
| Command | Description |
|---|---|
| `/workflow:session:start` | Discover existing sessions or start a new workflow session with intelligent session management. |
| `/workflow:session:list` | List all workflow sessions with status. |
| `/workflow:session:resume` | Resume the most recently paused workflow session. |
| `/workflow:session:complete` | Mark the active workflow session as complete and remove active flag. |
| `/workflow:session:sync` | ⚡ **NEW** Sync workflow session state to disk during execution. |
| `/workflow:session:solidify` | ⚡ **NEW** Solidify workflow session artifacts and prepare for archiving. |
### Core Workflow
| Command | Description |
|---|---|
| `/workflow:plan` | Orchestrate 5-phase planning workflow with quality gate, executing commands and passing context between phases. |
| `/workflow:lite-plan` | Lightweight interactive planning and execution workflow with in-memory planning, smart code exploration, cost-aware parallel execution, and 50K context protection. |
| `/workflow:lite-fix` | ⚡ **NEW** Intelligent bug diagnosis and fix workflow with adaptive severity assessment, risk-aware verification, and optional hotfix mode. |
| `/workflow:lite-execute` | Execute tasks based on in-memory plan, prompt description, or file content. |
| `/workflow:replan` | Interactive workflow replanning with session-level artifact updates and boundary clarification through guided questioning. |
| `/workflow:execute` | Coordinate agents for existing workflow tasks with automatic discovery. |
| `/workflow:resume` | Intelligent workflow session resumption with automatic progress analysis. |
| `/workflow:review` | Optional specialized review (security, architecture, docs) for completed implementation. |
| `/workflow:status` | Generate on-demand views from JSON task data. |
### Brainstorming
| Command | Description |
|---|---|
| `/workflow:brainstorm:artifacts` | Generate role-specific guidance-specification.md dynamically based on selected roles. |
| `/workflow:brainstorm:auto-parallel` | Parallel brainstorming automation with dynamic role selection and concurrent execution. |
| `/workflow:brainstorm:synthesis` | Clarify and refine role analyses through intelligent Q&A and targeted updates. |
| `/workflow:brainstorm:api-designer` | Generate or update api-designer/analysis.md addressing guidance-specification discussion points. |
| `/workflow:brainstorm:data-architect` | Generate or update data-architect/analysis.md addressing guidance-specification discussion points. |
| `/workflow:brainstorm:product-manager` | Generate or update product-manager/analysis.md addressing guidance-specification discussion points. |
| `/workflow:brainstorm:product-owner` | Generate or update product-owner/analysis.md addressing guidance-specification discussion points. |
| `/workflow:brainstorm:scrum-master` | Generate or update scrum-master/analysis.md addressing guidance-specification discussion points. |
| `/workflow:brainstorm:subject-matter-expert` | Generate or update subject-matter-expert/analysis.md addressing guidance-specification discussion points. |
| `/workflow:brainstorm:system-architect` | Generate or update system-architect/analysis.md addressing guidance-specification discussion points. |
| `/workflow:brainstorm:ui-designer` | Generate or update ui-designer/analysis.md addressing guidance-specification discussion points. |
| `/workflow:brainstorm:ux-expert` | Generate or update ux-expert/analysis.md addressing guidance-specification discussion points. |
### Quality & Verification
| Command | Description |
|---|---|
| `/workflow:plan-verify`| Perform non-destructive cross-artifact consistency and quality analysis of IMPL_PLAN.md and task.json before execution. |
### Code Review Cycle
| Command | Description |
|---|---|
| `/workflow:review-module-cycle` | ⚡ **NEW** Independent multi-dimensional code review for specified modules/files across 7 dimensions with hybrid parallel-iterative execution. |
| `/workflow:review-session-cycle` | ⚡ **NEW** Session-based comprehensive code review analyzing git changes across 7 dimensions with deep-dive on critical issues. |
| `/workflow:review-fix` | ⚡ **NEW** Automated fixing of code review findings with AI-powered planning, intelligent grouping, and test-driven verification. |
### Test-Driven Development (TDD)
| Command | Description |
|---|---|
| `/workflow:tdd-plan` | Orchestrate TDD workflow planning with Red-Green-Refactor task chains. |
| `/workflow:tdd-verify` | Verify TDD workflow compliance and generate quality report. |
### Test Generation & Execution
| Command | Description |
|---|---|
| `/workflow:test-gen` | Generate test plan and tasks by analyzing completed implementation. Use `/workflow:execute` to run generated tasks. |
| `/workflow:test-fix-gen` | Generate test-fix plan and tasks from existing implementation or prompt. Use `/workflow:execute` to run generated tasks. |
| `/workflow:test-cycle-execute` | Execute test-fix workflow with dynamic task generation and iterative fix cycles. Tasks are executed by `/workflow:execute`. |
### UI Design Workflow
| Command | Description |
|---|---|
| `/workflow:ui-design:explore-auto` | Exploratory UI design workflow with style-centric batch generation. |
| `/workflow:ui-design:imitate-auto` | High-speed multi-page UI replication with batch screenshot capture. |
| `/workflow:ui-design:capture` | Batch screenshot capture for UI design workflows using MCP or local fallback. |
| `/workflow:ui-design:explore-layers` | Interactive deep UI capture with depth-controlled layer exploration. |
| `/workflow:ui-design:style-extract` | Extract design style from reference images or text prompts using Claude's analysis. |
| `/workflow:ui-design:layout-extract` | Extract structural layout information from reference images, URLs, or text prompts. |
| `/workflow:ui-design:generate` | Assemble UI prototypes by combining layout templates with design tokens (pure assembler). |
| `/workflow:ui-design:design-sync` | Synchronize finalized design system references to brainstorming artifacts. |
| `/workflow:ui-design:animation-extract` | Extract animation and transition patterns from URLs, CSS, or interactive questioning. |
### Internal Tools
These commands are primarily used internally by other workflow commands but can be used manually.
| Command | Description |
|---|---|
| `/workflow:tools:concept-enhanced` | Enhanced intelligent analysis with parallel CLI execution and design blueprint generation. |
| `/workflow:tools:conflict-resolution` | Detect and resolve conflicts between plan and existing codebase using CLI-powered analysis. |
| `/workflow:tools:context-gather` | Intelligently collect project context using universal-executor agent based on task description and package into standardized JSON. |
| `/workflow:tools:task-generate` | Generate task JSON files and IMPL_PLAN.md from analysis results with artifacts integration. |
| `/workflow:tools:task-generate-agent` | Autonomous task generation using action-planning-agent with discovery and output phases. |
| `/workflow:tools:task-generate-tdd` | Generate TDD task chains with Red-Green-Refactor dependencies. |
| `/workflow:tools:tdd-coverage-analysis` | Analyze test coverage and TDD cycle execution. |
| `/workflow:tools:test-concept-enhanced` | Analyze test requirements and generate test generation strategy using Gemini. |
| `/workflow:tools:test-context-gather` | Collect test coverage context and identify files requiring test generation. |
| `/workflow:tools:test-task-generate` | Generate test-fix task JSON with iterative test-fix-retest cycle specification. |
## Task Commands (`/task:*`)
Commands for managing individual tasks within a workflow session.
| Command | Description |
|---|---|
| `/task:create` | Create implementation tasks with automatic context awareness. |
| `/task:breakdown` | Intelligent task decomposition with context-aware subtask generation. |
| `/task:execute` | Execute tasks with appropriate agents and context-aware orchestration. |
| `/task:replan` | ⚠️ **DEPRECATED** Use `/workflow:replan` instead. Legacy command for task replanning (maintained for backward compatibility). |
## Issue Commands (`/issue:*`)
Commands for issue discovery, planning, and execution management.
### Issue Discovery & Creation
| Command | Description |
|---|---|
| `/issue:discover` | ⚡ **NEW** Discover issues from codebase analysis and error patterns. |
| `/issue:discover-by-prompt` | ⚡ **NEW** Discover issues based on natural language prompt description. |
| `/issue:new` | ⚡ **NEW** Create structured issue with title, context, priority, and labels. |
### Issue Planning & Queue
| Command | Description |
|---|---|
| `/issue:plan` | ⚡ **NEW** Generate solution plan for specified issue with task breakdown. |
| `/issue:queue` | ⚡ **NEW** Form execution queue from planned issues and tasks. |
| `/issue:execute` | ⚡ **NEW** Execute tasks from issue queue with orchestration. |
| `/issue:convert-to-plan` | ⚡ **NEW** Convert issue to executable implementation plan. |
| `/issue:from-brainstorm` | ⚡ **NEW** Create issue from brainstorming session artifacts. |
### Issue Management
| Command | Description |
|---|---|
| `/issue:manage` | ⚡ **NEW** Interactive issue management with menu-driven CRUD operations. |
> **Note**: Issue commands use the `ccw issue` CLI endpoints for data storage and retrieval.
## Memory and Versioning Commands
| Command | Description |
|---|---|
| `/memory:docs` | Plan documentation workflow with dynamic grouping for module trees, README, ARCHITECTURE, and HTTP API docs. |
| `/memory:docs-full-cli` | ⚡ **NEW** Generate full project documentation using CLI execution with batched agents and fallback chain. |
| `/memory:docs-related-cli` | ⚡ **NEW** Generate/update documentation for git-changed modules using CLI execution with batched agents. |
| `/memory:update-full` | Complete project-wide CLAUDE.md documentation update with layer-based execution. |
| `/memory:update-related` | Context-aware CLAUDE.md documentation updates based on recent git changes. |
| `/memory:load` | Quickly load key project context into memory based on a task description. |
| `/memory:load-skill-memory` | Activate SKILL package and intelligently load documentation based on task intent. |
| `/memory:skill-memory` | 4-phase autonomous orchestrator to generate SKILL.md with progressive loading index. |
| `/memory:code-map-memory` | 3-phase orchestrator for code analysis and Mermaid documentation generation. |
| `/memory:tech-research` | 3-phase orchestrator for tech stack research and SKILL package generation. |
| `/memory:workflow-skill-memory` | Process archived sessions to generate workflow-progress SKILL package. |
| `/version` | Display version information and check for updates. |
| `/enhance-prompt` | Context-aware prompt enhancement using session memory and codebase analysis. |
## Team Skills
Unified team coordination and execution skills with role-spec based architecture.
### Core Team Skills (v5/v2)
| Skill | Description |
|-------|-------------|
| `team-lifecycle-v5` | ⚡ **NEW** Unified team skill for full lifecycle (spec/impl/test/review) with team-worker agent architecture. Roles: analyst, writer, planner, executor, tester, reviewer, architect, fe-developer, fe-qa. |
| `team-coordinate-v2` | ⚡ **NEW** Universal team coordination with dynamic role generation. Generates role-specs at runtime and spawns team-worker agents. |
| `team-executor-v2` | ⚡ **NEW** Lightweight session execution - resumes existing team-coordinate-v2 sessions for pure execution. |
### V4/V3 Team Skills (Maintained)
| Skill | Description |
|-------|-------------|
| `team-lifecycle-v4` | Previous version lifecycle skill. Maintained for backward compatibility. |
| `team-lifecycle-v3` | Earlier version lifecycle skill. Maintained for backward compatibility. |
| `team-coordinate` | Original team coordinator. Use `team-coordinate-v2` for new projects. |
| `team-executor` | Original team executor. Use `team-executor-v2` for new projects. |
### Specialized Team Skills
| Skill | Description |
|-------|-------------|
| `team-brainstorm` | Multi-role brainstorming with role-specific analysis generation. |
| `team-issue` | Issue-driven development pipeline with discover, plan, and execute phases. |
| `team-iterdev` | Iterative development workflow with planning, implementation, and testing cycles. |
| `team-planex` | Planning and execution workflow with wave-based task management. |
| `team-frontend` | Frontend-specific development workflow with UI design and QA cycles. |
| `team-quality-assurance` | Quality assurance and testing workflow. |
| `team-roadmap-dev` | Roadmap development and management workflow. |
| `team-tech-debt` | Technical debt identification and remediation workflow. |
| `team-testing` | Comprehensive testing workflow. |
| `team-uidesign` | UI/UX design workflow with style extraction and prototyping. |
| `team-ultra-analyze` | Deep codebase analysis with multi-angle exploration. |
| `team-review` | Multi-dimensional code review workflow. |
### Deprecated Team Skills
| Skill | Status | Replacement |
|-------|--------|-------------|
| Various team commands (team-planex, team-iterdev, etc.) | ⚠️ **DEPRECATED** | Use `team-lifecycle-v5` for unified lifecycle management. |
## Internal Tools (Deprecated)
| Command | Description |
|---|---|
| `/workflow:tools:tdd-coverage-analysis` | ⚠️ **DEPRECATED** Use integrated test coverage analysis. |
| `/workflow:tools:test-concept-enhanced` | ⚠️ **DEPRECATED** Use `/workflow:test-gen` instead. |
| `/workflow:tools:context-gather` | ⚠️ **DEPRECATED** Context gathering is now integrated into main workflows. |
| `/workflow:tools:task-generate` | ⚠️ **DEPRECATED** Use `/workflow:lite-plan` or team-lifecycle task generation. |
| `/workflow:tools:task-generate-agent` | ⚠️ **DEPRECATED** Use unified task generation in workflows. |

715
CONTRIBUTING.md
View File

@@ -1,715 +0,0 @@
# 🤝 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 dependencies
npm install
# Link your development version globally
npm link
# Verify installation
ccw --version
```
---
## 🛠️ 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

464
DASHBOARD_GUIDE.md
View File

@@ -1,464 +0,0 @@
# CCW Dashboard 用户指南
**版本**: 6.2.0
**更新日期**: 2025-12-20
CCW Dashboard 是 Claude Code Workflow 的可视化控制面板，提供项目管理、会话监控、代码索引、记忆管理等功能的统一界面。
---
## 目录
1. [快速启动](#快速启动)
2. [界面布局](#界面布局)
3. [导航结构](#导航结构)
4. [核心视图详解](#核心视图详解)
5. [实时功能](#实时功能)
6. [快捷键](#快捷键)
7. [个性化设置](#个性化设置)
8. [API 端点参考](#api-端点参考)
---
## 快速启动
```bash
# 启动 Dashboard（自动打开浏览器）
ccw view
# 指定项目路径
ccw view -p /path/to/project
# 指定端口
ccw serve --port 8080
# 仅启动服务器（不打开浏览器）
ccw serve
```
Dashboard 默认运行在 `http://localhost:3456`。
---
## 界面布局
CCW Dashboard 是一个单页应用（SPA），界面由四个核心部分组成：
```
┌─────────────────────────────────────────────────────────────┐
│ 顶部操作栏 (Header) │
├──────────────┬──────────────────────────────────────────────┤
│ │ │
│ 侧边栏 │ 主内容区 │
│ 导航 │ (Main Content) │
│ (Sidebar) │ │
│ │ │
│ │ │
├──────────────┴──────────────────────────────────────────────┤
│ 页脚 (Footer) │
└─────────────────────────────────────────────────────────────┘
```
### 顶部操作栏
| 元素 | 功能 |
|------|------|
| 品牌标识 | 显示 "Claude Code Workflow" |
| 项目路径选择器 | 切换最近项目或浏览新项目 |
| 刷新按钮 | 重新加载当前视图数据 |
| 语言切换 (EN/ZH) | 切换界面语言 |
| 主题切换 (☀/🌙) | 切换浅色/深色主题 |
### 侧边栏导航
侧边栏可折叠，按功能分组：
- **项目 (Project)**: 概览、文件浏览器、CLI 状态、历史记录、图谱
- **会话 (Sessions)**: 全部、活跃、已归档的工作流会话
- **轻量任务 (Lite Tasks)**: Lite Plan 和 Lite Fix 会话
- **配置**: MCP 服务器、Hooks 配置
- **记忆 (Memory)**: 上下文、核心记忆、提示历史、技能、规则、CLAUDE.md
---
## 导航结构
### 项目组 (Project)
| 视图 | 说明 |
|------|------|
| **概览** | 项目统计数据、会话总数、任务完成度 |
| **文件浏览器** | 文件树视图，支持预览文件内容 |
| **状态** | CLI 工具安装状态和配置 |
| **历史** | CLI 命令执行历史记录 |
| **图谱** | 代码关系可视化 |
### 会话组 (Sessions)
| 过滤器 | 说明 |
|--------|------|
| **全部** | 显示所有工作流会话 |
| **活跃** | 仅显示进行中的会话 |
| **已归档** | 仅显示已完成/归档的会话 |
### 轻量任务 (Lite Tasks)
| 类型 | 说明 |
|------|------|
| **Lite Plan** | 轻量级规划任务会话 |
| **Lite Fix** | 快速修复任务会话 |
### 配置组
| 视图 | 说明 |
|------|------|
| **MCP 服务器** | 管理 MCP 服务器配置 |
| **Hooks** | 配置工具生命周期钩子 |
### 记忆组 (Memory)
| 视图 | 说明 |
|------|------|
| **上下文** | 文件读写热点和活动热图 |
| **核心记忆** | 战略知识库和会话聚类 |
| **提示历史** | AI 交互历史记录 |
| **技能** | 可重用能力包管理 |
| **规则** | AI 交互指令规则 |
| **CLAUDE.md** | 项目配置文件管理 |
---
## 核心视图详解
### 1. 项目概览 (Project Overview)
显示项目的核心统计信息：
- **会话统计**: 总数、活跃数、已归档数
- **任务进度**: 完成率、进行中任务数
- **活跃会话轮播**: 快速预览当前活跃的会话
### 2. CLI 工具管理 (CLI Manager)
集中管理所有命令行工具的配置。
#### CLI 工具面板
- **状态显示**: Gemini、Qwen、Codex 的安装状态
- **默认工具**: 设置默认使用的 CLI 工具
- **模型配置**: 配置每个工具的主要和次要模型
- **安装/卸载**: 通过向导安装或卸载工具
#### API Endpoint 配置（无需安装 CLI）
如果您没有安装 Gemini/Qwen CLI，但有 API 访问权限（如反向代理服务），可以在 `~/.claude/cli-tools.json` 中配置 `api-endpoint` 类型的工具：
```json
{
"version": "3.2.0",
"tools": {
"gemini-api": {
"enabled": true,
"type": "api-endpoint",
"id": "your-api-id",
"primaryModel": "gemini-2.5-pro",
"secondaryModel": "gemini-2.5-flash",
"tags": ["analysis"]
}
}
}
```
**配置说明**：
- `type: "api-endpoint"`: 表示使用 API 调用而非 CLI
- `id`: API 端点标识符，用于路由请求
- API Endpoint 工具仅支持**分析模式**（只读），不支持文件写入操作
**使用示例**：
```bash
ccw cli -p "分析代码结构" --tool gemini-api --mode analysis
```
#### CodexLens 管理
- **索引路径**: 查看和修改索引存储位置
- **索引操作**:
- 初始化索引（向量模式/FTS 模式）
- 清理当前项目索引
- 清理所有索引
- **语义依赖**: 安装 Python 依赖
- **模型管理**: 下载/删除嵌入模型
- **测试搜索**: 验证索引功能
#### 索引统计
- 总索引大小
- 项目数量
- 向量索引数
- FTS 索引数
### 3. 代码图谱浏览器 (Graph Explorer)（隐藏）
基于 Cytoscape.js 的交互式代码关系可视化工具。
#### 数据源切换
- **代码关系**: 基于 CodexLens 索引的文件/类/函数关系
- **核心记忆**: 记忆条目和实体关系图
#### 交互功能
- **拖拽/缩放/平移**: 自由探索图谱
- **节点着色**: 根据类型和重要性区分
- **过滤器**:
- 范围: 所有文件 / 按模块 / 按文件
- 类型: CLASS / FUNCTION / IMPORTS / CALLS 等
#### 节点详情
- 点击节点显示详细信息
- 类型、路径、行号
- **影响分析**: 分析变更可能影响的文件和符号
### 4. MCP 服务器管理 (MCP Manager)
管理项目级和全局的 MCP 服务器配置。
#### 功能
- **服务器列表**: 查看已配置的服务器
- **创建服务器**: 新建服务器配置
- **编辑/删除**: 修改或移除服务器
- **模板安装**: 从预设模板安装服务器
- **状态监控**: 查看服务器运行状态
### 5. Hook 管理 (Hook Manager)
配置工具执行生命周期钩子。
#### 支持的钩子类型
- **PreToolUse**: 工具使用前触发
- **PostToolUse**: 工具使用后触发
- **Notification**: 通知类钩子
#### 配置方式
- 项目级钩子 (`.claude/settings.local.json`)
- 全局钩子 (`~/.claude/settings.json`)
- 向导创建复杂钩子
- 模板快速配置
### 6. 核心记忆 (Core Memory)
战略知识库管理系统。
#### 记忆列表
- 创建/编辑/归档/删除记忆条目
- 结构化的知识存储
- 标签和分类管理
#### 集群视图
- **自动聚类**: 语义分析相关会话
- **集群管理**:
- 查看集群成员
- 合并/拆分集群
- 删除集群
- **时间线**: 会话活动时间线
#### 嵌入管理
- 生成语义嵌入向量
- 嵌入状态监控
- 批量嵌入操作
### 7. 技能管理 (Skills Manager)
管理可重用的 AI 能力包。
#### 技能分类
- **项目技能**: `./.claude/skills/`
- **用户技能**: `~/.claude/skills/`
#### 技能卡片信息
- 名称和描述
- 版本号
- 包含的工具数量
- 支持文件数量
#### 技能创建
- **导入模式**: 从现有文件夹导入
- **CLI 生成**: 通过描述让 AI 生成
### 8. 帮助视图 (Help View)
国际化帮助文档系统。
- 动态加载帮助内容
- 支持中英文切换
- 快速查找功能指南
---
## 实时功能
Dashboard 通过 WebSocket 连接提供实时数据同步。
### WebSocket 连接
- 端点: `/ws`
- 自动重连机制
- 心跳保活
### 实时事件类型
| 事件 | 说明 |
|------|------|
| `SESSION_CREATED` | 新会话创建 |
| `SESSION_UPDATED` | 会话状态更新 |
| `TASK_UPDATED` | 任务进度更新 |
| `CLI_EXECUTION_STARTED` | CLI 执行开始 |
| `CLI_EXECUTION_COMPLETED` | CLI 执行完成 |
| `CODEXLENS_INDEX_PROGRESS` | 索引进度更新 |
| `MEMORY_UPDATED` | 记忆数据更新 |
| `CLAUDE_FILE_SYNCED` | CLAUDE.md 同步 |
| `REFRESH_REQUIRED` | 需要刷新数据 |
### 静默刷新
对于非关键事件，Dashboard 会在后台静默更新数据，无需用户干预。
---
## 快捷键
| 快捷键 | 功能 |
|--------|------|
| `Escape` | 关闭当前打开的模态框或侧边栏 |
---
## 个性化设置
### 主题
Dashboard 支持两种主题：
- **浅色模式 (Light)**: 默认主题，适合明亮环境
- **深色模式 (Dark)**: 护眼主题，适合暗光环境
点击顶部操作栏的太阳/月亮图标切换。
### 语言
Dashboard 支持两种语言：
- **English (EN)**: 英文界面
- **中文 (ZH)**: 简体中文界面
点击顶部操作栏的 EN/ZH 按钮切换。语言设置会保存到本地存储。
---
## API 端点参考
### 仪表盘数据
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/dashboard-data` | GET | 获取仪表盘主数据 |
| `/api/workspace/switch` | POST | 切换工作区 |
### 会话管理
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/sessions` | GET | 获取会话列表 |
| `/api/sessions/{id}` | GET | 获取会话详情 |
| `/api/sessions/{id}/tasks` | GET | 获取会话任务 |
### 核心记忆
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/core-memory/list` | GET | 获取记忆列表 |
| `/api/core-memory/embed-status` | GET | 嵌入状态 |
| `/api/core-memory/embed` | POST | 生成嵌入 |
| `/api/core-memory/clusters` | GET | 获取集群列表 |
| `/api/core-memory/clusters` | POST | 创建集群 |
| `/api/core-memory/clusters/{id}` | GET | 获取集群详情 |
| `/api/core-memory/clusters/{id}` | PATCH | 更新集群 |
| `/api/core-memory/clusters/{id}` | DELETE | 删除集群 |
| `/api/core-memory/clusters/auto` | POST | 自动聚类 |
| `/api/core-memory/graph` | GET | 获取记忆图谱 |
### CodexLens
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/codexlens/config` | GET | 获取配置 |
| `/api/codexlens/config` | POST | 更新配置 |
| `/api/codexlens/indexes` | GET | 获取索引列表 |
| `/api/codexlens/init` | POST | 初始化索引 |
| `/api/codexlens/clean` | POST | 清理索引 |
| `/api/codexlens/semantic/status` | GET | 语义依赖状态 |
| `/api/codexlens/models` | GET | 获取模型列表 |
### 代码图谱
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/graph/nodes` | GET | 获取图谱节点 |
| `/api/graph/edges` | GET | 获取图谱边 |
| `/api/graph/impact` | POST | 影响分析 |
### 技能管理
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/skills` | GET | 获取技能列表 |
| `/api/skills/{name}` | GET | 获取技能详情 |
| `/api/skills/create` | POST | 创建技能 |
| `/api/skills/{name}` | DELETE | 删除技能 |
### MCP 服务器
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/mcp/servers` | GET | 获取服务器列表 |
| `/api/mcp/servers` | POST | 创建服务器 |
| `/api/mcp/servers/{id}` | PATCH | 更新服务器 |
| `/api/mcp/servers/{id}` | DELETE | 删除服务器 |
### CLI 工具
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/cli/status` | GET | 工具状态 |
| `/api/cli/history` | GET | 执行历史 |
| `/api/cli/config` | GET/POST | 工具配置 |
---
## 故障排除
### Dashboard 无法启动
1. 检查端口是否被占用: `netstat -ano | findstr :3456`
2. 尝试使用其他端口: `ccw serve --port 8080`
3. 检查 Node.js 版本: `node --version` (需要 >= 16.0.0)
### WebSocket 连接失败
1. 检查防火墙设置
2. 确保后端服务正在运行
3. 刷新页面重新建立连接
### 数据不更新
1. 点击刷新按钮手动刷新
2. 检查 WebSocket 连接状态
3. 查看浏览器控制台是否有错误
---
## 相关文档
- [README.md](README.md) - 项目总览
- [GETTING_STARTED.md](GETTING_STARTED.md) - 快速入门
- [COMMAND_REFERENCE.md](COMMAND_REFERENCE.md) - 命令参考
- [CHANGELOG.md](CHANGELOG.md) - 更新日志
---
**CCW Dashboard** - Claude Code Workflow 的可视化控制中心

781
FAQ.md
View File

@@ -1,781 +0,0 @@
# ❓ 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?
**NPM Global Install** (Recommended):
```bash
npm install -g claude-code-workflow
```
**Verify Installation**:
```bash
ccw --version
ccw dashboard # Start Dashboard
ccw view # Start View interface
```
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?
Update via npm:
```bash
npm update -g claude-code-workflow
```
**Note**: Custom modifications in `~/.claude/` will be preserved. The npm package only updates core CCW files.
### 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 you know WHAT to build, but NOT HOW to build it.**
**Brainstorming scenarios**:
- 🤔 **Unclear solution approach** - Multiple ways to solve the problem, need expert analysis
- 🏗️ **Architectural exploration** - Need to explore different architectural patterns
- 📋 **Requirements clarification** - High-level goal is clear, but technical details are not
- 🔀 **Multiple trade-offs** - Need to analyze pros/cons of different approaches
- 🆕 **Unfamiliar domain** - Building something new without clear implementation path
**Skip brainstorming, use `/workflow:plan` directly when**:
- ✅ **Clear implementation approach** - You already know how to build it
- ✅ **Similar to existing code** - Following established patterns in your codebase
- ✅ **Well-defined requirements** - Technical specs are clear from the start
- ✅ **Simple features** - Straightforward implementation, no architectural decisions
**Workflow comparison**:
| Know what + Know how | Know what, NOT how |
|---------------------|-------------------|
| `/workflow:plan "Add JWT auth"` | `/workflow:brainstorm:auto-parallel "Design auth system"` → `/workflow:plan` |
| Plan generates tasks directly | Brainstorm explores solutions → Plan generates tasks |
**Example**:
```bash
# When you DON'T know how to build it
/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**:
- CLI tool configuration
- Example: `/cli:cli-init` (initialize Gemini/Qwen configurations)
**`/workflow:*` commands**:
- Multi-phase orchestration
- Session-based
- Complex development workflows
- Examples: `/workflow:plan`, `/workflow:lite-plan`, `/workflow:lite-fix`
> **Note**: Most CLI commands have been replaced by **semantic invocation**. Simply describe your needs in natural language, and Claude will automatically use the appropriate tools.
### 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 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 using specific commands, you can say:
```
"Use Gemini to analyze the authentication module architecture"
```
Claude will automatically select and execute the appropriate CLI tools (Gemini/Qwen/Codex) with optimized templates.
### 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.
---
## 📦 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
### `better-sqlite3` NODE_MODULE_VERSION mismatch
**Error message**:
```
Error: The module '.../better_sqlite3.node' was compiled against a different Node.js version
using NODE_MODULE_VERSION XX. This version of Node.js requires NODE_MODULE_VERSION YY.
```
**Cause**: The `better-sqlite3` native module was compiled for a different Node.js version than the one you're running. This commonly happens when:
- You installed dependencies with one Node.js version and later switched versions
- Prebuilt binaries don't match your Node.js version
**Solution**:
```bash
# Option 1: Rebuild the native module (recommended)
npm rebuild better-sqlite3
# Option 2: Rebuild from source
npm install better-sqlite3 --build-from-source
# Option 3: Reinstall all dependencies
rm -rf node_modules && npm install
```
> **Note**: Building from source requires C++ build tools. On macOS run `xcode-select --install`, on Ubuntu run `sudo apt install build-essential`, on Windows install [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/).
### "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: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)!

521
GETTING_STARTED.md
View File

@@ -1,521 +0,0 @@
# 🚀 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!

531
GETTING_STARTED_CN.md
View File

@@ -1,531 +0,0 @@
# 🚀 Claude Code Workflow (CCW) - 快速上手指南
欢迎来到 Claude Code Workflow (CCW) v7.0！本指南将帮助您在 5 分钟内快速入门，体验由 AI 驱动的自动化软件开发流程，包括团队编排、队列调度和智能 CLI 编排。
**项目地址**：[catlog22/Claude-Code-Workflow](https://github.com/catlog22/Claude-Code-Workflow)
> **🎉 v7.0 新特性**:
> - 🤖 **团队架构 v2**: team-coordinate-v2 / team-executor-v2 统一 team-worker 代理架构
> - 📋 **队列调度器**: 后台队列执行服务，支持依赖解析和会话池管理
> - 🖥️ **新仪表板视图**: 分析查看器、多终端网格仪表板、编排器模板编辑器
> - 🔄 **工作流会话命令**: start/resume/complete/sync 完整会话生命周期管理
> - 🌐 **A2UI v2**: 多选问题、单选组组件、WebSocket 实时通信
---
## ⏱️ 5 分钟快速入门
让我们通过一个简单的例子，从零开始构建一个 "Hello World" Web 应用。
### 第 1 步：安装 CCW
首先，请确保您已经根据 [安装指南](INSTALL_CN.md) 完成了 CCW 的安装。
### 第 2 步：创建执行计划（会自动启动会话）
直接告诉 CCW 您想做什么。CCW 会分析您的需求，并自动生成一个详细的、可执行的任务计划。
```bash
/workflow:plan "创建一个简单的 Express API，在根路径返回 Hello World"
```
> **💡 提示**：`/workflow:plan` 会自动创建和启动工作流会话，无需手动执行 `/workflow:session:start`。会话会根据任务描述自动命名，例如 `WFS-创建一个简单的-express-api`。
这个命令会启动一个完全自动化的规划流程，包括：
1. **上下文收集**：分析您的项目环境。
2. **智能体分析**：AI 智能体思考最佳实现路径。
3. **任务生成**：创建具体的任务文件（`.json` 格式）。
### 第 3 步：执行计划
当计划创建完毕后，您就可以命令 AI 智能体开始工作了。
```bash
/workflow:execute
```
您会看到 CCW 的智能体（如 `@code-developer`）开始逐一执行任务。它会自动创建文件、编写代码、安装依赖。
### 第 4 步：查看状态
想知道进展如何？随时可以查看当前工作流的状态。
```bash
/workflow:status
```
这会显示任务的完成情况、当前正在执行的任务以及下一步计划。
### 第 5 步：完成会话
所有任务完成后，标记会话为完成：
```bash
/workflow:session:complete
```
这会归档会话、提取经验教训，并可选地同步项目状态。
---
## 🧠 核心概念解析
理解这几个概念，能帮助您更好地使用 CCW：
- **工作流会话 (Workflow Session)**
> 就像一个独立的沙盒或项目空间，用于隔离不同任务的上下文、文件和历史记录。所有相关文件都存放在 `.workflow/WFS-<会话名>/` 目录下。
- **任务 (Task)**
> 一个原子化的工作单元，例如“创建 API 路由”、“编写测试用例”。每个任务都是一个 `.json` 文件，详细定义了目标、上下文和执行步骤。
- **智能体 (Agent)**
> 专门负责特定领域工作的 AI 助手。例如：
> - `@code-developer`: 负责编写和实现代码。
> - `@test-fix-agent`: 负责运行测试并自动修复失败的用例。
> - `@ui-design-agent`: 负责 UI 设计和原型创建。
> - `@cli-execution-agent`: 负责自主 CLI 任务处理（v4.5.0+）。
> - **team-worker**: 统一的工作代理，用于团队编排（v7.0+）。
- **工作流 (Workflow)**
> 一系列预定义的、相互协作的命令，用于编排不同的智能体和工具，以完成一个复杂的开发目标（如 `plan`、`execute`、`test-gen`）。
---
## 🆕 v7.0 新功能概览
### 工作流会话管理 (v7.0)
CCW v7.0 引入完整的会话生命周期命令：
```bash
# 启动新会话（自动命名）
/workflow:session:start --auto "实现用户认证"
# 恢复暂停的会话
/workflow:session:resume
# 完成并归档当前会话
/workflow:session:complete
# 同步会话工作到项目规范
/workflow:session:sync "完成的工作内容"
```
### 团队架构 v2 (v7.0)
对于需要多个专业角色的复杂项目，使用团队架构 v2：
```bash
# 协调团队，自动生成角色规范
/team-coordinate "构建实时协作系统"
# 执行预规划的团队会话
/team-executor <session-folder>
# 团队成员包括：analyst、planner、executor、tester、reviewer、architect
```
**核心功能**：
- **动态角色规范生成**：运行时创建角色特定指令
- **team-worker 代理**：统一处理阶段1-5编排的工作代理
- **内循环处理**：在单个代理中处理多个相同前缀任务
- **Discuss & Explore 子代理**：多视角批判和代码探索
### 队列调度器 (v7.0)
用于具有依赖管理的后台任务执行：
```bash
# 通过仪表板访问 → Terminal Dashboard → Queue Panel
# 或使用 API 端点进行程序化控制
```
**功能**：
- 拓扑排序的依赖解析
- 三层分配策略的会话池管理
- 实时 WebSocket 状态更新
- 可配置限制的并发执行
### 新仪表板视图 (v7.0)
**分析查看器页面** (`/analysis`):
- 并发分析会话的网格布局
- 过滤、分页和全屏模式
- 实时进度跟踪
**终端仪表板** (`/terminal-dashboard`):
- 多终端网格布局（tmux 风格分屏）
- 带代理编排的执行监控面板
- 拖放式会话组树管理
- 队列调度器控件
**编排器模板编辑器** (`/orchestrator`):
- 编排计划的可视化模板编辑
- 斜杠命令执行与终端集成
- 调试用的可观测性面板
---
## 🛠️ 常见场景示例
### 场景 1：快速功能开发
对于简单、明确的功能，使用直接的"规划 → 执行"模式：
```bash
# 创建计划（自动创建会话）
/workflow:plan "实现基于 JWT 的用户登录和注册功能"
# 执行
/workflow:execute
```
> **💡 提示**：`/workflow:plan` 会自动创建会话。您也可以先手动启动会话：`/workflow:session:start "功能名称"`。
### 场景 2：UI 设计探索
对于以 UI 为重点的项目，在实现前先进行设计探索：**ui-design → update → 规划 → 执行**
```bash
# 第 1 步：生成 UI 设计变体（自动创建会话）
/workflow:ui-design:explore-auto --prompt "一个现代、简洁的管理后台登录页面"
# 第 2 步：在 compare.html 中审查设计，然后同步设计系统到头脑风暴工件
/workflow:ui-design:design-sync --session <session-id> --selected-prototypes "login-v1,login-v2"
# 第 3 步：使用设计引用生成实现计划
/workflow:plan
# 第 4 步：执行实现
/workflow:execute
```
> **💡 提示**：`update` 命令将选定的设计原型集成到头脑风暴工件中，确保实现遵循批准的设计。
### 场景 3：复杂功能的多智能体头脑风暴
对于需要深入分析的复杂功能，使用完整工作流：**头脑风暴 → 规划 → 执行**
```bash
# 第 1 步：多智能体头脑风暴（自动创建会话）
/workflow:brainstorm:auto-parallel "设计一个支持冲突解决的实时协作文档编辑系统"
# 可选：指定专家角色数量（默认：3，最大：9）
/workflow:brainstorm:auto-parallel "构建可扩展的微服务平台" --count 5
# 第 2 步：从头脑风暴结果生成实现计划
/workflow:plan
# 第 3 步：执行计划
/workflow:execute
```
**头脑风暴优势**：
- **自动角色选择**：分析主题并选择 3-9 个相关专家角色（系统架构师、UI 设计师、产品经理等）
- **并行执行**：多个 AI 智能体从不同视角同时分析
- **综合规格说明**：生成整合的需求和设计文档
**何时使用头脑风暴**：
- **知道要做什么，但不知道怎么做** - 需要探索解决方案
- **存在多个解决路径** - 需要专家分析选择最佳方案
- **技术需求不明确** - 需要澄清架构、数据模型、API
- **重大架构决策** - 需要多角度分析再做决定
**何时跳过头脑风暴**（直接使用 `/workflow:plan`）：
- 已经知道实现方法
- 一开始就有清晰的技术需求
- 简单直接的功能
- 与代码库中现有实现类似
### 场景 4：质量保证 - 行动计划验证
规划后，验证您的实现计划的一致性和完整性：
```bash
# /workflow:plan 完成后，验证任务质量
/workflow:plan-verify
# 该命令将：
# 1. 检查需求覆盖率（所有需求都有任务）
# 2. 验证任务依赖关系（无循环或损坏的依赖）
# 3. 确保综合对齐（任务符合架构决策）
# 4. 评估任务规范质量
# 5. 生成详细的验证报告和修复待办事项
```
**验证报告包括**：
- 需求覆盖率分析
- 依赖关系图验证
- 综合对齐检查
- 任务规范质量评估
- 优先级修复建议
**使用时机**：
- 在 `/workflow:plan` 生成 IMPL_PLAN.md 和任务文件后
- 在开始 `/workflow:execute` 之前
- 处理具有许多依赖关系的复杂项目时
- 当您想确保高质量的任务规范时
**优势**：
- 在执行前捕获规划错误
- 确保完整的需求覆盖
- 验证架构一致性
- 识别资源冲突和技能差距
- 提供可执行的修复计划，集成 TodoWrite
### 场景 5：Bug 修复
快速 Bug 分析和修复工作流：
```bash
# 轻量级 Bug 修复工作流，带智能诊断
/workflow:lite-fix "密码错误时仍显示成功消息"
# Claude 会分析严重程度，诊断根因，并实现修复
```
### 场景 6：基于团队的协作开发 (v7.0)
对于需要多个专业视角的复杂项目：
```bash
# 协调团队，自动生成角色规范
/team-coordinate "设计和实现微服务架构"
# 工作流程：
# 1. 分析需求并检测所需能力
# 2. 生成动态角色规范（analyst、planner、executor、tester、reviewer）
# 3. 创建具有适当依赖关系的任务
# 4. 分派给 team-worker 代理
# 5. 通过回调监控进度
# 6. 完成并生成综合报告
# 恢复暂停的团队会话
/team-executor .workflow/.team/TLS-xxx-2026-02-27 resume
```
---
## 🔧 轻量级命令
除了完整的工作流模式，CCW 还提供轻量级命令，适合快速分析和日常任务。
### 快速任务工作流命令
使用工作流命令进行集成规划和 Bug 修复：
```bash
# 轻量级规划工作流
/workflow:lite-plan "设计一个可扩展的微服务架构"
# 带智能诊断的 Bug 修复工作流
/workflow:lite-fix "分析内存泄漏问题的可能原因"
# 初始化 CLI 工具配置
/cli:cli-init
```
### 语义调用（替代直接 CLI 命令）
> **重要**: 直接 CLI 命令（`/cli:analyze`、`/cli:chat`、`/cli:execute` 等）已被**语义调用**替代。只需使用自然语言描述您的需求，Claude 会自动选择并执行合适的 CLI 工具（Gemini/Qwen/Codex）和优化的模板。
用户可以通过自然语言告诉 Claude 使用特定工具完成任务，Claude 会理解意图并自动执行相应的命令。
#### 语义调用示例
直接在对话中使用自然语言描述需求：
**示例 1：代码分析**
```
用户："使用 gemini 分析一下这个项目的模块化架构"
→ Claude 会自动执行 gemini 进行分析
```
**示例 2：文档生成**
```
用户："用 gemini 生成 API 文档，包含所有端点的说明"
→ Claude 会理解需求，自动调用 gemini 的写入模式生成文档
```
**示例 3：代码实现**
```
用户："使用 codex 实现用户登录功能"
→ Claude 会调用 codex 工具进行自主开发
```
#### 语义调用的优势
- **自然交互**：无需记忆复杂的命令语法
- **智能理解**：Claude 会根据上下文选择合适的工具和参数
- **自动优化**：Claude 会自动添加必要的上下文和配置
### 内存管理：CLAUDE.md 更新
CCW 使用分层的 CLAUDE.md 文档系统维护项目上下文。定期更新这些文档对保证 AI 输出质量至关重要。
#### 完整项目重建索引
适用于大规模重构、架构变更或初次使用 CCW：
```bash
# 重建整个项目的文档索引
/memory:update-full
# 使用特定工具进行索引
/memory:update-full --tool gemini # 全面分析（推荐）
/memory:update-full --tool qwen # 架构重点
/memory:update-full --tool codex # 实现细节
```
**执行时机**：
- 项目初始化时
- 架构重大变更后
- 每周定期维护
- 发现 AI 输出偏差时
#### 快速加载特定任务上下文
当您需要立即获取特定任务的上下文，而无需更新文档时：
```bash
# 为特定任务加载上下文到内存
/memory:load "在当前前端基础上开发用户认证功能"
# 使用其他 CLI 工具进行分析
/memory:load --tool qwen "重构支付模块API"
```
**工作原理**：
- 委托 AI 智能体进行自主项目分析
- 发现相关文件并提取任务特定关键词
- 使用 CLI 工具（Gemini/Qwen）进行深度分析以节省令牌
- 返回加载到内存中的结构化"核心内容包"
- 为后续智能体操作提供上下文
**使用时机**：
- 开始新功能或任务之前
- 需要快速获取上下文而无需完整文档重建时
- 针对特定任务的架构或模式发现
- 作为基于智能体开发工作流的准备工作
#### 增量更新相关模块
适用于日常开发，只更新变更影响的模块：
```bash
# 更新最近修改相关的文档
/memory:update-related
# 指定工具进行更新
/memory:update-related --tool gemini
```
**执行时机**：
- 完成功能开发后
- 重构某个模块后
- 更新 API 接口后
- 修改数据模型后
#### 内存质量的影响
| 更新频率 | 结果 |
|---------|------|
| ❌ 从不更新 | 过时的 API 引用、错误的架构假设、低质量输出 |
| ⚠️ 偶尔更新 | 部分上下文准确、可能出现不一致 |
| ✅ 及时更新 | 高质量输出、精确的上下文、正确的模式引用 |
### CLI 工具初始化
首次使用外部 CLI 工具时，可以使用初始化命令快速配置：
```bash
# 自动配置所有工具
/cli:cli-init
# 只配置特定工具
/cli:cli-init --tool gemini
/cli:cli-init --tool qwen
```
该命令会：
- 分析项目结构
- 生成工具配置文件
- 设置 `.geminiignore` / `.qwenignore`
- 创建上下文文件引用
---
## 🎯 进阶用法：智能体技能 (Agent Skills)
智能体技能是可扩展 AI 功能的模块化、可复用能力。它们存储在 `.claude/skills/` 目录中,通过特定的触发机制调用。
### 技能工作原理
- **模型调用**：与斜杠命令不同,您不直接调用技能。AI 会根据对您目标的理解来决定何时使用技能。
- **上下文化**：技能为 AI 提供特定的指令、脚本和模板,用于专门化任务。
- **触发机制**：
- **对话触发**：在**自然对话**中使用 `-e` 或 `--enhance` 标识符来触发 `prompt-enhancer` 技能
- **CLI 命令增强**：在 **CLI 命令**中使用 `--enhance` 标识符进行提示词优化(这是 CLI 功能,不是技能触发)
### 使用示例
**对话触发** (激活 prompt-enhancer 技能):
```
用户: "分析认证模块 -e"
→ AI 使用 prompt-enhancer 技能扩展请求
```
**重要说明**：`-e` 标识符用于在自然对话中触发 prompt-enhancer 技能。
---
## 🎨 进阶用法：UI 设计工作流
CCW 包含强大的多阶段 UI 设计和原型制作工作流,能够从简单的描述或参考图像生成完整的设计系统和交互式原型。
### 核心命令
- `/workflow:ui-design:explore-auto`: 探索性工作流,基于提示词生成多种不同的设计变体。
- `/workflow:ui-design:imitate-auto`: 设计工作流,从本地参考文件(图片、代码)或文本提示创建原型。
### 示例：从提示词生成 UI
您可以使用单个命令为网页生成多种设计选项:
```bash
# 此命令将为登录页面生成 3 种不同的样式和布局变体
/workflow:ui-design:explore-auto --prompt "一个现代简洁的 SaaS 应用登录页面" --targets "login" --style-variants 3 --layout-variants 3
```
工作流完成后,会提供一个 `compare.html` 文件,让您可以可视化地查看和选择最佳设计组合。
---
## ❓ 常见问题排查 (Troubleshooting)
- **问题：提示 "No active session found" (未找到活动会话)**
> **原因**：您还没有启动一个工作流会话，或者当前会话已完成。
> **解决方法**：使用 `/workflow:session:start "您的任务描述"` 来开始一个新会话。
- **问题：命令执行失败或卡住**
> **原因**：可能是网络问题、AI 模型限制或任务过于复杂。
> **解决方法**：
> 1. 首先尝试使用 `/workflow:status` 检查当前状态。
> 2. 查看 `.workflow/WFS-<会话名>/.chat/` 目录下的日志文件，获取详细错误信息。
> 3. 如果任务过于复杂，尝试将其分解为更小的任务，然后使用 `/workflow:plan` 重新规划。
---
## 📚 进阶学习路径
当您掌握了基础用法后，可以探索 CCW 更强大的功能：
1. **测试驱动开发 (TDD)**: 使用 `/workflow:tdd-plan` 来创建一个完整的 TDD 工作流，AI 会先编写失败的测试，然后编写代码让测试通过，最后进行重构。
2. **多智能体头脑风暴**: 使用 `/workflow:brainstorm:auto-parallel` 让多个不同角色的 AI 智能体（如系统架构师、产品经理、安全专家）同时对一个主题进行分析，并生成一份综合报告。
3. **自定义智能体和命令**: 您可以修改 `.claude/agents/` 和 `.claude/commands/` 目录下的文件，来定制符合您团队特定需求的智能体行为和工作流。
希望本指南能帮助您顺利开启 CCW 之旅！

180
INSTALL.md
View File

@@ -1,180 +0,0 @@
# Claude Code Workflow (CCW) - Installation Guide
**English** | [中文](INSTALL_CN.md)
Installation guide for Claude Code Agent workflow coordination and distributed memory system.
> **Version 6.3.18: Native CodexLens & Dashboard Revolution** - Built-in code indexing engine (FTS + semantic search + HNSW vector index), new Dashboard views, TypeScript backend, session clustering intelligent memory management.
## ⚡ Quick Installation (Recommended)
### NPM Global Install
```bash
npm install -g claude-code-workflow
```
### Complete Installation
After installing the npm package, you need to run the installation command to set up workflows, scripts, and templates:
```bash
# Install CCW system files (workflows, scripts, templates)
ccw install
```
The `ccw install` command will:
- Install workflow definitions to `~/.ccw/workflows/`
- Install utility scripts to `~/.claude/scripts/`
- Install prompt templates to `~/.claude/templates/`
- Install skill definitions to `~/.codex/skills/`
- Configure shell integration (optional)
### Verify Installation
```bash
# Check ccw command
ccw --version
# Start Dashboard
ccw dashboard
# Start View interface (alternative UI)
ccw view
```
## 📂 Install from Source
If you want to install from source or contribute to development:
```bash
# Clone repository
git clone https://github.com/catlog22/Claude-Code-Workflow.git
cd Claude-Code-Workflow
# Install dependencies
npm install
# Global link (development mode)
npm link
```
## Platform Requirements
- **Node.js**: 16.0.0 or higher
- **OS**: Windows, Linux, macOS
Check Node.js version:
```bash
node --version # Should be >= 16.0.0
```
## ⚙️ Configuration
### Tool Control System
CCW uses a **configuration-based tool control system** that makes external CLI tools **optional** rather than required. This allows you to:
- ✅ **Start with Claude-only mode** - Work immediately without installing additional tools
- ✅ **Progressive enhancement** - Add external tools selectively as needed
- ✅ **Graceful degradation** - Automatic fallback when tools are unavailable
- ✅ **Flexible configuration** - Control tool availability per project
**Configuration File**: `~/.ccw/workflows/tool-control.yaml`
```yaml
tools:
gemini:
enabled: false # Optional: AI analysis & documentation
qwen:
enabled: true # Optional: AI architecture & code generation
codex:
enabled: true # Optional: AI development & implementation
```
**Behavior**:
- **When disabled**: CCW automatically falls back to other enabled tools or Claude's native capabilities
- **When enabled**: Uses specialized tools for their specific strengths
- **Default**: All tools disabled - Claude-only mode works out of the box
### Optional CLI Tools *(Enhanced Capabilities)*
While CCW works with Claude alone, installing these tools provides enhanced analysis and extended context:
#### System Utilities
| Tool | Purpose | Installation |
|------|---------|--------------|
| **ripgrep (rg)** | Fast code search | **macOS**: `brew install ripgrep`<br>**Linux**: `apt install ripgrep`<br>**Windows**: `winget install ripgrep` |
| **jq** | JSON processing | **macOS**: `brew install jq`<br>**Linux**: `apt install jq`<br>**Windows**: `winget install jq` |
#### External AI Tools
Configure these tools in `~/.ccw/workflows/tool-control.yaml` after installation:
| Tool | Purpose | Installation |
|------|---------|--------------|
| **Gemini CLI** | AI analysis & documentation | Follow [official docs](https://ai.google.dev) - Free quota, extended context |
| **Codex CLI** | AI development & implementation | Follow [official docs](https://github.com/openai/codex) - Autonomous development |
| **Qwen Code** | AI architecture & code generation | Follow [official docs](https://github.com/QwenLM/qwen-code) - Large context window |
### Recommended: MCP Tools *(Enhanced Analysis)*
MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recommended installation** - While CCW has fallback mechanisms, not installing MCP tools may lead to unexpected behavior or degraded performance in some workflows.
| MCP Server | Purpose | Installation Guide |
|------------|---------|-------------------|
| **Exa MCP** | External API patterns & best practices | [Install Guide](https://smithery.ai/server/exa) |
| **Chrome DevTools MCP** | ⚠️ **Required for UI workflows** - URL mode design extraction | [Install Guide](https://github.com/ChromeDevTools/chrome-devtools-mcp) |
> **Note**: Code Index MCP has been replaced by CCW's built-in **CodexLens** (`mcp__ccw-tools__codex_lens`). No additional installation required for code indexing.
## ✅ Verify Installation
After installation, open **Claude Code** and check if the workflow commands are available by running:
```bash
/workflow:session:list
```
This command should be recognized in Claude Code's interface. If you see the workflow slash commands (e.g., `/workflow:*`, `/cli:*`), the installation was successful.
## Troubleshooting
### Permission Errors (npm global install)
**Linux/macOS**:
```bash
# Option 1: Use nvm to manage Node.js (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# Option 2: Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
```
**Windows**: Run Command Prompt or PowerShell as Administrator
### Workflow Commands Not Working
- Verify installation: `ls ~/.claude` (should show agents/, commands/, workflows/)
- Restart Claude Code after installation
- Check `/workflow:session:list` command is recognized
### ccw Command Not Found
```bash
# Check global install location
npm list -g --depth=0
# Ensure npm bin directory is in PATH
npm bin -g
```
## Support
- **Issues**: [GitHub Issues](https://github.com/catlog22/Claude-Code-Workflow/issues)
- **Getting Started**: [Quick Start Guide](GETTING_STARTED.md)
- **Documentation**: [Main README](README.md)

207
INSTALL_CN.md
View File

@@ -1,207 +0,0 @@
# Claude Code Workflow (CCW) - 安装指南
[English](INSTALL.md) | **中文**
Claude Code Agent 工作流协调和分布式内存系统的安装指南。
> **版本 6.3.18：原生 CodexLens 与 Dashboard 革新** - 内置代码索引引擎（FTS + 语义搜索 + HNSW 向量索引），全新 Dashboard 视图，TypeScript 后端，会话聚类智能记忆管理。
## ⚡ 快速安装（推荐）
### NPM 全局安装
```bash
npm install -g claude-code-workflow
```
### 完成安装
安装 npm 包后，需要运行安装命令来设置工作流、脚本和模板：
```bash
# 安装 CCW 系统文件（工作流、脚本、模板）
ccw install
```
`ccw install` 命令将会：
- 安装工作流定义到 `~/.ccw/workflows/`
- 安装实用脚本到 `~/.claude/scripts/`
- 安装提示模板到 `~/.claude/templates/`
- 安装技能定义到 `~/.codex/skills/`
- 配置 shell 集成（可选）
### 验证安装
```bash
# 检查 ccw 命令
ccw --version
# 启动 Dashboard
ccw dashboard
# 启动 View 界面（替代 UI）
ccw view
```
## 📂 从源码安装
如果你想从源码安装或参与开发：
```bash
# 克隆仓库
git clone https://github.com/catlog22/Claude-Code-Workflow.git
cd Claude-Code-Workflow
# 安装依赖
npm install
# 全局链接（开发模式）
npm link
```
## 平台要求
- **Node.js**: 16.0.0 或更高版本
- **操作系统**: Windows、Linux、macOS
检查 Node.js 版本：
```bash
node --version # 应该 >= 16.0.0
```
## ⚙️ 配置
### 工具控制系统
CCW 使用**基于配置的工具控制系统**，使外部 CLI 工具成为**可选**而非必需。这允许你：
- ✅ **从仅 Claude 模式开始** - 无需安装额外工具即可立即使用
- ✅ **渐进式增强** - 按需选择性添加外部工具
- ✅ **优雅降级** - 工具不可用时自动回退
- ✅ **灵活配置** - 每个项目控制工具可用性
**配置文件**：`~/.claude/cli-tools.json`
```json
{
"version": "3.4.0",
"tools": {
"gemini": {
"enabled": true,
"primaryModel": "gemini-2.5-pro",
"type": "builtin"
},
"qwen": {
"enabled": true,
"primaryModel": "coder-model",
"type": "builtin"
},
"codex": {
"enabled": true,
"primaryModel": "gpt-5.2",
"type": "builtin"
},
"claude": {
"enabled": true,
"primaryModel": "sonnet",
"type": "builtin"
},
"opencode": {
"enabled": true,
"primaryModel": "opencode/glm-4.7-free",
"type": "builtin"
}
}
}
```
**行为**：
- **禁用时**：CCW 自动回退到其他已启用的工具或 Claude 的原生能力
- **启用时**：使用专门工具发挥其特定优势
- **默认**：首次运行时自动检测已安装的工具并同步启用状态
### 可选 CLI 工具（增强功能）
虽然 CCW 仅使用 Claude 即可工作，但安装这些工具可提供增强的分析和扩展上下文：
#### 系统工具
| 工具 | 用途 | 安装方式 |
|------|------|----------|
| **ripgrep (rg)** | 快速代码搜索 | **macOS**: `brew install ripgrep`<br>**Linux**: `apt install ripgrep`<br>**Windows**: `winget install ripgrep` |
| **jq** | JSON 处理 | **macOS**: `brew install jq`<br>**Linux**: `apt install jq`<br>**Windows**: `winget install jq` |
#### 外部 AI 工具
CCW 通过 `~/.claude/cli-tools.json` 统一管理以下 CLI 工具，所有工具均可通过 npm 全局安装：
| 工具 | npm 包 | 用途 | 安装方式 |
|------|--------|------|----------|
| **Gemini CLI** | `@google/gemini-cli` | Google AI 代码分析和生成 | `npm install -g @google/gemini-cli`<br>[GitHub](https://github.com/google-gemini/gemini-cli) |
| **Qwen Code** | `@qwen-code/qwen-code` | 阿里云 AI 编程助手 | `npm install -g @qwen-code/qwen-code`<br>[GitHub](https://github.com/QwenLM/qwen-code) |
| **Codex CLI** | `@openai/codex` | OpenAI 代码生成和理解 | `npm install -g @openai/codex`<br>[GitHub](https://github.com/openai/codex) |
| **Claude Code** | `@anthropic-ai/claude-code` | Anthropic AI 助手 | `npm install -g @anthropic-ai/claude-code`<br>[GitHub](https://github.com/anthropics/claude-code) |
| **OpenCode** | `opencode` | 开源多模型 AI 编程代理 | `npm install -g opencode`<br>[官网](https://opencode.ai) \| [GitHub](https://github.com/sst/opencode) |
> **提示**：也可在 CCW Dashboard 的 CLI Manager 视图中直接管理工具的安装、卸载和启用状态。
### 推荐：MCP 工具（增强分析）
MCP（模型上下文协议）工具提供高级代码库分析。**推荐安装** - 虽然 CCW 有回退机制，但不安装 MCP 工具可能导致某些工作流的意外行为或性能下降。
| MCP 服务器 | 用途 | 安装指南 |
|------------|------|----------|
| **Exa MCP** | 外部 API 模式和最佳实践 | [安装指南](https://smithery.ai/server/exa) |
| **Chrome DevTools MCP** | ⚠️ **UI 工作流必需** - URL 模式设计提取 | [安装指南](https://github.com/ChromeDevTools/chrome-devtools-mcp) |
> **注意**：Code Index MCP 已被 CCW 内置的 **CodexLens** (`mcp__ccw-tools__codex_lens`) 替代。无需额外安装代码索引工具。
## ✅ 验证安装
安装后，在 **Claude Code** 中检查工作流命令是否可用：
```bash
/workflow:session:list
```
此命令应在 Claude Code 界面中被识别。如果看到工作流斜杠命令（如 `/workflow:*`、`/cli:*`），则安装成功。
## 故障排除
### 权限错误（npm 全局安装）
**Linux/macOS**：
```bash
# 选项 1：使用 nvm 管理 Node.js（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# 选项 2：修复 npm 权限
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
```
**Windows**：以管理员身份运行命令提示符或 PowerShell
### 工作流命令无效
- 验证安装：`ls ~/.claude`（应显示 agents/、commands/、workflows/）
- 安装后重启 Claude Code
- 检查 `/workflow:session:list` 命令是否被识别
### ccw 命令未找到
```bash
# 检查全局安装位置
npm list -g --depth=0
# 确保 npm bin 目录在 PATH 中
npm bin -g
```
## 支持
- **问题**：[GitHub Issues](https://github.com/catlog22/Claude-Code-Workflow/issues)
- **快速入门**：[快速入门指南](GETTING_STARTED_CN.md)
- **文档**：[主 README](README_CN.md)

188
META_SKILL_SUMMARY.md
View File

@@ -1,188 +0,0 @@
# Meta-Skill Template Update Summary
## Update Overview
Successfully updated all 17 meta-skill workflow templates with proper execution configuration and context passing.
## Critical Correction: CLI Tools vs Slash Commands
**IMPORTANT**: ALL workflow commands (`/workflow:*`) must use `slash-command` type.
### Slash Command (workflow commands)
- **Type**: `slash-command`
- **Commands**: ALL `/workflow:*` commands
- Planning: plan, lite-plan, multi-cli-plan, tdd-plan
- Execution: execute, lite-execute
- Testing: test-fix-gen, test-cycle-execute, tdd-verify
- Review: review-session-cycle, review-cycle-fix, review-module-cycle
- Bug fixes: lite-fix, debug-with-file
- Exploration: brainstorm-with-file, brainstorm:auto-parallel, analyze-with-file
- **Modes**:
- `mainprocess`: Blocking, main process execution
- `async`: Background execution via `ccw cli --tool claude --mode write`
### CLI Tools (for pure analysis/generation)
- **Type**: `cli-tools`
- **When to use**: Only when there's NO specific workflow command
- **Purpose**: Dynamic prompt generation based on task content
- **Tools**: gemini (analysis), qwen (code generation), codex (review)
- **Examples**:
- "Analyze this architecture design and suggest improvements"
- "Generate unit tests for module X with 90% coverage"
- "Review code for security vulnerabilities"
## Key Changes
### 1. Schema Enhancement
All templates now include:
- **`execution`** configuration:
- Type: Always `slash-command` for workflow commands
- Mode: `mainprocess` (blocking) or `async` (background)
- **`contextHint`** field: Natural language instructions for context passing
- **`unit`** field: Groups commands into minimum execution units
- **`args`** field: Command arguments with `{{goal}}` and `{{prev}}` placeholders
### 2. Execution Patterns
**Planning (mainprocess)**:
- Interactive planning needs main process
- Examples: plan, lite-plan, tdd-plan, multi-cli-plan
**Execution (async)**:
- Long-running tasks need background
- Examples: execute, lite-execute, test-cycle-execute
**Review/Verify (mainprocess)**:
- Needs immediate feedback
- Examples: plan-verify, review-session-cycle, tdd-verify
**Fix (mainprocess/async)**:
- Simple fixes: mainprocess
- Complex fixes: async
- Examples: lite-fix (mainprocess), review-cycle-fix (mainprocess)
### 3. Minimum Execution Units
Preserved atomic command groups from ccw-coordinator.md:
| Unit | Commands | Purpose |
|------|----------|---------|
| `quick-implementation` | lite-plan → lite-execute | Lightweight implementation |
| `verified-planning-execution` | plan → plan-verify → execute | Full planning with verification |
| `bug-fix` | lite-fix → lite-execute | Bug diagnosis and fix |
| `test-validation` | test-fix-gen → test-cycle-execute | Test generation and validation |
| `code-review` | review-session-cycle → review-cycle-fix | Code review and fixes |
| `tdd-planning-execution` | tdd-plan → execute | Test-driven development |
| `multi-cli-planning` | multi-cli-plan → lite-execute | Multi-perspective planning |
| `issue-workflow` | issue:plan → issue:queue → issue:execute | Issue lifecycle |
| `rapid-to-issue` | lite-plan → convert-to-plan → queue → execute | Bridge lite to issue |
| `brainstorm-to-issue` | from-brainstorm → queue → execute | Bridge brainstorm to issue |
## Updated Templates
### Simple Workflows (Level 1-2)
1. **lite-lite-lite.json** - Ultra-lightweight direct execution
2. **bugfix-hotfix.json** - Urgent production fix (single async step)
3. **rapid.json** - Quick implementation with optional testing
4. **bugfix.json** - Bug fix with diagnosis and testing
5. **test-fix.json** - Fix failing tests workflow
6. **docs.json** - Documentation generation
### Complex Workflows (Level 3-4)
7. **tdd.json** - Test-driven development with verification
8. **coupled.json** - Full workflow with review and testing
9. **review.json** - Standalone code review workflow
10. **multi-cli-plan.json** - Multi-perspective planning
11. **full.json** - Comprehensive workflow with brainstorm
### Exploration Workflows
12. **brainstorm.json** - Multi-perspective ideation
13. **debug.json** - Hypothesis-driven debugging
14. **analyze.json** - Collaborative analysis
### Issue Workflows
15. **issue.json** - Full issue lifecycle
16. **rapid-to-issue.json** - Bridge lite plan to issue
17. **brainstorm-to-issue.json** - Bridge brainstorm to issue
## Design Principles Applied
1. **Slash Commands Only**: All workflow commands use `slash-command` type
2. **Minimum Execution Units**: Preserved atomic command groups
3. **Context Flow**: `contextHint` provides natural language guidance
4. **Execution Modes**:
- `mainprocess`: Interactive, needs user feedback
- `async`: Long-running, background execution
## CLI Tools Usage (Future Extension)
The `cli-tools` type is reserved for pure analysis/generation tasks WITHOUT specific workflow commands:
```json
{
"name": "custom-analysis",
"steps": [
{
"execution": {
"type": "cli-tools",
"mode": "mainprocess",
"tool": "gemini",
"cliMode": "analysis",
"rule": "analysis-analyze-technical-document"
},
"contextHint": "Analyze architecture design and provide recommendations"
}
]
}
```
**Note**: This is for future extension only. Current templates use slash commands exclusively.
## Files Modified
```
.claude/skills/meta-skill/templates/
├── rapid.json ✓ Updated (slash-command only)
├── coupled.json ✓ Updated (slash-command only)
├── bugfix.json ✓ Fixed (removed cli-tools)
├── bugfix-hotfix.json ✓ Updated (slash-command only)
├── tdd.json ✓ Fixed (removed cli-tools)
├── test-fix.json ✓ Updated (slash-command only)
├── review.json ✓ Fixed (removed cli-tools)
├── brainstorm.json ✓ Fixed (removed cli-tools)
├── debug.json ✓ Fixed (removed cli-tools)
├── analyze.json ✓ Fixed (removed cli-tools)
├── issue.json ✓ Updated (slash-command only)
├── multi-cli-plan.json ✓ Fixed (removed cli-tools)
├── docs.json ✓ Updated (slash-command only)
├── full.json ✓ Fixed (removed cli-tools)
├── rapid-to-issue.json ✓ Updated (slash-command only)
├── brainstorm-to-issue.json ✓ Updated (slash-command only)
├── lite-lite-lite.json ✓ Updated (slash-command only)
├── coupled-enhanced.json ✗ Removed (experimental)
└── rapid-cli.json ✗ Removed (experimental)
```
## Result
All 17 templates now correctly use:
- ✅ `slash-command` type exclusively
- ✅ Flexible `mainprocess`/`async` modes
- ✅ Context passing via `contextHint`
- ✅ Minimum execution unit preservation
- ✅ Consistent execution patterns
## Next Steps
The meta-skill workflow coordinator can now:
1. Discover templates dynamically via Glob
2. Parse execution configuration from each step
3. Execute slash commands with mainprocess/async modes
4. Pass context between steps using contextHint
5. Maintain minimum execution unit integrity
6. (Future) Support cli-tools for custom analysis tasks

47
README.md
View File

@@ -1,6 +1,4 @@
<div align="center">
new line
new line
<!-- Animated Header -->
<img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=6,11,20&height=180&section=header&text=Claude%20Code%20Workflow&fontSize=42&fontColor=fff&animation=twinkling&fontAlignY=32&desc=Multi-Agent%20AI%20Development%20Framework&descAlignY=52&descSize=18"/>
@@ -96,8 +94,7 @@ ccw install -m Global
<div align="center">
<table>
<tr><th>Level</th><th>Command</th><th>Use Case</th></tr>
<tr><td><b>1</b></td><td><code>/workflow:lite-lite-lite</code></td><td>Quick fixes, config changes</td></tr>
<tr><td><b>2</b></td><td><code>/workflow:lite-plan</code></td><td>Clear single-module features</td></tr>
<tr><td><b>2</b></td><td><code>/workflow:lite-plan</code></td><td>Quick fixes, single-module features</td></tr>
<tr><td><b>2</b></td><td><code>/workflow:lite-fix</code></td><td>Bug diagnosis and fix</td></tr>
<tr><td><b>2</b></td><td><code>/workflow:multi-cli-plan</code></td><td>Multi-perspective analysis</td></tr>
<tr><td><b>3</b></td><td><code>/workflow:plan</code></td><td>Multi-module development</td></tr>
@@ -109,10 +106,7 @@ ccw install -m Global
### Workflow Examples
```bash
# Level 1: Instant execution
/workflow:lite-lite-lite "Fix typo in README"
# Level 2: Lightweight planning
# Level 2: Lightweight planning (recommended for most tasks)
/workflow:lite-plan "Add JWT authentication"
/workflow:lite-fix "User upload fails with 413 error"
@@ -358,7 +352,7 @@ ccw upgrade -a # Upgrade all installations
```
┌─────────────────────────────────────────────────────────────────┐
│ Main Workflow (4 Levels) │
│ ⚡ Level 1: lite-lite-lite (instant, no artifacts) │
│ ⚡ Level 1: lite-lite-lite (instant execution) │
│ 📝 Level 2: lite-plan / lite-fix / multi-cli-plan (→ execute) │
│ 📊 Level 3: plan / tdd-plan / test-fix-gen (session persist) │
│ 🧠 Level 4: brainstorm:auto-parallel → plan → execute │
@@ -395,6 +389,41 @@ ccw upgrade -a # Upgrade all installations
---
## 📦 Project Structure
```
Claude-Code-Workflow/
├── .claude/
│ ├── agents/ # 22 specialized agents (team-worker, cli-discuss, etc.)
│ ├── commands/ # Slash commands (5 categories)
│ │ ├── root/ # Root commands (/ccw, /ccw-coordinator)
│ │ ├── cli/ # CLI commands (cli-init, codex-review)
│ │ ├── issue/ # Issue management (plan, execute, queue)
│ │ ├── memory/ # Memory commands (prepare, style-skill-memory)
│ │ └── workflow/ # Workflow commands (brainstorm, plan, session)
│ └── skills/ # 37 modular skills
│ ├── review-code/ # Code review with rule-based analysis
│ ├── skill-tuning/ # Skill diagnosis and optimization
│ ├── skill-generator/ # Skill scaffolding and generation
│ ├── spec-generator/ # Product specification generation
│ ├── memory-*/ # Memory management skills
│ ├── workflow-*/ # Workflow orchestration skills
│ ├── team-*/ # Team coordination skills
│ └── ...
├── ccw/
│ ├── src/ # TypeScript source code
│ │ ├── commands/ # CLI command implementations
│ │ ├── core/ # Core services (a2ui, auth, hooks, routes)
│ │ ├── mcp-server/ # MCP server implementation
│ │ ├── tools/ # Tool implementations
│ │ └── utils/ # Utility functions
│ └── frontend/ # React frontend (Terminal Dashboard, Orchestrator)
├── codex-lens/ # Local semantic code search engine
└── docs/ # Documentation
```
---
## 🎼 Team Cadence Control (Beat Model)
The v2 team architecture introduces an **event-driven beat model** for efficient orchestration:

45
README_CN.md
View File

@@ -92,8 +92,7 @@ ccw install -m Global
<div align="center">
<table>
<tr><th>级别</th><th>命令</th><th>使用场景</th></tr>
<tr><td><b>1</b></td><td><code>/workflow:lite-lite-lite</code></td><td>快速修复、配置调整</td></tr>
<tr><td><b>2</b></td><td><code>/workflow:lite-plan</code></td><td>明确的单模块功能</td></tr>
<tr><td><b>2</b></td><td><code>/workflow:lite-plan</code></td><td>快速修复、单模块功能</td></tr>
<tr><td><b>2</b></td><td><code>/workflow:lite-fix</code></td><td>Bug 诊断修复</td></tr>
<tr><td><b>2</b></td><td><code>/workflow:multi-cli-plan</code></td><td>多视角分析</td></tr>
<tr><td><b>3</b></td><td><code>/workflow:plan</code></td><td>多模块开发</td></tr>
@@ -105,10 +104,7 @@ ccw install -m Global
### 工作流示例
```bash
# Level 1: 即时执行
/workflow:lite-lite-lite "修复 README 中的拼写错误"
# Level 2: 轻量规划
# Level 2: 轻量规划 (推荐用于大多数任务)
/workflow:lite-plan "添加 JWT 认证"
/workflow:lite-fix "用户上传失败返回 413 错误"
@@ -354,7 +350,7 @@ ccw upgrade -a # 升级所有安装
```
┌─────────────────────────────────────────────────────────────────┐
│ 主干工作流 (4 级) │
│ ⚡ Level 1: lite-lite-lite (即时执行，无产物) │
│ ⚡ Level 1: lite-lite-lite (即时执行) │
│ 📝 Level 2: lite-plan / lite-fix / multi-cli-plan (→ execute) │
│ 📊 Level 3: plan / tdd-plan / test-fix-gen (Session 持久化) │
│ 🧠 Level 4: brainstorm:auto-parallel → plan → execute │
@@ -391,6 +387,41 @@ ccw upgrade -a # 升级所有安装
---
## 📦 项目结构
```
Claude-Code-Workflow/
├── .claude/
│ ├── agents/ # 22 个专业化智能体 (team-worker, cli-discuss 等)
│ ├── commands/ # 斜杠命令（5 个类别）
│ │ ├── root/ # 根命令 (/ccw, /ccw-coordinator)
│ │ ├── cli/ # CLI 命令 (cli-init, codex-review)
│ │ ├── issue/ # Issue 管理 (plan, execute, queue)
│ │ ├── memory/ # 内存命令 (prepare, style-skill-memory)
│ │ └── workflow/ # 工作流命令 (brainstorm, plan, session)
│ └── skills/ # 37 个模块化技能
│ ├── review-code/ # 基于规则的代码审查
│ ├── skill-tuning/ # 技能诊断与优化
│ ├── skill-generator/ # 技能脚手架与生成
│ ├── spec-generator/ # 产品规格生成
│ ├── memory-*/ # 内存管理技能
│ ├── workflow-*/ # 工作流编排技能
│ ├── team-*/ # 团队协调技能
│ └── ...
├── ccw/
│ ├── src/ # TypeScript 源码
│ │ ├── commands/ # CLI 命令实现
│ │ ├── core/ # 核心服务 (a2ui, auth, hooks, routes)
│ │ ├── mcp-server/ # MCP 服务器实现
│ │ ├── tools/ # 工具实现
│ │ └── utils/ # 工具函数
│ └── frontend/ # React 前端（终端仪表板、编排器）
├── codex-lens/ # 本地语义代码搜索引擎
└── docs/ # 文档
```
---
## 🎼 团队节拍控制 (Beat Model)
v2 团队架构引入了**事件驱动的节拍模型**，实现高效编排：

276
TASK6_SUMMARY.md
View File

@@ -1,276 +0,0 @@
# Task T6 - Dashboard Customization with react-grid-layout
## Status: COMPLETE
All remaining work for T6 (Dashboard Customization) has been successfully completed.
## Implementation Summary
### Files Modified
#### 1. DashboardGridContainer.tsx
- **Location**: `ccw/frontend/src/components/dashboard/DashboardGridContainer.tsx`
- **Changes**: Refactored from static Tailwind grid to responsive react-grid-layout
- **Features**:
- Uses `Responsive` component from react-grid-layout
- Integrated with `useUserDashboardLayout` hook for layout persistence
- Configurable breakpoints: lg (1024px), md (768px), sm (640px)
- Configurable columns: lg (12), md (6), sm (2)
- Row height: 60px
- Drag-drop enabled with `.drag-handle` class support
- Layout changes automatically debounced and saved to localStorage + Zustand
#### 2. DashboardHeader.tsx
- **Location**: `ccw/frontend/src/components/dashboard/DashboardHeader.tsx`
- **Changes**: Added layout reset button
- **New Props**:
- `onResetLayout?: () => void` - Callback for layout reset action
- **Features**:
- Reset button with RotateCcw icon
- Button positioned before refresh button
- Conditional rendering based on onResetLayout prop
- i18n support with "common.actions.resetLayout" key
#### 3. i18n Locale Files
Updated both English and Chinese translations:
**English (ccw/frontend/src/locales/en/common.json)**:
- Added `actions.resetLayout`: "Reset Layout"
**English (ccw/frontend/src/locales/en/home.json)**:
- Added `widgets` section with:
- `workflowStatus`: "Workflow Status"
- `activity`: "Activity Timeline"
- `taskTypes`: "Task Types"
**Chinese (ccw/frontend/src/locales/zh/common.json)**:
- Added `actions.resetLayout`: "重置布局"
**Chinese (ccw/frontend/src/locales/zh/home.json)**:
- Added `widgets` section with:
- `workflowStatus`: "工作流状态"
- `activity`: "活动时间线"
- `taskTypes`: "任务类型"
### Files Created
#### 1. DetailedStatsWidget.tsx
- **Location**: `ccw/frontend/src/components/dashboard/widgets/DetailedStatsWidget.tsx`
- **Purpose**: Wraps 6 stat cards for dashboard display
- **Features**:
- Displays: Active Sessions, Total Tasks, Completed, Pending, Failed, Today's Activity
- Uses `useDashboardStats` hook for data fetching
- Loading skeletons support
- Responsive grid layout (2 cols on mobile, 3 on tablet, 6 on desktop)
- Wrapped in Card component
#### 2. RecentSessionsWidget.tsx
- **Location**: `ccw/frontend/src/components/dashboard/widgets/RecentSessionsWidget.tsx`
- **Purpose**: Displays recent active workflow sessions
- **Features**:
- Fetches recent sessions using `useSessions` hook
- Configurable max sessions (default: 6)
- Sorts by creation date (newest first)
- Session cards with navigation to detail page
- "View All" button for full sessions page
- Empty state with helpful message
- Loading skeletons support
#### 3. WorkflowStatusPieChartWidget.tsx
- **Location**: `ccw/frontend/src/components/dashboard/widgets/WorkflowStatusPieChartWidget.tsx`
- **Purpose**: Placeholder widget for workflow status pie chart (T5 dependency)
- **Features**:
- Displays placeholder with PieChart icon
- Message: "Chart available after T5 completion"
- Ready for chart implementation after T5
#### 4. ActivityLineChartWidget.tsx
- **Location**: `ccw/frontend/src/components/dashboard/widgets/ActivityLineChartWidget.tsx`
- **Purpose**: Placeholder widget for activity trend chart (T5 dependency)
- **Features**:
- Displays placeholder with TrendingUp icon
- Message: "Chart available after T5 completion"
- Ready for chart implementation after T5
#### 5. TaskTypeBarChartWidget.tsx
- **Location**: `ccw/frontend/src/components/dashboard/widgets/TaskTypeBarChartWidget.tsx`
- **Purpose**: Placeholder widget for task type distribution chart (T5 dependency)
- **Features**:
- Displays placeholder with BarChart3 icon
- Message: "Chart available after T5 completion"
- Ready for chart implementation after T5
#### 6. widgets/index.ts
- **Location**: `ccw/frontend/src/components/dashboard/widgets/index.ts`
- **Purpose**: Central export point for all widget components
- **Exports**: All 5 widget components with their TypeScript props
## Architecture Overview
### Layout Persistence Flow
```
User drags/resizes widget
↓
ResponsiveGridLayout fires onLayoutChange
↓
DashboardGridContainer calls updateLayouts()
↓
useUserDashboardLayout debounces (1 second)
↓
Zustand store updated → localStorage persisted
↓
Layout restored on page reload
```
### Responsive Breakpoints
| Breakpoint | Width | Columns | Use Case |
|-----------|----------|---------|----------|
| **lg** | ≥ 1024px | 12 | Desktop |
| **md** | ≥ 768px | 6 | Tablet |
| **sm** | ≥ 640px | 2 | Mobile |
### Widget Grid Positions (Default Layout)
**Large screens (lg)**:
```
+--------------------------------+
| DetailedStatsWidget (12 cols) |
+--------+--------+--------+------+
| Recent | Workflow | Activity|Task|
|Sessions| Status | Chart |Type|
| (6x4) | (6x4) | (7x4) |(5x4|
+--------+--------+--------+------+
```
**Medium screens (md)**:
```
+-------------------+
| DetailedStatsWidget|
+----------+--------+
| RecentSessions (6) |
+-------------------+
| WorkflowStatus (6) |
+-------------------+
| Activity (6) |
+-------------------+
| TaskTypes (6) |
+-------------------+
```
**Small screens (sm)**:
```
+-----------+
|DetailStats|
+-----------+
| Recent |
+-----------+
| Workflow |
+-----------+
| Activity |
+-----------+
| TaskTypes |
+-----------+
```
## Dependencies
### Already Installed
- `react-grid-layout@1.4.4` - Draggable grid layout
- `@types/react-grid-layout@1.3.5` - TypeScript definitions
- `react-resizable` - Resizing support
### Existing Integrations
- `useUserDashboardLayout` hook for state management
- `useAppStore` (Zustand) for persistence
- `useDashboardStats` hook for statistics data
- `useSessions` hook for session data
## Testing Instructions
### Manual Testing Checklist
- [ ] Dashboard loads without errors
- [ ] All 5 widgets render properly
- [ ] Widgets are draggable (move widgets around)
- [ ] Widgets are resizable (drag widget edges)
- [ ] Layout persists after page reload
- [ ] Reset Layout button resets to default positions
- [ ] Responsive behavior works on mobile (shrink browser window)
- [ ] i18n translations display correctly
- [ ] Stat cards show loading skeletons while fetching
- [ ] Recent sessions list updates with fresh data
### TypeScript Verification
All new components pass TypeScript compilation with zero errors:
```bash
npx tsc --noEmit # No errors in dashboard/widgets directory
npm run build # Builds successfully
```
## Integration Points for Future Tasks
### For T5 (Charts Implementation)
The 3 chart placeholder widgets are ready to be replaced with actual chart components:
1. **WorkflowStatusPieChartWidget** - Implement pie chart showing workflow status distribution
2. **ActivityLineChartWidget** - Implement line chart showing activity trends
3. **TaskTypeBarChartWidget** - Implement bar chart showing task type distribution
Replace the placeholder Card content with Recharts (or preferred charting library) components.
### For HomePage Update
The HomePage component can be refactored to use the new widgets:
```typescript
<DashboardGridContainer>
<div key="stats" data-grid={{ i: 'detailed-stats', ... }}>
<DetailedStatsWidget />
</div>
<div key="sessions" data-grid={{ i: 'recent-sessions', ... }}>
<RecentSessionsWidget />
</div>
{/* Add chart widgets here */}
</DashboardGridContainer>
```
## Done When Checklist
- [x] CSS imports added to main.tsx
- [x] appStore extended with dashboardLayout state
- [x] DashboardGridContainer uses ResponsiveGridLayout
- [x] 5 widget wrapper components created
- [x] Layout reset button added to DashboardHeader
- [x] Drag-drop interactions functional
- [x] Layout persists after page reload
- [x] Zero TypeScript errors in new components
- [x] i18n keys added for all new UI elements
- [x] All components documented with JSDoc
## Files Summary
| File Path | Type | Status |
|-----------|------|--------|
| `DashboardGridContainer.tsx` | Modified | Refactored to use react-grid-layout |
| `DashboardHeader.tsx` | Modified | Added reset layout button |
| `defaultLayouts.ts` | Existing | No changes needed |
| `DetailedStatsWidget.tsx` | Created | Stat cards wrapper |
| `RecentSessionsWidget.tsx` | Created | Sessions list wrapper |
| `WorkflowStatusPieChartWidget.tsx` | Created | Chart placeholder (T5 dependency) |
| `ActivityLineChartWidget.tsx` | Created | Chart placeholder (T5 dependency) |
| `TaskTypeBarChartWidget.tsx` | Created | Chart placeholder (T5 dependency) |
| `widgets/index.ts` | Created | Export index |
| `en/common.json` | Modified | Added resetLayout translation |
| `zh/common.json` | Modified | Added resetLayout translation |
| `en/home.json` | Modified | Added widgets translations |
| `zh/home.json` | Modified | Added widgets translations |
## Build Output
```
✓ TypeScript compilation successful
✓ No errors in dashboard/widgets components
✓ Vite build completes successfully
```
## Next Steps (T5)
1. Implement actual charts using Recharts or similar
2. Replace placeholder widgets with functional chart components
3. Add chart data fetching hooks
4. Update HomePage to use new widget-based layout
5. Test responsive behavior on all screen sizes

339
UNIFIED_EXECUTE_SUMMARY.md
View File

@@ -1,339 +0,0 @@
# Unified-Execute-With-File: Implementation Summary
## 🎉 Project Complete
Both Claude and Codex versions of the universal execution engine are now ready for production use.
---
## 📦 Deliverables
### 1. Claude CLI Command (Optimized)
- **Location**: `.claude/commands/workflow/unified-execute-with-file.md`
- **Size**: 807 lines (25 KB)
- **Status**: ✅ Production-ready
- **Optimization**: 26% reduction from original 1,094 lines
**Usage**:
```bash
/workflow:unified-execute-with-file
/workflow:unified-execute-with-file -p .workflow/IMPL_PLAN.md -m parallel
/workflow:unified-execute-with-file -y "auth module"
```
### 2. Codex Prompt (Format-Adapted)
- **Location**: `.codex/prompts/unified-execute-with-file.md`
- **Size**: 722 lines (22 KB)
- **Status**: ✅ Production-ready
- **Savings**: 85 fewer lines than Claude version
**Usage**:
```
PLAN_PATH=".workflow/IMPL_PLAN.md"
EXECUTION_MODE="parallel"
AUTO_CONFIRM="yes"
EXECUTION_CONTEXT="auth module"
```
### 3. Comparison Guide
- **Location**: `.codex/prompts/UNIFIED_EXECUTE_COMPARISON.md`
- **Size**: 205 lines (5.5 KB)
- **Purpose**: Parameter mapping, format differences, migration paths
---
## ✨ Core Features (Both Versions)
### Plan Parsing
- ✅ IMPL_PLAN.md (from `/workflow:plan`)
- ✅ brainstorm synthesis.json (from `/workflow:brainstorm-with-file`)
- ✅ analysis conclusions.json (from `/workflow:analyze-with-file`)
- ✅ debug recommendations (from `/workflow:debug-with-file`)
- ✅ task JSON files (from `/workflow:lite-plan`)
### Multi-Agent Support
- ✅ code-developer (implementation)
- ✅ tdd-developer (test-driven development)
- ✅ test-fix-agent (testing & fixes)
- ✅ doc-generator (documentation)
- ✅ cli-execution-agent (CLI-based)
- ✅ universal-executor (fallback)
### Execution Strategy
- ✅ Dependency resolution (topological sort)
- ✅ Parallel execution (max 3 tasks/wave)
- ✅ File conflict detection
- ✅ Sequential fallback for conflicts
- ✅ Wave-based grouping
### Progress Tracking
- ✅ execution-events.md: Single source of truth
- ✅ Append-only unified execution log
- ✅ Agent reads all previous executions
- ✅ Knowledge chain between agents
- ✅ Human-readable + machine-parseable
### Error Handling
- ✅ Automatic retry mechanism
- ✅ User-interactive retry/skip/abort
- ✅ Dependency-aware task skipping
- ✅ Detailed error recovery notes
### Session Management
- ✅ Incremental execution (no re-execution)
- ✅ Resumable from failure points
- ✅ Cross-version compatibility (Claude ↔ Codex)
- ✅ Persistent session tracking
---
## 📂 Session Structure
Both versions create identical session structure:
```
.workflow/.execution/{executionId}/
├── execution.md # Execution plan and status
│ # - Task table, dependency graph
│ # - Execution timeline, statistics
│
└── execution-events.md # SINGLE SOURCE OF TRUTH
# - All agent executions (chronological)
# - Success/failure with details
# - Artifacts and notes for next agent
```
**Generated files**:
- Created at project paths: `src/types/auth.ts` (not `artifacts/src/types/auth.ts`)
- execution-events.md records actual paths for reference
---
## 🚀 Execution Flow
```
1. Load & Parse Plan
├─ Detect plan format
├─ Extract tasks
└─ Validate dependencies
2. Session Setup
├─ Create execution folder
├─ Initialize execution.md
└─ Initialize execution-events.md
3. Pre-Execution Validation
├─ Check task feasibility
├─ Detect dependency cycles
└─ User confirmation (unless auto-confirm)
4. Execution Orchestration
├─ Topological sort
├─ Group into waves (parallel-safe)
├─ Execute wave by wave
└─ Track progress in real-time
5. Progress Logging
├─ Each agent reads all previous executions
├─ Agent executes with full context
├─ Agent appends event (success/failure)
└─ Next agent inherits complete history
6. Completion
├─ Collect statistics
├─ Update execution.md
├─ execution-events.md complete
└─ Offer follow-up options
```
---
## 📊 Statistics
| Metric | Claude | Codex | Combined |
|--------|--------|-------|----------|
| **Lines** | 807 | 722 | 1,529 |
| **Size (KB)** | 25 | 22 | 47 |
| **Phases** | 4 | 4 | 4 |
| **Agent types** | 6+ | 6+ | 6+ |
| **Max parallel tasks** | 3 | 3 | 3 |
---
## 🔄 Cross-Version Compatibility
**Migration is seamless**:
| Scenario | Status |
|----------|--------|
| Start Claude → Resume Codex | ✅ Compatible |
| Start Codex → Resume Claude | ✅ Compatible |
| Mix both in workflows | ✅ Compatible |
| execution-events.md format | ✅ Identical |
| Session ID structure | ✅ Identical |
| Artifact locations | ✅ Identical |
| Agent selection | ✅ Identical |
---
## 📈 Implementation Progress
### Phase 1: Claude Optimization
- Initial version: 1,094 lines
- Optimizations:
- Consolidated Phase 3 (205 → 30 lines)
- Merged error handling (90 → 40 lines)
- Removed duplicate template
- Preserved all technical specifications
- Result: 807 lines (-26%)
### Phase 2: Codex Adaptation
- Format conversion: YAML CLI → Variable substitution
- Streamlined Phase documentation
- Maintained all core logic
- Result: 722 lines (85 fewer than Claude)
### Phase 3: Documentation
- Created comparison guide (205 lines)
- Parameter mapping matrix
- Format differences analysis
- Migration paths documented
---
## 📝 Git Commits
```
0fe8c18a docs: Add comparison guide between Claude and Codex versions
0086413f feat: Add Codex unified-execute-with-file prompt
8ff698ae refactor: Optimize unified-execute-with-file command documentation
```
---
## 🎯 Design Principles
1. **Single Source of Truth**
- execution-events.md as unified execution log
- No redundant tracking systems
2. **Knowledge Chain**
- Each agent reads all previous executions
- Context automatically inherited
- Full visibility into dependencies
3. **Format Agnostic**
- Accepts any planning/brainstorm/analysis output
- Smart format detection
- Extensible parser architecture
4. **Incremental Progress**
- No re-execution of completed tasks
- Resume from failure points
- Session persistence
5. **Safety & Visibility**
- Append-only event logging
- No data loss on failure
- Detailed error recovery
- Complete execution timeline
---
## 🔧 When to Use Each Version
### Use Claude Version When:
- Running in Claude Code CLI environment
- Need direct tool integration (TodoWrite, Task, AskUserQuestion)
- Prefer CLI flag syntax (`-y`, `-p`, `-m`)
- Building multi-command workflows
- Want full workflow system integration
### Use Codex Version When:
- Executing directly in Codex
- Prefer variable substitution format
- Need standalone execution
- Integrating with Codex command chains
- Want simpler parameter interface
---
## ✅ Quality Assurance
- ✅ Both versions functionally equivalent
- ✅ Dependency management validated
- ✅ Parallel execution tested
- ✅ Error handling verified
- ✅ Event logging format documented
- ✅ Cross-version compatibility confirmed
- ✅ Parameter mapping complete
- ✅ Session structure identical
---
## 📚 Documentation
**Main files**:
1. `.claude/commands/workflow/unified-execute-with-file.md` (807 lines)
- Complete Claude CLI command specification
- Full implementation details
- Phase-by-phase breakdown
2. `.codex/prompts/unified-execute-with-file.md` (722 lines)
- Codex-adapted prompt
- Format substitution
- Streamlined logic
3. `.codex/prompts/UNIFIED_EXECUTE_COMPARISON.md` (205 lines)
- Format differences
- Functional equivalence matrix
- Parameter mapping
- Usage recommendations
- Migration paths
---
## 🎓 Integration Points
**Input formats consumed**:
- IMPL_PLAN.md (from `/workflow:plan`)
- brainstorm synthesis.json (from `/workflow:brainstorm-with-file`)
- analysis conclusions.json (from `/workflow:analyze-with-file`)
- debug recommendations (from `/workflow:debug-with-file`)
- task JSON files (from `/workflow:lite-plan`)
**Output formats produced**:
- execution.md: Plan overview + execution timeline
- execution-events.md: Complete execution record
- Generated files at project paths
**Agent coordination**:
- code-developer, tdd-developer, test-fix-agent, doc-generator, cli-execution-agent, universal-executor
---
## 🚀 Ready for Production
Both implementations are complete, tested, and documented:
- **Claude CLI**: `/workflow:unified-execute-with-file`
- **Codex Prompt**: `unified-execute-with-file`
- **Comparison**: `UNIFIED_EXECUTE_COMPARISON.md`
Start using immediately or integrate into existing workflows.
---
## 📞 Next Steps
1. **Use Claude version** for workflow system integration
2. **Use Codex version** for direct Codex execution
3. **Refer to comparison guide** for format mapping
4. **Mix versions** for multi-tool workflows
5. **Extend parsers** for new plan formats as needed
---
**Project Status**: ✅ **COMPLETE**
All deliverables ready for production use.

1721
WORKFLOW_GUIDE.md
View File

File diff suppressed because it is too large Load Diff

1944
WORKFLOW_GUIDE_CN.md
View File

File diff suppressed because it is too large Load Diff

133
ccw-contentPattern-optimization-summary.md
View File

@@ -1,133 +0,0 @@
# CCW MCP read_file contentPattern 优化总结
## 优化背景
基于分析会话 ANL-ccw-mcp-file-tools-2025-02-08 的结论，对 `read_file` 工具的 `contentPattern` 参数进行了安全性和易用性优化。
## 实施的优化
### 1. 空字符串行为优化
- **之前**: 空字符串 `""` 返回错误
- **之后**: 空字符串 `""` 返回全文（设计行为）
- **实现**: `findMatches` 返回 `null` 表示"匹配所有内容"
### 2. 危险模式安全回退
- **之前**: 危险模式（如 `x*`）被拦截，返回空结果
- **之后**: 危险模式自动回退到返回全文（安全回退）
- **实现**: 检测到零宽度模式时返回 `null`，而不是 `[]`
### 3. 增强的错误处理
- 模式长度限制（1000 字符）→ 超限返回全文
- 无效正则表达式 → 返回全文而不是报错
- 迭代计数器保护（最大 1000 次迭代）
- 位置前进检查（防止 `regex.exec()` 卡住）
- 结果去重（使用 `Set` 防止重复行）
## 最终行为矩阵
| contentPattern 值 | 行为 | 返回值 | 文件是否包含 |
|-------------------|------|--------|--------------|
| `""` (空字符串) | 匹配所有内容 | `null` | ✅ 包含 |
| `"x*"` (危险模式) | 安全回退 | `null` | ✅ 包含 |
| `"CCW"` (正常匹配) | 正常过滤 | `["匹配行"]` | ✅ 包含 |
| `"NOMATCH"` (无匹配) | 跳过文件 | `[]` | ❌ 不包含 |
## 代码变更
### findMatches 函数签名
```typescript
// 之前
function findMatches(content: string, pattern: string): string[]
// 之后
function findMatches(content: string, pattern: string): string[] | null
```
### 返回值语义
- `null` → 匹配所有内容（不进行过滤）
- `[]` → 无匹配（跳过文件）
- `[string]` → 有匹配（返回匹配行）
### Schema 更新
```typescript
contentPattern: {
type: 'string',
description: 'Regex pattern to search within file content. Empty string "" returns all content. Dangerous patterns (e.g., "x*") automatically fall back to returning all content for safety.',
}
```
## 验证测试
运行 `node test-final-verification.js` 验证所有行为：
```bash
node test-final-verification.js
```
预期输出：
```
✅ 所有测试通过！
行为总结:
空字符串 "" → 返回全文（设计行为）
危险模式 "x*" → 返回全文（安全回退）
正常模式 "CCW" → 正常过滤
无匹配 "NOMATCH" → 跳过文件
```
## 相关文件
- `ccw/src/tools/read-file.ts` - 主要实现
- `test-final-verification.js` - 最终验证测试
- `test-mcp-tools.mjs` - MCP 工具参数验证
## 安全特性
1. **零宽度模式检测**: 在空字符串上双重 `exec` 测试
2. **迭代计数器**: 防止 ReDoS 攻击
3. **位置前进检查**: `match.index === lastIndex` 时强制前进
4. **结果去重**: 使用 `Set` 防止重复匹配
## 用户反馈处理
用户关键反馈：
> "空字符串 │ "" │ 输出错误并拦截 │ ✅ 这样不应该输出错误吧， 应该默认输出全部内容 read file"
实施结果：
- ✅ 空字符串返回全文（不是错误）
- ✅ 危险模式返回全文（不是拦截）
- ✅ 方法说明已更新
## 构建和测试
```bash
# 构建
npm run build
# 测试 MCP 工具
node test-mcp-tools.mjs
# 测试 contentPattern 行为
node test-final-verification.js
# 通过 CLI 测试
ccw tool exec read_file '{"paths":"README.md","contentPattern":"x*"}'
```
## 完成状态
- ✅ P0 任务 1: read_file offset/limit 多文件验证
- ✅ P0 任务 2: edit_file discriminatedUnion 重构
- ✅ contentPattern 安全性优化
- ✅ 空字符串行为修正
- ✅ 危险模式安全回退
- ✅ 方法说明更新
- ✅ 验证测试通过
## 优化日期
2025-02-08
## 相关分析会话
ANL-ccw-mcp-file-tools-2025-02-08

14
ccw/frontend/src/components/a2ui/A2UIPopupCard.tsx
View File

@@ -329,11 +329,11 @@ function SinglePagePopup({ surface, onClose }: A2UIPopupCardProps) {
'data-[state=open]:duration-300 data-[state=closed]:duration-200'
)}
onInteractOutside={(e) => {
// Prevent closing when clicking outside
// Prevent closing when clicking outside - only cancel button can close
e.preventDefault();
}}
onEscapeKeyDown={(e) => {
// Prevent closing with ESC key
// Prevent closing with ESC key - only cancel button can close
e.preventDefault();
}}
>
@@ -574,8 +574,14 @@ function MultiPagePopup({ surface, onClose }: A2UIPopupCardProps) {
'data-[state=open]:zoom-in-95 data-[state=closed]:zoom-out-95',
'data-[state=open]:duration-300 data-[state=closed]:duration-200'
)}
onInteractOutside={(e) => e.preventDefault()}
onEscapeKeyDown={(e) => e.preventDefault()}
onInteractOutside={(e) => {
// Prevent closing when clicking outside - only cancel button can close
e.preventDefault();
}}
onEscapeKeyDown={(e) => {
// Prevent closing with ESC key - only cancel button can close
e.preventDefault();
}}
>
{/* Header with current page title */}
<DialogHeader className="space-y-2 pb-4">

5
ccw/frontend/src/components/terminal-dashboard/QueueListColumn.tsx
View File

@@ -199,7 +199,7 @@ function SchedulerBar() {
{/* Progress + Concurrency */}
{isActive && (
<span className="text-[10px] text-muted-foreground">
{progress}% | {concurrency}/{config.maxConcurrentSessions}
{progress}% | {concurrency}/{config?.maxConcurrentSessions ?? 2}
</span>
)}
@@ -285,6 +285,9 @@ export function QueueListColumn() {
const associationChain = useIssueQueueIntegrationStore(selectAssociationChain);
const buildAssociationChain = useIssueQueueIntegrationStore((s) => s.buildAssociationChain);
// NOTE: loadInitialState is called from a parent component or app initialization
// to avoid infinite loop issues with Zustand selectors
const sortedItems = useMemo(
() => [...items].sort((a, b) => a.execution_order - b.execution_order),
[items]

8
ccw/frontend/src/components/terminal-dashboard/QueuePanel.tsx
View File

@@ -7,7 +7,7 @@
// Integrates with issueQueueIntegrationStore for association chain.
// Note: Scheduler controls are in the standalone SchedulerPanel.
import { useState, useMemo, useCallback, memo } from 'react';
import { useState, useMemo, useCallback, memo, useEffect } from 'react';
import { useIntl } from 'react-intl';
import {
ListChecks,
@@ -193,6 +193,12 @@ function QueueTabContent(_props: { embedded?: boolean }) {
// Scheduler store data
const schedulerItems = useQueueSchedulerStore(selectQueueItems);
const schedulerStatus = useQueueSchedulerStore(selectQueueSchedulerStatus);
const loadInitialState = useQueueSchedulerStore((s) => s.loadInitialState);
// Load scheduler state on mount
useEffect(() => {
loadInitialState();
}, [loadInitialState]);
// Legacy API data (fallback)
const queueQuery = useIssueQueue();

6
ccw/frontend/src/components/terminal-dashboard/SchedulerPanel.tsx
View File

@@ -82,7 +82,7 @@ export function SchedulerPanel() {
[updateConfig]
);
const sessionEntries = Object.entries(sessionPool);
const sessionEntries = Object.entries(sessionPool ?? {});
return (
<div className="flex flex-col h-full">
@@ -102,7 +102,7 @@ export function SchedulerPanel() {
})}
</span>
<span className="text-xs text-muted-foreground ml-auto tabular-nums">
{concurrency}/{config.maxConcurrentSessions}
{concurrency}/{config?.maxConcurrentSessions ?? 2}
</span>
</div>
@@ -188,7 +188,7 @@ export function SchedulerPanel() {
type="number"
min={1}
max={10}
value={config.maxConcurrentSessions}
value={config?.maxConcurrentSessions ?? 2}
onChange={handleConcurrencyChange}
className="w-14 h-6 text-xs text-center rounded border border-border bg-background px-1"
/>

1
ccw/frontend/src/pages/TerminalDashboardPage.tsx
View File

@@ -28,6 +28,7 @@ import { FileSidebarPanel } from '@/components/terminal-dashboard/FileSidebarPan
import { useWorkflowStore, selectProjectPath } from '@/stores/workflowStore';
import { useAppStore, selectIsImmersiveMode } from '@/stores/appStore';
import { useConfigStore } from '@/stores/configStore';
import { useQueueSchedulerStore } from '@/stores/queueSchedulerStore';
// ========== Main Page Component ==========

42
ccw/frontend/src/stores/queueSchedulerStore.ts
View File

@@ -305,11 +305,11 @@ const EMPTY_ITEMS: QueueItem[] = [];
/** Select current scheduler status */
export const selectQueueSchedulerStatus = (state: QueueSchedulerStore): QueueSchedulerStatus =>
state.status;
state?.status ?? 'idle';
/** Select all queue items */
export const selectQueueItems = (state: QueueSchedulerStore): QueueItem[] =>
state.items;
state?.items ?? [];
/**
* Select items that are ready to execute (status 'queued' or 'pending').
@@ -346,9 +346,11 @@ export const selectExecutingItems = (state: QueueSchedulerStore): QueueItem[] =>
* Returns 0 when there are no items.
*/
export const selectSchedulerProgress = (state: QueueSchedulerStore): number => {
const total = state.items.length;
if (!state) return 0;
const items = state.items ?? [];
const total = items.length;
if (total === 0) return 0;
const terminal = state.items.filter(
const terminal = items.filter(
(item) => item.status === 'completed' || item.status === 'failed'
).length;
return Math.round((terminal / total) * 100);
@@ -369,3 +371,35 @@ export const selectCurrentConcurrency = (state: QueueSchedulerStore): number =>
/** Select scheduler error */
export const selectSchedulerError = (state: QueueSchedulerStore): string | null =>
state.error;
// ========== Auto-initialization ==========
/**
* Flag to prevent multiple initialization calls.
* This is set outside the store to avoid triggering re-renders.
*/
let schedulerInitialized = false;
/**
* Initialize the queue scheduler state once.
* Safe to call multiple times - will only initialize once.
*/
export function initializeScheduler(): void {
if (!schedulerInitialized) {
schedulerInitialized = true;
useQueueSchedulerStore.getState().loadInitialState().catch((error) => {
console.error('[QueueScheduler] Failed to initialize:', error);
// Reset flag on error to allow retry
schedulerInitialized = false;
});
}
}
// Auto-initialize when this module is imported (deferred to next tick)
if (typeof window !== 'undefined') {
// Defer initialization to avoid blocking initial render
// and to ensure all store subscriptions are set up first
setTimeout(() => {
initializeScheduler();
}, 100);
}

31
ccw/src/core/a2ui/A2UIWebSocketHandler.ts
View File

@@ -405,7 +405,7 @@ export class A2UIWebSocketHandler {
case 'submit': {
const otherText = this.inputValues.get(`__other__:${questionId}`);
// Check if this is a single-select or multi-select
// Check if this is a single-select
const singleSelection = this.singleSelectSelections.get(questionId);
if (singleSelection !== undefined) {
// Resolve __other__ to actual text input
@@ -413,14 +413,27 @@ export class A2UIWebSocketHandler {
this.inputValues.delete(`__other__:${questionId}`);
return resolveAndCleanup({ questionId, value, cancelled: false });
}
// Multi-select submit
const multiSelected = this.multiSelectSelections.get(questionId) ?? new Set<string>();
// Resolve __other__ in multi-select: replace with actual text
const values = Array.from(multiSelected).map(v =>
v === '__other__' && otherText ? otherText : v
);
this.inputValues.delete(`__other__:${questionId}`);
return resolveAndCleanup({ questionId, value: values, cancelled: false });
// Check if this is a multi-select
const multiSelected = this.multiSelectSelections.get(questionId);
if (multiSelected !== undefined && multiSelected.size > 0) {
// Resolve __other__ in multi-select: replace with actual text
const values = Array.from(multiSelected).map(v =>
v === '__other__' && otherText ? otherText : v
);
this.inputValues.delete(`__other__:${questionId}`);
return resolveAndCleanup({ questionId, value: values, cancelled: false });
}
// Check if this is a text input (no selections, but has input value)
const inputValue = this.inputValues.get(questionId);
if (inputValue !== undefined) {
this.inputValues.delete(questionId);
return resolveAndCleanup({ questionId, value: inputValue, cancelled: false });
}
// No value found - submit empty string
return resolveAndCleanup({ questionId, value: '', cancelled: false });
}
case 'input-change': {

14
ccw/src/core/routes/hooks-routes.ts
View File

@@ -343,7 +343,19 @@ export async function handleHooksRoutes(ctx: HooksRouteContext): Promise<boolean
const initState = extraData.initialState as Record<string, unknown>;
const questionId = initState.questionId as string | undefined;
const questionType = initState.questionType as string | undefined;
if (questionId && questionType === 'select') {
// Handle multi-question surfaces (multi-page): initialize tracking for each page
if (questionType === 'multi-question' && Array.isArray(initState.pages)) {
const pages = initState.pages as Array<{ questionId: string; type: string }>;
for (const page of pages) {
if (page.type === 'multi-select') {
a2uiWebSocketHandler.initMultiSelect(page.questionId);
} else if (page.type === 'select') {
a2uiWebSocketHandler.initSingleSelect(page.questionId);
}
}
} else if (questionId && questionType === 'select') {
// Single-question surface: initialize based on question type
a2uiWebSocketHandler.initSingleSelect(questionId);
} else if (questionId && questionType === 'multi-select') {
a2uiWebSocketHandler.initMultiSelect(questionId);

27
ccw/src/tools/ask-question.ts
View File

@@ -409,12 +409,37 @@ function generateQuestionSurface(question: Question, surfaceId: string, timeoutM
component: {
TextField: {
value: question.defaultValue ? { literalString: String(question.defaultValue) } : undefined,
onChange: { actionId: 'answer', parameters: { questionId: question.id } },
onChange: { actionId: 'input-change', parameters: { questionId: question.id } },
placeholder: question.placeholder || 'Enter your answer',
type: 'text',
},
},
});
// Add Submit/Cancel buttons for input type
components.push({
id: 'submit-btn',
component: {
Button: {
onClick: { actionId: 'submit', parameters: { questionId: question.id } },
content: {
Text: { text: { literalString: 'Submit' } },
},
variant: 'primary',
},
},
});
components.push({
id: 'cancel-btn',
component: {
Button: {
onClick: { actionId: 'cancel', parameters: { questionId: question.id } },
content: {
Text: { text: { literalString: 'Cancel' } },
},
variant: 'secondary',
},
},
});
break;
}
}

62
codex_prompt.md
View File

@@ -1,62 +0,0 @@
# Custom Prompts
<DocsTip>
Custom prompts are deprecated. Use [skills](https://developers.openai.com/codex/skills) for reusable
instructions that Codex can invoke explicitly or implicitly.
</DocsTip>
Custom prompts (deprecated) let you turn Markdown files into reusable prompts that you can invoke as slash commands in both the Codex CLI and the Codex IDE extension.
Custom prompts require explicit invocation and live in your local Codex home directory (for example, `~/.codex`), so they're not shared through your repository. If you want to share a prompt (or want Codex to implicitly invoke it), [use skills](https://developers.openai.com/codex/skills).
1. Create the prompts directory:
```bash
mkdir -p ~/.codex/prompts
```
2. Create `~/.codex/prompts/draftpr.md` with reusable guidance:
```markdown
---
description: Prep a branch, commit, and open a draft PR
argument-hint: [FILES=<paths>] [PR_TITLE="<title>"]
---
Create a branch named `dev/<feature_name>` for this work.
If files are specified, stage them first: $FILES.
Commit the staged changes with a clear message.
Open a draft PR on the same branch. Use $PR_TITLE when supplied; otherwise write a concise summary yourself.
```
3. Restart Codex so it loads the new prompt (restart your CLI session, and reload the IDE extension if you are using it).
Expected: Typing `/prompts:draftpr` in the slash command menu shows your custom command with the description from the front matter and hints that files and a PR title are optional.
## Add metadata and arguments
Codex reads prompt metadata and resolves placeholders the next time the session starts.
- **Description:** Shown under the command name in the popup. Set it in YAML front matter as `description:`.
- **Argument hint:** Document expected parameters with `argument-hint: KEY=<value>`.
- **Positional placeholders:** `$1` through `$9` expand from space-separated arguments you provide after the command. `$ARGUMENTS` includes them all.
- **Named placeholders:** Use uppercase names like `$FILE` or `$TICKET_ID` and supply values as `KEY=value`. Quote values with spaces (for example, `FOCUS="loading state"`).
- **Literal dollar signs:** Write `$$` to emit a single `$` in the expanded prompt.
After editing prompt files, restart Codex or open a new chat so the updates load. Codex ignores non-Markdown files in the prompts directory.
## Invoke and manage custom commands
1. In Codex (CLI or IDE extension), type `/` to open the slash command menu.
2. Enter `prompts:` or the prompt name, for example `/prompts:draftpr`.
3. Supply required arguments:
```text
/prompts:draftpr FILES="src/pages/index.astro src/lib/api.ts" PR_TITLE="Add hero animation"
```
4. Press Enter to send the expanded instructions (skip either argument when you don't need it).
Expected: Codex expands the content of `draftpr.md`, replacing placeholders with the arguments you supplied, then sends the result as a message.
Manage prompts by editing or deleting files under `~/.codex/prompts/`. Codex scans only the top-level Markdown files in that folder, so place each custom prompt directly under `~/.codex/prompts/` rather than in subdirectories.

234
contentPattern-library-options.md
View File

@@ -1,234 +0,0 @@
# contentPattern 实现方案对比
## 当前实现
```typescript
// 手动实现的正则搜索，存在无限循环风险
function findMatches(content: string, pattern: string): string[] {
const regex = new RegExp(pattern, 'gm');
// ... 手动处理，容易出错
}
```
**问题**：
- 🔴 无限循环风险（空字符串、零宽匹配）
- 🔴 ReDoS 攻击风险（灾难性回溯）
- 🟡 需要手动维护安全检查
- 🟡 测试覆盖成本高
---
## 方案对比
### 方案 1: ripgrep (rg) CLI 工具 ⭐ 推荐
**优点**：
- ✅ 工业级可靠性，被广泛使用
- ✅ 自动处理 ReDoS 保护
- ✅ 性能极佳（Rust 实现）
- ✅ 支持复杂的正则表达式
- ✅ 内置超时保护
**缺点**：
- ❌ 需要外部依赖
- ❌ 跨平台兼容性需要考虑
**实现**：
```typescript
import { execSync } from 'child_process';
function findMatches(content: string, pattern: string): string[] {
// 将内容写入临时文件
const tempFile = writeTempFile(content);
try {
const result = execSync(
`rg --only-matching --no-line-number --max-count=10 --regexp ${escapeShellArg(pattern)} ${tempFile}`,
{ encoding: 'utf8', timeout: 5000 }
);
return result.split('\n').filter(Boolean);
} catch (error) {
// No matches or timeout
return [];
} finally {
unlinkSync(tempFile);
}
}
```
**评分**：⭐⭐⭐⭐⭐ (最可靠)
---
### 方案 2: search-mark 库
**npm**: `search-mark`
**优点**：
- ✅ 轻量级
- ✅ 纯 JavaScript
- ✅ API 简单
- ✅ 无外部依赖
**实现**：
```typescript
import search from 'search-mark';
function findMatches(content: string, pattern: string): string[] {
try {
const regex = new RegExp(pattern, 'gm');
const results = search(content, regex);
return results
.slice(0, 10) // 限制结果数量
.map(r => r.match); // 返回匹配文本
} catch (error) {
console.error(`Pattern error: ${error.message}`);
return [];
}
}
```
**评分**：⭐⭐⭐⭐ (平衡)
---
### 方案 3: fast-glob + 手动搜索
**npm**: `fast-glob`
**优点**：
- ✅ 快速的文件搜索
- ✅ 内置缓存
- ✅ TypeScript 支持
**实现**：
```typescript
import fastGlob from 'fast-glob';
// 使用 fast-glob 查找文件
const files = await fastGlob('**/*.ts', { cwd: projectDir });
// 使用 ripgrep 或简单字符串搜索内容
```
**评分**：⭐⭐⭐ (适合文件搜索)
---
### 方案 4: node-replace (简化版)
**npm**: `@nodelib/foo`
**实现**：
```typescript
import { replace } from '@nodelib/foo';
function findMatches(content: string, pattern: string): string[] {
try {
const matches: string[] = [];
replace(content, new RegExp(pattern, 'g'), (match) => {
if (matches.length < 10) {
// 提取匹配所在行
const lines = content.split('\n');
const lineIndex = content.substring(0, match.index).split('\n').length - 1;
matches.push(lines[lineIndex].trim());
}
return match; // 不替换，只收集
});
return matches;
} catch (error) {
console.error(`Pattern error: ${error.message}`);
return [];
}
}
```
**评分**：⭐⭐⭐ (中等复杂度)
---
## 推荐方案
### 对于 CCW read_file 工具：
**最佳方案**: **保持当前实现 + 添加安全检查**
原因：
1. ✅ 无需额外依赖
2. ✅ 性能可控（JavaScript 原生）
3. ✅ 已添加安全保护（迭代计数器、位置检查）
4. ✅ 简单可靠
**已添加的保护**：
```typescript
// 1. 空字符串检查
if (!pattern || pattern.length === 0) {
return [];
}
// 2. 零宽度检测（新增）
const testRegex = new RegExp(pattern, 'gm');
const emptyTest = testRegex.exec('');
if (emptyTest && emptyTest[0] === '' && emptyTest.index === 0) {
const secondMatch = testRegex.exec('');
if (secondMatch && secondMatch.index === 0) {
return []; // 危险模式
}
}
// 3. 迭代计数器 (1000 次)
// 4. 位置前进检查
// 5. 结果去重
```
---
## 如果需要更强的保护
考虑使用 **node-ripgrep** 或直接调用 **rg** CLI：
```typescript
// 如果 ripgrep 可用
import { execSync } from 'child_process';
function findMatchesRg(content: string, pattern: string, timeout = 5000): string[] {
const tempFile = `/tmp/search_${Date.now()}.txt`;
writeFileSync(tempFile, content, 'utf8');
try {
const cmd = [
'rg',
'--only-matching',
'--no-line-number',
'--max-count', '10',
'--regexp', pattern,
tempFile
].join(' ');
const result = execSync(cmd, {
encoding: 'utf8',
timeout,
stdio: ['ignore', 'pipe', 'ignore']
});
return result.split('\n').filter(Boolean);
} catch (error) {
return [];
} finally {
unlinkSync(tempFile);
}
}
```
---
## 总结
| 方案 | 可靠性 | 性能 | 依赖 | 推荐度 |
|------|--------|------|------|--------|
| ripgrep CLI | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | 外部工具 | ⭐⭐⭐⭐ |
| search-mark | ⭐⭐⭐⭐ | ⭐⭐⭐ | npm 包 | ⭐⭐⭐⭐ |
| 当前实现 + 保护 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | 无 | ⭐⭐⭐⭐ |
| node-replace | ⭐⭐⭐ | ⭐⭐⭐ | npm 包 | ⭐⭐⭐ |
**最终建议**: 保持当前实现 + 已添加的安全检查，如果需要更强的保护，再考虑 ripgrep CLI 方案。

194
status-reference.md
View File

@@ -1,194 +0,0 @@
# Issue System Status Reference
> CCW Issue Management 状态管理参考手册
## 概述
CCW Issue 系统包含三个核心实体，每个实体有独立的状态定义：
| 实体 | 描述 | 存储位置 |
|------|------|----------|
| **Issue** | 问题/任务 | `.workflow/issues/issues.jsonl` |
| **Queue** | 执行队列 | `.workflow/issues/queues/*.json` |
| **QueueItem** | 队列项（解决方案级别） | Queue 内的 `solutions[]` 数组 |
---
## Issue 状态
**类型定义**: `'registered' | 'planning' | 'planned' | 'queued' | 'executing' | 'completed' | 'failed' | 'paused'`
| 状态 | 含义 | 触发命令/场景 |
|------|------|---------------|
| `registered` | 已注册，待规划 | `ccw issue create`, `ccw issue init`, `ccw issue pull` |
| `planning` | 规划中 | 手动设置 `ccw issue update <id> --status planning` |
| `planned` | 已规划，solution 已绑定 | `ccw issue bind <issue-id> <solution-id>` |
| `queued` | 已加入执行队列 | `ccw issue queue add <issue-id>`, `ccw issue retry` |
| `executing` | 执行中 | `ccw issue next` |
| `completed` | 已完成 | `ccw issue done <item-id>` |
| `failed` | 执行失败 | `ccw issue done <item-id> --fail` |
| `paused` | 暂停 | 手动设置 `ccw issue update <id> --status paused` |
### Issue 状态流转图
```
┌─────────────────────────────────────┐
│ ▼
registered ──→ planning ──→ planned ──→ queued ──→ executing ──→ completed
▲ │
│ ▼
└─────── failed
│
▼
paused (手动)
```
---
## Queue 状态
**类型定义**: `'active' | 'completed' | 'archived' | 'failed' | 'merged'`
| 状态 | 含义 | 触发命令/场景 |
|------|------|---------------|
| `active` | 活跃队列，可执行 | 创建队列时默认, `ccw issue retry` 重置 |
| `completed` | 已完成（所有项完成） | 所有 QueueItem 状态为 `completed` |
| `archived` | 已归档 | `ccw issue queue archive` |
| `failed` | 有失败项 | 有 QueueItem 失败且所有项已终止 |
| `merged` | 已合并到其他队列 | `ccw issue queue merge <source> --queue <target>` |
### Queue 状态流转图
```
┌────────────────────────────────────────┐
│ ▼
active ───────┼──────────────────────────────────→ completed ──→ archived
│
│ ┌───────────┐
└────────→│ failed │
└─────┬─────┘
│ retry
▼
active
active ──────────────────────────────────────────→ merged
```
---
## QueueItem 状态
**类型定义**: `'pending' | 'ready' | 'executing' | 'completed' | 'failed' | 'blocked'`
| 状态 | 含义 | 触发命令/场景 |
|------|------|---------------|
| `pending` | 等待执行 | 创建队列项时默认, `ccw issue retry` 重置 |
| `ready` | 依赖满足，可执行 | 计算得出（非持久化），用于 DAG |
| `executing` | 执行中 | `ccw issue next` |
| `completed` | 已完成 | `ccw issue done <item-id>` |
| `failed` | 失败 | `ccw issue done <item-id> --fail` |
| `blocked` | 被依赖阻塞 | 计算得出（非持久化），用于 DAG |
### QueueItem 状态流转图
```
pending ──→ executing ──→ completed
▲ │
│ ▼
└───────── failed (retry 重置)
```
> **注意**: `ready` 和 `blocked` 是在 `ccw issue queue dag` 命令中动态计算的，不会持久化存储。
---
## 状态验证
系统内置状态验证函数，防止无效状态赋值：
```typescript
// 常量定义
const VALID_QUEUE_STATUSES = ['active', 'completed', 'archived', 'failed', 'merged'] as const;
const VALID_ITEM_STATUSES = ['pending', 'ready', 'executing', 'completed', 'failed', 'blocked'] as const;
const VALID_ISSUE_STATUSES = ['registered', 'planning', 'planned', 'queued', 'executing', 'completed', 'failed', 'paused'] as const;
// 验证函数
validateQueueStatus(status: string): status is QueueStatus
validateItemStatus(status: string): status is QueueItemStatus
validateIssueStatus(status: string): status is IssueStatus
```
---
## 常用命令速查
### 状态查询
```bash
# 查看所有 Issue
ccw issue list
# 按状态筛选 Issue
ccw issue list --status planned,queued
# 查看队列状态
ccw issue queue
# 查看队列 DAG（含 ready/blocked 计算状态）
ccw issue queue dag
```
### 状态更新
```bash
# 更新 Issue 状态
ccw issue update <issue-id> --status <status>
# 从队列同步 Issue 状态为 queued
ccw issue update --from-queue
# 重试失败项（QueueItem → pending, Issue → queued, Queue → active）
ccw issue retry [issue-id]
```
### 执行流程
```bash
# 添加到队列 (Issue → queued, 创建 QueueItem → pending)
ccw issue queue add <issue-id>
# 获取下一个执行项 (QueueItem → executing, Issue → executing)
ccw issue next
# 标记完成 (QueueItem → completed, Issue → completed)
ccw issue done <item-id>
# 标记失败 (QueueItem → failed, Issue → failed)
ccw issue done <item-id> --fail --reason "error message"
```
---
## 状态对照表
| 操作 | Issue 状态 | Queue 状态 | QueueItem 状态 |
|------|-----------|------------|----------------|
| 创建 Issue | `registered` | - | - |
| 绑定 Solution | `planned` | - | - |
| 加入队列 | `queued` | `active` | `pending` |
| 开始执行 | `executing` | `active` | `executing` |
| 执行完成 | `completed` | `completed`* | `completed` |
| 执行失败 | `failed` | `failed`* | `failed` |
| 重试 | `queued` | `active` | `pending` |
| 归档队列 | - | `archived` | - |
| 合并队列 | - | `merged` | - |
> *Queue 状态在所有项完成/失败后才会更新
---
## 相关文档
- [Queue 命令详解](./queue.md)
- [Execute 工作流](./execute.md)
- [Plan 规划流程](./plan.md)