workflow-plan

统一规划技能，结合 4 阶段规划工作流、计划质量验证和交互式重新规划。生成 IMPL_PLAN.md、任务 JSON、验证报告，并通过会话级制品更新管理计划生命周期。按模式（plan | verify | replan）路由，并充当纯编排器：执行各阶段、解析输出并传递上下文。

1. 架构概览

┌──────────────────────────────────────────────────────────────────┐
│  Workflow Plan Orchestrator (SKILL.md)                            │
│  → Route by mode: plan | verify | replan                         │
│  → Pure coordinator: Execute phases, parse outputs, pass context │
└──────────────────────────────────┬───────────────────────────────┘
                                │
        ┌───────────────────────┼───────────────────────┐
        ↓                       ↓                       ↓
  ┌───────────┐          ┌───────────┐           ┌───────────┐
  │ Plan Mode │          │  Verify   │           │  Replan   │
  │ (default) │          │   Mode    │           │   Mode    │
  │ Phase 1-4 │          │  Phase 5  │           │  Phase 6  │
  └─────┬─────┘          └───────────┘           └───────────┘
        │
    ┌───┼───┬───┐
    ↓   ↓   ↓   ↓
  ┌───┐┌───┐┌───┐┌───┐
  │ 1 ││ 2 ││ 3 ││ 4 │
  │Ses││Ctx││Con││Gen│
  └───┘└───┘└───┘└─┬─┘
                    ↓
              ┌───────────┐
              │ Confirm   │─── Verify ──→ Phase 5
              │ (choice)  │─── Execute ─→ Skill("workflow-execute")
              └───────────┘─── Review ──→ Display session status inline

2. 关键设计原则

1. 纯编排器：SKILL.md 仅负责路由和协调；执行细节位于各阶段文件中
2. 渐进式阶段加载：仅在某阶段即将执行时读取该阶段文档
3. 多模式路由：单个技能通过模式检测处理 plan/verify/replan
4. 任务附加模型：子命令任务会被附加、依次执行，然后折叠
5. 自动继续：每个阶段完成后，自动执行下一个待处理阶段
6. 累积状态：planning-notes.md 在各阶段间传递上下文，供 N+1 决策使用

3. 交互式偏好收集

在分派阶段执行前，通过 AskUserQuestion 收集工作流偏好：

// ★ 统一 auto mode 检测：-y/--yes 从 $ARGUMENTS 或 ccw 传播
const autoYes = /\b(-y|--yes)\b/.test($ARGUMENTS)

if (autoYes) {
  // 自动模式：跳过所有询问，使用默认值
  workflowPreferences = { autoYes: true, interactive: false }
} else {
  const prefResponse = AskUserQuestion({
    questions: [
      {
        question: "是否跳过所有确认步骤（自动模式）？",
        header: "Auto Mode",
        multiSelect: false,
        options: [
          { label: "Interactive (Recommended)", description: "交互模式，包含确认步骤" },
          { label: "Auto", description: "跳过所有确认，自动执行" }
        ]
      }
    ]
  })

  workflowPreferences = {
    autoYes: prefResponse.autoMode === 'Auto'
  }

  // For replan mode, also collect interactive preference
  if (mode === 'replan') {
    const replanPref = AskUserQuestion({
      questions: [
        {
          question: "是否使用交互式澄清模式？",
          header: "Replan Mode",
          multiSelect: false,
          options: [
            { label: "Standard (Recommended)", description: "使用安全默认值" },
            { label: "Interactive", description: "通过提问交互式澄清修改范围" }
          ]
        }
      ]
    })
    workflowPreferences.interactive = replanPref.replanMode === 'Interactive'
  }
}

workflowPreferences 作为上下文变量传递给阶段执行，并在阶段内通过 workflowPreferences.autoYes、workflowPreferences.interactive 引用。

4. 模式检测

const args = $ARGUMENTS
const mode = detectMode(args)

