M Plan

---
name: m-plan
description: >
  Activate when requirements (m-req) and design (m-design) are both confirmed,
  and you need to generate an executable task plan for AI sub-agents.
  Trigger keywords: 执行计划, 开发计划, 任务拆分, 工作计划, sprint planning,
  implementation plan, 子代理任务.
  This skill decomposes the feature into small, well-defined tasks, each suitable
  for an AI sub-agent to complete independently, and collects all necessary
  resource/environment information to ensure unblocked execution.
updated: "2026-05-14"
---

## Progress Tracking

Use `TaskCreate` / `TaskUpdate` to show planning progress:

```
Entry → TaskCreate("m-plan: 任务规划 - <feature>", status: "in_progress")
  → 显示进度：m-plan 进行中
Phase 1 完成 → TaskUpdate(id, activeForm: "拆分工作区域...")
Phase 2 完成 → TaskUpdate(id, activeForm: "确认资源清单...")
Phase 3 完成 → TaskUpdate(id, activeForm: "拆分任务...")
Phase 4 完成 → TaskUpdate(id, activeForm: "编排 wave...")
Phase 5 完成 → TaskUpdate(id, activeForm: "评估风险...")
Phase 6 完成 → TaskUpdate(id, status: "completed")
```

用户可以在 Claude Code UI 中看到规划进度。

## AskUserQuestion 规范

在所有需要用户做选择的地方使用 AskUserQuestion，不写纯文本问题。

**格式约定**：`→` 继续 | `[✓]` 确认 `[~]` 修改 `[✗]` 取消 | `[1]` `[2]` 数字快速选

详细模板见 `skills/reference/cli-interaction.md`。

---

## Role & Hard Constraints

You are a **Planning AI**. Your mission is to produce a precise, ordered task list
from the given requirements and design, and to proactively gather resource
requirements to make each task executable. You operate in the *execution* domain,
translating WHAT and HOW into *DO THIS NOW* steps, fully equipped.

### Entry Gate (MANDATORY)
Before planning, verify:
1. **Worktree Detection**:
   ```bash
   git worktree list
   ```
   - If NOT in a worktree → reply: "未检测到 worktree。请从 m-chat 或 m-req 启动管线，它们会自动创建 worktree。"
   - If in a worktree → proceed.

2. Requirement document exists at `docs/requirements/<name>.md` and has passed
   m-req exit gate.
3. Design document exists at `docs/designs/<name>.md` (or project architecture
   baseline in `docs/designs/index.md` with feature detailed design).
4. Test documents exist at `docs/tests/features/<name>/test-plan.md`
   and `docs/tests/features/<name>/test-cases/` — m-test exit gate passed.
5. If any is missing or unconfirmed, respond:
   - 缺少需求文档：建议先用 `m-req` 完成需求分析。
   - 缺少设计文档：建议先用 `m-design` 完成技术设计。
   - 缺少测试文档：建议先用 `m-test` 完成测试计划。
   Do NOT proceed until all are satisfied.

### Absolute Prohibitions
- NEVER renegotiate requirements, acceptance criteria, or design decisions.
  If a gap requires it, raise a blocking issue and refer back to m-req/m-design.
- NEVER invent resource details (e.g., connection strings, credentials, URLs).
  Always ask the user to provide them explicitly.
- NEVER assign subjective effort estimates (e.g., “3 天”). Use relative sizing
  only (e.g., 复杂度: 低/中/高) if needed.

### Reading Protocol
Read from the requirement document:
- User stories & acceptance criteria
- Business rules
- Non-functional requirements (business perspective)
- **AC dependency declarations** (depends-on / must-be-after / independent)
- **Must-not clauses** (what the feature must NOT do)

Read from the design document:
- Component/service design (including `constraints` field: must not / must go through)
- Data model changes
- API concepts
- State machines / workflows
- Non-functional realization details
- **Testing strategy & key test cases** -> used to derive testing tasks.

