module-init

name	module-init
description	创建 modules/ 体系下的基础模块 / 子模块 / 需求资产包。基于 templates/modules-template/ 复制骨架，填充占位符，初始化机器维护索引段，刷新上级 overview，并维护反向索引 code-paths-index.json 段。触发词：新建模块、新建子模块、初始化需求、module-init、新建 PRD 需求骨架。
when_to_use	创建第一个/新的基础模块或子模块时； 为子模块新建一个需求资产包（含默认子需求 `main/`）时； 迁移老需求到 modules/ 体系前作为单点工具使用； 用户主动调用 `/core:module-init` 时。
user-invocable	true
allowed-tools	["Read","Write","Edit","Glob","Grep","Bash"]

Module Init Skill

前置依赖

调用本 skill 前需读 skill: document-norms §1（归属矩阵）/ §2（frontmatter 字段）/ §3（三段制 overview + HTML 注释边界）/ §4（索引层级与同步）。

定位

modules/ 体系下三类骨架的唯一创建入口：

• 基础模块（basic-module）= 领域级，10-20 个上限
• 子模块（sub-module）= 功能级，按需扩展
• 需求资产包（requirement）= <sub>/requirements/<req_slug>/ 含 meta.yaml + overview.md + 默认子需求 main/（可改名）

适用范围：已接入 Workframe 的项目（modules/ 体系默认启用）。

不适用：

• 修改/重命名已有模块 → 直接 Edit + 调 module-index-refresh
• 一次性大规模迁移 → 调 migrate-to-modules
• 仅刷新索引段 → 调 module-index-refresh
• 创建 ADR / 调研 / 草稿 → 直接 Write 到对应目录（不需要 module-init）

输入

模式	必需输入（向用户问一次的字段）	可选输入
创建基础模块	name	owner / domain_tags
创建子模块	parent_basic + name	owner / tech_stack / code_paths
创建需求	parent_basic + parent_sub + name	owner / sub_req_name（默认 main；用户可改名作为首个子需求目录）

name 命名约定（单字段承担路径段名与展示名，权威定义见插件根 reference/module-architecture.md §5.1）：

• 允许字符：英文 / 数字 / 短横线 / 下划线 / 中文。例：profile / 用户档案 / avatar-cropper / 编辑资料
• 3 条 OS 硬约束（避不开）：
  • 不能含路径分隔符 / \
  • 不能含 Windows 禁字符 < > : " | ? *
  • 不能含空格（含中间空格——stale 索引按空白切分，带空格的名字会被截断）
• 推荐英文短词（跨语言团队 + GitHub Pages 静态化 URL 友好），但中文也允许（subprocess / hooks 已统一 utf-8 处理）
• 内部存储：name 直接填到 yaml schema 的 name 字段（无 display_name / slug 二字段）。模板里 basic-module / sub-module 用 {{BASIC_NAME}} / {{SUB_NAME}} 占位符，需求资产包仍保留 slug + title（不合并；{{REQ_SLUG}} + {{REQ_TITLE}} 占位符不动；理由见 module-architecture §5.2）；子需求用 {{SUB_REQ_SLUG}} 占位符（取值约束同 {{REQ_SLUG}}，允许中文）
• 二段式 module path（用于跨文档引用 / issues module: / board.yaml module:）：两个 name 用 / 拼接，例 profile/edit 或 用户档案/编辑资料

对话流总则（避免反复问 / 误判 / 工程师腔）

1. 资产类型必须在第一步明确：调用入口（/core:module-init 后用户的自然语言意图，或参数携带）必须能解析出"创建基础模块 / 子模块 / 需求资产包"三选一。无法解析时只问这一个问题问清，不问其他字段直到资产类型定下来。一旦确定，不再二次确认。
2. 前提校验（仅在 Step 1 用于决定是否拒绝调用）：
   • .workframe-config.json 存在即视为已接入，可继续
   • 不存在 → 拒绝并提示"当前目录不是 Workframe 项目，先用 /workframe-launcher:setup 接入"
   • 不要看 CLAUDE.md 是否存在（接入已有项目时不保证生成 CLAUDE.md）
   • 不校验 project_type 取值——modules/ 体系对所有 Workframe 项目默认启用
