Skip to content

Commit c4d4f15

Browse files
NeilJo-GYNeilJo-GY
committed
feat(v0.8.0): Workflow Completeness Enhancement
- Clarify two types of workflows (Entity State Machines vs Specification Usage Workflow) - Update all examples to use MetaSpec's own SDS/SDD workflows - Enhance Constitution Part II with Workflow Completeness principle - Update SDS/SDD specify commands with Type 2 workflow guidance - Eliminate project-specific examples (SDM, marketing) Key Changes: - constitution.md.j2: Added Type 2 Specification Usage Workflow (REQUIRED for all speckits) - specify.md.j2 (SDS): Replaced SDM examples with MetaSpec SDS Workflow (8 steps) - specify.md.j2 (SDD): Added guidance to check Domain Spec for workflows first - domain-spec-template.md.j2: Updated Key Distinction to use MetaSpec examples - AGENTS.md: Added clear distinction between two workflow types - memory/constitution.md: Restructured into three parts (I, II, III) BREAKING CHANGE: Constitution now requires Type 2 Specification Usage Workflow for all speckits Based on community feedback from speckit development
1 parent 67c3c15 commit c4d4f15

File tree

7 files changed

+800
-46
lines changed

7 files changed

+800
-46
lines changed

‎AGENTS.md‎

Lines changed: 89 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,50 @@ memory/constitution.md
124124

125125
**CRITICAL NEW PRINCIPLE** (v0.7.0+): MetaSpec now requires **workflow-first design** for all domain specifications.
126126

127+
### Two Types of Workflows ⭐ UPDATED v0.8.0
128+
129+
**IMPORTANT**: There are TWO types of workflows in specifications. Understanding the distinction is critical.
130+
131+
#### Type 1: Entity State Machines (Business Execution)
132+
133+
**What**: Lifecycle of individual entities during business operations
134+
**Example**: Order (pending → confirmed → shipped → delivered)
135+
**Used by**: Business logic, domain operations
136+
**Defines**: Status field transitions, business rules
137+
138+
```yaml
139+
Order Entity:
140+
status: [pending, confirmed, shipped, delivered]
141+
transitions:
142+
- pending → confirmed (when: payment verified)
143+
- confirmed → shipped (when: items packed)
144+
- shipped → delivered (when: customer receives)
145+
```
146+
147+
#### Type 2: Specification Usage Workflow (Specification Creation) ⭐ NEW
148+
149+
**What**: End-to-end process of creating and using the specification itself
150+
**Example**: SDS Workflow (Constitution → Specify → Clarify → ... → Implement)
151+
**Used by**: Users creating specifications, AI agents
152+
**Defines**: Action steps, slash commands, quality gates
153+
154+
```yaml
155+
SDS Workflow:
156+
Step 1: Constitution → /metaspec.sds.constitution
157+
Step 2: Specify → /metaspec.sds.specify
158+
Step 3: Clarify → /metaspec.sds.clarify
159+
...
160+
Step 8: Implement → /metaspec.sds.implement
161+
```
162+
163+
**Key Distinction**:
164+
- **Type 1**: How entities change during business execution (WHAT happens)
165+
- **Type 2**: How to create/use/validate the specification (HOW to use speckit)
166+
167+
**Most speckits need BOTH**:
168+
- Type 1: Define entity lifecycles (if domain has stateful entities)
169+
- Type 2: **Required for all Speckits** - Define specification creation workflow
170+
127171
### Why Workflow Matters
128172
129173
❌ **Don't build**: "Tool箱" (collection of isolated operations)
@@ -134,11 +178,12 @@ memory/constitution.md
134178
**Before v0.7.0**: Developers could create speckits that passed all quality checks but lacked clear user workflows. Users received "13 commands" without knowing which to use first, or how they relate.
135179
136180
**After v0.7.0**: All domain specifications MUST define:
137-
1. **Workflow Phases** - Distinct stages in the user journey
181+
1. **Workflow Phases** - Distinct stages in the user journey (Type 2)
138182
2. **Phase Purposes** - Why each phase exists
139183
3. **Operation Mapping** - Which operations belong to which phase
140184
4. **Sequencing** - Entry/exit criteria, dependencies, ordering
141185
5. **End-to-End Examples** - Complete workflow demonstrations
186+
6. **Entity State Machines** - If domain has stateful entities (Type 1)
142187
143188
### MetaSpec as Example
144189
@@ -199,38 +244,63 @@ The new **Part II Principle 7: Workflow Completeness** ensures:
199244

