feat: Introduce Workflow-Driven Design Philosophy (v0.7.0)

NeilJo-GY · NeilJo-GY · commit f1ddce488dd5 · 2025-11-15T19:29:03.000+08:00
Major Feature: Added Workflow Completeness Principle

- Added Part II Principle 7 'Workflow Completeness' to Constitution template
- Added 'Workflow Specification' section to domain spec template
- Updated AGENTS.md with workflow-driven design philosophy
- Version bump: 0.6.8 → 0.7.0

This addresses a fundamental design gap where speckits could pass quality
checks but lack clear user workflows. Now all domain specifications must
define complete user workflows with phases, operation mapping, and sequencing.

Philosophy: Build 'Workflow Systems', not 'Tool Boxes'

Refs: marketing-spec-kit feedback, real-world usage analysis
diff --git a/AGENTS.md b/AGENTS.md
@@ -100,6 +100,7 @@ memory/constitution.md
 │   - Implementation Neutrality
 │   - Extensibility Design
 │   - Domain Fidelity
+│   - Workflow Completeness ⭐ NEW
 │
 └── Part III: Toolkit Implementation Principles (管理: /metaspec.sdd.constitution)
     - Entity-First Design
@@ -115,6 +116,122 @@ memory/constitution.md
 2. **AI-First Design** (Part I): Generated systems must be AI-friendly
 3. **Progressive Enhancement** (Part I): Start with MVP, add features incrementally
 4. **Domain Specificity** (Part I): Respect domain constraints
