spec-init

spec-init

Overview

spec-init is used to create a new requirements-level Spec Pack in this repository: automatically increment the three-digit number, create and switch to the {num}-{short-name} branch, generate the .aisdlc/specs/{num}-{short-name}/ directory structure, and write the original requirements into requirements/raw.md（UTF-8 with BOM）。

Constraint: even if the repository contains .gitmodules，spec-init only initializeroot project's Spec branch and Spec Pack; sub-repository branches are not created in batch at this stage.

When to use / when not to use

• When to use
  • The user wants to start a "new requirement" Spec (there is not yet a {num}-{short-name} branch and .aisdlc/specs/... directory).
  • The user has only provided Chinese requirements text (it is inconvenient to manually create a file first), and is worried about garbled text caused by parameter encoding.
  • You need to ensure the branch naming, number source, and directory structure conform to repository conventions.
• Do not use when
  • already on a valid {num}-{short-name} spec branch, and .aisdlc/specs/{num}-{short-name}/ already exists and its structure is complete (in this case, proceed directly to subsequent commands).

Quick reference

• Branch naming：{num}-{short-name}（num is a three-digit number;short-name is kebab-case, 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 location：<本SKILL.md目录>/scripts/
• Script entry point (PowerShell)：spec-create-branch.ps1（-File execute directly, requires PowerShell 5.0+)
• Script entry point (Bash)：spec-create-branch.sh(for command-line arguments, see --help; stdout outputs JSON)
• Key side effect: after the script executes successfully, it will delete the passed-in source file (whether it is the original file or a temporary file).
• Boundary with sub-repositories: if subsequent implementation involves submodules, in principle the implementation plan will create and verify a Spec branch with the same name as the root project between I1 -> I2 create and validate a Spec branch with the same name as the root project between

Implementation steps (Agent behavior specification)

1) Parse user input → always reduce it to a file path

Mandatory rule: always pass requirements content as a file path(to avoid problems with Chinese content in parameter passing/encoding).

• Input is a file path: use that path directly as $sourceFilePath(but warn that it "will be deleted").
• Input is text: use the Agent's Write tool to write the text directly into a temporary file under the repository root _sdlc-raw-temp.md, then use that path as $sourceFilePath。
  • No need to worry about leftovers: after the script executes successfully, it will automatically delete the source file.

Example (Agent operation):

1. Write 工具 → 路径: {REPO_ROOT}/_sdlc-raw-temp.md，内容: 用户提供的原始需求文本
2. 将 {REPO_ROOT}/_sdlc-raw-temp.md 作为 $sourceFilePath / --source-file 传入脚本

2) Generate short-name(2-4 words, kebab-case)

Extract a 2-4 word short name from the original requirements, prefer "verb-noun", and retain common technical abbreviations (such as oauth2、jwt、api）：

• Example: batch export orders + async task → export-orders-batch or add-order-export
• If unsure, prefer more general and shorter:export-orders

3) Call the script to create the branch and Spec Pack

Automatically select the script implementation based on the operating system (do not force-run the "other" one).

• Windows / PowerShell: use powershell -NoProfile -ExecutionPolicy Bypass -File "<脚本路径>" ... call
• macOS/Linux / Bash: directly execute spec-create-branch.sh(stdout outputs JSON)

Execution parameters (fill in only the parameters)

• PowerShell（Main）：

  • -ShortName <kebab-case>

  • -SourceFilePath <需求文件路径>

  • -Title <可选>

  • Invocation form:

    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 <可选>
  • Invocation form:spec-create-branch.sh --short-name <...> --source-file <...> [--title <...>]

Script responsibility boundaries:

• If the current directory is inside a submodule, the script should first trace back to the root project, then create the Spec branch and .aisdlc/specs/...
• Do not create a submodule branch at this stage, and do not generate an extra repo manifest file

4) Acceptance (DoD)

Check whether the following facts all hold simultaneously (none may be missing):

• Current branch name (git branch --show-current) conforms to {num}-{short-name}。
• .aisdlc/specs/<branchName>/ exists, and contains 5 required subdirectories (requirements/、design/、implementation/、verification/、release/）。
• .aisdlc/specs/<branchName>/requirements/raw.md exists, and its content equals the original requirement (note that the file header has a UTF-8 BOM).
• The passed-in source file has been deleted (this is not a bug; if the user needs to keep it, they should back it up themselves before step 1).
• If the repository contains .gitmodules: this stage does not require any sub-repository to have created a branch; this should be handled later by the I1/I2 gates

5) After completion: immediately hand back to using-aisdlc to continue automatic progression

spec-init After the DoD passes, this skill does not make a "next-step routing" decision (to avoid having a second routing source). Unified approach:

• Output ROUTER_SUMMARY(see next section)
• Immediately call using-aisdlc to route the next step (Router defaults to automatic continuation; enter R1:spec-product-clarify）

Output after completion and automatic routing (must be executed)

After Spec Pack initialization is complete (whether successful or failed),mustcomplete the following actions (in order, none may be omitted):

1. Output ROUTER_SUMMARY(YAML form, for Router decision-making; fill in according to actual results):

On successful creation:

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）"

When any DoD is not satisfied and it stops:

ROUTER_SUMMARY:
  stage: R0
  artifacts: []
  needs_human_review: true
  blocked: true
  block_reason: "<填写失败点与最小修复动作>"
  notes: "未完成初始化，需先修复再继续"

1. Immediately execute using-aisdlc: pass the above ROUTER_SUMMARY as routing input to using-aisdlc, and let the Router determine the next step andautomatically proceed(no need to wait for the user to say "continue").

   • If the Router determines that automatic continuation is possible: continue executing the next worker skill in the same conversation round (such as R1, etc.)
   • If the Router triggers a hard interruption: stop and output the blocking reason, required inputs, and candidate next steps

2. Conversation output: before calling using-aisdlc, you may briefly state "The artifacts for this stage have been written to disk; now calling using-aisdlc to route the next step."

Common errors (and how to avoid them)

• Inventing your own branch/directory structure: do not use spec/<slug>、feature/<slug>、features/<slug>; the specification for this repository is {num}-{short-name} + .aisdlc/specs/...。
• Passing Chinese requirements directly as command-line arguments: always write them to a file, then pass the path.
• Mistakenly thinking the script will not delete the source file: it will delete the file pointed to by SourceFilePath ; for the user's original file, be sure to first confirm whether a backup is needed.
• Short names are nonstandard: Avoid uppercase, underscores, Chinese; avoid leading/trailing hyphens and consecutive --; try to use 2-4 words.
• Treat submodule as the Spec root directory: Even if triggered from a sub-repo directory, you must return to the root project to create .aisdlc/specs/...