Unify terminology: protocol → specification

- Update AGENTS.md: Use 'specification' instead of 'protocol' consistently
- Update all SDS command templates: specify, plan, tasks, implement
- Update SDD specify template: Unify dependency descriptions
- Update generator.py: Revise comments
- Note: specs/protocol/ directory name kept for historical reasons, but documentation refers to 'domain specifications'

Author: NeilJo-GY

AGENTS.md

@@ -274,21 +274,21 @@ def _select_templates(self, meta_spec: MetaSpecDefinition) -> dict[str, str]:
         # 3. MetaSpec commands and templates for speckit development → .metaspec/
         # These provide AI-assisted workflow for developing the speckit itself
         # Three-layer architecture:
-        #   - SDS (Spec-Driven Specification): 8 commands for protocol definition
+        #   - SDS (Spec-Driven Specification): 8 commands for specification definition
         #   - SDD (Spec-Driven Development): 8 commands for toolkit development
         #   - Evolution: 3 shared commands for specification evolution
 
-        # SDS commands (8): Protocol specification definition
+        # SDS commands (8): Domain specification definition
         # File naming: metaspec.sds.{command}.md to use /metaspec.sds.{command} prefix
         sds_commands = [
-            "constitution",  # Define protocol principles
-            "specify",  # Define protocol entities and operations
-            "clarify",  # Resolve protocol ambiguities
-            "plan",  # Plan protocol architecture and sub-specifications
-            "tasks",  # Break down protocol specification work
-            "implement",  # Write protocol specification documents
-            "checklist",  # Generate quality checklist for protocol
-            "analyze",  # Check protocol consistency
+            "constitution",  # Define specification design principles
+            "specify",  # Define specification entities and operations
+            "clarify",  # Resolve specification ambiguities
+            "plan",  # Plan specification architecture and sub-specifications
+            "tasks",  # Break down specification work
+            "implement",  # Write specification documents
+            "checklist",  # Generate quality checklist for specification
+            "analyze",  # Check specification consistency
         ]
 
         for cmd in sds_commands:

src/metaspec/generator.py

@@ -40,15 +40,15 @@ ls specs/protocol/ | grep -E '^[0-9]{3}-'
 If no protocol specs exist, **STOP** and show this error:
 
 ```
-❌ ERROR: Cannot create toolkit without protocol specification
+❌ ERROR: Cannot create toolkit without domain specification
 
-MetaSpec is a Spec-Driven framework. Every toolkit MUST depend on a protocol.
+MetaSpec is a Spec-Driven framework. Every toolkit MUST depend on a specification.
 
-The protocol defines WHAT (domain specification).
+The specification defines WHAT (domain specification).
 The toolkit defines HOW (implementation).
 
 Please run this command first:
-  /metaspec.sds.specify "Define {domain} protocol"
+  /metaspec.sds.specify "Define {domain} specification"
 
 Then return to create toolkit with:
   /metaspec.sdd.specify "Create {toolkit} for {domain}"
@@ -169,28 +169,28 @@ Generate **Toolkit Implementation Specification** with these sections:
 
 #### **Dependencies Section** (REQUIRED - CRITICAL)
 
-**First and foremost**, declare dependencies on protocol specifications:
+**First and foremost**, declare dependencies on domain specifications:
 
 ```markdown
 ## Dependencies
 
-**Protocol Specifications**:
-- **protocol/001-{domain}-protocol** - {Brief description of what protocol defines}
+**Domain Specifications**:
+- **protocol/001-{domain}-specification** - {Brief description of what specification defines}
 
 ### Dependency Rationale
 
-{Explain how this toolkit depends on the protocol:}
-- Which protocol entities are parsed/validated?
-- Which protocol rules are enforced?
-- How does the toolkit implement protocol operations?
+{Explain how this toolkit depends on the specification:}
+- Which specification entities are parsed/validated?
+- Which specification rules are enforced?
+- How does the toolkit implement specification operations?
 
 **Important**: 
-- This toolkit MUST reference at least one protocol specification
-- Changes to protocol specs may require updates to this toolkit
-- Without protocol dependency, this violates the Spec-Driven principle
+- This toolkit MUST reference at least one domain specification
+- Changes to specification may require updates to this toolkit
+- Without specification dependency, this violates the Spec-Driven principle
 ```
 
-**CRITICAL**: This Dependencies section is mandatory. Toolkit without protocol is not a valid speckit.
+**CRITICAL**: This Dependencies section is mandatory. Toolkit without specification is not a valid speckit.
 
 #### **Toolkit Overview**
 ```markdown

src/metaspec/templates/meta/sdd/commands/specify.md.j2

@@ -1,5 +1,5 @@
 ---
-description: Execute protocol specification writing by processing and completing all tasks from tasks.md
+description: Execute specification writing by processing and completing all tasks from tasks.md
 ---
 
 ## User Input
