Conversational SDD Guidance

/opsx:*

What is SDD (Specification-Driven Development)

• Reach consensus first — Humans and AI reach an agreement on "what to do, how to do it, and how to accept" before writing code
• Change equals folder — Each change is packaged as a set of artifacts (proposal/specs/design/tasks)
• Increment first — Describe changes with incremental specifications, adapted to iterations of existing systems
• Traceable — Each change has a complete closed loop of intent → solution → acceptance → archiving

OpenSpec Core Concepts

openspec/changes/<name>/

spec-driven

OpenSpec Directory Structure

项目根目录/
├── openspec/
│   ├── config.yaml                 # 项目配置（schema、context、rules）
│   ├── changes/                    # 变更工作区
│   │   ├── <change-name>/
│   │   │   ├── proposal.md         # 变更意图（为什么做、做什么）
│   │   │   ├── specs/              # 增量需求规格
│   │   │   │   └── <capability>/
│   │   │   │       └── spec.md     # 具体能力的需求和场景
│   │   │   ├── design.md           # 技术设计（怎么做）
│   │   │   └── tasks.md            # 实现任务清单
│   │   └── archive/                # 已归档的变更
│   └── specs/                      # 主规格（系统行为真相源）
│       └── <domain>/
│           └── spec.md

Artifact Dependency (spec-driven mode)

                    proposal
                   （根节点）
                       │
         ┌─────────────┴─────────────┐
         │                           │
         ▼                           ▼
      specs                       design
   （依赖:                      （依赖:
    proposal）                   proposal）
         │                           │
         └─────────────┬─────────────┘
                       │
                       ▼
                    tasks
                 （依赖:
                specs, design）

OpenSpec CLI Core Commands

openspec new change "<name>"

openspec/changes/<name>/

openspec status --change "<name>" --json

openspec instructions <artifact> --change "<name>" --json

openspec list --json

openspec archive "<name>"

⛔ Iron Rule: Documentation First, Coding Later

• ❌ Do not start writing code during the proposal stage
• ❌ Do not start writing code during the specification stage
• ❌ Do not start writing code during the design stage
• ❌ Do not start writing code during the task stage
• ❌ Do not skip the documentation stage and implement functions directly
• ✅ Only when proposal.md, specs/, design.md, tasks.md are all created, and the user confirms to enter the implementation stage, you can start writing application code

⛔ Iron Rule: All Artifact Documents Must Be Written in Chinese

• Document titles, body descriptions, requirement descriptions, scenario descriptions, etc. are all in Chinese
• Proprietary technical terms (such as API names, variable names, command lines, etc.) can remain in English as they are
• Document structure tags (such as

  ## 新增需求

  ,

  ### 需求：xxx

  ,

  #### 场景：xxx

  ) use Chinese

Core Principles

1. Documentation first, coding later — Complete the specification document first, and code only after reaching a consensus. This is the most important principle, with priority over everything else
2. Artifact documents must be in Chinese — All openspec artifact documents must be written in Chinese, no English allowed
3. Conversation driven — Users only need to chat, AI actively guides the process, no manual command input required
4. Confirmation per stage — Confirm the direction with the user before each SDD stage to ensure consensus
5. Flexible progression — Support rollback, skipping, mid-term adjustment, no mandatory linear progression
6. Code base based — Research based on the actual code base, no unfounded assumptions
7. Deepen as needed — Adjust the process depth according to the complexity of requirements

Trigger and Intent Recognition

When to Activate

• "I want to develop a XX feature"
• "Help me make a XX"
• "Need to add XX capability"
• "Let's do XX"
• "There is a requirement to develop"
• Any expression describing features, fixes, enhancements or new capabilities

Initial Assessment

1. Check if openspec is initialized
   bash

   ls openspec/config.yaml

   If not initialized, inform the user and recommend running

   openspec init

   .
2. Check for active changes
   bash

   openspec list --json

   If there are active changes, ask the user:
   • Do you want to continue an existing change?
   • Or do you want to start a new change?