+5. **Workflow Completeness** (Part II): ⭐ **NEW** - Define complete user workflows, not just isolated operations
+
+---
+
+## 🚀 Workflow-Driven Design Philosophy
+
+**CRITICAL NEW PRINCIPLE** (v0.7.0+): MetaSpec now requires **workflow-first design** for all domain specifications.
+
+### Why Workflow Matters
+
+❌ **Don't build**: "Tool箱" (collection of isolated operations)  
+✅ **Do build**: "Workflow Systems" (integrated end-to-end user journeys)
+
+### The Problem We Solved
+
+**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.
+
+**After v0.7.0**: All domain specifications MUST define:
+1. **Workflow Phases** - Distinct stages in the user journey
+2. **Phase Purposes** - Why each phase exists
+3. **Operation Mapping** - Which operations belong to which phase
+4. **Sequencing** - Entry/exit criteria, dependencies, ordering
+5. **End-to-End Examples** - Complete workflow demonstrations
+
+### MetaSpec as Example
+
+MetaSpec itself demonstrates perfect workflow design:
+
+```
+SDS Workflow:
+  Phase 1: Constitution → /metaspec.sds.constitution
+  Phase 2: Specification → /metaspec.sds.specify
+  Phase 3: Quality Gates → /metaspec.sds.clarify, /metaspec.sds.checklist
+  Phase 4: Implementation → /metaspec.sds.plan, /metaspec.sds.tasks, /metaspec.sds.implement
+  Phase 5: Validation → /metaspec.sds.analyze
+
+SDD Workflow:
+  Phase 1: Constitution → /metaspec.sdd.constitution
+  Phase 2: Specification → /metaspec.sdd.specify, /metaspec.sdd.clarify
+  Phase 3: Architecture → /metaspec.sdd.plan, /metaspec.sdd.checklist
+  Phase 4: Implementation → /metaspec.sdd.tasks, /metaspec.sdd.analyze, /metaspec.sdd.implement
+```
+
+**Your mission**: Ensure all speckits you help create follow this same pattern.
+
+### Required Workflow Elements
+
+When defining domain specifications, ALWAYS include:
+
+1. **Phase Definitions**
+   ```yaml
+   Phase 1: [Name]
+     Purpose: [Why this phase exists]
+     Entry: [When user enters]
+     Operations: [Which operations]
+     Outputs: [What is produced]
+     Exit: [When complete]
+   ```
+
+2. **Operation-to-Phase Mapping**
+   - Every operation MUST belong to at least one workflow phase
+   - No "orphan" operations without clear usage context
+
+3. **Workflow Examples**
+   - Show complete end-to-end usage
+   - Demonstrate phase transitions
+   - Include success indicators
+
+4. **Decision Points**
+   - Document when users choose between paths
+   - Explain branching logic
+   - Provide decision criteria
+
+### Enforcement
+
+The new **Part II Principle 7: Workflow Completeness** ensures:
+- `/metaspec.sds.constitution` includes workflow requirements
+- `/metaspec.sds.specify` generates Workflow Specification sections
+- `/metaspec.sds.checklist` (future) validates workflow completeness
+- `/metaspec.sds.analyze` (future) scores workflow quality
+
+### Examples
+
+**Good Workflow-Driven Design**:
+```
+Marketing Operations Workflow:
+  Phase 1: Strategic Planning
+    - Operations: /marketing.plan.create, /marketing.plan.validate
+    - Output: Approved marketing plan
+  
+  Phase 2: Campaign Design
+    - Operations: /marketing.campaign.design, /marketing.campaign.get
+    - Output: Campaign specifications
+  
+  Phase 3: Content Creation
+    - Operations: /marketing.generate.post, /marketing.generate.article
+    - Output: Ready-to-publish content
+```
+
+**Bad (Pre-v0.7.0) Design**:
+```
+Marketing Operations:
+  - /marketing.project (what's this for?)
+  - /marketing.campaign (when to use?)
+  - /marketing.generate.post (how does this relate to campaign?)
+  ❌ Users confused about sequence and relationships
+```
+
+### Your Checklist
+
+When helping users create speckits, verify:
+- [ ] Domain specification includes "Workflow Specification" section
+- [ ] All operations are mapped to workflow phases
+- [ ] Each phase has clear purpose, entry/exit criteria
+- [ ] End-to-end workflow examples provided
+- [ ] Constitution Part II includes Workflow Completeness principle
 
 ---
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,141 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.7.0] - 2025-11-15
+
+### ⭐ Major Feature - Workflow-Driven Design Philosophy
+
+**Introduced Workflow Completeness Principle for Domain Specifications**
+
+MetaSpec now enforces **workflow-first design** for all domain specifications, addressing a fundamental design gap where speckits could pass all quality checks but lack clear user workflows.
+
+**Problem We Solved**:
+- Before v0.7.0: Developers created speckits with isolated operations ("tool箱")
+- Users received collections of commands without knowing usage order or relationships
+- High quality scores but poor usability - no end-to-end guidance
+- Example: "13 commands" but unclear which to use first, how they connect
+
+**Solution**:
+- Added **Part II Principle 7: Workflow Completeness** to Constitution
+- All domain specifications MUST now define complete user workflows
+- Workflows include phases, operation mapping, sequencing, and examples
+- MetaSpec itself demonstrates this principle with SDS/SDD workflows
+
+### ✨ Added
+
+#### Constitution Template Updates
+- **Added Part II Principle 7**: "Workflow Completeness"
+  - Requires complete user workflows from start to finish
+  - Distinct phases/stages with clear purposes
+  - Operation ordering and dependencies
+  - Decision points and branching logic
+  - End-to-end workflow examples
+  - Operations mapped to workflow phases
+- Example workflow structure in constitution template
+- Domain-specific workflow examples (Marketing, MCP, API Testing)
+
+#### Domain Specification Template
+- **Added "Workflow Specification" section** to `domain-spec-template.md.j2`
+  - `user_workflows` in frontmatter YAML
+  - Workflow phases with purpose, entry/exit criteria
+  - Operation-to-phase mapping
+  - Workflow example usage
+  - Design rationale emphasizing integrated workflows
+- Positioned after "Use Cases", before "Core Entities"
+
+#### Documentation Updates
+- **AGENTS.md**: New "Workflow-Driven Design Philosophy" section
+  - Explains why workflow matters (systems vs toolboxes)
+  - Shows MetaSpec's own workflows as examples
+  - Required workflow elements checklist
+  - Good vs bad design examples
+  - Enforcement mechanisms
+- **Constitution Structure**: Updated to show Workflow Completeness as 7th principle
+
+### 🎯 Philosophy
+
+**Core Principle**:
+```
+❌ Don't build: "Tool箱" (isolated operations)
+✅ Do build: "Workflow Systems" (integrated user journeys)
+```
+
+**MetaSpec as Example**:
+```
+SDS Workflow:
+  Phase 1: Constitution → /metaspec.sds.constitution
+  Phase 2: Specification → /metaspec.sds.specify
+  Phase 3: Quality Gates → /metaspec.sds.clarify, /metaspec.sds.checklist
+  Phase 4: Implementation → /metaspec.sds.plan, /metaspec.sds.tasks, /metaspec.sds.implement
+  Phase 5: Validation → /metaspec.sds.analyze
+```
+
+**Required Elements**:
+1. **Workflow Phases** - Distinct stages in user journey
+2. **Phase Purposes** - Why each phase exists
+3. **Operation Mapping** - Which operations belong to which phase
+4. **Sequencing** - Entry/exit criteria, dependencies, ordering
+5. **End-to-End Examples** - Complete workflow demonstrations
+
+### 🔄 Impact on Existing Projects
+
+**Backward Compatibility**: ✅ Fully compatible
+- Existing speckits continue to work
+- No breaking changes to APIs or commands
+- Templates add new sections but don't remove existing content
+
+**Migration Path**:
+- New projects automatically get workflow-focused templates
+- Existing projects can add workflow sections via `/metaspec.sds.specify`
+- Constitution updates guide workflow definition
+- Future: `/metaspec.sds.checklist` and `/metaspec.sds.analyze` will validate workflow completeness
+
+### 📊 Quality Enforcement
+
+**Current (v0.7.0)**:
+- ✅ Constitution template includes Workflow Completeness principle
+- ✅ Domain spec template includes Workflow Specification section
+- ✅ AGENTS.md documents workflow requirements
+
+**Future (v0.7.x)**:
+- 🔜 `/metaspec.sds.checklist` validates workflow completeness
+- 🔜 `/metaspec.sds.analyze` scores workflow quality (Dimension 7: 15% weight)
+- 🔜 Low scores (<70%) if workflow missing or incomplete
+
+### 💡 Rationale
+
+**Feedback Source**: Real-world development of `marketing-spec-kit`
+- Followed complete SDS + SDD workflow
+- All quality checks passed (50/50, 98/100)
+- Final result: 13 isolated commands without clear workflow
+- Discovery: MetaSpec showed perfect workflows but didn't require them
+
+**Design Philosophy Alignment**:
+- MetaSpec demonstrates workflow-first design
+- New principle ensures generated speckits follow same pattern
+- "Practice what you preach" - consistency across framework
+
+**User Experience**:
+- Users need guidance on operation sequencing
+- Isolated operations less valuable than integrated workflows
+- Workflow definition enables better AI assistance and automation
+
+### 🎉 Benefits
+
+1. **Clearer User Guidance**: Users know which operations to use when
+2. **Better AI Support**: AI agents understand operation context and sequencing
+3. **Improved Usability**: Speckits are systems, not just tool collections
+4. **Design Consistency**: All speckits follow MetaSpec's workflow pattern
+5. **Quality Assurance**: Future validation catches workflow gaps early
+
+### 📚 References
+
+- **Feedback Document**: `/Users/guyue/marketing-spec-kit/docs/internal/metaspec-feedback.md`
+- **Related Issue**: Design gap identified through real-world usage
+- **Philosophy**: Workflow Systems vs Tool Boxes
+
+---
+
 ## [0.6.8] - 2025-11-15
 
 ### 🐛 Bug Fixes - Critical
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "meta-spec"
-version = "0.6.8"
+version = "0.7.0"
 description = "Meta-specification framework for generating Spec-Driven X (SD-X) toolkits for AI agents"
 readme = "README.md"
 requires-python = ">=3.11"