200245
### Examples
201246

202-
**Good Workflow-Driven Design**:
247+
**Good Workflow-Driven Design** (Type 2: Specification Usage Workflow):
203248
```
204-
Marketing Operations Workflow:
205-
Phase 1: Strategic Planning
206-
- Operations: /marketing.plan.create, /marketing.plan.validate
207-
- Output: Approved marketing plan
249+
MetaSpec SDS Workflow:
250+
Phase 1: Foundation
251+
- Operations: /metaspec.sds.constitution
252+
- Output: Specification design principles
208253

209-
Phase 2: Campaign Design
210-
- Operations: /marketing.campaign.design, /marketing.campaign.get
211-
- Output: Campaign specifications
254+
Phase 2: Specification
255+
- Operations: /metaspec.sds.specify, /metaspec.sds.clarify
256+
- Output: Domain specification document
212257

213-
Phase 3: Content Creation
214-
- Operations: /marketing.generate.post, /marketing.generate.article
215-
- Output: Ready-to-publish content
258+
Phase 3: Quality Gates
259+
- Operations: /metaspec.sds.checklist, /metaspec.sds.analyze
260+
- Output: Quality validation reports
261+
262+
Phase 4: Implementation (if complex)
263+
- Operations: /metaspec.sds.plan, /metaspec.sds.tasks, /metaspec.sds.implement
264+
- Output: Sub-specifications
265+
```
266+
267+
**Good Entity State Machine** (Type 1: Business Execution):
268+
```
269+
Specification Entity (MetaSpec itself):
270+
States: draft → review → approved → deprecated
271+
Transitions:
272+
- draft → review (when: ready for feedback)
273+
- review → approved (when: quality checks pass)
274+
- approved → deprecated (when: replaced by new version)
216275
```
217276
218277
**Bad (Pre-v0.7.0) Design**:
219278
```
220-
Marketing Operations:
221-
- /marketing.project (what's this for?)
222-
- /marketing.campaign (when to use?)
223-
- /marketing.generate.post (how does this relate to campaign?)
279+
Specification Operations (no workflow):
280+
- /spec.create (what's this for?)
281+
- /spec.validate (when to use?)
282+
- /spec.analyze (how does this relate to create?)
224283
❌ Users confused about sequence and relationships
225284
```
226285
227286
### Your Checklist
228287
229288
When helping users create speckits, verify:
230-
- [ ] Domain specification includes "Workflow Specification" section
231-
- [ ] All operations are mapped to workflow phases
232-
- [ ] Each phase has clear purpose, entry/exit criteria
289+
290+
**Type 2: Specification Usage Workflow** (Required for all speckits):
291+
- [ ] Domain specification includes "Specification Usage Workflow" section
292+
- [ ] Workflow has 8-12 action steps (Constitution → Specify → ... → Implement)
293+
- [ ] Each step maps 1:1 to a slash command
294+
- [ ] Each step has clear goal, inputs, outputs, quality criteria
233295
- [ ] End-to-end workflow examples provided
296+
297+
**Type 1: Entity State Machines** (If domain has stateful entities):
298+
- [ ] Domain specification includes "Entity State Machines" section
299+
- [ ] Each stateful entity has defined states and transitions
300+
- [ ] Forbidden transitions are documented
301+
- [ ] Validation rules for state changes defined
302+
303+
**Constitution**:
234304
- [ ] Constitution Part II includes Workflow Completeness principle
235305
236306
---

‎CHANGELOG.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,197 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
77

88
## [Unreleased]
99