3. Assess complexity and determine process depth

   Complexity	Characteristics	Suggested Process
   Simple	Bug fixes, small adjustments, single file	Proposal → Tasks → Implementation → Archiving
   Medium	New features, multi-file changes	Proposal → Specifications → Design → Tasks → Implementation → Archiving
   Complex	Architectural changes, cross-domain	Exploration → Proposal → Specifications → Design → Tasks → Implementation → Verification → Archiving

   Show the assessment result to the user:

   "According to your description, this looks like a [simple/medium/complex] change. I recommend proceeding with the following process: [process list]. Do you think this is okay?"

   Let the user adjust the plan.

Stage Process

  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
  │  探索    │───►│  提案    │───►│  规格    │───►│  设计    │
  │ Explore  │    │ Propose  │    │  Specs   │    │  Design  │
  └──────────┘    └──────────┘    └──────────┘    └──────────┘
                                                       │
  ┌──────────┐    ┌──────────┐    ┌──────────┐         │
  │  归档    │◄───│  验证    │◄───│  实现    │◄───┌────┘
  │ Archive  │    │  Verify  │    │  Apply   │    │
  └──────────┘    └──────────┘    └──────────┘    ▼
                                              ┌──────────┐
                                              │  任务    │
                                              │  Tasks   │
                                              └──────────┘

1. Inform — Inform the user which stage is about to start and its purpose
2. Discuss — Discuss key information of this stage with the user
3. Confirm — Execute after confirming the direction
4. Execute — Call openspec CLI to generate artifacts
5. Summarize — Show the artifact summary and guide to the next stage

Stage 1: Exploration

Purpose: Help users sort out ideas, research the problem space, and clarify requirement boundaries

1. Ask open-ended questions to understand the problem:
   • "What is the core problem you are encountering?"
   • "What should it look like in an ideal state?"
   • "Are there any reference solutions?"
2. Research the code base (if needed):
   • Search for relevant code, patterns, existing implementations
   • Sort out the current architecture related to the discussion
   • Use ASCII charts to visualize findings
3. Explore solutions and trade-offs:
   • If there are multiple solutions, list the comparison
   • Build a comparison table
   • Highlight risks and unknowns
4. Transition: When the idea is clear, summarize the findings and ask:

   "The requirements are now relatively clear. To summarize: [key points]. We can enter the proposal stage, do you want me to create a change?"

Stage 2: Proposal

Purpose: Create a change and write proposal.md, clarify why to do it / what to do / scope

1. Derive the change name from the user's description:
   • Convert to kebab-case (for example: "用户关系查询" →

     user-relation-query

     )
   • Confirm with the user: "I suggest the change name is

     <name>

     , is that okay?"
2. Create change:
   bash

   openspec new change "<name>"

3. Get proposal guidance:
   bash

   openspec instructions proposal --change "<name>" --json

4. Discuss proposal content with the user: Ask about the following aspects:
   • Intent: Why do this change? What problem does it solve?
   • Scope: What is included? What is not included?
   • Method: Preliminary technical ideas?
   • Impact: Which modules/users are affected?
5. Create proposal.md based on discussion and guidance template (content must be in Chinese)
6. Show summary and confirm:

   "The proposal has been created. Core content: [summary]. After confirming there are no problems, shall we enter the requirement specification stage?"

• The

  context

  and

  rules

  returned by instructions are constraint information for AI, not file content
• Do not copy

  <context>

  ,

  <rules>

  ,

  <project_context>

  blocks into artifact files
• ⛔ Do not write any application code in this stage, only produce proposal.md document

Stage 3: Specifications

Purpose: Create incremental specifications, define requirements, scenarios and acceptance criteria

1. Check status and get guidance:
   bash

   openspec status --change "<name>" --json
   openspec instructions specs --change "<name>" --json

2. Read proposal.md to get context
3. Discuss specifications with the user:
   • Identify capability modules from the proposal
   • For each capability, discuss:
     • What are the requirements (using RFC 2119 keywords: MUST/SHOULD/MAY)?
     • What are the scenarios (preconditions/operations/expected results)?
     • What are the boundary cases?
     • What are the exception cases?
