using-aisdlc (Using AI SDLC / Spec Pack Process in sdlc-dev)

Overview

This is a "Navigation + Guardrail" type Skill: used in the Spec Pack (

{num}-{short-name}

) process of sdlc-dev, this Skill acts as the "only Router" to determine which skill to use next, and uses hard guardrails to prevent context drift and incorrect directory writes.

Announce at the start: "I am using the using-aisdlc skill to navigate the Spec Pack process and perform guardrail checks."

This Skill now covers two main paths:

Demand Path (R0–R4):

raw.md → solution.md → prd.md → prototype.md → demo/

Design Path (D0–D2, can be skipped entirely):

D0 Diversion → (Optional) D1 research → (If not skipped) D2 RFC

Development Path (I1–I2 + Finish):

solution/prd/design → implementation/plan.md → Execute Implementation → finishing-development

Core Principles:

Context first, read/write later: For any read/write operations on
```
{FEATURE_DIR}/requirements/*
```
,
```
{FEATURE_DIR}/design/*
```
,
```
{FEATURE_DIR}/implementation/*
```
(or writing demo in R4) → first run
```
spec-context
```
to get
```
FEATURE_DIR
```
(stop if it fails).
One node = one skill = one persisted artifact: Execute R0/R1/R2/R3/R4 step by step; prohibit "completing PRD + prototype + Demo all at once".
Progressive disclosure: First read project-level
```
memory/
```
and related contract indexes; only read/write
```
{FEATURE_DIR}/requirements/*
```
after clearly handling a specific Spec.
Do not write "to-be-confirmed issue list" for uncertainties: Uniformly enter into a "validation checklist" (Owner/Deadline/Signal/Action).
Closed-loop feedback: Verification findings from R3/R4 will flow back to update R1/R2/R3 (re-run R4 if necessary).
SSOT for implementation phase: During implementation,
```
{FEATURE_DIR}/implementation/plan.md
```
serves as the single source of truth (SSOT) for the execution checklist and status (checkbox + audit information); execution status is only written back to
```
plan.md
```
.

Routing Contract (Only Authority: Next Step Determined Solely by using-aisdlc)

In the Spec Pack scenario of this repository, the judgment of "what to do next/whether to skip/which path to take" can only be made by using-aisdlc.
Other skills (R1/R2/R3/R4/D1/D2/I1/I2/Finish) are worker skills: they only handle guardrails for their phase, persist artifacts, and perform DoD self-checks. They must not:

"Autonomously divert to the next skill" within the skill (e.g., "automatically proceed to X after completion")
Make routing conclusions like "skip/not skip a phase" within the skill (at most perform foolproof checks: stop if preconditions are not met, and prompt to return to using-aisdlc)

Important Supplement: Router allows auto-advance. As the Router, using-aisdlc can execute in series within the same conversation following guardrails:

spec-context → worker skill → (Optional) re-route

.
Worker skills still cannot "decide the next step on their own", but can provide structured artifact and status summaries at the end to facilitate the Router's judgment on whether to continue auto-advancing.

Unified Loop Output: After any worker skill completes, output the following uniformly (both sections are required):

"The artifact for this phase has been persisted. Please return to
```
using-aisdlc
```
for next-step routing (if no manual guardrail is triggered, the Router can continue automatically)."
```
ROUTER_SUMMARY
```
(structured summary for automatic routing; YAML format is recommended with fixed fields, avoid free text):
- ```
stage
```
  : e.g.,
```
R1
```
  /
```
R2
```
  /
```
D2
```
  /
```
I1
```
  /
```
I2
```
  /
```
Finish
```
- ```
artifacts
```
  : array of artifact paths (can be empty)
- ```
needs_human_review
```
  :
```
true|false
```
- ```
blocked
```
  :
```
true|false
```
- ```
block_reason
```
  : string (empty if none)
- ```
notes
```
  : string (can be empty)

Auto-Advance Strategy (Improve Experience and Efficiency)

Goal: Without sacrificing guardrails and SSOT, turn "return to using-aisdlc" from manual operation to default automatic behavior; only stop when user intervention is truly needed.

Trigger Conditions for Auto-Advance (Satisfy Any One)

