webref/.specify/README.md

.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 or the constitution itself for detailed guidance.