# Toolkit Specification: [TOOLKIT_NAME]

**Created**: [DATE]  
**Status**: Draft  
**Domain**: [TOOLKIT_DOMAIN]  
**Input**: "$ARGUMENTS"

---

## Toolkit Overview

**Purpose**: [What this toolkit does - one sentence]

**Target Domain**: [Domain name, e.g., API Testing, Design Systems, Infrastructure]

**Primary Use Cases**:
1. [Use case 1]
2. [Use case 2]
3. [Use case 3]

**Example Scenario**:
```
[Show a brief scenario of how users would use this toolkit]
Example: "Developer writes API test spec in test.yaml, validates it, then executes tests against staging API"
```

---

## User Journey Analysis

**Purpose**: Understand who uses this toolkit, their goals, and derive features from real scenarios.

### Primary Users

**User Distribution**:
- [Percentage]% AI Agents (e.g., Claude, GitHub Copilot, Cursor)
- [Percentage]% Human Developers

**User Characteristics**:
- **AI Agents**: [Skill level, context, limitations]  
  Example: "AI agents need clear rules, examples, and structured commands"
- **Human Developers**: [Skill level, experience, goals]  
  Example: "Developers need fast validation, clear error messages, and good docs"

---

### Key Scenarios

**Scenario 1: [Scenario Name]**
- **User**: [AI Agent | Human Developer | Both]
- **Context**: [When does this happen?]
- **Goal**: [What does the user want to achieve?]
- **Pain Point**: [What problem are they facing?]
- **Desired Experience**: [What would make this easy?]
- **Required Features**: [Feature 1, Feature 2, Feature 3]

**Example**:
```
Scenario: AI Agent generates specification from natural language
- User: AI Agent (Claude in Cursor)
- Context: Developer describes requirement in chat
- Goal: Generate valid specification file
- Pain Point: AI doesn't know domain rules
- Desired Experience: AI accesses specification reference, gets template, validates output
- Required Features: show-spec command, get-template command, validate CLI
```

---

**Scenario 2: [Scenario Name]**
- **User**: [AI Agent | Human Developer | Both]
- **Context**: [When does this happen?]
- **Goal**: [What does the user want to achieve?]
- **Pain Point**: [What problem are they facing?]
- **Desired Experience**: [What would make this easy?]
- **Required Features**: [Feature 1, Feature 2, Feature 3]

---

**Scenario 3: [Scenario Name]**
- **User**: [AI Agent | Human Developer | Both]
- **Context**: [When does this happen?]
- **Goal**: [What does the user want to achieve?]
- **Pain Point**: [What problem are they facing?]
- **Desired Experience**: [What would make this easy?]
- **Required Features**: [Feature 1, Feature 2, Feature 3]

---

[Add 2-3 more scenarios as needed for complete coverage]

---

### Derived Features

**Feature Categorization**:
- **Information Access**: Help users understand rules and constraints
- **Content Generation**: Help users create specifications
- **Validation**: Help users verify correctness
- **Developer Experience**: Documentation, error messages, examples

**Priority Matrix**:

**P0 (Must Have)** - Critical for core workflows:
- [Feature 1]: [Why critical] (Scenarios: [1, 3])
- [Feature 2]: [Why critical] (Scenarios: [1, 2, 3])
- [Feature 3]: [Why critical] (Scenarios: [2])

**P1 (Should Have)** - Important for good UX:
- [Feature 4]: [Why important] (Scenarios: [2, 3])
- [Feature 5]: [Why important] (Scenarios: [3])

**P2 (Nice to Have)** - Enhancement for advanced users:
- [Feature 6]: [Why helpful] (Scenarios: [1])

**Example**:
```
P0 (Must Have):
- Specification reference system: AI needs rules before generating (Scenarios: 1, 3)
- Template system: Users need starting points (Scenarios: 1, 2)
- Validation CLI: Critical for both AI and developers (All scenarios)

P1 (Should Have):
- Error explanation: Helps users fix issues quickly (Scenarios: 2, 3)
- Interactive wizard: Reduces learning curve (Scenarios: 2)

P2 (Nice to Have):
- Auto-fix suggestions: Convenience for simple errors (Scenarios: 3)
```

---

### Command Design Rationale

**CLI Commands** (derived from scenarios):
- `init`: [Why this command exists] → Addresses Scenario [N]
- `validate`: [Why this command exists] → Addresses Scenario [N]
- `[command3]`: [Why this command exists] → Addresses Scenario [N]

