---
description: Define toolkit specification (SDD - Spec-Driven Development)
---

## User Input

```text
$ARGUMENTS
```

You **MUST** consider the user input before proceeding (if not empty).

## Outline

The text the user typed after `/metaspec.sdd.specify` is the **toolkit specification description**. 

**PURPOSE: Toolkit Specification (SDD)** 🎯

This command is for defining **toolkit implementation specifications**:
- Focus: HOW to implement the toolkit
- Output: `specs/toolkit/001-{name}/spec.md`
- Must depend on protocol specs
- Implementation-focused

**NOT for protocol definition** - Use `/metaspec.sds.specify` for that.

Follow this execution flow:

### 1. Determine Toolkit and Load Existing Specification

**Step 1a: Verify Protocol Dependency (REQUIRED)**

```bash
# Check if protocol specs exist
ls specs/protocol/ | grep -E '^[0-9]{3}-'
```

**CRITICAL REQUIREMENT**: Toolkit specs MUST depend on at least one protocol spec.

If no protocol specs exist, **STOP** and show this error:

```
❌ ERROR: Cannot create toolkit without protocol specification

MetaSpec is a Spec-Driven framework. Every toolkit MUST depend on a protocol.

The protocol defines WHAT (domain specification).
The toolkit defines HOW (implementation).

Please run this command first:
  /metaspec.sds.specify "Define {domain} protocol"

Then return to create toolkit with:
  /metaspec.sdd.specify "Create {toolkit} for {domain}"

Why this matters:
- Protocol is the specification (core asset)
- Toolkit is the implementation (supporting tool)
- Without protocol, this becomes a generic code generator
- MetaSpec's value is in spec-driven development
```

**Do not proceed** if no protocol specs exist.

**Step 1b: Generate Toolkit Name**

Based on user input, generate:
- Short name: `{domain}-{component}`
- Example: "mcp-parser", "graphql-validator", "oauth-client"
- Check existing `specs/toolkit/` directory structure

**Step 1c: Find Next Available Number**

```bash
# List existing toolkit specs
ls specs/toolkit/ | grep -E '^[0-9]{3}-' | sort -n
# Find next number (e.g., if 001, 002 exist, use 003)
```

**Step 1d: Load Existing or Create New**

- Check for `specs/toolkit/{number}-{name}/spec.md`
- If exists, load for updating
- If new, create new directory structure

### 2. Gather Toolkit Specification Content

**Focus**: Define how to implement tools to support the protocol.

**Critical Questions**:

1. **Dependencies**: Which protocol specs does this toolkit support?
   - **REQUIRED**: Must reference at least one `protocol/XXX-` spec
   - Example: "Depends on: protocol/001-mcp-core-protocol"
   
2. **Toolkit Purpose**: What does this toolkit do?
   - Example: "Parse and validate MCP server definitions"
   
3. **Implementation Language** (NEW - CRITICAL 🎯):
   - **Primary language**: Python / TypeScript / Go / Rust / Other?
   - **Rationale**: Why this language?
     - Target user community (Python devs, TS/JS devs, etc.)
     - Ecosystem fit (existing tools, libraries)
     - Performance requirements
     - Deployment constraints
   - **Secondary languages**: Any additional language support needed?
   
4. **Required Components** (NEW - CRITICAL 🎯):
   Determine which components are needed for this toolkit:
   
   - [ ] **Parser** - Parse specifications from files
     - Needed if: Users write specs in files (YAML/JSON/TOML)
     - Not needed if: Specs are generated programmatically
   
   - [ ] **Validator** - Validate against protocol rules
     - Needed if: Need to enforce protocol compliance
     - Always recommended for spec-driven toolkits
   
   - [ ] **CLI** - Command-line interface
     - Needed if: Users interact via terminal
     - Provides: init, validate, generate commands
   
   - [ ] **Generator** - Generate code/docs from specs
     - Needed if: Want to automate code generation
     - Examples: Generate TypeScript types, Python classes
   
   - [ ] **SDK/Library** - Programmatic API
     - Needed if: Other tools need to integrate
     - Provides: Python/TS/Go module for importing
   
   **Which are MVP (must have) vs. future enhancements (nice to have)?**
   
5. **Architecture Direction** (NEW 🎯):
   - **Structure**: Monolithic / Modular / Plugin-based?
   - **Dependencies**: What frameworks/libraries?
     - Examples: Pydantic (Python), Zod (TypeScript), encoding/json (Go)
   - **Extensibility**: Plugin system / Hooks / Base classes?
   
6. **Parser Component** (if needed): How will specifications be parsed?
   - Input formats (YAML, JSON, TOML, other)?
   - Output format (Objects, AST, IR)?
   
7. **Validator Component** (if needed): What validation will it perform?
   - Must validate against protocol rules
   - What error messages/codes?
   
8. **CLI Commands** (if needed): What commands will users run?
   - Example: `{toolkit-name} init`, `validate`, `generate`
   - What are the inputs/outputs for each command?

9. **Generator Component** (if needed): What will it generate?
   - Output formats: Code (Python/TS/Go), Docs (MD), Config (JSON/YAML)?
   - Templates: Built-in / User-provided / Both?

10. **SDK/Library** (if needed): Will there be programmatic APIs?
    - Public API surface: What functions/classes?
    - Integration: How will other tools use this?

**Important Notes**:
- This is SDD (Spec-Driven Development) - focus on implementation
- Must explicitly depend on protocol specs
- For protocol definition, use `/metaspec.sds.specify` instead

**If user input is vague**, make informed guesses based on domain standards and document assumptions.

### 3. Generate Toolkit Specification Content

Generate **Toolkit Implementation Specification** with these sections:

#### **Dependencies Section** (REQUIRED - CRITICAL)

**First and foremost**, declare dependencies on protocol specifications:

```markdown
## Dependencies

**Protocol Specifications**:
- **protocol/001-{domain}-protocol** - {Brief description of what protocol 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?

**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
```

**CRITICAL**: This Dependencies section is mandatory. Toolkit without protocol is not a valid speckit.

#### **Toolkit Overview**
```markdown
## Overview

**Name**: {Toolkit Name}
**Version**: {version}
**Status**: Draft | In Development | Stable
**Created**: {date}

**Purpose**: {What this toolkit does}

**Target Protocol**: Implements support for protocol/001-{domain}-protocol

**Primary Use Cases**:
1. {Use case 1}
2. {Use case 2}
3. {Use case 3}

**Example**:
```bash
# How users will use this toolkit
{toolkit-name} init spec.yaml
{toolkit-name} validate spec.yaml
{toolkit-name} generate --output ./generated
```
\```

#### **Implementation Details** (NEW 🎯)
```markdown
## Implementation

