feat: 更新执行命令文档，添加队列ID要求和用户提示功能

2026-02-05 01:50:27 +08:00 · 2026-01-15 16:22:48 +08:00
parent 0c9a6d4154
commit c24ed016cb
4 changed files with 643 additions and 30 deletions
--- a/.claude/commands/issue/execute.md
+++ b/.claude/commands/issue/execute.md
@@ -1,7 +1,7 @@
 ---
 name: execute
 description: Execute queue with DAG-based parallel orchestration (one commit per solution)
-argument-hint: "[--worktree [<existing-path>]] [--queue <queue-id>]"
+argument-hint: "--queue <queue-id> [--worktree [<existing-path>]]"
 allowed-tools: TodoWrite(*), Bash(*), Read(*), AskUserQuestion(*)
 ---

@@ -19,14 +19,57 @@ Minimal orchestrator that dispatches **solution IDs** to executors. Each executo
 - **Executor handles all tasks within a solution sequentially**
 - **Single worktree for entire queue**: One worktree isolates ALL queue execution from main workspace

+## Queue ID Requirement (MANDATORY)
+
+**Queue ID is REQUIRED.** You MUST specify which queue to execute via `--queue <queue-id>`.
+
+### If Queue ID Not Provided
+
+When `--queue` parameter is missing, you MUST:
+
+1. **List available queues** by running:
+```javascript
+const result = Bash('ccw issue queue list --brief --json');
+const index = JSON.parse(result);
+```
+
+2. **Display available queues** to user:
+```
+Available Queues:
+ID                    Status      Progress    Issues
+-----------------------------------------------------------
+→ QUE-20251215-001   active      3/10        ISS-001, ISS-002
+  QUE-20251210-002   active      0/5         ISS-003
+  QUE-20251205-003   completed   8/8         ISS-004
+```
+
+3. **Stop and ask user** to specify which queue to execute:
+```javascript
+AskUserQuestion({
+  questions: [{
+    question: "Which queue would you like to execute?",
+    header: "Queue",
+    multiSelect: false,
+    options: index.queues
+      .filter(q => q.status === 'active')
+      .map(q => ({
+        label: q.id,
+        description: `${q.status}, ${q.completed_solutions || 0}/${q.total_solutions || 0} completed, Issues: ${q.issue_ids.join(', ')}`
+      }))
+  }]
+})
+```
+
+4. **After user selection**, continue execution with the selected queue ID.
+
+**DO NOT auto-select queues.** Explicit user confirmation is required to prevent accidental execution of wrong queue.
+
 ## Usage

 ```bash
-/issue:execute                           # Execute active queue(s)
-/issue:execute --queue QUE-xxx           # Execute specific queue
-/issue:execute --worktree                # Execute entire queue in isolated worktree
-/issue:execute --worktree --queue QUE-xxx
-/issue:execute --worktree /path/to/existing/worktree  # Resume in existing worktree
+/issue:execute --queue QUE-xxx           # Execute specific queue (REQUIRED)
+/issue:execute --queue QUE-xxx --worktree  # Execute in isolated worktree
+/issue:execute --queue QUE-xxx --worktree /path/to/existing/worktree  # Resume
 ```

 **Parallelism**: Determined automatically by task dependency DAG (no manual control)
