spec-init

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

spec-init

概览

Overview

spec-init

用于在本仓库里创建一个新的需求级 Spec Pack：自动递增三位编号、创建并切换到

{num}-{short-name}

分支、生成

.aisdlc/specs/{num}-{short-name}/

目录结构，并把原始需求写入

requirements/raw.md

（UTF-8 with BOM）。

spec-init

is used to create a new requirement-level Spec Pack in this repository: automatically increment the three-digit number, create and switch to the

{num}-{short-name}

branch, generate the directory structure

.aisdlc/specs/{num}-{short-name}/

, and write the original requirements to

requirements/raw.md

(UTF-8 with BOM).

何时使用 / 不使用

When to Use / Not to Use

使用时机
- 用户要开始一个“新需求”的 Spec（还没有
```
{num}-{short-name}
```
  分支与
```
.aisdlc/specs/...
```
  目录）。
- 用户只给了中文需求文本（不方便先手动建文件），担心参数编码导致乱码。
- 需要确保分支命名、编号来源、目录结构与后续命令（如
```
spec-product-clarify
```
  ）一致。
不要用在
- 已经在一个合法的
```
{num}-{short-name}
```
  spec 分支上，且
```
.aisdlc/specs/{num}-{short-name}/
```
  已存在并结构完整（这时直接进入后续命令）。

Use Cases
- You are starting a Spec for a "new requirement" (no
```
{num}-{short-name}
```
  branch or
```
.aisdlc/specs/...
```
  directory exists yet).