**Slash Commands** (for AI agents):
- `/[toolkit].show-spec`: [Why this command exists] → Addresses Scenario [N]
- `/[toolkit].get-template`: [Why this command exists] → Addresses Scenario [N]
- `/[toolkit].[command3]`: [Why this command exists] → Addresses Scenario [N]

**Templates** (identified from scenarios):
- `basic-[entity].yaml`: [Why needed] → Used in Scenario [N]
- `advanced-[entity].yaml`: [Why needed] → Used in Scenario [N]

**Example**:
```
CLI Commands:
- init: Quick project setup for developers → Scenario 2
- validate: Critical verification for both AI and humans → All scenarios
- docs: Reference for developers → Scenario 2

Slash Commands:
- /mcpspeckit.show-spec: AI needs rules before generating → Scenario 1
- /mcpspeckit.get-template: AI needs starting structure → Scenario 1
- /mcpspeckit.validate-json: AI needs to check output → Scenario 1, 3

Templates:
- basic-server.yaml: Starting point for simple cases → Scenario 1, 2
- advanced-server.yaml: Complete example with all features → Scenario 2
```

---

### Scenario Coverage Matrix

| Scenario | CLI Commands | Slash Commands | Templates | Priority |
|----------|--------------|----------------|-----------|----------|
| Scenario 1 | validate | show-spec, get-template | basic-*.yaml | P0 |
| Scenario 2 | init, validate, docs | - | basic-*.yaml, advanced-*.yaml | P0 |
| Scenario 3 | validate | validate-json, explain-error | - | P0 |

**Coverage Verification**:
- ✅ All P0 scenarios have complete feature support
- ✅ Every feature traces back to at least one scenario
- ✅ No arbitrary features (all scenario-driven)

---

## Specification Types

### [Specification Type 1]

**Purpose**: [What this spec type is for]

**File Format**: YAML | JSON | Markdown | TOML

**Example**:
```yaml
[Show minimal example of this spec type]
```

**When to use**: [Scenarios where users would create this spec type]

**Validation**: [What makes this spec type valid]

---

### [Specification Type 2] *(if applicable)*

**Purpose**: [What this spec type is for]

**File Format**: YAML | JSON | Markdown | TOML

**Example**:
```yaml
[Show minimal example]
```

**When to use**: [Scenarios]

---

## Entity Definitions

### [PRIMARY_ENTITY]

**Description**: [What this entity represents in the domain]

**Fields**:

| Field | Type | Required | Description | Example | Constraints |
|-------|------|----------|-------------|---------|-------------|
| [field_1] | string | Yes | [Description] | `"example"` | [Constraints] |
| [field_2] | string | Yes | [Description] | `"example"` | [Constraints] |
| [field_3] | number | No | [Description] | `42` | [Constraints] |
| [field_4] | array | No | [Description] | `["item1"]` | [Constraints] |
| [field_5] | object | No | [Description] | `{key: "value"}` | [Constraints] |

**Validation Rules**:
- **VR-001**: [Rule 1 - e.g., "field_1 must match pattern ^[a-z-]+$"]
- **VR-002**: [Rule 2 - e.g., "field_2 must be one of: value1, value2, value3"]
- **VR-003**: [Rule 3 - e.g., "if field_3 is provided, it must be > 0"]

**Domain Constraints**:
- [Constraint 1 - e.g., "HTTP methods follow RFC 7231"]
- [Constraint 2 - e.g., "Status codes must be in 100-599 range"]
- [Constraint 3 - e.g., "Endpoints must start with /"]

**Example Entity Instance**:
```yaml
[Show complete example of this entity]
```

---

### [SECONDARY_ENTITY] *(if applicable)*

**Description**: [What this entity represents]

**Fields**:

| Field | Type | Required | Description | Example |
|-------|------|----------|-------------|---------|
| [field_1] | string | Yes | [Description] | `"example"` |

**Validation Rules**:
- [Rules for this entity]

**Relationship to [PRIMARY_ENTITY]**:
[How this entity relates to primary entity]

---

## Workflow Definitions

### [WORKFLOW_1]

**Purpose**: [What this workflow accomplishes]

**User Goal**: [What user wants to achieve]

**Steps**:

1. **[Step 1 Name]**: [What happens]  
   **Input**: [What user provides]  
   **Output**: [What user gets]  
   **Command**: `[toolkit-name] [command] [args]`  
   **Validation**: [What is checked]

