BREAKING CHANGE: rename specs/protocol/ to specs/domain/

Rename directory from 'protocol' to 'domain' for better semantic clarity:
- 'domain' is more general and includes protocols, formats, models, rules
- Aligns with Domain-Driven Design principles
- Better symmetry: specs/domain/ (WHAT) vs specs/toolkit/ (HOW)

Impact:
- All 122 references across 19 files updated
- Affects all existing speckits using MetaSpec
- Migration: Rename specs/protocol/ → specs/domain/ in existing projects

Files changed:
- Core docs: AGENTS.md, CHANGELOG.md
- Templates: all SDS/SDD command templates
- Docs: iteration-layers.md, evolution-guide.md, internal docs

Author: NeilJo-GY

AGENTS.md

@@ -124,7 +124,7 @@ For defining domain specifications:
 - `/metaspec.sds.checklist` - Generate quality checklist for specification
 - `/metaspec.sds.analyze` - Check specification consistency
 
-**Location**: Works with `specs/protocol/` directory (stores domain specifications)
+**Location**: Works with `specs/domain/` directory (stores domain specifications)
 
 #### 🌳 Recursive Tree Structure (NEW)
 
@@ -134,7 +134,7 @@ For defining domain specifications:
 
 **Physical Structure** (flat directory layout):
 ```bash
-specs/protocol/
+specs/domain/
 ├── 001-order-specification/     # All at same level
 ├── 002-order-creation/
 ├── 003-payment-processing/
@@ -155,7 +155,7 @@ specs/protocol/
 ```
 
 **Why flat physical structure?**
-- ✅ Simple paths: `specs/protocol/013-credit-card-payment/`
+- ✅ Simple paths: `specs/domain/013-credit-card-payment/`
 - ✅ FEATURE independence: Each specification is a standalone FEATURE
 - ✅ Flexible numbering: 003's children can be 013-015 (skip 004-012)
 - ✅ Git branch friendly: Branch name = directory name
@@ -168,7 +168,7 @@ specs/protocol/
 - **Unified commands**: Same commands work at all levels
 
 **How relationships are maintained**:
-- **Physical**: All specifications are sibling directories under `specs/protocol/`
+- **Physical**: All specifications are sibling directories under `specs/domain/`
 - **Logical**: Parent-child relationships declared in YAML frontmatter
   ```yaml
   ---
@@ -190,7 +190,7 @@ specs/protocol/
 /metaspec.sds.implement → Creates 002-008
 
 # At level 2 (003 is also complex)
-cd specs/protocol/003-payment-processing/
+cd specs/domain/003-payment-processing/
 /metaspec.sds.plan → Decides to split again
 /metaspec.sds.implement → Creates 013-015
 ```
@@ -239,7 +239,7 @@ MetaSpec generates **working toolkits** through a three-stage process:
 ```
 /metaspec.sds.specify
   ↓
-specs/protocol/001-{domain}-specification/spec.md
+specs/domain/001-{domain}-specification/spec.md
   - Entity definitions
   - Validation rules
   - Operations
@@ -338,7 +338,7 @@ For controlled specification evolution (both SDS and SDD):
 
 ```
 MetaSpec commands (19 total):
-  - SDS (8 commands)     → Define domain specifications (specs/protocol/)
+  - SDS (8 commands)     → Define domain specifications (specs/domain/)
   - SDD (8 commands)     → Develop toolkits (specs/toolkit/)
   - Evolution (3 shared) → Manage changes (changes/)
                               ↓
@@ -386,7 +386,7 @@ When using MetaSpec to develop a speckit, follow this two-phase approach:
 
 **Purpose**: Define the domain specification, rules, and standards
 
-**Location**: `specs/protocol/001-{domain}-specification/`
+**Location**: `specs/domain/001-{domain}-specification/`
 
 **What to include**:
 - Domain entities and schemas
@@ -396,7 +396,7 @@ When using MetaSpec to develop a speckit, follow this two-phase approach:
 
 **Example**:
 ```markdown
-# specs/protocol/001-mcp-core-specification/spec.md
+# specs/domain/001-mcp-core-specification/spec.md
 
 ## MCP Specification
 
@@ -511,7 +511,7 @@ examples/
 ```bash
 # Phase 1: Domain Specification (SDS)
 /metaspec.sds.constitution  # Define specification design principles