diff --git a/src/metaspec/__init__.py b/src/metaspec/__init__.py
@@ -5,7 +5,7 @@
 from YAML definitions.
 """
 
-__version__ = "0.6.8"
+__version__ = "0.7.0"
 
 __all__ = ["__version__"]
 
diff --git a/src/metaspec/templates/meta/sds/commands/constitution.md.j2 b/src/metaspec/templates/meta/sds/commands/constitution.md.j2
@@ -89,6 +89,23 @@ Based on user input and domain understanding, update these **standard specificat
 
 **Rationale**: Domain-faithful specifications are easier to adopt and understand.
 
+#### **VII. Workflow Completeness**
+- All specifications define complete user workflows from start to finish
+- Distinct phases/stages of the user journey are clearly identified
+- Operation ordering and dependencies are documented
+- Decision points and branching logic are specified
+- End-to-end workflow examples are provided
+- Operations are mapped to specific workflow phases
+
+**Rationale**: Users need guidance on how to use operations in sequence. Isolated operations are less valuable than integrated workflows. Workflow definition enables better AI assistance and automation.
+
+**Example workflow structure**:
+```
+Phase 1: Planning → operations: create_plan, validate_plan
+Phase 2: Execution → operations: execute_task, monitor_progress  
+Phase 3: Analysis → operations: generate_report, optimize
+```
+
 ### 4. Prepare domain-specific examples
 
 For each principle in Part II, provide domain-specific examples:
@@ -99,11 +116,12 @@ For each principle in Part II, provide domain-specific examples:
 - **Implementation Neutrality**: How to avoid technology coupling?
 - **Extensibility Design**: How to support evolution?
 - **Domain Fidelity**: What standards to follow? Terminology?
+- **Workflow Completeness**: What workflow phases? Operation ordering? User journey?
 
 **Examples by domain**:
-- Marketing: Campaign (name, type, channels, budget, dates), CPM/CTR/ROAS validation
-- MCP: Tool (name, description, inputSchema), JSON Schema validation
-- API Testing: APITest (endpoint, method, assertions), HTTP status validation
+- Marketing: Campaign (name, type, channels, budget, dates), CPM/CTR/ROAS validation, Workflow: Planning → Campaign Design → Content Creation → Execution → Analysis
+- MCP: Tool (name, description, inputSchema), JSON Schema validation, Workflow: Server Init → Tool Discovery → Tool Execution → Result Processing
+- API Testing: APITest (endpoint, method, assertions), HTTP status validation, Workflow: Test Design → Setup → Execution → Validation → Reporting
 
 ### 5. Update Part II section
 
@@ -138,6 +156,24 @@ Update only the `## Part II: Specification Design Principles` section with domai
 
 [Domain standards and conventions to follow]
 
+### 7. Workflow Completeness
+
+[Complete user workflows from start to finish]
+
+**Required workflow elements**:
+- Phase definitions with clear purposes
+- Operation ordering and dependencies
+- Entry and exit criteria for each phase
+- Decision points and branching logic
+- End-to-end workflow examples
+
+**Example workflow**:
+```
+Phase 1: [Phase Name] → operations: [op1, op2]
+Phase 2: [Phase Name] → operations: [op3, op4]
+Phase 3: [Phase Name] → operations: [op5, op6]
+```
+
 <!-- Managed by /metaspec.sds.constitution -->
 ```
 
diff --git a/src/metaspec/templates/meta/templates/domain-spec-template.md.j2 b/src/metaspec/templates/meta/templates/domain-spec-template.md.j2
