SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsspec-plan

spec-plan

Agents & models

View repository

Updated 10-16 08:49

About this skill

spec-plan (I1: implementation plan / plan.md SSOT)

Overview

The goal of I1 is to turn {FEATURE_DIR}/requirements/* and {FEATURE_DIR}/design/* into adirectly executableimplementation orchestration: the main artifact is {FEATURE_DIR}/implementation/plan.md（Spec-level SSOT: task list, dependencies, AC mapping, branch mapping, Phase C gate, overall progress summary).
When Task Pack / multi-task collaboration is enabled, simultaneously write to disk at {FEATURE_DIR}/implementation/tasks/<TASK_DIR>/ the task-level SSOT (task.md、status.yaml、review.md, as needed research.md、design.md), sinking thehigh-frequency execution statedown from plan.md , to avoid multiple people contending for a single file.
Single-person single-branch degradation: you may skip creating implementation/tasks/, and still expand the complete steps and checkboxes within plan.md (compatible with historical I1).

At the start, announce:"I am using the spec-plan skill to create an implementation plan (plan.md SSOT)."

When to use / not use

  • When to use
    • You need to produce or update {FEATURE_DIR}/implementation/plan.md(mandatory for I1).
    • You are about to enter I2 execution, but there is currently no "checkable + executable" task list.
  • Do not use when
    • spec-context fails, and you cannot obtain FEATURE_DIR(in this case you must stop).
    • Insufficient input-side SSOT:requirements/solution.md and requirements/prd.md both do not exist, and scope/acceptance cannot be traced (you must mark NEEDS CLARIFICATION in plan.md and block entry into I2).

Gate / Stop (strictly enforced)

REQUIRED SUB-SKILL: currently executing spec-context to obtain context, and echo back in the conversation FEATURE_DIR=...(allowing (reuse)）。

Stop immediately (satisfying any one is sufficient):

  • Did not receive FEATURE_DIR
  • branch/directory uncertain (you find yourself wanting to "guess the .aidlc/specs/... path")
  • requirements/solution.md and requirements/prd.md are both missing, making the goal/scope/acceptance criteria untraceable
  • Any key uncertainty cannot be evidenced in the input (you must write it into plan.md/## NEEDS CLARIFICATION, and clearly state "block entry into I2")

Input / Output (on-disk conventions)

  • Read (progressive disclosure, minimum necessary)
    • Project-level (must-read its index or necessary fragments):project/memory/*、project/contracts/、project/adr/
      • Graceful degradation: if .aidlc/project/ does not exist or the above index files are missing, mark CONTEXT GAP butdo not block the I1 process; in the "impact scope and constraints" section of plan.md , note that the corresponding gap source is CONTEXT GAP, and suggest subsequently filling it in through Discover or actual verification
    • Spec-level (read as little as needed):{FEATURE_DIR}/requirements/solution.md or {FEATURE_DIR}/requirements/prd.md(at least one of them)
    • Impact analysis (mandatory, if solution.md exists): must read {FEATURE_DIR}/requirements/solution.md#impact-analysis, extract the list of affected modules and the invariants that must be observed, as constraint input for I1 (if missing, stop and return to R1 to fill it in)
    • Spec level (if present and relevant):{FEATURE_DIR}/design/design.md、{FEATURE_DIR}/design/research.md
    • .gitmodules(if present; used to identify the static list of submodules that can participate in implementation)
  • Write
    • Required：{FEATURE_DIR}/implementation/plan.md
    • Optional (multi-task / collaboration): for each task directory {FEATURE_DIR}/implementation/tasks/<TASK_DIR>/ initialize the Task Pack (copy from this skill's assets/ template and fill in):
      • task.md ← assets/task-template.md
      • status.yaml ← assets/task-status.template.yaml
      • review.md ← assets/task-review-template.md
      • As needed:research.md ← assets/task-research-template.md；design.md ← assets/task-design-template.md

Collaboration scripts (design doc §13.2 / §13.3)

The following scripts are located in this skill's ./scripts/（source files are ASCII, to avoid Windows PowerShell 5.1 failing to parse UTF-8 Chinese without a BOM). In theconsumer repositoryexecute; the current branch may be Spec branchortask branch（001-foo/T1-bar), or use -FeatureDir to explicitly pass in the Spec Pack path.

Script Purpose
task-collab-common.ps1 Internal module: dot-source, do not execute separately
init-task-pack.ps1 From assets/ template generate implementation/tasks/<TaskDir>/
new-task-branch.ps1 Create and switch from the Spec branch SpecBranch/TaskDir
sync-task-status-summary.ps1 Read-only summary of each status.yaml(may add -Json）
test-phase-c-gate.ps1 Phase B→C task-level gate (routing_status all done, no blocked）
validate-task-branch.ps1 §13.3: Task branch gate (the Task Pack directory must exist; can be hooked to pre-push)
set-task-review-state.ps1 §13.3: Write in_review / task-review
update-task-status-after-merge.ps1 §13.3: After merging back to Spec, mark the task as done
test-spec-integration-gate.ps1 §13.3: Invoke phase-c gate + optional -RequireCleanWorkingTree

Git hook example：assets/githooks-pre-push-validate-task-branch.sample.ps1

Example (in the root directory of the consumer repository, with the corresponding Spec or task branch already checked out):

powershell -NoProfile -ExecutionPolicy Bypass -File "<SKILL_DIR>/scripts/init-task-pack.ps1" -TaskDir T1-user-api -Title "Login API"
powershell -NoProfile -ExecutionPolicy Bypass -File "<SKILL_DIR>/scripts/new-task-branch.ps1" -TaskDir T1-user-api
powershell -NoProfile -ExecutionPolicy Bypass -File "<SKILL_DIR>/scripts/sync-task-status-summary.ps1"
powershell -NoProfile -ExecutionPolicy Bypass -File "<SKILL_DIR>/scripts/test-phase-c-gate.ps1"
powershell -NoProfile -ExecutionPolicy Bypass -File "<SKILL_DIR>/scripts/validate-task-branch.ps1"
powershell -NoProfile -ExecutionPolicy Bypass -File "<SKILL_DIR>/scripts/set-task-review-state.ps1" -TaskDir T1-user-api
powershell -NoProfile -ExecutionPolicy Bypass -File "<SKILL_DIR>/scripts/update-task-status-after-merge.ps1" -TaskDir T1-user-api -PrUrl "https://example.com/pr/1"
powershell -NoProfile -ExecutionPolicy Bypass -File "<SKILL_DIR>/scripts/test-spec-integration-gate.ps1" -RequireCleanWorkingTree

and spec-context relationship:spec-context already supportstask branchand outputs TASK_WORK_BRANCH / TASK_DIR / TASK_PACK_DIR; the worker must still first spec-context get FEATURE_DIR. The script is intended forhuman / CI, resolved via branch name or -FeatureDir ,does not replace spec-context gate. For Router additions, see using-aidlc 's router/routing-collaboration.md。

small task granularity (reuse writing-plans)

Each step is one action (2–5 minutes), and in plan.md write so that "anyone can copy and execute":

  • "Write a failing test" (if applicable) - one step
  • "Run to ensure it fails" - one step
  • "Implement the minimum code to make the test pass" - one step
  • "Run verification to ensure it passes" - one step
  • "Commit" (commit frequently; controlled by AUTO_COMMIT,AUTO_COMMIT=false mark as "skipped (AUTO_COMMIT=false)" and list the changed files) - one step

Constraint: I1 only writes plans, not code; but each task must declare itsminimum verification method(command + expected signal).

plan.md header (required)

Must start with this header(for the full structure, see ./assets/plan-template.md, including AC mapping, task dependencies, task index, Phase C gate and other collaboration fields):

# [需求名] 实现计划（SSOT）

> **必需技能：** `spec-execute`（按批次执行本计划）
> **上下文获取：** 必须先执行 `spec-context` 获取上下文，定位 `{FEATURE_DIR}`，失败即停止

**目标：** [一句话描述要交付什么]
**范围：** In / Out
**架构：** [2–3 句方法说明 + 关键约束]
**验收口径：** [引用 requirements/solution.md 或 requirements/prd.md 的 AC/验收点]
**影响范围：** [引用 requirements/solution.md#impact-analysis 的受影响模块清单]
**需遵守的不变量：** [从 requirements/solution.md#impact-analysis 提取的关键 API/Data 契约不变量]
**子仓范围：** [若存在 `.gitmodules`，列出本次需求涉及的 submodule；无则写“无”]

---

Plan body (required)

  • TL;DR: Summarize the plan's goal and scope in one sentence
  • Scope and boundaries: In/Out (align requirements and design)
  • AC mapping: Requirement AC → Task (collaboration mode recommended)
  • Task dependencies: Dependency graph or table (consistent with each Task Pack status.yaml in the depends_on )
  • Task index: Task ID, Owner, task branch,implementation/tasks/... path (recommended when Task Pack is enabled)
  • Phase C entry conditions: Gate check (see template)
  • Impact scope and constraints (required)：
    • List of affected modules and impact types (reference requirements/solution.md#impact-analysis）
    • API/Data contract invariants to be followed (list one by one, annotate source module/anchor)
    • Cross-module impacts and coordination items (based on dependency graph/impact analysis)
  • Code workspace list (if applicable, required)：
    • Reference affected sub-repository paths from .gitmodules Reference the affected sub-repository path
    • Mark whether each sub-repository required
    • Default branch requirement: same name as root project CURRENT_BRANCH With the same name
    • If exceptions exist, explicitly record exception_reason
  • Milestones and cadence: Phase breakdown, time estimates, deliverables list
  • Dependencies and resources: External systems/teams/permissions/environments/data dependencies
  • Risks and verification: Risk list, verification method, Owner
  • Acceptance criteria: Key ACs and acceptors corresponding to PRD/solution
  • NEEDS CLARIFICATION (required): List all unresolved uncertainties in one place (must not enter I2 before resolution)

Task structure (reuse writing-plans, but add SSOT/audit/gates)

plan.md must containcheckabletask list (- [ ]/- [x]). Check granularity isTask done, not every micro-step.

  • Task Pack not enabled: Each task can write full steps, verification, and audit in plan.md (legacy mode).
  • Task Pack enabled：plan.md keep task-level summary, index, and completion check;full steps and high-frequency statusare written to the corresponding directory's task.md and status.yaml(see ./assets/task-template.md）。

Each task must contain (complete in plan.md and/or the corresponding task.md , none may be omitted overall):

  • Exact file paths (create/modify/test)
  • Verifiable acceptance points (testable conditions)
  • Executable steps (command + expected output/signal)
  • Commit points and minimal audit information (record by repo branch/commit/pr/changed_files）

Task template (example skeleton):

## 任务清单（SSOT）

### Task T1: [任务标题]

- [ ] **状态**：未开始 / 进行中 / 完成 / 阻塞（阻塞必须写明取证路径）

**代码仓范围：**
- 根项目：
- 子仓：（如适用；填写 `.gitmodules` 中的路径，并注明 `required=true/false`）

**文件：**
- 创建：`exact/path/to/new.file`
- 修改：`exact/path/to/existing.file`（可选：精确到段落/函数）
- 测试：`tests/exact/path/to/test.file`（如适用）

**验收点：**
- [可验证条件 1]
- [可验证条件 2]

**步骤 1：写失败测试（如适用）**
- 修改点：`tests/...`
- Run: `[精确命令]`
- Expected: FAIL（写出期望看到的关键失败信号）

**步骤 2：写最少实现**
- 修改点：`path/to/file`

**步骤 3：运行验证**
- Run: `[精确命令]`
- Expected: PASS（写出期望看到的关键通过信号）

**步骤 4：提交（受 AUTO_COMMIT 控制）**
- `AUTO_COMMIT=true`（默认）：频繁提交；commit message 必须中文
  - Commit message: `[一句话说明 why（中文）]`
- `AUTO_COMMIT=false`：跳过自动提交，输出"以下文件已变更，请手动提交："及变更文件清单
- 审计信息：
  - repo: `root`
    branch: `{CURRENT_BRANCH}`
    commit: `<TBD>`（`AUTO_COMMIT=false` 时填"手动提交"）
    pr: `<TBD>`
    changed_files: `<TBD>`
  - repo: `<submodule path>`（如适用）
    branch: `{CURRENT_BRANCH}`
    commit: `<TBD>`（`AUTO_COMMIT=false` 时填"手动提交"）
    pr: `<TBD>`
    changed_files: `<TBD>`

Command writing convention: default to PowerShell; separate multiple commands on the same line with ; (do not use &&）。

I1-DoD (gate: none may be missing)

  • Plan scope is consistent with and traceable to {FEATURE_DIR}/requirements/*、{FEATURE_DIR}/design/* Consistent and traceable
  • Milestones are clear and acceptable (each item has a corresponding artifact or verifiable criterion)
  • Dependencies and risks are listed, with minimal verification/mitigation actions (including Owner)
  • Key acceptance criteria are traceable (at least reference requirements/prd.md or requirements/solution.md）
  • Scope of impact and constraints have been injected：plan.md Contains the "Scope of Impact and Constraints" section; affected modules and invariants that must be observed have been extracted from requirements/solution.md#impact-analysis and listed item by item
  • If .gitmodules exists and the impact analysis hits a sub-repository:plan.md The affected sub-repositories have been declared,required flags, default same-name branch requirements, and exception reasons
  • plan.md contains a "Task Checklist (SSOT)", and each task includes: file path, acceptance points, minimum verification method, commit points, and audit information (may be distributed across plan.md and Task Pack task.md , but must be satisfied after merging)
  • If a Task Pack has been created:plan.md contains Task Index(pointing to implementation/tasks/...), and within each pack status.yaml in routing_status / activity_stage / depends_on is consistent with the plan
  • Any uncertain items enter NEEDS CLARIFICATION, andmust not enter I2 before they are eliminated

Keep in mind (high-frequency rules quick reference)

  • Always first execute spec-context to obtain context, get FEATURE_DIR=..., and stop if it fails
  • Always writeExact Path、Exact CommandandExpected Signal
  • Do not write uncertainty as known; uniformly enter NEEDS CLARIFICATION and block I2
  • DRY, YAGNI, TDD, frequent commits (the commit rhythm must also be reflected in the plan;AUTO_COMMIT=false mark the commit step as "skip (AUTO_COMMIT=false)" and instead list the changed file manifest)
  • If this implementation involves sub-repositories: first clearly state the affected sub-repositories and same-name branch requirements in I1; sub-repository branch creation/verification occurs between I1 -> I2

Execution handoff (after writing plan.md)

After saving the plan, this skill no longer decides the "next step/execution method". The unified approach:

  • Announce:{FEATURE_DIR}/implementation/plan.md has been written to disk, and is the Spec-levelorchestration SSOT (if a Task Pack has been initialized, the task-level execution SSOT is in implementation/tasks/*）
  • Note:immediately call using-aidlc to route the next step (usually routes to I2:spec-execute, then to Finish:finishing-development）
  • If the user explicitly requests "use subagent-driven-development for parallel execution in this session", also firstcall using-aidlc to clarify the routing conclusion before starting execution (to avoid having a second routing source)

Output and automatic routing after completion (must be executed)

plan.md Afterhas been written to disk,complete the following actions (in order, none may be omitted):

  1. Output ROUTER_SUMMARY(in YAML form, for Router decision-making):
ROUTER_SUMMARY:
  stage: I1
  artifacts:
    - "{FEATURE_DIR}/implementation/plan.md"
  needs_human_review: false
  blocked: false
  block_reason: ""
  notes: "软检查点：plan.md 建议评审；如不触发硬中断 Router 可继续自动推进"

  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 it can automatically continue: continue executing the next worker skill in the same conversation round (such as I2, Finish, etc.)
    • If the Router triggers a hard interrupt: stop and output the blocking reason, required input, and candidate next steps

  2. Dialogue output: Before calling using-aidlc, you may briefly state, "The artifacts for this stage have been saved; calling using-aidlc to route the next step."