-/metaspec.sds.specify       # Create specs/protocol/001-{domain}-specification/spec.md
+/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
@@ -584,7 +584,7 @@ cd my-speckit
 
 **Example 2: Iterating on specification**
 ```bash
-# Make changes to specs/protocol/001-*/spec.md
+# Make changes to specs/domain/001-*/spec.md
 /metaspec.sds.clarify  # Resolve ambiguities
 /metaspec.sds.checklist  # Validate specification quality
 /metaspec.sds.analyze  # Check consistency
@@ -654,7 +654,7 @@ Output:
 Score: 33% (1/3 passing)
 
 # Step 2: User fixes issues
-User edits specs/protocol/001-mcp/spec.md
+User edits specs/domain/001-mcp/spec.md
 - Adds field types
 - Adds validation rules
 

CHANGELOG.md

@@ -17,7 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 SDS now supports hierarchical domain specifications with unlimited depth:
 
-- **Physical Structure**: Flat directory layout under `specs/protocol/`
+- **Physical Structure**: Flat directory layout under `specs/domain/`
   - All specifications are sibling directories (e.g., `001-root/`, `002-child/`, `013-grandchild/`)
   - Simple paths, FEATURE independence, Git branch friendly
 
@@ -79,7 +79,7 @@ Added 3 new commands for complex specification definition:
 
 **Why Flat Physical + Tree Logical?**
 
-1. **Simple paths**: `specs/protocol/013-credit-card-payment/` (not deeply nested)
+1. **Simple paths**: `specs/domain/013-credit-card-payment/` (not deeply nested)
 2. **FEATURE independence**: Each protocol is a standalone FEATURE with its own lifecycle
 3. **Flexible numbering**: Sub-protocols can use any available numbers (skip ranges)
 4. **Git branch friendly**: Branch name = directory name = protocol_id

docs/evolution-guide.md

@@ -46,7 +46,7 @@ Need to change specification?
 # Toolkit is v1.0.0 and published to community
 # User wants to add a new field
 
-❌ WRONG: Direct edit specs/protocol/XXX/spec.md
+❌ WRONG: Direct edit specs/domain/XXX/spec.md
 ✅ RIGHT: /metaspec.proposal "Add new field"
 ```
 
@@ -99,7 +99,7 @@ Need to change specification?
 # Toolkit is in draft (v0.1.0)
 # User wants to fix typos, add examples, improve descriptions
 
-✅ RIGHT: Direct edit specs/protocol/XXX/spec.md
+✅ RIGHT: Direct edit specs/domain/XXX/spec.md
 ✅ THEN: /metaspec.sds.checklist (update mode) to verify
 ```
 
@@ -125,14 +125,14 @@ Need to change specification?
 
 ```bash
 1. User writes initial protocol spec
-   $ vim specs/protocol/001-mcp-protocol/spec.md
+   $ vim specs/domain/001-mcp-protocol/spec.md
 
 2. User validates quality
    $ /metaspec.sds.checklist
    → Result: ❌ CHK003 - Missing field types
 
 3. User fixes directly (minor improvement)
-   $ vim specs/protocol/001-mcp-protocol/spec.md
+   $ vim specs/domain/001-mcp-protocol/spec.md
    # Add missing type definitions
 
 4. User re-validates
@@ -259,7 +259,7 @@ $ /metaspec.proposal "Fix typo in description" --type sds
 # Overhead: proposal.md, tasks.md, impact.md, approval process
 
 ✅ RIGHT:
-$ vim specs/protocol/001-xxx/spec.md  # Fix typo
+$ vim specs/domain/001-xxx/spec.md  # Fix typo
 $ /metaspec.sds.checklist  # Validate
 ```
 
@@ -273,7 +273,7 @@ $ /metaspec.sds.checklist  # Validate
 # Toolkit is v1.0.0 and published
 
 ❌ WRONG:
-$ vim specs/protocol/001-xxx/spec.md  # Add new field
+$ vim specs/domain/001-xxx/spec.md  # Add new field
 $ git commit -m "Add new field"
 
 ✅ RIGHT:
@@ -369,7 +369,7 @@ $ /metaspec.recommend-workflow "I want to add a new field"
 ✅ Alternative: Evolution (if complex or near release)
 
 🔄 Suggested workflow:
-1. Edit specs/protocol/001-xxx/spec.md
+1. Edit specs/domain/001-xxx/spec.md
 2. Run /metaspec.sds.checklist (update mode)
 3. Verify: CHK###: ❌ → ✅
 ```

docs/internal/iteration-roadmap.md

@@ -129,7 +129,7 @@ A command does NOT need iteration if:
 **Workflow**:
 ```bash
 $ /metaspec.sds.specify "Define MCP protocol"
-  → Creates specs/protocol/001-mcp-protocol/spec.md
+  → Creates specs/domain/001-mcp-protocol/spec.md
 $ vim spec.md  # User edits directly
 $ /metaspec.sds.checklist  # Validate (with iteration)
 ```
@@ -334,7 +334,7 @@ For each command needing iteration support, follow this pattern:
 **CRITICAL**: Before generating, check if output already exists:
 
 ```bash
-ls specs/protocol/XXX-name/[output-directory]/
+ls specs/domain/XXX-name/[output-directory]/
 ```
 
 **If exists**, ask user:

docs/iteration-layers.md

@@ -123,7 +123,7 @@
 # Toolkit: v0.2.0 (draft)
 # Change: Add usage example
 
-1. vim specs/protocol/001-mcp/spec.md
+1. vim specs/domain/001-mcp/spec.md
    # Add example section
 
 2. /metaspec.sds.checklist
@@ -236,7 +236,7 @@ Done! ✅
 
 ```yaml
 ✅ Checklist reads:
-  - specs/protocol/XXX/spec.md
+  - specs/domain/XXX/spec.md
 
 ✅ Checklist writes:
   - checklists/comprehensive-quality.md

src/metaspec/templates/README.md

@@ -139,7 +139,7 @@ Development methodologies organized by lifecycle:
 - `analyze.md.j2` - Check specification consistency
 
 **Generated to**: `.metaspec/commands/metaspec.sds.*`
-**Works with**: `specs/protocol/` directory
+**Works with**: `specs/domain/` directory
 
 ##### `meta/sdd/commands/` - Spec-Driven Development (8 commands)
 

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

@@ -30,7 +30,7 @@ Define domain protocol specifications:
 - `/metaspec.sds.checklist` - Generate quality checklist for protocol
 - `/metaspec.sds.analyze` - Check protocol consistency
 
-**Output**: `specs/protocol/` directory
+**Output**: `specs/domain/` directory
 
 ### Layer 2: SDD (Spec-Driven Development) - 8 Commands
 
@@ -75,7 +75,7 @@ Manage specification changes:
 /metaspec.sds.analyze
 ```
 
-**Output**: `specs/protocol/001-{domain}-protocol/spec.md`
+**Output**: `specs/domain/001-{domain}-protocol/spec.md`
 
 ### Phase 2: Design Toolkit (SDD)
 

src/metaspec/templates/meta/README.md

@@ -54,7 +54,7 @@ meta/
 
 1. **SDS (Spec-Driven Specification)** - Define domain specifications
    - Goal: Define WHAT (what the specification is)
-   - Output: `specs/protocol/` directory
+   - Output: `specs/domain/` directory
    - Examples: Define MCP specification, OpenAPI specification
    - **Status**: Primary, core asset
 
@@ -127,12 +127,12 @@ Generated command prefix: `/metaspec.sds.*`
 | Command | Purpose | Output |
 |------|------|------|
 | `constitution` | Define specification design principles | memory/constitution.md |
-| `specify` | Define specification entities and rules | specs/protocol/00X-name/spec.md |
+| `specify` | Define specification entities and rules | specs/domain/00X-name/spec.md |
 | `clarify` | Resolve specification ambiguities | Update spec.md |
-| `plan` | Plan specification architecture and sub-specifications | specs/protocol/00X-name/plan.md |
-| `tasks` | Break down specification work | specs/protocol/00X-name/tasks.md |
+| `plan` | Plan specification architecture and sub-specifications | specs/domain/00X-name/plan.md |
+| `tasks` | Break down specification work | specs/domain/00X-name/tasks.md |
 | `implement` | Write specification documents | Create/update spec files |
-| `checklist` | Generate quality checklist for specification | specs/protocol/00X-name/checklists/ |
+| `checklist` | Generate quality checklist for specification | specs/domain/00X-name/checklists/ |
 | `analyze` | Check specification consistency | Analysis report |
 
 **Use Cases**:
@@ -214,7 +214,7 @@ generated-speckit/
 #### protocol/ - Protocol Specifications (SDS Output)
 
 ```
-specs/protocol/
+specs/domain/
 ├── 001-mcp-core-protocol/
 │   ├── spec.md              # Protocol entity definitions
 │   │                        # - Server interface
@@ -348,12 +348,12 @@ Project root
     │                       - Can change toolkit/
     │                       - Version tracking, approval process
     │
-    ├─ change ─────────────> specs/protocol/
+    ├─ change ─────────────> specs/domain/
     └─ change ─────────────> specs/toolkit/
 ```
 
 **Key Principles**:
-1. **specs/protocol/** - Independent protocol specifications, can be published and referenced separately
+1. **specs/domain/** - Independent protocol specifications, can be published and referenced separately
 2. **specs/toolkit/** - Explicitly depends on protocol/, implements specific tools
 3. **changes/** - Manages evolution of both, maintains change history (at project root)
 
@@ -385,7 +385,7 @@ target: protocol/001-mcp-core       # Change target (relative to specs/)
 
 # Create domain specification
 /metaspec.sds.specify "MCP Server Specification"
-# Output: specs/protocol/001-mcp-server-specification/spec.md
+# Output: specs/domain/001-mcp-server-specification/spec.md
 
 # Clarify details
 /metaspec.sds.clarify
@@ -394,7 +394,7 @@ target: protocol/001-mcp-core       # Change target (relative to specs/)
 /metaspec.sds.analyze
 ```
 
-**Output**: `specs/protocol/001-xxx/spec.md` - Pure protocol definition
+**Output**: `specs/domain/001-xxx/spec.md` - Pure protocol definition
 
 #### Phase 2: Toolkit Specification (SDD)
 
@@ -493,7 +493,7 @@ Because Evolution is a **shared** mechanism for SDS and SDD:
 # Phase 1: Define MCP specification (SDS)
 /metaspec.sds.constitution  # Define specification design principles
 /metaspec.sds.specify "MCP Specification Core"
-# → specs/protocol/001-mcp-specification-core/spec.md
+# → specs/domain/001-mcp-specification-core/spec.md
 
 # Phase 2: Develop MCP Parser (SDD)
 /metaspec.sdd.specify "MCP Request Parser"
@@ -520,7 +520,7 @@ Because Evolution is a **shared** mechanism for SDS and SDD:
 - **meta/** - For **speckit developers** (meta layer)
   * Used to develop speckit itself
   * Audience: Developers developing speckits generated by MetaSpec
-  * Output: specs/protocol/, specs/toolkit/
+  * Output: specs/domain/, specs/toolkit/
 
 - **library/generic/** - For **speckit users** (application layer)
   * Used to develop projects using speckit

src/metaspec/templates/meta/evolution/commands/archive.md.j2

@@ -32,7 +32,7 @@ Archive a completed and applied change proposal, moving it to history and finali
 ### 2. Merge spec deltas into main specs
 
 **Update target spec** (based on proposal type):
-- For `--type sds`: Update `specs/protocol/XXX-name/spec.md`
+- For `--type sds`: Update `specs/domain/XXX-name/spec.md`
 - For `--type sdd`: Update `specs/toolkit/XXX-name/spec.md`
 
 **Merge process**:

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

@@ -56,25 +56,25 @@ ls specs/toolkit/XXX-name/analysis/
 
 **For Feature 1 (Protocol Spec)**:
 - **Required**:
-  - `specs/protocol/001-{domain}-protocol/spec.md` (protocol definition)
+  - `specs/domain/001-{domain}-protocol/spec.md` (protocol definition)
   - `/memory/constitution.md` (domain principles)
 - **Optional**:
-  - `specs/protocol/001-{domain}-protocol/checklists/`
+  - `specs/domain/001-{domain}-protocol/checklists/`
 - **Skip**: plan.md, tasks.md (not needed for protocol specs)
 
 **For Feature 2 (Toolkit Spec)**:
 - **Required**:
   - `specs/toolkit/001-toolkit/spec.md` (toolkit definition)
   - `specs/toolkit/001-toolkit/plan.md` (architecture)
   - `specs/toolkit/001-toolkit/tasks.md` (task breakdown)
-  - `specs/protocol/001-{domain}-protocol/spec.md` (dependency!)
+  - `specs/domain/001-{domain}-protocol/spec.md` (dependency!)
   - `/memory/constitution.md` (design principles)
 - **Optional**:
   - `specs/toolkit/001-toolkit/architecture.md`
   - `specs/toolkit/001-toolkit/research.md`
 
 **If Feature 1 missing for Feature 2**: 
-⚠️ **CRITICAL**: "Feature 2 depends on Feature 1 but `specs/protocol/001-*` not found!"
+⚠️ **CRITICAL**: "Feature 2 depends on Feature 1 but `specs/domain/001-*` not found!"
 
 ### 3. Build semantic models
 
@@ -108,7 +108,7 @@ ls specs/toolkit/XXX-name/analysis/
 **For Feature 2 (Toolkit Spec)** - Check dependency on Feature 1:
 
 **Check**:
-1. ✅ Feature 1 exists: `specs/protocol/001-{domain}-protocol/spec.md`
+1. ✅ Feature 1 exists: `specs/domain/001-{domain}-protocol/spec.md`
 2. ✅ Feature 2 declares dependency:
    - Has a "Dependencies" section
    - References "001-{domain}-protocol-spec"
@@ -133,7 +133,7 @@ ls specs/toolkit/XXX-name/analysis/
 ❌ HIGH: Feature 2 Validator doesn't reference Feature 1 validation rules
    → ACTION RECOMMENDED: Update Validator section to reference protocol rules
 
-✅ Feature 1 exists: specs/protocol/001-mcp-protocol-spec/spec.md
+✅ Feature 1 exists: specs/domain/001-mcp-protocol-spec/spec.md
 ✅ Feature 2 declares dependency: "Depends on: 001-mcp-protocol-spec"
 ✅ Validator references Feature 1: "Validates against MCP protocol rules"
 ```