@@ -44,13 +87,18 @@ Minimal orchestrator that dispatches **solution IDs** to executors. Each executo
 ## Execution Flow

 ```
-Phase 0 (if --worktree): Setup Queue Worktree
+Phase 0: Validate Queue ID (REQUIRED)
+   ├─ If --queue provided → use specified queue
+   ├─ If --queue missing → list queues, prompt user to select
+   └─ Store QUEUE_ID for all subsequent commands
+
+Phase 0.5 (if --worktree): Setup Queue Worktree
   ├─ Create ONE worktree for entire queue: .ccw/worktrees/queue-<timestamp>
   ├─ All subsequent execution happens in this worktree
   └─ Main workspace remains clean and untouched

 Phase 1: Get DAG & User Selection
-   ├─ ccw issue queue dag [--queue QUE-xxx] → { parallel_batches: [["S-1","S-2"], ["S-3"]] }
+   ├─ ccw issue queue dag --queue ${QUEUE_ID} → { parallel_batches: [["S-1","S-2"], ["S-3"]] }
   └─ AskUserQuestion → executor type (codex|gemini|agent), dry-run mode, worktree mode

 Phase 2: Dispatch Parallel Batch (DAG-driven)
@@ -75,11 +123,65 @@ Phase 4 (if --worktree): Worktree Completion

 ## Implementation

+### Phase 0: Validate Queue ID
+
+```javascript
+// Check if --queue was provided
+let QUEUE_ID = args.queue;
+
+if (!QUEUE_ID) {
+  // List available queues
+  const listResult = Bash('ccw issue queue list --brief --json').trim();
+  const index = JSON.parse(listResult);
+
+  if (index.queues.length === 0) {
+    console.log('No queues found. Use /issue:queue to create one first.');
+    return;
+  }
+
+  // Filter active queues only
+  const activeQueues = index.queues.filter(q => q.status === 'active');
+
+  if (activeQueues.length === 0) {
+    console.log('No active queues found.');
+    console.log('Available queues:', index.queues.map(q => `${q.id} (${q.status})`).join(', '));
+    return;
+  }
+
+  // Display and prompt user
+  console.log('\nAvailable Queues:');
+  console.log('ID'.padEnd(22) + 'Status'.padEnd(12) + 'Progress'.padEnd(12) + 'Issues');
+  console.log('-'.repeat(70));
+  for (const q of index.queues) {
+    const marker = q.id === index.active_queue_id ? '→ ' : '  ';
+    console.log(marker + q.id.padEnd(20) + q.status.padEnd(12) +
+      `${q.completed_solutions || 0}/${q.total_solutions || 0}`.padEnd(12) +
+      q.issue_ids.join(', '));
+  }
+
+  const answer = AskUserQuestion({
+    questions: [{
+      question: "Which queue would you like to execute?",
+      header: "Queue",
+      multiSelect: false,
+      options: activeQueues.map(q => ({
+        label: q.id,
+        description: `${q.completed_solutions || 0}/${q.total_solutions || 0} completed, Issues: ${q.issue_ids.join(', ')}`
+      }))
+    }]
+  });
+
+  QUEUE_ID = answer['Queue'];
+}
+
+console.log(`\n## Executing Queue: ${QUEUE_ID}\n`);
+```
+
 ### Phase 1: Get DAG & User Selection

 ```javascript
