# .specify Directory

This directory contains the project's governance framework and specification templates.

## Purpose

The `.specify` system provides:
- **Constitutional Principles:** Binding rules for all development work
- **Template Library:** Standardized formats for plans, specs, and tasks
- **Consistency Enforcement:** Automated checks that code adheres to principles
- **Living Documentation:** Evolving guidance that grows with the project

## Directory Structure

```
.specify/
├── memory/
│   └── constitution.md          # Project constitution (versioned)
├── templates/
│   ├── plan-template.md         # Feature planning template
│   ├── spec-template.md         # Technical specification template
│   ├── tasks-template.md        # Task tracking template
│   └── commands/
│       └── constitution.md      # Constitution amendment workflow
├── plans/                       # (Create as needed) Feature plans
├── specs/                       # (Create as needed) Specifications
└── tasks/                       # (Create as needed) Task lists
```

## Key Files

### constitution.md
The project's binding principles covering:
- Code quality and maintainability
- Testing discipline (≥80% coverage)
- User experience consistency
- Performance and efficiency

**Version:** 1.0.0 (ratified 2025-11-02)

Every code change must align with constitutional principles. The constitution can be amended via pull request with proper versioning and impact analysis.

### Templates

#### plan-template.md
Use for high-level feature planning. Includes:
- Objectives and scope definition
- Constitution alignment checklist
- Technical approach and architecture
- Implementation phases
- Risk assessment

#### spec-template.md
Use for detailed technical specifications. Includes:
- Functional and non-functional requirements
- Design and data models
- API specifications with types
- Testing strategy
- Performance analysis

#### tasks-template.md
Use for sprint/milestone task tracking. Includes:
- Tasks categorized by constitutional principle
- Estimation guidelines (S/M/L/XL)
- Completion checklist
- Blocked task tracking

## Workflow

1. **Plan** → Create plan from template, verify constitutional alignment
2. **Specify** → Write detailed spec with testable requirements
3. **Implement** → Break down into tasks, execute with continuous testing
4. **Review** → Code review validates principle adherence
5. **Deploy** → Merge and monitor success metrics

## Constitutional Compliance

Every plan, spec, and task must explicitly address:

✅ **Code Quality:** How will this maintain/improve maintainability?  
✅ **Testing:** What tests ensure correctness? (≥80% coverage)  
✅ **User Experience:** How does this impact users positively?  
✅ **Performance:** What are the performance implications?

## Amending the System

### To amend the constitution:
1. PR to `constitution.md` with rationale
2. Increment version (MAJOR.MINOR.PATCH)
3. Update dependent templates
4. Add Sync Impact Report

### To improve templates:
1. PR to template file with changes
2. Explain benefit and backward compatibility
3. Update examples if structure changes

## Version History

- **1.0.0 (2025-11-02):** Initial specification system established with four core principles

## Questions?

Refer to the [main README](../README.md) or the constitution itself for detailed guidance.