@@ -9,6 +9,145 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
99
1010---
1111
12+ ## [ 0.7.3] - 2025-11-16
13+
14+ ### 📝 Documentation Improvement - SDS "Specification Operations" Clarification
15+
16+ ** Prevents confusion between Specification Operations and Toolkit Commands in domain specs**
17+
18+ This release completes the command generation fix by clarifying the SDS (Spec-Driven Specification) side, preventing users from defining toolkit commands in domain specifications.
19+
20+ ### Context
21+
22+ ** Related to v0.7.2** : v0.7.2 fixed SDD (toolkit generation logic), but the root cause was in SDS where "Specification Operations" was being misused as "Toolkit Commands".
23+
24+ ** Discovery** : Real-world usage revealed that Domain Spec's "Specification Operations" section was being used to define toolkit commands (e.g., ` /marketing.project ` , ` /marketing.campaign ` ), when it should only be used for API/Protocol interface definitions.
25+
26+ ### The Confusion
27+
28+ #### Two Different "Operations" Were Being Mixed:
29+
30+ ** Type 1: Specification Operations** (SDS - Correct Usage) ✅
31+ ``` yaml
32+ # API/Protocol Specification
33+ Operations :
34+ - initialize : Server startup (MCP protocol)
35+ - GET /users : List users (REST API)
36+ - tools/list : Enumerate tools (MCP operation)
37+ ` ` `
38+ - These are **interface definitions** that the specification defines
39+ - Implementers must follow these interfaces
40+ - Only for API/Protocol specifications
41+
42+ **Type 2: Toolkit Commands** (Should be in SDD) ❌
43+ ` ` ` yaml
44+ # Marketing Spec-Kit (Incorrect - was in Domain Spec)
45+ Operations :
46+ - /marketing.project : Access project
47+ - /marketing.campaign : Access campaign
48+ ` ` `
49+ - These are **toolkit commands** for operating data
50+ - Should be defined in Toolkit Spec (SDD), not Domain Spec (SDS)
51+ - Most domains don't need Specification Operations at all
52+
53+ ### Changed
54+
55+ #### ` /metaspec.sds.specify` Command Template
56+
57+ **Added Clear Usage Guidance** (Line 177-196):
58+ - Explicit warning : " This is for API/Protocol specifications that define interfaces"
59+ - Examples : MCP protocol operations, REST API endpoints
60+ - Clear "When to use" vs "When NOT to use" guidance
61+ - Key distinction between Specification Operations (SDS) and Toolkit Commands (SDD)
62+
63+ **Added Output Warnings** (Line 912-917):
64+ ` ` ` markdown
65+ - Specification Operations: {count} API/protocol operations defined
66+ ⚠️ Note: Only for API/Protocol specs (MCP, REST API). Most domains leave this empty.
67+ Toolkit commands should be defined in SDD, not here!
68+ ` ` `
69+
70+ # ## When to Define Specification Operations
71+
72+ **✅ Use when**:
73+ - Your domain IS an API/Protocol specification (MCP, REST API, GraphQL, gRPC)
74+ - You're defining interfaces that implementers must follow
75+ - These are specification-level operations (WHAT interfaces exist)
76+
77+ **❌ Don't use when**:
78+ - Your domain is NOT an API specification (Marketing, E-commerce, CRM, etc.)
79+ - You want to define toolkit commands (use `/metaspec.sdd.specify` instead)
80+ - You're unsure - if confused, leave empty and define commands in SDD
81+
82+ **Key principle**: Most domains don't need Specification Operations. This is specifically for API/Protocol specifications.
83+
84+ # ## Impact
85+
86+ **Before this fix**:
87+ ```
88+ User creates Marketing domain spec
89+ ↓
90+ Defines "Operations": /marketing.project, /marketing.campaign...
91+ ↓
92+ SDD inherits these as commands
93+ ↓
94+ Generates wrong command type ❌
95+ ```
96+
97+ **After this fix**:
98+ ```
99+ User creates Marketing domain spec
100+ ↓
101+ Sees: "Only for API/Protocol specs, most domains leave empty"
102+ ↓
103+ Leaves Operations empty
104+ ↓
105+ SDD independently designs workflow commands ✅
106+ ```
107+
108+ ### Migration Guide
109+
110+ **For existing speckits with misused Specification Operations**:
111+
112+ 1. **Check your domain type**:
113+ ```bash
114+ # Is your domain an API/Protocol spec?
115+ - MCP, REST API, GraphQL → Keep Specification Operations
116+ - Marketing, E-commerce, CRM → Remove/leave empty
117+ ```
118+
119+ 2 . ** If NOT an API spec, clean domain spec** :
120+ ``` bash
121+ # Edit: specs/domain/001-{domain}-spec/spec.md
122+ # Remove or set to empty:
123+ operations: []
124+ ```
125+
126+ 3 . ** Verify toolkit spec has workflow commands** :
127+ ``` bash
128+ # specs/toolkit/001-{name}/spec.md should have:
129+ Commands:
130+ - /domainspec.constitution
131+ - /domainspec.specify
132+ - ...workflow commands (not entity commands)
133+ ```
134+
135+ ### Why This Matters
136+
137+ This fix completes the command generation problem by addressing both sides:
138+ - ** v0.7.2** : Fixed SDD (toolkit generation logic) - prevents generating entity commands
139+ - ** v0.7.3** : Fixed SDS (specification guidance) - prevents defining wrong operations
140+
141+ Together, these ensure speckits follow the correct workflow-guidance pattern from specification to implementation.
142+
143+ ### References
144+
145+ - ** Fix Document** : ` docs/internal/sds-operations-clarification-fix.md `
146+ - ** Related Version** : v0.7.2 (fixed SDD side)
147+ - ** Discovery Source** : Real-world speckit development feedback
148+
149+ ---
150+
12151## [ 0.7.2] - 2025-11-16
13152
14153### 🔧 Critical Bug Fix - SDD Specify Command Generation Logic
0 commit comments