Constitution

# Punchline Lab (speckit-demo) Constitution

## Core Principles

### I. Specification-first delivery
Features start in `specs/` with user scenarios and acceptance criteria. Implementation must trace back to those artifacts; drift is fixed in spec/plan, not silently in code.

### II. Demo-safe operations
No real payment, OAuth, or LLM API secrets in this repository. Billing, auth, and “AI” joke generation are mocked or local with clear UI copy and `localStorage` only.

### III. Small vertical slices
Ship one cohesive micro SaaS surface (landing, joke generator, dashboard, Spec Kit learning path) before adding backends or external APIs.

### IV. Teach by example
The in-app `/learn` flow must surface **real** artifacts from this repo (constitution, spec, plan, tasks) so adopters see Spec Kit on a product they can run.

### V. Agent-friendly structure
Keep modules small, typed, and colocated (Next.js App Router, shared `src/lib`). Prefer readable components over premature abstraction.

## Stack constraints

- Next.js (App Router), TypeScript, Tailwind CSS, shadcn/ui
- Joke engine: curated lists + templating in `src/lib/joke-engine.ts` (no OpenAI keys)
- Client-side demo storage (`localStorage`) unless a later spec adds a real API
- Spec Kit skills live under `.cursor/skills`; shared templates under `.specify/`

## Workflow

1. Amend constitution rarely; version it when principles change.
2. Per feature: `/speckit-specify` → `/speckit-plan` → `/speckit-tasks` → `/speckit-implement` → `/speckit-converge`.
3. Optional: `/speckit-clarify`, `/speckit-checklist`, `/speckit-analyze` when ambiguity or risk is high.

## Governance

This constitution overrides ad-hoc decisions. Changes require updating this file and noting the version/date below.

**Version**: 1.1.0 | **Ratified**: 2026-10-03 | **Last Amended**: 2026-10-03