# [TOOLKIT_NAME] Constitution
<!-- Example: API Test Kit Constitution, Design Token Kit Constitution -->

## Toolkit Purpose

[TOOLKIT_PURPOSE]
<!-- Example: This toolkit enables developers to write declarative API test specifications and execute them programmatically. It serves the API testing domain, focusing on REST/GraphQL APIs. -->

**Domain**: [TOOLKIT_DOMAIN]  
<!-- Example: API Testing, Design Systems, Infrastructure as Code -->

**Primary Entity**: [PRIMARY_ENTITY]  
<!-- Example: APITest, DesignToken, ServiceConfig -->

---

## Core Principles

### I. Entity-First Design

[ENTITY_FIRST_DESCRIPTION]
<!-- Example: 
- Start with minimal APITest entity (endpoint, method, assertions)
- All fields must have clear descriptions and types
- Required fields: endpoint, method (only truly essential data)
- Optional fields: headers, body, auth (progressive enhancement)

Rationale: Simple entities are easier for AI agents to understand and validate.
-->

### II. Validator Extensibility

[VALIDATOR_EXTENSIBILITY_DESCRIPTION]
<!-- Example:
- Core validator handles JSON Schema validation (Pydantic)
- Support custom assertion types via register_assertion_validator()
- Error messages include field path and fix suggestions
- Validation performance: <100ms for typical test specs

Rationale: Different APIs need different assertion types; extensibility is key.
-->

### III. Spec-First Development

[SPEC_FIRST_DESCRIPTION]
<!-- Example:
- Users write test.yaml with APITest specifications
- Specifications are declarative (what to test, not how)
- YAML/JSON format for human-readability
- Specifications are version-controlled with git

Rationale: Spec-first enables AI agents to generate and validate test specifications.
-->

### IV. AI-Agent Friendly

[AI_AGENT_FRIENDLY_DESCRIPTION]
<!-- Example:
- Clear error messages: "Field 'endpoint' is required in APITest entity"
- Examples in every error message: "Expected: endpoint: '/api/users'"
- Consistent naming: snake_case for fields, kebab-case for CLI
- Explicit behavior: no magic defaults, all behavior documented

Rationale: AI agents need clear feedback to correct mistakes and learn patterns.
-->

### V. Progressive Enhancement

[PROGRESSIVE_ENHANCEMENT_DESCRIPTION]
<!-- Example:
- MVP: init + validate commands (week 1)
- v0.2: execute command (week 2)
- v0.3: generate command (week 3)
- v1.0: report + coverage (week 4)
- Semantic versioning strictly followed
- Feature maturity labels: alpha, beta, stable

Rationale: Start simple, grow based on user feedback.
-->

### VI. Domain Specificity

[DOMAIN_SPECIFICITY_DESCRIPTION]
<!-- Example:
- HTTP method validation: only GET, POST, PUT, DELETE, PATCH
- Status code validation: 100-599 range
- Header names: case-insensitive per RFC 7230
- Content-Type validation for request/response bodies
- RESTful conventions: endpoint starts with /

Rationale: Generic toolkits are weak toolkits; domain focus creates value.
-->

---

## Additional Principles

[ADDITIONAL_PRINCIPLES]
<!-- Optional domain-specific principles beyond the standard 6
Example for API Testing:
### VII. Test Isolation
- Each test must be independent
- No shared state between tests
- Setup/teardown hooks for test data

Example for Design Systems:
### VII. Design Token Hierarchy
- Tokens must follow category > type > item structure
- Reference tokens allowed (color.primary.500)
- No circular references
-->

---

## Implementation Constraints

[IMPLEMENTATION_CONSTRAINTS]
<!-- Example:
### Technology Stack
- Python 3.9+ required
- Pydantic 2.0+ for validation
- Typer for CLI interface
- PyYAML for spec parsing

### Performance Targets
- Validation: <100ms per spec
- Execution: <5s for 100 tests
- Memory: <50MB for typical workload

### Code Quality
- Type hints required (mypy --strict)
- Test coverage >90%
- Documentation: every public API
-->

---

## Governance

[GOVERNANCE_RULES]
<!-- Example:
### Amendment Process
1. Propose change via GitHub issue
2. Discuss impact on existing specs/code
3. Update constitution with version bump
4. Update affected code/docs
5. Announce in CHANGELOG

### Compliance Checks
- CI/CD validates constitution compliance
- Pre-commit hooks check principle adherence
- Code review checklist references principles

### Review Schedule
- Constitution reviewed quarterly
- Principles updated based on user feedback
- Breaking changes require MAJOR version bump
-->

---

## Version History

**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
<!-- Example: Version: 1.0.0 | Ratified: 2025-10-28 | Last Amended: 2025-10-28 -->

### Change Log

[CHANGE_LOG]
<!-- Example:
- v1.0.0 (2025-10-28): Initial constitution
- v1.1.0 (2025-11-15): Added Test Isolation principle
- v1.1.1 (2025-11-20): Clarified Entity-First examples
-->