### Language & Ecosystem

**Primary Language**: {Python / TypeScript / Go / Rust / Other}

**Rationale**: 
{Why this language was chosen:}
- Target user community: {who will use this}
- Ecosystem fit: {existing tools and libraries}
- Performance considerations: {if relevant}
- Deployment needs: {pip / npm / binary / etc.}

**Key Dependencies**:
- {Framework/library 1}: {Purpose}
- {Framework/library 2}: {Purpose}
- {Framework/library 3}: {Purpose}

### Architecture

**Structure**: {Monolithic / Modular / Plugin-based}

**Core Components**:
- [ ] Parser - {Brief description}
- [ ] Validator - {Brief description}
- [ ] CLI - {Brief description}
- [ ] Generator - {Brief description if included}
- [ ] SDK - {Brief description if included}

**Extensibility**:
{How will users extend this toolkit:}
- Plugin system / Custom validators / Hooks / etc.

**File Structure** (Preliminary):
```
src/
  {package_name}/
    __init__.py         # Package initialization
    models.py           # Data models (if needed)
    parser.py           # Parser component (if needed)
    validator.py        # Validator component (if needed)
    cli.py              # CLI component (if needed)
    generator.py        # Generator component (if needed)
    api.py              # SDK interface (if needed)
```

Note: Actual structure will be refined in `/metaspec.sdd.plan`
\```

#### **Component Specifications**

Define each toolkit component:

##### **Component 1: Parser**

```markdown
### Parser Component

**Purpose**: Parse user specifications into validated objects

**Input Formats**:
- YAML (primary)
- JSON (alternative)
- Python dict (programmatic)

**Output Format**:
- Validated Python object
- AST representation (if needed)

**Parsing Steps**:
1. Load file (YAML/JSON)
2. Validate schema structure
3. Transform to internal representation
4. Return parsed object or errors

**Error Handling**:
- `ParseError`: Invalid YAML/JSON syntax
- `SchemaError`: Missing required fields
- `TypeE Error`: Incorrect field types

**API**:
```python
from {toolkit_name}.parser import parse_spec

# Parse from file
spec = parse_spec("spec.yaml")

# Parse from string
spec = parse_spec(yaml_string, format="yaml")

# Parse from dict
spec = parse_spec(spec_dict, format="dict")
```
\```

##### **Component 2: Validator**

```markdown
### Validator Component

**Purpose**: Validate specifications against protocol rules (from protocol/001-xxx)

**Validation Rules** (Reference protocol spec):
1. {Rule from protocol/001-xxx}
2. {Rule from protocol/001-xxx}
3. {Rule from protocol/001-xxx}

**Validation Levels**:
- **Error**: Violations that prevent usage
- **Warning**: Issues that should be fixed
- **Info**: Suggestions for improvement

**Validation Output**:
```python
ValidationResult(
    valid: bool,
    errors: List[ValidationError],
    warnings: List[ValidationWarning],
    info: List[ValidationInfo]
)
```

**Error Messages**:
- Clear, actionable error messages
- Point to exact location in spec
- Suggest fixes when possible

**API**:
```python
from {toolkit_name}.validator import validate_spec

# Validate parsed spec
result = validate_spec(spec)

if not result.valid:
    for error in result.errors:
        print(f"{error.location}: {error.message}")
```
\```

##### **Component 3: CLI Commands**

**CRITICAL**: CLI commands come from **Toolkit Purpose**, NOT from protocol workflow.

```markdown
### CLI Commands

**Key Distinction**:
- **Slash Commands** → From protocol workflow (define-requirements, create-design)
- **CLI Commands** → From toolkit function (init, check, list, validate)

---

**STEP 1: Define Toolkit Type**

**Question: What type of tool is this toolkit?**

Select primary toolkit type(s):

- [ ] **Generator/Scaffolder** - Creates projects, initializes structures
  - Example: Specify (`specify init`), MetaSpec (`metaspec init`)
  
- [ ] **Environment Checker** - Verifies system setup, dependencies
  - Example: Specify (`specify check`)
  
- [ ] **Validator** - Validates against protocol schemas
  - Example: OpenSpec (`openspec validate`)
  
- [ ] **Query/Reference Tool** - Provides protocol information
  - Example: OpenSpec (`openspec show`, `openspec list`)
  
- [ ] **State Manager** - Manages project/spec state
  - Example: OpenSpec (`openspec update`)
  
- [ ] **Community Platform** - Connects to package registry
  - Example: MetaSpec (`metaspec search`, `metaspec install`)

---

**STEP 2: Derive CLI Commands from Toolkit Purpose**

**CRITICAL**: ❌ **DON'T use fixed command names** (init, validate, list)  
            ✅ **DO derive commands based on toolkit function and domain**

**Why This Matters**:
- CLI commands serve toolkit-specific purposes
- Names should reflect what the toolkit actually does
- Real projects show diverse command naming

---

**CLI Command Derivation Process**:

1. **Identify Toolkit Functions**
   - What does this toolkit DO?
   - Generator: Creates projects/files
   - Validator: Checks compliance
   - Query: Displays information
   - Manager: Tracks/updates state

2. **Match Functions to Command Purposes**
   - Don't copy "init, validate, list"
   - Think: What actions do users need?

3. **Choose Domain-Appropriate Names**
   - Match domain terminology
   - Keep commands intuitive

---

**Real Project CLI Commands** (learn from these):

| Project | Toolkit Type | Actual Commands | Insight |
|---------|-------------|-----------------|---------|
| **Specify** | Generator<br>+ Checker | `init` - Create project<br>`check` - Verify tools | Simple, focused |
| **OpenSpec** | Validator<br>+ Query<br>+ Manager | `validate` - Check proposal<br>`list` - Show proposals<br>`show` - Display details<br>`update` - Sync state | State-management oriented |
| **MetaSpec** | Generator<br>+ Community | `init` - Generate speckit<br>`search` - Find packages<br>`install` - Get from community<br>`contribute` - Share speckit | Community platform |
| **Spec-Kit** | Workflow Tool | No CLI (shell scripts only)<br>`specify.sh`, `plan.sh` | Script-based approach |