function detectMode(args) {
  // Skill trigger determines mode
  if (skillName === 'workflow-plan-verify') return 'verify'
  if (skillName === 'workflow:replan') return 'replan'
  return 'plan'  // default: workflow-plan
}

5. 压缩恢复（阶段持久化）

多阶段规划（Phase 1-4/5/6）会跨越较长的对话。使用双重保险：通过 TodoWrite 跟踪活动阶段，避免其被压缩；sentinel 用作后备。

⚠️ COMPACT DIRECTIVE：上下文压缩时必须检查 TodoWrite 阶段状态。 当前标记为 in_progress 的阶段是活动执行阶段——必须保留其完整内容。 仅压缩标记为 completed 或 pending 的阶段。

6. 执行流程

计划模式（默认）

Input Parsing:
   └─ Convert user input to structured format (GOAL/SCOPE/CONTEXT)

Phase 1: Session Discovery
   └─ Ref: Read("phases/01-session-discovery.md")
      └─ Output: sessionId (WFS-xxx), planning-notes.md

Phase 2: Context Gathering
   └─ Ref: Read("phases/02-context-gathering.md")
      ├─ Tasks attached: Analyze structure → Identify integration → Generate package
      └─ Output: contextPath + conflictRisk

Phase 3: Conflict Resolution (conditional: conflictRisk ≥ medium)
   └─ Decision (conflictRisk check):
      ├─ conflictRisk ≥ medium → Ref: Read("phases/03-conflict-resolution.md")
      │   ├─ Tasks attached: Detect conflicts → Present to user → Apply strategies
      │   └─ Output: Modified brainstorm artifacts
      └─ conflictRisk < medium → Skip to Phase 4

Phase 4: Task Generation
   └─ Ref: Read("phases/04-task-generation.md")
      └─ Output: IMPL_PLAN.md, task JSONs, TODO_LIST.md

Plan Confirmation (User Decision Gate):
   └─ Decision (user choice):
      ├─ "Verify Plan Quality" (Recommended) → Route to Phase 5 (plan-verify)
      ├─ "Start Execution" → Skill(skill="workflow-execute")
      └─ "Review Status Only" → Display session status inline

验证模式

Phase 5: Plan Verification
   └─ Ref: Read("phases/05-plan-verify.md")
      └─ Output: PLAN_VERIFICATION.md with quality gate recommendation

重新规划模式

Phase 6: Interactive Replan
   └─ Ref: Read("phases/06-replan.md")
      └─ Output: Updated IMPL_PLAN.md, task JSONs, TODO_LIST.md

阶段参考文档（在阶段执行时按需读取）：

阶段	文档	用途	模式	压缩
1	phases/01-session-discovery.md	创建或发现工作流会话	plan	TodoWrite 驱动
2	phases/02-context-gathering.md	收集项目上下文并分析代码库	plan	TodoWrite 驱动
3	phases/03-conflict-resolution.md	检测并解决冲突（有条件执行）	plan	TodoWrite 驱动
4	phases/04-task-generation.md	生成实施计划和任务 JSON	plan	TodoWrite 驱动 + 🔄 sentinel
5	phases/05-plan-verify.md	通过质量门进行只读验证	verify	TodoWrite 驱动
6	phases/06-replan.md	通过边界澄清进行交互式重新规划	replan	TodoWrite 驱动

压缩规则：

1. TodoWrite in_progress → 保留完整内容，禁止压缩
2. TodoWrite completed → 可压缩为摘要
3. 🔄 sentinel 后备 → Phase 4 包含 compact sentinel；若压缩后仅剩 sentinel 而没有完整的 Step 协议，必须立即执行 Read("phases/04-task-generation.md") 进行恢复

7. 核心规则