4. Create incremental specification files under

   specs/<capability>/spec.md

   (content must be in Chinese):
   • Use

     ## 新增需求

     to describe new behaviors
   • Use

     ## 修改需求

     to describe changed behaviors
   • Use

     ## 移除需求

     to describe deprecated behaviors
5. Show summary and confirm:

   "The requirement specifications have been created, with a total of N capabilities and M scenarios. Do you want me to go through them one by one for confirmation? After confirmation, we will enter the technical design stage."

# <能力名称> 增量规格

## 新增需求

### 需求：<名称>
系统必须/应当/可以 <行为描述>。

#### 场景：<名称>
- 前置条件：<前置条件>
- 当：<操作>
- 则：<预期结果>
- 且：<补充预期>

Stage 4: Design

Purpose: Create design.md, record technical solutions and architectural decisions

1. Get design guidance:
   bash

   openspec instructions design --change "<name>" --json

2. Read proposal and specifications to get context
3. Research the code base: Search for relevant patterns, dependencies, integration points
4. Discuss technical solutions with the user:
   • Architectural decisions and reasons
   • Data flow and component interaction
   • Files that need to be changed
   • Risks and countermeasures
5. Create design.md based on discussion and template (content must be in Chinese)
6. Show summary and confirm:

   "The technical design is completed. Core solution: [summary]. After confirmation, shall we enter the task splitting stage?"

Stage 5: Tasks

Purpose: Create tasks.md, split the implementation into an executable task list

1. Get task guidance:
   bash

   openspec instructions tasks --change "<name>" --json

2. Read all pre-artifacts (proposal, specifications, design) to get context
3. Create tasks.md (content must be in Chinese), including a task list with checkboxes:
   • Group by category
   • Use hierarchical numbering (1.1, 1.2, etc.)
   • Each task has moderate granularity, can be completed in one focused session
   • Include verification steps
4. Show task list and confirm with the user:

   "The tasks have been split into N groups with a total of M tasks. Please confirm the task list: [task summary]. Start implementation after confirmation?"

# 任务清单

## 1. <分组名称>
- [ ] 1.1 <任务描述>
- [ ] 1.2 <任务描述>

## 2. <分组名称>
- [ ] 2.1 <任务描述>

Stage 6: Implementation (Coding)

Purpose: Code and implement step by step according to the task list

• proposal.md has been created and confirmed by the user
• Requirement specifications under the specs/ directory have been created and confirmed by the user
• design.md has been created and confirmed by the user (unless the user explicitly agrees to skip)
• tasks.md has been created and confirmed by the user
• The user has explicitly agreed to enter the coding implementation stage

1. Verify entry conditions: Run

   openspec status --change "<name>" --json

   to confirm that all required artifacts exist
2. Get implementation guidance:
   bash

   openspec instructions apply --change "<name>" --json

3. Read all context files (from the implementation guidance output)
4. Complete pending tasks one by one: a. Inform which task is currently being processed b. Implement code changes c. Mark the task as completed:

   - [ ]

   →

   - [x]

   d. Brief the user on the completion status e. Ask: "Continue to the next task?" (for important tasks)
5. Pause conditions:
   • Unclear task → Ask the user for clarification
   • Design problems found during implementation → Suggest updating artifacts, seek user opinions
   • Encounter errors or blockages → Report and wait for guidance
6. When all completed:

   "All N tasks are completed! Next, we can verify to confirm the consistency between the implementation and the specifications. Do you want to start verification?"

## 正在实现: <change-name>

正在处理任务 3/7: <任务描述>
[...实现过程...]
✓ 任务完成

正在处理任务 4/7: <任务描述>
[...实现过程...]
✓ 任务完成

Stage 7: Verification

Purpose: Verify the consistency between implementation and artifacts

