module-init

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（默认空）
     

   • 子模块标准文案模板（单基础模块时）：

     **这个子模块叫什么名字？**
     
     > 命名约束同基础模块（英文 / 数字 / 短横线 / 下划线 / 中文；不含 `/` `\` `< > : " | ? *`；不含空格）。
     
     父基础模块默认为 `用户档案`（当前唯一），可不答。
     
     可选（不答即用默认）：
     - owner（默认 `pm`）
     - tech_stack / code_paths（留空我会跳过反向索引初始化，可后填）
     

   • 需求标准文案模板（注意：需求目录不表达版本，默认在 <req_slug>/ 下建一个子需求目录 main/；不强问 sub_req_name，事后想改名直接重命名目录即可）：

     **这个需求叫什么名字？**（用作目录名 + 跨文档引用标识）
     
     > 命名约束同模块（英文 / 数字 / 短横线 / 下划线 / 中文；不含 `/` `\` `< > : " | ? *`；不含空格）。
     >
     > **两个占位符都从这一个答案派生，不再单独问**：`{{REQ_SLUG}}` = 目录名（原样）；
     > `{{REQ_TITLE}}` = 展示标题——**默认等于目录名**，仅当用户答的是英文 slug
     > （如 `avatar-cropper`）时才顺带问一句中文标题，中文名直接两处同值。
     > 骨架里两个占位符都必须替换，留一个没换会在 PRD 标题里露出 `{{REQ_TITLE}}`。
     
     可选（不答即用默认）：
     - owner（默认 `pm`）
     - sub_req_name（默认 `main`；想给首个子需求另起名时填，例如 `phase-1`、`核心流程`；后续拆子需求直接新建即可，不必现在决定）