fete/CLAUDE.md

fete

A privacy-focused, self-hostable PWA for event announcements and RSVPs. Alternative to Facebook Events or Telegram groups — reduced to the essentials.

Project Statutes

These are the non-negotiable principles of this project. Every decision — architectural, technical, or design-related — must be consistent with them.

Governance

• The agent works autonomously on implementation tasks.
• When facing architectural decisions, fundamental design questions, tech stack choices, or dependency selections: advise, propose options, and ask for approval before proceeding.
• Actively challenge decisions — including the developer's — when there are good reasons to. Don't be a yes-machine.
• When encountering problems, attempt to solve them independently first. Only escalate when stuck.

Methodology

• Follow Research → Spec → Test → Implement → Review. No shortcuts.
• API-first development: the OpenAPI spec (backend/src/main/resources/openapi/api.yaml) is the single source of truth for the REST API contract. Define endpoints and schemas in the spec first, then generate backend interfaces and frontend types before writing any implementation code.
• Never write implementation code without a specification.
• Always write tests before implementation (TDD). Red → Green → Refactor.
• Refactoring is permitted freely as long as it does not alter the fundamental architecture.
• No vibe coding. Every line of code must be intentional and traceable to a requirement.
• Document integrity: when a decision is revised (pivot), add an addendum with rationale — never rewrite or delete the original decision. Traceability over tidiness.
• When a setup task or user story is completed, check off its acceptance criteria in the corresponding spec file (spec/setup-tasks.md or spec/userstories.md) before committing. Progress must be tracked — no silent completions.

Privacy

• Privacy is a design constraint, not a feature. It shapes every decision from the start.
• No analytics, no telemetry — not even self-hosted.
• Never log PII or IP addresses on the server.
• For every feature, critically evaluate what data is necessary. Only store what is absolutely required for functionality.
• Never include external dependencies that phone home: no CDNs, no Google Fonts, no tracking-capable libraries.

Design

• The visual design system is defined in spec/design-system.md. All frontend implementation must follow it.
• Color palette, typography, component patterns, and layout rules are specified there — do not deviate without explicit approval.

Quality

• KISS and grugbrain. Engineer it properly, but don't over-engineer.
• No workarounds. Always fix the root cause, even if it takes longer.
• Address technical debt immediately. Don't let it accumulate.
• Accessibility is a baseline requirement, not an afterthought.

Dependencies

• Every dependency is a deliberate, justified decision.
• A dependency must provide substantial value and a significant portion of its features must actually be used.
• Dependencies must be actively maintained and open source. Copyleft is fine — the project is GPL-licensed.
• Never introduce a dependency that phones home or compromises user privacy.

Language

• Conversation and brainstorming: German.
• Code, comments, commits, documentation: English — no exceptions.

Deployment

• The project provides a Dockerfile. How and where it is deployed is the hoster's responsibility.
• A docker-compose example in the README is sufficient.
• Documentation lives in the README. No wiki, no elaborate docs site.

Tech Stack

• Backend: Java 25 (LTS, installed via SDKMAN), Spring Boot 3.5.x, Maven with wrapper (./mvnw)
• Frontend: Vue 3, TypeScript, Vue Router, Vite, Vitest, ESLint, Prettier
• Node.js: 24 LTS (for Docker/CI; development tolerates newer versions)
• Base package: de.fete, hexagonal architecture (single Maven module, package-level separation)
• No Pinia — Composition API (ref/reactive) + localStorage is sufficient
• No JPA until T-4 — added when database infrastructure is ready

Build Commands

What	Command
Backend test	cd backend && ./mvnw test
Backend run	cd backend && ./mvnw spring-boot:run
Frontend install	cd frontend && npm install
Frontend build	cd frontend && npm run build
Frontend test	cd frontend && npm run test:unit
Frontend dev	cd frontend && npm run dev
Backend checkstyle	cd backend && ./mvnw checkstyle:check
Backend full verify	cd backend && ./mvnw verify

Agent Documentation

• Research reports: docs/agents/research/
• Implementation plans: docs/agents/plan/
• Agent test reports (browser verification): .agent-tests/ (gitignored)
• Use the browser-interactive-testing skill (rodney/showboat) for visual verification — this is an agent tool, not manual work.

Skills

The following skills are available and should be used for their respective purposes:

Skill	Trigger	Purpose
rpi-research	Deep codebase investigation needed	Conducts thorough research and produces a written report. Use for understanding how something works before changing it.
rpi-plan	Feature, refactor, or bug fix needs planning	Creates detailed, phased implementation plans through interactive research and iteration.
rpi-implement	Approved plan ready for execution	Executes approved implementation plans phase by phase with automated and manual verification.
browser-interactive-testing	Visual verification of web pages	Headless Chrome testing via rodney/showboat. Use for screenshots, browser automation, and visual test reports.

Ralph Loops

• Autonomous work is done via Ralph Loops. See .claude/rules/ralph-loops.md for documentation.
• The loop runner is ralph.sh. Each run lives in its own directory under .ralph/.
• Run directories contain: instructions.md (prompt), chief-wiggum.md (directives), answers.md (human answers), questions.md (Ralph's questions), progress.txt (iteration log), meta.md (metadata), run.log (execution log).
• Project specifications (user stories, setup tasks, personas, etc.) live in spec/.