User explicitly states: "Continue / Next step / Follow recommendation / Auto-advance / Run through the shortest loop / Take me through the process directly"
Current conversation intent is clear and unidirectional: e.g., user says "I want to create PRD/prototype/Demo/implementation plan/start implementation", and all pre-requisite artifacts are complete

ROUTER_SUMMARY

from the previous worker skill marks:

needs_human_review=false

and

blocked=false

Scenarios That Must Stop and Hand Over to the User (Manual Guardrails)

Requires user review and confirmation: The artifact will become the authoritative input for subsequent phases, and the cost of errors is high
- Typical examples:
```
solution.md
```
  (especially
```
#impact-analysis
```
  ),
```
prd.md
```
  ,
```
prototype.md
```
  ,
```
design/design.md
```
  ,
```
implementation/plan.md
```
Better for user to make path choices: Multiple reasonable routes exist, and the Router may choose the wrong one with default strategies alone
- Typical diversion points: Whether to supplement R2/R3/R4; whether to enter implementation (I1/I2); whether to skip design in D0 (if user has not indicated preference)
Missing critical external input: Cannot proceed without it
- Typical examples:
```
spec-context
```
  fails; R4 cannot find
```
DEMO_PROJECT_ROOT
```
  ; worker skill marks
```
blocked=true
```

Exception: If the user explicitly requests "directly develop following the shortest loop and accept default decisions", using-aisdlc can automatically determine whether to skip design in D0 based on the decision table, and automatically enter I1; however, before entering I2 (modifying code), it should still confirm the user's intent is "start implementation" rather than "only produce a plan".

Default Auto-Advance Sequence (When Auto-Advance is Allowed)

Guardrails first: If the next step triggers read/write operations on
```
{FEATURE_DIR}/...
```
or writes demo, first run
```
spec-context
```
and echo
```
FEATURE_DIR=...
```
(stop if it fails)
Then execute: Call the only routed worker skill and complete artifact persistence
Then re-route: Read
```
ROUTER_SUMMARY
```
, continue if auto-advance conditions are met; otherwise output "reason for stopping + minimal action requiring user selection/review"

Routing Input/Output (Conversation-Level Protocol)

Input (Minimum Information Required for Routing): User intent (what to produce/which phase to enter) + current Spec context (must obtain
```
FEATURE_DIR/CURRENT_BRANCH/REPO_ROOT
```
via
```
spec-context
```
).

Decision Basis (Only Recognize SSOT Files and Guardrails):

R0:
```
{FEATURE_DIR}/requirements/raw.md
```

R1:

{FEATURE_DIR}/requirements/solution.md

(must contain

## Impact Analysis

, anchor

#impact-analysis

)

R2:
```
{FEATURE_DIR}/requirements/prd.md
```
R3:
```
{FEATURE_DIR}/requirements/prototype.md
```
D1:
```
{FEATURE_DIR}/design/research.md
```
D2:
```
{FEATURE_DIR}/design/design.md
```
I1:
```
{FEATURE_DIR}/implementation/plan.md
```

Output (Only "Next Step Instruction" Format):
- You are currently in:
```
<Phase>
```
- Next step (only one):
```
<Skill Name>
```
- Must pass first:
```
spec-context → FEATURE_DIR=...
```
  (and hard guardrails of this Skill)
- Will produce:
```
<Persisted Artifact Path>
```

When to Use / Not to Use

Use Cases
- You want to start/continue a Spec: generate or update
```
raw.md / solution.md / prd.md / prototype.md / demo
```
- You want to push a "simple requirement" directly to the development loop:
```
solution.md → plan.md → execute → finishing
```
- You want to decide the design phase route: whether to skip design, whether research is needed, whether RFC (design/design.md) is needed
- You are unsure "which spec-product-* skill to run now"
- You are unsure "whether to run spec-implementation-plan / spec-implementation-execute or first supplement demand inputs"
Do Not Use
- Only discussing concepts, not involving persisted files and directory structures of the Spec Pack in this repository

Only Guardrails (Must Be Followed)

Rule: As long as the task involves reading/writing any of the following, you must first run
spec-context
and echo
FEATURE_DIR=...
:

