From 9151a82d1d9166c3a8729306c7db8724f5228420 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Sat, 18 Oct 2025 23:37:24 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BC=98=E5=8C=96=20README=20=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E5=B9=B6=E5=88=9B=E5=BB=BA=E5=91=BD=E4=BB=A4=E5=8F=82?= =?UTF-8?q?=E8=80=83=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 主要变更： 1. 精简 README.md 和 README_CN.md 结构 - 移除冗长的功能描述和安装细节 - 合并理念章节为"核心概念" - 简化安装说明，链接到详细 INSTALL.md - 移除详细命令列表，链接到新的 COMMAND_REFERENCE.md 2. 创建 COMMAND_REFERENCE.md - 完整的命令列表和分类 - 按功能组织（Workflow, CLI, Task, Memory, UI Design, Testing） - 包含所有遗漏的命令（UI 设计、测试工作流等） 3. 创建 COMMAND_SPEC.md - 详细的命令技术规范 - 包含参数、职责、Agent 调用、Skill 调用 - 实际使用示例 - 命令间的工作流集成说明 4. 修正 Critical 级别问题 - 统一仓库 URL 为 Claude-Code-Workflow - 更新 INSTALL.md 中的过时信息 5. 文档引用优化 - 在 README 中添加到 COMMAND_REFERENCE.md 和 COMMAND_SPEC.md 的链接 - 保持中英文文档结构一致 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- COMMAND_REFERENCE.md | 133 ++++++ COMMAND_SPEC.md | 476 +++++++++++++++++++ INSTALL.md | 25 +- INSTALL_CN.md | 23 +- README.md | 1046 ++--------------------------------------- README_CN.md | 1052 ++---------------------------------------- 6 files changed, 691 insertions(+), 2064 deletions(-) create mode 100644 COMMAND_REFERENCE.md create mode 100644 COMMAND_SPEC.md diff --git a/COMMAND_REFERENCE.md b/COMMAND_REFERENCE.md new file mode 100644 index 00000000..f4cafbab --- /dev/null +++ b/COMMAND_REFERENCE.md @@ -0,0 +1,133 @@ +# Command Reference + +This document provides a comprehensive reference for all commands available in the Claude Code Workflow (CCW) system. + +## Unified CLI Commands (`/cli:*`) + +These commands provide direct access to AI tools for quick analysis and interaction without initiating a full workflow. + +| Command | Description | +|---|---| +| `/cli:analyze` | Quick codebase analysis using CLI tools (codex/gemini/qwen). | +| `/cli:chat` | Simple CLI interaction command for direct codebase analysis. | +| `/cli:cli-init`| Initialize CLI tool configurations (Gemini and Qwen) based on workspace analysis. | +| `/cli:codex-execute` | Automated task decomposition and execution with Codex using resume mechanism. | +| `/cli:discuss-plan` | Orchestrates an iterative, multi-model discussion for planning and analysis without implementation. | +| `/cli:execute` | Auto-execution of implementation tasks with YOLO permissions and intelligent context inference. | +| `/cli:mode:bug-index` | Bug analysis and fix suggestions using CLI tools. | +| `/cli:mode:code-analysis` | Deep code analysis and debugging using CLI tools with specialized template. | +| `/cli:mode:plan` | Project planning and architecture analysis using CLI tools. | + +## 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. | + +### Core Workflow + +| Command | Description | +|---|---| +| `/workflow:plan` | Orchestrate 5-phase planning workflow with quality gate, executing commands and passing context between phases. | +| `/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 topic-framework.md dynamically based on selected roles. | +| `/workflow:brainstorm:auto-parallel` | Parallel brainstorming automation with dynamic role selection and concurrent execution. | +| `/workflow:brainstorm:synthesis` | Generate synthesis-specification.md from topic-framework and role analyses with @ references using conceptual-planning-agent. | +| `/workflow:brainstorm:api-designer` | Generate or update api-designer/analysis.md addressing topic-framework discussion points. | +| `/workflow:brainstorm:data-architect` | Generate or update data-architect/analysis.md addressing topic-framework discussion points. | +| `/workflow:brainstorm:product-manager` | Generate or update product-manager/analysis.md addressing topic-framework discussion points. | +| `/workflow:brainstorm:product-owner` | Generate or update product-owner/analysis.md addressing topic-framework discussion points. | +| `/workflow:brainstorm:scrum-master` | Generate or update scrum-master/analysis.md addressing topic-framework discussion points. | +| `/workflow:brainstorm:subject-matter-expert` | Generate or update subject-matter-expert/analysis.md addressing topic-framework discussion points. | +| `/workflow:brainstorm:system-architect` | Generate or update system-architect/analysis.md addressing topic-framework discussion points. | +| `/workflow:brainstorm:ui-designer` | Generate or update ui-designer/analysis.md addressing topic-framework discussion points. | +| `/workflow:brainstorm:ux-expert` | Generate or update ux-expert/analysis.md addressing topic-framework discussion points. | + +### Quality & Verification + +| Command | Description | +|---|---| +| `/workflow:concept-clarify` | Identify underspecified areas in brainstorming artifacts through targeted clarification questions before action planning. | +| `/workflow:action-plan-verify`| Perform non-destructive cross-artifact consistency and quality analysis of IMPL_PLAN.md and task.json before execution. | + +### 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` | Create independent test-fix workflow session by analyzing completed implementation. | +| `/workflow:test-fix-gen` | Create independent test-fix workflow session from existing implementation (session or prompt-based). | +| `/workflow:test-cycle-execute` | Execute test-fix workflow with dynamic task generation and iterative fix cycles. | + +### 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:batch-generate` | Prompt-driven batch UI generation using target-style-centric parallel execution. | +| `/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:update` | Update brainstorming artifacts with finalized design system references. | +| `/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:context-gather` | Intelligently collect project context using general-purpose 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` | Replan individual tasks with detailed user input and change tracking. | + +## Memory and Versioning Commands + +| Command | Description | +|---|---| +| `/memory:update-full` | Complete project-wide CLAUDE.md documentation update. | +| `/memory:update-related` | Context-aware CLAUDE.md documentation updates based on recent changes. | +| `/version` | Display version information and check for updates. | +| `/enhance-prompt` | Context-aware prompt enhancement using session memory and codebase analysis. | + diff --git a/COMMAND_SPEC.md b/COMMAND_SPEC.md new file mode 100644 index 00000000..3051f451 --- /dev/null +++ b/COMMAND_SPEC.md @@ -0,0 +1,476 @@ + +# Claude Code Workflow (CCW) - Command Specification + +**Version**: 4.6.0 +**Generated**: 2025年10月18日星期六 + +## 1. Introduction + +This document provides a detailed technical specification for every command available in the Claude Code Workflow (CCW) system. It is intended for advanced users and developers who wish to understand the inner workings of CCW, customize commands, or build new workflows. + +For a user-friendly overview, please see [COMMAND_REFERENCE.md](COMMAND_REFERENCE.md). + +## 2. Command Categories + +Commands are organized into the following categories: + +- **Workflow Commands**: High-level orchestration for multi-phase development processes. +- **CLI Commands**: Direct access to AI tools for analysis and interaction. +- **Task Commands**: Management of individual work units within a workflow. +- **Memory Commands**: Context and documentation management. +- **UI Design Commands**: Specialized workflow for UI/UX design and prototyping. +- **Testing Commands**: TDD and test generation workflows. + +--- + +## 3. Workflow Commands + +High-level orchestrators for complex, multi-phase development processes. + +### **/workflow:plan** + +- **Syntax**: `/workflow:plan [--agent] [--cli-execute] "text description"|file.md` +- **Parameters**: + - `--agent` (Optional, Flag): Use the `task-generate-agent` for autonomous task generation. + - `--cli-execute` (Optional, Flag): Generate tasks with commands ready for CLI execution (e.g., using Codex). + - `description|file.md` (Required, String): A description of the planning goal or a path to a markdown file containing the requirements. +- **Responsibilities**: Orchestrates a 5-phase planning workflow that includes session start, context gathering, intelligent analysis, concept clarification (quality gate), and task generation. +- **Agent Calls**: Delegates analysis to `@cli-execution-agent` and task generation to `@action-planning-agent`. +- **Skill Invocation**: Does not directly invoke a skill, but the underlying agents may. +- **Integration**: This is a primary entry point for starting a development workflow. It is followed by `/workflow:execute`. +- **Example**: + ```bash + /workflow:plan "Create a simple Express API that returns Hello World" + ``` + +### **/workflow:execute** + +- **Syntax**: `/workflow:execute [--resume-session="session-id"]` +- **Parameters**: + - `--resume-session` (Optional, String): The ID of a paused session to resume. +- **Responsibilities**: Discovers and executes all pending tasks in the active (or specified) workflow session. It handles dependency resolution and orchestrates agents to perform the work. +- **Agent Calls**: Dynamically calls the agent specified in each task's `meta.agent` field (e.g., `@code-developer`, `@test-fix-agent`). +- **Integration**: The primary command for implementing a plan generated by `/workflow:plan`. +- **Example**: + ```bash + # Execute tasks in the currently active session + /workflow:execute + ``` + +### **/workflow:resume** + +- **Syntax**: `/workflow:resume "session-id"` +- **Parameters**: + - `session-id` (Required, String): The ID of the workflow session to resume. +- **Responsibilities**: A two-phase orchestrator that first analyzes the status of a paused session and then resumes it by calling `/workflow:execute --resume-session`. +- **Agent Calls**: None directly. It orchestrates `/workflow:status` and `/workflow:execute`. +- **Integration**: Used to continue a previously paused or interrupted workflow. +- **Example**: + ```bash + /workflow:resume "WFS-user-login-feature" + ``` + +### **/workflow:review** + +- **Syntax**: `/workflow:review [--type=security|architecture|action-items|quality] [session-id]` +- **Parameters**: + - `--type` (Optional, String): The type of review to perform. Defaults to `quality`. + - `session-id` (Optional, String): The session to review. Defaults to the active session. +- **Responsibilities**: Performs a specialized, post-implementation review. This is optional, as the default quality gate is passing tests. +- **Agent Calls**: Uses `gemini-wrapper` or `qwen-wrapper` for analysis based on the review type. +- **Integration**: Used after `/workflow:execute` to perform audits before deployment. +- **Example**: + ```bash + /workflow:review --type=security + ``` + +### **/workflow:status** + +- **Syntax**: `/workflow:status [task-id]` +- **Parameters**: + - `task-id` (Optional, String): If provided, shows details for a specific task. +- **Responsibilities**: Generates and displays an on-demand view of the current workflow's status by reading task JSON data. Does not modify any state. +- **Agent Calls**: None. +- **Integration**: A read-only command used to check progress at any point. +- **Example**: + ```bash + /workflow:status + ``` + +--- + +## 4. Session Management Commands + +Commands for creating, listing, and managing workflow sessions. + +### **/workflow:session:start** +- **Syntax**: `/workflow:session:start [--auto|--new] [description]` +- **Parameters**: + - `--auto` (Flag): Intelligently reuses an active session if relevant, otherwise creates a new one. + - `--new` (Flag): Forces the creation of a new session. + - `description` (Optional, String): A description for the new session's goal. +- **Responsibilities**: Manages session creation and activation. It can discover existing sessions, create new ones, and set the active session marker. +- **Agent Calls**: None. +- **Example**: + ```bash + /workflow:session:start "My New Feature" + ``` + +### **/workflow:session:list** +- **Syntax**: `/workflow:session:list` +- **Parameters**: None. +- **Responsibilities**: Lists all workflow sessions found in the `.workflow/` directory, showing their status (active, paused, completed). +- **Agent Calls**: None. +- **Example**: + ```bash + /workflow:session:list + ``` + +### **/workflow:session:resume** +- **Syntax**: `/workflow:session:resume` +- **Parameters**: None. +- **Responsibilities**: Finds the most recently paused session and marks it as active. +- **Agent Calls**: None. +- **Example**: + ```bash + /workflow:session:resume + ``` + +### **/workflow:session:complete** +- **Syntax**: `/workflow:session:complete [--detailed]` +- **Parameters**: + - `--detailed` (Flag): Shows a more detailed completion summary. +- **Responsibilities**: Marks the currently active session as "completed", records timestamps, and removes the `.active-*` marker file. +- **Agent Calls**: None. +- **Example**: + ```bash + /workflow:session:complete + ``` + +--- + +## 5. CLI Commands + +Direct access to AI tools for analysis and code interaction without a full workflow structure. + +### **/cli:analyze** +- **Syntax**: `/cli:analyze [--agent] [--tool codex|gemini|qwen] [--enhance] ` +- **Responsibilities**: Performs read-only codebase analysis. Can operate in standard mode (direct tool call) or agent mode (`@cli-execution-agent`) for automated context discovery. +- **Agent Calls**: `@cli-execution-agent` (if `--agent` is used). +- **Example**: + ```bash + /cli:analyze "authentication patterns" + ``` + +### **/cli:chat** +- **Syntax**: `/cli:chat [--agent] [--tool codex|gemini|qwen] [--enhance] ` +- **Responsibilities**: Provides a direct Q&A interface with AI tools for codebase questions. Read-only. +- **Agent Calls**: `@cli-execution-agent` (if `--agent` is used). +- **Example**: + ```bash + /cli:chat "how does the caching layer work?" + ``` + +### **/cli:cli-init** +- **Syntax**: `/cli:cli-init [--tool gemini|qwen|all] [--output path] [--preview]` +- **Responsibilities**: Initializes configuration for CLI tools (`.gemini/`, `.qwen/`) by analyzing the workspace and creating optimized `.geminiignore` and `.qwenignore` files. +- **Agent Calls**: None. +- **Example**: + ```bash + /cli:cli-init + ``` + +### **/cli:codex-execute** +- **Syntax**: `/cli:codex-execute [--verify-git] ` +- **Responsibilities**: Orchestrates automated task decomposition and sequential execution using Codex. It uses the `resume --last` mechanism for context continuity between subtasks. +- **Agent Calls**: None directly, but orchestrates `codex` CLI tool. +- **Example**: + ```bash + /cli:codex-execute "implement user authentication system" + ``` + +### **/cli:discuss-plan** +- **Syntax**: `/cli:discuss-plan [--topic '...'] [--task-id '...'] [--rounds N] ` +- **Responsibilities**: Orchestrates an iterative, multi-model (Gemini, Codex, Claude) discussion to perform deep analysis and planning without modifying code. +- **Agent Calls**: None directly, but orchestrates `gemini-wrapper` and `codex` CLI tools. +- **Example**: + ```bash + /cli:discuss-plan --topic "Design a new caching layer" + ``` + +### **/cli:execute** +- **Syntax**: `/cli:execute [--agent] [--tool codex|gemini|qwen] [--enhance] ` +- **Responsibilities**: Executes implementation tasks with auto-approval (`YOLO` mode). **MODIFIES CODE**. +- **Agent Calls**: `@cli-execution-agent` (if `--agent` is used). +- **Example**: + ```bash + /cli:execute "implement JWT authentication with middleware" + ``` + +### **/cli:mode:bug-index** +- **Syntax**: `/cli:mode:bug-index [--agent] [--tool ...] [--enhance] [--cd path] ` +- **Responsibilities**: Performs systematic bug analysis using the `bug-fix.md` template. Read-only. +- **Agent Calls**: `@cli-execution-agent` (if `--agent` is used). +- **Example**: + ```bash + /cli:mode:bug-index "null pointer error in login flow" + ``` + +### **/cli:mode:code-analysis** +- **Syntax**: `/cli:mode:code-analysis [--agent] [--tool ...] [--enhance] [--cd path] ` +- **Responsibilities**: Performs deep code analysis and execution path tracing using the `code-analysis.md` template. Read-only. +- **Agent Calls**: `@cli-execution-agent` (if `--agent` is used). +- **Example**: + ```bash + /cli:mode:code-analysis "trace authentication execution flow" + ``` + +### **/cli:mode:plan** +- **Syntax**: `/cli:mode:plan [--agent] [--tool ...] [--enhance] [--cd path] ` +- **Responsibilities**: Performs comprehensive planning and architecture analysis using the `plan.md` template. Read-only. +- **Agent Calls**: `@cli-execution-agent` (if `--agent` is used). +- **Example**: + ```bash + /cli:mode:plan "design user dashboard architecture" + ``` + +--- + +## 6. Task Commands + +Commands for managing individual tasks within a workflow session. + +### **/task:create** +- **Syntax**: `/task:create "task title"` +- **Parameters**: + - `title` (Required, String): The title of the task. +- **Responsibilities**: Creates a new task JSON file within the active session, auto-generating an ID and inheriting context. +- **Agent Calls**: Suggests an agent (e.g., `@code-developer`) based on task type but does not call it. +- **Example**: + ```bash + /task:create "Build authentication module" + ``` + +### **/task:breakdown** +- **Syntax**: `/task:breakdown ` +- **Parameters**: + - `task-id` (Required, String): The ID of the parent task to break down. +- **Responsibilities**: Manually decomposes a complex parent task into smaller, executable subtasks. Enforces a 10-task limit and file cohesion. +- **Agent Calls**: None. +- **Example**: + ```bash + /task:breakdown IMPL-1 + ``` + +### **/task:execute** +- **Syntax**: `/task:execute ` +- **Parameters**: + - `task-id` (Required, String): The ID of the task to execute. +- **Responsibilities**: Executes a single task or a parent task (by executing its subtasks) using the assigned agent. +- **Agent Calls**: Calls the agent specified in the task's `meta.agent` field. +- **Example**: + ```bash + /task:execute IMPL-1.1 + ``` + +### **/task:replan** +- **Syntax**: `/task:replan ["text"|file.md] | --batch [report.md]` +- **Parameters**: + - `task-id` (String): The ID of the task to replan. + - `input` (String): Text or a file path with the new specifications. + - `--batch` (Flag): Enables batch processing from a verification report. +- **Responsibilities**: Updates a task's specification, creating a versioned backup of the previous state. +- **Agent Calls**: None. +- **Example**: + ```bash + /task:replan IMPL-1 "Add OAuth2 authentication support" + ``` + +--- + +## 7. Memory and Versioning Commands + +### **/memory:update-full** +- **Syntax**: `/memory:update-full [--tool gemini|qwen|codex] [--path ]` +- **Responsibilities**: Orchestrates a complete, project-wide update of all `CLAUDE.md` documentation files. +- **Agent Calls**: None directly, but orchestrates CLI tools (`gemini-wrapper`, etc.). +- **Example**: + ```bash + /memory:update-full + ``` + +### **/memory:update-related** +- **Syntax**: `/memory:update-related [--tool gemini|qwen|codex]` +- **Responsibilities**: Performs a context-aware update of `CLAUDE.md` files for modules affected by recent git changes. +- **Agent Calls**: None directly, but orchestrates CLI tools. +- **Example**: + ```bash + /memory:update-related + ``` + +### **/version** +- **Syntax**: `/version` +- **Parameters**: None. +- **Responsibilities**: Displays local and global installation versions and checks for updates from GitHub. +- **Agent Calls**: None. +- **Example**: + ```bash + /version + ``` + +### **/enhance-prompt** +- **Syntax**: `/enhance-prompt ` +- **Responsibilities**: A system-level skill that enhances a user's prompt by adding context from session memory and codebase analysis. It is typically triggered automatically by other commands that include the `--enhance` flag. +- **Skill Invocation**: This is a core skill, invoked when `--enhance` is used. +- **Agent Calls**: None. +- **Example (as part of another command)**: + ```bash + /cli:execute --enhance "fix the login button" + ``` + +--- + +## 8. UI Design Commands + +Specialized workflow for UI/UX design, from style extraction to prototype generation. + +### **/workflow:ui-design:explore-auto** +- **Syntax**: `/workflow:ui-design:explore-auto [--prompt "..."] [--images "..."] [--targets "..."] ...` +- **Responsibilities**: Fully autonomous, multi-phase workflow that orchestrates style extraction, layout extraction, and prototype generation. +- **Agent Calls**: `@ui-design-agent`. +- **Example**: + ```bash + /workflow:ui-design:explore-auto --prompt "Modern blog: home, article, author" + ``` + +### **/workflow:ui-design:imitate-auto** +- **Syntax**: `/workflow:ui-design:imitate-auto --url-map "" [--capture-mode ] ...` +- **Responsibilities**: High-speed, multi-page UI replication workflow that captures screenshots and orchestrates the full design pipeline. +- **Agent Calls**: `@ui-design-agent`. +- **Example**: + ```bash + /workflow:ui-design:imitate-auto --url-map "home:https://linear.app, features:https://linear.app/features" + ``` + +### **/workflow:ui-design:batch-generate** +- **Syntax**: `/workflow:ui-design:batch-generate [--prompt "..."] [--targets "..."] ...` +- **Responsibilities**: Prompt-driven batch UI generation with parallel execution for multiple targets and styles. +- **Agent Calls**: `@ui-design-agent`. +- **Example**: + ```bash + /workflow:ui-design:batch-generate --prompt "Dashboard with metric cards and charts" + ``` + +### **/workflow:ui-design:capture** +- **Syntax**: `/workflow:ui-design:capture --url-map "target:url,..." ...` +- **Responsibilities**: Batch screenshot capture tool with MCP-first strategy and local fallbacks. +- **Agent Calls**: None directly, uses MCP tools. +- **Example**: + ```bash + /workflow:ui-design:capture --url-map "home:https://linear.app" + ``` + +### **/workflow:ui-design:explore-layers** +- **Syntax**: `/workflow:ui-design:explore-layers --url --depth <1-5> ...` +- **Responsibilities**: Performs a deep, interactive UI capture of a single URL, exploring layers from the full page down to the Shadow DOM. +- **Agent Calls**: None directly, uses MCP tools. +- **Example**: + ```bash + /workflow:ui-design:explore-layers --url https://linear.app --depth 3 + ``` + +### **/workflow:ui-design:style-extract** +- **Syntax**: `/workflow:ui-design:style-extract [--images "..."] [--prompt "..."] ...` +- **Responsibilities**: Extracts design styles from images or text prompts and generates production-ready design systems (`design-tokens.json`, `style-guide.md`). +- **Agent Calls**: `@ui-design-agent`. +- **Example**: + ```bash + /workflow:ui-design:style-extract --images "design-refs/*.png" --variants 3 + ``` + +### **/workflow:ui-design:layout-extract** +- **Syntax**: `/workflow:ui-design:layout-extract [--images "..."] [--urls "..."] ...` +- **Responsibilities**: Extracts structural layout information (HTML structure, CSS layout rules) separately from visual style. +- **Agent Calls**: `@ui-design-agent`. +- **Example**: + ```bash + /workflow:ui-design:layout-extract --urls "home:https://linear.app" --mode imitate + ``` + +### **/workflow:ui-design:generate** +- **Syntax**: `/workflow:ui-design:generate [--base-path ] ...` +- **Responsibilities**: A pure assembler that combines pre-extracted layout templates with design tokens to generate final UI prototypes. +- **Agent Calls**: `@ui-design-agent`. +- **Example**: + ```bash + /workflow:ui-design:generate --session WFS-design-run + ``` + +### **/workflow:ui-design:update** +- **Syntax**: `/workflow:ui-design:update --session ...` +- **Responsibilities**: Synchronizes the finalized design system references into the core brainstorming artifacts (`synthesis-specification.md`) to make them available for the planning phase. +- **Agent Calls**: None. +- **Example**: + ```bash + /workflow:ui-design:update --session WFS-my-app + ``` + +### **/workflow:ui-design:animation-extract** +- **Syntax**: `/workflow:ui-design:animation-extract [--urls ""] [--mode ] ...` +- **Responsibilities**: Extracts animation and transition patterns from URLs (auto mode) or through interactive questioning to generate animation tokens. +- **Agent Calls**: `@ui-design-agent` (for interactive mode). +- **Example**: + ```bash + /workflow:ui-design:animation-extract --urls "home:https://linear.app" --mode auto + ``` + +--- + +## 9. Testing Commands + +Workflows for Test-Driven Development (TDD) and post-implementation test generation. + +### **/workflow:tdd-plan** +- **Syntax**: `/workflow:tdd-plan [--agent] "feature description"|file.md` +- **Responsibilities**: Orchestrates a 7-phase TDD planning workflow, creating tasks with Red-Green-Refactor cycles. +- **Agent Calls**: Orchestrates sub-commands which may call agents. +- **Example**: + ```bash + /workflow:tdd-plan "Implement a secure login endpoint" + ``` + +### **/workflow:tdd-verify** +- **Syntax**: `/workflow:tdd-verify [session-id]` +- **Responsibilities**: Verifies TDD workflow compliance by analyzing task chains, test coverage, and cycle execution. +- **Agent Calls**: None directly, orchestrates `gemini-wrapper`. +- **Example**: + ```bash + /workflow:tdd-verify WFS-login-tdd + ``` + +### **/workflow:test-gen** +- **Syntax**: `/workflow:test-gen [--use-codex] [--cli-execute] ` +- **Responsibilities**: Creates an independent test-fix workflow by analyzing a completed implementation session. +- **Agent Calls**: Orchestrates sub-commands that call `@code-developer` and `@test-fix-agent`. +- **Example**: + ```bash + /workflow:test-gen WFS-user-auth-v2 + ``` + +### **/workflow:test-fix-gen** +- **Syntax**: `/workflow:test-fix-gen [--use-codex] [--cli-execute] ( | "description" | /path/to/file.md)` +- **Responsibilities**: Creates an independent test-fix workflow from either a completed session or a feature description. +- **Agent Calls**: Orchestrates sub-commands that call `@code-developer` and `@test-fix-agent`. +- **Example**: + ```bash + /workflow:test-fix-gen "Test the user authentication API endpoints" + ``` + +### **/workflow:test-cycle-execute** +- **Syntax**: `/workflow:test-cycle-execute [--resume-session="session-id"] [--max-iterations=N]` +- **Responsibilities**: Executes a dynamic test-fix workflow, creating intermediate fix tasks based on test results and analysis. +- **Agent Calls**: `@code-developer`, `@test-fix-agent`. +- **Example**: + ```bash + /workflow:test-cycle-execute --resume-session="WFS-test-user-auth" + ``` diff --git a/INSTALL.md b/INSTALL.md index 1e6574c2..99b73695 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -9,16 +9,16 @@ Interactive installation guide for Claude Code with Agent workflow coordination ### All Platforms - Remote PowerShell Installation ```powershell # Interactive remote installation from feature branch (latest) -iex (iwr -useb https://raw.githubusercontent.com/catlog22/Dmsflow/main/install-remote.ps1) +iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1) # Global installation with unified file output system -iex (iwr -useb https://raw.githubusercontent.com/catlog22/Dmsflow/main/install-remote.ps1) -Global +iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1) -Global # Force overwrite (non-interactive) - includes all new workflow file generation features -iex (iwr -useb https://raw.githubusercontent.com/catlog22/Dmsflow/main/install-remote.ps1) -Force -NonInteractive +iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1) -Force -NonInteractive # One-click backup all existing files (no confirmations needed) -iex (iwr -useb https://raw.githubusercontent.com/catlog22/Dmsflow/main/install-remote.ps1) -BackupAll +iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1) -BackupAll ``` **What the remote installer does:** @@ -37,8 +37,7 @@ iex (iwr -useb https://raw.githubusercontent.com/catlog22/Dmsflow/main/install-r ### All Platforms (PowerShell) ```powershell # Clone the repository with latest features -git clone -b main https://github.com/catlog22/Claude-CCW.git -cd Dmsflow +cd Claude-Code-Workflow # Windows PowerShell 5.1+ or PowerShell Core (Global installation only) .\Install-Claude.ps1 @@ -57,22 +56,22 @@ All parameters can be passed to the remote installer: ```powershell # Global installation -iex (iwr -useb https://raw.githubusercontent.com/catlog22/Dmsflow/main/install-remote.ps1) -Global +iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1) -Global # Install to specific directory -iex (iwr -useb https://raw.githubusercontent.com/catlog22/Dmsflow/main/install-remote.ps1) -Directory "C:\MyProject" +iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1) -Directory "C:\MyProject" # Force overwrite without prompts -iex (iwr -useb https://raw.githubusercontent.com/catlog22/Dmsflow/main/install-remote.ps1) -Force -NonInteractive +iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1) -Force -NonInteractive # Install from specific branch -iex (iwr -useb https://raw.githubusercontent.com/catlog22/Dmsflow/main/install-remote.ps1) -Branch "dev" +iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1) -Branch "dev" # Skip backups (overwrite without backup - not recommended) -iex (iwr -useb https://raw.githubusercontent.com/catlog22/Dmsflow/main/install-remote.ps1) -NoBackup +iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1) -NoBackup # Explicit automatic backup all existing files (default behavior since v1.1.0) -iex (iwr -useb https://raw.githubusercontent.com/catlog22/Dmsflow/main/install-remote.ps1) -BackupAll +iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1) -BackupAll ``` ### Local Installation Options @@ -164,7 +163,7 @@ Install PowerShell Core: ### ⚡ Super Quick (One-Liner) ```powershell # Complete installation in one command -iex (iwr -useb https://raw.githubusercontent.com/catlog22/Dmsflow/main/install-remote.ps1) -Global +iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1) -Global # Done! 🎉 # Start using Claude Code with Agent workflows! diff --git a/INSTALL_CN.md b/INSTALL_CN.md index 4ed72917..9fb76107 100644 --- a/INSTALL_CN.md +++ b/INSTALL_CN.md @@ -9,16 +9,16 @@ Claude Code Agent 工作流协调和分布式内存系统的交互式安装指 ### 所有平台 - 远程 PowerShell 安装 ```powershell # 从功能分支进行交互式远程安装（最新版本） -iex (iwr -useb https://raw.githubusercontent.com/catlog22/Dmsflow/main/install-remote.ps1) +iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1) # 包含统一文件输出系统的全局安装 -iex (iwr -useb https://raw.githubusercontent.com/catlog22/Dmsflow/main/install-remote.ps1) -Global +iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1) -Global # 强制覆盖（非交互式）- 包含所有新的工作流文件生成功能 -iex (iwr -useb https://raw.githubusercontent.com/catlog22/Dmsflow/main/install-remote.ps1) -Force -NonInteractive +iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1) -Force -NonInteractive # 一键备份所有现有文件（无需确认） -iex (iwr -useb https://raw.githubusercontent.com/catlog22/Dmsflow/main/install-remote.ps1) -BackupAll +iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1) -BackupAll ``` **远程安装器的功能：** @@ -37,8 +37,7 @@ iex (iwr -useb https://raw.githubusercontent.com/catlog22/Dmsflow/main/install-r ### 所有平台（PowerShell） ```powershell # 克隆包含最新功能的仓库 -git clone -b main https://github.com/catlog22/Claude-CCW.git -cd Dmsflow +cd Claude-Code-Workflow # Windows PowerShell 5.1+ 或 PowerShell Core（仅支持全局安装） .\Install-Claude.ps1 @@ -57,19 +56,19 @@ pwsh ./Install-Claude.ps1 ```powershell # 全局安装 -iex (iwr -useb https://raw.githubusercontent.com/catlog22/Dmsflow/main/install-remote.ps1) -Global +iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1) -Global # 安装到指定目录 -iex (iwr -useb https://raw.githubusercontent.com/catlog22/Dmsflow/main/install-remote.ps1) -Directory "C:\MyProject" +iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1) -Directory "C:\MyProject" # 强制覆盖而不提示 -iex (iwr -useb https://raw.githubusercontent.com/catlog22/Dmsflow/main/install-remote.ps1) -Force -NonInteractive +iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1) -Force -NonInteractive # 从特定分支安装 -iex (iwr -useb https://raw.githubusercontent.com/catlog22/Dmsflow/main/install-remote.ps1) -Branch "dev" +iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1) -Branch "dev" # 跳过备份（更快） -iex (iwr -useb https://raw.githubusercontent.com/catlog22/Dmsflow/main/install-remote.ps1) -NoBackup +iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1) -NoBackup ``` ### 本地安装选项 @@ -140,7 +139,7 @@ iex (iwr -useb https://raw.githubusercontent.com/catlog22/Dmsflow/main/install-r ### ⚡ 超快速（一键） ```powershell # 一条命令完成安装 -iex (iwr -useb https://raw.githubusercontent.com/catlog22/Dmsflow/main/install-remote.ps1) -Global +iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1) -Global # 完成！🎉 # 开始使用 Claude Code Agent 工作流！ diff --git a/README.md b/README.md index be1efa0b..0492be72 100644 --- a/README.md +++ b/README.md @@ -16,56 +16,28 @@ **Claude Code Workflow (CCW)** transforms AI development from simple prompt chaining into a robust, context-first orchestration system. It solves execution uncertainty and error accumulation through structured planning, deterministic execution, and intelligent multi-model orchestration. > **🎉 Latest: v4.6.0** - Concept Clarification & Agent-Driven Analysis. See [CHANGELOG.md](CHANGELOG.md) for details. -> -> **What's New in v4.6.0**: -> - 🎯 **Concept Clarification Quality Gate**: Interactive Q&A to resolve ambiguities before task generation (Phase 3.5) -> - 🤖 **Agent-Delegated Analysis**: Phase 3 now uses cli-execution-agent for autonomous context discovery -> - 🔄 **Dual-Mode Support**: concept-clarify auto-detects brainstorm vs plan workflows -> - 📚 **Test-Cycle-Execute**: Enhanced documentation for dynamic test-fix iteration workflows -> - ✨ **Backward Compatible**: All enhancements preserve existing workflow functionality - ---- > 📚 **New to CCW?** Check out the [**Getting Started Guide**](GETTING_STARTED.md) for a beginner-friendly 5-minute tutorial! --- -## ✨ Core Differentiators +## ✨ Core Concepts -#### **1. Context-First Architecture** 🎯 -Pre-defined context gathering via `context-package.json` and `flow_control.pre_analysis` eliminates execution uncertainty. Agents load correct context **before** implementation, solving the "1-to-N" development drift problem. +CCW is built on a set of core principles that differentiate it from traditional AI development approaches: -#### **2. JSON-First State Management** 📋 -Task states live in `.task/IMPL-*.json` (single source of truth). Markdown files are read-only views. Separates data from presentation, enabling programmatic orchestration without state drift. - -#### **3. Autonomous Multi-Phase Orchestration** 🔄 -Commands like `/workflow:plan` chain specialized sub-commands (session → context → analysis → tasks) with zero user intervention. `flow_control` mechanism creates executable "programs" for agents with step dependencies. - -#### **4. Multi-Model Strategic Orchestration** 🧠 -- **Gemini/Qwen**: Analysis, exploration, documentation (large context) -- **Codex**: Implementation, autonomous execution (`resume --last` maintains context) -- **Result**: 5-10x better task handling vs single-model approaches - -#### **5. Hierarchical Memory System** 🧬 -4-layer documentation (Root → Domain → Module → Sub-Module) provides context at appropriate abstraction levels, preventing information overload while maintaining precision. - -#### **6. Specialized Role-Based Agents** 🤖 -Dedicated agents mirror real software teams: `@action-planning-agent`, `@code-developer`, `@test-fix-agent`, `@ui-design-agent`. Includes TDD workflows (Red-Green-Refactor), UI design (layout/style separation), and automated QA. - ---- - -### **Additional Features** - -- **✅ Pre-execution Verification**: Quality gates (`/workflow:concept-clarify`, `/workflow:action-plan-verify`) -- **🔧 Unified CLI**: `/cli:*` commands with multi-tool support (`--tool gemini|qwen|codex`) -- **📦 Smart Context Package**: Links tasks to relevant code and external examples -- **🎨 UI Design Workflow**: Claude-native style/layout extraction, zero dependencies -- **🔄 Progressive Enhancement**: Optional tools extend capabilities, Claude-only mode works out-of-box +- **Context-First Architecture**: Pre-defined context gathering eliminates execution uncertainty by ensuring agents have the correct information *before* implementation. +- **JSON-First State Management**: Task states live in `.task/IMPL-*.json` files as the single source of truth, enabling programmatic orchestration without state drift. +- **Autonomous Multi-Phase Orchestration**: Commands chain specialized sub-commands and agents to automate complex workflows with zero user intervention. +- **Multi-Model Strategy**: Leverages the unique strengths of different AI models (Gemini for analysis, Codex for implementation) for superior results. +- **Hierarchical Memory System**: A 4-layer documentation system provides context at the appropriate level of abstraction, preventing information overload. +- **Specialized Role-Based Agents**: A suite of agents (`@code-developer`, `@test-fix-agent`, etc.) mirrors a real software team to handle diverse tasks. --- ## ⚙️ Installation +For detailed installation instructions, please refer to the [**INSTALL.md**](INSTALL.md) guide. + ### **🚀 Quick One-Line Installation** **Windows (PowerShell):** @@ -78,1001 +50,39 @@ Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/cat bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.sh) ``` -### **📋 Interactive Version Selection** - -After running the installation command, you'll see an interactive menu with real-time version information: - -``` -Detecting latest release and commits... -Latest stable: v3.2.0 (2025-10-02 04:27 UTC) -Latest commit: cdea58f (2025-10-02 08:15 UTC) - -==================================================== - Version Selection Menu -==================================================== - -1) Latest Stable Release (Recommended) - |-- Version: v3.2.0 - |-- Released: 2025-10-02 04:27 UTC - \-- Production-ready - -2) Latest Development Version - |-- Branch: main - |-- Commit: cdea58f - |-- Updated: 2025-10-02 08:15 UTC - |-- Cutting-edge features - \-- May contain experimental changes - -3) Specific Release Version - |-- Install a specific tagged release - \-- Recent: v3.2.0, v3.1.0, v3.0.1 - -==================================================== - -Select version to install (1-3, default: 1): -``` - -**Version Options:** -- **Option 1 (Recommended)**: Latest stable release with verified production quality -- **Option 2**: Latest development version from main branch with newest features -- **Option 3**: Specific version tag for controlled deployments - -> 💡 **Pro Tip**: The installer automatically detects and displays the latest version numbers and release dates from GitHub. Just press Enter to select the recommended stable release. - -### **📦 Local Installation (Install-Claude.ps1)** - -For local installation without network access, use the bundled PowerShell installer: - -**Installation Modes:** -```powershell -# Interactive mode with prompts (recommended) -.\Install-Claude.ps1 - -# Quick install with automatic backup -.\Install-Claude.ps1 -Force -BackupAll - -# Non-interactive install -.\Install-Claude.ps1 -NonInteractive -Force -``` - -**Installation Options:** - -| Mode | Description | Installs To | -|------|-------------|-------------| -| **Global** | System-wide installation (default) | `~/.claude/`, `~/.codex/`, `~/.gemini/` | -| **Path** | Custom directory + global hybrid | Local: `agents/`, `commands/`
Global: `workflows/`, `scripts/` | - -**Backup Behavior:** -- **Default**: Automatic backup enabled (`-BackupAll`) -- **Disable**: Use `-NoBackup` flag (⚠️ overwrites without backup) -- **Backup location**: `claude-backup-{timestamp}/` in installation directory - -**⚠️ Important Warnings:** -- `-Force -BackupAll`: Silent file overwrite (with backup) -- `-NoBackup -Force`: Permanent file overwrite (no recovery) -- Global mode modifies user profile directories - ### **✅ 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. - -> **📝 Installation Notes:** -> - The installer will automatically install/update `.codex/` and `.gemini/` directories -> - **Global mode**: Installs to `~/.codex` and `~/.gemini` -> - **Path mode**: Installs to your specified directory (e.g., `project/.codex`, `project/.gemini`) -> - **Backup**: Existing files are backed up by default to `claude-backup-{timestamp}/` -> - **Safety**: Use interactive mode for first-time installation to review changes - ---- - -## ⚙️ 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**: `~/.claude/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: - -#### **External CLI Tools** - -| Tool | Purpose | Installation | Benefits | -|------|---------|--------------|----------| -| **Gemini CLI** | AI analysis & documentation | `npm install -g @google/gemini-cli` ([GitHub](https://github.com/google-gemini/gemini-cli)) | Free quota, extended context for complex projects | -| **Codex CLI** | AI development & implementation | `npm install -g @openai/codex` ([GitHub](https://github.com/openai/codex)) | Autonomous development, mathematical reasoning | -| **Qwen Code** | AI architecture & code generation | `npm install -g @qwen-code/qwen-code` ([Docs](https://github.com/QwenLM/qwen-code)) | Large context window, architecture analysis | - -#### **System Utilities** - -| Tool | Purpose | Installation | -|------|---------|--------------| -| **ripgrep (rg)** | Fast code search | [Download](https://github.com/BurntSushi/ripgrep/releases) or `brew install ripgrep` (macOS), `apt install ripgrep` (Ubuntu) | -| **jq** | JSON processing | [Download](https://jqlang.github.io/jq/download/) or `brew install jq` (macOS), `apt install jq` (Ubuntu) | - -**Quick Install (All Tools):** - -```bash -# macOS -brew install ripgrep jq -npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code - -# Ubuntu/Debian -sudo apt install ripgrep jq -npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code - -# Windows (Chocolatey) -choco install ripgrep jq -npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code -``` - -### **Essential: Gemini CLI Setup** - -Configure Gemini CLI for optimal integration: - -```json -// ~/.gemini/settings.json -{ - "contextFileName": ["CLAUDE.md", "GEMINI.md"] -} -``` - -### **Recommended: .geminiignore** - -Optimize performance by excluding unnecessary files: - -```bash -# .geminiignore (in project root) -/dist/ -/build/ -/node_modules/ -/.next/ -*.tmp -*.log -/temp/ - -# Include important docs -!README.md -!**/CLAUDE.md -``` - -### **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. - -#### Available MCP Servers - -| MCP Server | Purpose | Installation Guide | -|------------|---------|-------------------| -| **Exa MCP** | External API patterns & best practices | [Install Guide](https://smithery.ai/server/exa) | -| **Code Index MCP** | Advanced internal code search | [Install Guide](https://github.com/johnhuang316/code-index-mcp) | -| **Chrome DevTools MCP** | ⚠️ **Required for UI workflows** - URL mode design extraction | [Install Guide](https://github.com/ChromeDevTools/chrome-devtools-mcp) | - -#### Benefits When Enabled -- 📊 **Faster Analysis**: Direct codebase indexing vs manual searching -- 🌐 **External Context**: Real-world API patterns and examples -- 🔍 **Advanced Search**: Pattern matching and similarity detection -- ⚡ **Better Reliability**: Primary tools for certain workflows -- 🎨 **UI Workflows**: Chrome DevTools enables pixel-perfect design extraction from live URLs - -⚠️ **Note**: Some workflows expect MCP tools to be available. Without them, you may experience: -- Slower code analysis and search operations -- Reduced context quality in some scenarios -- Fallback to less efficient traditional tools -- Potential unexpected behavior in advanced workflows - ---- - -## 🎯 Agent Skills - -**Agent Skills** extend Claude's capabilities with modular, reusable expertise packages. Skills are automatically discovered and triggered based on context. - -### **Available Skills** - -#### **Prompt Enhancer** -Transform vague prompts into structured, actionable specifications. - -**Usage**: Add `-e` or `--enhance` flag to any request -```bash -# Example -fix authentication issue -e -optimize database queries --enhance -``` - -**What it does**: -- Analyzes session context and tech stack -- Structures intent into INTENT → ACTION format -- Adds relevant context, constraints, and metrics -- Outputs ready-to-execute specifications - -**Output**: Dynamic structured prompt adapted to task type (simple tasks get minimal fields, complex tasks get comprehensive specifications) - -### **Creating Custom Skills** - -Skills are stored in `.claude/skills/` (project) or `~/.claude/skills/` (personal): - -```bash -# Create a new skill -mkdir -p .claude/skills/my-skill -``` - -**SKILL.md structure**: -```yaml ---- -name: My Skill Name -description: What it does and when to use it. Use when [trigger conditions]. -allowed-tools: Read, Grep, Glob # Optional tool restrictions ---- - -# My Skill Name - -## Instructions -[Step-by-step guidance for Claude] - -## Examples -[Concrete usage examples] -``` - -**Best Practices**: -- Write specific descriptions with clear trigger conditions -- Include both what the skill does and when to use it -- Keep skills focused on single capabilities -- Test by asking questions that match your description - -For complete documentation, see [skills.md](skills.md). - ---- - -## 🚀 Getting Started - -### Complete Development Workflow - -**Phase 1: Brainstorming & Conceptual Planning** -```bash -# Multi-perspective brainstorming with role-based agents -/workflow:brainstorm:auto-parallel "Build a user authentication system" - -# Review and refine specific aspects (optional) -/workflow:brainstorm:ui-designer "authentication flows" -/workflow:brainstorm:synthesis # Generate consolidated specification -``` - -**Phase 1.5: Concept Verification** *(Optional Quality Gate)* -```bash -# Identify and resolve ambiguities in brainstorming artifacts -/workflow:concept-clarify - -# OR specify session explicitly -/workflow:concept-clarify --session WFS-auth -``` -- Runs after `/workflow:brainstorm:synthesis` and before `/workflow:plan` -- Interactive Q&A to clarify underspecified requirements, architecture decisions, or risks -- Maximum 5 questions per session with multiple-choice or short-answer format -- Updates `synthesis-specification.md` with clarifications incrementally -- Ensures conceptual foundation is clear before detailed planning -- Generates coverage summary with recommendations to proceed or address outstanding items - -**Phase 2: UI Design Refinement** *(Optional for UI-heavy projects)* - -**🎯 Choose Your Workflow:** - -**Scenario 1: Starting from an idea or concept** → Use `explore-auto` -```bash -# Generate multiple style and layout options to explore different directions -/workflow:ui-design:explore-auto --prompt "Modern blog: home, article, author" --style-variants 3 --layout-variants 2 -# Creates a 3×2 matrix: 3 visual styles × 2 layouts = 6 prototypes to choose from -``` - -**Scenario 2: Replicating an existing design** → Use `imitate-auto` -```bash -# Fast, high-fidelity replication of reference designs -/workflow:ui-design:imitate-auto --images "refs/design.png" --pages "dashboard,settings" -# Or auto-screenshot from URL (requires Playwright/Chrome DevTools MCP) -/workflow:ui-design:imitate-auto --url "https://linear.app" --pages "home,features" -``` - -**Scenario 3: Batch creation from existing design system** → Use `batch-generate` -```bash -# Already have a design system? Generate multiple pages quickly -/workflow:ui-design:batch-generate --prompt "Create profile and settings pages" --layout-variants 2 -``` - -**Advanced: Manual Step-by-Step Control** (v4.4.0+) -```bash -# 1. Extract visual style (colors, typography, spacing) -/workflow:ui-design:style-extract --images "refs/*.png" --mode explore --variants 3 - -# 2. Consolidate into production-ready design tokens -/workflow:ui-design:consolidate --variants "variant-1,variant-3" - -# 3. Extract layout structure (DOM, CSS layout rules) -/workflow:ui-design:layout-extract --targets "dashboard,auth" --mode explore --variants 2 --device-type responsive - -# 4. Combine style + layout → HTML/CSS prototypes -/workflow:ui-design:generate --style-variants 1 --layout-variants 2 - -# 5. Preview and select -cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080 -# Visit http://localhost:8080/compare.html for side-by-side comparison - -# 6. Integrate selected design into project -/workflow:ui-design:update --session WFS-auth --selected-prototypes "dashboard-s1-l2" -``` - -**Phase 3: Action Planning** -```bash -# Create executable implementation plan -/workflow:plan "Implement JWT-based authentication system" - -# OR for TDD approach -/workflow:tdd-plan "Implement authentication with test-first development" -``` - -**Phase 3.5: Action Plan Verification** *(Optional Pre-Execution Check)* -```bash -# Validate plan consistency and completeness -/workflow:action-plan-verify - -# OR specify session explicitly -/workflow:action-plan-verify --session WFS-auth -``` -- Runs after `/workflow:plan` or `/workflow:tdd-plan` and before `/workflow:execute` -- Read-only analysis of `IMPL_PLAN.md` and task JSON files against `synthesis-specification.md` -- Validates requirements coverage, dependency integrity, and synthesis alignment -- Identifies inconsistencies, duplications, ambiguities, and underspecified items -- Generates detailed verification report with severity-rated findings (CRITICAL/HIGH/MEDIUM/LOW) -- Recommends whether to PROCEED, PROCEED_WITH_FIXES, or BLOCK_EXECUTION -- Provides actionable remediation suggestions for detected issues - -**Phase 4: Execution** -```bash -# Execute tasks with AI agents -/workflow:execute - -# Monitor progress -/workflow:status -``` - -**Phase 5: Testing & Quality Assurance** -```bash -# Generate independent test-fix workflow (v3.2.2+) -/workflow:test-gen WFS-auth # Creates WFS-test-auth session -/workflow:test-cycle-execute # Execute test-fix cycle with dynamic iteration - -# Resume interrupted test session -/workflow:test-cycle-execute --resume-session="WFS-test-auth" - -# OR verify TDD compliance (TDD workflow) -/workflow:tdd-verify -``` - -**What is `/workflow:test-cycle-execute`?** -- **Dynamic Task Generation**: Creates intermediate fix tasks based on test failures during execution -- **Iterative Testing**: Automatically runs test-fix cycles until all tests pass or max iterations reached -- **CLI-Driven Analysis**: Uses Gemini/Qwen to analyze failures and generate fix strategies -- **Agent Coordination**: Delegates test execution and fixes to `@test-fix-agent` -- **Autonomous Completion**: Continues until success without user interruption - -### Quick Start for Simple Tasks - -**Feature Development:** -```bash -/workflow:session:start "Add password reset feature" -/workflow:plan "Email-based password reset with token expiry" -/workflow:execute -``` - -**Bug Fixing:** -```bash -# Interactive analysis with CLI tools -/cli:mode:bug-index --tool gemini "Login timeout on mobile devices" - -# Execute the suggested fix -/workflow:execute -``` - -> **💡 When to Use Which Approach?** -> -> **Use `/workflow:plan` + `/workflow:execute` for:** -> - Complex features requiring multiple modules (>3 modules) -> - Tasks with multiple subtasks (>5 subtasks) -> - Cross-cutting changes affecting architecture -> - Features requiring coordination between components -> - When you need structured planning and progress tracking -> -> **Use Claude Code directly for:** -> - Simple, focused changes (single file or module) -> - Quick bug fixes with clear solutions -> - Documentation updates -> - Code refactoring within one component -> - Straightforward feature additions - -**Code Analysis:** -```bash -# Deep codebase analysis -/cli:mode:code-analysis --tool qwen "Analyze authentication module architecture" -``` +If the slash commands (e.g., `/workflow:*`) are recognized, the installation was successful. --- ## 🛠️ Command Reference -### **Unified CLI Commands (`/cli:*)** -*Use the `--tool ` flag to select the desired tool. Defaults to `gemini`.* - -| Command | Description | -|---|---| -| `/cli:analyze` | Deep codebase analysis. | -| `/cli:chat` | Direct, interactive chat with a tool. | -| `/cli:execute` | Execute a task with full permissions. | -| `/cli:cli-init`| Initialize CLI tool configurations for the workspace. | -| `/cli:mode:bug-index` | Analyze bugs and suggest fixes. | -| `/cli:mode:code-analysis` | Perform deep code analysis and debugging. | -| `/cli:mode:plan` | Project planning and architecture analysis. | - -### **Workflow Commands (`/workflow:*)** - -| Command | Description | -|---|---| -| `/workflow:session:*` | Manage development sessions (`start`, `resume`, `list`, `complete`). | -| `/workflow:brainstorm:*` | Use role-based agents for multi-perspective planning. | -| `/workflow:concept-clarify` | **Optional** Quality gate - Identify and resolve ambiguities in brainstorming artifacts before planning (runs after synthesis, before plan). | -| `/workflow:ui-design:explore-auto` | **v4.4.0** Matrix exploration mode - Generate multiple style × layout variants with layout/style separation. | -| `/workflow:ui-design:imitate-auto` | **v4.4.0** Fast imitation mode - Rapid UI replication with auto-screenshot, layout extraction, and assembly. | -| `/workflow:ui-design:style-extract` | **v4.4.0** Extract visual style (colors, typography, spacing) from images/text using Claude-native analysis. | -| `/workflow:ui-design:layout-extract` | **v4.4.0** Extract structural layout (DOM, CSS layout rules) with device-aware templates. | -| `/workflow:ui-design:consolidate` | **v4.4.0** Consolidate style variants into validated design tokens using Claude synthesis. | -| `/workflow:ui-design:generate` | **v4.4.0** Pure assembler - Combine layout templates + design tokens → HTML/CSS prototypes. | -| `/workflow:ui-design:update` | **v4.4.0** Integrate finalized design system into brainstorming artifacts. | -| `/workflow:plan` | Create a detailed, executable plan from a description. | -| `/workflow:tdd-plan` | Create TDD workflow (6 phases) with test coverage analysis and Red-Green-Refactor cycles. | -| `/workflow:action-plan-verify` | **Optional** Pre-execution check - Validate IMPL_PLAN.md and task.json consistency and completeness (runs after plan, before execute). | -| `/workflow:execute` | Execute the current workflow plan autonomously. | -| `/workflow:status` | Display the current status of the workflow. | -| `/workflow:test-gen [--use-codex] ` | Create test generation workflow with auto-diagnosis and fix cycle for completed implementations. | -| `/workflow:test-cycle-execute` | **v4.5.0** Execute test-fix workflow with dynamic task generation and iterative fix cycles. Runs tests → analyzes failures with CLI → generates fix tasks → retests until success. | -| `/workflow:tdd-verify` | Verify TDD compliance and generate quality report. | -| `/workflow:review` | **Optional** manual review (only use when explicitly needed - passing tests = approved code). | -| `/workflow:tools:test-context-gather` | Analyze test coverage and identify missing test files. | -| `/workflow:tools:test-concept-enhanced` | Generate test strategy and requirements analysis using Gemini. | -| `/workflow:tools:test-task-generate` | Generate test task JSON with test-fix-cycle specification. | - -### **UI Design Workflow Commands (`/workflow:ui-design:*`)** *(v4.4.0)* - -The design workflow system provides complete UI design refinement with **layout/style separation architecture**, **pure Claude execution**, **intelligent target inference**, and **zero external dependencies**. - -⚠️ **For URL-based design extraction**: Install [Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) to enable auto-extraction of computed styles and DOM structure from live URLs. Falls back to visual analysis if unavailable. - -#### 📐 Architecture Overview - -The UI workflow follows a **separation of concerns** philosophy: -- **Style (Visual Tokens)**: Colors, typography, spacing, borders → `design-tokens.json` -- **Layout (Structure)**: DOM hierarchy, CSS layout rules → `layout-templates.json` -- **Assembly**: Pure combination of style + layout → HTML/CSS prototypes - -**Command Categories:** - -| Category | Commands | Purpose | -|----------|----------|---------| -| **High-Level Orchestrators** | `explore-auto`, `imitate-auto`, `batch-generate` | Complete workflows (recommended) | -| **Input/Capture** | `capture`, `explore-layers` | Screenshot acquisition | -| **Analysis/Extraction** | `style-extract`, `layout-extract` | Visual style and structural layout extraction | -| **Processing/Generation** | `consolidate`, `generate` | Token validation and prototype assembly | -| **Integration** | `update` | Design system integration into project | - -#### 🧭 Decision Tree: Which Command Should I Use? - -``` -┌─ Have an idea or text description? -│ └─→ /workflow:ui-design:explore-auto -│ (Explores multiple style × layout options) -│ -┌─ Want to replicate an existing design? -│ └─→ /workflow:ui-design:imitate-auto -│ (High-fidelity single design replication) -│ -┌─ Already have a design system? -│ └─→ /workflow:ui-design:batch-generate -│ (Batch create multiple pages/components) -│ -└─ Need fine-grained control? - └─→ Use individual commands in sequence: - 1. style-extract → Extract colors, fonts, spacing - 2. consolidate → Validate and merge tokens - 3. layout-extract → Extract DOM structure - 4. generate → Combine into prototypes - 5. update → Integrate into project -``` - -#### 🔄 Workflow Diagrams - -**Explore Workflow** (Idea → Multiple Designs): -``` -Prompt/Images → style-extract (explore mode) - ↓ - consolidate (N variants) - ↓ - layout-extract (explore mode) - ↓ - generate (N styles × M layouts) - ↓ - update (selected designs) -``` - -**Imitate Workflow** (Reference → Single Design): -``` -URL/Images → capture/explore-layers - ↓ - style-extract (imitate mode) - ↓ - layout-extract (imitate mode) - ↓ - consolidate (single variant) - ↓ - generate (1 style × 1 layout) - ↓ - update (final design) -``` - -#### Core Commands - -**`/workflow:ui-design:explore-auto`** - Matrix exploration mode -```bash -# Comprehensive exploration - multiple style × layout variants -/workflow:ui-design:explore-auto --prompt "Modern blog: home, article, author" --style-variants 3 --layout-variants 2 - -# With images and session integration -/workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png" --style-variants 2 --layout-variants 3 - -# Text-only mode with page inference -/workflow:ui-design:explore-auto --prompt "E-commerce: home, product, cart" --style-variants 2 --layout-variants 2 -``` -- **🎯 Matrix Mode**: Generate all style × layout combinations -- **📊 Comprehensive Exploration**: Compare multiple design directions -- **🔍 Interactive Comparison**: Side-by-side comparison with viewport controls -- **✅ Cross-page Validation**: Automatic consistency checks for multi-page designs -- **⚡ Batch Selection**: Quick selection by style or layout - -**`/workflow:ui-design:imitate-auto`** - Fast imitation mode -```bash -# Rapid single-design replication -/workflow:ui-design:imitate-auto --images "refs/design.png" --pages "dashboard,settings" - -# With session integration -/workflow:ui-design:imitate-auto --session WFS-auth --images "refs/ui.png" --pages "home,product" - -# Auto-screenshot from URL (requires Playwright) -/workflow:ui-design:imitate-auto --url "https://example.com" --pages "landing" -``` -- **⚡ Speed Optimized**: 5-10x faster than explore-auto -- **📸 Auto-Screenshot**: Automatic URL screenshot capture with Playwright/Chrome -- **🎯 Direct Extraction**: Skip variant selection, go straight to implementation -- **🔧 Single Design Focus**: Best for copying existing designs quickly - -**`/workflow:ui-design:style-extract`** - Visual style extraction (v4.4.0) -```bash -# Pure text prompt -/workflow:ui-design:style-extract --prompt "Modern minimalist, dark theme" --mode explore --variants 3 - -# Pure images -/workflow:ui-design:style-extract --images "refs/*.png" --mode explore --variants 3 - -# Hybrid (text guides image analysis) -/workflow:ui-design:style-extract --images "refs/*.png" --prompt "Linear.app style" --mode imitate - -# High-fidelity single style -/workflow:ui-design:style-extract --images "design.png" --mode imitate -``` -- **🎨 Visual Tokens Only**: Colors, typography, spacing (no layout structure) -- **🔄 Dual Mode**: Imitate (single variant) / Explore (multiple variants) -- **Claude-Native**: Single-pass analysis, no external tools -- **Output**: `style-cards.json` with embedded `proposed_tokens` - -**`/workflow:ui-design:layout-extract`** - Structural layout extraction (v4.4.0) -```bash -# Explore mode - multiple layout variants -/workflow:ui-design:layout-extract --targets "home,dashboard" --mode explore --variants 3 --device-type responsive - -# Imitate mode - single layout replication -/workflow:ui-design:layout-extract --images "refs/*.png" --targets "dashboard" --mode imitate --device-type desktop - -# With MCP research (explore mode) -/workflow:ui-design:layout-extract --prompt "E-commerce checkout" --targets "cart,checkout" --mode explore --variants 2 -``` -- **🏗️ Structure Only**: DOM hierarchy, CSS layout rules (no visual style) -- **📱 Device-Aware**: Desktop, mobile, tablet, responsive optimizations -- **🧠 Agent-Powered**: Uses ui-design-agent for structural analysis -- **🔍 MCP Research**: Layout pattern inspiration (explore mode) -- **Output**: `layout-templates.json` with token-based CSS - -**`/workflow:ui-design:consolidate`** - Validate and merge tokens -```bash -# Consolidate selected style variants -/workflow:ui-design:consolidate --session WFS-auth --variants "variant-1,variant-3" -``` -- **Claude Synthesis**: Single-pass generation of all design system files -- **Features**: WCAG AA validation, OKLCH colors, W3C token format -- **Output**: `design-tokens.json`, `style-guide.md`, `tailwind.config.js`, `validation-report.json` - -**`/workflow:ui-design:generate`** - Pure assembler (v4.4.0) -```bash -# Combine layout templates + design tokens -/workflow:ui-design:generate --style-variants 1 --layout-variants 2 - -# Multiple styles with multiple layouts -/workflow:ui-design:generate --style-variants 2 --layout-variants 3 -``` -- **📦 Pure Assembly**: Combines pre-extracted layout-templates.json + design-tokens.json -- **❌ No Design Logic**: All layout/style decisions made in previous phases -- **✅ Token Resolution**: Replaces var() placeholders with actual token values -- **🎯 Matrix Output**: Generates style × layout × targets prototypes -- **🔍 Interactive Preview**: `compare.html` with side-by-side comparison - -**`/workflow:ui-design:update`** - Integrate design system -```bash -# Update brainstorming artifacts with design system -/workflow:ui-design:update --session WFS-auth --selected-prototypes "login-variant-1" -``` -- **Updates**: `synthesis-specification.md`, `ui-designer/style-guide.md` -- **Makes design tokens available for task generation** - -#### Preview System - -After running `ui-generate`, you get interactive preview tools that **work directly in the browser without requiring a server**: - -**Direct Browser Preview** (Recommended - No Server Required): -```bash -# Navigate to prototypes directory -cd .workflow/WFS-auth/.design/prototypes - -# Open in browser (double-click the file, or use command): -open index.html # macOS -start index.html # Windows -xdg-open index.html # Linux - -# Both index.html and compare.html work directly without a server -open compare.html # Open comparison view directly -``` - -**Optional: Local Server** (For advanced features): -```bash -cd .workflow/WFS-auth/.design/prototypes -# Choose one if you need server-side features: -python -m http.server 8080 # Python -npx http-server -p 8080 # Node.js -php -S localhost:8080 # PHP -# Visit: http://localhost:8080 -``` - -**Preview Features**: -- `index.html`: Master navigation with all prototypes (works offline) -- `compare.html`: Side-by-side comparison with viewport controls (works offline) -- Synchronized scrolling for layout comparison -- Dynamic page switching -- Real-time responsive testing -- **No server required** - all features work by opening files directly in browser - -#### 📦 Output Structure - -All UI workflow outputs are organized in the `.design` directory within your session: - -``` -.workflow/WFS-/.design/ -├── design-run-YYYYMMDD-HHMMSS/ # Timestamped design run -│ ├── screenshots/ # 📸 Captured screenshots -│ │ ├── home.png -│ │ └── dashboard.png -│ │ -│ ├── style-extraction/ # 🎨 Style analysis phase -│ │ ├── style-cards.json # AI-proposed style variants -│ │ └── design-space-analysis.json # (explore mode) Diversity analysis -│ │ -│ ├── layout-extraction/ # 🏗️ Layout analysis phase -│ │ └── layout-templates.json # Structural templates with token-based CSS -│ │ -│ ├── style-consolidation/ # ✅ Production design systems -│ │ ├── style-1/ -│ │ │ ├── design-tokens.json # W3C design tokens -│ │ │ ├── style-guide.md # Visual design documentation -│ │ │ ├── tailwind.config.js # Tailwind configuration -│ │ │ └── validation-report.json # WCAG AA validation results -│ │ └── style-2/ -│ │ └── ... -│ │ -│ └── prototypes/ # 🎯 Final HTML/CSS prototypes -│ ├── home-style-1-layout-1.html # Matrix-generated prototypes -│ ├── home-style-1-layout-1.css -│ ├── home-style-1-layout-2.html -│ ├── dashboard-style-2-layout-1.html -│ ├── index.html # Master navigation page -│ └── compare.html # Side-by-side comparison tool -│ -└── latest -> design-run-YYYYMMDD-HHMMSS # Symlink to most recent run -``` - -**Key Files:** - -| File | Purpose | Generated By | -|------|---------|--------------| -| `style-cards.json` | AI-proposed visual styles with embedded tokens | `style-extract` | -| `layout-templates.json` | Structural templates with token-based CSS | `layout-extract` | -| `design-tokens.json` | Production-ready W3C design tokens | `consolidate` | -| `style-guide.md` | Visual design system documentation | `consolidate` | -| `compare.html` | Interactive prototype comparison matrix | `generate` | - -**Best Practices:** - -1. **Session Management**: All runs within a session accumulate in `.design/design-run-*/` -2. **Versioning**: Each run is timestamped for easy rollback -3. **Integration**: Use `update` command to link final tokens to project artifacts -4. **Cleanup**: Old runs can be safely deleted; `latest` symlink always points to newest +CCW provides a rich set of commands for managing workflows, tasks, and interacting with AI tools. For a complete list and detailed descriptions of all available commands, please see the [**COMMAND_REFERENCE.md**](COMMAND_REFERENCE.md) file. --- -### **Task & Memory Commands** +## 🚀 Getting Started -| Command | Description | -|---|---| -| `/task:*` | Manage individual tasks (`create`, `breakdown`, `execute`, `replan`). | -| `/update-memory-full` | Re-index the entire project documentation. | -| `/update-memory-related` | Update documentation related to recent changes. | -| `/version` | Display version information and check for updates from GitHub. | +The best way to get started is to follow the 5-minute tutorial in the [**Getting Started Guide**](GETTING_STARTED.md). ---- +Here is a quick example of a common development workflow: -## 🧠 Memory Management: Foundation of Context Quality - -CCW's hierarchical memory system enables accurate context gathering and prevents execution drift. Regular updates are critical for high-quality AI outputs. - -#### **Memory Hierarchy** - -``` -CLAUDE.md (Root) → domain/CLAUDE.md (Domain) → module/CLAUDE.md (Module) → submodule/CLAUDE.md (Sub-Module) -``` - -#### **When to Update** - -| Trigger | Command | Purpose | -|---------|---------|---------| -| After major features | `/update-memory-related` | Update affected modules/dependencies | -| After architecture changes | `/update-memory-full` | Re-index entire project | -| Before complex planning | `/update-memory-related` | Ensure latest patterns in context-package.json | -| After refactoring | `/update-memory-related` | Update implementation patterns/APIs | -| Weekly maintenance | `/update-memory-full` | Keep docs synchronized | - -#### **Quality Impact** - -**Without updates:** ❌ Outdated patterns, deprecated APIs, incorrect context, architecture drift -**With updates:** ✅ Current patterns, latest APIs, accurate context, architecture alignment - -#### **Best Practices** - -1. Update immediately after significant changes -2. Use `/update-memory-related` frequently (faster, targeted) -3. Schedule `/update-memory-full` weekly (catches drift) -4. Review generated CLAUDE.md files -5. Integrate into CI/CD pipelines - -> 💡 Memory quality determines context-package.json quality and execution accuracy. Treat as critical maintenance, not optional docs. - -#### **Tool Integration** - -```bash -/update-memory-full --tool gemini # Comprehensive analysis (default) -/update-memory-full --tool qwen # Architecture focus -/update-memory-full --tool codex # Implementation details -``` - ---- - -## 🏗️ Technical Architecture - -Complete, self-documenting system for orchestrating AI agents with professional software engineering practices. - -### **Project Organization** - -``` -.claude/ -├── agents/ # Specialized AI agents (action-planning, code-developer, test-fix) -├── commands/ # User-facing and internal commands (workflow:*, cli:*, task:*) -├── workflows/ # Strategic framework (architecture, strategies, schemas, templates) -├── scripts/ # Utility automation (module analysis, file watching) -└── prompt-templates/# Standardized AI prompts -``` - -**Principles:** Separation of concerns (agents/commands/workflows), hierarchical commands, self-documenting, extensible templates - -### **Execution Model** - -``` -User Command → Orchestrator → Phase 1-4 (Context → Analysis → Planning → Execution) - ↓ - Specialized Agents (pre_analysis → implementation → validation) -``` - -**Example:** `/workflow:plan "Build auth"` → session:start → context-gather → concept-enhanced → task-generate - ---- - -## 🧩 How It Works: Design Philosophy - -### The Core Problem - -Traditional AI coding workflows face a fundamental challenge: **execution uncertainty leads to error accumulation**. - -**Example:** -```bash -# Prompt 1: "Develop XX feature" -# Prompt 2: "Review XX architecture in file Y, then develop XX feature" -``` - -While Prompt 1 might succeed for simple tasks, in complex workflows: -- The AI may examine different files each time -- Small deviations compound across multiple steps -- Final output drifts from the intended goal - -> **CCW's Mission**: Solve the "1-to-N" problem — building upon existing codebases with precision, not just "0-to-1" greenfield development. - ---- - -### The CCW Solution: Context-First Architecture - -#### 1. **Pre-defined Context Gathering** - -Instead of letting agents randomly explore, CCW uses structured context packages: - -**`context-package.json`** created during planning: -```json -{ - "metadata": { - "task_description": "...", - "tech_stack": {"frontend": [...], "backend": [...]}, - "complexity": "high" - }, - "assets": [ - { - "path": "synthesis-specification.md", - "priority": "critical", - "sections": ["Backend Module Structure"] - } - ], - "implementation_guidance": { - "start_with": ["Step 1", "Step 2"], - "critical_security_items": [...] - } -} -``` - -#### 2. **JSON-First Task Model** - -Each task includes a `flow_control.pre_analysis` section: - -```json -{ - "id": "IMPL-1", - "flow_control": { - "pre_analysis": [ - { - "step": "load_architecture", - "commands": ["Read(architecture.md)", "grep 'auth' src/"], - "output_to": "arch_context", - "on_error": "fail" - } - ], - "implementation_approach": { - "modification_points": ["..."], - "logic_flow": ["..."] - }, - "target_files": ["src/auth/index.ts"] - } -} -``` - -**Key Innovation**: The `pre_analysis` steps are **executed before implementation**, ensuring agents always have the correct context. - -#### 3. **Multi-Phase Orchestration** - -CCW workflows are orchestrators that coordinate slash commands: - -**Planning Phase** (`/workflow:plan`): -``` -Phase 1: session:start → Create session -Phase 2: context-gather → Build context-package.json -Phase 3: concept-enhanced → CLI analysis (Gemini/Qwen) -Phase 4: task-generate → Generate task JSONs with pre_analysis -``` - -**Execution Phase** (`/workflow:execute`): -``` -For each task: - 1. Execute pre_analysis steps → Load context - 2. Apply implementation_approach → Make changes - 3. Validate acceptance criteria → Verify success - 4. Generate summary → Track progress -``` - -#### 4. **Multi-Model Orchestration** - -Each AI model serves its strength: - -| Model | Role | Use Cases | -|-------|------|-----------| -| **Gemini** | Analysis & Understanding | Long-context analysis, architecture review, bug investigation | -| **Qwen** | Architecture & Design | System design, code generation, architectural planning | -| **Codex** | Implementation | Feature development, testing, autonomous execution | - -**Example:** -```bash -# Gemini analyzes the problem space -/cli:mode:code-analysis --tool gemini "Analyze auth module" - -# Qwen designs the solution -/cli:analyze --tool qwen "Design scalable auth architecture" - -# Codex implements the code -/workflow:execute # Uses @code-developer with Codex -``` - ---- - -### From 0-to-1 vs 1-to-N Development - -| Scenario | Traditional Workflow | CCW Approach | -|----------|---------------------|--------------| -| **Greenfield (0→1)** | ✅ Works well | ✅ Adds structured planning | -| **Feature Addition (1→2)** | ⚠️ Context uncertainty | ✅ Context-package links to existing code | -| **Bug Fixing (N→N+1)** | ⚠️ May miss related code | ✅ Pre-analysis finds dependencies | -| **Refactoring** | ⚠️ Unpredictable scope | ✅ CLI analysis + structured tasks | - ---- - -### Key Workflows - -#### **Complete Development (Brainstorm → Deploy)** -``` -Brainstorm (8 roles) → Synthesis → Plan (4 phases) → Execute → Test → Review -``` - -#### **Quick Feature Development** -``` -session:start → plan → execute → test-gen → execute -``` - -#### **TDD Workflow** -``` -tdd-plan (TEST→IMPL→REFACTOR chains) → execute → tdd-verify -``` - -#### **Bug Fixing** -``` -cli:mode:bug-index (analyze) → execute (fix) → test-gen (verify) -``` +1. **Start a Session**: + ```bash + /workflow:session:start "Implement user login feature" + ``` +2. **Create a Plan**: + ```bash + /workflow:plan "Implement JWT-based user login and registration" + ``` +3. **Execute the Plan**: + ```bash + /workflow:execute + ``` --- @@ -1084,4 +94,4 @@ cli:mode:bug-index (analyze) → execute (fix) → test-gen (verify) ## 📄 License -This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details. +This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details. \ No newline at end of file diff --git a/README_CN.md b/README_CN.md index 0524ee81..97df0056 100644 --- a/README_CN.md +++ b/README_CN.md @@ -5,7 +5,7 @@ [![Version](https://img.shields.io/badge/version-v4.6.0-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases) [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)]() -[![MCP工具](https://img.shields.io/badge/🔧_MCP工具-实验性-orange.svg)](https://github.com/modelcontextprotocol) +[![MCP Tools](https://img.shields.io/badge/🔧_MCP_Tools-Experimental-orange.svg)](https://github.com/modelcontextprotocol) **语言:** [English](README.md) | [中文](README_CN.md) @@ -13,59 +13,31 @@ --- -**Claude Code Workflow (CCW)** 将 AI 开发从简单提示词链接转变为强大的上下文优先编排系统。通过结构化规划、确定性执行和智能多模型编排，解决执行不确定性和误差累积问题。 +**Claude Code Workflow (CCW)** 将 AI 开发从简单的提示词链接转变为一个强大的、上下文优先的编排系统。它通过结构化规划、确定性执行和智能多模型编排，解决了执行不确定性和误差累积的问题。 > **🎉 最新版本: v4.6.0** - 概念澄清与智能体驱动分析。详见 [CHANGELOG.md](CHANGELOG.md)。 -> -> **v4.6.0 版本新特性**: -> - 🎯 **概念澄清质量关卡**: 任务生成前通过交互式问答解决歧义（Phase 3.5） -> - 🤖 **智能体委托分析**: Phase 3 现使用 cli-execution-agent 进行自主上下文发现 -> - 🔄 **双模式支持**: concept-clarify 自动检测头脑风暴 vs 规划工作流 -> - 📚 **测试循环执行**: 增强了动态测试修复迭代工作流的文档说明 -> - ✨ **向后兼容**: 所有增强功能保留现有工作流功能 - ---- > 📚 **第一次使用 CCW？** 查看 [**快速上手指南**](GETTING_STARTED_CN.md) 获取新手友好的 5 分钟教程！ --- -## ✨ 核心差异化特性 +## ✨ 核心概念 -#### **1. 上下文优先架构** 🎯 -通过 `context-package.json` 和 `flow_control.pre_analysis` 预定义上下文收集，消除执行不确定性。智能体在实现**前**加载正确上下文，解决"1到N"开发漂移问题。 +CCW 构建在一系列核心原则之上，这些原则使其与传统的 AI 开发方法区别开来： -#### **2. JSON 优先状态管理** 📋 -任务状态存于 `.task/IMPL-*.json`（单一事实来源），Markdown 为只读视图。数据与表现分离，实现程序化编排无状态漂移。 - -#### **3. 自主多阶段编排** 🔄 -`/workflow:plan` 等命令链接专用子命令（会话 → 上下文 → 分析 → 任务），零用户干预。`flow_control` 机制创建带步骤依赖的可执行"程序"。 - -#### **4. 多模型战略编排** 🧠 -- **Gemini/Qwen**：分析、探索、文档（大上下文） -- **Codex**：实现、自主执行（`resume --last` 保持上下文） -- **结果**：比单模型方法任务处理提升 5-10 倍 - -#### **5. 分层内存系统** 🧬 -4 层文档（根 → 领域 → 模块 → 子模块）在适当抽象级别提供上下文，防止信息过载并保持精确性。 - -#### **6. 专用基于角色的智能体** 🤖 -专用智能体镜像真实软件团队：`@action-planning-agent`、`@code-developer`、`@test-fix-agent`、`@ui-design-agent`。包含 TDD 工作流（Red-Green-Refactor）、UI 设计（布局/样式分离）和自动 QA。 - ---- - -### **其他特性** - -- **✅ 执行前验证**：质量关卡（`/workflow:concept-clarify`、`/workflow:action-plan-verify`） -- **🔧 统一 CLI**：`/cli:*` 命令支持多工具（`--tool gemini|qwen|codex`） -- **📦 智能上下文包**：链接任务到相关代码和外部示例 -- **🎨 UI 设计工作流**：Claude 原生样式/布局提取，零依赖 -- **🔄 渐进式增强**：可选工具扩展能力，纯 Claude 模式开箱即用 +- **上下文优先架构**: 通过预定义的上下文收集，消除了执行过程中的不确定性，确保智能体在实现*之前*就拥有正确的信息。 +- **JSON 优先的状态管理**: 任务状态完全存储在 `.task/IMPL-*.json` 文件中，作为唯一的事实来源，实现了无需状态漂移的程序化编排。 +- **自主多阶段编排**: 命令链式调用专门的子命令和智能体，以零用户干预的方式自动化复杂的工作流。 +- **多模型策略**: 充分利用不同 AI 模型（如 Gemini 用于分析，Codex 用于实现）的独特优势，以获得更优越的结果。 +- **分层内存系统**: 一个 4 层文档系统，在适当的抽象级别上提供上下文，防止信息过载。 +- **专门的基于角色的智能体**: 一套模拟真实软件团队的智能体（`@code-developer`, `@test-fix-agent` 等），用于处理多样化的任务。 --- ## ⚙️ 安装 +有关详细的安装说明，请参阅 [**INSTALL_CN.md**](INSTALL_CN.md) 指南。 + ### **🚀 一键快速安装** **Windows (PowerShell):** @@ -78,1001 +50,39 @@ Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/cat bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.sh) ``` -### **📋 交互式版本选择** - -运行安装命令后，您将看到包含实时版本信息的交互式菜单： - -``` -正在检测最新版本和提交... -最新稳定版: v3.2.0 (2025-10-02 04:27 UTC) -最新提交: cdea58f (2025-10-02 08:15 UTC) - -==================================================== - 版本选择菜单 -==================================================== - -1) 最新稳定版（推荐） - |-- 版本: v3.2.0 - |-- 发布时间: 2025-10-02 04:27 UTC - \-- 生产就绪 - -2) 最新开发版 - |-- 分支: main - |-- 提交: cdea58f - |-- 更新时间: 2025-10-02 08:15 UTC - |-- 最新功能 - \-- 可能包含实验性更改 - -3) 指定版本 - |-- 安装特定标签版本 - \-- 最近版本: v3.2.0, v3.1.0, v3.0.1 - -==================================================== - -选择要安装的版本 (1-3, 默认: 1): -``` - -**版本选项：** -- **选项 1（推荐）**：经过验证的最新稳定版本，生产环境可用 -- **选项 2**：来自 main 分支的最新开发版本，包含最新功能 -- **选项 3**：指定版本标签，用于受控部署 - -> 💡 **提示**：安装程序会自动从 GitHub 检测并显示最新的版本号和发布日期。只需按 Enter 键即可选择推荐的稳定版本。 - -### **📦 本地安装 (Install-Claude.ps1)** - -无需网络访问时，使用内置的 PowerShell 安装脚本： - -**安装模式：** -```powershell -# 交互式安装（推荐） -.\Install-Claude.ps1 - -# 快速安装（自动备份） -.\Install-Claude.ps1 -Force -BackupAll - -# 非交互式安装 -.\Install-Claude.ps1 -NonInteractive -Force -``` - -**安装选项：** - -| 模式 | 描述 | 安装位置 | -|------|------|----------| -| **Global** | 系统级安装（默认） | `~/.claude/`、`~/.codex/`、`~/.gemini/` | -| **Path** | 自定义目录 + 全局混合 | 本地：`agents/`、`commands/`
全局：`workflows/`、`scripts/` | - -**备份行为：** -- **默认**：自动备份启用（`-BackupAll`） -- **禁用**：使用 `-NoBackup` 标志（⚠️ 无备份覆盖） -- **备份位置**：安装目录中的 `claude-backup-{timestamp}/` - -**⚠️ 重要警告：** -- `-Force -BackupAll`：静默文件覆盖（带备份） -- `-NoBackup -Force`：永久文件覆盖（无法恢复） -- Global 模式会修改用户配置目录 - ### **✅ 验证安装** -安装后，打开 **Claude Code** 并检查工作流命令是否可用，运行以下命令： +安装后，打开 **Claude Code** 并通过运行以下命令检查工作流命令是否可用： ```bash /workflow:session:list ``` - -此命令应在 Claude Code 界面中被识别。如果您能看到工作流 slash 命令（例如 `/workflow:*`、`/cli:*`），说明安装成功。 - -> **📝 安装说明：** -> - 安装程序将自动安装/更新 `.codex/` 和 `.gemini/` 目录 -> - **全局模式**：安装到 `~/.codex` 和 `~/.gemini` -> - **路径模式**：安装到指定目录（例如 `project/.codex`、`project/.gemini`） -> - **备份**：默认自动备份现有文件到 `claude-backup-{timestamp}/` -> - **安全**：首次安装建议使用交互式模式以审查更改 - ---- - -## ⚙️ 配置 - -### **工具控制系统** - -CCW 使用**基于配置的工具控制系统**，使外部 CLI 工具成为**可选项**而非必需项。这允许您： - -- ✅ **从纯 Claude 模式开始** - 无需安装额外工具即可立即开始工作 -- ✅ **渐进式增强** - 根据需要选择性地添加外部工具 -- ✅ **优雅降级** - 工具不可用时自动回退 -- ✅ **灵活配置** - 按项目控制工具可用性 - -**配置文件**: `~/.claude/workflows/tool-control.yaml` - -```yaml -tools: - gemini: - enabled: false # 可选：AI 分析与文档生成 - qwen: - enabled: true # 可选：AI 架构与代码生成 - codex: - enabled: true # 可选：AI 开发与实现 -``` - -**行为**: -- **禁用时**: CCW 自动回退到其他已启用工具或 Claude 的原生能力 -- **启用时**: 使用专用工具发挥各自优势 -- **默认**: 所有工具禁用 - 纯 Claude 模式开箱即用 - -### **可选 CLI 工具** *(增强功能)* - -虽然 CCW 仅使用 Claude 即可工作，但安装这些工具可提供增强的分析和扩展上下文： - -#### **外部 CLI 工具** - -| 工具 | 用途 | 安装方式 | 优势 | -|------|------|----------|------| -| **Gemini CLI** | AI 分析与文档生成 | `npm install -g @google/gemini-cli` ([GitHub](https://github.com/google-gemini/gemini-cli)) | 免费配额，复杂项目的扩展上下文 | -| **Codex CLI** | AI 开发与实现 | `npm install -g @openai/codex` ([GitHub](https://github.com/openai/codex)) | 自主开发，数学推理 | -| **Qwen Code** | AI 架构与代码生成 | `npm install -g @qwen-code/qwen-code` ([文档](https://github.com/QwenLM/qwen-code)) | 大上下文窗口，架构分析 | - -#### **系统实用工具** - -| 工具 | 用途 | 安装方式 | -|------|------|----------| -| **ripgrep (rg)** | 快速代码搜索 | [下载](https://github.com/BurntSushi/ripgrep/releases) 或 `brew install ripgrep` (macOS), `apt install ripgrep` (Ubuntu) | -| **jq** | JSON 处理 | [下载](https://jqlang.github.io/jq/download/) 或 `brew install jq` (macOS), `apt install jq` (Ubuntu) | - -**快速安装（所有工具）：** - -```bash -# macOS -brew install ripgrep jq -npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code - -# Ubuntu/Debian -sudo apt install ripgrep jq -npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code - -# Windows (Chocolatey) -choco install ripgrep jq -npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code -``` - -### **必需: Gemini CLI 设置** - -配置 Gemini CLI 以实现最佳集成： - -```json -// ~/.gemini/settings.json -{ - "contextFileName": ["CLAUDE.md", "GEMINI.md"] -} -``` - -### **推荐: .geminiignore** - -通过排除不必要的文件来优化性能： - -```bash -# .geminiignore (在项目根目录) -/dist/ -/build/ -/node_modules/ -/.next/ -*.tmp -*.log -/temp/ - -# 包含重要文档 -!README.md -!**/CLAUDE.md -``` - -### **推荐: MCP 工具** *(增强分析)* - -MCP (模型上下文协议) 工具提供高级代码库分析。**推荐安装** - 虽然 CCW 具有回退机制，但不安装 MCP 工具可能会导致某些工作流出现意外行为或性能下降。 - -#### 可用的 MCP 服务器 - -| MCP 服务器 | 用途 | 安装指南 | -|------------|------|---------| -| **Exa MCP** | 外部 API 模式和最佳实践 | [安装指南](https://smithery.ai/server/exa) | -| **Code Index MCP** | 高级内部代码搜索 | [安装指南](https://github.com/johnhuang316/code-index-mcp) | -| **Chrome DevTools MCP** | ⚠️ **UI 工作流必需** - URL 模式设计提取 | [安装指南](https://github.com/ChromeDevTools/chrome-devtools-mcp) | - -#### 启用后的好处 -- 📊 **更快分析**: 直接代码库索引 vs 手动搜索 -- 🌐 **外部上下文**: 真实世界的 API 模式和示例 -- 🔍 **高级搜索**: 模式匹配和相似性检测 -- ⚡ **更好的可靠性**: 某些工作流的主要工具 -- 🎨 **UI 工作流**: Chrome DevTools 实现从在线 URL 进行像素级精确设计提取 - -⚠️ **注意**: 某些工作流期望 MCP 工具可用。如果没有安装，您可能会遇到： -- 代码分析和搜索操作速度较慢 -- 某些场景下上下文质量降低 -- 回退到效率较低的传统工具 -- 高级工作流中可能出现意外行为 - ---- - -## 🎯 智能体技能 (Agent Skills) - -**智能体技能** 通过模块化、可复用的专业知识包扩展 Claude 的能力。技能会根据上下文自动发现和触发。 - -### **可用技能** - -#### **提示词增强器 (Prompt Enhancer)** -将模糊提示转换为结构化、可执行的规范。 - -**使用方式**：在任何请求中添加 `-e` 或 `--enhance` 标志 -```bash -# 示例 -修复认证问题 -e -优化数据库查询 --enhance -``` - -**功能说明**: -- 分析会话上下文和技术栈 -- 将意图结构化为 INTENT → ACTION 格式 -- 添加相关上下文、约束和指标 -- 输出可立即执行的规范 - -**输出**：根据任务类型动态调整的结构化提示（简单任务使用最少字段，复杂任务使用全面规范） - -### **创建自定义技能** - -技能存储在 `.claude/skills/`（项目）或 `~/.claude/skills/`（个人）： - -```bash -# 创建新技能 -mkdir -p .claude/skills/my-skill -``` - -**SKILL.md 结构**: -```yaml ---- -name: 我的技能名称 -description: 功能说明和使用时机。使用时机：[触发条件]。 -allowed-tools: Read, Grep, Glob # 可选工具限制 ---- - -# 我的技能名称 - -## 指令 -[Claude 的分步指导] - -## 示例 -[具体使用示例] -``` - -**最佳实践**: -- 编写具体的描述，包含明确的触发条件 -- 同时说明功能和使用时机 -- 保持技能专注于单一能力 -- 通过匹配描述的问题进行测试 - -完整文档请参阅 [skills.md](skills.md)。 - ---- - -## 🚀 快速入门 - -### 完整开发工作流 - -**阶段 1：头脑风暴与概念规划** -```bash -# 多视角头脑风暴，使用基于角色的智能体 -/workflow:brainstorm:auto-parallel "构建用户认证系统" - -# 审查和优化特定方面（可选） -/workflow:brainstorm:ui-designer "认证流程" -/workflow:brainstorm:synthesis # 生成综合规范 -``` - -**阶段 1.5：概念验证** *(可选质量关卡)* -```bash -# 识别并解决头脑风暴产物中的歧义 -/workflow:concept-clarify - -# 或显式指定会话 -/workflow:concept-clarify --session WFS-auth -``` -- 在 `/workflow:brainstorm:synthesis` 之后、`/workflow:plan` 之前运行 -- 通过交互式问答澄清未明确的需求、架构决策或风险 -- 每次会话最多 5 个问题，支持多选或简答格式 -- 增量更新 `synthesis-specification.md` 以记录澄清内容 -- 确保概念基础明确后再进行详细规划 -- 生成覆盖度摘要，建议继续或解决未决项 - -**阶段 2：UI 设计精炼** *(UI 密集型项目可选)* - -**🎯 选择您的工作流：** - -**场景 1：从想法或概念开始** → 使用 `explore-auto` -```bash -# 生成多个风格和布局选项来探索不同方向 -/workflow:ui-design:explore-auto --prompt "现代博客：首页，文章，作者" --style-variants 3 --layout-variants 2 -# 创建一个 3×2 矩阵：3种视觉风格 × 2种布局 = 6个原型供选择 -``` - -**场景 2：复制现有设计** → 使用 `imitate-auto` -```bash -# 快速、高保真复制参考设计 -/workflow:ui-design:imitate-auto --images "refs/design.png" --pages "dashboard,settings" -# 或从 URL 自动截图（需要 Playwright/Chrome DevTools MCP） -/workflow:ui-design:imitate-auto --url "https://linear.app" --pages "home,features" -``` - -**场景 3：从现有设计系统批量创建** → 使用 `batch-generate` -```bash -# 已有设计系统？快速生成多个页面 -/workflow:ui-design:batch-generate --prompt "创建个人资料和设置页面" --layout-variants 2 -``` - -**高级：手动分步控制** (v4.4.0+) -```bash -# 1. 提取视觉样式（颜色、排版、间距） -/workflow:ui-design:style-extract --images "refs/*.png" --mode explore --variants 3 - -# 2. 整合为可用于生产的设计令牌 -/workflow:ui-design:consolidate --variants "variant-1,variant-3" - -# 3. 提取布局结构（DOM、CSS 布局规则） -/workflow:ui-design:layout-extract --targets "dashboard,auth" --mode explore --variants 2 --device-type responsive - -# 4. 组合样式 + 布局 → HTML/CSS 原型 -/workflow:ui-design:generate --style-variants 1 --layout-variants 2 - -# 5. 预览并选择 -cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080 -# 访问 http://localhost:8080/compare.html 进行并排比较 - -# 6. 将选定的设计集成到项目中 -/workflow:ui-design:update --session WFS-auth --selected-prototypes "dashboard-s1-l2" -``` - -**阶段 3：行动规划** -```bash -# 创建可执行的实现计划 -/workflow:plan "实现基于 JWT 的认证系统" - -# 或使用 TDD 方法 -/workflow:tdd-plan "使用测试优先开发实现认证" -``` - -**阶段 3.5：行动计划验证** *(可选执行前检查)* -```bash -# 验证计划一致性和完整性 -/workflow:action-plan-verify - -# 或显式指定会话 -/workflow:action-plan-verify --session WFS-auth -``` -- 在 `/workflow:plan` 或 `/workflow:tdd-plan` 之后、`/workflow:execute` 之前运行 -- 对 `IMPL_PLAN.md` 和任务 JSON 文件进行只读分析，并与 `synthesis-specification.md` 对照 -- 验证需求覆盖率、依赖完整性和综合对齐性 -- 识别不一致、重复、歧义和未充分说明的项目 -- 生成详细验证报告，包含严重性评级的发现（CRITICAL/HIGH/MEDIUM/LOW） -- 建议是否 PROCEED、PROCEED_WITH_FIXES 或 BLOCK_EXECUTION -- 提供针对检测到的问题的可操作修复建议 - -**阶段 4：执行** -```bash -# 使用 AI 智能体执行任务 -/workflow:execute - -# 监控进度 -/workflow:status -``` - -**阶段 5：测试与质量保证** -```bash -# 生成独立测试修复工作流（v3.2.2+） -/workflow:test-gen WFS-auth # 创建 WFS-test-auth 会话 -/workflow:test-cycle-execute # 执行测试修复循环，包含动态迭代 - -# 恢复中断的测试会话 -/workflow:test-cycle-execute --resume-session="WFS-test-auth" - -# 或验证 TDD 合规性（TDD 工作流） -/workflow:tdd-verify -``` - -**什么是 `/workflow:test-cycle-execute`？** -- **动态任务生成**：基于测试失败在执行过程中创建中间修复任务 -- **迭代测试**：自动运行测试修复循环，直到所有测试通过或达到最大迭代次数 -- **CLI 驱动分析**：使用 Gemini/Qwen 分析失败并生成修复策略 -- **智能体协调**：将测试执行和修复委托给 `@test-fix-agent` -- **自主完成**：持续直到成功，无需用户干预 - -### 简单任务快速入门 - -**功能开发：** -```bash -/workflow:session:start "添加密码重置功能" -/workflow:plan "基于邮件的密码重置，带令牌过期" -/workflow:execute -``` - -**Bug 修复：** -```bash -# 使用 CLI 工具进行交互式分析 -/cli:mode:bug-index --tool gemini "移动设备上登录超时" - -# 执行建议的修复 -/workflow:execute -``` - -> **💡 何时使用哪种方式？** -> -> **使用 `/workflow:plan` + `/workflow:execute` 适用于：** -> - 需要多个模块的复杂功能（>3 个模块） -> - 包含多个子任务的任务（>5 个子任务） -> - 影响架构的横切变更 -> - 需要组件间协调的功能 -> - 需要结构化规划和进度跟踪时 -> -> **直接使用 Claude Code 适用于：** -> - 简单、聚焦的变更（单个文件或模块） -> - 解决方案明确的快速 bug 修复 -> - 文档更新 -> - 单个组件内的代码重构 -> - 简单直接的功能添加 - -**代码分析：** -```bash -# 深度代码库分析 -/cli:mode:code-analysis --tool qwen "分析认证模块架构" -``` +如果斜杠命令（例如 `/workflow:*`）被识别，则表示安装成功。 --- ## 🛠️ 命令参考 -### **统一 CLI 命令 (`/cli:*)** -*使用 `--tool ` 标志选择所需工具。默认为 `gemini`。* - -| 命令 | 描述 | -|---|---| -| `/cli:analyze` | 深度代码库分析。 | -| `/cli:chat` | 与工具进行直接的交互式聊天。 | -| `/cli:execute` | 以完全权限执行任务。 | -| `/cli:cli-init`| 为工作区初始化CLI工具配置。 | -| `/cli:mode:bug-index` | 分析错误并提出修复建议。 | -| `/cli:mode:code-analysis` | 执行深度代码分析和调试。 | -| `/cli:mode:plan` | 项目规划和架构分析。 | - -### **工作流命令 (`/workflow:*)** - -| 命令 | 描述 | -|---|---| -| `/workflow:session:*` | 管理开发会话（`start`, `resume`, `list`, `complete`）。 | -| `/workflow:brainstorm:*` | 使用基于角色的智能体进行多视角规划。 | -| `/workflow:concept-clarify` | **可选** 质量关卡 - 在规划之前识别并解决头脑风暴产物中的歧义（在综合后、规划前运行）。 | -| `/workflow:ui-design:explore-auto` | **v4.4.0** 矩阵探索模式 - 通过布局/样式分离生成多个风格×布局变体。 | -| `/workflow:ui-design:imitate-auto` | **v4.4.0** 快速模仿模式 - 通过自动截图、布局提取和汇编实现快速 UI 复制。 | -| `/workflow:ui-design:style-extract` | **v4.4.0** 使用 Claude 原生分析从图像/文本提取视觉样式（颜色、排版、间距）。 | -| `/workflow:ui-design:layout-extract` | **v4.4.0** 通过设备感知模板提取结构布局（DOM、CSS 布局规则）。 | -| `/workflow:ui-design:consolidate` | **v4.4.0** 使用 Claude 合成将风格变体整合为经过验证的设计令牌。 | -| `/workflow:ui-design:generate` | **v4.4.0** 纯汇编器 - 组合布局模板 + 设计令牌 → HTML/CSS 原型。 | -| `/workflow:ui-design:update` | **v4.4.0** 将最终确定的设计系统集成到头脑风暴产物中。 | -| `/workflow:plan` | 从描述创建详细、可执行的计划。 | -| `/workflow:tdd-plan` | 创建 TDD 工作流（6 阶段），包含测试覆盖分析和 Red-Green-Refactor 循环。 | -| `/workflow:action-plan-verify` | **可选** 执行前检查 - 验证 IMPL_PLAN.md 和任务 JSON 的一致性和完整性（在规划后、执行前运行）。 | -| `/workflow:execute` | 自主执行当前的工作流计划。 | -| `/workflow:status` | 显示工作流的当前状态。 | -| `/workflow:test-gen [--use-codex] ` | 为已完成实现创建独立测试生成工作流，支持自动诊断和修复。 | -| `/workflow:test-cycle-execute` | **v4.5.0** 执行测试修复工作流，包含动态任务生成和迭代修复循环。运行测试 → 使用 CLI 分析失败 → 生成修复任务 → 重新测试直至成功。 | -| `/workflow:tdd-verify` | 验证 TDD 合规性并生成质量报告。 | -| `/workflow:review` | **可选** 手动审查（仅在明确需要时使用，测试通过即代表代码已批准）。 | -| `/workflow:tools:test-context-gather` | 分析测试覆盖率，识别缺失的测试文件。 | -| `/workflow:tools:test-concept-enhanced` | 使用 Gemini 生成测试策略和需求分析。 | -| `/workflow:tools:test-task-generate` | 生成测试任务 JSON，包含 test-fix-cycle 规范。 | - -### **UI 设计工作流命令 (`/workflow:ui-design:*`)** *(v4.4.0)* - -⚠️ **基于 URL 的设计提取**: 安装 [Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) 以启用从在线 URL 自动提取计算样式和 DOM 结构。如果不可用，将回退到视觉分析。 - -设计工作流系统提供完整的 UI 设计精炼,具备**布局/样式分离架构**、**纯 Claude 执行**、**智能目标推断**和**零外部依赖**。 - -#### 📐 架构概述 - -UI 工作流遵循**关注点分离**哲学： -- **样式（视觉令牌）**：颜色、排版、间距、边框 → `design-tokens.json` -- **布局（结构）**：DOM 层次结构、CSS 布局规则 → `layout-templates.json` -- **汇编**：纯粹组合样式 + 布局 → HTML/CSS 原型 - -**命令分类：** - -| 类别 | 命令 | 目的 | -|----------|----------|---------| -| **高级编排器** | `explore-auto`, `imitate-auto`, `batch-generate` | 完整工作流（推荐） | -| **输入/捕获** | `capture`, `explore-layers` | 截图获取 | -| **分析/提取** | `style-extract`, `layout-extract` | 视觉样式和结构布局提取 | -| **处理/生成** | `consolidate`, `generate` | 令牌验证和原型汇编 | -| **集成** | `update` | 设计系统集成到项目 | - -#### 🧭 决策树：应该使用哪个命令？ - -``` -┌─ 有想法或文本描述？ -│ └─→ /workflow:ui-design:explore-auto -│ （探索多个风格 × 布局选项） -│ -┌─ 想复制现有设计？ -│ └─→ /workflow:ui-design:imitate-auto -│ （高保真单一设计复制） -│ -┌─ 已有设计系统？ -│ └─→ /workflow:ui-design:batch-generate -│ （批量创建多个页面/组件） -│ -└─ 需要细粒度控制？ - └─→ 按顺序使用单独命令： - 1. style-extract → 提取颜色、字体、间距 - 2. consolidate → 验证并合并令牌 - 3. layout-extract → 提取 DOM 结构 - 4. generate → 组合为原型 - 5. update → 集成到项目 -``` - -#### 🔄 工作流程图 - -**探索工作流**（想法 → 多个设计）： -``` -提示词/图像 → style-extract（探索模式） - ↓ - consolidate（N 个变体） - ↓ - layout-extract（探索模式） - ↓ - generate（N 个样式 × M 个布局） - ↓ - update（选定的设计） -``` - -**模仿工作流**（参考 → 单一设计）： -``` -URL/图像 → capture/explore-layers - ↓ - style-extract（模仿模式） - ↓ - layout-extract（模仿模式） - ↓ - consolidate（单一变体） - ↓ - generate（1 个样式 × 1 个布局） - ↓ - update（最终设计） -``` - -#### 核心命令 - -**`/workflow:ui-design:explore-auto`** - 矩阵探索模式 -```bash -# 全面探索 - 多个风格×布局变体 -/workflow:ui-design:explore-auto --prompt "现代博客：首页，文章，作者" --style-variants 3 --layout-variants 2 - -# 与图像和会话集成 -/workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png" --style-variants 2 --layout-variants 3 - -# 纯文本模式，带页面推断 -/workflow:ui-design:explore-auto --prompt "电商：首页，产品，购物车" --style-variants 2 --layout-variants 2 -``` -- **🎯 矩阵模式**: 生成所有风格×布局组合 -- **📊 全面探索**: 比较多个设计方向 -- **🔍 交互式对比**: 带视口控制的并排比较 -- **✅ 跨页面验证**: 多页面设计的自动一致性检查 -- **⚡ 批量选择**: 按风格或布局快速选择 - -**`/workflow:ui-design:imitate-auto`** - 快速模仿模式 -```bash -# 快速单一设计复制 -/workflow:ui-design:imitate-auto --images "refs/design.png" --pages "dashboard,settings" - -# 与会话集成 -/workflow:ui-design:imitate-auto --session WFS-auth --images "refs/ui.png" --pages "home,product" - -# 从 URL 自动截图（需要 Playwright） -/workflow:ui-design:imitate-auto --url "https://example.com" --pages "landing" -``` -- **⚡ 速度优化**: 比 explore-auto 快 5-10 倍 -- **📸 自动截图**: 使用 Playwright/Chrome 自动捕获 URL 截图 -- **🎯 直接提取**: 跳过变体选择，直接进入实现 -- **🔧 单一设计聚焦**: 最适合快速复制现有设计 - -**`/workflow:ui-design:style-extract`** - 视觉样式提取（v4.4.0） -```bash -# 纯文本提示 -/workflow:ui-design:style-extract --prompt "现代极简，深色主题" --mode explore --variants 3 - -# 纯图像 -/workflow:ui-design:style-extract --images "refs/*.png" --mode explore --variants 3 - -# 混合（文本指导图像分析） -/workflow:ui-design:style-extract --images "refs/*.png" --prompt "Linear.app 风格" --mode imitate - -# 高保真单一风格 -/workflow:ui-design:style-extract --images "design.png" --mode imitate -``` -- **🎨 仅视觉令牌**：颜色、排版、间距（无布局结构） -- **🔄 双模式**：模仿（单一变体）/ 探索（多个变体） -- **Claude 原生**：单次分析，无外部工具 -- **输出**：包含嵌入式 `proposed_tokens` 的 `style-cards.json` - -**`/workflow:ui-design:layout-extract`** - 结构布局提取（v4.4.0） -```bash -# 探索模式 - 多个布局变体 -/workflow:ui-design:layout-extract --targets "home,dashboard" --mode explore --variants 3 --device-type responsive - -# 模仿模式 - 单一布局复制 -/workflow:ui-design:layout-extract --images "refs/*.png" --targets "dashboard" --mode imitate --device-type desktop - -# 使用 MCP 研究（探索模式） -/workflow:ui-design:layout-extract --prompt "电商结账" --targets "cart,checkout" --mode explore --variants 2 -``` -- **🏗️ 仅结构**：DOM 层次结构、CSS 布局规则（无视觉样式） -- **📱 设备感知**：桌面、移动、平板、响应式优化 -- **🧠 智能体驱动**：使用 ui-design-agent 进行结构分析 -- **🔍 MCP 研究**：布局模式灵感（探索模式） -- **输出**：包含基于令牌的 CSS 的 `layout-templates.json` - -**`/workflow:ui-design:consolidate`** - 验证和合并令牌 -```bash -# 整合选定的风格变体 -/workflow:ui-design:consolidate --session WFS-auth --variants "variant-1,variant-3" -``` -- **Claude 合成**：单次生成所有设计系统文件 -- **功能**：WCAG AA 验证、OKLCH 颜色、W3C 令牌格式 -- **输出**：`design-tokens.json`、`style-guide.md`、`tailwind.config.js`、`validation-report.json` - -**`/workflow:ui-design:generate`** - 纯汇编器（v4.4.0） -```bash -# 组合布局模板 + 设计令牌 -/workflow:ui-design:generate --style-variants 1 --layout-variants 2 - -# 多个样式与多个布局 -/workflow:ui-design:generate --style-variants 2 --layout-variants 3 -``` -- **📦 纯汇编**：组合预提取的 layout-templates.json + design-tokens.json -- **❌ 无设计逻辑**：所有布局/样式决策在之前阶段完成 -- **✅ 令牌解析**：用实际令牌值替换 var() 占位符 -- **🎯 矩阵输出**：生成样式 × 布局 × 目标原型 -- **🔍 交互式预览**：`compare.html` 并排比较 - -**`/workflow:ui-design:update`** - 集成设计系统 -```bash -# 使用设计系统更新头脑风暴产物 -/workflow:ui-design:update --session WFS-auth --selected-prototypes "dashboard-s1-l2" -``` -- **更新**: `synthesis-specification.md`、`ui-designer/style-guide.md` -- **使设计令牌可用于任务生成** - -#### 预览系统 - -运行 `ui-generate` 后，您将获得交互式预览工具，**无需启动服务器即可直接在浏览器中使用**： - -**直接浏览器预览**（推荐 - 无需服务器）: -```bash -# 导航到原型目录 -cd .workflow/WFS-auth/.design/prototypes - -# 在浏览器中打开（双击文件或使用命令）: -open index.html # macOS -start index.html # Windows -xdg-open index.html # Linux - -# index.html 和 compare.html 都可以直接打开，无需服务器 -open compare.html # 直接打开对比视图 -``` - -**可选：本地服务器**（用于高级功能）: -```bash -cd .workflow/WFS-auth/.design/prototypes -# 如果需要服务器端功能，可选择一个: -python -m http.server 8080 # Python -npx http-server -p 8080 # Node.js -php -S localhost:8080 # PHP -# 访问: http://localhost:8080 -``` - -**预览功能**: -- `index.html`: 包含所有原型的主导航（离线可用） -- `compare.html`: 带视口控制的并排对比（离线可用） -- 同步滚动用于布局对比 -- 动态页面切换 -- 实时响应式测试 -- **无需服务器** - 所有功能都可通过直接在浏览器中打开文件来使用 - -#### 📦 输出结构 - -所有 UI 工作流输出都组织在会话内的 `.design` 目录中： - -``` -.workflow/WFS-/.design/ -├── design-run-YYYYMMDD-HHMMSS/ # 带时间戳的设计运行 -│ ├── screenshots/ # 📸 捕获的截图 -│ │ ├── home.png -│ │ └── dashboard.png -│ │ -│ ├── style-extraction/ # 🎨 样式分析阶段 -│ │ ├── style-cards.json # AI 提议的风格变体 -│ │ └── design-space-analysis.json # （探索模式）多样性分析 -│ │ -│ ├── layout-extraction/ # 🏗️ 布局分析阶段 -│ │ └── layout-templates.json # 包含基于令牌的 CSS 的结构模板 -│ │ -│ ├── style-consolidation/ # ✅ 生产设计系统 -│ │ ├── style-1/ -│ │ │ ├── design-tokens.json # W3C 设计令牌 -│ │ │ ├── style-guide.md # 视觉设计文档 -│ │ │ ├── tailwind.config.js # Tailwind 配置 -│ │ │ └── validation-report.json # WCAG AA 验证结果 -│ │ └── style-2/ -│ │ └── ... -│ │ -│ └── prototypes/ # 🎯 最终 HTML/CSS 原型 -│ ├── home-style-1-layout-1.html # 矩阵生成的原型 -│ ├── home-style-1-layout-1.css -│ ├── home-style-1-layout-2.html -│ ├── dashboard-style-2-layout-1.html -│ ├── index.html # 主导航页面 -│ └── compare.html # 并排比较工具 -│ -└── latest -> design-run-YYYYMMDD-HHMMSS # 指向最新运行的符号链接 -``` - -**关键文件：** - -| 文件 | 目的 | 生成命令 | -|------|---------|--------------| -| `style-cards.json` | AI 提议的视觉样式及嵌入的令牌 | `style-extract` | -| `layout-templates.json` | 包含基于令牌的 CSS 的结构模板 | `layout-extract` | -| `design-tokens.json` | 可用于生产的 W3C 设计令牌 | `consolidate` | -| `style-guide.md` | 视觉设计系统文档 | `consolidate` | -| `compare.html` | 交互式原型比较矩阵 | `generate` | - -**最佳实践：** - -1. **会话管理**：会话内的所有运行累积在 `.design/design-run-*/` -2. **版本控制**：每次运行都有时间戳，便于回滚 -3. **集成**：使用 `update` 命令将最终令牌链接到项目产物 -4. **清理**：旧运行可以安全删除；`latest` 符号链接始终指向最新的 +CCW 提供了一套丰富的命令，用于管理工作流、任务以及与 AI 工具的交互。有关所有可用命令的完整列表和详细说明，请参阅 [**COMMAND_REFERENCE.md**](COMMAND_REFERENCE.md) 文件。 --- -### **任务与内存命令** +## 🚀 快速入门 -| 命令 | 描述 | -|---|---| -| `/task:*` | 管理单个任务（`create`, `breakdown`, `execute`, `replan`）。 | -| `/update-memory-full` | 重新索引整个项目文档。 | -| `/update-memory-related` | 更新与最近更改相关的文档。 | -| `/version` | 显示版本信息并检查 GitHub 更新。 | +开始使用的最佳方式是遵循 [**快速上手指南**](GETTING_STARTED_CN.md) 中的 5 分钟教程。 ---- +以下是一个常见开发工作流的快速示例： -## 🧠 内存管理：上下文质量基础 - -分层内存系统实现精确上下文收集和防止执行漂移。定期更新是高质量 AI 输出的关键。 - -#### **内存层次** - -``` -CLAUDE.md（根）→ domain/CLAUDE.md（领域）→ module/CLAUDE.md（模块）→ submodule/CLAUDE.md（子模块） -``` - -#### **更新时机** - -| 触发条件 | 命令 | 目的 | -|---------|---------|---------| -| 主要功能实现后 | `/update-memory-related` | 更新受影响模块/依赖 | -| 架构变更后 | `/update-memory-full` | 重新索引整个项目 | -| 复杂规划前 | `/update-memory-related` | 确保 context-package.json 最新模式 | -| 重构后 | `/update-memory-related` | 更新实现模式/API | -| 每周维护 | `/update-memory-full` | 保持文档同步 | - -#### **质量影响** - -**无更新：** ❌ 过时模式、弃用 API、错误上下文、架构漂移 -**有更新：** ✅ 当前模式、最新 API、准确上下文、架构对齐 - -#### **最佳实践** - -1. 重大变更后立即更新 -2. 频繁使用 `/update-memory-related`（更快、有针对性） -3. 每周安排 `/update-memory-full`（捕获漂移） -4. 审查生成的 CLAUDE.md 文件 -5. 集成到 CI/CD 流水线 - -> 💡 内存质量决定 context-package.json 质量和执行准确性。视为关键维护，非可选文档。 - -#### **工具集成** - -```bash -/update-memory-full --tool gemini # 全面分析（默认） -/update-memory-full --tool qwen # 架构聚焦 -/update-memory-full --tool codex # 实现细节 -``` - ---- - -## 🏗️ 技术架构 - -完整的自文档化系统，用专业软件工程实践编排 AI 智能体。 - -### **项目组织** - -``` -.claude/ -├── agents/ # 专用 AI 智能体（action-planning、code-developer、test-fix） -├── commands/ # 面向用户和内部命令（workflow:*、cli:*、task:*） -├── workflows/ # 战略框架（架构、策略、模式、模板） -├── scripts/ # 实用工具自动化（模块分析、文件监控） -└── prompt-templates/# 标准化 AI 提示词 -``` - -**原则：** 关注点分离（agents/commands/workflows）、层次化命令、自文档化、可扩展模板 - -### **执行模型** - -``` -用户命令 → 编排器 → 阶段 1-4（上下文 → 分析 → 规划 → 执行） - ↓ - 专用智能体（pre_analysis → 实现 → 验证） -``` - -**示例：** `/workflow:plan "构建认证"` → session:start → context-gather → concept-enhanced → task-generate - ---- - -## 🧩 工作原理：设计理念 - -### 核心问题 - -传统的 AI 编码工作流面临一个根本性挑战：**执行不确定性导致误差累积**。 - -**示例：** -```bash -# 提示词1："开发XX功能" -# 提示词2："查看XX文件中架构设计，开发XX功能" -``` - -虽然提示词1对简单任务可能成功，但在复杂工作流中： -- AI 每次可能检查不同的文件 -- 小偏差在多个步骤中累积 -- 最终输出偏离预期目标 - -> **CCW 的使命**：解决"1到N"的问题 — 精确地在现有代码库基础上开发，而不仅仅是"0到1"的全新项目开发。 - ---- - -### CCW 解决方案：上下文优先架构 - -#### 1. **预定义上下文收集** - -CCW 使用结构化上下文包，而不是让智能体随机探索： - -**规划阶段创建的 `context-package.json`**： -```json -{ - "metadata": { - "task_description": "...", - "tech_stack": {"frontend": [...], "backend": [...]}, - "complexity": "high" - }, - "assets": [ - { - "path": "synthesis-specification.md", - "priority": "critical", - "sections": ["后端模块结构"] - } - ], - "implementation_guidance": { - "start_with": ["步骤1", "步骤2"], - "critical_security_items": [...] - } -} -``` - -#### 2. **JSON 优先任务模型** - -每个任务包含 `flow_control.pre_analysis` 部分： - -```json -{ - "id": "IMPL-1", - "flow_control": { - "pre_analysis": [ - { - "step": "load_architecture", - "commands": ["Read(architecture.md)", "grep 'auth' src/"], - "output_to": "arch_context", - "on_error": "fail" - } - ], - "implementation_approach": { - "modification_points": ["..."], - "logic_flow": ["..."] - }, - "target_files": ["src/auth/index.ts"] - } -} -``` - -**核心创新**：`pre_analysis` 步骤在实现**之前执行**，确保智能体始终拥有正确的上下文。 - -#### 3. **多阶段编排** - -CCW 工作流是协调斜杠命令的编排器： - -**规划阶段** (`/workflow:plan`)： -``` -阶段1: session:start → 创建会话 -阶段2: context-gather → 构建 context-package.json -阶段3: concept-enhanced → CLI 分析（Gemini/Qwen） -阶段4: task-generate → 生成带 pre_analysis 的任务 JSON -``` - -**执行阶段** (`/workflow:execute`)： -``` -对于每个任务： - 1. 执行 pre_analysis 步骤 → 加载上下文 - 2. 应用 implementation_approach → 进行更改 - 3. 验证验收标准 → 验证成功 - 4. 生成摘要 → 跟踪进度 -``` - -#### 4. **多模型编排** - -每个 AI 模型发挥各自优势： - -| 模型 | 角色 | 使用场景 | -|------|------|----------| -| **Gemini** | 分析与理解 | 长上下文分析、架构审查、bug 调查 | -| **Qwen** | 架构与设计 | 系统设计、代码生成、架构规划 | -| **Codex** | 实现 | 功能开发、测试、自主执行 | - -**示例：** -```bash -# Gemini 分析问题空间 -/cli:mode:code-analysis --tool gemini "分析认证模块" - -# Qwen 设计解决方案 -/cli:analyze --tool qwen "设计可扩展的认证架构" - -# Codex 实现代码 -/workflow:execute # 使用带 Codex 的 @code-developer -``` - ---- - -### 0到1 vs 1到N 开发 - -| 场景 | 传统工作流 | CCW 方法 | -|------|-----------|----------| -| **全新项目（0→1）** | ✅ 效果良好 | ✅ 增加结构化规划 | -| **功能添加（1→2）** | ⚠️ 上下文不确定 | ✅ context-package 链接现有代码 | -| **Bug 修复（N→N+1）** | ⚠️ 可能遗漏相关代码 | ✅ pre_analysis 查找依赖 | -| **重构** | ⚠️ 范围不可预测 | ✅ CLI 分析 + 结构化任务 | - ---- - -### 核心工作流 - -#### **完整开发（头脑风暴 → 部署）** -``` -头脑风暴（8个角色）→ 综合 → 规划（4阶段）→ 执行 → 测试 → 审查 -``` - -#### **快速功能开发** -``` -session:start → plan → execute → test-gen → execute -``` - -#### **TDD 工作流** -``` -tdd-plan (TEST→IMPL→REFACTOR 链) → execute → tdd-verify -``` - -#### **Bug 修复** -``` -cli:mode:bug-index（分析）→ execute（修复）→ test-gen（验证） -``` +1. **启动会话**: + ```bash + /workflow:session:start "实现用户登录功能" + ``` +2. **创建计划**: + ```bash + /workflow:plan "实现基于 JWT 的用户登录和注册" + ``` +3. **执行计划**: + ```bash + /workflow:execute + ``` --- @@ -1084,4 +94,4 @@ cli:mode:bug-index（分析）→ execute（修复）→ test-gen（验证） ## 📄 许可证 -此项目根据 **MIT 许可证** 授权。详见 [LICENSE](LICENSE) 文件。 +此项目根据 **MIT 许可证** 授权。详见 [LICENSE](LICENSE) 文件。 \ No newline at end of file