constitution added

.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"
+}

.specify/memory/constitution.md

@@ -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
 
-### [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. Keep It Simple Stupid (KISS)
 
-### [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 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]
-<!-- 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 -->
+**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]
-<!-- Example: IV. Integration Testing -->
-[PRINCIPLE_4_DESCRIPTION]
-<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
+**Rationale**: This is a POC. Speed of learning and iteration matters more than architectural
+elegance. Complexity kills POCs.
 
-### [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 -->
+### II. Easy to Change
 
-## [SECTION_2_NAME]
-<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
+Code MUST be written with future modification in mind. High coupling between unrelated modules
+is non-compliant.
 
-[SECTION_2_CONTENT]
-<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
+**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]
-<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
+**Rationale**: A POC that cannot pivot cheaply is a dead end. Changeability is the primary
+competitive advantage of early-stage software.
 
-[SECTION_3_CONTENT]
-<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
+### 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
-<!-- 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 -->
+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]
-<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
+**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