```
{FEATURE_DIR}/requirements/raw.md
```
```
{FEATURE_DIR}/requirements/solution.md
```
```
{FEATURE_DIR}/requirements/prd.md
```
```
{FEATURE_DIR}/requirements/prototype.md
```

{FEATURE_DIR}/design/*.md

(e.g.,

design/design.md

design/research.md

)

```
{FEATURE_DIR}/implementation/plan.md
```

{REPO_ROOT}/demo/prototypes/{CURRENT_BRANCH}/...

(R4)

This applies even if the user verbally provides
FEATURE_DIR
. (The most common violation in baseline testing: treating "user-provided path" as trusted context.)

Command Writing Convention: Default to PowerShell; use
;
to separate multiple commands on the same line (do not use
&&
).

The Shortest Loop You Need (Simple Requirement Development): raw → solution.md → plan.md → execute → finishing-development

Applicable Premises (Satisfy Any One):

Single scope, clear boundaries, low risk, no need for additional design phase decision documents (can determine to skip design per D0 in
```
design/aisdlc_spec_design.md
```
)
Traceable acceptance criteria: At least can write clear acceptance points in
```
solution.md
```
(or more complete
```
prd.md
```
)

Shortest Loop (Recommended to Run First):

R0: Persist raw (if package not yet created)
- Use:
```
spec-init
```
- Output:
```
{FEATURE_DIR}/requirements/raw.md
```
Guardrail: Locate Spec Context
- Use:
```
spec-context
```
- Requirement: Must echo
```
FEATURE_DIR=...
```
  in the conversation; stop if it fails
R1: raw → solution (Converge on a Solution)
- Use:
```
spec-product-clarify
```
- Output:
```
{FEATURE_DIR}/requirements/solution.md
```
- Artifact Guardrail:
```
solution.md
```
  must contain
```
## Impact Analysis
```
  (anchor
```
#impact-analysis
```
  ), as constrained input for subsequent D2/I1
- Compatibility Note: Users may say
```
solutions.md
```
  , but the SSOT for demand side in this repository is solution.md
  (singular); do not create
```
solutions.md
```
  to avoid dual SSOT
D0: Diversion Judgment (Whether Design Phase is Needed)
- Use:
```
using-aisdlc
```
  (This Skill is responsible for judgment; no persistence or reference to diversion conclusion in subsequent artifacts)
- Conclusion: Skip design → I1; Do not skip → (As needed) D1/D2
I1: solution/prd/design → plan (Write to Executable)
- Use:
```
spec-implementation-plan
```
- Output:
```
{FEATURE_DIR}/implementation/plan.md
```
  (SSOT for execution checklist and status)
I2: Execute in Batches per Plan (Implementation + Write Back Status/Audit)
- Use:
```
spec-implementation-execute
```
- Rule: Execution status is only written back to
```
implementation/plan.md
```
  ; stop when encountering
```
NEEDS CLARIFICATION
```
  / blocked
Finish: Development Completion Confirmation (Verification Only, Complete Only When All Green)
- Use:
```
finishing-development
```
- Output: A "completion confirmation report" (including actually executed commands and results)

Core Workflows (Demand Side R0 → R4; Design Side D0 → (Optional) D1 → (Optional) D2; Implementation Side I1 → I2 → Finish)

dot

digraph aisdlc_flow {
  rankdir=LR;
  node [shape=box];
  "Need to handle a requirement (Spec)" -> "Is there a valid spec branch/Spec Pack?";
  "Is there a valid spec branch/Spec Pack?" [shape=diamond];
  "Is there a valid spec branch/Spec Pack?" -> "R0: spec-init" [label="No / Uncertain"];
  "R0: spec-init" -> "Run spec-context" ;
  "Is there a valid spec branch/Spec Pack?" -> "Run spec-context" [label="Yes"];
  "Run spec-context" -> "Obtain FEATURE_DIR / CURRENT_BRANCH / REPO_ROOT";
  "Obtain FEATURE_DIR / CURRENT_BRANCH / REPO_ROOT" -> "Select demand path R1-R4 (Optional)";
  "Obtain FEATURE_DIR / CURRENT_BRANCH / REPO_ROOT" -> "D0: Skip design?";
  "Select demand path R1-R4 (Optional)" -> "R1: raw->solution (with Impact Analysis)";
  "R1: raw->solution (with Impact Analysis)" -> "R2: solution->prd (Optional)";
  "R2: solution->prd (Optional)" -> "R3: prd->prototype (Optional)";
  "R3: prd->prototype (Optional)" -> "R4: prototype->demo (Optional)";
  "D0: Skip design?" [shape=diamond];
  "D0: Skip design?" -> "I1: spec-implementation-plan" [label="Yes (Skip)"];
  "D0: Skip design?" -> "D1: spec-design-research (Optional)" [label="No, and research needed"];
  "D0: Skip design?" -> "D2: spec-design (RFC)" [label="No, and no research needed"];
  "D1: spec-design-research (Optional)" -> "D2: spec-design (RFC)";
  "R1: raw->solution (with Impact Analysis)" -> "D0: Skip design?";
  "R2: solution->prd (Optional)" -> "D0: Skip design?";
  "R3: prd->prototype (Optional)" -> "D0: Skip design?";
  "D2: spec-design (RFC)" -> "I1: spec-implementation-plan";
  "I1: spec-implementation-plan" -> "I2: spec-implementation-execute";
  "I2: spec-implementation-execute" -> "Finish: finishing-development";
}

D0/D1/D2 Routing Rules (Determined by using-aisdlc)

The caliber and details of the design phase are subject to
design/aisdlc_spec_design.md
; only the executable routing decision table is provided here.

D0: Whether to Skip Design Phase (Only Determined by using-aisdlc)

Consider skipping (satisfy any one to consider): Single scope with clear boundaries / no changes to external commitments (API/events/permissions/data caliber) and no migration rollback / no critical technical uncertainties / acceptance criteria are sufficiently traceable
Default to not skip (hit any one): Changes to external contracts/permissions/calibers, data migration/rollback, high-risk uncertainties, large impact on multiple systems/upstream and downstream, team explicitly requires RFC review

Conclusion:

Skip → Route to
```
spec-implementation-plan
```
(I1), and require supplementing minimal decision information in
```
plan.md
```
Do not skip → Enter D1/D2 diversion

D1: Whether Research is Needed (Only Determined by using-aisdlc)

Route to

spec-design-research

(need D1) if any of the following are hit:

Solution correctness depends on unknown facts (if X is not true, the entire solution will be overturned)
Multiple solutions lack evidence to support trade-offs
High-risk points exist in external contracts/migration/security/performance/consistency that need to be verified first

Otherwise: Directly route to

spec-design

to produce D2 (RFC).

D2: Execute RFC (Worker Skill spec-design Persists Artifact)

When routed to D2,

spec-design

is only responsible for producing/updating:

```
{FEATURE_DIR}/design/design.md
```

And must consume:

solution.md#impact-analysis

+ full text of affected module component pages + full text of related ADRs; must explicitly mark

CONTEXT GAP

if any are missing.

R0: Initialize New Spec Pack

Use:
```
spec-init
```

When: No

{num}-{short-name}

branch and

.aisdlc/specs/{num}-{short-name}/

directory exist yet

Output:
```
{FEATURE_DIR}/requirements/raw.md
```
(UTF-8 with BOM)
After completion: Return to
```
using-aisdlc
```
for next-step routing (usually first
```
spec-context
```
, then enter R1)

R1: Clarification + Solution Decision (raw → solution)

Use:
```
spec-product-clarify
```
Pre-requisite Input:
```
spec-context
```
succeeds;
```
{FEATURE_DIR}/requirements/raw.md
```
exists and is non-empty
Key Discipline: One question at a time (prioritize multiple-choice questions) + incrementally write back to
```
raw.md/## Clarification Records
```
+ stop mechanism
Output:
```
{FEATURE_DIR}/requirements/solution.md
```
Artifact Guardrail:
```
solution.md
```
must contain
```
## Impact Analysis
```
(
```
#impact-analysis
```
), and can be directly referenced by D2/I1/I2
After completion: Return to
```
using-aisdlc
```
for next-step routing (R2/R3/R4/D0→I1/D1/D2 etc., uniformly determined by this Skill)

R2: PRD (solution → prd, Optional)

Use:
```
spec-product-prd
```
Pre-requisite Input:
```
{FEATURE_DIR}/requirements/solution.md
```
must exist
Output:
```
{FEATURE_DIR}/requirements/prd.md
```
After completion: Return to
```
using-aisdlc
```
for next-step routing

R3: Prototype (prd → prototype, Optional)

Use:
```
spec-product-prototype
```
Pre-requisite Input:
```
{FEATURE_DIR}/requirements/prd.md
```
must exist
Output:
```
{FEATURE_DIR}/requirements/prototype.md
```
After completion: Return to
```
using-aisdlc
```
for next-step routing (enter R4 as needed; flow back to R1/R2/R3 if issues are found)

R4: Interactive Demo (prototype → demo, Optional)

Use:
```
spec-product-demo
```
Pre-requisite Input:
```
{FEATURE_DIR}/requirements/prototype.md
```
must exist; Demo project root directory can be located (stop and request
```
DEMO_PROJECT_ROOT
```
if not found)

Output: Default to

{REPO_ROOT}/demo/prototypes/{CURRENT_BRANCH}/

After completion: Return to
```
using-aisdlc
```
for next-step routing (run walkthrough; flow back to update R1/R2/R3/R4 as needed if issues are found)

D1: Research (Optional)

Use:
```
spec-design-research
```
Pre-requisite Input:
```
requirements/solution.md
```
exists and is traceable;
Output:
```
{FEATURE_DIR}/design/research.md
```
After completion: Return to
```
using-aisdlc
```
to route to D2 or return to R1 to revise inputs

D2: Design (RFC / Decision Document; Mandatory if Not Skipped)

Use:
```
spec-design
```
Pre-requisite Input: Must read
```
solution.md#impact-analysis
```
, and read full text of affected module component pages and related ADRs (must write
```
CONTEXT GAP
```
if not readable)
Output:
```
{FEATURE_DIR}/design/design.md
```
After completion: Return to
```
using-aisdlc
```
to route to I1

I1: Implementation Plan (solution/prd/design → plan.md, Mandatory)

Use:
```
spec-implementation-plan
```
Pre-requisite Input:
```
spec-context
```
succeeds; at least one of
```
{FEATURE_DIR}/requirements/solution.md
```
or
```
prd.md
```
exists (otherwise must mark
```
NEEDS CLARIFICATION
```
in
```
plan.md
```
and block entry to I2)
Output:
```
{FEATURE_DIR}/implementation/plan.md
```
(SSOT for execution checklist and status)
After completion: Return to
```
using-aisdlc
```
to route to I2

I2: Execution (Batch Implementation per plan.md and Write Back, Mandatory)

Use:
```
spec-implementation-execute
```
Pre-requisite Input:
```
{FEATURE_DIR}/implementation/plan.md
```
must exist and be executable; return to I1 if it does not exist/is not executable
Output: Code and configuration changes + write back of
```
plan.md
```
checkbox/audit information (only source of status)
After completion: Return to
```
using-aisdlc
```
to route to Finish

Finish: Development Completion Confirmation (Verification Only, Complete Only When All Green)

Use:
```
finishing-development
```
Output: Completion confirmation report (executed commands and results are reproducible)
After completion: Return to
```
using-aisdlc
```
(or end; this Skill does not handle merging/PR/cleanup)

Quick Reference (High-Frequency Lookup)

What You Want to Do	Must Have First	Execute Skill	Main Artifact
Create package for new requirement	Original requirement (text or file)	`spec-init`	`requirements/raw.md`
Converge on solution (with impact analysis)	`raw.md`	`spec-product-clarify`	`requirements/solution.md#impact-analysis`
Freeze delivery specification	`solution.md`	`spec-product-prd`	`requirements/prd.md`
Eliminate interaction ambiguity	`prd.md`	`spec-product-prototype`	`requirements/prototype.md`
High-fidelity walkthrough	`prototype.md` + runnable demo project root directory	`spec-product-demo`	`demo/prototypes/{branch}/`
Design research (Optional)	`solution.md`	`spec-design-research`	`design/research.md`
Produce RFC (if not skipped)	`solution.md#impact-analysis`	`spec-design`	`design/design.md`
Write executable plan (Mandatory)	`solution.md` or `prd.md`	`spec-implementation-plan`	`implementation/plan.md`
Implement per plan (Mandatory)	`implementation/plan.md`	`spec-implementation-execute`	Code changes + `plan.md` write back
Development completion confirmation (Mandatory)	Code implemented + plan tasks completed	`finishing-development`	Completion confirmation report

As long as you read/write
{FEATURE_DIR}/requirements/*
,
{FEATURE_DIR}/design/*
,
{FEATURE_DIR}/implementation/*
, or write demo in R4: first run
spec-context
, stop if it fails.

Red Flag List (Stop and Correct if Any Appears)

Start reading/writing

{FEATURE_DIR}/requirements/*

{FEATURE_DIR}/design/*

{FEATURE_DIR}/implementation/*

(or start R4 demo writing) without running

spec-context

Accept verbal
```
FEATURE_DIR
```
from user and "trust it and skip scripts"
Continue even if
```
spec-context
```
reports an error (e.g., "write a version first" even on main branch)
Generate documents first to catch up on progress, then supplement context/clarify later
When R4 cannot find the runnable demo project root directory, initialize a Vite/Next.js project "in the location you think is appropriate" on your own
Start "directly writing code" without
```
{FEATURE_DIR}/implementation/plan.md
```
(or if the plan is not executable)
Write status/audit information elsewhere (issue/chat record/another file) during execution instead of writing back to
```
implementation/plan.md
```

Common Errors (and How to Fix Them)

Treat "user-provided path/branch name" as context: Still must run
```
spec-context
```
to echo
```
FEATURE_DIR=...
```
; stop if it cannot be executed.
Generate first, then clarify/supplement evidence later: First complete the R1 clarification loop (one question at a time + write back), then generate artifacts after meeting DoD.
Skip levels: Write
```
prd.md
```
without
```
solution.md
```
, write
```
prototype.md
```
without
```
prd.md
```
, make demo without
```
prototype.md
```
→ stop and return to the previous step in all cases.
Skip levels in development: Start implementation without
```
implementation/plan.md
```
→ return to I1 to write until "executable + verifiable + auditable", then enter I2.

Common Excuses and Countermeasures (From Baseline Testing)

Excuse (Source of Pressure)	Common Violations	Mandatory Countermeasures
"I already told you the FEATURE_DIR, don't run the script"	Accept verbal path and write files directly	Still must run `spec-context` ; stop if it cannot be executed, only deliver "blocking reason + required input/next step"
"I'm in a hurry, write solution.md on main first"	Skip guardrails, guess directory to write	`spec-context` fails → Stop; switch to a valid spec branch first or run `spec-init` first
"Do PRD/prototype/Demo all at once"	Node coupling leads to drift, cannot flow back	Split into R1→R2→R3→R4; provide next step and DoD self-check after each step
"Don't write the plan, directly modify the code"	Skip I1, execution is not auditable, easy to go out of bounds	First use `spec-implementation-plan` to produce `implementation/plan.md` (SSOT), then use `spec-implementation-execute` for batch execution and write back

A Good Example (Correct Opening for the Shortest Path)

User: "I want to work on a new requirement, first create a solution (solution.md), I don't want to find the directory myself."

Correct Approach (First Round):

If no spec branch/Spec Pack has been created yet → first run
```
spec-init
```
(persist the original requirement to
```
raw.md
```
)
Then execute
```
spec-context
```
and echo
```
FEATURE_DIR=...
```
Enter R1: Ask the user only 1 highest-leverage multiple-choice question; incrementally write back to
```
raw.md/## Clarification Records
```
after receiving the answer
After meeting DoD or triggering the stop mechanism, generate
```
solution.md
```
, and provide the next step:
- Simple requirement for development: I1
```
spec-implementation-plan
```
  → I2
```
spec-implementation-execute
```
  →
```
finishing-development
```
- Need more complete specification/prototype: Enter I1/I2 only after R2/R3/R4 (as needed)

using-aisdlc

NPX Install

Tags

SKILL.md Content (Chinese)