- You only have Chinese requirement text (it's inconvenient to manually create files first) and are worried about garbled characters caused by parameter encoding.
- You need to ensure consistency between branch naming, numbering source, directory structure, and subsequent commands (such as
```
spec-product-clarify
```
  ).
Do Not Use When
- You are already on a valid
```
{num}-{short-name}
```
  spec branch, and the
```
.aisdlc/specs/{num}-{short-name}/
```
  directory already exists with a complete structure (proceed directly to subsequent commands in this case).

快速参考

Quick Reference

分支命名：
```
{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）
脚本入口：
```
spec-create-branch.ps1
```
的
```
Main
```
脚本参数
- ```
-ShortName
```
  （必需）
- ```
-SourceFilePath
```
  （必需，必须是文件路径）
- ```
-Title
```
  （可选）
关键副作用：脚本执行成功后会删除
```
SourceFilePath
```
指向的源文件（无论是原始文件还是临时文件）。

Branch Naming:
```
{num}-{short-name}
```
(
```
num
```
is a three-digit number;
```
short-name
```
is in kebab-case, using lowercase letters/numbers/hyphens)
Unified Output Location:
```
.aisdlc/specs/{num}-{short-name}/
```

Required Subdirectories:

requirements/

design/

implementation/

verification/

release/

Initial File:
```
requirements/raw.md
```
(content = original requirements; encoding = UTF-8 with BOM)
Script Entry Point:
```
Main
```
in
```
spec-create-branch.ps1
```
Script Parameters
- ```
-ShortName
```
  (required)
- ```
-SourceFilePath
```
  (required, must be a file path)
- ```
-Title
```
  (optional)
Key Side Effect: The source file pointed to by
```
SourceFilePath
```
will be deleted after the script executes successfully (whether it's an original file or a temporary file).

实施步骤（Agent 行为规范）

Implementation Steps (Agent Behavior Specifications)

0) 预检（不要跳过）

0) Pre-Check (Do Not Skip)

确认当前工作目录在目标 Git 仓库内（
```
git rev-parse --show-toplevel
```
能成功）。
确认 PowerShell 版本满足脚本要求（脚本声明
```
#Requires -Version 7.0
```
）。
如果用户提供的是“文件路径”，提醒：该文件会被脚本删除；如需保留，先复制一份再传入。

Confirm that the current working directory is within the target Git repository (
```
git rev-parse --show-toplevel
```
executes successfully).
Confirm that the PowerShell version meets the script requirements (the script declares
```
#Requires -Version 7.0
```
).
If the user provides a "file path", remind them: this file will be deleted by the script; if you need to keep it, make a copy before passing it in.

1) 解析用户输入 → 一律落到文件路径

1) Parse User Input → Always Use File Path

强制规则：始终以文件路径方式传入需求内容（避免中文内容在参数传递/编码上出问题）。

输入是文件路径：直接用该路径作为
```
$sourceFilePath
```
（但要提示“会被删除”）。
输入是文本：创建临时文件并用 UTF-8 with BOM 写入，然后把临时文件路径作为
```
$sourceFilePath
```
。

PowerShell 模板（文本 → BOM 临时文件）：

powershell

$raw = @"
为现有后台系统新增‘批量导出订单’功能：支持按时间范围/状态筛选、CSV 与 XLSX 两种格式、导出任务异步执行并在导出中心可下载，权限仅管理员可见。
"@

$utf8Bom = [System.Text.UTF8Encoding]::new($true)
$tmp = Join-Path ([System.IO.Path]::GetTempPath()) ("sdlc-raw-{0}.md" -f ([guid]::NewGuid().ToString("N")))
[System.IO.File]::WriteAllText($tmp, $raw, $utf8Bom)
$sourceFilePath = $tmp

Mandatory Rule: Always pass requirement content via a file path (to avoid issues with Chinese content in parameter passing/encoding).

Input is a file path: Directly use this path as
```
$sourceFilePath
```
(but prompt "will be deleted").
Input is text: Create a temporary file and write to it using UTF-8 with BOM, then use the temporary file path as
```
$sourceFilePath
```
.

PowerShell Template (Text → BOM Temporary File):

powershell

$raw = @"
为现有后台系统新增‘批量导出订单’功能：支持按时间范围/状态筛选、CSV 与 XLSX 两种格式、导出任务异步执行并在导出中心可下载，权限仅管理员可见。
"@

$utf8Bom = [System.Text.UTF8Encoding]::new($true)
$tmp = Join-Path ([System.IO.Path]::GetTempPath()) ("sdlc-raw-{0}.md" -f ([guid]::NewGuid().ToString("N")))
[System.IO.File]::WriteAllText($tmp, $raw, $utf8Bom)
$sourceFilePath = $tmp

2) 生成

short-name

（2-4 词，kebab-case）

2) Generate

short-name

(2-4 Words, Kebab-Case)

从原始需求提炼 2-4 个词的短名称，优先“动词-名词”，保留常见技术缩写（如

oauth2

、

jwt

、

api

）：

示例：批量导出订单 + 异步任务 →
```
export-orders-batch
```
或
```
add-order-export
```
若不确定，宁可更通用、更短：
```
export-orders
```

Extract a 2-4 word short name from the original requirements, prioritize "verb-noun" structure, and retain common technical abbreviations (e.g.,

oauth2

jwt

api

Example: Batch export orders + asynchronous task →
```
export-orders-batch
```
or
```
add-order-export
```
If unsure, use a more general, shorter name:
```
export-orders
```

3) 调用脚本创建分支与 Spec Pack

3) Call Script to Create Branch and Spec Pack

必须用 dot sourcing 加载脚本并调用
Main
，不要直接运行脚本文件。

powershell

$repoRoot = (git rev-parse --show-toplevel)
. (Join-Path $repoRoot "skills\spec-init\spec-create-branch.ps1")

$shortName = "export-orders"
$title = ""

$result = Main -ShortName $shortName -SourceFilePath $sourceFilePath -Title $title
$result

You must load the script using dot sourcing and call
Main
; do not run the script file directly.

powershell

$repoRoot = (git rev-parse --show-toplevel)
. (Join-Path $repoRoot "skills\spec-init\spec-create-branch.ps1")

$shortName = "export-orders"
$title = ""

$result = Main -ShortName $shortName -SourceFilePath $sourceFilePath -Title $title
$result

4) 验收（DoD）

4) Acceptance Criteria (DoD)

检查以下事实是否同时成立（缺一不可）：

当前分支名等于
```
$result.branchName
```
，且符合
```
{num}-{short-name}
```
。
```
.aisdlc/specs/$($result.branchName)/
```
存在，且包含 5 个必需子目录。
```
.aisdlc/specs/$($result.branchName)/requirements/raw.md
```
存在，内容等于原始需求，且为 UTF-8 with BOM。
```
$sourceFilePath
```
指向的源文件已被删除（这不是 bug；若用户需要保留，应在步骤 1 之前自行备份）。

如需对

raw.md

的 BOM 做显式校验，可用下面片段检查前三个字节是否为

EF BB BF

：

powershell

$repoRoot = (git rev-parse --show-toplevel)
$rawPath = (Join-Path $repoRoot ".aisdlc\specs\$($result.branchName)\requirements\raw.md")
$bytes = [System.IO.File]::ReadAllBytes((Resolve-Path $rawPath))
($bytes.Length -ge 3) -and ($bytes[0] -eq 0xEF) -and ($bytes[1] -eq 0xBB) -and ($bytes[2] -eq 0xBF)

Verify that all of the following are true (none can be missing):

The current branch name equals
```
$result.branchName
```
and conforms to
```
{num}-{short-name}
```
.
```
.aisdlc/specs/$($result.branchName)/
```
exists and contains the 5 required subdirectories.
```
.aisdlc/specs/$($result.branchName)/requirements/raw.md
```
exists, its content matches the original requirements, and it is encoded in UTF-8 with BOM.
The source file pointed to by
```
$sourceFilePath
```
has been deleted (this is not a bug; if the user needs to keep it, they should back it up before step 1).

If you need to explicitly verify the BOM of

raw.md

, use the following snippet to check if the first three bytes are

EF BB BF

powershell

$repoRoot = (git rev-parse --show-toplevel)
$rawPath = (Join-Path $repoRoot ".aisdlc\specs\$($result.branchName)\requirements\raw.md")
$bytes = [System.IO.File]::ReadAllBytes((Resolve-Path $rawPath))
($bytes.Length -ge 3) -and ($bytes[0] -eq 0xEF) -and ($bytes[1] -eq 0xBB) -and ($bytes[2] -eq 0xBF)

5) 完成后：自动进入

spec-product-clarify

（R1）

5) After Completion: Automatically Proceed to

spec-product-clarify

(R1)

强制衔接规则：

spec-init

的 DoD 通过后，不要停在“提示下一步”，而是立刻进入 R1（澄清 + 方案对比 + 推荐决策），直到产出

requirements/solution.md

或用户明确停止。

Mandatory Transition Rule: After the DoD of

spec-init

is met, do not stop at "prompt for next steps"; instead, immediately proceed to R1 (clarification + solution comparison + recommended decision) until

requirements/solution.md

is produced or the user explicitly stops.

5.1 先过门禁：定位

FEATURE_DIR

（必须）

5.1 First, Pass the Gate: Locate

FEATURE_DIR

(Mandatory)

禁止手写/猜
.aisdlc/specs/...
路径；必须以
spec-context
的输出为准。

powershell

$repoRoot = (git rev-parse --show-toplevel)
. (Join-Path $repoRoot "skills\spec-context\spec-common.ps1")
$context = Get-SpecContext
$FEATURE_DIR = $context.FEATURE_DIR
Write-Host "FEATURE_DIR=$FEATURE_DIR"

若上面报错 → 立刻停止（不要继续生成/写任何

requirements/*.md

内容）。

Do not manually write/guess the
.aisdlc/specs/...
path; must use the output of
spec-context
.

powershell

$repoRoot = (git rev-parse --show-toplevel)
. (Join-Path $repoRoot "skills\spec-context\spec-common.ps1")
$context = Get-SpecContext
$FEATURE_DIR = $context.FEATURE_DIR
Write-Host "FEATURE_DIR=$FEATURE_DIR"

If the above code throws an error → Stop immediately (do not continue generating/writing any

requirements/*.md

content).

5.2 进入 R1：按

spec-product-clarify

的“一次一问 + 增量回写”推进

5.2 Proceed to R1: Follow

spec-product-clarify

's "One Question at a Time + Incremental Rewrite" Approach

从这里开始，严格按

spec-product-clarify

执行（无需重复发明流程），最小闭环如下：

读取：
```
$FEATURE_DIR/requirements/raw.md
```
立刻发起第 1 个澄清问题：只问 1 个最高杠杆未知，优先做成 2–4 选项的选择题（带“其他/不确定”兜底 + 你的推荐项与理由）
用户回答后必须增量回写：追加到
```
$FEATURE_DIR/requirements/raw.md
```
的
```
## 澄清记录
```
停止条件满足后生成：
```
$FEATURE_DIR/requirements/solution.md
```
（结论摘要 / 推荐方案 / 2–3 备选 / 决策依据 / 验证清单 / 迭代记录）

关键禁令：不写“待确认问题清单”；所有不确定性统一进入
solution.md
的“验证清单”（Owner/截止/信号/动作）。

From this point, strictly follow

spec-product-clarify

(no need to reinvent the process); the minimum closed loop is as follows:

Read:
```
$FEATURE_DIR/requirements/raw.md
```
Immediately Initiate the 1st Clarification Question: Only ask 1 highest-leverage unknown, preferably as a multiple-choice question with 2–4 options (with "Other/Unsure" fallback + your recommended option and rationale)
After User Answers, Must Incrementally Rewrite: Append to the
```
## Clarification Records
```
section in
```
$FEATURE_DIR/requirements/raw.md
```
Generate When Stop Conditions Are Met:
```
$FEATURE_DIR/requirements/solution.md
```
(conclusion summary / recommended solution / 2–3 alternatives / decision basis / verification checklist / iteration records)

Key Prohibition: Do not write "pending confirmation question list"; all uncertainties should be unified into the "verification checklist" in
solution.md
(Owner/Deadline/Signal/Action).

常见错误（以及怎么避免）

Common Mistakes (and How to Avoid Them)

自创分支/目录结构：不要用

spec/<slug>

、

feature/<slug>

、

features/<slug>

；本仓库规范是

{num}-{short-name}

.aisdlc/specs/...

。

把中文需求当作命令行参数直接传递：一律写入 UTF-8 BOM 文件，再传路径。
误以为脚本不会删源文件：它会删除
```
SourceFilePath
```
指向的文件；对用户的原始文件务必先确认是否需要备份。
短名称不规范：避免大写、下划线、中文；避免前后连字符与连续
```
--
```
；尽量 2-4 词。

Creating Custom Branch/Directory Structures: Do not use
```
spec/<slug>
```
,
```
feature/<slug>
```
,
```
features/<slug>
```
; the repository specification is
```
{num}-{short-name}
```
+
```
.aisdlc/specs/...
```
.
Directly Passing Chinese Requirements as Command Line Parameters: Always write to a UTF-8 BOM file first, then pass the path.
Mistakenly Believing the Script Won't Delete the Source File: It will delete the file pointed to by
```
SourceFilePath
```
; always confirm with the user whether they need to back up their original file first.
Non-Standard Short Names: Avoid uppercase letters, underscores, Chinese characters; avoid leading/trailing hyphens and consecutive
```
--
```
; aim for 2-4 words.

spec-init

Original

Translation

spec-init

spec-init

概览

Overview

何时使用 / 不使用

When to Use / Not to Use

快速参考

Quick Reference

实施步骤（Agent 行为规范）

Implementation Steps (Agent Behavior Specifications)

0) 预检（不要跳过）

0) Pre-Check (Do Not Skip)

1) 解析用户输入 → 一律落到文件路径

1) Parse User Input → Always Use File Path

2) 生成
`short-name`
（2-4 词，kebab-case）

2) Generate
`short-name`
(2-4 Words, Kebab-Case)

3) 调用脚本创建分支与 Spec Pack

3) Call Script to Create Branch and Spec Pack

4) 验收（DoD）

4) Acceptance Criteria (DoD)

5) 完成后：自动进入
`spec-product-clarify`
（R1）

5) After Completion: Automatically Proceed to
`spec-product-clarify`
(R1)

5.1 先过门禁：定位
`FEATURE_DIR`
（必须）

5.1 First, Pass the Gate: Locate
`FEATURE_DIR`
(Mandatory)

5.2 进入 R1：按
`spec-product-clarify`
的“一次一问 + 增量回写”推进

5.2 Proceed to R1: Follow
`spec-product-clarify`
's "One Question at a Time + Incremental Rewrite" Approach

常见错误（以及怎么避免）

Common Mistakes (and How to Avoid Them)

spec-init

Original

Translation

spec-init

spec-init

概览

Overview

何时使用 / 不使用

When to Use / Not to Use

快速参考

Quick Reference

实施步骤（Agent 行为规范）

Implementation Steps (Agent Behavior Specifications)

0) 预检（不要跳过）

0) Pre-Check (Do Not Skip)

1) 解析用户输入 → 一律落到文件路径

1) Parse User Input → Always Use File Path

2) 生成 short-name（2-4 词，kebab-case）

2) Generate short-name (2-4 Words, Kebab-Case)

3) 调用脚本创建分支与 Spec Pack

3) Call Script to Create Branch and Spec Pack

4) 验收（DoD）

4) Acceptance Criteria (DoD)

5) 完成后：自动进入 spec-product-clarify（R1）

5) After Completion: Automatically Proceed to spec-product-clarify (R1)

5.1 先过门禁：定位 FEATURE_DIR（必须）

5.1 First, Pass the Gate: Locate FEATURE_DIR (Mandatory)

5.2 进入 R1：按 spec-product-clarify 的“一次一问 + 增量回写”推进

5.2 Proceed to R1: Follow spec-product-clarify's "One Question at a Time + Incremental Rewrite" Approach

常见错误（以及怎么避免）

Common Mistakes (and How to Avoid Them)

2) 生成
`short-name`
（2-4 词，kebab-case）

2) Generate
`short-name`
(2-4 Words, Kebab-Case)

5) 完成后：自动进入
`spec-product-clarify`
（R1）

5) After Completion: Automatically Proceed to
`spec-product-clarify`
(R1)

5.1 先过门禁：定位
`FEATURE_DIR`
（必须）

5.1 First, Pass the Gate: Locate
`FEATURE_DIR`
(Mandatory)

5.2 进入 R1：按
`spec-product-clarify`
的“一次一问 + 增量回写”推进

5.2 Proceed to R1: Follow
`spec-product-clarify`
's "One Question at a Time + Incremental Rewrite" Approach