---

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（本模块完成）