3. modules/ 体系开启检测（决定 Step 1 走"启用 + 建首个"还是"在已有体系下建"分支）：
   • 已开启：projects/modules/overview.md 存在
   • 未开启：上述文件不存在
   • 不要用 projects/specs/ 是否存在判断"老需求多 → 建议 migrate"——项目骨架（project_scaffold.py）默认会建空 projects/specs/overview.md，这不是"有老需求"信号
   • 正确判定"specs/ 含真需求"：projects/specs/ 下 **/*.md 与 **/*.yaml 文件总数 ≥ 2（即除 overview.md 之外还有 ≥1 文件）才提示 migrate 选项
4. 命名只问一次：用 §输入 的 name 单字段询问（yaml 只有 name 一个名字字段）。直接用普通对话提问"这个模块叫什么名字？"，不要用 AskUserQuestion 多选组件硬编码候选名（如 user/demo/content/auth）误导用户——除非候选基于本项目实际上下文（如 .workframe-config.json project_name / 已有模块的语义类比）合理推荐，否则一律开放输入
5. 大白话：禁止在对话里出现 slug / display_name / 正则 ^[a-z]... 等术语（基础/子模块层无此二字段；需求层 req_slug 仅作为内部 frontmatter 引用契约存在，不必跟用户提）。规则失败时给具体反例（如"不能含 /，输入 foo/bar 不允许"），不要贴正则
6. 报告末尾不输出盲目警告：通过规则 2 的前提校验后，不要再在报告尾部提示"本项目可能不该启用 modules/"一类的话
7. 询问 name 的文案分层（让 PM 一眼看到"现在该回什么"，不被可选项淹没）：
   • 核心问题独占一行 + 视觉突出（粗体或 ❓ 起头）：例 **这个子模块叫什么名字？**
   • 命名约束折叠到 > 引用块的小字注释，不跟核心问题混段
   • 智能默认前置（如果适用）：例 父基础模块默认为 用户档案（当前唯一），让 PM 知道这一项不必管
   • 可选项明确标注"可跳过 / 留空用默认"，避免 PM 误以为必答
   • 基础模块标准文案模板：

     **这个基础模块叫什么名字？**
     
     > 英文 / 数字 / 短横线 / 下划线 / 中文都可（如 `profile` / `用户档案` / `avatar-cropper`）；不能含 `/` `\` `< > : " | ? *` 与空格（含中间）。
     
     可选（不答即用默认）：
     - owner（默认 `pm`）
     - domain_tags（默认空）
     

工作流

Step 1: 输入校验 + 路径解析

按 §对话流总则 第 2-3 条做项目类型 + modules/ 开启状态检测，然后分支：

• 未接入 Workframe（无 .workframe-config.json）：拒绝调用，提示先跑 /workframe-launcher:setup
• modules/ 体系未开启（按总则第 3 条）：进一步看 specs/
  • specs/ 没真需求（按总则第 3 条判定）：默认进入"启用 modules/ 并创建首个基础模块"流程，直接走资产类型 = basic-module，不再问"哪类资产"
  • specs/ 有真需求（≥2 文件）：提示用户"已有 X 个 specs/ 老需求，走 /core:migrate-to-modules 一次性迁移更高效；本次仍要建独立模块吗？"
• modules/ 体系已开启：按总则第 1 条问资产类型（basic-module / sub-module / requirement 三选一），不要默认走 basic-module
• 验证 name 命名（按 §输入 命名约定 3 条 OS 硬约束）
• 验证父级存在（创建子模块时父基础模块必须存在；创建需求时子模块必须存在）
• 检查目标路径不冲突（同 name 已存在时拒绝并提示已有路径）

Step 2: 落盘（basic / sub 模式 → 调脚本；requirement 模式 → 模型执行）

2a. 基础模块 / 子模块：调 module_init.py 确定性落盘

把采集到的值写成树 JSON（schema 见脚本 docstring；单建一个 basic 或 sub 也是同一结构），交给脚本一次完成：

# 插件根从 plugin-root.txt 取（SessionStart hook 每会话刷新），不依赖环境变量
python "$(cat .claude/workframe-state/plugin-root.txt)/scripts/module_init.py" --project "<项目根>" --params "<tree.json>"