**Key Insight**: Commands reflect toolkit purpose, not generic patterns

---

**Command Purpose Guidelines** (NOT fixed names):

| Toolkit Function | Command Purpose | Naming Examples | When to Include |
|-----------------|----------------|-----------------|-----------------|
| **Project Generation** | Create/initialize | `init`, `create`, `new`, `scaffold` | If toolkit creates projects |
| **Environment Setup** | Check prerequisites | `check`, `verify`, `doctor`, `setup` | If toolkit needs environment |
| **Protocol Validation** | Validate compliance | `validate`, `check`, `lint`, `verify` | If protocol has rules |
| **Information Query** | Display data | `list`, `show`, `info`, `get`, `display` | If toolkit manages content |
| **State Management** | Update/sync | `update`, `sync`, `refresh`, `pull` | If toolkit tracks state |
| **Community Integration** | Package operations | `search`, `install`, `publish`, `contribute` | If ecosystem exists |

**Customization Based on Domain**:
```bash
# Generic toolkit → Generic commands
toolkit validate spec.yaml

# Domain-specific → Domain commands  
mcp-toolkit validate-server config.json
api-toolkit check-endpoint spec.yaml
```

---

**Example Derivation - MCP-Speckit**:

```markdown
## Toolkit Type Analysis

**Primary Functions**:
1. Validator (validate MCP server definitions)
2. Query Tool (show MCP protocol reference)
3. Generator (optional: scaffold MCP projects)

**Derived CLI Commands**:

### From Validator function:
✅ validate <file>          # Validate MCP server definition
   --strict                 # Treat warnings as errors
   --format json            # Output format

### From Query Tool function:
✅ show spec [section]      # Display MCP protocol docs
✅ get template <entity>    # Get entity template
✅ list examples            # List available examples

### From Generator function (if needed):
✅ init [project-name]      # Initialize MCP project
   --template server        # Project template

**Customization Decision**:
- Keep generic: `validate`, `init` (standard toolkit operations)
- Or domain-specific: `validate-server`, `init-mcp-project`
- Choice depends on: toolkit scope, user expectations
```

**Result**: 3-6 CLI commands based on toolkit functions, not fixed templates
```

---

**STEP 3: Protocol-Influenced CLI Parameters**

**Protocol content can influence command parameters** (not command names):

**If protocol defines entity types**:
```bash
# Protocol has: Server, Tool, Resource entities
{toolkit-name} show <entity-type>     # show server | tool | resource
{toolkit-name} init <entity-type>     # init server | tool
```

**If protocol has structured sections**:
```bash
# Protocol has: Overview, Entities, Operations, Examples sections
{toolkit-name} docs [section]         # docs entities | docs operations
```

**If protocol defines workflow phases**:
```bash
# Protocol has: Phase 1, Phase 2, Phase 3
{toolkit-name} status                 # Show current phase
{toolkit-name} next                   # Move to next phase
```

**Key Principle**: 
- Protocol influences **parameters and options**
- NOT command names (those come from toolkit purpose)
- Use protocol's actual terminology in parameters

---

**STEP 4: Define CLI Implementation**

**For each derived command, specify**:

```markdown
### Command: {command-name}

**Purpose**: {What this command does}

**Usage**:
\```bash
{toolkit-name} {command} [arguments] [options]
\```

**Arguments**:
- arg1: (required) Description
- arg2: (optional) Description

**Options**:
- --option1: Description
- --option2: Description

**Example**:
\```bash
{toolkit-name} {command} example-arg --option1 value
\```

**Implementation Notes**:
- Uses: {library/framework}
- Output: {format}
- Exit codes: 0 (success), 1 (error)
```

---

**Example: MCP-Speckit CLI Design**

**Toolkit Type**: Validator + Query Tool + Generator

**Derived Commands** (domain-appropriate naming):

```bash
# From Validator type
mcpspeckit validate <file>
  --strict              Treat warnings as errors
  --format json         JSON output

# From Query Tool type  
mcpspeckit show [section]       # Not "get-spec" - more intuitive
  --format markdown              # Show MCP protocol docs

mcpspeckit list [type]           # List entities or examples
  --type servers                 # MCP-specific entity types

mcpspeckit docs <topic>          # Access MCP documentation
  --search keyword               # Search docs

# From Generator type
mcpspeckit init [project-name]
  --template server              # Initialize MCP project
  --ai-provider anthropic        # Configure AI provider
```

**Naming Rationale**:
- ✅ `show` instead of `get-spec` (more intuitive verb)
- ✅ `docs` for documentation access (common pattern)
- ✅ `list` stays generic (standard query command)
- ✅ Parameters reflect MCP domain (`servers`, `server`, `ai-provider`)

**Note**: These CLI commands are **independent tools**, NOT called by Slash Commands.

---

**CLI vs Slash Commands Summary**

**Key Distinction**:
- **CLI Commands**: Independent tools for developers (validate, list, docs)
- **Slash Commands**: AI execution guides (see **Component 4: Slash Commands** for details)

**Relationship**: Separated by design - no direct calls between them.

**CLI Implementation**: typer (Python) or commander (Node.js) with rich formatting.

```

---

##### **Component 4: Slash Commands - Spec-Driven Execution (CRITICAL for AI-Oriented Tools)**

**Component Structure**:
- **Overview**: What Slash Commands are and dual-source architecture
- **[Source 1](#source-1-protocol-derived-commands-custom)**: Protocol-Derived Commands (7-STEP process)
- **[Source 2](#source-2-library-selected-commands-reusable)**: Library-Selected Commands (Selection & Adaptation)

**CRITICAL UNDERSTANDING**: Slash Commands are **NOT** CLI usage manuals. They are **spec-driven execution guides** that embed protocol knowledge and guide AI to produce spec-compliant outputs.

```markdown
### Slash Commands

**What they are**: Spec-driven execution guides with embedded protocol knowledge
**Where they go**: `templates/commands/` directory  
**How AI uses them**: Via `/` prefix in AI chat (Cursor, Windsurf, etc.)
**Core purpose**: Guide AI to **produce outputs that comply with protocol specifications**

**Key Distinction**:
- ❌ **NOT**: "How to call CLI commands" (wrapper documentation)
- ✅ **YES**: "How to execute according to protocol specs" (spec-driven guidance)