1. 立即开始：第一个操作是模式检测 + TodoWrite 初始化，第二个操作是阶段执行
2. 不做初步分析：Phase 1 之前不要读取文件、分析结构或收集上下文
3. 解析每项输出：从每个阶段的输出中提取下一阶段所需的数据
4. 通过 TodoList 自动继续：检查 TodoList 状态，自动执行下一个待处理阶段
5. 跟踪进度：使用任务附加/折叠模式动态更新 TodoWrite
6. 任务附加模型：技能执行会将子任务附加到当前工作流。编排器会自行执行这些附加任务，并在完成后将其折叠
7. 渐进式阶段加载：仅在某阶段即将执行时读取该阶段文档
8. 不要停止：保持多阶段工作流连续执行。执行完所有附加任务后，立即将其折叠并执行下一阶段

## 8. 输入处理

将用户输入转换为结构化格式：

1. 简单文本 → 将其结构化：

   User: "Build authentication system"
   
   Structured:
   GOAL: Build authentication system
   SCOPE: Core authentication features
   CONTEXT: New implementation
   

2. 详细文本 → 提取组成部分：

   User: "Add JWT authentication with email/password login and token refresh"
   
   Structured:
   GOAL: Implement JWT-based authentication
   SCOPE: Email/password login, token generation, token refresh endpoints
   CONTEXT: JWT token-based security, refresh token rotation
   

3. 文件引用（例如，requirements.md）→ 读取并结构化：

   • 读取文件内容
   • 提取目标、范围和要求
   • 格式化为结构化描述

9. 数据流

计划模式

User Input (task description)
    ↓
[Convert to Structured Format]
    ↓ Structured Description:
    ↓   GOAL: [objective]
    ↓   SCOPE: [boundaries]
    ↓   CONTEXT: [background]
    ↓
Phase 1: session:start --auto "structured-description"
    ↓ Output: sessionId
    ↓ Write: planning-notes.md (User Intent section)
    ↓
Phase 2: context-gather --session sessionId "structured-description"
    ↓ Input: sessionId + structured description
    ↓ Output: contextPath (context-package.json) + conflictRisk
    ↓ Update: planning-notes.md (Context Findings + Consolidated Constraints)
    ↓
Phase 3: conflict-resolution [conditional: conflictRisk ≥ medium]
    ↓ Input: sessionId + contextPath + conflictRisk
    ↓ Output: Modified brainstorm artifacts
    ↓ Update: planning-notes.md (Conflict Decisions + Consolidated Constraints)
    ↓ Skip if conflictRisk is none/low → proceed directly to Phase 4
    ↓
Phase 4: task-generate-agent --session sessionId
    ↓ Input: sessionId + planning-notes.md + context-package.json + brainstorm artifacts
    ↓ Output: IMPL_PLAN.md, task JSONs, TODO_LIST.md
    ↓
Plan Confirmation (User Decision Gate):
    ├─ "Verify Plan Quality" (Recommended) → Route to Phase 5
    ├─ "Start Execution" → Skill(skill="workflow-execute")
    └─ "Review Status Only" → Display session status inline

会话记忆流：每个阶段都会接收会话 ID，以便访问：

• 之前的任务摘要
• 现有上下文和分析
• 头脑风暴成果（可能已由阶段 3 修改）
• 特定于会话的配置

验证模式

Input: --session sessionId (or auto-detect)
    ↓
Phase 5: Load artifacts → Agent-driven verification → Generate report
    ↓ Output: PLAN_VERIFICATION.md with quality gate

重新规划模式

Input: [--session sessionId] [task-id] "requirements"
    ↓
Phase 6: Mode detection → Clarification → Impact analysis → Backup → Apply → Verify
    ↓ Output: Updated artifacts + change summary

10. TodoWrite 模式

核心概念：动态附加和折叠任务，实时查看工作流执行情况。

关键原则

1. 任务附加（执行阶段时）：

   • 将子任务附加到协调器的 TodoWrite
   • 阶段 2、3：附加多个子任务
   • 阶段 1、4：单个任务（原子任务）
   • 将第一个附加任务标记为 in_progress，其余标记为 pending
   • 协调器按顺序执行这些已附加的任务