脚本承包：骨架复制 + 占位符替换（断言零残留）+ positioning 写入定位段 + code_paths 写入 submodule.yaml + 反向索引初始化（内部调 check-stale-modules.py init-submodule，复用其文件锁与原子写）+ global basic-modules-index 与 basic submodules-index 两层索引段重建。幂等：已存在文件一律跳过，重跑索引无变化。

• 退出码 2 = 参数 / 命名校验失败，把 stderr 报错原样转述给用户（不要自行猜测修正）
• 退出码非 0 时不要手工补文件——修正输入后重跑脚本
• 脚本 stderr 的 ⚠ 警告（如 code_paths 与文件现值不一致）必须转述，不吞

2b. 需求资产包：模型按下列步骤执行（暂不脚本化）

1. 从 <插件根>/templates/modules-template/requirement/（插件根 = cat .claude/workframe-state/plugin-root.txt）用 Read + Write 逐文件复制 → <sub>/requirements/<req_slug>/（含 meta.yaml + overview.md + main/ 子目录及其下文件），保持 .gitkeep
2. 用户给定的 sub_req_name 不是默认值 main 时，把 <req_slug>/main/ 重命名为 <req_slug>/<sub_req_name>/
3. 逐文件替换 {{XXX}} 占位符（表见 templates/modules-template/README.md；{{SUB_REQ_SLUG}} 无论目录是否重命名都要替换）。{{NOW_ISO}} = ISO-8601 带时区时间戳（格式见 document-norms §2.7）；{{TODAY}} = YYYY-MM-DD
4. 调 module-index-refresh skill 同步需求层索引段：<sub>/overview.md（requirements-index）+ <sub>/requirements/overview.md（requirements-by-status）+ <req_slug>/overview.md（sub-requirements-index，初次同步含 main/ 一行）

Step 3: frontmatter 校验 + 报告

