Skip to content

Commit f2b5060

Browse files
committed
docs: fix redundancy and inconsistencies in documentation
- Remove duplicate 'Protocol relationships' section in AGENTS.md (line 198-202 duplicated line 170-183) - Fix anchor links: 'Two-Feature Architecture' -> 'SDS + SDD Separation' - Add numbering strategy explanation for recursive protocol hierarchy - Update command counts: 16 -> 19 commands (8 SDS + 8 SDD + 3 Evolution) - Add missing SDS commands in README.md: plan, tasks, implement - Ensure consistency between AGENTS.md and README.md
1 parent 633d767 commit f2b5060

File tree

2 files changed

+20
-13
lines changed

2 files changed

+20
-13
lines changed

AGENTS.md

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ Developer (validates MCP servers against spec)
5454

5555
**This means**: MetaSpec is not just "spec-driven development" - it's a framework that **generates speckits** (spec-driven toolkits) for any domain.
5656

57-
**See [Recommended Practice: Two-Feature Architecture](#recommended-practice-two-feature-architecture) in MetaSpec Commands section for how speckits separate protocol specs from implementation.**
57+
**See [Recommended Practice: SDS + SDD Separation](#recommended-practice-sds--sdd-separation) in MetaSpec Commands section for how speckits separate protocol specs from implementation.**
5858

5959
---
6060

@@ -195,13 +195,14 @@ cd specs/protocol/003-payment-processing/
195195
/metaspec.sds.implement → Creates 013-015
196196
```
197197

198-
**Protocol relationships** (logical, not physical):
199-
- **Parent → Child**: Parent's `spec.md` lists sub-protocols in "Sub-Specifications" table
200-
- **Child → Parent**: Child's frontmatter declares `parent: {parent-id}`
201-
- **Parent chain**: Tracked in frontmatter, displayed as breadcrumb in child's `spec.md`
202-
- **All protocols are sibling directories**: Relationships exist in metadata, not file structure
198+
**Numbering strategy**:
199+
- Root protocol starts at 001
200+
- First-level children: 002-009 (reserve 001 for root)
201+
- Second-level children: 010-099 (e.g., 003's children are 013-015)
202+
- Third-level children: 100-999
203+
- Benefits: Clear hierarchy, flexible expansion, easy identification
203204

204-
**See [Recommended Practice: Two-Feature Architecture](#recommended-practice-two-feature-architecture) for protocol + toolkit separation.**
205+
**See [Recommended Practice: SDS + SDD Separation](#recommended-practice-sds--sdd-separation) for protocol + toolkit separation.**
205206

206207
---
207208

@@ -772,7 +773,7 @@ See [Decision Guide](docs/evolution-guide.md) for when to use which.
772773
773774
This section describes **how to generate a speckit** using `metaspec init`.
774775
775-
**Note**: This is different from **developing a speckit** (which uses MetaSpec commands and [Two-Feature Architecture](#recommended-practice-two-feature-architecture) practice).
776+
**Note**: This is different from **developing a speckit** (which uses MetaSpec commands and [SDS + SDD Separation](#recommended-practice-sds--sdd-separation) practice).
776777
777778
### Two Workflows
778779

README.md

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -182,12 +182,12 @@ cd my-speckit
182182
my-speckit info # Use directly (no metaspec prefix!)
183183

184184
# Generated speckits include built-in MetaSpec commands (AI-assisted development)
185-
# MetaSpec Commands: /metaspec.sds.*, /metaspec.sdd.*, /metaspec.* (16 commands total)
185+
# MetaSpec Commands: /metaspec.sds.*, /metaspec.sdd.*, /metaspec.* (19 commands total)
186186
```
187187

188188
**Key Principle**: MetaSpec is a **generator**, not a runtime. Generated speckits are independent tools.
189189

190-
**Built-in MetaSpec Workflow**: Every speckit includes 16 MetaSpec commands for complete development lifecycle (5 SDS + 8 SDD + 3 Evolution)
190+
**Built-in MetaSpec Workflow**: Every speckit includes 19 MetaSpec commands for complete development lifecycle (8 SDS + 8 SDD + 3 Evolution)
191191

192192
**Iteration-Aware Design**: Commands check for existing output and support update/new/append modes, preserving history and tracking progress across iterations ([Constitution Principle #6](memory/constitution.md#6-iteration-aware-design))
193193

@@ -245,7 +245,7 @@ MetaSpec is designed for AI agents with strong reasoning capabilities. Speckit c
245245

246246
| Tool | Purpose | Built-in? | Access Method |
247247
|------|---------|-----------|--------------|
248-
| **MetaSpec Commands** | Complete spec-driven workflow (16 commands) | ✅ Yes | `/metaspec.sds.*`, `/metaspec.sdd.*`, `/metaspec.*` slash commands in generated speckits |
248+
| **MetaSpec Commands** | Complete spec-driven workflow (19 commands) | ✅ Yes | `/metaspec.sds.*`, `/metaspec.sdd.*`, `/metaspec.*` slash commands in generated speckits |
249249

250250
**Complete Workflow**:
251251

@@ -256,10 +256,13 @@ metaspec init my-spec-kit
256256
# 2️⃣ DEVELOP: Use built-in MetaSpec slash commands (no installation needed)
257257
cd my-spec-kit
258258

259-
# SDS Commands (5) - Define protocol specification
259+
# SDS Commands (8) - Define protocol specification
260260
# /metaspec.sds.constitution - Define protocol principles
261261
# /metaspec.sds.specify - Define protocol entities and operations
262262
# /metaspec.sds.clarify - Resolve protocol ambiguities
263+
# /metaspec.sds.plan - Plan protocol architecture and sub-specifications
264+
# /metaspec.sds.tasks - Break down protocol specification work
265+
# /metaspec.sds.implement - Write protocol specification documents
263266
# /metaspec.sds.checklist - Generate quality checklist for protocol
264267
# /metaspec.sds.analyze - Check protocol consistency
265268

@@ -352,6 +355,9 @@ pip install -e .
352355
# Phase 1: Define protocol (SDS)
353356
# /metaspec.sds.constitution - Define protocol principles
354357
# /metaspec.sds.specify - Define protocol entities and operations
358+
# /metaspec.sds.plan - Plan protocol architecture (if complex)
359+
# /metaspec.sds.tasks - Break down specification work
360+
# /metaspec.sds.implement - Write protocol specification documents
355361
# /metaspec.sds.analyze - Check protocol consistency
356362

357363
# Phase 2: Develop toolkit (SDD)
@@ -432,7 +438,7 @@ uv run mypy src/metaspec # Type check
432438

433439
**v0.1.0** - Alpha Release 🎉
434440

435-
Core features complete: YAML validation, multi-domain generation, CLI tools, AI agent support, built-in MetaSpec commands (16 commands: 5 SDS + 8 SDD + 3 Evolution), unified spec interface.
441+
Core features complete: YAML validation, multi-domain generation, CLI tools, AI agent support, built-in MetaSpec commands (19 commands: 8 SDS + 8 SDD + 3 Evolution), unified spec interface.
436442

437443
---
438444

0 commit comments

Comments
 (0)