106 lines
3.4 KiB
Markdown
106 lines
3.4 KiB
Markdown
# .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.
|
|
|