spec-plan（I1: Implementation Plan / plan.md SSOT）

Overview

{FEATURE_DIR}/requirements/*

{FEATURE_DIR}/design/*

{FEATURE_DIR}/implementation/plan.md

When to use / When not to use

• Use cases
  • You need to generate or update

    {FEATURE_DIR}/implementation/plan.md

    (mandatory for I1).
  • You are ready to enter I2 execution, but there is no "checkable + executable" task list currently.
• Do not use when

  • spec-context

    fails and you cannot get

    FEATURE_DIR

    (you must stop at this point).
  • Input side SSOT is insufficient: both

    requirements/solution.md

    and

    requirements/prd.md

    do not exist, and scope/acceptance criteria cannot be traced (you must mark NEEDS CLARIFICATION in plan.md and block entry into I2).

Gate Check / Stop Rules (Strictly Enforced)

spec-context

FEATURE_DIR=...

(reuse)

• FEATURE_DIR

  is not obtained
• Branch/directory is uncertain (you find yourself wanting to "guess the

  .aisdlc/specs/...

  path")
• Both

  requirements/solution.md

  and

  requirements/prd.md

  are missing, making the goal/scope/acceptance criteria untraceable
• Any key uncertainty cannot be evidenced in the input (must be written into

  plan.md/## NEEDS CLARIFICATION

  , and explicitly "block entry into I2")

Input / Output (Persistence Conventions)

• Read (progressive disclosure, minimum necessary)
  • Project level (must read its index or necessary fragments):

    project/memory/*

    ,

    project/contracts/

    ,

    project/adr/

  • 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 invariants to be followed as constraint inputs for I1 (stop and go back to R1 to fill if missing)
  • Spec level (if exists and relevant):

    {FEATURE_DIR}/design/design.md

    ,

    {FEATURE_DIR}/design/research.md

  • .gitmodules

    (if exists; used to identify the static list of submodules that can participate in the implementation)
• Write (only one)

  • {FEATURE_DIR}/implementation/plan.md

Small Task Granularity (Reuse writing-plans)

plan.md

• "Write failure test" (if applicable) - one step
• "Run to ensure it fails" - one step
• "Implement the minimum code that makes the test pass" - one step
• "Run verification to ensure it passes" - one step
• "Commit" (frequent commits) - one step

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

plan.md

Header (Mandatory)

./assets/plan-template.md

# [Requirement Name] Implementation Plan (SSOT)

> **Required Skill:** `spec-execute` (execute this plan in batches)
> **Context Acquisition:** Must first execute `spec-context` to get context and locate `{FEATURE_DIR}`, stop if failed

**Goal:** [One sentence describing what to deliver]
**Scope:** In / Out
**Architecture:** [2-3 sentences describing the method + key constraints]
**Acceptance Criteria:** [Reference AC/acceptance points from requirements/solution.md or requirements/prd.md]
**Impact Scope:** [Reference the list of affected modules from requirements/solution.md#impact-analysis]
**Invariants to Follow:** [Key API/Data contract invariants extracted from requirements/solution.md#impact-analysis]
**Submodule Scope:** [If `.gitmodules` exists, list the submodules involved in this requirement; write "None" if there are none]

---

Plan Body (Mandatory)

• TL;DR: One sentence summarizing the plan goal and scope
• Scope and Boundary: In/Out (aligned with requirements and design)
• 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, mark source module/anchor)
  • Cross-module impact and coordination matters (based on dependency graph/impact analysis)
• Code Workspace List (if applicable, required):
  • Reference affected submodule paths from

    .gitmodules

  • Mark whether each submodule is

    required

  • Default branch requirement: same name as the root project

    CURRENT_BRANCH

  • If there are exceptions, explicitly record

    exception_reason

• Milestones and Rhythm: Phase split, time estimation, deliverable list
• Dependencies and Resources: External system/team/permission/environment/data dependencies
• Risks and Verification: Risk list, verification method, Owner
• Acceptance Criteria: Key AC and acceptor corresponding to PRD/solution
• NEEDS CLARIFICATION (mandatory): Uniformly list unresolved uncertainties (entry to I2 is not allowed before resolution)

Task Structure (Reuse writing-plans, with SSOT/audit/gate check added)

plan.md

- [ ]/- [x]

• Exact file path (create/modify/test)
• Verifiable acceptance points (testable conditions)
• Executable steps (command + expected output/signal)
• Commit points and minimum audit information (record

  branch/commit/pr/changed_files

  by repo)

## Task List (SSOT)

### Task T1: [Task Title]

- [ ] **Status:** Not started / In progress / Completed / Blocked (for blocking, the evidence path must be written)

**Code Repository Scope:**
- Root project:
- Submodule: (if applicable; fill in the path in `.gitmodules` and indicate `required=true/false`)

**Files:**
- Create: `exact/path/to/new.file`
- Modify: `exact/path/to/existing.file` (optional: accurate to paragraph/function)
- Test: `tests/exact/path/to/test.file` (if applicable)

**Acceptance Points:**
- [Verifiable condition 1]
- [Verifiable condition 2]

**Step 1: Write failure test (if applicable)**
- Modification point: `tests/...`
- Run: `[exact command]`
- Expected: FAIL (write the key failure signal you expect to see)

**Step 2: Write minimum implementation**
- Modification point: `path/to/file`

**Step 3: Run verification**
- Run: `[exact command]`
- Expected: PASS (write the key pass signal you expect to see)

**Step 4: Commit (frequent commits; commit message must be in Chinese)**
- Commit message: `[One sentence explaining why (Chinese)]`
- Audit information:
  - repo: `root`
    branch: `{CURRENT_BRANCH}`
    commit: `<TBD>`
    pr: `<TBD>`
    changed_files: `<TBD>`
  - repo: `<submodule path>` (if applicable)
    branch: `{CURRENT_BRANCH}`
    commit: `<TBD>`
    pr: `<TBD>`
    changed_files: `<TBD>`

Command writing convention: Default for PowerShell; use

;

to separate multiple commands on the same line (do not use

&&

).

I1-DoD (Gate Check: No item is missing)

• The plan scope is consistent and traceable with

  {FEATURE_DIR}/requirements/*

  ,

  {FEATURE_DIR}/design/*

• Milestones are clear and acceptable (each item has corresponding deliverables or verifiable standards)
• Dependencies and risks have been listed, and there are minimum verification/mitigation actions (including Owner)
• Key acceptance criteria are traceable (at least reference

  requirements/prd.md

  or

  requirements/solution.md

  )
• Impact scope and constraints have been injected:

  plan.md

  contains the "Impact Scope and Constraints" paragraph, and the affected modules and invariants to be followed have been extracted from

  requirements/solution.md#impact-analysis

  and listed one by one
• If

  .gitmodules

  exists and the impact analysis hits submodules:

  plan.md

  has declared the affected submodules,

  required

  mark, default same-name branch requirement and exception reason
• There is a "Task List (SSOT)" in

  plan.md

  , and each task includes: file path, acceptance point, minimum verification method, commit point and audit information
• Any uncertain items are included in

  NEEDS CLARIFICATION

  , and entry to I2 is not allowed before resolution

Keep in Mind (Quick Reference for High-frequency Rules)

• Always execute

  spec-context

  first to get context, get

  FEATURE_DIR=...

  , stop if failed
• Always write exact path, exact command and expected signal
• Do not write uncertainty as known; uniformly include it in

  NEEDS CLARIFICATION

  and block I2
• DRY, YAGNI, TDD, frequent commits (the commit rhythm should also be reflected in the plan)
• If this implementation involves submodules: first write down the affected submodules and same-name branch requirements in I1; submodule branch creation/verification occurs between I1 -> I2

Execution Handover (After writing plan.md)

• Announce:

  {FEATURE_DIR}/implementation/plan.md

  has been persisted to disk and is the only SSOT on the implementation side
• Tip: Call immediately

  using-aisdlc

  to route the next step (usually routed to I2:

  spec-execute

  , then to Finish:

  finishing-development

  )
• If the user explicitly requires "this session uses subagent-driven-development for parallel execution", you should also call

  using-aisdlc

  to clarify the routing conclusion before starting execution (to avoid a second routing source)

Post-completion Output and Automatic Routing (Mandatory)

plan.md

1. Output ROUTER_SUMMARY (YAML format, for Router decision making):

ROUTER_SUMMARY:
  stage: I1
  artifacts:
    - "{FEATURE_DIR}/implementation/plan.md"
  needs_human_review: false
  blocked: false
  block_reason: ""
  notes: "Soft checkpoint: plan.md is recommended for review; if no hard interrupt is triggered, the Router can continue to advance automatically"

1. Execute

   using-aisdlc

   immediately: Pass the above

   ROUTER_SUMMARY

   as routing input to using-aisdlc, and the Router will determine the next step and advance automatically (no need to wait for the user to say "continue").
   • If the Router determines that it can automatically continue: continue to execute the next worker skill in the same round of conversation (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. Conversation Output: Before calling using-aisdlc, you can briefly state "The product of this stage has been persisted to disk, and using-aisdlc is being called to route the next step."