1. Read all artifacts (proposal, specifications, design, tasks)
2. Verify from three dimensions:

   Dimension	Check content
   Completeness	Are all tasks completed? Are all requirements implemented? Are all scenarios covered?
   Correctness	Does the implementation conform to the intent of the specifications? Are boundary cases handled?
   Consistency	Are design decisions reflected in the code? Are patterns consistent?

3. Problem classification:
   • Severe: Must be fixed before archiving
   • Warning: Should be fixed, but can be archived first
   • Suggestion: Improvement and optimization suggestions
4. Show verification report:

   ## 验证报告: <change-name>
   
   完整性: ✓ 12/12 任务已完成
   正确性: ✓ 所有需求已匹配
   一致性: ⚠ 1 个警告
   
   严重: 0 | 警告: 1 | 建议: 2
   可以归档: 是（有警告）

5. If problems are found: Assist in fixing, then re-verify
6. When verification passes:

   "Verification passed! All implementations are consistent with the specifications. Archiving can be done, do you want to start?"

Stage 8: Archiving

Purpose: Archive changes, merge incremental specifications into the main specification

1. Confirm with the user:

   "About to archive

   <name>

   . This will merge the incremental specifications into the main specification and move the change to archive. Confirm archiving?"

2. Show upcoming operations:
   • Incremental specifications → Merge to

     openspec/specs/

   • Change directory → Move to

     openspec/changes/archive/<date>-<name>/

3. Execute archiving:
   bash

   openspec archive "<name>"

4. Final summary:

   ## 归档完成
   
   **变更名称**: <name>
   **归档位置**: openspec/changes/archive/<date>-<name>/
   **已更新规格**: openspec/specs/<capability>/spec.md
   
   恭喜！这个变更已完整走完 SDD 流程。
   如果有新的需求，随时告诉我。

Process Control

Skip Stages

• Exploration: Can be skipped when requirements are already clear
• Design: Can be skipped when the implementation solution is simple and direct
• Verification: Not recommended to skip, but possible for minimal changes

Rollback and Modification

1. Inform: "Found that [design/requirement/solution] needs adjustment"
2. Go back to the corresponding stage
3. Update artifacts
4. Continue from the interruption point

"Found that the solution in design.md needs adjustment during implementation. Let me update the technical design before continuing the implementation."

Resume Progress

1. Run

   openspec list --json

   to find active changes
2. Run

   openspec status --change "<name>" --json

   to check progress
3. Summarize current status:

   "Detected that you have an ongoing change

   <name>

   , current progress: [status]. Do you want to continue?"

4. Resume from the appropriate stage

Interaction Guide

Stage Transition Template

---
## [Stage Name] Stage Completed

### Achievements of this stage
- [List key outputs]

### Next step: [Next Stage Name]
[Brief description of what to do in the next stage]

Are you ready? Or is there anything you want to adjust?
---

When the user goes off-topic

1. Answer the user's question
2. Gently remind: "We still have an ongoing change

   <name>

   , do you want to continue?"

When the user wants to give up

1. Confirm: "Are you sure you want to pause

   <name>

   ? Progress will be saved, you can continue at any time."
2. Do not archive unfinished changes

Security Constraints

• ⛔ Before all document artifacts are completed and confirmed, never write application code — This is the first iron rule of SDD
• ⛔ All artifact documents (proposal.md, spec.md, design.md, tasks.md) must be written in Chinese — No matter what language the instructions template is, the generated document content must be in Chinese
• Before creating artifacts or implementing code each time, you must first obtain user confirmation
• Do not write

  context

  /

  rules

  from instructions into artifact files — Those are just constraint information for AI
• Always use openspec CLI to query status, get guidance, perform archiving
• Before creating new artifacts, always read their dependent artifacts first
• Keep changes focused — Each change only contains one logical unit of work
• Pause when unsure — Better to ask the user than to guess
• Follow pattern constraints — Act according to the artifact dependency graph in openspec status
• Track progress — Use TodoWrite tool to maintain user-visible progress
• Strictly follow the stage order — Exploration → Proposal → Specifications → Design → Tasks → Implementation → Verification → Archiving. Only the implementation stage allows writing application code