---
name: module-start
description: 模块循环入口。定位当前模块与未完成 REQ，派发到 feature-brainstorm（每个 REQ 一次）或 test-gate（本模块全部完成）。幂等可重入。
user-invocable: false
allowed-tools: Read Write Skill Glob Grep Bash(git branch *) Bash(git checkout *) Bash(git rev-parse *) Bash(git pull *) Bash(git status *) Bash(git symbolic-ref *) Bash(curl *) Bash(jq *)
---

**所有输出必须使用中文。**

# module-start

## 执行步骤

### 步骤 1：定位当前模块与本模块 REQ 列表

按 `docs/02 § 二 开发顺序清单` 的 REQ 顺序扫描，找到第一个所属模块尚未 merged 的模块作为 `current_module`，并抽取本模块 REQ 序列。

模块状态判定（`MR:` 字段 × GitLab API state 三种组合的语义和应对动作）参见 `CLAUDE.md § ✅ 模块完成判定规则 § 模块状态语义`。

找到 `current_module` 后，从 docs/02 § 二 的 REQ 列表里取出所有 `module_id == current_module` 的项，按原序得 `req_list[]`（A5 约束保证同模块 REQ 连续）。模块名、需求卡目录等其它字段由后续步骤按需从 `docs/08 § 二` 或 `docs/01-需求清单/` 取，不在本步骤预读。

约束：

- GitLab 凭据从 `.env.local` 读取（`GITLAB_API_URL` / `GITLAB_TOKEN` / `GITLAB_PROJECT_ID`）
- API 异常（HTTP 非 2xx / 找不到 MR / state 非合法值）一律硬停，**禁止静默假设未 merged**，向用户打印诊断信息，引导核查上述凭据与 docs/08 的 iid
- 任何文件读取或解析失败 → 打印错误并停止

### 步骤 2：所有模块都完成时结束

如果步骤 1 没找到任何未 merged 的模块（即整个项目已做完），打印"所有模块已完成"提示用户，结束流程，不再进入后续步骤。

### 步骤 3：确保处于模块分支

确保工作树位于 `target_branch = module-<module_id>`（例 `module-module_sys`）。

- 已在该分支 → 继续步骤 4
- 该分支已存在但当前不在 → checkout 过去
- 该分支不存在 → 先把工作树切到远程默认分支（main 或 master）并 fast-forward 同步，作为新分支的干净 base，再 `git checkout -b` 创建模块分支

任何错误（定位不到默认分支 / 切换前工作树脏 / 不能 fast-forward / checkout 失败）一律停下并打印诊断信息，不自动 stash、不强制覆盖。

### 步骤 4：计算已完成 REQ 集合 `done_reqs[]`

对 `req_list[]` 中每个 REQ，检查 `docs/superpowers/reviews/` 下是否存在该 REQ 的 review 文件、且其 `verdict` 字段为 `approve`。两条件都满足 → 收入 `done_reqs[]`，步骤 6 推进时跳过这些 REQ。

每次进入本 skill 都重新计算（不缓存），保证中断/重跑后能从最新进度继续。

### 步骤 5：渲染并打印模块横幅

按 `${CLAUDE_SKILL_DIR}/templates/module-start-banner-template.md` 渲染输出。

### 步骤 6：派发

- 还有未完成 REQ → 调用 `Skill(feature-brainstorm)` 启动该 REQ 的功能循环
- 本模块 REQ 全部完成 → 调用 `Skill(test-gate)` 进入模块测试闸门

## 参考

- `docs/02-开发计划.md § 二 开发顺序清单`（分发权威）
- `docs/08-模块任务管理.md § 二`（模块元数据，含 `MR:` 字段；完成判定以 MR state 为准）
- `docs/superpowers/reviews/*.md`（REQ 级进度事实——verdict=approve 即完成）
- `${CLAUDE_SKILL_DIR}/templates/module-start-banner-template.md`
- 下游：`feature-brainstorm`（每个 REQ）/ `test-gate`（本模块完成）