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

docs: consolidate documentation with 4-level workflow guide

Browse Source 
- Add WORKFLOW_GUIDE.md (EN) and WORKFLOW_GUIDE_CN.md (CN)
- Simplify README.md to highlight 4-level workflow system
- Remove redundant docs: MCP_*.md, WORKFLOW_DECISION_GUIDE*.md, WORKFLOW_DIAGRAMS.md
- Move COMMAND_SPEC.md to docs/
- Move codex_mcp.md, CODEX_LENS_AUTO_HYBRID.md to codex-lens/docs/
- Delete temporary debug documents and outdated files

Root directory: 28 → 14 MD files
This commit is contained in:
catlog22
2026-01-17 10:38:06 +08:00
parent 464f3343f3
commit bc4176fda0
20 changed files with 1459 additions and 5515 deletions
Download Patch File Download Diff File Expand all files Collapse all files

449
docs/COMMAND_SPEC.md Normal file
View File

@@ -0,0 +1,449 @@
# Claude Code Workflow (CCW) - Command Specification
**Version**: 6.2.0
**Updated**: 2025-12-20
## 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 6.2.0 Changes**: Native CodexLens replaces Code Index MCP (FTS + Semantic + HNSW), CLI refactored to `ccw cli -p`, session clustering replaces knowledge graph, new Dashboard views (CLAUDE.md Manager, Skills Manager, Graph Explorer, Core Memory), TypeScript backend migration.
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:lite-plan** ⚡ NEW
- **Syntax**: `/workflow:lite-plan [--tool claude|gemini|qwen|codex] [-e|--explore] "task description"|file.md`
- **Parameters**:
- `--tool` (Optional, String): Preset CLI tool for execution (claude|gemini|qwen|codex). If not provided, user selects during confirmation.
- `-e, --explore` (Optional, Flag): Force code exploration phase (overrides auto-detection logic).
- `task description|file.md` (Required, String): Task description or path to .md file.
- **Responsibilities**: Lightweight interactive planning and execution workflow with 5 phases:
1. **Task Analysis & Exploration**: Auto-detects need for codebase context, optionally launches `@cli-explore-agent` (30-90s)
2. **Clarification**: Interactive Q&A based on exploration findings (user-dependent)
3. **Planning**: Adaptive planning strategy - direct (Low complexity) or delegate to `@cli-planning-agent` (Medium/High complexity) (20-60s)
4. **Three-Dimensional Confirmation**: Multi-select interaction for task approval + execution method + code review tool (user-dependent)
5. **Execution & Tracking**: Live TodoWrite progress updates with selected method (5-120min)
- **Key Features**:
- **Smart Code Exploration**: Auto-detects when codebase context is needed (use `-e` to force)
- **In-Memory Planning**: No file artifacts generated during planning phase
- **Three-Dimensional Multi-Select**: Task approval (Allow/Modify/Cancel) + Execution method (Agent/Provide Plan/CLI) + Code review (No/Claude/Gemini/Qwen/Codex)
- **Parallel Task Execution**: Identifies independent tasks for concurrent execution
- **Flexible Execution**: Choose between Agent (@code-developer) or CLI (Gemini/Qwen/Codex)
- **Optional Post-Review**: Built-in code quality analysis with user-selectable AI tool
- **Agent Calls**:
- `@cli-explore-agent` (conditional, Phase 1)
- `@cli-planning-agent` (conditional, Phase 3 for Medium/High complexity)
- `@code-developer` (conditional, Phase 5 if Agent execution selected)
- **Skill Invocation**: None directly, but agents may invoke skills.
- **Integration**: Standalone workflow for quick tasks. Alternative to `/workflow:plan` + `/workflow:execute` pattern.
- **Example**:
```bash
# Basic usage with auto-detection
/workflow:lite-plan "Add JWT authentication to user login"
# Force code exploration
/workflow:lite-plan -e "Refactor logging module for better performance"
# Basic usage
/workflow:lite-plan "Add unit tests for auth service"
```
### **/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` 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 moves the session from `.workflow/active/` to `.workflow/archives/`.
- **Agent Calls**: None.
- **Example**:
```bash
/workflow:session:complete
```
---
## 5. CLI Commands
CLI tool configuration commands.
### **/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
```
> **Note**: For analysis, planning, and bug fixing, use workflow commands (`/workflow:lite-plan`, `/workflow:lite-fix`) or semantic invocation through natural language. Claude will automatically use appropriate CLI tools (Gemini/Qwen/Codex) with templates as needed.
---
## 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 <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**:
```bash
/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**:
```bash
/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**:
```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 <directory>]`
- **Responsibilities**: Orchestrates a complete, project-wide update of all `CLAUDE.md` documentation files.
- **Agent Calls**: None directly, but orchestrates CLI tools (`gemini`, etc.).
- **Example**:
```bash
/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**:
```bash
/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**:
```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 <user input>` or use `-e` flag in conversation
- **Responsibilities**: A system-level skill that enhances a user's prompt by adding context from session memory and codebase analysis. It is typically triggered by the `-e` flag in natural conversation.
- **Skill Invocation**: This is a core skill, invoked when `-e` is used in conversation.
- **Agent Calls**: None.
- **Example (in natural conversation)**:
```
User: "fix the login button -e"
→ Prompt-enhancer expands and enhances the request
```
---
## 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 --input "<value>" [--session <id>]`
- **Responsibilities**: UI design workflow with direct code/image input for design token extraction and prototype generation. Accepts local code files, images (glob patterns), or text descriptions.
- **Agent Calls**: `@ui-design-agent`.
- **Example**:
```bash
# Image reference
/workflow:ui-design:imitate-auto --input "design-refs/*.png"
# Code import
/workflow:ui-design:imitate-auto --input "./src/components"
# Text prompt
/workflow:ui-design:imitate-auto --input "Modern minimalist design"
```
### **/workflow:ui-design:style-extract**
- **Syntax**: `/workflow:ui-design:style-extract [--images "<glob>"] [--prompt "<desc>"] [--variants <count>] ...`
- **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 "<glob>"] [--prompt "<desc>"] [--targets "<list>"] ...`
- **Responsibilities**: Extracts structural layout information (HTML structure, CSS layout rules) from images or text prompts.
- **Agent Calls**: `@ui-design-agent`.
- **Example**:
```bash
/workflow:ui-design:layout-extract --images "design-refs/*.png" --targets "home,dashboard"
```
### **/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**:
```bash
/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**:
```bash
/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**:
```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`.
- **Example**:
```bash
/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**:
```bash
/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**:
```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 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**:
```bash
/workflow:test-cycle-execute --resume-session="WFS-test-user-auth"
```

