spec-init
概览
spec-init 用于在本仓库里创建一个新的需求级 Spec Pack：自动递增三位编号、创建并切换到 {num}-{short-name} 分支、生成 .aisdlc/specs/{num}-{short-name}/ 目录结构，并把原始需求写入 requirements/raw.md（UTF-8 with BOM）。
约束：即使仓库包含 .gitmodules，spec-init 也只初始化根项目的 Spec 分支与 Spec Pack；子仓分支不在本阶段批量创建。
何时使用 / 不使用
- 使用时机
- 用户要开始一个"新需求"的 Spec（还没有 {num}-{short-name} 分支与 .aisdlc/specs/... 目录）。 - 用户只给了中文需求文本（不方便先手动建文件），担心参数编码导致乱码。 - 需要确保分支命名、编号来源、目录结构符合仓库约定。
- 不要用在
- 已经在一个合法的 {num}-{short-name} spec 分支上，且 .aisdlc/specs/{num}-{short-name}/ 已存在并结构完整（这时直接进入后续命令）。
快速参考
- 分支命名：
{num}-{short-name}（num为三位数字；short-name为 kebab-case，小写字母/数字/连字符） - 统一输出位置：
.aisdlc/specs/{num}-{short-name}/ - 必备子目录：
requirements/、design/、implementation/、verification/、release/ - 初始文件：
requirements/raw.md（内容=原始需求；编码=UTF-8 with BOM） - 脚本位置：
<本SKILL.md目录>/scripts/ - 脚本入口（PowerShell）：
spec-create-branch.ps1（-File直接执行，需 PowerShell 5.0+） - 脚本入口（Bash）：
spec-create-branch.sh（命令行参数见--help；stdout 输出 JSON） - 关键副作用：脚本执行成功后会删除传入的源文件（无论是原始文件还是临时文件）。
- 与子仓的边界：若后续实现涉及 submodule，原则上由实现计划在
I1 -> I2之间创建并校验与根项目同名的 Spec 分支
实施步骤（Agent 行为规范）
1) 解析用户输入 → 一律落到文件路径
强制规则：始终以文件路径方式传入需求内容（避免中文内容在参数传递/编码上出问题）。
- 输入是文件路径：直接用该路径作为
$sourceFilePath（但要提示"会被删除"）。 - 输入是文本：用 Agent 的 Write 工具 将文本直接写入仓库根目录下的临时文件
_sdlc-raw-temp.md，然后用该路径作为$sourceFilePath。
- 无需担心残留：脚本执行成功后会自动删除该源文件。
示例（Agent 操作）：
1. Write 工具 → 路径: {REPO_ROOT}/_sdlc-raw-temp.md，内容: 用户提供的原始需求文本
2. 将 {REPO_ROOT}/_sdlc-raw-temp.md 作为 $sourceFilePath / --source-file 传入脚本2) 生成 short-name（2-4 词，kebab-case）
从原始需求提炼 2-4 个词的短名称，优先"动词-名词"，保留常见技术缩写（如 oauth2、jwt、api）：
- 示例：批量导出订单 + 异步任务 →
export-orders-batch或add-order-export - 若不确定，宁可更通用、更短：
export-orders
3) 调用脚本创建分支与 Spec Pack
按操作系统自动选择脚本实现（不要硬跑"另一种"）。
- Windows / PowerShell：用
powershell -NoProfile -ExecutionPolicy Bypass -File "<脚本路径>"...调用 - macOS/Linux / Bash：直接执行
spec-create-branch.sh（stdout 输出 JSON）
执行参数（只填参数即可）
- PowerShell（
Main）：
- -ShortName <kebab-case> - -SourceFilePath <需求文件路径> - -Title <可选> - 调用形态： powershell -NoProfile -ExecutionPolicy Bypass -File "<本SKILL.md目录>/scripts/spec-create-branch.ps1" -ShortName "<kebab-case>" -SourceFilePath "<需求文件路径>" [-Title "<标题>"]
- Bash（
spec-create-branch.sh）：
- --short-name <kebab-case> - --source-file <需求文件路径> - --title <可选> - 调用形态：spec-create-branch.sh --short-name <...> --source-file <...> [--title <...>]
脚本职责边界：
- 若当前目录位于 submodule 内，脚本应先回溯到根项目，再在根项目创建 Spec 分支与
.aisdlc/specs/... - 不在此阶段创建 submodule 分支，也不生成额外的 repo 清单文件
4) 验收（DoD）
检查以下事实是否同时成立（缺一不可）：
- 当前分支名（
git branch --show-current）符合{num}-{short-name}。 .aisdlc/specs/<branchName>/存在，且包含 5 个必需子目录（requirements/、design/、implementation/、verification/、release/）。.aisdlc/specs/<branchName>/requirements/raw.md存在，内容等于原始需求（注意文件头有 UTF-8 BOM）。- 传入的源文件已被删除（这不是 bug；若用户需要保留，应在步骤 1 之前自行备份）。
- 若仓库包含
.gitmodules：本阶段不要求任何子仓已创建分支；后续应由 I1/I2 门禁处理
5) 完成后：立即交回 using-aisdlc 继续自动推进
spec-init 的 DoD 通过后，本技能不做"下一步分流"判定（避免出现第二个路由源）。统一做法：
- 输出
ROUTER_SUMMARY（见下节） - 立即调用
using-aisdlc路由下一步（Router 默认自动续跑；进入 R1：spec-product-clarify）
完成后输出与自动路由（必须执行）
Spec Pack 初始化完成后（无论成功或失败），必须完成以下动作（按顺序，不可省略）：
- 输出 ROUTER_SUMMARY（YAML 形态，供 Router 决策；按实际结果填写）：
创建成功时：
ROUTER_SUMMARY:
stage: R0
artifacts:
- "{FEATURE_DIR}/requirements/raw.md"
needs_human_review: false
blocked: false
block_reason: ""
notes: "Spec Pack 已初始化完成；建议 Router 进入 R1（spec-product-clarify）"任一 DoD 未满足并停止时：
ROUTER_SUMMARY:
stage: R0
artifacts: []
needs_human_review: true
blocked: true
block_reason: "<填写失败点与最小修复动作>"
notes: "未完成初始化，需先修复再继续"- 立即执行
using-aisdlc：将上述ROUTER_SUMMARY作为路由输入传递给 using-aisdlc，由 Router 判定下一步并自动推进（无需等待用户说「继续」）。
- 若 Router 判定可自动续跑：在同一轮对话内继续执行下一步 worker skill（如 R1 等） - 若 Router 触发硬中断：停下并输出阻断原因、需要的输入、候选下一步
- 对话输出：在调用 using-aisdlc 前，可简短说明「本阶段产物已落盘，正在调用 using-aisdlc 路由下一步。」
常见错误（以及怎么避免）
- 自创分支/目录结构：不要用
spec/<slug>、feature/<slug>、features/<slug>；本仓库规范是{num}-{short-name}+.aisdlc/specs/...。 - 把中文需求当作命令行参数直接传递：一律写入文件，再传路径。
- 误以为脚本不会删源文件：它会删除
SourceFilePath指向的文件；对用户的原始文件务必先确认是否需要备份。 - 短名称不规范：避免大写、下划线、中文；避免前后连字符与连续
--；尽量 2-4 词。 - 把 submodule 当作 Spec 根目录：即使从子仓目录触发，也必须回到根项目创建
.aisdlc/specs/...