2. **[Step 2 Name]**: [What happens]  
   **Input**: [What user provides]  
   **Output**: [What user gets]  
   **Command**: `[toolkit-name] [command] [args]`  
   **Validation**: [What is checked]

3. **[Step 3 Name]**: [What happens]  
   **Input**: [What user provides]  
   **Output**: [What user gets]  
   **Command**: `[toolkit-name] [command] [args]`  
   **Result**: [Final outcome]

**Example Usage**:
```bash
# Step 1
[toolkit-name] [command1] [args]
# [Show expected output]

# Step 2
[toolkit-name] [command2] [args]
# [Show expected output]

# Step 3
[toolkit-name] [command3] [args]
# [Show expected output]
```

**Success Indicators**:
- ✅ [How user knows workflow succeeded]
- ✅ [What artifacts are produced]
- ✅ [What feedback user receives]

**Error Scenarios**:
- ❌ [Common error 1] → [How to fix]
- ❌ [Common error 2] → [How to fix]

---

### [WORKFLOW_2] *(if applicable)*

**Purpose**: [What this workflow accomplishes]

**Steps**:
[Similar structure as workflow 1]

---

## CLI Commands

### `init`

**Purpose**: [What this command does]

**Usage**: `[toolkit-name] init [options] <output-file>`

**Options**:
- `--template <name>`: [Description]
- `--force`: [Description]

**Example**:
```bash
[toolkit-name] init test.yaml
# Creates test.yaml with template content
```

**Output**: [What user sees]

**Generated Files**: [List of files created]

---

### `validate`

**Purpose**: [What this command does]

**Usage**: `[toolkit-name] validate [options] <spec-file>`

**Options**:
- `--strict`: [Description]
- `--format <json|text>`: [Description]

**Example**:
```bash
[toolkit-name] validate test.yaml
# ✅ Validation passed: test.yaml
#    - All required fields present
#    - No validation errors
#    - 3 entities validated
```

**Output**: [What user sees]

**Exit Codes**:
- `0`: Validation successful
- `1`: Validation failed
- `2`: File not found or invalid format

---

### `[command3]`

**Purpose**: [What this command does]

**Usage**: `[toolkit-name] [command3] [options] <args>`

**Options**:
[List options]

**Example**:
```bash
[Show example]
```

**Output**: [What user sees]

---

[Add more commands as needed]

---

## Templates & Examples

**Purpose**: Define how templates and examples are organized to embody specification composability.

### Templates Directory Structure

**Core Principle**: Organize by **specification system source**, not by file type.

**Recommended Structure**:
```
templates/
├── README.md               # User guide (explains structure, available commands, usage)
├── [library-spec-1]/       # From MetaSpec library (e.g., generic, spec-kit)
│   ├── commands/           # Slash Commands from this specification system
│   │   └── [command-name].md
│   └── templates/          # Entity/workflow templates from this system
│       └── [template-name].yaml
├── [library-spec-2]/       # Another library specification system
│   ├── commands/
│   └── templates/
└── [custom]/               # Custom (derived from domain specification)
    ├── commands/           # Specification-specific Slash Commands
    │   └── [command-name].md
    └── templates/          # Specification entity templates
        └── [entity-name].yaml
```

**Example (MCP-Speckit)**:
```
templates/
├── README.md              # 📖 User guide (auto-generated by MetaSpec)
├── generic/               # From library/generic (brownfield/greenfield)
│   ├── commands/
│   │   ├── init.md
│   │   └── validate.md
│   └── templates/
│       └── basic-spec.yaml
├── spec-kit/              # From library/sdd/spec-kit
│   ├── commands/
│   │   ├── plan.md
│   │   └── implement.md
│   └── templates/
│       └── toolkit-spec.yaml
└── mcp/                   # Custom (from domain/001-mcp-spec)
    ├── commands/
    │   ├── show-spec.md
    │   ├── get-template.md
    │   └── validate-server.md
    └── templates/
        ├── basic-server.yaml
        ├── advanced-server.yaml
        └── tool-definition.yaml
```

---

### Template Mapping

**Map specification systems to directory names**:

| Specification Source | Directory Name | Contents |
|---------------------|----------------|----------|
| library/generic/brownfield | `generic/` | Init, validate commands |
| library/sdd/spec-kit | `spec-kit/` | Spec-driven workflow commands |
| domain/001-[domain]-spec | `[domain]/` | Domain-specific commands & templates |
| Custom workflow | `[workflow-name]/` | Custom specification system |