435
docs/workflows/ISSUE_LOOP_WORKFLOW.md
View File

@@ -1,435 +0,0 @@
# CCW Issue Loop 工作流完全指南
> 两阶段生命周期设计，支持在项目迭代中积累问题并集中解决
---
## 目录
1. [什么是 Issue Loop 工作流](#什么是-issue-loop-工作流)
2. [核心架构](#核心架构)
3. [两阶段生命周期](#两阶段生命周期)
4. [命令详解](#命令详解)
5. [使用场景](#使用场景)
6. [推荐策略](#推荐策略)
7. [串行无监管执行](#串行无监管执行)
8. [最佳实践](#最佳实践)
---
## 什么是 Issue Loop 工作流
Issue Loop 是 CCW (Claude Code Workflow) 中的批量问题处理工作流，专为处理项目迭代过程中积累的多个问题而设计。与单次修复不同，Issue Loop 采用 **"积累 → 规划 → 队列 → 执行"** 的模式，实现问题的批量发现和集中解决。
### 核心理念
```
传统模式：发现问题 → 立即修复 → 发现问题 → 立即修复 → ...
↓
Issue Loop：持续积累 → 集中规划 → 队列优化 → 批量执行
```
**优势**：
- 避免频繁上下文切换
- 冲突检测和依赖排序
- 并行执行支持
- 完整的追踪和审计
---
## 核心架构
```
┌─────────────────────────────────────────────────────────────────┐
│ Issue Loop Workflow │
├─────────────────────────────────────────────────────────────────┤
│ Phase 1: Accumulation (积累) │
│ /issue:discover, /issue:discover-by-prompt, /issue:new │
├─────────────────────────────────────────────────────────────────┤
│ Phase 2: Batch Resolution (批量解决) │
│ /issue:plan → /issue:queue → /issue:execute │
└─────────────────────────────────────────────────────────────────┘
```
### 数据流转
```
issues.jsonl → solutions/<id>.jsonl → queues/<queue-id>.json → 执行
↓ ↓ ↓
Issue 记录 解决方案 优先级排序 + 冲突检测
```
---
## 两阶段生命周期
### Phase 1: Accumulation (积累阶段)
在项目正常迭代过程中，持续发现和记录问题：
| 触发场景 | 对应命令 | 说明 |
|----------|----------|------|
| 任务完成后 Review | `/issue:discover` | 自动分析代码发现潜在问题 |
| 代码审查发现 | `/issue:new` | 手动创建结构化 Issue |
| 测试失败 | `/issue:discover-by-prompt` | 根据描述创建 Issue |
| 用户反馈 | `/issue:new` | 手动录入反馈问题 |
**Issue 状态流转**：
```
registered → planned → queued → executing → completed
↓
issue-history.jsonl
```
### Phase 2: Batch Resolution (批量解决阶段)
积累足够 Issue 后，集中处理：
```
Step 1: /issue:plan --all-pending # 为所有待处理 Issue 生成解决方案
Step 2: /issue:queue # 形成执行队列（冲突检测 + 排序）
Step 3: /issue:execute # 批量执行（串行或并行）
```
---
## 命令详解
### 积累阶段命令
#### `/issue:new`
手动创建结构化 Issue：
```bash
ccw issue init <id> --title "Issue 标题" --priority P2
```
#### `/issue:discover`
自动分析代码发现问题：
```bash
# 使用 gemini 进行多视角分析
# 发现：bug、安全问题、性能问题、代码规范等
```
#### `/issue:discover-by-prompt`
根据描述创建 Issue：
```bash
# 输入问题描述，自动生成结构化 Issue
```
### 批量解决阶段命令
#### `/issue:plan`
为 Issue 生成解决方案：
```bash
ccw issue plan --all-pending # 规划所有待处理 Issue
ccw issue plan ISS-001 # 规划单个 Issue
```
**输出**：每个 Issue 生成包含以下内容的解决方案：
- 修改点 (modification_points)
- 实现步骤 (implementation)
- 测试要求 (test)
- 验收标准 (acceptance)
#### `/issue:queue`
形成执行队列：
```bash
ccw issue queue # 创建新队列
ccw issue queue add <id> # 添加到当前队列
ccw issue queue list # 查看队列历史
```
**关键功能**：
- 冲突检测：使用 Gemini CLI 分析解决方案间的文件冲突
- 依赖排序：根据依赖关系确定执行顺序
- 优先级加权：高优先级 Issue 优先执行
#### `/issue:execute`
执行队列中的解决方案：
```bash
ccw issue next # 获取下一个待执行解决方案
ccw issue done <item_id> # 标记完成
ccw issue done <id> --fail # 标记失败
```
### 管理命令
```bash
ccw issue list # 列出活跃 Issue
ccw issue status <id> # 查看 Issue 详情
ccw issue history # 查看已完成 Issue
ccw issue update --from-queue # 从队列同步状态
```
---
## 使用场景
### 场景 1: 项目迭代后的技术债务清理
```
1. 完成 Sprint 功能开发
2. 执行 /issue:discover 发现技术债务
3. 积累一周后，执行 /issue:plan --all-pending
4. 使用 /issue:queue 形成队列
5. 使用 codex 执行 /issue:execute 批量处理
```
### 场景 2: 代码审查后的批量修复
```
1. 完成 PR 代码审查
2. 对每个发现执行 /issue:new 创建 Issue
3. 积累本次审查的所有发现
4. 执行 /issue:plan → /issue:queue → /issue:execute
```
### 场景 3: 测试失败的批量处理
```
1. 运行测试套件
2. 对失败的测试执行 /issue:discover-by-prompt
3. 一次性规划所有失败修复
4. 串行执行确保不引入新问题
```
### 场景 4: 安全漏洞批量修复
```
1. 安全扫描发现多个漏洞
2. 每个漏洞创建 Issue 并标记 P1 优先级
3. 使用 /issue:queue 自动按严重度排序
4. 执行修复并验证
```
---
## 推荐策略
### 何时使用 Issue Loop
| 条件 | 推荐 |
|------|------|
| 问题数量 >= 3 | Issue Loop |
| 问题涉及多个模块 | Issue Loop |
| 问题间可能有依赖 | Issue Loop |
| 需要冲突检测 | Issue Loop |
| 单个简单 bug | `/workflow:lite-fix` |
| 紧急生产问题 | `/workflow:lite-fix --hotfix` |
### 积累策略
**推荐阈值**：
- 积累 5-10 个 Issue 后集中处理
- 或按时间周期（如每周五下午）统一处理
- 紧急问题除外，立即标记 P1 并单独处理
### 队列策略
```javascript
// 冲突检测规则
if (solution_A.files ∩ solution_B.files !== ∅) {
// 存在文件冲突，需要串行执行
queue.addDependency(solution_A, solution_B)
}
// 优先级排序
sort by:
1. priority (P1 > P2 > P3)
2. dependencies (被依赖的先执行)
3. complexity (低复杂度先执行)
```
---
## 串行无监管执行
**推荐使用 Codex 命令进行串行无监管执行**：
```bash
codex -p "@.codex/prompts/issue-execute.md"
```
### 执行流程
```
INIT: ccw issue next
↓
WHILE solution exists:
├── 1. 解析 solution JSON
├── 2. 逐个执行 tasks:
│ ├── IMPLEMENT: 按步骤实现
│ ├── TEST: 运行测试验证
│ └── VERIFY: 检查验收标准
├── 3. 提交代码 (每个 solution 一次 commit)
├── 4. 报告完成: ccw issue done <id>
└── 5. 获取下一个: ccw issue next
↓
COMPLETE: 输出最终报告
```
### Worktree 模式（推荐并行执行）
```bash
# 创建隔离的工作树
codex -p "@.codex/prompts/issue-execute.md --worktree"
# 恢复中断的执行
codex -p "@.codex/prompts/issue-execute.md --worktree /path/to/existing"
```
**优势**：
- 并行执行器不冲突
- 主工作目录保持干净
- 执行完成后易于清理
- 支持中断恢复
### 执行规则
1. **永不中途停止** - 持续执行直到队列为空
2. **一次一个解决方案** - 完全完成（所有任务 + 提交 + 报告）后继续
3. **解决方案内串行** - 每个任务的实现/测试/验证按顺序完成
4. **测试必须通过** - 任何任务测试失败则修复后继续
5. **每解决方案一次提交** - 所有任务共享一次 commit
6. **自我验证** - 所有验收标准必须通过
7. **准确报告** - 使用 `ccw issue done` 报告完成
8. **优雅处理失败** - 失败时报告并继续下一个
### Commit 格式
```
[commit_type](scope): [solution.description]
## Solution Summary
- **Solution-ID**: SOL-ISS-20251227-001-1
- **Issue-ID**: ISS-20251227-001
- **Risk/Impact/Complexity**: low/medium/low
## Tasks Completed
- [T1] 实现用户认证: Modify src/auth/
- [T2] 添加测试覆盖: Add tests/auth/
## Files Modified
- src/auth/login.ts
- tests/auth/login.test.ts
## Verification
- All unit tests passed
- All acceptance criteria verified
```
---
## 最佳实践
### 1. Issue 质量
创建高质量的 Issue 描述：
```json
{
"title": "清晰简洁的标题",
"context": {
"problem": "具体问题描述",
"impact": "影响范围",
"reproduction": "复现步骤（如适用）"
},
"priority": "P1-P5"
}
```
### 2. Solution 审查
在执行前审查生成的解决方案：
```bash
ccw issue status <id> # 查看解决方案详情
```
检查点：
- 修改点是否准确
- 测试覆盖是否充分
- 验收标准是否可验证
### 3. 队列监控
```bash
ccw issue queue # 查看当前队列状态
ccw issue queue list # 查看队列历史
```
### 4. 失败处理
```bash
# 单个失败
ccw issue done <id> --fail --reason '{"task_id": "T1", "error": "..."}'
# 重试失败项
ccw issue retry --queue QUE-xxx
```
### 5. 历史追溯
```bash
ccw issue history # 查看已完成 Issue
ccw issue history --json # JSON 格式导出
```
---
## 工作流对比
| 维度 | Issue Loop | lite-fix | coupled |
|------|------------|----------|---------|
| **适用场景** | 批量问题 | 单个 bug | 复杂功能 |
| **问题数量** | 3+ | 1 | 1 |
| **生命周期** | 两阶段 | 单次 | 多阶段 |
| **冲突检测** | 有 | 无 | 无 |
| **并行支持** | Worktree 模式 | 无 | 无 |
| **追踪审计** | 完整 | 基础 | 完整 |
---
## 快速参考
### 完整流程命令
```bash
# 1. 积累阶段
/issue:new # 手动创建
/issue:discover # 自动发现
# 2. 规划阶段
/issue:plan --all-pending
# 3. 队列阶段
/issue:queue
# 4. 执行阶段（推荐使用 codex）
codex -p "@.codex/prompts/issue-execute.md"
# 或手动执行
/issue:execute
```
### CLI 命令速查
```bash
ccw issue list # 列出 Issue
ccw issue status <id> # 查看详情
ccw issue plan --all-pending # 批量规划
ccw issue queue # 创建队列
ccw issue next # 获取下一个
ccw issue done <id> # 标记完成
ccw issue history # 查看历史
```
---
## 总结
Issue Loop 工作流是 CCW 中处理批量问题的最佳选择，通过两阶段生命周期设计，实现了问题的高效积累和集中解决。配合 Codex 的串行无监管执行能力，可以在保证质量的同时大幅提升效率。
**记住**：
- 积累足够数量（5-10 个）后再集中处理
- 使用 Codex 进行串行无监管执行
- 利用 Worktree 模式实现并行执行
- 保持 Issue 描述的高质量