@@ -35,9 +35,9 @@ You **MUST** consider the user input before proceeding (if not empty).
 Get current protocol from Git branch or SPECIFY_FEATURE:
 ```bash
 # From Git branch
-current_protocol=$(git branch --show-current)
+current_spec=$(git branch --show-current)
 # Or from environment variable
-current_protocol=$SPECIFY_FEATURE
+current_spec=$SPECIFY_FEATURE
 
 # Example: "003-payment-processing"
 ```
@@ -54,14 +54,14 @@ type: parent
 ---
 ```
 
-**Store context for sub-protocol creation**:
+**Store context for sub-specification creation**:
 - `current_id`: "003-payment-processing"
 - `parent_id`: "001-order-protocol" or null
 - `root_id`: "001-order-protocol"
 
-**This context will be passed to specify** when creating sub-protocols:
+**This context will be passed to specify** when creating sub-specifications:
 - Sub-protocols will have: parent={current_id}, root={root_id}
-- Example: If current=003, sub-protocol 013 will have parent=003, root=001
+- Example: If current=003, sub-specification 013 will have parent=003, root=001
 
 **Step 2c: Read Planning Documents**
 
@@ -230,7 +230,7 @@ Phase 4: Cross-Reference Validation
       - specify will create 013-credit-card-payment/ with correct frontmatter
       - specify generates spec.md with parent chain
 
-   d. **Verify sub-protocol created**:
+   d. **Verify sub-specification created**:
       ```yaml
       # Generated in specs/protocol/013-credit-card-payment/spec.md
       ---
@@ -295,7 +295,7 @@ Phase 4: Cross-Reference Validation
 
 ### Dependency Rationale
 
-{Explain what this sub-protocol depends on from core protocol:}
+{Explain what this sub-specification depends on from core protocol:}
 - Entities used: [List core entities referenced]
 - Operations extended: [List operations]
 - Validation rules inherited: [List rules]
@@ -306,11 +306,11 @@ Phase 4: Cross-Reference Validation
 
 **Name**: {Sub-Protocol Name}  
 **Domain**: {Specific concern within main protocol}  
-**Purpose**: {What problem this sub-protocol solves}
+**Purpose**: {What problem this sub-specification solves}
 
 **Problem Statement**: {Detailed problem description}
 