10+
### 🔄 v0.8.0 - Workflow Completeness Enhancement
11+
12+
**Date**: 2025-11-17
13+
**Focus**: Clarify two types of workflows and eliminate project-specific examples
14+
15+
#### Context
16+
17+
Based on community feedback, MetaSpec's workflow guidance was incomplete:
18+
- ✅ Type 1 (Entity State Machines) was well-documented
19+
- ❌ Type 2 (Specification Usage Workflow) lacked clear guidance
20+
- ❌ Examples used project-specific terminology (SDM, marketing)
21+
22+
This caused confusion: developers didn't know what granularity of workflow to define, or where Type 2 workflows should be documented.
23+
24+
#### Changes
25+
26+
##### 1. Clarified Two Types of Workflows
27+
28+
**Added clear distinction throughout all documentation**:
29+
30+
**Type 1: Entity State Machines**
31+
- Purpose: Entity lifecycle during business execution
32+
- Example: Order (pending → confirmed → shipped → delivered)
33+
- Used by: Business logic, domain operations
34+
- Defines: Status field transitions, business rules
35+
- Optional: Only for stateful entities
36+
37+
**Type 2: Specification Usage Workflow** ⭐ NEW
38+
- Purpose: End-to-end specification creation process
39+
- Example: SDS Workflow (Constitution → Specify → Clarify → ... → Implement)
40+
- Used by: Users creating specifications, AI agents
41+
- Defines: Action steps, slash commands, quality gates
42+
- **Required**: For all Speckits
43+
44+
##### 2. Updated All Examples to Use MetaSpec Itself
45+
46+
**Before** (v0.7.x):
47+
```yaml
48+
# Used project-specific examples
49+
SDM Workflow: Constitution → Discover → Strategy → Create
50+
Marketing Operations: /marketing.project, /marketing.campaign
51+
```
52+
53+
**After** (v0.8.0):
54+
```yaml
55+
# Uses MetaSpec's own workflows
56+
SDS Workflow: Constitution → Specify → Clarify → Plan → ... → Implement
57+
Specification Entity: draft → review → approved → deprecated
58+
```
59+
60+
**Rationale**: MetaSpec should be self-demonstrating. Every example now uses MetaSpec's own SDS/SDD workflows, making it universally applicable without project-specific bias.
61+
62+
##### 3. Updated Constitution (Part II: Workflow Completeness)
63+
64+
**Added to `memory/constitution.md`**:
65+
- Restructured into three parts (Part I, II, III)
66+
- **Part II, Principle 7: Workflow Completeness**
67+
- Defines both workflow types clearly
68+
- Specifies Type 2 as REQUIRED for all speckits
69+
- Provides MetaSpec's own workflow as example
70+
- Explains the rationale (pre-v0.7.0 vs post-v0.7.0)
71+
72+
##### 4. Enhanced `/metaspec.sds.specify` Command
73+
74+
**File**: `src/metaspec/templates/meta/sds/commands/specify.md.j2`
75+
76+
**Changes**:
77+
- Lines 464-568: Replaced SDM example with complete MetaSpec SDS Workflow (8 steps)
78+
- Lines 439-445: Updated workflow type examples (SDS, SDD, SD-X instead of SDM)
79+
- Lines 624-638: Updated comparison example using MetaSpec entities
80+
81+
**Example improvement**:
82+
```markdown
83+
# Before
84+
Workflow: Spec-Driven Marketing (SDM)
85+
Step 1: Constitution → Define brand principles
86+
Step 2: Discover → Research market needs
87+
...
88+
89+
# After
90+
Workflow: SDS (Spec-Driven Specification)
91+
Step 1: Constitution → Establish specification design principles
92+
Step 2: Specify → Create initial specification document
93+
Step 3: Clarify → Resolve underspecified areas
94+
...
95+
Step 8: Implement → Write sub-specification documents
96+
```
97+
98+
##### 5. Enhanced `/metaspec.sdd.specify` Command
99+
100+
**File**: `src/metaspec/templates/meta/sdd/commands/specify.md.j2`
101+
102+
**Changes**:
103+
- Lines 929-947: Added explicit guidance to check Domain Spec for Specification Usage Workflow
104+
- Added key question: "What is the recommended workflow for users to create specifications using these entities?"
105+
- Emphasized: If workflow not in Domain Spec → go back and define it first
106+
107+
**New guidance**:
108+
```markdown
109+
**First, check your Domain Specification**:
110+
- [ ] Does it have a "Specification Usage Workflow" section?
111+
- [ ] Does this workflow define the end-to-end process?
112+
- [ ] Are workflow steps defined at action level (8-12 steps)?
113+
- **If YES** → Use this workflow directly to derive commands
114+
- **If NO** → Go back to Domain Spec and define it first
115+
```
116+
117+
##### 6. Updated Domain Spec Template
118+
119+
**File**: `src/metaspec/templates/meta/templates/domain-spec-template.md.j2`
120+
121+
**Changes**:
122+
- Lines 210-214: Updated "Key Distinction" to use MetaSpec examples
123+
- Type 2: SDS workflow (Constitution → Specify → Clarify → ...)
124+
- Type 1: Specification entity (draft → review → approved → deprecated)
125+
126+
##### 7. Enhanced AGENTS.md
127+
128+
**File**: `AGENTS.md`
129+
130+
**Changes**:
131+
- Lines 127-169: Added new section "Two Types of Workflows" with clear comparison
132+
- Lines 247-284: Updated examples to use MetaSpec SDS/SDD workflows
133+
- Lines 290-304: Enhanced checklist to distinguish Type 1 vs Type 2 requirements
134+
135+
**Structure**:
136+
```markdown
137+
### Two Types of Workflows ⭐ UPDATED v0.8.0
138+
139+
#### Type 1: Entity State Machines (Business Execution)
140+
[Clear definition and example]
141+
142+
#### Type 2: Specification Usage Workflow (Specification Creation) ⭐ NEW
143+
[Clear definition and example]
144+
145+
**Key Distinction**: ...
146+
**Most speckits need BOTH**: ...
147+
```
148+
149+
#### Impact
150+
151+
**For Speckit Developers**:
152+
- ✅ Clear understanding of two workflow types
153+
- ✅ Know where to define each type (Domain Spec)
154+
- ✅ Can directly map Type 2 workflow to slash commands
155+
- ✅ Universal examples (MetaSpec) applicable to any domain
156+
157+
**For AI Agents**:
158+
- ✅ Consistent examples across all documentation
159+
- ✅ Clear Type 2 workflow → command derivation pattern
160+
- ✅ No confusion from project-specific terminology
161+
162+
**For MetaSpec Itself**:
163+
- ✅ Self-demonstrating: Uses own workflows as examples
164+
- ✅ No maintenance burden of keeping project-specific examples updated
165+
- ✅ Dogfooding: MetaSpec practices what it preaches
166+
167+
#### Files Changed
168+
169+
1. `src/metaspec/templates/meta/sds/commands/specify.md.j2` (+104 lines)
170+
2. `src/metaspec/templates/meta/sdd/commands/specify.md.j2` (+17 lines)
171+
3. `src/metaspec/templates/meta/templates/domain-spec-template.md.j2` (+3 lines)
172+
4. `src/metaspec/templates/meta/sds/commands/constitution.md.j2` (+47 lines) ⭐ **KEY FILE**
173+
5. `memory/constitution.md` (+184 lines, restructured)
174+
6. `AGENTS.md` (+60 lines, restructured)
175+
176+
**⚠️ Note**: File #4 (`constitution.md.j2` command template) is the most critical update, as it defines Part II principles for all generated speckits.
177+
178+
#### Enforcement
179+
180+
The Workflow Completeness principle (Part II, Principle 7) ensures:
181+
- `/metaspec.sds.constitution` includes workflow requirements
182+
- `/metaspec.sds.specify` generates both workflow types
183+
- `/metaspec.sds.checklist` (future) validates workflow completeness
184+
- `/metaspec.sds.analyze` (future) scores workflow quality
185+
186+
#### Migration Guide
187+
188+
**For existing speckits**:
189+
1. Review Domain Spec: Does it have "Specification Usage Workflow"?
190+
2. If NO: Run `/metaspec.sds.specify` again with Type 2 workflow guidance
191+
3. Define 8-12 action steps (Constitution → Specify → ... → Implement pattern)
192+
4. Map each step to a slash command
193+
5. Update Toolkit Spec to reference Domain Spec workflow
194+
195+
**For new speckits**:
196+
- Start with MetaSpec's SDS workflow as template
197+
- Adapt to your domain terminology
198+
- Keep core phases (constitution, specify, plan, implement)
199+
- Add/remove phases based on domain requirements
200+
10201
---
11202

12203
## [0.7.3] - 2025-11-16

0 commit comments

Comments
 (0)