**When to Include**:
- ✅ Primary users are AI agents
- ✅ Tool enforces a specific protocol/specification
- ✅ Outputs must comply with validation rules
- ✅ Multi-step workflows require protocol knowledge

---

### 🎯 Dual-Source Architecture (Composable Spec Systems)

**IMPORTANT**: Slash Commands come from **TWO sources** and can be **composed**:

#### Source 1: Protocol-Derived (Custom)
- **From**: SDS protocol specification (`specs/protocol/`)
- **Nature**: Dynamic, protocol-specific, tailored
- **Process**: Analyze protocol → Derive commands
- **Examples**: `get-template`, `validate`, workflow actions

#### Source 2: Library-Selected (Reusable)
- **From**: MetaSpec template library (`library/`)
- **Nature**: Pre-built, domain-specific, reusable
- **Process**: Select specification system → Adapt to toolkit
- **Examples**: Generic SD-X, Spec-Kit workflow, OpenSpec evolution

#### Composition Strategy

```
Choose one or combine:

Option A: Protocol-Only (Custom)
  → Derive all commands from protocol
  → Fully tailored to domain
  → Example: MCP-specific commands

Option B: Library-Only (Reusable)
  → Use pre-built spec system
  → Quick start, proven patterns
  → Example: Generic SD-X workflow

Option C: Composed (Recommended)
  → Base: Library spec system
  → Extension: Protocol-derived commands
  → Example: Generic workflow + MCP entities
```

**MetaSpec's Composability**:
- MetaSpec itself uses `meta/` spec system (16 commands)
- Spec-Kit uses `library/sdd/spec-kit/` spec system
- OpenSpec uses `library/sdd/openspec/` spec system
- Your speckit can choose/compose these systems

---

#### Source 1: Protocol-Derived Commands (Custom)

**Overview**: Derive commands by analyzing your protocol specification and extracting domain-specific terminology.

**STEP 1: Analyze Protocol Specification**

**Before defining Slash Commands**, analyze the SDS protocol specification in `specs/protocol/`.

**Questions to Ask**:

1. **Protocol Complexity**
   - [ ] Does the protocol define complex rules and constraints?
   - [ ] Will AI need to reference these rules repeatedly?
   - **If YES** → Need commands to access protocol knowledge

2. **Entities & Structures**
   - [ ] Does the protocol define multiple entity types?
   - [ ] Do entities have specific structures (schemas, fields, validation)?
   - **If YES** → Need commands to work with entities

3. **Validation Rules**
   - [ ] Does the protocol specify validation constraints?
   - [ ] Must outputs be validated against schemas?
   - **If YES** → Need validation commands

4. **Workflows & Phases**
   - [ ] Does the protocol define a multi-phase workflow?
   - [ ] Are there specific actions in each phase?
   - **If YES** → Analyze workflow type:
     - **Type A (State Machine)**: Abstract states (draft → review → approved)
       → Use navigation commands: `get-workflow`, `next-phase`
     - **Type B (Action Sequence)**: Concrete actions (define → clarify → validate)
       → Each action becomes a command

5. **Examples & Templates**
   - [ ] Does the protocol include examples or templates?
   - [ ] Will AI need to reference these?
   - **If YES** → Need commands to retrieve examples

---

**STEP 2: Derive Command Names from Protocol**

**CRITICAL**: ❌ **DON'T use generic names** (get-spec, get-template, validate)  
            ✅ **DO extract domain-specific names** from protocol terminology

**Why This Matters**:
- Generic names lose domain meaning
- Real projects use domain-specific terminology
- Better developer experience with familiar terms

---

**Command Naming Process**:

1. **Read Protocol Content**
   - Workflow phases: "Define Server", "Configure Endpoints"
   - Entity names: "Server", "Tool", "Resource"
   - Operations: "Initialize", "Validate", "Deploy"

2. **Extract Verb + Noun Pairs**
   - "Define Server" → verb: define, noun: server
   - "Configure Endpoints" → verb: configure, noun: endpoints
   - "Validate Configuration" → verb: validate, noun: configuration

3. **Form Domain-Specific Command Names**
   - Hyphenated: `define-server`, `configure-endpoints`
   - Or use protocol's exact terminology

---

**Real Project Command Naming Patterns**:

| Project | Pattern | Examples | Insight |
|---------|---------|----------|---------|
| **Spec-Kit** | Verb-Noun | `specify-feature`<br>`plan-implementation`<br>`implement-feature` | Workflow actions become commands |
| **OpenSpec** | Domain Verbs | `proposal`<br>`apply`<br>`archive` | Protocol's change management terms |
| **MetaSpec** | Namespaced | `sds.specify`<br>`sdd.clarify`<br>`sdd.plan` | Layered specification system |

**Key Insight**: ❌ No project uses `get-template` or `get-spec` → ✅ All use domain terminology

---

**Command Purpose Categories** (for guidance, NOT fixed names):

| Protocol Contains | Command Purpose | Naming Examples | When to Include |
|------------------|----------------|-----------------|-----------------|
| **Workflow phases** | Execute phase actions | MCP: `define-server`, `configure-tools`<br>API: `create-endpoint`, `test-endpoint` | Always (if workflow exists) |
| **Entity types** | Work with entities | MCP: `init-server`, `add-tool`<br>API: `scaffold-endpoint`, `define-schema` | If 3+ entities |
| **Validation rules** | Validate outputs | MCP: `validate-server`, `check-config`<br>API: `lint-spec`, `verify-endpoint` | If complex rules |
| **Multi-step process** | Navigate process | Project: `next-phase`, `show-roadmap`<br>Deploy: `status`, `rollback` | If state machine workflow |
| **Reference docs** | Access knowledge | Protocol: `show-spec`, `docs server`<br>Standard: `reference`, `help-with` | If complex (20+ pages) |

**Key Principle**: Use protocol's own vocabulary, don't impose generic names

---

**Example**: See **Component 3: Example - MCP-Speckit CLI Design** (line 573) for MCP-Speckit naming examples.

**Quick Reference**:
```markdown
Protocol workflow: "Define Server" → Command: `define-server`
Protocol entity: "Server" → Command: `init-server`
Protocol validation: "Validate Config" → Command: `validate-server`

Key principle: Extract verb+noun from protocol terminology
```

---

**STEP 3: Classify Commands (Slash + CLI/Script Support)**

**CRITICAL**: Slash Commands are for AI execution. CLI/Scripts provide optional support.

**Command Types** (based on real projects: Spec-Kit, OpenSpec, MetaSpec):