-**Solution**: {How this sub-protocol addresses the problem}
+**Solution**: {How this sub-specification addresses the problem}
 
 **Scope**:
 - ✅ Included: {What's in scope}
@@ -320,7 +320,7 @@ Phase 4: Cross-Reference Validation
 
 ## Glossary
 
-{Terms specific to this sub-protocol}
+{Terms specific to this sub-specification}
 
 - **{Term 1}**: {Definition}
   - Example: {Example usage}
@@ -354,7 +354,7 @@ Phase 4: Cross-Reference Validation
 
 ## Core Entities
 
-{Entities specific to this sub-protocol}
+{Entities specific to this sub-specification}
 
 ### Entity: {EntityName}
 
@@ -392,7 +392,7 @@ entity_name:
 
 ## Workflow
 
-{If this sub-protocol involves state transitions or lifecycle}
+{If this sub-specification involves state transitions or lifecycle}
 
 ### State Machine: {Entity Name}
 
@@ -417,7 +417,7 @@ entity_name:
 
 ## Protocol Operations
 
-{Operations specific to this sub-protocol}
+{Operations specific to this sub-specification}
 
 ### Operation: {operation_name}
 
@@ -536,8 +536,8 @@ error_response:
 ### Entity References
 
 **From Core Protocol**:
-- {Core Entity 1}: {How used in this sub-protocol}
-- {Core Entity 2}: {How used in this sub-protocol}
+- {Core Entity 1}: {How used in this sub-specification}
+- {Core Entity 2}: {How used in this sub-specification}
 
 ### Operation Extensions
 
@@ -569,7 +569,7 @@ error_response:
 
 ## Version History
 
-- **v1.0.0** ({date}): Initial sub-protocol specification
+- **v1.0.0** ({date}): Initial sub-specification specification
   - Defined {N} entities
   - Specified {N} operations
   - Established {N} validation rules

src/metaspec/templates/meta/sds/commands/implement.md.j2

@@ -1,5 +1,5 @@
 ---
-description: Plan protocol specification structure by analyzing complexity and organizing sub-specifications
+description: Plan specification structure by analyzing complexity and organizing sub-specifications
 ---
 
 ## User Input
@@ -12,56 +12,56 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 ## Outline
 
-**Goal**: Analyze protocol complexity and plan the specification structure, including identifying necessary sub-specifications and their dependencies.
+**Goal**: Analyze specification complexity and plan the specification structure, including identifying necessary sub-specifications and their dependencies.
 
-**Important**: This command runs AFTER `/metaspec.sds.specify` when initial protocol concept is defined. It determines whether the protocol needs to be split into multiple sub-specifications.
+**Important**: This command runs AFTER `/metaspec.sds.specify` when initial specification concept is defined. It determines whether the specification needs to be split into multiple sub-specifications.
 
 ### Execution Flow
 
-#### 1. Load Protocol Context
+#### 1. Load Specification Context
 
-**Step 1a: Determine Current Protocol**
+**Step 1a: Determine Current Specification**
 
-Get current protocol from Git branch or SPECIFY_FEATURE:
+Get current specification from Git branch or SPECIFY_FEATURE:
 ```bash
 # From Git branch
-current_protocol=$(git branch --show-current)
+current_spec=$(git branch --show-current)
 # Or from environment variable
-current_protocol=$SPECIFY_FEATURE
+current_spec=$SPECIFY_FEATURE
 
 # Example: "003-payment-processing"
 ```
 
 **Step 1b: Read Protocol Specification**
 
-Read the spec.md for current protocol:
+Read the spec.md for current specification:
 ```bash
 # Read the spec.md
-cat specs/protocol/${current_protocol}/spec.md
+cat specs/protocol/${current_spec}/spec.md
 ```
 
 **Step 1c: Extract Metadata** (from YAML frontmatter)
 
 Parse frontmatter to understand context:
 ```yaml
 ---
-protocol_id: 003-payment-processing
+spec_id: 003-payment-processing
 parent: 001-order-protocol
 root: 001-order-protocol
 type: parent  # or leaf or root
 ---
 ```
 
 **Store context**:
-- `current_id`: protocol_id (e.g., "003-payment-processing")
+- `current_id`: spec_id (e.g., "003-payment-processing")
 - `parent_id`: parent (e.g., "001-order-protocol" or null)
 - `root_id`: root (e.g., "001-order-protocol")
 - `current_type`: type (e.g., "parent", "leaf", "root")
 
 **This tells us**:
-- Where this protocol is in the hierarchy
-- Can inform numbering for sub-protocols
-- Understand if this is already a sub-protocol (can have sub-sub-protocols)
+- Where this specification is in the hierarchy
+- Can inform numbering for sub-specifications
+- Understand if this is already a sub-specification (can have sub-sub-specifications)
 
 **Step 1d: Extract Specification Content**
 
@@ -128,7 +128,7 @@ Note: Adjusted to align with 1500-line threshold mentioned in Decision Matrix
 
 **Output format (both cases)**:
 ```
-Protocol Analysis: {protocol_id}
+Protocol Analysis: {spec_id}
 
 📊 Complexity Assessment:
    - Lines: {line_count}
@@ -149,7 +149,7 @@ Protocol Analysis: {protocol_id}
 Reason: Specification is manageable (complexity: {score:.2f})
 
 This protocol does not need to be split into sub-specifications.
-It is a **leaf protocol** - a complete, self-contained specification.
+It is a **leaf specification** - a complete, self-contained specification.
 
 Next Steps:
 ✅ Specification is ready
@@ -610,7 +610,7 @@ graph TD
    - Is modular documentation valuable?
 
 4. **Consider evolution**
-   - Will parts of the protocol evolve at different rates?
+   - Will parts of the specification evolve at different rates?
    - Do some sections need stricter stability guarantees?
    - Is independent versioning valuable?
 

src/metaspec/templates/meta/sds/commands/plan.md.j2

@@ -1,5 +1,5 @@
 ---
-description: Define domain protocol specification (SDS - Spec-Driven Specification)
+description: Define domain specification (SDS - Spec-Driven Specification)
 ---
 
 ## User Input
@@ -12,15 +12,15 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 ## Outline
 
-The text the user typed after `/metaspec.sds.specify` is the **protocol specification description**. 
+The text the user typed after `/metaspec.sds.specify` is the **domain specification description**. 
 
-**PURPOSE: Protocol Specification (SDS)** 🎯
+**PURPOSE: Domain Specification (SDS)** 🎯
 
-This command is for defining **domain protocols, rules, and standards**:
-- Focus: WHAT the protocol is
+This command is for defining **domain specifications, rules, and standards**:
+- Focus: WHAT the domain specification is
 - Output: `specs/protocol/001-{name}/spec.md`
 - Independent of any implementation
-- Pure protocol definition
+- Pure domain specification
 
 **NOT for toolkit implementation** - Use `/metaspec.sdd.specify` for that.
 
@@ -220,7 +220,7 @@ Describe real-world scenarios where this protocol applies:
 
 #### **Core Entities**
 
-Define protocol entities (NOT toolkit entities):
+Define specification entities (NOT toolkit entities):
 
 **Template**:
 ```markdown
@@ -390,7 +390,7 @@ Comprehensive list of all protocol constraints:
 
 #### **Error Handling**
 
-Define protocol-level error handling:
+Define specification-level error handling:
 
 ```markdown
 ## Error Handling