Claude-Code-Workflow/COMMAND_SPEC.md

Claude Code Workflow (CCW) - Command Specification

Version: 5.0.0 Updated: 2025年10月24日星期六

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.

Version 5.0 Changes: Removed MCP code-index dependency, streamlined TDD workflow with conflict resolution, and refocused brainstorming on role analysis instead of synthesis documents.

For a user-friendly overview, please see 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:

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

  # 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:

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

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

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

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

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

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

  /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] <analysis target>
• 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:

  /cli:analyze "authentication patterns"
  

/cli:chat

• Syntax: /cli:chat [--agent] [--tool codex|gemini|qwen] [--enhance] <inquiry>
• 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:

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

  /cli:cli-init
  

/cli:codex-execute

• Syntax: /cli:codex-execute [--verify-git] <description|task-id>
• 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:

  /cli:codex-execute "implement user authentication system"
  

/cli:discuss-plan

• Syntax: /cli:discuss-plan [--topic '...'] [--task-id '...'] [--rounds N] <input>
• 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:

  /cli:discuss-plan --topic "Design a new caching layer"
  

/cli:execute

• Syntax: /cli:execute [--agent] [--tool codex|gemini|qwen] [--enhance] <description|task-id>
• Responsibilities: Executes implementation tasks with auto-approval (YOLO mode). MODIFIES CODE.
• Agent Calls: @cli-execution-agent (if --agent is used).
• Example:

  /cli:execute "implement JWT authentication with middleware"
  

/cli:mode:bug-index

• Syntax: /cli:mode:bug-index [--agent] [--tool ...] [--enhance] [--cd path] <bug description>
• Responsibilities: Performs systematic bug analysis using the bug-fix.md template. Read-only.
• Agent Calls: @cli-execution-agent (if --agent is used).
• Example:

  /cli:mode:bug-index "null pointer error in login flow"
  

/cli:mode:code-analysis

• Syntax: /cli:mode:code-analysis [--agent] [--tool ...] [--enhance] [--cd path] <analysis target>
• 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:

  /cli:mode:code-analysis "trace authentication execution flow"
  

/cli:mode:plan

• Syntax: /cli:mode:plan [--agent] [--tool ...] [--enhance] [--cd path] <topic>
• Responsibilities: Performs comprehensive planning and architecture analysis using the plan.md template. Read-only.
• Agent Calls: @cli-execution-agent (if --agent is used).
• Example:

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

  /task:create "Build authentication module"
  

/task:breakdown

• Syntax: /task:breakdown <task-id>
• 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:

  /task:breakdown IMPL-1
  

/task:execute

• Syntax: /task:execute <task-id>
• 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:

  /task:execute IMPL-1.1
  

/task:replan

• Syntax: /task:replan <task-id> ["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:

  /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 <directory>]
• 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:

  /memory:update-full
  

/memory:load

• Syntax: /memory:load [--tool gemini|qwen] "task context description"
• Parameters:
  • "task context description" (Required, String): Task description to guide context extraction.
  • --tool <gemini|qwen> (Optional): Specify CLI tool for agent to use (default: gemini).
• Responsibilities: Delegates to @general-purpose agent to analyze the project and return a structured "Core Content Pack". This pack is loaded into the main thread's memory, providing essential context for subsequent operations.
• Agent-Driven Execution: Fully delegates to general-purpose agent which autonomously:
  1. Analyzes project structure and documentation
  2. Extracts keywords from task description
  3. Discovers relevant files using ripgrep/find search tools
  4. Executes Gemini/Qwen CLI for deep analysis
  5. Generates structured JSON content package
• Core Philosophy: Read-only analysis, token-efficient (CLI analysis in agent), structured output
• Agent Calls: @general-purpose agent.
• Integration: Provides quick, task-relevant context for subsequent agent operations while minimizing token consumption.
• Example:

  /memory:load "在当前前端基础上开发用户认证功能"
  /memory:load --tool qwen "重构支付模块API"
  

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

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

  /version
  

/enhance-prompt

• Syntax: /enhance-prompt <user input>
• 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):

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

  /workflow:ui-design:explore-auto --prompt "Modern blog: home, article, author"
  

/workflow:ui-design:imitate-auto

• Syntax: /workflow:ui-design:imitate-auto --url-map "<map>" [--capture-mode <batch|deep>] ...
• Responsibilities: High-speed, multi-page UI replication workflow that captures screenshots and orchestrates the full design pipeline.
• Agent Calls: @ui-design-agent.
• Example:

  /workflow:ui-design:imitate-auto --url-map "home:https://linear.app, features:https://linear.app/features"
  

/workflow:ui-design:capture

• Syntax: /workflow:ui-design:capture --url-map "target:url,..." ...
• Responsibilities: Batch screenshot capture tool using MCP Chrome DevTools with multi-tier fallback strategy (MCP → Playwright → Chrome → Manual).
• Agent Calls: None directly, uses MCP Chrome DevTools or browser automation as fallback.
• Example:

  /workflow:ui-design:capture --url-map "home:https://linear.app"
  

/workflow:ui-design:explore-layers

• Syntax: /workflow:ui-design:explore-layers --url <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 Chrome DevTools for layer exploration.
• Example:

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

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

  /workflow:ui-design:layout-extract --urls "home:https://linear.app" --mode imitate
  

/workflow:ui-design:generate

• Syntax: /workflow:ui-design:generate [--base-path <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:

  /workflow:ui-design:generate --session WFS-design-run
  

/workflow:ui-design:design-sync

• Syntax: /workflow:ui-design:design-sync --session <session_id> [--selected-prototypes "<list>"]
• Responsibilities: Synchronizes the finalized design system references into the core brainstorming artifacts (role analysis documents) to make them available for the planning phase.
• Agent Calls: None.
• Example:

  /workflow:ui-design:design-sync --session WFS-my-app
  

/workflow:ui-design:animation-extract

• Syntax: /workflow:ui-design:animation-extract [--urls "<list>"] [--mode <auto|interactive>] ...
• 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:

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

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

  /workflow:tdd-verify WFS-login-tdd
  

/workflow:test-gen

• Syntax: /workflow:test-gen [--use-codex] [--cli-execute] <source-session-id>
• 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:

  /workflow:test-gen WFS-user-auth-v2
  

/workflow:test-fix-gen

• Syntax: /workflow:test-fix-gen [--use-codex] [--cli-execute] (<source-session-id> | "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:

  /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 test-fix workflow by delegating to /workflow:execute. Generates test tasks dynamically and creates intermediate fix tasks based on test results.
• Agent Calls: Delegates to /workflow:execute which invokes @test-fix-agent for task execution.
• Note: This command generates tasks; actual execution is performed by /workflow:execute.
• Example:

  /workflow:test-cycle-execute --resume-session="WFS-test-user-auth"