constitution added
This commit is contained in:
Adrien
11
.specify/init-options.json
Normal file
11
.specify/init-options.json
Normal file
@@ -0,0 +1,11 @@
|
|||||||
|
{
|
||||||
|
"ai": "claude",
|
||||||
|
"ai_commands_dir": null,
|
||||||
|
"ai_skills": false,
|
||||||
|
"branch_numbering": "sequential",
|
||||||
|
"here": true,
|
||||||
|
"offline": false,
|
||||||
|
"preset": null,
|
||||||
|
"script": "sh",
|
||||||
|
"speckit_version": "0.4.3"
|
||||||
|
}
|
||||||
@@ -1,50 +1,128 @@
|
|||||||
# [PROJECT_NAME] Constitution
|
<!--
|
||||||
<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
|
SYNC IMPACT REPORT
|
||||||
|
==================
|
||||||
|
Version change: (unset) → 1.0.0
|
||||||
|
New file: first ratification, all placeholders filled.
|
||||||
|
|
||||||
|
Modified principles: N/A (initial ratification)
|
||||||
|
|
||||||
|
Added sections:
|
||||||
|
- Core Principles (5 principles)
|
||||||
|
- Technology Constraints
|
||||||
|
- Development Workflow
|
||||||
|
- Governance
|
||||||
|
|
||||||
|
Templates reviewed:
|
||||||
|
- .specify/templates/plan-template.md ✅ compatible (no amendments needed)
|
||||||
|
- .specify/templates/spec-template.md ✅ compatible (no amendments needed)
|
||||||
|
- .specify/templates/tasks-template.md ✅ compatible (no amendments needed)
|
||||||
|
|
||||||
|
Deferred TODOs:
|
||||||
|
- TODO(RATIFICATION_DATE): exact project start date unknown; using today (2026-03-31) as ratification date.
|
||||||
|
-->
|
||||||
|
|
||||||
|
# AI Teacher Constitution
|
||||||
|
|
||||||
## Core Principles
|
## Core Principles
|
||||||
|
|
||||||
### [PRINCIPLE_1_NAME]
|
### I. Keep It Simple Stupid (KISS)
|
||||||
<!-- 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 -->
|
|
||||||
|
|
||||||
### [PRINCIPLE_2_NAME]
|
Every design and implementation decision MUST default to the simplest viable option.
|
||||||
<!-- Example: II. CLI Interface -->
|
Complexity MUST be explicitly justified against a concrete, present need — not a hypothetical
|
||||||
[PRINCIPLE_2_DESCRIPTION]
|
future requirement. Gold-plating, speculative abstractions, and premature optimization are
|
||||||
<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
|
non-compliant.
|
||||||
|
|
||||||
### [PRINCIPLE_3_NAME]
|
**Rules:**
|
||||||
<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
|
- A feature MUST NOT be split into multiple layers/services unless a single layer is demonstrably insufficient.
|
||||||
[PRINCIPLE_3_DESCRIPTION]
|
- Dependencies MUST be chosen for their simplicity, not their feature count.
|
||||||
<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
|
- If two approaches solve the problem equally well, the shorter one wins.
|
||||||
|
|
||||||
### [PRINCIPLE_4_NAME]
|
**Rationale**: This is a POC. Speed of learning and iteration matters more than architectural
|
||||||
<!-- Example: IV. Integration Testing -->
|
elegance. Complexity kills POCs.
|
||||||
[PRINCIPLE_4_DESCRIPTION]
|
|
||||||
<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
|
|
||||||
|
|
||||||
### [PRINCIPLE_5_NAME]
|
### II. Easy to Change
|
||||||
<!-- 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 -->
|
|
||||||
|
|
||||||
## [SECTION_2_NAME]
|
Code MUST be written with future modification in mind. High coupling between unrelated modules
|
||||||
<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
|
is non-compliant.
|
||||||
|
|
||||||
[SECTION_2_CONTENT]
|
**Rules:**
|
||||||
<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
|
- Modules MUST communicate through clearly defined interfaces; internal implementation details
|
||||||
|
MUST NOT leak across boundaries.
|
||||||
|
- Hardcoded values MUST be extracted to configuration at the boundary where they are consumed.
|
||||||
|
- A feature's core logic MUST be separable from its delivery mechanism (HTTP handler, CLI, etc.)
|
||||||
|
without full rewrites.
|
||||||
|
|
||||||
## [SECTION_3_NAME]
|
**Rationale**: A POC that cannot pivot cheaply is a dead end. Changeability is the primary
|
||||||
<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
|
competitive advantage of early-stage software.
|
||||||
|
|
||||||
[SECTION_3_CONTENT]
|
### III. Web-First Architecture
|
||||||
<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
|
|
||||||
|
The project is a web application. All architectural decisions MUST assume an HTTP
|
||||||
|
request/response model as the primary interface.
|
||||||
|
|
||||||
|
**Rules:**
|
||||||
|
- The backend MUST expose a REST (or equivalent HTTP) API as its public contract.
|
||||||
|
- The frontend MUST be a standalone client that communicates solely through the API;
|
||||||
|
server-side rendering of business logic is non-compliant.
|
||||||
|
- API contracts MUST be versioned at the URL path level (`/api/v1/...`) from day one.
|
||||||
|
|
||||||
|
**Rationale**: Maintaining a clean client/server split allows each side to evolve independently,
|
||||||
|
which is critical for a project that is expected to change frequently.
|
||||||
|
|
||||||
|
### IV. Documentation as Architecture
|
||||||
|
|
||||||
|
The README.md MUST contain a living architecture overview using Mermaid diagrams. Diagrams MUST
|
||||||
|
be updated whenever the architecture changes; outdated diagrams are a compliance violation.
|
||||||
|
|
||||||
|
**Rules:**
|
||||||
|
- At minimum, a system-context diagram (components and their relationships) MUST exist in README.md.
|
||||||
|
- Each major subsystem added to the project MUST be reflected in the README diagram within the
|
||||||
|
same PR that introduces it.
|
||||||
|
- Diagrams MUST use the `mermaid` fenced code block syntax so they render natively on GitHub/GitLab.
|
||||||
|
|
||||||
|
**Rationale**: For a POC with a small team, the README is the primary onboarding document.
|
||||||
|
Keeping diagrams co-located with code prevents documentation rot.
|
||||||
|
|
||||||
|
|
||||||
|
## Technology Constraints
|
||||||
|
|
||||||
|
- **Project type**: Web application (backend API + frontend client).
|
||||||
|
- **Structure**: `backend/` and `frontend/` at repository root (Option 2 in plan template).
|
||||||
|
- **Complexity ceiling**: Maximum two deployable units (one backend, one frontend) unless
|
||||||
|
a concrete scaling need is demonstrated and documented.
|
||||||
|
- **External services**: MUST be wrapped behind an interface so they can be swapped without
|
||||||
|
cascading changes.
|
||||||
|
- **Database**: A single relational or document store is sufficient for the POC; no distributed
|
||||||
|
storage without explicit justification.
|
||||||
|
|
||||||
|
## Development Workflow
|
||||||
|
|
||||||
|
- Branch strategy: feature branches off `main`; short-lived (merge within one week).
|
||||||
|
- PR size: SHOULD be small enough to review in under 30 minutes; large PRs MUST be split.
|
||||||
|
- README MUST be updated in the same PR as any architectural change (Principle IV).
|
||||||
|
- The `Complexity Tracking` table in the plan template MUST be filled whenever a Principle I
|
||||||
|
or II violation is introduced.
|
||||||
|
- No performance optimization pass before the first working end-to-end prototype is validated
|
||||||
|
(Principle V gate).
|
||||||
|
|
||||||
## Governance
|
## Governance
|
||||||
<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
|
|
||||||
|
|
||||||
[GOVERNANCE_RULES]
|
This constitution supersedes all informal conventions. Amendments MUST be proposed as a PR
|
||||||
<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
|
that updates this file with an incremented version number and updated `LAST_AMENDED_DATE`.
|
||||||
|
|
||||||
**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
|
**Amendment procedure:**
|
||||||
<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
|
1. Open a PR with the proposed changes to this file.
|
||||||
|
2. The PR description MUST state which principle is affected and why the change is needed.
|
||||||
|
3. Merge after at least one reviewer approves.
|
||||||
|
4. All open feature branches MUST be rebased onto the updated `main` within 48 hours of merge.
|
||||||
|
|
||||||
|
**Versioning policy (semantic):**
|
||||||
|
- MAJOR: Removal or redefinition of an existing principle.
|
||||||
|
- MINOR: Addition of a new principle or section.
|
||||||
|
- PATCH: Clarifications, wording, or typo fixes.
|
||||||
|
|
||||||
|
**Compliance review**: Every PR review MUST include a check against the Constitution Check
|
||||||
|
section in the plan template. Non-compliant complexity MUST be logged in the Complexity
|
||||||
|
Tracking table before merge.
|
||||||
|
|
||||||
|
**Version**: 1.0.0 | **Ratified**: 2026-03-31 | **Last Amended**: 2026-03-31
|
||||||
|
|||||||
Reference in New Issue
Block a user