docs: clarify SDS workflow - distinguish core vs optional commands

Aligned with GitHub spec-kit pattern (specify→plan→tasks→implement):

Changes:
1. AGENTS.md - Added two SDS workflow paths:
   - Path 1: Simple (2 core + 2 recommended) - for single specification
   - Path 2: Complex (5 core + 2 recommended) - for splitting needed
   - Clearly marked optional commands (clarify)

2. README.md - Updated command listings:
   - Added workflow annotations (Simple/Complex paths)
   - Marked required/recommended/optional commands
   - Added ⭐ markers for complex-path-only commands (plan/tasks/implement)

3. .metaspec/README.md.j2 template:
   - Added Simple Path and Complex Path examples
   - Clear progression from simple to complex

Key improvements:
- ✅ Distinguishes core flow vs quality assurance vs on-demand
- ✅ Shows when to use plan/tasks/implement (complex specs only)
- ✅ Aligns with spec-kit best practices
- ✅ Reduces confusion about "must use all 8 commands"

Reference: https://github.com/github/spec-kit (specify→plan→tasks→implement)

Author: NeilJo-GY

AGENTS.md

@@ -546,16 +546,44 @@ examples/
 
 #### MetaSpec Workflow for SDS + SDD
 
+**SDS has two workflow paths** (like [GitHub spec-kit](https://github.com/github/spec-kit)):
+
+**Path 1: Simple Specification** (Recommended starting point)
+- Use when: Single specification document, no need to split
+
 ```bash
-# Phase 1: Domain Specification (SDS)
-/metaspec.sds.constitution  # Define specification design principles
-/metaspec.sds.specify       # Create specs/domain/001-{domain}-specification/spec.md
-/metaspec.sds.clarify       # Resolve specification ambiguities
-/metaspec.sds.plan          # Plan specification architecture (if complex)
-/metaspec.sds.tasks         # Break down specification work
-/metaspec.sds.implement     # Write specification documents
-/metaspec.sds.checklist     # Generate quality checklist for specification
-/metaspec.sds.analyze       # Check specification consistency
+# Core Flow (Required)
+/metaspec.sds.constitution  # 1. Define specification design principles
+/metaspec.sds.specify       # 2. Create specs/domain/001-{domain}-specification/spec.md
+
+# Quality Assurance (Recommended)
+/metaspec.sds.checklist     # 3. Generate quality checklist
+/metaspec.sds.analyze       # 4. Check specification consistency
+
+# On-Demand Optimization (Optional)
+/metaspec.sds.clarify       # Resolve ambiguities (if issues found)
+```
+
+**Path 2: Complex Specification** (Needs splitting)
+- Use when: Large specification requiring multiple sub-specifications
+
+```bash
+# Core Flow (Required)
+/metaspec.sds.constitution  # 1. Define specification design principles
+/metaspec.sds.specify       # 2. Create root specification
+/metaspec.sds.plan          # 3. Plan sub-specification architecture ⭐
+/metaspec.sds.tasks         # 4. Break down specification tasks ⭐
+/metaspec.sds.implement     # 5. Implement sub-specifications ⭐
+
+# Quality Assurance (Recommended)
+/metaspec.sds.checklist     # 6. Generate quality checklist
+/metaspec.sds.analyze       # 7. Check specification consistency
+
+# On-Demand Optimization (Optional)
+/metaspec.sds.clarify       # Resolve ambiguities (any stage)
+```
+
+📌 **How to choose**: Start with Path 1. If `/metaspec.sds.specify` output shows complexity, run `/metaspec.sds.plan` to decide if splitting is needed. If yes, switch to Path 2.
 
 # Phase 2: Toolkit Specification (SDD)
 /metaspec.sdd.constitution  # Define toolkit principles
@@ -605,21 +633,39 @@ examples/
 
 ### Practical Examples
 
-**Example 1: Starting a new speckit**
+**Example 1: Starting a new speckit (Simple Specification)**
 ```bash
 cd my-speckit
-# Phase 1: Define specification
+# Phase 1: Define specification (Simple Path)
 /metaspec.sds.constitution  # Define specification design principles
-/metaspec.sds.specify "Define domain specification"  # Specification entities
-/metaspec.sds.checklist  # Generate quality checklist
-/metaspec.sds.analyze  # Check specification consistency
+/metaspec.sds.specify "Define domain specification"  # Create specification
+/metaspec.sds.checklist  # Quality check (recommended)
+/metaspec.sds.analyze  # Consistency check (recommended)
 
 # Phase 2: Design toolkit
 /metaspec.sdd.constitution  # Define toolkit principles
 /metaspec.sdd.specify "Define parser and validator"  # Toolkit spec
 /metaspec.sdd.plan  # Architecture design
 ```
 
+**Example 1b: Complex Specification (Needs Splitting)**
+```bash
+cd my-speckit
+# Phase 1: Define specification (Complex Path)
+/metaspec.sds.constitution  # Define specification design principles
+/metaspec.sds.specify "Define MCP specification"  # Create root specification
+/metaspec.sds.plan  # Plan sub-specification architecture
+/metaspec.sds.tasks  # Break down specification tasks
+/metaspec.sds.implement  # Implement sub-specifications
+/metaspec.sds.checklist  # Quality check (recommended)
+/metaspec.sds.analyze  # Consistency check (recommended)
+
+# Phase 2: Design toolkit (same as simple path)
+/metaspec.sdd.constitution
+/metaspec.sdd.specify "Define parser and validator"
+/metaspec.sdd.plan
+```
+
 **Example 2: Iterating on specification**
 ```bash
 # Make changes to specs/domain/001-*/spec.md

README.md

@@ -280,14 +280,19 @@ metaspec init my-spec-kit
 cd my-spec-kit
 
 # SDS Commands (8) - Define domain specification
-# /metaspec.sds.constitution - Define specification design principles
-# /metaspec.sds.specify      - Define specification entities and operations
-# /metaspec.sds.clarify      - Resolve specification ambiguities
-# /metaspec.sds.plan         - Plan specification architecture and sub-specifications
-# /metaspec.sds.tasks        - Break down specification work
-# /metaspec.sds.implement    - Write specification documents
-# /metaspec.sds.checklist    - Generate quality checklist for specification
-# /metaspec.sds.analyze      - Check specification consistency
+# 
+# Core Flow (2-5 commands depending on complexity):
+#   Simple: constitution → specify → [checklist] → [analyze]
+#   Complex: constitution → specify → plan → tasks → implement → [checklist] → [analyze]
+#
+# /metaspec.sds.constitution - Define specification design principles (required)
+# /metaspec.sds.specify      - Define specification entities and operations (required)
+# /metaspec.sds.plan         - Plan specification architecture (if complex) ⭐
+# /metaspec.sds.tasks        - Break down specification work (if complex) ⭐
+# /metaspec.sds.implement    - Write specification documents (if complex) ⭐
+# /metaspec.sds.checklist    - Generate quality checklist (recommended)
+# /metaspec.sds.analyze      - Check specification consistency (recommended)
+# /metaspec.sds.clarify      - Resolve specification ambiguities (optional, on-demand)
 
 # SDD Commands (8) - Develop spec-driven toolkit
 # /metaspec.sdd.constitution - Define toolkit principles
@@ -372,25 +377,40 @@ cd my-spec-kit
 pip install -e .
 
 # Step 4: Use built-in MetaSpec commands for AI-assisted development
+#
 # Phase 1: Define domain specification (SDS - 8 commands)
+#   Simple Path: constitution → specify → [checklist] → [analyze]
+#   Complex Path: constitution → specify → plan → tasks → implement → [checklist] → [analyze]
+#
+# Core (required):
 # /metaspec.sds.constitution  - Define specification design principles
 # /metaspec.sds.specify       - Define specification entities
-# /metaspec.sds.clarify       - Resolve specification ambiguities
-# /metaspec.sds.plan          - Plan specification architecture
-# /metaspec.sds.tasks         - Break down specification work
-# /metaspec.sds.implement     - Write specification documents
+#
+# If complex (splitting needed):
+# /metaspec.sds.plan          - Plan specification architecture ⭐
+# /metaspec.sds.tasks         - Break down specification work ⭐
+# /metaspec.sds.implement     - Write specification documents ⭐
+#
+# Quality (recommended):
 # /metaspec.sds.checklist     - Generate quality checklist
 # /metaspec.sds.analyze       - Check specification consistency
+#
+# On-demand (optional):
+# /metaspec.sds.clarify       - Resolve specification ambiguities
 
 # Phase 2: Develop toolkit (SDD - 8 commands)
+#   Core: constitution → specify → plan → tasks → implement
+#   Quality: checklist → analyze
+#   On-demand: clarify
+#
 # /metaspec.sdd.constitution  - Define toolkit principles
 # /metaspec.sdd.specify       - Define toolkit specifications
-# /metaspec.sdd.clarify       - Resolve toolkit ambiguities
 # /metaspec.sdd.plan          - Plan implementation architecture
 # /metaspec.sdd.tasks         - Break down implementation work
 # /metaspec.sdd.implement     - Build your speckit
-# /metaspec.sdd.checklist     - Validate quality
-# /metaspec.sdd.analyze       - Check consistency
+# /metaspec.sdd.checklist     - Validate quality (recommended)
+# /metaspec.sdd.analyze       - Check consistency (recommended)
+# /metaspec.sdd.clarify       - Resolve toolkit ambiguities (optional)
 
 # Step 5: Share with community
 metaspec contribute my-spec-kit

src/metaspec/templates/base/.metaspec/README.md.j2

@@ -66,18 +66,35 @@ Manage specification changes:
 
 ### Phase 1: Define Specification (SDS)
 
+**Simple Path** (Recommended starting point):
+
 ```bash
-# Step 1: Define specification principles
-/metaspec.sds.constitution
+# Core Flow
+/metaspec.sds.constitution  # 1. Define specification principles
+/metaspec.sds.specify       # 2. Define specification entities
+
+# Quality Assurance (Recommended)
+/metaspec.sds.checklist     # 3. Generate quality checklist
+/metaspec.sds.analyze       # 4. Check consistency
+```
 
-# Step 2: Define specification entities
-/metaspec.sds.specify
+**Complex Path** (If splitting needed):
 
-# Step 3: Validate specification quality
-/metaspec.sds.checklist
-/metaspec.sds.analyze
+```bash
+# Core Flow
+/metaspec.sds.constitution  # 1. Define specification principles
+/metaspec.sds.specify       # 2. Define root specification
+/metaspec.sds.plan          # 3. Plan sub-specification architecture
+/metaspec.sds.tasks         # 4. Break down specification tasks
+/metaspec.sds.implement     # 5. Implement sub-specifications
+
+# Quality Assurance (Recommended)
+/metaspec.sds.checklist     # 6. Generate quality checklist
+/metaspec.sds.analyze       # 7. Check consistency
 ```
 
+**On-Demand**: Use `/metaspec.sds.clarify` to resolve ambiguities at any stage.
+
 **Output**: `specs/domain/001-{domain}-spec/spec.md`
 
 ### Phase 2: Design Toolkit (SDD)