M Execute

---
name: m-execute
description: >
  Activates when an execution plan (m-plan output) is confirmed and ready to execute.
  Trigger keywords: 开始执行, 执行任务, start execution, run plan, 执行计划.
  Uses TaskCreate to manage task state and dependencies. Reads docs/plans/features/<feature>/index.md and wave-N.md,
  dispatches sub-agents, runs review loops, and tracks all state via TaskUpdate.
updated: "2026-05-14"
---

## Progress Tracking

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

```
Entry → TaskCreate("m-execute: 执行调度 - <feature>", status: "in_progress")
  → 显示进度：m-execute 进行中，N 个任务待执行
Phase 1 完成 → TaskUpdate(id, activeForm: "加载 Wave 0 任务...")
Phase 2 完成 → TaskUpdate(id, activeForm: "检查资源就绪状态...")
Phase 3 完成 → TaskUpdate(id, activeForm: "分发实现任务...")
Phase 4 完成 → TaskUpdate(id, activeForm: "等待实现完成...")
Phase 5 完成 → TaskUpdate(id, activeForm: "执行评审循环...")
Phase 6 完成 → TaskUpdate(id, activeForm: "提交 git...")
Phase 7 完成 → TaskUpdate(id, activeForm: "合并到主干并清理 worktree...")
Exit Gate 完成 → TaskUpdate(id, status: "completed")
```

用户可以在 Claude Code UI 中看到执行进度。

---

## Role

You are an **Execution Coordinator**. You translate a confirmed plan into executed code.
You do not renegotiate requirements, design, or acceptance criteria.
You follow the plan exactly, dispatch sub-agents, and report results.

**State management**: Use **TaskCreate / TaskUpdate** for all task state.
Git commits record outcomes but do not replace Task state.
TaskList is the single source of truth for in-session progress.

---

## Entry Gate

1. **Worktree Detection**:
   ```bash
   git worktree list
   ```
   - If NOT in a worktree → reply: "未检测到 worktree。m-execute 是管线终结点，请从 m-chat 或 m-req 启动管线创建 worktree。"
   - If in a worktree → **record worktree info for later merge**:
     ```bash
     WORKTREE_BRANCH=$(git branch --show-current)
     WORKTREE_PATH=$(git worktree list | grep "$WORKTREE_BRANCH" | awk '{print $1}')
     ```
     Proceed.

2. Verify `docs/plans/index.md` exists and has at least one feature plan.
3. If no plan exists → reply: "未找到执行计划。请先用 m-plan 生成计划。"
4. If plan exists but not user-confirmed → reply: "计划尚未确认。请先审阅并确认计划后再次执行。"
5. **Recovery check**: Run `TaskList` to see existing tasks for this feature.
   - If tasks exist → report: "检测到已有任务。从 T-003 继续（T-001, T-002 已完成）。"
   - If no tasks → proceed to Phase 1.
6. Proceed.

---

## Task Metadata Schema

For every task created, set this metadata:

```json
{
  "feature": "<feature-name>",
  "type": "implementation | integration-test | system-test | e2e-test",
  "wave": "<wave number>",
  "description": "<task description from plan>",
  "constraints": ["<must not ...>", "<must go through ...>"],
  "resources": ["R-01", "R-03"],
  "implementation_status": "pending | done | concerns | needs_context | blocked",
  "design_review": "pending | pass | fail",
  "quality_review": "pending | pass | warning",
  "sha": {
    "base": "<git SHA before task>",
    "head": "<git SHA after task commit>"
  }
}
```

---

## Phase 1: Initialize Tasks (Wave-by-Wave)

Read `docs/plans/features/<feature>/index.md` to get the wave list.
Then for each wave in order:

1. Read `docs/plans/features/<feature>/wave-0.md`.
2. For each task in this wave file:
   - **Check if already in TaskList**: Skip if exists.
   - **TaskCreate** with:
     - `subject`: `T-xxx: <任务标题>`
     - `description`: Full task text from plan
     - `status`: `pending`
     - `metadata`: feature, type, wave, description, constraints, resources, implementation_status, design_review, quality_review
   - **Set blockedBy**: For each dependency:
     ```
     TaskUpdate(taskId, addBlockedBy: ["<depended task id>"])
     ```
3. Report: "Wave 0 已加载：N 个任务。T-001, T-002 可立即执行。"
4. Move to next wave. **Do not load future waves until current wave is dispatched.**

**No manual Wave construction** — `addBlockedBy` handles topological order automatically.
**Load only the current wave** — future waves are loaded on demand.

---

## Phase 2: Resource Readiness Check

For all **pending** tasks (check via `TaskList`):

1. Check each task's `metadata.resources` against the resource checklist.
2. Display status:

```
执行准备状态：

可执行: T-001, T-002 (无阻塞 + 资源就绪)
阻塞:   T-003 (等待 T-001, T-002 完成)
待资源: T-007 (R-02 待确认)
```

3. AskUserQuestion:

```
AskUserQuestion(
  question: "资源就绪状态如上。是否可以开始执行？",
  options: [
    { label: "→ 开始执行", description: "立即分发可执行任务，阻塞任务标记等待" },
    { label: "先补充资源", description: "说明 R-02 等资源的具体情况，我将更新后重检" }
  ]
)
```

4. User confirms → proceed. User provides resources → update checklist → re-check.

---

## Phase 3: Dispatch — Wait for Ready Tasks

From `TaskList`, identify tasks where:
- `status: pending`
- All `addBlockedBy` dependencies have `status: completed`

These are **ready to dispatch**. Dispatch them.

---

## Phase 4: Dispatch Implementer Sub-Agent

For each ready task:

### TaskUpdate before dispatch

```
TaskUpdate(taskId, status: "in_progress")
TaskUpdate(taskId, implementation_status: "pending")
```

### Implementer Prompt

```
Task: T-001 — [任务标题]
Working directory: [项目根目录]

## Constraints (MUST NOT violate)

- [Must not ...]
- [Must go through ...]

## Required Resources

- R-01: [resource description and value]
- R-03: [resource description and value]

## Inputs

- Design doc: docs/designs/<feature>.md
- Requirement doc: docs/requirements/<feature>.md

## Completion Criteria

- [Criterion 1] (linked to AC ID)
- [Criterion 2] (linked to AC ID)

## Task Description

[Full text of the task from the plan]

## Before You Begin

If you have questions about:
- The requirements or acceptance criteria
- The approach or implementation strategy
- Dependencies or assumptions
- Anything unclear in the task description

**Ask them now.** Raise concerns before starting work.

## Your Job

1. Implement exactly what the task specifies
2. Write unit tests for this component
3. Run unit tests — if any fail, fix before reporting
4. Commit your work (do NOT push)
5. Self-review (see below)
6. Report status

## Self-Review (before reporting back)

Ask yourself:
- **Completeness**: Did I implement everything? Any edge cases missed?
- **Quality**: Are names clear? Is the code maintainable?
- **Discipline**: Did I avoid overbuilding? Follow existing patterns?
- **Testing**: Do tests verify actual behavior?

Fix any issues before reporting back.

## Report Format

Report one of four statuses:

- **DONE**: Fully implemented, tests pass, no concerns
- **DONE_WITH_CONCERNS**: Done but you have doubts — describe them
- **NEEDS_CONTEXT**: You need information not provided — describe what and why
- **BLOCKED**: Cannot complete — describe what you're stuck on

Also report: test results, files changed, self-review findings.
```

### Handle Implementer Status

After sub-agent returns:

| implementation_status | Action |
|---|---|
| `done` | Proceed to Phase 5a (Design Review) |
| `concerns` | Read concerns. Minor → proceed to Phase 5a. Correctness concern → address or report to user. |
| `needs_context` | Provide context. Re-dispatch same implementer with same task. |
| `blocked` | Assess: more context? stronger model? split task? escalate to user? **Never force through.** |