• 校验所有新建文件的 frontmatter 字段齐全（§2 必填字段；basic/sub 由脚本模板渲染保证，抽查即可）
• module 字段二段式（仅子模块和需求）
• 输出报告：

  ✅ 已创建：
    - projects/modules/<basic>/<sub>/submodule.yaml
    - projects/modules/<basic>/<sub>/overview.md
    - ... (其他文件)
  
  ✅ 已同步索引段：
    - projects/modules/overview.md
    - projects/modules/<basic>/overview.md
  
  ⚠️ 待人工填充：
    - submodule.yaml 的 code_paths（项目根相对，如 miniprogram/pages/<sub>/**）
    - submodule.yaml 的 tech_stack（数组对象）
  
  下一步建议：
    - 配置 code_paths 后跑 `python "$(cat .claude/workframe-state/plugin-root.txt)/scripts/check-stale-modules.py" init-submodule <basic>/<sub>` 触发反向索引重建（或 `... rebuild-index` 全量重建）
    - 调 `code-to-doc` skill 解析现有代码生成 current-state/
  

输出

• 新建的目录与文件
• 同步刷新的上级 overview 机器维护索引段
• 待人工填充清单（code_paths / tech_stack）
• 下一步建议（reindex / code-to-doc）

质量自检

• 项目类型按 §对话流总则 第 2 条判定（先 .workframe-config.json，不只看 CLAUDE.md）
• 资产类型在 Step 1 单次确定后不再二次确认（§对话流总则 第 1 条）
• 用户输入 name 只问一次（§对话流总则 第 4 条；yaml 无 slug + display_name 二字段）
• name 符合 §输入 命名约定（3 条 OS 硬约束）
• 父级存在（创建子模块/需求时）
• 所有 {{XXX}} 占位符已替换（basic / sub 由脚本断言零残留；需求模式手工替换 {{REQ_SLUG}} + {{REQ_TITLE}} + {{SUB_REQ_SLUG}} 后自查；需求类型相关占位符已废弃，不再有效）
• frontmatter updated = 当前 ISO 时间
• module 字段二段式（子模块/需求）
• 上级 overview 机器维护段已重建（basic/sub 两层由脚本收尾自动做；需求层已调 module-index-refresh）
• 反向索引段已初始化（子模块且 code_paths 非空时——脚本自动，⚠ 警告已转述）
• HTML 注释边界格式正确（§3.3）
• 报告末尾未输出"本项目可能不该启用 modules/"的盲目警告（前提校验已合规时；§对话流总则 第 6 条）
• 询问 name 时按 §对话流总则 第 7 条文案模板：核心问题独占一行 + 粗体 / ❓ 突出，命名约束折叠到 > 引用块小字，可选项明确标注"不答即用默认"

反模式

• ❌ 三层及以上嵌套（<basic>/<sub>/<sub-sub>/ 拒绝；超出拆基础模块）
• ❌ 创建子模块时跳过父基础模块（必须父级先存在）
• ❌ 跳过上级 overview 同步（module-index-refresh 必须调用）
• ❌ 手动编辑机器维护段（HTML 注释 START/END 之间）
• ❌ code_paths 写小程序根相对路径（必须项目根相对）
• ❌ 用 module-init 修改已存在模块（应 Edit + module-index-refresh）
• ❌ 在对话流里出现已废字段 slug / display_name（基础/子模块只有单字段 name）；也别因此误用旧模板占位符 {{BASIC_SLUG}} / {{BASIC_DISPLAY_NAME}} 等（已替换为 {{BASIC_NAME}} / {{SUB_NAME}}）
• ❌ 用 AskUserQuestion 给硬编码候选名（如 user / demo / content / auth）—— 除非候选基于本项目上下文合理推荐
• ❌ 把 projects/specs/ 是否存在 当作"已有老需求"信号（项目骨架默认建空 overview.md，不算真需求）
• ❌ 项目类型只看 CLAUDE.md 不读 .workframe-config.json（scaffold 不保证 CLAUDE.md 已渲染）
• ❌ 前提校验已通过还输出"本项目可能不该启用 modules/"盲目警告（只在校验失败时才提示）
• ❌ 已确定要建子模块 / 需求后又重复问"创建哪类资产"（资产类型一旦确定不再二次确认）
• ❌ 询问 name 时把核心问题（"叫什么名字？"）和命名约束 + 可选项混在同一段——核心问题被淹没，PM 不知道现在该回什么；正确做法见 §对话流总则 第 7 条文案模板
• ❌ 强问 sub_req_name——默认建 main/ 即可，立项前 PM 往往无法判断要不要拆子需求；事后想改名或拆分都好办（直接新建另一个 <sub_req_slug>/）
• ❌ 立项时主动建多个子需求目录——除非用户明确说要拆，默认就一个 main/；多余的子需求目录是噪音
• ❌ 在需求层 frontmatter / yaml 里写已废除字段（需求版本字段、需求类型枚举不使用；版本演进进 prd.md「变更与决策记录」，目录结构不表达需求类型）

完整反模式见 skill: document-norms §10。

与其他 skill 的衔接

• document-norms §1 §2 §3 §4：归属与字段标准（前置）
• module_init.py（core script）：basic/sub 落盘 + 两层索引段 + 反向索引的机械承包方（Step 2a）
• module-index-refresh：需求层索引段同步（Step 2b 第 4 步必调）
• code-to-doc：创建子模块后建议调用，从代码反向生成 current-state/
• prd-writer：创建需求资产包后产出 <sub_req_slug>/prd.md（业务方）；默认覆盖 main/prd.md 占位符内容
• migrate-to-modules：大规模迁移时为内部子例程被调用
• check-stale-modules.py（hook script）：反向索引并发安全的最终承担方（由 module_init.py 内部调用）

失败模式与降级

失败	降级
module_init.py 退出码 2（参数/命名校验）	转述 stderr 原文，修正输入后重跑；不手工补文件
module_init.py 退出码 1（异常）	转述报错；确认 plugin-root.txt 指向的插件根有效后重试
反向索引初始化失败（脚本 ⚠ 警告）	转述警告 + 提示用户事后跑 python "$(cat .claude/workframe-state/plugin-root.txt)/scripts/check-stale-modules.py" rebuild-index
需求模式模板复制失败	报错 + 不写部分文件；用户重试
需求模式占位符替换不完全	报告未替换的占位符位置，请用户手动填充
需求层索引同步失败	报告"骨架已建但索引未同步"，提示手动 /core:module-index-refresh