---

### P0 Slash Commands

**From Step 2.5 STEP 4 (Command Derivation from Scenarios)**:

**P0 Commands** (Must implement - derived from key scenarios):
- [ ] `/[toolkit].[command1]` - [Purpose] (Scenario: [N])
- [ ] `/[toolkit].[command2]` - [Purpose] (Scenario: [N])
- [ ] `/[toolkit].[command3]` - [Purpose] (Scenario: [N])

**Example**:
```
P0 Slash Commands for MCP-Speckit:
- [ ] /mcpspeckit.show-spec - Display MCP specification rules (Scenario: 1, 3)
- [ ] /mcpspeckit.get-template - Retrieve server template (Scenario: 1, 2)
- [ ] /mcpspeckit.validate-server - Validate server definition (Scenario: 1, 2, 3)
```

---

### Entity Templates

**Map specification entities to template files**:

| Entity | Template File | Purpose | Used In Scenario |
|--------|--------------|---------|------------------|
| [PRIMARY_ENTITY] | `basic-[entity].yaml` | Minimal valid example | [1, 2] |
| [PRIMARY_ENTITY] | `advanced-[entity].yaml` | Complete with all fields | [2] |
| [SECONDARY_ENTITY] | `[entity].yaml` | Secondary entity template | [1, 3] |

**Example (MCP-Speckit)**:
```
| Entity | Template File | Purpose | Used In Scenario |
|--------|--------------|---------|------------------|
| Server | basic-server.yaml | Simple MCP server | 1, 2 |
| Server | advanced-server.yaml | Full featured server | 2 |
| Tool | tool-definition.yaml | Tool schema template | 1, 3 |
| Resource | resource-definition.yaml | Resource template | 2, 3 |
```

---

### Examples Directory

**Separate from templates** - Complete working examples:

```
examples/
├── basic/
│   ├── [example-1].yaml          # Simple example
│   └── README.md                  # Explanation
├── advanced/
│   ├── [example-2].yaml          # Complex example
│   └── README.md                  # Explanation
├── use-cases/
│   ├── [use-case-1]/
│   │   ├── [spec].yaml
│   │   └── README.md
│   └── [use-case-2]/
│       ├── [spec].yaml
│       └── README.md
└── README.md                      # Examples overview
```

