# Implementation Plan: [TOOLKIT_NAME]

**Date**: [DATE]  
**Status**: Draft  
**Specification**: [link to spec.md]

**Note**: This file is generated by `/metaspec:plan`. It defines HOW to build the toolkit, not WHAT the toolkit does.

---

## Summary

[Extract from spec.md: toolkit purpose + technical approach from research]

**Example**:
```
API Test Kit enables declarative API testing through YAML specifications.
Built with Python + Pydantic for validation, Typer for CLI, PyYAML for parsing.
Extensible via custom assertion types and request/response hooks.
```

---

## Technical Context

**Language/Version**: Python 3.9+ (minimum), 3.11+ (recommended)  
**Parser**: PyYAML 6.0+ or ruamel.yaml (for line number preservation)  
**Validator**: Pydantic 2.0+ (JSON Schema + custom validators)  
**CLI Framework**: Typer 0.9+ (modern, type-safe CLI)  
**Testing**: pytest 7.0+ (unit + integration tests)  
**Type Checking**: mypy --strict (enforce type safety)  
**Documentation**: Markdown + docstrings (Sphinx later)

**Domain**: [from spec.md]  
**Primary Entity**: [from spec.md]  
**Validation Strategy**: [JSON Schema (structure) + custom rules (domain logic)]  
**Performance Targets**: [from spec.md quality criteria]  
**Extensibility Requirements**: [custom validators, plugins, hooks]

**Unknowns** (resolve in Phase 0):
- [NEEDS CLARIFICATION: question 1]
- [NEEDS CLARIFICATION: question 2]

---

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

**From** `/memory/constitution.md`:

### I. Entity-First Design ✅ | ❌
- [ ] Entity model starts with 3-5 core fields
- [ ] Optional fields for progressive enhancement
- [ ] Clear field descriptions and types
- [ ] Examples for every field

**Status**: [PASS | VIOLATION]  
**Note**: [If VIOLATION, explain why and justify]

### II. Validator Extensibility ✅ | ❌
- [ ] Core validator handles structure (Pydantic)
- [ ] Custom validation rules via plugins
- [ ] Clear error messages with fix suggestions
- [ ] Performance target: < 100ms

**Status**: [PASS | VIOLATION]  
**Note**: [If VIOLATION, explain why and justify]

### III. Spec-First Development ✅ | ❌
- [ ] Users write declarative specifications
- [ ] Specifications are human-readable (YAML/JSON)
- [ ] Specifications are version-controlled

**Status**: [PASS | VIOLATION]

### IV. AI-Agent Friendly ✅ | ❌
- [ ] Clear error messages: "Field 'X' is required in Y entity"
- [ ] Examples in error messages
- [ ] Consistent naming conventions
- [ ] No implicit behavior

**Status**: [PASS | VIOLATION]

### V. Progressive Enhancement ✅ | ❌
- [ ] MVP: init + validate commands
- [ ] v0.2: [next feature]
- [ ] v0.3: [next feature]
- [ ] Semantic versioning

**Status**: [PASS | VIOLATION]

### VI. Domain Specificity ✅ | ❌
- [ ] Respects domain constraints
- [ ] Follows domain conventions
- [ ] References domain standards
- [ ] Domain-specific validation

**Status**: [PASS | VIOLATION]

**Overall Gate Status**: [PASS | FAIL]

---

## Project Structure

### Documentation (this toolkit)

```text
[toolkit-name]/
├── specs/
│   ├── spec.md                    # What (from /metaspec:specify)
│   ├── plan.md                    # This file (from /metaspec:plan)
│   ├── research.md                # Phase 0 (from /metaspec:plan)
│   ├── architecture.md            # Phase 1 (from /metaspec:plan)
│   ├── parser-design.md           # Phase 1 (from /metaspec:plan)
│   ├── validator-design.md        # Phase 1 (from /metaspec:plan)
│   └── tasks.md                   # Phase 2 (from /metaspec:tasks)
└── checklists/
    └── implementation-quality.md  # Quality gates
```

### Source Code

```text
[toolkit-name]/
├── README.md                      # User-facing documentation
├── AGENTS.md                      # AI agent guide
├── CHANGELOG.md                   # Version history
├── pyproject.toml                 # Python project config
├── .gitignore
│
├── memory/
│   └── constitution.md            # Design principles
│
├── templates/
│   └── spec-template.yaml         # Template for user specs
│
├── src/
│   └── [toolkit_name]/            # Snake-case package name
│       ├── __init__.py            # Package exports
│       ├── models.py              # Pydantic entity models
│       ├── parser.py              # YAML/JSON parser
│       ├── validator.py           # Validation logic
│       ├── cli.py                 # Typer CLI interface
│       ├── errors.py              # Custom exceptions
│       └── utils.py               # Helper functions
│
└── tests/
    ├── unit/                      # Fast, isolated tests
    │   ├── test_models.py         # Entity model tests
    │   ├── test_parser.py         # Parser tests
    │   ├── test_validator.py      # Validator tests
    │   └── test_utils.py          # Utility tests
    │
    ├── integration/               # End-to-end tests
    │   └── test_cli.py            # CLI command tests
    │
    └── fixtures/                  # Test data
        ├── valid_specs/           # Valid spec examples
        │   ├── simple.yaml
        │   ├── complex.yaml
        │   └── edge_cases.yaml
        └── invalid_specs/         # Invalid spec examples
            ├── missing_field.yaml
            ├── wrong_type.yaml
            └── invalid_value.yaml
```

