Skip to content

Commit c174e4a

Browse files
committed
docs: unify terminology in template files
- templates/README.md: Update SDS command descriptions - 'protocol specification' → 'domain specification' - 'protocol principles' → 'specification design principles' - SDS command templates: - analyze.md.j2: Update all protocol references - checklist.md.j2: Batch replace protocol → specification - constitution.md.j2: Update standard principles descriptions
1 parent 49efa41 commit c174e4a

File tree

4 files changed

+35
-35
lines changed

4 files changed

+35
-35
lines changed

src/metaspec/templates/README.md

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -121,22 +121,22 @@ Development methodologies organized by lifecycle:
121121

122122
### `meta/` - MetaSpec Three-Layer Architecture
123123

124-
**Purpose**: AI-assisted workflow for developing the speckit itself using a three-layer command architecture that separates protocol specification from toolkit development.
124+
**Purpose**: AI-assisted workflow for developing the speckit itself using a three-layer command architecture that separates domain specification from toolkit development.
125125

126126
#### Three Layers
127127

128128
##### `meta/sds/commands/` - Spec-Driven Specification (8 commands)
129129

130-
**Purpose**: Define domain protocol specifications
130+
**Purpose**: Define domain specifications
131131

132-
- `constitution.md.j2` - Define protocol design principles
133-
- `specify.md.j2` - Define protocol entities, operations, validation rules
134-
- `clarify.md.j2` - Resolve protocol ambiguities
135-
- `plan.md.j2` - Plan protocol architecture and sub-specifications
136-
- `tasks.md.j2` - Break down protocol specification work
137-
- `implement.md.j2` - Write protocol specification documents
138-
- `checklist.md.j2` - Generate quality checklist for protocol specification
139-
- `analyze.md.j2` - Check protocol consistency
132+
- `constitution.md.j2` - Define specification design principles
133+
- `specify.md.j2` - Define specification entities, operations, validation rules
134+
- `clarify.md.j2` - Resolve specification ambiguities
135+
- `plan.md.j2` - Plan specification architecture and sub-specifications
136+
- `tasks.md.j2` - Break down specification work
137+
- `implement.md.j2` - Write specification documents
138+
- `checklist.md.j2` - Generate quality checklist for specification
139+
- `analyze.md.j2` - Check specification consistency
140140

141141
**Generated to**: `.metaspec/commands/metaspec.sds.*`
142142
**Works with**: `specs/protocol/` directory
@@ -219,10 +219,10 @@ my-speckit/
219219
```bash
220220
cd my-speckit
221221

222-
# Phase 1: Define protocol (SDS)
223-
/metaspec.sds.constitution # Define protocol principles
224-
/metaspec.sds.specify # Create protocol specifications
225-
/metaspec.sds.analyze # Check protocol consistency
222+
# Phase 1: Define specification (SDS)
223+
/metaspec.sds.constitution # Define specification design principles
224+
/metaspec.sds.specify # Create domain specifications
225+
/metaspec.sds.analyze # Check specification consistency
226226

227227
# Phase 2: Develop toolkit (SDD)
228228
/metaspec.sdd.constitution # Define toolkit principles

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

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
description: Perform protocol specification quality analysis - read-only analysis for protocol consistency
2+
description: Perform specification quality analysis - read-only analysis for specification consistency
33
---
44

55
## User Input
@@ -12,9 +12,9 @@ You **MUST** consider the user input before proceeding (if not empty).
1212

1313
## Goal
1414

15-
Identify inconsistencies, ambiguities, and gaps in protocol specifications. **READ-ONLY** analysis - no file modifications.
15+
Identify inconsistencies, ambiguities, and gaps in domain specifications. **READ-ONLY** analysis - no file modifications.
1616

17-
**Focus**: Protocol specification quality (WHAT the protocol is), NOT toolkit implementation (HOW to implement).
17+
**Focus**: Domain specification quality (WHAT the specification is), NOT toolkit implementation (HOW to implement).
1818

1919
## Operating Constraints
2020

@@ -447,16 +447,16 @@ Would you like me to suggest concrete fixes for the top 5 issues?
447447

448448
## Important Notes
449449

450-
1. **Protocol-Focused Analysis**
451-
- Only analyze protocol specifications
450+
1. **Specification-Focused Analysis**
451+
- Only analyze domain specifications
452452
- Do NOT check toolkit implementation details
453453
- Do NOT reference plan.md, tasks.md, or src/ code
454-
- Focus: WHAT the protocol is, not HOW to implement it
454+
- Focus: WHAT the specification is, not HOW to implement it
455455

456456
2. **Constitution Authority**
457457
- Constitution violations are always CRITICAL
458-
- Protocol must adjust, not constitution
459-
- Protocol-specific principles apply
458+
- Specification must adjust, not constitution
459+
- Specification-specific principles apply
460460

461461
3. **Read-Only Analysis**
462462
- No file modifications

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,17 @@
11
---
2-
description: Generate quality checklist for protocol specification - validates protocol quality, NOT implementation correctness
2+
description: Generate quality checklist for specification - validates protocol quality, NOT implementation correctness
33
---
44

55
## Checklist Purpose: "Unit Tests for Protocol Specifications"
66

7-
**CRITICAL CONCEPT**: Checklists are **UNIT TESTS FOR SPECIFICATION WRITING** - they validate the quality, clarity, and completeness of protocol specifications.
7+
**CRITICAL CONCEPT**: Checklists are **UNIT TESTS FOR SPECIFICATION WRITING** - they validate the quality, clarity, and completeness of specifications.
88

99
**NOT for implementation verification**:
1010
- ❌ "Verify parser handles protocol correctly"
1111
- ❌ "Test validator catches protocol violations"
1212
- ❌ "Confirm toolkit implements protocol"
1313

14-
**FOR protocol specification quality validation**:
14+
**FOR specification quality validation**:
1515
- ✅ "Are all protocol entities clearly defined? [Completeness]"
1616
- ✅ "Are operation schemas consistently specified? [Consistency]"
1717
- ✅ "Are error codes documented with examples? [Completeness]"
@@ -213,7 +213,7 @@ Test if protocol follows constitution principles:
213213
- Are domain standards followed? [Consistency, Constitution]
214214

215215
#### **Ambiguities & Gaps**
216-
Test for protocol specification issues:
216+
Test for specification issues:
217217
- Are vague terms quantified ("valid", "appropriate")? [Ambiguity]
218218
- Are conflicting requirements identified? [Conflict]
219219
- Are missing definitions noted? [Gap]
@@ -344,7 +344,7 @@ Test for protocol specification issues:
344344
- [ ] CHK003 - Confirm toolkit CLI works with protocol
345345
```
346346