| Type | AI Role | Support | Slash? | CLI? | Script? | Example |
|------|---------|---------|--------|------|---------|---------|
| **Pure-Execution** | Produces content | None | ✅ Yes | ❌ No | ❌ No | `define-requirements` |
| **Script-Assisted** | Produces content | Shell scripts | ✅ Yes | ❌ No | ✅ Yes | Spec-Kit's `specify` |
| **CLI-Referenced** | Produces + validates | Independent CLI | ✅ Yes | ✅ Yes | ❌ No | OpenSpec's `proposal` |

**Classification Decision Tree**:

```
For each derived command, ask:

1. Does AI need to produce structured content?
   ✅ YES → Continue to Q2
   ❌ NO → This is likely a pure CLI tool (skip Slash)

2. Does it need file system setup (directories, skeleton)?
   ✅ YES → Script-Assisted (create helper script)
   ❌ NO → Continue to Q3

3. Should output be validated independently?
   ✅ YES → CLI-Referenced (create validate CLI)
   ❌ NO → Pure-Execution (Slash only)
```

**Key Insights from Real Projects**:

- **Spec-Kit**: Uses shell scripts for setup, AI for content
  ```bash
  /speckit.specify → calls create-new-feature.sh → AI fills content
  ```

- **OpenSpec**: AI produces, CLI validates independently
  ```bash
  /openspec.proposal → AI creates → User runs: openspec validate <id>
  ```

- **MetaSpec**: Pure AI execution, CLI for other purposes
  ```bash
  /metaspec.sdd.specify → AI produces spec.md (no CLI needed)
  metaspec init → Separate CLI for generation
  ```

**Classification Result**:

```markdown
For each derived command, classify as:

- **Pure-Execution**: AI produces content → Slash only
  - Example: define-server, create-design (most common)
  
- **Script-Assisted**: Need structure setup → Script + Slash
  - Example: init-project (if creating directories)
  
- **CLI-Referenced**: Need independent validation → CLI + Slash
  - Example: validate command (See **Component 3, STEP 2: Derive CLI Commands from Toolkit Purpose** for CLI design)

**Typical Counts**:
- Slash Commands: 4-8
- Helper Scripts: 1-2 (if Script-Assisted)
- CLI Commands: 3-5 (if CLI-Referenced, defined in Component 3)
```

---

**STEP 4: Implement Support Tools (CLI + Scripts)**

**IMPORTANT**: CLI commands should be fully defined in **Component 3: CLI Commands** first.  
This section covers implementation of support tools specifically for Slash Commands.

**Cross-Reference**: See **Component 3: CLI Commands** (lines 364-643) for complete CLI command specification.

**This section covers**:
- 4a. CLI Commands (CLI-Referenced Pattern only - subset of Component 3)
- 4b. Helper Scripts (Script-Assisted Pattern only)

---

**Implement based on command classification**:

**4a. CLI Commands (CLI-Referenced Pattern)**

**Cross-Reference**: This is a subset of CLI commands defined in **Component 3: CLI Commands** (lines 364-643).

**Context**: When STEP 3 identifies "CLI-Referenced Pattern" commands, implement the associated CLI tools here.

**From Component 3**: Follow the **CLI Command Derivation Process** (Component 3, STEP 1-4) to fully define these CLI commands before implementing.

**Purpose**: Independent tools for validation, querying, display

```markdown
### CLI Implementation Checklist

**Independent CLI Tools** (user calls directly):

Based on your toolkit functions (from **Component 3, STEP 1: Define Toolkit Type**), implement:

- [ ] **Validation**: validate <file>, check, lint
  - Validate against protocol schema
  - Independent verification tool

- [ ] **Information Display**: show [section], docs <topic>, help
  - Display protocol documentation
  - Provide reference information

- [ ] **Query**: list [type], info
  - List available entities/examples
  - Show protocol information

**Naming Reminder**:
- ❌ Don't hardcode: get-spec, get-template, get-example
- ✅ Choose intuitive: show, docs, list, help
- ✅ Or domain-specific: show-mcp-spec, list-servers

**Implementation Guidelines**:
- These are **standalone tools**, not called by Slash Commands
- Focus on validation, querying, displaying
- Should work without AI involvement
- Users call them directly after AI produces content
```

**4b. Helper Scripts (Script-Assisted Only)**

**Purpose**: Set up file structure, create skeletons

```markdown
### Script Implementation Checklist

**Helper Scripts** (called by Slash Commands):
- [ ] scripts/setup-project.sh: Create project structure
- [ ] scripts/init-entity.sh <entity>: Create entity skeleton
- [ ] scripts/check-prerequisites.sh: Verify environment

**Script Guidelines**:
- Keep scripts simple (directory creation, file copying)
- AI does content production, scripts do structure
- Example from Spec-Kit:
  ```bash
  # scripts/setup-project.sh
  mkdir -p specs/ templates/ docs/
  cp templates/spec-template.md specs/
  echo "Structure ready for AI to fill"
  ```
```

**Key Principle**: **Slash Commands don't "call" CLI**. CLI and Scripts are separate support tools.

---

**STEP 5: Create Spec-Driven Slash Commands (All Types)**

**Based on classification in STEP 3**, create appropriate Slash Command templates for each type.

**Reference**: See **STEP 3: Classify Commands** above for command type definitions (Pure-Execution, Script-Assisted, CLI-Referenced).

---

##### Template 1: Pure-Execution Slash Commands (Most Common)

```markdown
# /{toolkit-name}.{command}

## Purpose
[What protocol-compliant output to produce]

## Protocol Specification (EMBEDDED)
**From**: specs/protocol/{XXX}/spec.md

### Entity Structure
[Copy entity definition from protocol]
- field1: type (required) - description
- field2: type (optional) - description
- Constraints: [Protocol constraints]

### Validation Rules
- VR001: {Rule from protocol}
- VR002: {Rule from protocol}

### Examples
[Protocol examples]

## AI Execution Steps
1. **Understand User Intent**
   - Extract key information
   - Map to protocol entity

2. **Apply Protocol Rules**
   - Check constraint 1
   - Ensure constraint 2

3. **Structure Output**
   - Follow entity schema
   - Include required fields

4. **Self-Validate**
   - Verify against protocol rules
   - Check all constraints met

## Output Template
\```json
{
  "field1": "...",  // From protocol
  "field2": "..."   // Validated against VR001
}
\```

## Validation (Optional)
User can validate output independently:
\```bash
{toolkit-name} validate output.json
\```

## Related Commands
- /{toolkit}.get-spec - Reference full protocol (if exists)
```