**Structure Decision**: [Document why this structure was chosen, reference constitution principles]

---

## Complexity Tracking

> **Fill ONLY if Constitution Check has violations that must be justified**

| Principle | Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|-----------|------------|-------------------------------------|
| [Principle name] | [What violates] | [Justification] | [Why simpler won't work] |

**Example**:
| Entity-First | 10 fields in MVP | Domain requires 8 mandatory fields | Splitting would break domain semantics |

---

## Phase 0: Domain Research (research.md)

**Status**: [PENDING | IN PROGRESS | COMPLETE]

**Research Tasks**:

1. **Domain Standards**
   - Research: [domain] industry standards and specifications
   - Expected findings: RFCs, W3C specs, ISO standards
   - Output: List of relevant standards with URLs

2. **Reference Implementations**
   - Research: Existing [domain] tools and their approaches
   - Expected findings: Popular tools, their strengths/weaknesses
   - Output: Lessons learned, patterns to adopt/avoid

3. **Validation Patterns**
   - Research: Common validation patterns in [domain]
   - Expected findings: Error types, validation layers, rules
   - Output: Recommended validation approach

4. **Error Message Best Practices**
   - Research: Effective error messages for [domain] tooling
   - Expected findings: Message formats, fix suggestions
   - Output: Error message template and examples

**Unknowns to Resolve**:
- [NEEDS CLARIFICATION 1] → Research task: [description]
- [NEEDS CLARIFICATION 2] → Research task: [description]

**Output File**: `/specs/research.md`

---

## Phase 1: Architecture Design

**Status**: [PENDING | IN PROGRESS | COMPLETE]  
**Prerequisites**: research.md complete, all NEEDS CLARIFICATION resolved

### Document 1: Architecture Overview (architecture.md)

**Content**:
- Component diagram (Parser, Models, Validator, CLI, Errors)
- Component responsibilities (what each does)
- Data flow (User input → Output)
- Extension points (how to extend toolkit)
- Technology choices (why Python, Pydantic, Typer)

**Key Sections**:
```markdown
## Component Diagram
[Visual or text description of how components interact]

## Component Responsibilities
### Parser (parser.py)
- Responsibility 1
- Responsibility 2

### Models (models.py)
- Responsibility 1
- Responsibility 2

[... other components ...]

## Data Flow
1. Step 1
2. Step 2
3. Step 3

## Extension Points
1. Extension point 1: [how to use]
2. Extension point 2: [how to use]
```

### Document 2: Parser Design (parser-design.md)

**Content**:
- Parser interface (function signatures)
- Error handling (file not found, invalid syntax, empty file)
- Implementation notes (ruamel.yaml for line numbers, caching)
- Performance considerations

**Key Sections**:
```markdown
## Parser Interface
```python
def parse_spec(file_path: Path) -> Dict[str, Any]:
    """[docstring]"""
```

## Error Handling
### Error Type 1
[Error message example]

### Error Type 2
[Error message example]

## Implementation Notes
- Note 1
- Note 2
```

### Document 3: Validator Design (validator-design.md)

**Content**:
- Validation layers (structural, semantic, domain)
- Validator interface (function signatures)
- Error message format (with examples)
- Custom validator registration (plugin system)
- Performance targets

**Key Sections**:
```markdown
## Validation Layers
### Layer 1: Structural (Pydantic)
- Check 1
- Check 2

### Layer 2: Semantic (Custom)
- Check 1
- Check 2

### Layer 3: Domain (Domain-Specific)
- Check 1 [reference to research.md]
- Check 2 [reference to research.md]

## Validator Interface
```python
class ValidationResult:
    is_valid: bool
    errors: List[ValidationError]

def validate_spec(entity: EntityModel) -> ValidationResult:
    """[docstring]"""
```

## Error Message Format
```
❌ Error: [Type]
  [Details]
```

## Custom Validator Registration
[How users extend validation]
```

**Output Files**:
- `/specs/architecture.md`
- `/specs/parser-design.md`
- `/specs/validator-design.md`

---

## Phase 1: Constitution Re-Check

**After architecture design, re-evaluate constitution compliance**:

### I. Entity-First Design
**Architecture Compliance**: [How architecture supports simple entities]  
**Status**: ✅ PASS | ❌ FAIL  
**Note**: [Any concerns or adjustments needed]

### II. Validator Extensibility
**Architecture Compliance**: [How architecture supports custom validators]  
**Status**: ✅ PASS | ❌ FAIL  
**Note**: [Plugin system design details]

### III. Spec-First Development
**Architecture Compliance**: [How users write specs first]  
**Status**: ✅ PASS | ❌ FAIL

### IV. AI-Agent Friendly
**Architecture Compliance**: [How error messages are AI-friendly]  
**Status**: ✅ PASS | ❌ FAIL

### V. Progressive Enhancement
**Architecture Compliance**: [MVP design and enhancement path]  
**Status**: ✅ PASS | ❌ FAIL

### VI. Domain Specificity
**Architecture Compliance**: [How architecture enforces domain rules]  
**Status**: ✅ PASS | ❌ FAIL

**Overall Re-Check Status**: [PASS | FAIL]  
**Action Required**: [None | Adjust architecture]

---

## Next Steps

1. ✅ **Complete**: Implementation plan with architecture design
2. ⏭️ **Next**: Use `/metaspec:tasks` to break down into implementable tasks
3. ⏭️ **Then**: Use `/metaspec:implement` to execute implementation
4. ⏭️ **Finally**: Use `/metaspec:checklist` to verify quality

---

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