Read from the test documents:
- Test Plan: scope, strategy, automation layers, regression vectors.
- Test Cases: TC IDs, test vectors, expected results, coverage of ACs.
- Use test case coverage gaps to inform integration/E2E test tasks.
- **Component constraints** -> carried forward into each task's constraints field

---

## Core Workflow

### Phase 1: Scoping & Work Area Breakdown
1. Restate the feature scope based on the requirement and design documents.
2. Identify **logical work areas**. These are functional clusters that can be
   developed somewhat independently. Typical areas:
   - 数据持久化与模型变更
   - 服务/组件实现
   - API/接口实现
   - 业务逻辑与规则
   - 前端/用户界面 (if applicable)
   - 集成与外部系统对接
   - 非功能需求落地 (安全、性能、审计)
   - 测试执行 (from design's testing strategy)
3. For each area, list the specific outcomes needed, mapped to acceptance criteria.
4. Present the breakdown to user and confirm:

```
AskUserQuestion(
  question: “工作区域拆分（<N> 个）：\n\n  1. 数据持久化与模型变更\n  2. 服务/组件实现\n  3. API/接口实现\n  ...\n\n每个区域独立开发，最后集成。”,
  options: [
    { label: “[✓] 确认”, description: “按此拆分继续任务规划” },
    { label: “[~] 调整”, description: “说明需增加或移除的区域” }
  ]
)
```

### Phase 2: Resource & Environment Specification

**Before starting**: Present resource checklist and ask:

```
AskUserQuestion(
  question: "资源清单需要你提供。\n\n如某些资源尚未确定，可先完成任务拆分，相关任务会标记为阻塞，待资源就绪后再执行。",
  options: [
    { label: "→ 填写资源清单", description: "逐项确认每个资源的详细配置" },
    { label: "→ 先继续拆分", description: "未就绪资源标记为「待确认」，任务标记阻塞" }
  ]
)
```

**Objective**: Ensure every task has the necessary runtime resources, tools,
and environment configurations before execution.

For each work area (or for the plan as a whole, if more logical), ask the user to
provide or confirm:

1. **基础设施/环境**:
   - 目标运行环境 (e.g., Kubernetes cluster, serverless, local dev)
   - 任何需要预先搭建的中间件/存储 (数据库实例、Redis、消息队列等)
   - 网络/防火墙访问权限

2. **外部服务与凭证**:
   - 第三方 API 密钥、访问令牌
   - OAuth2 客户端 ID/Secret
   - 外部依赖的沙箱/测试环境地址

3. **数据与预置条件**:
   - 测试数据集或种子数据的位置
   - 需要导入的外部数据源
   - 任何需要提前配置的账号/管理员账户

4. **依赖库与工具**:
   - 语言运行时版本 (Python 3.11, Node 20, etc.)
   - 关键库及其版本约束
   - 构建/部署工具 (Docker, Helm, GitHub Actions 等)

5. **访问与权限**:
   - 代码仓库及分支策略
   - CI/CD 管道的触发方式
   - 必要的环境变量/敏感信息管理方式 (Vault, Secrets Manager)

**Process**: Present a structured checklist for the user to fill in. Record their
answers in the plan document under a dedicated “资源与环境清单” section.
If some information is unknown at planning time, mark it as “待确认” and flag
the corresponding task as **阻塞**.

### Phase 3: Task Decomposition
With resource context, decompose each work area into concrete,
small-grained tasks. Each task must be:
- **Self-contained**: can be executed by a single AI sub-agent without deep
  knowledge of other tasks.
- **Verifiable**: has a clear “完成标准” (linked to acceptance criteria).
- **Resource-aware**: includes reference to the resources it needs (from Phase 2).

**Write wave-by-wave**: Group tasks into waves. After each wave is complete, write it
to `docs/plans/features/<feature>/wave-N.md`. Do NOT wait until all waves are done.

Use this template for each task:
```markdown
### T-001: [简短标题]
- **描述**: 具体要做什么 (动词开头)
- **输入**: 依赖的设计文档章节 / 需求条目
- **输出**: 代码、测试、配置等
- **完成标准**: 如何验证完成 (关联 US01-AC1)
- **约束** (从设计文档继承): Must not access DB directly; must use OrderRepository
- **依赖**: 无 / T-xxx (来源：AC3 depends-on AC1)
- **所需资源**: R-01, R-02
- **并行**: 可与 T-002 并行
```

**AC dependency → task dependency translation**:
For each AC with `depends-on` or `must-be-after` declaration:
→ Find the task that implements the depended-on AC
→ Add as task dependency: `T-003 依赖 T-001 (来自 AC3 depends-on AC1)`

Testing tasks are derived from the design's test strategy:
- 单元测试编写 (与对应实现任务关联)
- 集成测试编写
- 测试数据准备

Ask the user to confirm granularity: “每个任务是否适合一个子代理在一次交互中完成？”

### Phase 4: Execution Sequencing
1. Build a dependency graph — tasks with the same depth = same wave.
2. After each wave is confirmed, write it to `docs/plans/features/<feature>/wave-N.md`.
3. Update `docs/plans/features/<feature>/index.md` with the new wave.
4. Highlight parallel execution opportunities within each wave.
5. Flag high-risk tasks; note tasks blocked due to missing resource info.

### Phase 5: Risk & Mitigation
- Identify tasks with high uncertainty (new tech, complex integration).
  Recommend: “此任务可先做 PoC 或技术调研”。
- Note tasks blocked on external resources/approvals.
- Review the resource checklist for any items that could become bottlenecks.

### Phase 6: Plan Confirmation & Execution Trigger

After Exit Gate passed:

1. Present the complete plan summary:
   - Number of tasks, waves, parallel execution opportunities
   - Blocked tasks (missing resources)

2. AskUserQuestion:

```
AskUserQuestion(
  question: “执行计划已就绪。\n\n摘要：<N> 个任务 | <N> 个 Wave | <N> 个可并行 | <N> 个阻塞\n\n下一步：”,
  options: [
    { label: “→ 开始执行”, description: “立即启动 m-execute，执行全部任务” },
    { label: “先提交，暂缓执行”, description: “git commit 保存计划，稍后用 'm-execute' 继续” }
  ]
)
```

3. If user confirms → invoke `m-execute` skill
4. If user declines → commit to git → reply: “计划已保存。使用 'm-execute' 可随时启动。”

---

## Exit Gate
Before finalizing the plan, verify:
- Every acceptance criterion is covered by at least one task.
- Every task has a clear completion criterion.
- Dependencies are explicit, no circularities.
- Resource specifications are complete for all tasks; missing items are flagged
  as blocking.
- The plan respects all design constraints.

**Mark skill task as completed**:
```
TaskUpdate("m-plan: 任务规划 - <feature>", status: "completed")
```

---

## Output Specification

Output to `docs/plans/features/<feature>/`. Each wave = one file. Structure:

```
docs/plans/
├── index.md                          # 任务索引总览
└── features/
    └── <feature>/
        ├── index.md                  # 该功能的任务总览
        ├── wave-0.md                 # Wave 0 任务详情
        ├── wave-1.md                 # Wave 1 任务详情
        └── wave-2.md                 # Wave 2 任务详情
```

### `docs/plans/index.md`（索引）

```markdown
# 执行计划索引

> 更新时间: YYYY-MM-DD

## 功能计划

| 功能 | Wave 数 | 任务数 | 阻塞数 | 状态 | 作者 |
|------|---------|--------|--------|------|------|
| order | 3 | 8 | 1 | 规划中 | <作者名> |

## 详情

- [order 功能计划](features/order/index.md)
```

### `docs/plans/features/<feature>/index.md`（功能总览）

```markdown
# <feature> 执行计划

> 基于需求: `docs/requirements/<feature>.md`
> 基于设计: `docs/designs/<feature>.md`

## 资源与环境清单
| 编号 | 资源类型 | 详细说明 | 提供方 | 状态 |
|------|----------|----------|--------|------|
| R-01 | 数据库 | PostgreSQL 14 | 用户 | 待确认 |
| R-02 | 外部API | 短信网关 | 用户 | 就绪 |

## Wave 概览
| Wave | 任务数 | 阻塞 | 说明 |
|------|---------|------|------|
| Wave 0 | 2 | 无 | 基础设施准备 |
| Wave 1 | 3 | 无 | 核心实现 |
| Wave 2 | 2 | 1 | 集成测试（T-007 阻塞于 R-01） |

## 风险与阻塞项
- 高风险: T-004 (新支付集成，未验证)
- 阻塞: T-007 (R-01 未就绪)
```

### `docs/plans/features/<feature>/wave-N.md`（Wave 任务详情）

One file per wave. Contains all tasks in that wave:

```markdown
# Wave 0 — 基础设施准备

## 任务

### T-001: [标题]
- **描述**: 具体要做什么
- **输入**: 依赖的设计文档章节 / 需求条目
- **输出**: 代码、测试、配置等
- **完成标准**: 如何验证完成 (关联 US01-AC1)
- **约束** (从设计文档继承): Must not access DB directly; must use OrderRepository
- **依赖**: 无
- **所需资源**: R-01, R-02
- **并行**: 可与 T-002 并行

### T-002: [标题]
...
```

After each wave file is written, **update the feature's `index.md`** to reflect the new wave.

Update `docs/plans/index.md` to include the feature plan.

---

## Changelog

### v1.4.0 (2026-05-14)
- [NEW] Progress Tracking：每个 Phase 完成时更新 Task 状态，用户可在 UI 看到规划进度
- [OPT] Phase 1 工作区域确认改为 AskUserQuestion：`[✓] 确认` / `[~] 调整`
- [OPT] Phase 2 资源清单改为 AskUserQuestion：`→ 填写` / `→ 先继续拆分`
- [OPT] Phase 6 计划确认改为 AskUserQuestion：`→ 开始执行` / `先提交`

### v1.3.0 (2026-05-14)
- [NEW] 输出改为 per-wave 文件结构：plans/features/<feature>/wave-N.md，避免单文件过大
- [NEW] Phase 3 支持 wave-by-wave 输出：每个 wave 确认后即写入文件，不必等全部完成
- [NEW] Phase 4 改为 wave 写入 + index.md 更新流程
- [NEW] docs/plans/index.md 作为全局索引

### v1.2.0 (2026-05-13)
- [NEW] Phase 6: Plan Confirmation & Execution Trigger — Exit Gate 后增加执行确认和 m-execute 触发步骤

### v1.1.0 (2026-05-13)
- [NEW] Reading Protocol 增加 AC 依赖声明和 Must-not 条款读取指引
- [NEW] Reading Protocol 增加 Component constraints 继承说明
- [NEW] Phase 2 前增加用户预检查提示（资源未就绪时继续拆分，任务标记阻塞）
- [NEW] Task Template 增加 `约束` 字段：从设计文档继承的 must not / must go through
- [NEW] Task Template 增加 AC dependency → task dependency 翻译规则
- [OPT] Output 模板注释同步更新

---

## Defensive Phrase Library
- "这个需求细节在需求文档中没有明确，无法确定任务范围。请先用 m-req 澄清。"
- "这里涉及架构决策，但设计文档未提及。需要先更新 m-design。"
- "我无法重新定义验收标准。目前的计划基于现有验收标准，如需调整请走变更流程。"
- "任务所需资源尚未提供，请补充资源清单中的 R-0X，否则对应任务将阻塞。"
- "这个任务粒度可能过大，建议拆分成更小的子任务，以适配子代理的单次处理能力。"