From 3507ce27e59b6bc21f2f8ae59f9234b1ded50751 Mon Sep 17 00:00:00 2001 From: Adrien Date: Tue, 31 Mar 2026 14:19:39 +0200 Subject: [PATCH] constitution added --- .specify/init-options.json | 11 +++ .specify/memory/constitution.md | 148 ++++++++++++++++++++++++-------- 2 files changed, 124 insertions(+), 35 deletions(-) create mode 100644 .specify/init-options.json diff --git a/.specify/init-options.json b/.specify/init-options.json new file mode 100644 index 0000000..8c37510 --- /dev/null +++ b/.specify/init-options.json @@ -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" +} \ No newline at end of file diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md index a4670ff..5c8ca4d 100644 --- a/.specify/memory/constitution.md +++ b/.specify/memory/constitution.md @@ -1,50 +1,128 @@ -# [PROJECT_NAME] Constitution - + + +# AI Teacher Constitution ## Core Principles -### [PRINCIPLE_1_NAME] - -[PRINCIPLE_1_DESCRIPTION] - +### I. Keep It Simple Stupid (KISS) -### [PRINCIPLE_2_NAME] - -[PRINCIPLE_2_DESCRIPTION] - +Every design and implementation decision MUST default to the simplest viable option. +Complexity MUST be explicitly justified against a concrete, present need — not a hypothetical +future requirement. Gold-plating, speculative abstractions, and premature optimization are +non-compliant. -### [PRINCIPLE_3_NAME] - -[PRINCIPLE_3_DESCRIPTION] - +**Rules:** +- A feature MUST NOT be split into multiple layers/services unless a single layer is demonstrably insufficient. +- Dependencies MUST be chosen for their simplicity, not their feature count. +- If two approaches solve the problem equally well, the shorter one wins. -### [PRINCIPLE_4_NAME] - -[PRINCIPLE_4_DESCRIPTION] - +**Rationale**: This is a POC. Speed of learning and iteration matters more than architectural +elegance. Complexity kills POCs. -### [PRINCIPLE_5_NAME] - -[PRINCIPLE_5_DESCRIPTION] - +### II. Easy to Change -## [SECTION_2_NAME] - +Code MUST be written with future modification in mind. High coupling between unrelated modules +is non-compliant. -[SECTION_2_CONTENT] - +**Rules:** +- 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 +competitive advantage of early-stage software. -[SECTION_3_CONTENT] - +### III. Web-First Architecture + +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_RULES] - +This constitution supersedes all informal conventions. Amendments MUST be proposed as a PR +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:** +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