347-
**✅ CORRECT - Testing protocol specification quality**:
347+
**✅ CORRECT - Testing specification quality**:
348348
```markdown
349349
- [ ] CHK001 - Are protocol parsing requirements specified? [Completeness, Spec §Parser Requirements]
350350
- [ ] CHK002 - Are protocol validation rules documented? [Completeness, Spec §Validation Rules]
@@ -376,7 +376,7 @@ Test for protocol specification issues:
376376

377377
🎯 Purpose:
378378
This checklist validates the quality of protocol entity definitions in spec.md.
379-
It does NOT test if toolkit implements protocol, but whether the protocol specification is:
379+
It does NOT test if toolkit implements protocol, but whether the specification is:
380380
- Complete (all entities defined)
381381
- Clear (types, constraints explicit)
382382
- Consistent (follows constitution)

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

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ Follow this execution flow:
3939

4040
### 3. Derive protocol-specific principles
4141

42-
Based on the user input and protocol domain, populate these **standard protocol principles**:
42+
Based on the user input and specification domain, populate these **standard specification design principles**:
4343

4444
#### **I. Entity Clarity**
4545
- Entity definitions are complete and unambiguous
@@ -94,8 +94,8 @@ Based on the user input and protocol domain, populate these **standard protocol
9494
- `[PROTOCOL_NAME]` - e.g., "MCP", "OpenAPI", "GraphQL"
9595
- `[PROTOCOL_DOMAIN]` - e.g., "AI Model Communication", "API Specification", "Data Query"
9696
- `[PRIMARY_ENTITIES]` - e.g., "Server, Tool, Resource", "Path, Operation, Schema"
97-
- `[PRINCIPLE_N_NAME]` - Use standard protocol principles above
98-
- `[PRINCIPLE_N_DESCRIPTION]` - Detailed description with protocol-specific examples
97+
- `[PRINCIPLE_N_NAME]` - Use standard specification design principles above
98+
- `[PRINCIPLE_N_DESCRIPTION]` - Detailed description with specification-specific examples
9999
- `[GOVERNANCE_RULES]` - How to amend constitution, specification review process
100100
- `[CONSTITUTION_VERSION]` - Semantic versioning (start at 1.0.0)
101101
- `[RATIFICATION_DATE]` - Today's date (ISO 8601: YYYY-MM-DD)
@@ -203,7 +203,7 @@ Before finalizing:
203203
- [ ] No remaining `[PLACEHOLDER]` tokens
204204
- [ ] Version follows semantic versioning
205205
- [ ] Dates in ISO 8601 format (YYYY-MM-DD)
206-
- [ ] All 6 standard protocol principles present
206+
- [ ] All 6 standard specification design principles present
207207
- [ ] Each principle has clear description and rationale
208208
- [ ] Principles are verifiable (can check spec compliance)
209209
- [ ] Governance section includes amendment process
@@ -240,7 +240,7 @@ Provide:
240240
🔄 Next steps:
241241
1. Review the constitution in /memory/protocol-constitution.md
242242
2. Use /metaspec.sds.specify to define protocol entities aligned with these principles
243-
3. Reference these principles during protocol design
243+
3. Reference these principles during specification design
244244

245245
💡 Suggested commit message:
246246
docs: adopt protocol constitution v[VERSION] ([principle summary])
@@ -254,7 +254,7 @@ Provide:
254254
- Focus on entity definitions, validation rules, operation interfaces
255255

256256
2. **Standard vs Domain-Specific Principles**
257-
- Always include the 6 standard protocol principles
257+
- Always include the 6 standard specification design principles
258258
- Add domain-specific principles as needed (e.g., "RESTful Conventions" for APIs)
259259
- Don't remove standard principles without strong justification
260260

@@ -265,7 +265,7 @@ Provide:
265265
- Good: "Entity `Tool` must specify `name` (string, required), `description` (string, required), `inputSchema` (JSON Schema, required)"
266266

267267
4. **Specification-First Language**
268-
- Write for protocol designers reading this document
268+
- Write for specification designers reading this document
269269
- Use imperative language (MUST, SHOULD, MAY)
270270
- Avoid ambiguity ("usually", "typically" → specify exact rules)
271271
- Include anti-patterns (what NOT to specify)

0 commit comments

Comments
 (0)