**Example**: MetaSpec's `/metaspec.sdd.specify`, OpenSpec's `/openspec.proposal`

---

##### Template 2: Script-Assisted Slash Commands (Spec-Kit Pattern)

```markdown
# /{toolkit-name}.{command}

## Purpose
[What to produce, with script handling setup]

## Helper Script
\```bash
scripts/{script-name}.sh --args
\```

**Script Purpose**: Set up file structure, create skeleton

## Protocol Specification (EMBEDDED)
**From**: specs/protocol/{XXX}/spec.md

[Copy relevant protocol sections like Pure-Execution template]

## Execution Flow
1. **Call Helper Script**
   \```bash
   scripts/setup-{entity}.sh --name {entity-name}
   \```
   - Script creates: Directory structure, skeleton files
   - Script outputs: Paths to files AI should fill

2. **AI Produces Content**
   - Read script output (file paths)
   - Load protocol specification
   - Fill skeleton with protocol-compliant content

3. **Verify Structure**
   - Check all required files created
   - Validate against protocol

## Output
- Structure: Created by script
- Content: Produced by AI

## Related Commands
- /{toolkit}.validate - Validate final output
```

**Example**: Spec-Kit's `/speckit.specify` (calls `create-new-feature.sh`)

---

##### Template 3: CLI-Referenced Slash Commands (Validation Reminder)

**Purpose**: Remind AI to suggest CLI validation after production

```markdown
# /{toolkit-name}.validate

## Purpose
Remind AI to suggest validation after producing content

## When to Use
After AI has produced output via Pure-Execution commands

## What AI Should Do
1. Acknowledge content production complete
2. Suggest validation to user:
   \```
   "Content created successfully!
   
   To validate against {protocol-name} schema, run:
     {toolkit-name} validate <file>
   "
   \```

## Available CLI Commands
- `{toolkit-name} validate <file>` - Validate against schema
- `{toolkit-name} get-spec` - View protocol details
- `{toolkit-name} list` - List available entities

## Note
This Slash Command doesn't "call" CLI directly.
It teaches AI to suggest appropriate CLI commands to users.
```

**Example**: After `/mcpspeckit.define-requirements`, AI suggests `mcpspeckit validate requirements.json`

---

**STEP 6: Workflow-Specific Commands (Type B Only)**

**If protocol defines Type B Workflow (Action Sequence)**, these workflow actions become **Pure-Execution Slash Commands**:

```markdown
Protocol Workflow Example:
  phases:
    - Requirements:
        actions:
          - define_requirements   ← Action (verb)
          - clarify_requirements  ← Action (verb)
    - Design:
        actions:
          - create_design         ← Action (verb)
          - review_design         ← Action (verb)

Command Classification:
  - define-requirements → Pure-Execution (AI produces)
  - clarify-requirements → Pure-Execution (AI refines)
  - create-design → Pure-Execution (AI produces)
  - review-design → Pure-Execution (AI reviews)

Each Slash Command contains:
  - Protocol knowledge for that phase
  - Entity structure for that artifact
  - Spec-driven execution steps
  - Validation rules for outputs
  - No CLI needed (AI produces directly)
```

**Judgment Rule**: 
- Workflow step is a **verb/action** → Pure-Execution Slash Command
- Workflow step is a **noun/state** → CLI-Backed navigation commands (`get-workflow`, `next-phase`)

---

**STEP 7: Final Command Inventory**

**Summarize all derived and classified commands**:

```markdown
## Command Inventory

### CLI Commands (Total: X)

**CLI-Backed** (Y commands):
- [ ] get-spec: Read protocol files
- [ ] get-template: Read entity templates
- [ ] validate: Execute validation logic
- [ ] get-workflow: Query workflow state
- [ ] get-example: Read examples

**Hybrid** (Z commands):
- [ ] init: Create project structure

**Total CLI**: X = Y + Z

### Slash Commands (Total: X+N)

**CLI-Backed** (Y commands - matches CLI):
- [ ] /{toolkit}.get-spec.md
- [ ] /{toolkit}.get-template.md
- [ ] /{toolkit}.validate.md
- [ ] /{toolkit}.get-workflow.md
- [ ] /{toolkit}.get-example.md

**Hybrid** (Z commands - matches CLI):
- [ ] /{toolkit}.init.md

**Pure-Execution** (N commands - NO CLI):
- [ ] /{toolkit}.define-requirements.md
- [ ] /{toolkit}.clarify-requirements.md
- [ ] /{toolkit}.create-design.md
- [ ] /{toolkit}.generate-code.md
- ... (from workflow actions)

**Total Slash**: X + N
```

**Key Ratios**:
- CLI commands: 5-10 typical
- Slash commands: 10-20 typical
- Slash > CLI (this is expected!)

**Priority Guide**:
- P0 (Critical): get-spec, get-template, validate, workflow actions
- P1 (Important): get-workflow, get-example, init
- P2 (Skip): info, version (use CLI --help instead)

---

**Design Principles: Spec-Driven Execution**

1. **Embed Protocol Knowledge**
   - ✅ Include entity definitions from protocol
   - ✅ Copy validation rules into commands
   - ✅ Provide protocol examples
   - ❌ Don't just say "call this CLI"

2. **Guide Spec-Compliant Production**
   - ✅ Show how to structure outputs per protocol
   - ✅ Explain how to apply validation rules
   - ✅ Provide output templates from protocol
   - ❌ Don't just describe CLI parameters

3. **Validate Against Protocol**
   - ✅ Include validation checklists from protocol
   - ✅ Self-check steps for AI
   - ✅ Clear compliance criteria
   - ❌ Don't rely on external validation only

**Quality Checklist**:
- [ ] Embeds protocol knowledge (entities, rules, constraints)
- [ ] Guides spec-compliant output production
- [ ] Includes validation rules from protocol
- [ ] Provides protocol-based templates
- [ ] AI can produce compliant output without external reference

**Summary**: Source 1 provides a 7-STEP process to derive custom Slash Commands from your protocol specification, ensuring domain-specific terminology and spec-driven execution.

---

#### Source 2: Library-Selected Commands (Reusable)

**Overview**: Select and adapt pre-built specification systems from MetaSpec's template library.