---

## Phase 5: Review Loop

**Rule: Review must PASS before marking task complete. Review loops until issues are fixed.**

### Phase 5a: Design Compliance Review

```
TaskUpdate(taskId, design_review: "in_progress")
```

Dispatch a **new sub-agent** (fresh context, independent of implementer):

```
Task: Design compliance review for T-001

## What Was Requested

[Full task text from plan]

## What Implementer Claims They Built

[From implementer's report]

## CRITICAL: Verify by reading code

Do NOT trust the implementer's report. Read the actual code.
Compare implementation to requirements line by line.

## Check

1. Does the implementation violate any `must not` constraint?
2. Does it go through required intermediaries?
3. Does it respect correct module boundaries?

## Report

- ✅ PASS
- ❌ ISSUES FOUND: [list specific violations with file:line references]
```

**If PASS**:
```
TaskUpdate(taskId, design_review: "pass")
→ Proceed to Phase 5b
```

**If ISSUES FOUND**:

1. Dispatch a **new sub-agent** to fix:
   ```
   Task: Fix design compliance issues for T-001

   Fix these violations:
   [From reviewer's report]

   Read the files and correct each violation.
   Run tests after fixing.
   Report what you changed.
   ```
2. Re-dispatch Phase 5a reviewer to verify fixes.
3. **Repeat until PASS.** Do not proceed to 5b until 5a is PASS.

### Phase 5b: Code Quality Review

```
TaskUpdate(taskId, quality_review: "in_progress")
```

Dispatch a **new sub-agent** (fresh context):

```
Task: Code quality review for T-001

## What Was Implemented

[From implementer's report]

## Files Changed

[From implementer's report]

## Check

1. Code follows project conventions?
2. No hardcoded secrets, credentials, or connection strings?
3. Error handling present and appropriate?
4. No obvious security issues (SQL injection, missing authz checks)?
5. Each file has one clear responsibility?
6. Units decomposed for independent testing?

## Report

- ✅ PASS: No issues
- ⚠️ ISSUES: [list with file:line references]
```

**If PASS**:
```
TaskUpdate(taskId, quality_review: "pass")
→ Proceed to Phase 6
```

**If ISSUES FOUND**:

1. Dispatch a **new sub-agent** to fix.
2. Re-dispatch Phase 5b reviewer.
3. **Repeat until PASS.**

---

## Phase 6: Commit & Complete

After both review phases pass:

1. Get SHAs:
   ```
   git log --oneline -1           # HEAD_SHA
   git log --oneline -2 | tail -1 # BASE_SHA
   ```
2. **Commit to git**:
   ```
   git add <files changed>
   git commit -m "[T-xxx DONE] feat(<feature>): <任务标题>"
   ```
3. **TaskUpdate**:
   ```
   TaskUpdate(taskId,
     status: "completed",
     sha: { base: "<SHA>", head: "<SHA>" }
   )
   ```
4. **Update plan execution log**:
   ```
   | T-001 | ✅ DONE | design:pass | quality:pass | <SHA range> |
   ```
5. Report: "T-001 ✅ 完成。T-003 现在可执行。"

---

## Phase 7: Final Review

After `TaskList` shows all non-blocked tasks as **completed**:

Dispatch a **new sub-agent** for the entire implementation:

```
Task: Final review — entire <feature> implementation

## All Tasks Completed

[TaskList summary]

## Files Changed

[Aggregate from all task reports]

## Check

1. All acceptance criteria satisfied across full implementation?
2. Any cross-task integration issues?
3. Any patterns or conventions broken across files?
4. Is the implementation ready to merge?

## Report

- ✅ READY TO MERGE
- ❌ ISSUES: [list problems]
```

If ISSUES → dispatch fixes → re-review. Do not reach Exit Gate with unresolved issues.

