initial specifications
This commit is contained in:
+137
-35
@@ -1,50 +1,152 @@
|
||||
# [PROJECT_NAME] Constitution
|
||||
<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
|
||||
<!--
|
||||
SYNC IMPACT REPORT
|
||||
===================
|
||||
Version Change: 0.0.0 → 1.0.0
|
||||
Modified Principles: N/A (initial creation)
|
||||
Added Sections:
|
||||
- Core Principles (5 principles defined)
|
||||
- Quality Standards
|
||||
- Development Process
|
||||
- Governance
|
||||
Removed Sections: N/A
|
||||
Templates Status:
|
||||
✅ .specify/templates/spec-template.md - Verified alignment
|
||||
✅ .specify/templates/plan-template.md - Constitution Check section present
|
||||
✅ .specify/templates/tasks-template.md - Test-first approach reflected
|
||||
✅ .specify/templates/checklist-template.md - Generic template aligns
|
||||
✅ .specify/templates/agent-file-template.md - Generic template aligns
|
||||
Follow-up TODOs:
|
||||
- Consider adding specific technology stack constraints as project matures
|
||||
- Review slash command files for any agent-specific references
|
||||
===================
|
||||
-->
|
||||
|
||||
# Reklamator Constitution
|
||||
|
||||
## Core Principles
|
||||
|
||||
### [PRINCIPLE_1_NAME]
|
||||
<!-- Example: I. Library-First -->
|
||||
[PRINCIPLE_1_DESCRIPTION]
|
||||
<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
|
||||
### I. Specification-First Development
|
||||
|
||||
### [PRINCIPLE_2_NAME]
|
||||
<!-- Example: II. CLI Interface -->
|
||||
[PRINCIPLE_2_DESCRIPTION]
|
||||
<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
|
||||
Every feature MUST begin with a complete specification document before any implementation work begins. Specifications MUST include:
|
||||
- Prioritized user stories that are independently testable
|
||||
- Functional requirements with unique identifiers (FR-001, etc.)
|
||||
- Measurable success criteria
|
||||
- Edge cases and boundary conditions
|
||||
|
||||
### [PRINCIPLE_3_NAME]
|
||||
<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
|
||||
[PRINCIPLE_3_DESCRIPTION]
|
||||
<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
|
||||
**Rationale**: Clear specifications prevent scope creep, enable accurate effort estimation, and provide a shared understanding between stakeholders and implementers. Independent testability ensures we can deliver incremental value.
|
||||
|
||||
### [PRINCIPLE_4_NAME]
|
||||
<!-- Example: IV. Integration Testing -->
|
||||
[PRINCIPLE_4_DESCRIPTION]
|
||||
<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
|
||||
### II. Test-First Discipline (NON-NEGOTIABLE)
|
||||
|
||||
### [PRINCIPLE_5_NAME]
|
||||
<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
|
||||
[PRINCIPLE_5_DESCRIPTION]
|
||||
<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
|
||||
Tests MUST be written before implementation code. The mandatory workflow is:
|
||||
1. Write tests that capture requirements
|
||||
2. Verify tests FAIL (proving they test something meaningful)
|
||||
3. Implement the minimum code to make tests pass
|
||||
4. Refactor while keeping tests green
|
||||
|
||||
## [SECTION_2_NAME]
|
||||
<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
|
||||
**Rationale**: Test-first development forces clear thinking about requirements and interfaces. It prevents the common trap of writing tests that merely confirm what the code does rather than what it should do. This is non-negotiable because untested code is unmaintainable code.
|
||||
|
||||
[SECTION_2_CONTENT]
|
||||
<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
|
||||
### III. Independent User Stories
|
||||
|
||||
## [SECTION_3_NAME]
|
||||
<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
|
||||
User stories MUST be designed as independently deliverable units of value. Each story:
|
||||
- Can be implemented without requiring other stories to be complete
|
||||
- Can be tested in isolation
|
||||
- Delivers tangible value to users even if it's the only story delivered
|
||||
- Has an explicitly assigned priority (P1, P2, P3, etc.)
|
||||
|
||||
[SECTION_3_CONTENT]
|
||||
<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
|
||||
**Rationale**: Independent stories enable incremental delivery, reduce risk, allow flexible prioritization, and support parallel development when team capacity allows.
|
||||
|
||||
### IV. Simplicity & Justification
|
||||
|
||||
Complexity MUST be justified. Default to the simplest solution that meets requirements. When introducing:
|
||||
- Additional abstraction layers
|
||||
- New dependencies
|
||||
- Design patterns beyond direct implementation
|
||||
- Additional projects or services
|
||||
|
||||
Document WHY it's needed and what simpler alternative was rejected and why.
|
||||
|
||||
**Rationale**: Complexity is expensive. It increases cognitive load, maintenance burden, bug surface area, and onboarding time. Every complexity decision should be a conscious tradeoff with documented reasoning.
|
||||
|
||||
### V. Documentation as Code
|
||||
|
||||
Documentation MUST live alongside code, be version-controlled, and follow the same review process. Required documentation:
|
||||
- Feature specifications in `/specs/[###-feature-name]/spec.md`
|
||||
- Implementation plans in `/specs/[###-feature-name]/plan.md`
|
||||
- Data models, contracts, and quickstart guides in feature directories
|
||||
- Constitution (this document) for governance
|
||||
|
||||
**Rationale**: Outdated documentation is worse than no documentation. Treating docs as code ensures they stay current, searchable, and reviewable. The Specify framework structure enforces this by design.
|
||||
|
||||
## Quality Standards
|
||||
|
||||
### Testing Requirements
|
||||
|
||||
- **Contract tests**: Required for all public APIs and interfaces
|
||||
- **Integration tests**: Required for user journeys and cross-component interactions
|
||||
- **Unit tests**: Optional but encouraged for complex logic
|
||||
- **Test independence**: Tests MUST NOT depend on execution order
|
||||
- **Test clarity**: Test names MUST describe what behavior is being verified
|
||||
|
||||
### Code Quality
|
||||
|
||||
- Clear, self-documenting code preferred over extensive comments
|
||||
- Comments required only for non-obvious decisions or complex algorithms
|
||||
- Linting and formatting tools MUST be configured and enforced
|
||||
- Error handling MUST be explicit and meaningful
|
||||
- Logging MUST be structured and include sufficient context
|
||||
|
||||
## Development Process
|
||||
|
||||
### Feature Lifecycle
|
||||
|
||||
1. **Specify** (`/speckit.specify`): Create feature specification with user stories
|
||||
2. **Clarify** (`/speckit.clarify`): Address any ambiguities or underspecified areas
|
||||
3. **Plan** (`/speckit.plan`): Research, design data models, define contracts
|
||||
4. **Tasks** (`/speckit.tasks`): Generate dependency-ordered implementation tasks
|
||||
5. **Implement** (`/speckit.implement`): Execute tasks following test-first discipline
|
||||
6. **Analyze** (`/speckit.analyze`): Verify cross-artifact consistency
|
||||
|
||||
### Branching & Integration
|
||||
|
||||
- Feature branches named `###-feature-name` where ### is numeric identifier
|
||||
- Branch created before planning phase begins
|
||||
- Regular integration to avoid long-lived feature branches
|
||||
- All changes require review before merging
|
||||
|
||||
### Constitution Compliance
|
||||
|
||||
Before starting implementation (Phase 0 research), run Constitution Check from `plan.md`. Any violations MUST be documented in the Complexity Tracking table with:
|
||||
- What rule is being violated
|
||||
- Why it's necessary for this feature
|
||||
- What simpler alternative was considered and rejected
|
||||
|
||||
## Governance
|
||||
<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
|
||||
|
||||
[GOVERNANCE_RULES]
|
||||
<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
|
||||
### Amendment Process
|
||||
|
||||
**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
|
||||
<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
|
||||
1. **Proposal**: Document proposed change with rationale
|
||||
2. **Review**: Discuss impact on existing practices and templates
|
||||
3. **Sync**: Update all dependent templates and documentation
|
||||
4. **Version**: Increment version following semantic versioning
|
||||
5. **Ratify**: Record amendment date and version
|
||||
|
||||
### Versioning Policy
|
||||
|
||||
- **MAJOR (X.0.0)**: Backward incompatible changes, principle removals, fundamental redefinitions
|
||||
- **MINOR (x.Y.0)**: New principles added, sections expanded, new mandatory practices
|
||||
- **PATCH (x.y.Z)**: Clarifications, wording improvements, typo fixes, non-semantic changes
|
||||
|
||||
### Compliance Review
|
||||
|
||||
All feature specifications, plans, and implementations MUST be reviewed for constitutional compliance. Reviewers MUST verify:
|
||||
- Specification precedes implementation
|
||||
- Tests written before code
|
||||
- User stories are independently testable
|
||||
- Complexity is justified in Complexity Tracking table when needed
|
||||
- Required documentation is complete and current
|
||||
|
||||
### Conflicts & Precedence
|
||||
|
||||
This constitution supersedes all other development guidelines, practices, or conventions. When conflicts arise, this document governs. If this constitution is unclear or incomplete for a specific situation, propose an amendment rather than work around it.
|
||||
|
||||
**Version**: 1.0.0 | **Ratified**: 2025-10-14 | **Last Amended**: 2025-10-14
|
||||
|
||||
Reference in New Issue
Block a user