spec-init

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 .aidlc/specs/{num}-{short-name}/ directory structure, and write the original requirement into requirements/raw.md（UTF-8 with BOM）。

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

When to use / when not to use

• When to use
  • The user wants to start the Spec for a "new requirement" (there is no {num}-{short-name} branch or .aidlc/specs/... directory yet).
  • The user has only provided the requirement text in Chinese (it is inconvenient to manually create a file first), and is worried that argument encoding will cause garbled text.
  • You need to ensure that the branch naming, number source, and directory structure conform to repository conventions.
• Do not use it when
  • already on a valid {num}-{short-name} spec branch, and .aidlc/specs/{num}-{short-name}/ already exists with a complete structure (in this case go directly to the subsequent commands).

Quick reference

• Branch naming：{num}-{short-name}（num is a three-digit number;short-name is kebab-case, lowercase letters/digits/hyphens)
• Unified output location：.aidlc/specs/{num}-{short-name}/
• Required subdirectories：requirements/、design/、implementation/、verification/、release/
• Initial file：requirements/raw.md(content = original requirement; 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 deletes 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 creates and verifies, between I1 -> I2 , a Spec branch with the same name as the root project

Implementation steps (Agent behavior specification)

1) Parse user input → always resolve to a file path

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

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

Example (Agent operation):

1. Write 工具 → 路径: {REPO_ROOT}/_dlc-raw-temp.md，内容: 用户提供的原始需求文本
2. 将 {REPO_ROOT}/_dlc-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 requirement, preferring "verb-noun", and retaining common technical abbreviations (such as oauth2、jwt、api）：

• Example: batch export orders + async task → export-orders-batch or add-order-export
• If uncertain, prefer something more generic 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 "<脚本路径>" ... to invoke
• 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 .aidlc/specs/...
• Do not create submodule branches 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):

• The current branch name (git branch --show-current) conforms to {num}-{short-name}。
• .aidlc/specs/<branchName>/ exists and contains the 5 required subdirectories (requirements/、design/、implementation/、verification/、release/）。
• .aidlc/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: at this stage no sub-repository is required to have created a branch; this should be handled later by the I1/I2 gates

5) After completion: immediately hand back to using-aidlc 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). The unified approach:

• Output ROUTER_SUMMARY(see the next section)
• Immediately call using-aidlc to route the next step (the Router automatically continues by default; 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(in YAML form, for Router decision-making; fill in according to the actual result):

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-aidlc: pass the above ROUTER_SUMMARY as routing input to using-aidlc, 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 (such as R1, etc.) within the same conversation turn
   • If the Router triggers a hard interrupt: stop and output the blocking reason, the required input, and candidate next steps

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

Common mistakes (and how to avoid them)

• Inventing your own branch/directory structure: do not use spec/<slug>、feature/<slug>、features/<slug>; the convention of this repository is {num}-{short-name} + .aidlc/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 non-standard: Avoid uppercase, underscores, Chinese; avoid leading and trailing hyphens and consecutive --; try to keep it 2-4 words.
• Treat submodule as the Spec root directory: even if triggered from a sub-repository directory, you must return to the root project to create .aidlc/specs/...