-// Get dependency graph and parallel batches
-const dagJson = Bash(`ccw issue queue dag`).trim();
+// Get dependency graph and parallel batches (QUEUE_ID required)
+const dagJson = Bash(`ccw issue queue dag --queue ${QUEUE_ID}`).trim();
 const dag = JSON.parse(dagJson);

 if (dag.error || dag.ready_count === 0) {
@@ -298,8 +400,8 @@ ccw issue done ${solutionId} --fail --reason '{"task_id": "TX", "error_type": "t
 ### Phase 3: Check Next Batch

 ```javascript
-// Refresh DAG after batch completes
-const refreshedDag = JSON.parse(Bash(`ccw issue queue dag`).trim());
+// Refresh DAG after batch completes (use same QUEUE_ID)
+const refreshedDag = JSON.parse(Bash(`ccw issue queue dag --queue ${QUEUE_ID}`).trim());

 console.log(`
 ## Batch Complete
@@ -309,9 +411,9 @@ console.log(`
 `);

 if (refreshedDag.ready_count > 0) {
-  console.log('Run `/issue:execute` again for next batch.');
+  console.log(`Run \`/issue:execute --queue ${QUEUE_ID}\` again for next batch.`);
  // Note: If resuming, pass existing worktree path:
-  // /issue:execute --worktree <worktreePath>
+  // /issue:execute --queue ${QUEUE_ID} --worktree <worktreePath>
 }
 ```

@@ -367,10 +469,12 @@ if (useWorktree && refreshedDag.ready_count === 0 && refreshedDag.completed_coun
 ┌─────────────────────────────────────────────────────────────────┐
 │ Orchestrator                                                    │
 ├─────────────────────────────────────────────────────────────────┤
-│ 0. (if --worktree) Create ONE worktree for entire queue         │
+│ 0. Validate QUEUE_ID (required, or prompt user to select)       │
+│                                                                 │
+│ 0.5 (if --worktree) Create ONE worktree for entire queue        │
 │    → .ccw/worktrees/queue-exec-<queue-id>                       │
 │                                                                 │
-│ 1. ccw issue queue dag                                          │
+│ 1. ccw issue queue dag --queue ${QUEUE_ID}                      │
 │    → { parallel_batches: [["S-1","S-2"], ["S-3"]] }             │
 │                                                                 │
 │ 2. Dispatch batch 1 (parallel, SAME worktree):                  │
@@ -405,8 +509,19 @@ if (useWorktree && refreshedDag.ready_count === 0 && refreshedDag.completed_coun

 ## CLI Endpoint Contract

-### `ccw issue queue dag`
-Returns dependency graph with parallel batches (solution-level):
+### `ccw issue queue list --brief --json`
+Returns queue index for selection (used when --queue not provided):
+```json
+{
+  "active_queue_id": "QUE-20251215-001",
+  "queues": [
+    { "id": "QUE-20251215-001", "status": "active", "issue_ids": ["ISS-001"], "total_solutions": 5, "completed_solutions": 2 }
+  ]
+}
+```
+
+### `ccw issue queue dag --queue <queue-id>`
+Returns dependency graph with parallel batches (solution-level, **--queue required**):
 ```json
 {
  "queue_id": "QUE-...",
--- a/.codex/prompts/issue-execute.md
+++ b/.codex/prompts/issue-execute.md
@@ -1,6 +1,6 @@
 ---
 description: Execute all solutions from issue queue with git commit after each solution
-argument-hint: "[--worktree [<existing-path>]] [--queue <queue-id>]"
+argument-hint: "--queue <queue-id> [--worktree [<existing-path>]]"
 ---

 # Issue Execute (Codex Version)
@@ -9,6 +9,49 @@ argument-hint: "[--worktree [<existing-path>]] [--queue <queue-id>]"

 **Serial Execution**: Execute solutions ONE BY ONE from the issue queue via `ccw issue next`. For each solution, complete all tasks sequentially (implement → test → verify), then commit once per solution with formatted summary. Continue autonomously until queue is empty.

+## Queue ID Requirement (MANDATORY)
+
+**Queue ID is REQUIRED.** You MUST specify which queue to execute via `--queue <queue-id>`.
+
+### If Queue ID Not Provided
+
+When `--queue` parameter is missing, you MUST:
+
+1. **List available queues** by running:
+```javascript
+const result = shell_command({ command: "ccw issue queue list --brief --json" })
+```
+
+2. **Parse and display queues** to user:
+```
+Available Queues:
+ID                    Status      Progress    Issues
+-----------------------------------------------------------
+→ QUE-20251215-001   active      3/10        ISS-001, ISS-002
+  QUE-20251210-002   active      0/5         ISS-003
+  QUE-20251205-003   completed   8/8         ISS-004
+```
+
+3. **Stop and ask user** to specify which queue to execute:
+```javascript
+AskUserQuestion({
+  questions: [{
+    question: "Which queue would you like to execute?",
+    header: "Queue",
+    multiSelect: false,
+    options: [
+      // Generate from parsed queue list - only show active/pending queues
+      { label: "QUE-20251215-001", description: "active, 3/10 completed, Issues: ISS-001, ISS-002" },
+      { label: "QUE-20251210-002", description: "active, 0/5 completed, Issues: ISS-003" }
+    ]
+  }]
+})
+```
+
+4. **After user selection**, continue execution with the selected queue ID.
+
+**DO NOT auto-select queues.** Explicit user confirmation is required to prevent accidental execution of wrong queue.
+
 ## Worktree Mode (Recommended for Parallel Execution)

 When `--worktree` is specified, create or use a git worktree to isolate work.
@@ -77,7 +120,8 @@ cd "${WORKTREE_PATH}"

 **Worktree Execution Pattern**:
 ```
-1. [WORKTREE] ccw issue next → auto-redirects to main repo's .workflow/
+0. [MAIN REPO] Validate queue ID (--queue required, or prompt user to select)
+1. [WORKTREE] ccw issue next --queue <queue-id> → auto-redirects to main repo's .workflow/
 2. [WORKTREE] Implement all tasks, run tests, git commit
 3. [WORKTREE] ccw issue done <item_id> → auto-redirects to main repo
 4. Repeat from step 1
@@ -177,10 +221,12 @@ echo "Branch '${WORKTREE_NAME}' kept. Merge manually when ready."
 ## Execution Flow

 ```
-INIT: Fetch first solution via ccw issue next
+STEP 0: Validate queue ID (--queue required, or prompt user to select)
+
+INIT: Fetch first solution via ccw issue next --queue <queue-id>

 WHILE solution exists:
-  1. Receive solution JSON from ccw issue next
+  1. Receive solution JSON from ccw issue next --queue <queue-id>
  2. Execute all tasks in solution.tasks sequentially:
     FOR each task:
       - IMPLEMENT: Follow task.implementation steps
@@ -188,7 +234,7 @@ WHILE solution exists:
       - VERIFY: Check task.acceptance criteria
  3. COMMIT: Stage all files, commit once with formatted summary
  4. Report completion via ccw issue done <item_id>
-  5. Fetch next solution via ccw issue next
+  5. Fetch next solution via ccw issue next --queue <queue-id>

 WHEN queue empty:
  Output final summary
@@ -196,11 +242,14 @@ WHEN queue empty:

 ## Step 1: Fetch First Solution

+**Prerequisite**: Queue ID must be determined (either from `--queue` argument or user selection in Step 0).
+
 Run this command to get your first solution:

 ```javascript
 // ccw auto-detects worktree and uses main repo's .workflow/
-const result = shell_command({ command: "ccw issue next" })
+// QUEUE_ID is required - obtained from --queue argument or user selection
+const result = shell_command({ command: `ccw issue next --queue ${QUEUE_ID}` })
 ```

 This returns JSON with the full solution definition:
@@ -494,11 +543,12 @@ shell_command({

 ## Step 5: Continue to Next Solution

-Fetch next solution:
+Fetch next solution (using same QUEUE_ID from Step 0/1):

 ```javascript
 // ccw auto-detects worktree
-const result = shell_command({ command: "ccw issue next" })
+// Continue using the same QUEUE_ID throughout execution
+const result = shell_command({ command: `ccw issue next --queue ${QUEUE_ID}` })
 ```

 **Output progress:**
@@ -567,18 +617,28 @@ When `ccw issue next` returns `{ "status": "empty" }`:

 | Command | Purpose |
 |---------|---------|
-| `ccw issue next` | Fetch next solution from queue (auto-selects from active queues) |
-| `ccw issue next --queue QUE-xxx` | Fetch from specific queue |
+| `ccw issue queue list --brief --json` | List all queues (for queue selection) |
+| `ccw issue next --queue QUE-xxx` | Fetch next solution from specified queue (**--queue required**) |
 | `ccw issue done <id>` | Mark solution complete with result (auto-detects queue) |
 | `ccw issue done <id> --fail --reason "..."` | Mark solution failed with structured reason |
 | `ccw issue retry --queue QUE-xxx` | Reset failed items in specific queue |

 ## Start Execution

-Begin by running:
+**Step 0: Validate Queue ID**
+
+If `--queue` was NOT provided in the command arguments:
+1. Run `ccw issue queue list --brief --json`
+2. Display available queues to user
+3. Ask user to select a queue via `AskUserQuestion`
+4. Store selected queue ID for all subsequent commands
+
+**Step 1: Fetch First Solution**
+
+Once queue ID is confirmed, begin by running:

 ```bash
-ccw issue next
+ccw issue next --queue <queue-id>
 ```

 Then follow the solution lifecycle for each solution until queue is empty.
--- a/README.md
+++ b/README.md
@@ -281,6 +281,9 @@ CCW provides comprehensive documentation to help you get started quickly and mas
 - [**Dashboard Guide**](DASHBOARD_GUIDE.md) - Dashboard user guide and interface overview
 - [**Dashboard Operations**](DASHBOARD_OPERATIONS_EN.md) - Detailed operation instructions

+### 🔄 **Workflow Guides**
+- [**Issue Loop Workflow**](docs/workflows/ISSUE_LOOP_WORKFLOW.md) - Batch issue processing with two-phase lifecycle (accumulate → resolve)
+
 ### 🏗️ **Architecture & Design**
 - [**Architecture Overview**](ARCHITECTURE.md) - System design and core components
 - [**Project Introduction**](PROJECT_INTRODUCTION.md) - Detailed project overview
--- a/docs/workflows/ISSUE_LOOP_WORKFLOW.md
+++ b/docs/workflows/ISSUE_LOOP_WORKFLOW.md
@@ -0,0 +1,435 @@
+# 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 描述的高质量