**Alternative/Complement to Protocol-Derived**: Use pre-built specification systems from MetaSpec library.

**Why Simpler Process?**  
Unlike Source 1 (derive from scratch), Source 2 reuses proven commands. The process is:
1. **Select** appropriate library (based on domain/workflow)
2. **Adapt** variables to your domain
3. **Integrate** into your speckit

This is intentionally simpler than Source 1's 7-STEP derivation process.

---

**Discover Available Libraries**

**Library Location**: MetaSpec GitHub repository

**To explore available specification systems**:

1. **Browse library catalog online**:
   ```
   https://github.com/ACNet-AI/MetaSpec/tree/main/src/metaspec/templates/library
   ```

2. **Read library README**:
   ```
   https://github.com/ACNet-AI/MetaSpec/blob/main/src/metaspec/templates/library/README.md
   ```

3. **View specific library**:
   ```
   https://github.com/ACNet-AI/MetaSpec/tree/main/src/metaspec/templates/library/{library-name}
   ```

**Each library provides**:
- Pre-built Slash Commands
- Proven workflow patterns
- Domain-specific or universal abstractions
- Adaptation guidelines

**Selection Principles**

**Choose library based on**:

1. **Domain Match**
   - Software development → Look for SDD libraries
   - Design/Testing/Documentation → Look for generic/universal libraries
   - Specific protocols → Look for protocol-specific libraries