**Example Content**:
- **basic/**: 1-2 simple examples demonstrating core features
- **advanced/**: 1-2 complex examples showing all capabilities
- **use-cases/**: Real-world scenarios from User Journey Analysis

**Requirements**:
- [ ] At least 1-2 basic examples
- [ ] At least 1 advanced example
- [ ] Examples validate successfully
- [ ] Each example has README explaining usage
- [ ] Examples cover P0 scenarios from User Journey Analysis

---

### Implementation Checklist

**Templates Directory**:
- [ ] Library specifications mapped to `templates/[library-name]/`
- [ ] Custom specification in `templates/[domain]/`
- [ ] P0 Slash Commands created (from User Journey Analysis)
- [ ] Entity templates match specification entities
- [ ] Each specification system has `commands/` and `templates/` subdirectories
- [ ] **`templates/README.md` created** - User guide explaining structure, available commands, and usage

**Examples Directory**:
- [ ] Examples in top-level `examples/` directory (not under templates/)
- [ ] At least 1-2 complete working examples
- [ ] Examples validate successfully with toolkit
- [ ] Each example has clear README
- [ ] Examples demonstrate P0 scenarios

**Benefits**:
- ✅ Clear provenance: Know which spec system provides which commands
- ✅ Avoid conflicts: Different systems can have same-named commands
- ✅ Partial replacement: Update one spec system without affecting others
- ✅ Follows MetaSpec convention: Same pattern as `library/sdd/spec-kit/`
- ✅ Embodies composability: Specification systems can be selected and composed

---

## Validation Requirements

### Structural Validation

**Purpose**: Ensure specification has correct structure

**Requirements**:
- **SV-001**: File must be valid YAML/JSON
- **SV-002**: All required fields must be present
- **SV-003**: Field types must match specification
- **SV-004**: No unknown fields (unless extensibility enabled)

**Error Message Format**:
```
❌ Structural Error: [Error type]
  Field: [field_path]
  Issue: [What's wrong]
  Expected: [What should be]
  Fix: [How to fix it]
```

---

### Semantic Validation

**Purpose**: Ensure specification makes logical sense

**Requirements**:
- **SM-001**: [Requirement 1 - e.g., "Referenced entities must exist"]
- **SM-002**: [Requirement 2 - e.g., "No circular dependencies"]
- **SM-003**: [Requirement 3 - e.g., "Unique identifiers"]

**Error Message Format**:
```
❌ Semantic Error: [Error type]
  Location: [where in spec]
  Issue: [What's wrong]
  Context: [Relevant info]
  Fix: [How to fix it]
```

---

### Domain-Specific Validation

**Purpose**: Ensure specification follows domain rules

**Requirements**:
- **DV-001**: [Domain rule 1 - e.g., "HTTP methods must be valid"]
- **DV-002**: [Domain rule 2 - e.g., "Status codes in valid range"]
- **DV-003**: [Domain rule 3 - e.g., "URLs must be valid"]

**Why These Rules**:
- [Rule 1]: [Explanation of why this domain constraint exists]
- [Rule 2]: [Explanation]
- [Rule 3]: [Explanation]

**Error Message Format**:
```
❌ Domain Error: [Error type]
  Field: [field_name]
  Value: [actual_value]
  Issue: [Why this violates domain rules]
  Expected: [What's valid in this domain]
  Fix: [How to fix it]
```

---

## Quality Criteria

### Usability

- **QC-001**: Users can create valid spec in < 5 minutes
- **QC-002**: Error messages include fix suggestions
- **QC-003**: Examples provided for every concept
- **QC-004**: Consistent naming conventions throughout

### Performance

- **QC-005**: Validation completes in < 100ms for typical spec
- **QC-006**: Toolkit handles 1000+ specifications
- **QC-007**: Memory usage < 50MB for normal workloads
- **QC-008**: Startup time < 1 second

### AI-Friendliness

- **QC-009**: Error messages are parseable by AI
- **QC-010**: Examples in all documentation
- **QC-011**: Consistent patterns (no special cases)
- **QC-012**: Clear intent (no implicit behavior)

### Extensibility

- **QC-013**: Custom validators can be registered
- **QC-014**: Plugin system for new entity types
- **QC-015**: Hook points for workflow customization
- **QC-016**: Clear extension documentation

### Domain Alignment

- **QC-017**: Follows domain conventions (e.g., REST standards)
- **QC-018**: Respects domain constraints (e.g., HTTP specs)
- **QC-019**: Uses domain terminology correctly
- **QC-020**: Validates against domain rules

---

## Assumptions

[Document assumptions made during specification]

**Example**:
- **ASM-001**: File format is YAML (human-readable, widely adopted)
- **ASM-002**: Validation uses JSON Schema (standard, well-supported)
- **ASM-003**: CLI uses Typer framework (Python standard)
- **ASM-004**: Error messages are English (internationalization later)

**Rationale**: [Why these assumptions are reasonable]

---

## Open Questions

[NEEDS CLARIFICATION: Question 1 - specific question that needs answer]

[NEEDS CLARIFICATION: Question 2 - specific question that needs answer]

[NEEDS CLARIFICATION: Question 3 - specific question that needs answer]

**Note**: Maximum 3 open questions. Other ambiguities resolved with reasonable defaults documented in Assumptions.

---

## Constitution Alignment

**Entity-First Design**: ✅ | ❌  
[Explain how this spec follows or violates Entity-First principle]

**Validator Extensibility**: ✅ | ❌  
[Explain extensibility design]

**Spec-First Development**: ✅ | ❌  
[Explain how users write specs first]

**AI-Agent Friendly**: ✅ | ❌  
[Explain error messages, examples, consistency]

**Progressive Enhancement**: ✅ | ❌  
[Explain MVP and enhancement path]

**Domain Specificity**: ✅ | ❌  
[Explain domain constraints and conventions]

---

## Next Steps

1. ✅ **Complete**: Toolkit specification defined
2. ⏭️ **Next**: Use `/metaspec:clarify` to refine ambiguous sections
3. ⏭️ **Then**: Use `/metaspec:plan` to design implementation architecture
4. ⏭️ **Finally**: Use `/metaspec:tasks` to break down implementation

---

**Version**: 1.0  
**Last Updated**: [DATE]  
**Status**: Draft | Under Review | Approved