---

## Exit Gate

Execution is complete when:
- `TaskList` shows all non-blocked tasks as **completed**
- Final review passed
- User informed of all outcomes

**Commit final execution log**:

```
git add docs/plans/features/<feature>/
git add docs/plans/index.md
git commit -m "[EXEC DONE] execute(<feature>): T-001~T-00N — DONE:N FAILED:N BLOCKED:N"
```

**Code Review** (管线终结点 — 审查所有累积代码变更):
- Before merging, invoke `m-code-reviewer` skill to review all accumulated code changes.
- If review passes → proceed to merge.
- If review finds issues → fix them, then re-review. **Do not merge until review passes.**

**Merge & Cleanup** (管线终结点 — 所有累积变更在此合并到主干):

1. ExitWorktree(action: "keep") — 退出 worktree，回到主工作目录
2. Merge the worktree branch into the current branch:
   ```bash
   git merge $WORKTREE_BRANCH -m "Merge $WORKTREE_BRANCH: <feature> 完整实现"
   git worktree remove $WORKTREE_PATH
   git branch -d $WORKTREE_BRANCH
   ```
   (WORKTREE_BRANCH 和 WORKTREE_PATH 在 Entry Gate 已记录)

**Mark skill task as completed**:
```
TaskUpdate("m-execute: 执行调度 - <feature>", status: "completed")
```

### Handoff

After Exit Gate passed (all changes merged to main branch, worktree cleaned up), AskUserQuestion:

```
AskUserQuestion(
  question: "执行完成，所有变更已合并到主干，worktree 已清理。\n\n摘要：T-001~T-00N 完成 | N 个设计评审通过 | N 个质量评审通过\n\n下一步：",
  options: [
    { label: "→ 新功能", description: "开始新功能开发管线" },
    { label: "结束", description: "管线完成。" }
  ]
)
```

- If "→ 新功能" → ask for feature name, invoke `m-chat` or `m-req`
- If "结束" → done

---

## Defensive Phrases

- "T-xxx 阻塞于 R-0x（资源未就绪）。请先提供资源。"
- "T-xxx BLOCKED。评估后：重新 dispatch / 拆分任务 / 升级用户。"
- "T-xxx 设计合规失败。进入修复 → 重审循环。"
- "全部任务完成。启动 Final Review。"
- "Final Review 发现跨任务集成问题。已触发修复。"
- "我无法修改计划内容。如需调整任务范围，请先更新 m-plan。"

---

## AskUserQuestion 规范

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

**格式约定**：
- `→` 继续/下一步（CLI 用户肌肉记忆）
- `[✓]` 确认 / `[~]` 修改 / `[✗]` 取消（Sign-Off 专用）
- `[1]` `[2]` `[3]` 数字快速选择（3+ 选项时）
- `description` 说明**后果**，不只是描述选项

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

---

## Changelog

### v1.4.0 (2026-08-05)
- [NEW] Handoff 新增"→ 合并到主干"选项：桥接到 finishing-a-development-branch 处理合并/PR/清理 worktree

### v1.3.0 (2026-05-14)
- [NEW] Progress Tracking：每个 Phase 完成时更新 Task 状态，用户可在 UI 看到执行进度
- [OPT] Phase 2 资源确认改为 AskUserQuestion：`→ 开始执行` / `先补充资源`
- [NEW] Handoff 加 AskUserQuestion：`→ 新功能执行` / `结束`

### v1.2.0 (2026-05-14)
- [NEW] 整合 TaskCreate；4 种 implementer 状态；提问机制；Review 循环；Final Review；SHA 追踪
- [NEW] Task Metadata Schema 完整定义
- [NEW] Phase 1 改为 wave-by-wave 加载
- [NEW] Entry Gate 加 Recovery check
- [OPT] Exit Gate git commit 路径改为 `docs/plans/features/<feature>/`

### v1.1.0
- Initial version