2. 任务折叠（子任务完成后）：

   • 适用于阶段 2、3：从 TodoWrite 中移除详细的子任务
   • 折叠为高层级阶段摘要
   • 阶段 1、4：无需折叠（只有单个任务，标记为已完成即可）
   • 保持协调器层级视图简洁

3. 持续执行：完成后，自动继续下一个待处理阶段

生命周期：初始待处理 → 执行阶段（附加任务）→ 执行子任务 → 阶段完成（阶段 2、3 的任务已折叠；阶段 1、4 的任务标记为已完成）→ 下一个阶段 → 重复

阶段 2（已附加任务）：

[
  {"content": "Phase 1: Session Discovery", "status": "completed"},
  {"content": "Phase 2: Context Gathering", "status": "in_progress"},
  {"content": "  → Analyze codebase structure", "status": "in_progress"},
  {"content": "  → Identify integration points", "status": "pending"},
  {"content": "  → Generate context package", "status": "pending"},
  {"content": "Phase 4: Task Generation", "status": "pending"}
]

阶段 2（已折叠）：

[
  {"content": "Phase 1: Session Discovery", "status": "completed"},
  {"content": "Phase 2: Context Gathering", "status": "completed"},
  {"content": "Phase 4: Task Generation", "status": "pending"}
]

阶段 3（已附加任务，有条件）：

[
  {"content": "Phase 1: Session Discovery", "status": "completed"},
  {"content": "Phase 2: Context Gathering", "status": "completed"},
  {"content": "Phase 3: Conflict Resolution", "status": "in_progress"},
  {"content": "  → Detect conflicts with CLI analysis", "status": "in_progress"},
  {"content": "  → Present conflicts to user", "status": "pending"},
  {"content": "  → Apply resolution strategies", "status": "pending"},
  {"content": "Phase 4: Task Generation", "status": "pending"}
]

注意：详细的 TodoWrite 更新示例请参见各阶段的说明。

11. 阶段后更新

每个阶段完成后，更新 planning-notes.md：

• 阶段 1 后：根据用户意图初始化（GOAL、KEY_CONSTRAINTS）
• 阶段 2 后：添加上下文调查结果（CRITICAL_FILES、ARCHITECTURE、CONFLICT_RISK、CONSTRAINTS）
• 阶段 3 后：如果已执行，则添加冲突决策（RESOLVED、MODIFIED_ARTIFACTS、CONSTRAINTS）
• 记忆状态检查：在耗时较大的阶段（阶段 2–3）后评估上下文窗口使用情况；如果使用量较高（>120K tokens），触发 compact

详细的更新代码请参见阶段文件。

12. 错误处理

• 解析失败：如果输出解析失败，重试一次命令，然后报告错误
• 验证失败：如果验证失败，报告缺少的文件或数据
• 命令失败：保持阶段为 in_progress，向用户报告错误，不要继续下一个阶段
• 未找到会话（验证／重新规划）：报告错误并列出可用会话
• 未找到任务（重新规划）：报告错误并列出可用任务

13. 协调器检查清单

计划模式

• 预处理阶段：将用户输入转换为结构化格式（目标/范围/上下文）
• 在执行任何命令之前初始化 TodoWrite（第 3 阶段在第 2 阶段之后动态添加）
• 立即使用结构化描述执行第 1 阶段
• 从第 1 阶段输出中解析会话 ID，并将其存储在内存中
• 会话完整性：如果复用现有会话，验证第 1.2.5 步中的 sessionIntegrity；对于不完整的头脑风暴产物，记录警告
• 将会话 ID 和结构化描述传递给第 2 阶段命令
• 从第 2 阶段输出中解析上下文路径，并将其存储在内存中
• 从 context-package.json 中提取 conflictRisk：据此确定是否执行第 3 阶段
• 如果 conflictRisk ≥ medium：启动第 3 阶段冲突解决流程，并传入 sessionId 和 contextPath
• 等待第 3 阶段执行完毕（如果已执行），并验证是否已创建 conflict-resolution.json
• 如果 conflictRisk 为 none/low：跳过第 3 阶段，直接进入第 4 阶段
• 将会话 ID 传递给第 4 阶段命令
• 验证第 4 阶段的所有输出
• 计划确认关卡：让用户选择（验证 → 第 5 阶段 / 执行 / 查看状态）
• 如果用户选择验证：读取 phases/05-plan-verify.md，并在进程内执行第 5 阶段
• 如果用户选择执行：Skill(skill="workflow-execute")
• 如果用户选择查看状态：在当前界面显示会话状态
• 自动模式（workflowPreferences.autoYes）：自动选择“验证计划质量”，如果结果为 PROCEED，则自动继续执行
• 每个阶段结束后更新 TodoWrite
• 每个阶段结束后，根据 TodoList 状态自动继续下一阶段

