spec-init

Overview

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

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

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).

Implementation Steps (Agent Behavior Specifications)

0) Pre-Check (Do Not Skip)

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) Parse User Input → Always Use File Path

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) Generate

short-name

(2-4 Words, Kebab-Case)

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) Call Script to Create Branch and Spec Pack

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) Acceptance Criteria (DoD)

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) After Completion: Automatically Proceed to

spec-product-clarify

(R1)

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 First, Pass the Gate: Locate

FEATURE_DIR

(Mandatory)

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 Proceed to R1: Follow

spec-product-clarify

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

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)

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

NPX Install

Tags

SKILL.md Content (Chinese)

spec-init

Overview

When to Use / Not to Use

Quick Reference

Implementation Steps (Agent Behavior Specifications)

0) Pre-Check (Do Not Skip)

1) Parse User Input → Always Use File Path

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

3) Call Script to Create Branch and Spec Pack

4) Acceptance Criteria (DoD)

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

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

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

NPX Install

Tags

SKILL.md Content (Chinese)

spec-init

Overview

When to Use / Not to Use

Quick Reference

Implementation Steps (Agent Behavior Specifications)

0) Pre-Check (Do Not Skip)

1) Parse User Input → Always Use File Path

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

3) Call Script to Create Branch and Spec Pack

4) Acceptance Criteria (DoD)

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

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

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) Generate
`short-name`
(2-4 Words, Kebab-Case)

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

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

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