2. **Abstraction Level**
   - Need pure abstraction → Choose generic/universal
   - Need domain concepts → Choose specialized (e.g., sdd/*)
   - Need protocol-specific → Choose protocol libraries

3. **Workflow Type**
   - Greenfield (from scratch) → Greenfield workflows
   - Brownfield (evolution) → Evolution/change management workflows
   - Both → Compose multiple libraries

4. **Complexity**
   - Simple toolkit → Start with generic
   - Complex domain → Use specialized library
   - Uncertain → Start generic, specialize later

**Quick Reference (Current Libraries)**

**See [library/README.md](https://github.com/ACNet-AI/MetaSpec/blob/main/src/metaspec/templates/library/README.md) for complete catalog.**

**Common libraries include**:

- [`generic/`](https://github.com/ACNet-AI/MetaSpec/tree/main/src/metaspec/templates/library/generic) - Universal SD-X (domain-agnostic)
- [`sdd/spec-kit/`](https://github.com/ACNet-AI/MetaSpec/tree/main/src/metaspec/templates/library/sdd/spec-kit) - Software development (greenfield)
- [`sdd/openspec/`](https://github.com/ACNet-AI/MetaSpec/tree/main/src/metaspec/templates/library/sdd/openspec) - Specification evolution (brownfield)

**As library grows, refer to [online catalog](https://github.com/ACNet-AI/MetaSpec/tree/main/src/metaspec/templates/library) for full list.**

---

**Adaptation Process**

**When using library commands**:

1. **Variable Mapping**
   - Map library variables to your domain terms
   - Example: `{{ entity_type }}` → "API Endpoint"
   - Example: `{{ deliverable }}` → "OpenAPI Schema"
   - See library's README.md on GitHub for all variables

2. **Terminology Adjustment**
   - Replace generic terms with domain-specific ones
   - Maintain command structure and workflow logic
   - Preserve spec-driven execution principles

3. **Add Protocol Context** (if composing)
   - Enhance library commands with protocol knowledge
   - Embed entity definitions and validation rules
   - Result: Library structure + Protocol specifics

**See selected library's README.md on [MetaSpec GitHub](https://github.com/ACNet-AI/MetaSpec/tree/main/src/metaspec/templates/library) for detailed adaptation guidelines.**

---

**Composition Examples**

**Composition Pattern 1: Library + Protocol**

```
Base: Select library (e.g., generic/)
  → Provides workflow commands
  
Extension: Derive from protocol
  → Add entity-specific commands (get-template)
  → Add protocol commands (get-spec, validate)

Result: Combined command set
```

**Composition Pattern 2: Protocol Only**

```
Derive all commands from protocol
  → No library dependency
  → Fully custom to domain
  
Result: Tailored command set
```

**Composition Pattern 3: Library Only**

```
Use library as-is
  → Quick start
  → Adapt variables only
  
Result: Proven workflow pattern
```

---

**Integration with Generator**

**In toolkit specification**, document:

```markdown
### Slash Commands Strategy

**Source**: [Protocol | Library | Composed]

**If Library**: 
- Selected: {library-name} (from MetaSpec library)
- Reference: https://github.com/ACNet-AI/MetaSpec/tree/main/src/metaspec/templates/library/{library-name}
- Rationale: {Why this library}

**If Protocol-Derived**:
- Based on: specs/protocol/{number}-{name}
- Commands needed: {List and rationale}

**If Composed**:
- Base: {library-name} (from MetaSpec)
- Extensions: {Protocol-derived commands}
- Composition rationale: {Why compose}
```

**Generator expectations**:
- Copy selected library from MetaSpec to `templates/commands/`
- Apply variable mappings (cli_name, entity_type, etc.)
- Add protocol-derived commands if specified
- Resolve naming conflicts

---

**Quality Checklist (Library-Selected)**

- [ ] Selected appropriate library for domain
- [ ] Mapped all library variables to domain terms
- [ ] Adapted terminology to match domain
- [ ] Added protocol knowledge where applicable
- [ ] No naming conflicts between library and protocol commands
- [ ] All commands properly prefixed (/{toolkit}.*)

---

**Integration with Generated Speckit**

These Slash Commands (from library and/or protocol) will:
1. Be generated into `templates/commands/` directory
2. Embed protocol knowledge where applicable
3. Provide reusable workflow patterns from library
4. Enable spec-driven development by AI agents
5. Support composition of multiple specification systems

**This demonstrates MetaSpec's Composability**: Specification systems can be selected, adapted, and composed.

**Summary**: Source 2 enables rapid adoption by selecting pre-built specification systems from MetaSpec's library, adapting variables to your domain, and composing with custom commands.

\```

##### **Component 5: Generator (Optional)**

If applicable:

```markdown
### Generator Component

**Purpose**: Generate code/artifacts from validated specs

**Generation Targets**:
- {Target 1}: {Description}
- {Target 2}: {Description}

**Templates**:
- Location: `templates/`
- Format: Jinja2
- Customization: User-overridable

**API**:
```python
from {toolkit_name}.generator import generate

# Generate from spec
generate(spec, output_dir="./output", template="default")
```
\```

#### **Architecture Design**

```markdown
## Architecture

### Module Structure
```
{toolkit_name}/
├── __init__.py
├── parser.py          # Parser component
├── validator.py       # Validator component
├── generator.py       # Generator component (optional)
├── cli.py             # CLI entry point
├── models.py          # Data models
├── exceptions.py      # Custom exceptions
└── templates/         # Templates (if generator exists)
```

### Data Flow
```
Input File
    ↓
  Parser  ───→ Parsed Spec Object
    ↓
Validator ───→ Validation Result
    ↓
Generator ───→ Output Artifacts
```

### Key Classes
- `{Toolkit}Spec`: Main specification object
- `{Toolkit}Parser`: Parser implementation
- `{Toolkit}Validator`: Validator implementation
- `{Toolkit}Generator`: Generator implementation (optional)
\```

#### **Dependencies and Requirements**

```markdown
## Technical Requirements

### Language
- Python 3.9+

### Core Dependencies
- `pydantic`: Data validation and settings management
- `typer`: CLI framework
- `pyyaml` or `ruamel.yaml`: YAML parsing
- `jinja2`: Template engine (if generator)
- `rich`: Terminal formatting

### Development Dependencies
- `pytest`: Testing framework
- `mypy`: Type checking
- `ruff`: Linting and formatting
- `coverage`: Code coverage

### Optional Dependencies
- {Additional deps based on specific needs}
```

#### **Validation Strategy**

```markdown
## Validation Strategy

### Unit Tests
- Test each component independently
- Mock external dependencies
- Aim for 80%+ coverage

### Integration Tests
- Test component interactions
- Test CLI commands end-to-end
- Test with real specification files

### Validation Cases
1. **Parser Tests**:
   - Valid YAML/JSON parsing
   - Invalid syntax handling
   - Edge cases (empty files, large files)

2. **Validator Tests**:
   - Each validation rule from protocol spec
   - Error message quality
   - Multiple errors handling

3. **CLI Tests**:
   - Each command with various options
   - Error handling
   - Help messages

4. **Generator Tests** (if applicable):
   - Template rendering
   - Output file creation
   - Custom template handling

### Validation Data
- Sample valid specifications
- Sample invalid specifications
- Edge cases

**Validation Location**: `tests/` directory
```

#### **Success Criteria**

```markdown
## Success Criteria

### MVP Features
- ✅ {Feature 1}
- ✅ {Feature 2}
- ✅ {Feature 3}

### Quality Metrics
- All tests pass
- 80%+ code coverage
- No critical linting errors
- Type hints complete (mypy passes)

### Documentation
- README with quickstart
- API documentation
- CLI help messages complete
- Example specifications

### User Experience
- Clear error messages
- Fast execution (< 1s for typical specs)
- Good CLI UX (progress bars, colors)
```

### 4. Write Specification File

**Location**: `specs/toolkit/{number}-{name}/spec.md`

**Structure**:
```markdown
# {Toolkit Name}

**Version**: {version}
**Status**: Draft | In Development | Stable
**Created**: {date}

## Dependencies

{Dependencies from Section 3: Generate Toolkit Specification Content}

## Overview

{Overview from Section 3: Generate Toolkit Specification Content}

## Components

{Component specifications from Section 3: Generate Toolkit Specification Content}

## Architecture

{Architecture design from Section 3: Generate Toolkit Specification Content}

## Technical Requirements

{Requirements from Section 3: Generate Toolkit Specification Content}

## Validation Strategy

{Validation strategy from Section 3: Generate Toolkit Specification Content}

## Success Criteria

{Success criteria from Section 3: Generate Toolkit Specification Content}

## Implementation Plan

See `plan.md` (created via `/metaspec.sdd.plan`)

## Tasks

See `tasks.md` (created via `/metaspec.sdd.tasks`)
```

### 5. Success Output

```
✅ Toolkit specification created/updated:

📁 Location:
   specs/toolkit/{number}-{name}/spec.md

🎯 Toolkit: {Toolkit Name} v{version}

📦 Dependencies:
   → protocol/{dependency-1}
   → protocol/{dependency-2}

🔧 Components: {count} components defined
   - {Component 1}
   - {Component 2}
   ...

✓ Architecture: Defined
✓ Validation Strategy: Defined
✓ Success Criteria: Defined

🔄 Next steps:
1. Review toolkit specification
2. Run /metaspec.sdd.plan to create implementation plan
3. Run /metaspec.sdd.tasks to break down work
4. Run /metaspec.sdd.implement to start building
```

## Best Practices

### Toolkit Specification Focus

✅ **DO**:
- Define HOW to implement the toolkit
- Specify Parser, Validator, CLI, Generator
- Reference protocol specs explicitly
- Include architecture and validation strategy
- Focus on user experience

❌ **DON'T**:
- Redefine the protocol (belongs in protocol specs)
- Skip dependency declarations
- Mix protocol and toolkit concerns
- Over-specify implementation details

### Dependency Management

- **Always** declare protocol dependencies at the top
- Reference specific protocol/XXX- specs
- Document which protocol features are supported
- Note version compatibility if relevant

### Component Design

- Keep components modular and testable
- Clear interfaces between components
- Minimal coupling
- Support both CLI and programmatic usage

### Progressive Enhancement

Start with MVP:
1. Parser (basic)
2. Validator (core rules)
3. CLI (init + validate)

Add later:
4. Generator
5. Advanced CLI features
6. SDK/Library enhancements

## Constitution Check

Before finalizing, verify against `memory/constitution.md`:

```bash
# Check toolkit spec against constitution
grep -A 5 "Minimal Viable Abstraction" memory/constitution.md
grep -A 5 "AI-First Design" memory/constitution.md
```

**Ensure**:
- Start with minimal viable toolkit
- Components are clearly defined
- Architecture supports extension
- Testing is built-in from start

## Troubleshooting

**If no protocol specs exist**:
→ Prompt user to create protocol spec first with `/metaspec.sds.specify`

**If toolkit seems too complex**:
→ Break into multiple toolkit specs (e.g., parser-only, validator-only)

**If unclear architecture**:
→ Use `/metaspec.sdd.clarify` to resolve design questions

**If components overlap**:
→ Review separation of concerns, consider merging or splitting

**If validation strategy unclear**:
→ Focus on contract testing at component boundaries