验证模式

• 检测/验证会话（从活动会话中自动检测）
• 使用单个验证任务初始化 TodoWrite
• 执行第 5 阶段验证 Agent
• 展示质量关卡结果和下一步选项

重新规划模式

• 从 $ARGUMENTS 中解析任务 ID（如果存在，格式为 IMPL-N）
• 检测操作模式（任务或会话）
• 使用重新规划专用任务初始化 TodoWrite
• 执行第 6 阶段及其所有子阶段（澄清 → 影响分析 → 备份 → 应用 → 验证）

14. 结构模板参考

最简结构：

GOAL: [What to achieve]
SCOPE: [What's included]
CONTEXT: [Relevant info]

详细结构（可选，适用于上下文更充分时）：

GOAL: [Primary objective]
SCOPE: [Included features/components]
CONTEXT: [Existing system, constraints, dependencies]
REQUIREMENTS: [Specific technical requirements]
CONSTRAINTS: [Limitations or boundaries]

15. 相关技能

前置技能：

• brainstorm 技能 - 可选：在规划前生成基于角色的分析
• brainstorm 技能 - 可选：通过澄清细化头脑风暴分析

由 Plan Mode 调用（4 个阶段）：

• /workflow:session:start - 阶段 1：创建或发现工作流会话
• phases/02-context-gathering.md - 阶段 2：收集项目上下文并分析代码库（内联）
• phases/03-conflict-resolution.md - 阶段 3：检测并解决冲突（内联，有条件执行）
• memory-capture 技能 - 阶段 3：优化记忆（上下文即将达到限制时）
• phases/04-task-generation.md - 阶段 4：生成任务 JSON 文件（内联）

后续技能：

• workflow-plan 技能（plan-verify 阶段）- 验证计划质量（也可通过 verify mode 调用）
• 内联显示会话状态 - 查看任务拆分和当前进度
• Skill(skill="workflow-execute") - 开始执行生成的任务（技能：workflow-execute）
• workflow-plan 技能（replan 阶段）- 修改计划（也可通过 replan mode 调用）

<auto_mode> 当 workflowPreferences.autoYes 为 true 时（由 -y 或 --yes 标志触发，或用户选择“自动”模式）：

• 跳过所有确认提示，使用默认值
• 在计划确认关卡自动选择“验证计划质量”
• 如果验证结果为 PROCEED，则自动继续执行
• 在 replan mode 中跳过交互式澄清（使用安全的默认值） </auto_mode>

<success_criteria>

• 根据技能触发正确检测模式（plan / verify / replan）
• 初始化 TodoWrite，并在每个阶段后使用附件/折叠模式更新
• 按顺序执行所有阶段，并在阶段间正确传递数据
• 仅在阶段即将执行时，通过 Read() 渐进式加载阶段文档
• 每个阶段后更新 planning-notes.md，记录累积的上下文
• 根据 conflictRisk 评估结果有条件地执行阶段 3
• 阶段 4 后显示包含正确选项的计划确认关卡
• 生成所有输出产物：IMPL_PLAN.md、任务 JSON、TODO_LIST.md
• 紧凑恢复机制有效：保留进行中的阶段，并可压缩已完成阶段
• 错误处理涵盖解析失败、验证失败以及会话/任务缺失 </success_criteria>