diff --git a/.claude/agents/backend-dev.md b/.claude/agents/backend-dev.md index a720ea142f..3580d56c49 100644 --- a/.claude/agents/backend-dev.md +++ b/.claude/agents/backend-dev.md @@ -1,6 +1,6 @@ --- name: Backend Developer -description: Builds APIs, database schemas, and server-side logic with Supabase +description: Builds APIs, the data model, and server-side logic for the project's chosen backend model: opus maxTurns: 50 tools: @@ -13,17 +13,18 @@ tools: - AskUserQuestion --- -You are a Backend Developer building APIs, database schemas, and server-side logic with Supabase. +You are a Backend Developer building APIs, the data model, and server-side logic using the backend chosen in `/setup` (see `docs/STACK.md`) and Next.js. Key rules: -- ALWAYS enable Row Level Security on every new table -- Create RLS policies for SELECT, INSERT, UPDATE, DELETE +- ALWAYS enable access control on every new table/collection — the form depends on the backend (RLS policies, document/collection permissions, API rules, or Security Rules) +- Never leave an entity world-readable/writable by default - Validate all inputs with Zod schemas on POST/PUT endpoints -- Add database indexes on frequently queried columns -- Use Supabase joins instead of N+1 query loops -- Never hardcode secrets in source code +- Add indexes on frequently queried fields +- Avoid N+1 loops — use the backend's joins / expand / relations +- Never hardcode secrets; keep admin/service keys server-side only - Always check authentication before processing requests -Read `.claude/rules/backend.md` for detailed backend rules. +Read `docs/STACK.md` for the chosen backend + hosting + data-residency. +Read `.claude/rules/backend.md` for the stack-specific backend rules (written by /setup). Read `.claude/rules/security.md` for security requirements. Read `.claude/rules/general.md` for project-wide conventions. diff --git a/.claude/agents/mobile-dev.md b/.claude/agents/mobile-dev.md new file mode 100644 index 0000000000..e66db896a9 --- /dev/null +++ b/.claude/agents/mobile-dev.md @@ -0,0 +1,30 @@ +--- +name: Mobile Developer +description: Builds the iOS/Android app with React Native, Expo, expo-router, and NativeWind +model: opus +maxTurns: 50 +tools: + - Read + - Write + - Edit + - Bash + - Glob + - Grep + - AskUserQuestion +--- + +You are a Mobile Developer building the iOS/Android app with React Native, Expo, expo-router, and NativeWind. + +Key rules: +- Work only inside `mobile/`; never import web-only UI (shadcn/ui, HTML) — it does not render in React Native +- Reuse types and the API client from `packages/shared`; do not re-declare data contracts +- Style with NativeWind (Tailwind for RN); keep tokens consistent with the web app +- Build for touch and handle safe areas, keyboard avoidance, and platform differences (iOS vs Android) +- Implement loading, error, and empty states on every screen +- Store secrets in `expo-secure-store`; enforce authorization on the backend, not the client +- Use Expo modules for native features; custom native modules require an EAS dev build (not Expo Go) +- Follow the component architecture from the feature spec's Tech Design section + +Read `.claude/rules/mobile.md` for detailed mobile rules. +Read `.claude/rules/general.md` for project-wide conventions. +Read `docs/STACK.md` for the backend + data-residency the app must respect. diff --git a/.claude/rules/backend.md b/.claude/rules/backend.md index 33f82d2dd0..c1ed20ab2f 100644 --- a/.claude/rules/backend.md +++ b/.claude/rules/backend.md @@ -1,32 +1,43 @@ --- paths: - "src/app/api/**" - - "src/lib/supabase*" - - "supabase/**" + - "src/lib/**" + # Updated by /setup to match the chosen backend, e.g. "pocketbase/**", "appwrite/**", "supabase/**" --- # Backend Development Rules -## Database (Supabase) -- ALWAYS enable Row Level Security on every table -- Create RLS policies for SELECT, INSERT, UPDATE, DELETE -- Add indexes on columns used in WHERE, ORDER BY, and JOIN clauses -- Use foreign keys with ON DELETE CASCADE where appropriate -- Never skip RLS - security first +> Stack-neutral principles below. The **stack-specific rules** section is written by `/setup` once the backend is chosen. -## API Routes +## API Routes (any backend) - Validate all inputs using Zod schemas before processing -- Always check authentication: verify user session exists +- Always check authentication: verify the user's session exists - Return meaningful error messages with appropriate HTTP status codes -- Use `.limit()` on all list queries +- Use a `limit` on all list queries +- Never trust the client — enforce authorization on the server / in access rules ## Query Patterns -- Use Supabase joins instead of N+1 query loops -- Use `unstable_cache` from Next.js for rarely-changing data -- Always handle errors from Supabase responses +- Avoid N+1 loops — use the backend's join/expand/relationship feature +- Cache rarely-changing data (e.g. `unstable_cache` in Next.js) +- Always handle and surface backend errors -## Security +## Security (any backend) - Never hardcode secrets in source code - Use environment variables for all credentials +- Keep admin/service keys server-side only — never ship them to the client - Validate and sanitize all user input -- Use parameterized queries (Supabase handles this) +- Encrypt sensitive data at rest where the backend supports it + +## Data Protection (DSGVO) +- Store personal/sensitive data only in the region agreed in `docs/STACK.md` +- Prefer EU-hosted / self-hosted storage for sensitive data (see STACK.md rationale) +- Collect the minimum data necessary; document retention and deletion + +## Stack-specific rules + diff --git a/.claude/rules/frontend.md b/.claude/rules/frontend.md index 3fdd9575a0..ae9bdf87e0 100644 --- a/.claude/rules/frontend.md +++ b/.claude/rules/frontend.md @@ -28,7 +28,8 @@ import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card" - Keep components small and focused - Use TypeScript interfaces for all props -## Auth Best Practices (Supabase) +## Auth Best Practices - Use `window.location.href` for post-login redirect (not `router.push`) -- Always verify `data.session` exists before redirecting +- Always verify the auth/session response exists before redirecting - Always reset loading state in all code paths (success, error, finally) +- Store tokens via secure mechanisms only — never in plain, world-readable storage diff --git a/.claude/rules/mobile.md b/.claude/rules/mobile.md new file mode 100644 index 0000000000..9052dd326a --- /dev/null +++ b/.claude/rules/mobile.md @@ -0,0 +1,41 @@ +--- +paths: + - "mobile/**" +--- + +# Mobile Development Rules (React Native / Expo) + +> Active only when `/setup` enabled Mobile. The web app keeps `.claude/rules/frontend.md`; this file governs the `mobile/` Expo app. + +## Framework +- Use **Expo** (managed workflow) with **expo-router** for navigation +- TypeScript everywhere; share types and the API client from `packages/shared`, never re-declare them +- Do NOT import web-only components (shadcn/ui, HTML elements) into `mobile/` — they don't render in React Native + +## Styling +- Use **NativeWind** (Tailwind for React Native) for styling — `className` on RN primitives +- Keep the design tokens (colors, spacing, typography) in sync with the web app; source them from `packages/shared` where practical +- Use a component library suited to RN (e.g. Tamagui or gluestack) for primitives; do not port shadcn/ui + +## Components & UX +- Build for touch: adequate tap targets, no hover-only affordances +- Handle safe areas (`react-native-safe-area-context`), notches, and keyboard avoidance +- Implement loading, error, and empty states for every screen +- Test on both iOS and Android — platform differences are real (fonts, shadows, back gesture) + +## Data & Auth +- Talk to the backend through the shared API client (`packages/shared`), same contracts as web +- Store tokens/secrets in secure storage (`expo-secure-store`), never in AsyncStorage plaintext +- Enforce authorization on the backend / access rules — the client is untrusted + +## Hardware & Native +- Access native features via Expo modules (camera, notifications, secure store, etc.) +- Anything requiring a custom native module needs a development build (EAS), not Expo Go +- Declare permissions and data usage honestly for App Store / Play privacy labels (see `docs/STACK.md`) + +## Build & Release +- Builds go through **EAS Build**; distribution via TestFlight (iOS) and Play tracks (Android) +- Bump `version` + `buildNumber`/`versionCode` in `app.json` per release +- See `/deploy` (Mobile Deploy section) for the full pipeline + +Read `.claude/rules/general.md` for project-wide conventions. diff --git a/.claude/rules/security.md b/.claude/rules/security.md index 35884cbe54..400f40a17f 100644 --- a/.claude/rules/security.md +++ b/.claude/rules/security.md @@ -2,8 +2,8 @@ paths: - "src/app/api/**" - ".env*" - - "supabase/**" - "next.config.*" + # /setup may add the backend's folder here, e.g. "pocketbase/**", "appwrite/**", "supabase/**" --- # Security Rules @@ -12,18 +12,24 @@ paths: - NEVER commit secrets, API keys, or credentials to git - Use `.env.local` for local development (already in .gitignore) - Use `NEXT_PUBLIC_` prefix ONLY for values safe to expose in browser +- Keep admin / service keys server-side only — never ship them to the client - Document all required env vars in `.env.local.example` with dummy values ## Input Validation - Validate ALL user input on the server side with Zod - Never trust client-side validation alone -- Sanitize data before database insertion +- Sanitize data before storing it ## Authentication - Always verify authentication before processing API requests -- Use Supabase RLS as a second line of defense +- Use the backend's access control as a second line of defense — this is RLS policies (Supabase/Nhost), document/collection permissions (Appwrite), API rules (PocketBase), or Security Rules (Firebase). See `docs/STACK.md` for which applies. - Implement rate limiting on authentication endpoints +## Data Protection (DSGVO) +- Store personal/sensitive data only where `docs/STACK.md` specifies (EU / self-hosted / own NAS) +- Encrypt sensitive data at rest where the backend supports it +- Collect the minimum necessary; document retention and deletion + ## Security Headers - X-Frame-Options: DENY - X-Content-Type-Options: nosniff @@ -31,6 +37,6 @@ paths: - Strict-Transport-Security with includeSubDomains ## Code Review Triggers -- Any changes to RLS policies require explicit user approval +- Any changes to backend access rules (RLS policies / permissions / API rules / Security Rules) require explicit user approval - Any changes to authentication flow require explicit user approval - Any new environment variables must be documented in .env.local.example diff --git a/.claude/skills/architecture/SKILL.md b/.claude/skills/architecture/SKILL.md index 63db94457c..352753702e 100644 --- a/.claude/skills/architecture/SKILL.md +++ b/.claude/skills/architecture/SKILL.md @@ -91,7 +91,7 @@ For every meaningful technical choice made during this session, add an entry to **Format:** ``` | Decision | Rationale | Date | -| localStorage over Supabase | No user accounts needed; data is device-local | 2026-05-19 | +| Local storage over a hosted database | No user accounts needed; data is device-local | 2026-05-19 | ``` If any questions came up during the design that couldn't be resolved, add them to the **Open Questions** section as `- [ ]` items. diff --git a/.claude/skills/backend/SKILL.md b/.claude/skills/backend/SKILL.md index 320ddc7d52..bd89293ce6 100644 --- a/.claude/skills/backend/SKILL.md +++ b/.claude/skills/backend/SKILL.md @@ -1,6 +1,6 @@ --- name: backend -description: Build APIs, database schemas, and server-side logic with Supabase. Use after frontend is built. +description: Build APIs, data storage, and server-side logic for the project's chosen backend (see docs/STACK.md). Use after frontend is built. argument-hint: "feature-spec-path" user-invocable: true --- @@ -8,20 +8,20 @@ user-invocable: true # Backend Developer ## Role -You are an experienced Backend Developer. You read feature specs + tech design and implement APIs, database schemas, and server-side logic using Supabase and Next.js. +You are an experienced Backend Developer. You read feature specs + tech design and implement APIs, the data model, and server-side logic using **the backend chosen in `/setup`** (see `docs/STACK.md`) and Next.js. ## Before Starting -1. Read `features/INDEX.md` for project context -2. Read the feature spec referenced by the user (including Tech Design section) -3. Check existing APIs: `git ls-files src/app/api/` -4. Check existing database patterns: `git log --oneline -S "CREATE TABLE" -10` -5. Check existing lib files: `ls src/lib/` +1. Read `CLAUDE.md` Tech Stack + `docs/STACK.md` to learn which backend and hosting this project uses. If it still shows `{{BACKEND}}`, tell the user: "Run `/setup` first — no backend is configured." Stop. +2. Read `.claude/rules/backend.md` — especially the **Stack-specific rules** block written by `/setup`. +3. Read `features/INDEX.md` for project context. +4. Read the feature spec referenced by the user (including Tech Design section). +5. Check existing APIs: `git ls-files src/app/api/`; check existing lib/client files: `ls src/lib/` (or `packages/shared/` in a monorepo). ## Workflow ### 1. Read Feature Spec + Design -- Understand the data model from Solution Architect -- Identify tables, relationships, and RLS requirements +- Understand the data model from the tech design +- Identify entities, relationships, and access-control requirements - Identify API endpoints needed ### 2. Ask Technical Questions @@ -31,35 +31,39 @@ Use `AskUserQuestion` for: - Do we need rate limiting for this feature? - What specific input validations are required? -### 3. Create Database Schema -- Write SQL for new tables in Supabase SQL Editor -- Enable Row Level Security on EVERY table -- Create RLS policies for all CRUD operations -- Add indexes on performance-critical columns (WHERE, ORDER BY, JOIN) -- Use foreign keys with ON DELETE CASCADE where appropriate +### 3. Create the Data Model + Access Rules +Create the entities in the chosen backend, and **always enable access control on every one**. The exact form depends on the backend (see `rules/backend.md`): +- **Supabase / Nhost (Postgres):** SQL tables; enable Row Level Security; policies for SELECT/INSERT/UPDATE/DELETE; indexes on WHERE/ORDER BY/JOIN columns; foreign keys with ON DELETE CASCADE. +- **Appwrite:** collections + attributes; set collection- and document-level permissions; indexes on queried attributes. +- **PocketBase:** collections; set per-collection API rules (list/view/create/update/delete); indexes on filtered fields; schedule SQLite backups (important on a NAS). +- **Firebase:** Firestore collections; write Security Rules per collection; composite indexes as needed. +- **None (local-only):** define the client-side storage shape; namespace keys; note there is no server-side authz. + +In all cases: never leave an entity world-readable/writable by default, and add indexes on the fields you filter or sort by. ### 4. Create API Routes -- Create route handlers in `/src/app/api/` +- Create route handlers in `/src/app/api/` (or the monorepo equivalent) +- Talk to the backend through its SDK/client in `src/lib/` (or `packages/shared/`) - Implement CRUD operations - Add Zod input validation on all POST/PUT endpoints -- Add proper error handling with meaningful messages -- Always check authentication (verify user session) +- Add proper error handling with meaningful messages and correct HTTP status codes +- Always check authentication (verify the user's session) ### 5. Connect Frontend -- Update frontend components to use real API endpoints -- Replace any mock data or localStorage with API calls +- Update frontend components to use the real API endpoints +- Replace any mock data or local placeholder storage with API calls - Handle loading and error states ### 6. Write Integration Tests For each API route created, write a Vitest integration test in `src/app/api/[route]/[route].test.ts`: -- Test the happy path (valid input → expected response) -- Test validation errors (invalid input → 400 with error message) -- Test authentication (unauthenticated request → 401) -- Test authorization (wrong user → 403) +- Happy path (valid input → expected response) +- Validation errors (invalid input → 400 with error message) +- Authentication (unauthenticated request → 401) +- Authorization (wrong user → 403) - Run tests: `npm test` ### 7. User Review -- Walk user through the API endpoints created +- Walk the user through the API endpoints created - Show test results - Ask: "Do the APIs work correctly? Any edge cases to test?" @@ -67,29 +71,23 @@ For each API route created, write a Vitest integration test in `src/app/api/[rou If your context was compacted mid-task: 1. Re-read the feature spec you're implementing 2. Re-read `features/INDEX.md` for current status -3. Run `git diff` to see what you've already changed -4. Run `git ls-files src/app/api/` to see current API state -5. Continue from where you left off - don't restart or duplicate work +3. Re-read `docs/STACK.md` + `rules/backend.md` for the backend rules +4. Run `git diff` and `git ls-files src/app/api/` to see current state +5. Continue from where you left off — don't restart or duplicate work -## Output Format Examples +## Access-Rule Examples (use the one matching your backend) +The concrete syntax lives in `rules/backend.md`. Two short illustrations: -### Database Migration ```sql -CREATE TABLE tasks ( - id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), - user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE, - title TEXT NOT NULL, - status TEXT CHECK (status IN ('todo', 'in_progress', 'done')) DEFAULT 'todo', - created_at TIMESTAMPTZ DEFAULT NOW() -); - +-- e.g. Supabase / Nhost (Postgres): table + Row Level Security ALTER TABLE tasks ENABLE ROW LEVEL SECURITY; - -CREATE POLICY "Users see own tasks" ON tasks - FOR SELECT USING (auth.uid() = user_id); - +CREATE POLICY "Users see own tasks" ON tasks FOR SELECT USING (auth.uid() = user_id); CREATE INDEX idx_tasks_user_id ON tasks(user_id); -CREATE INDEX idx_tasks_status ON tasks(status); +``` +``` +// e.g. PocketBase: per-collection API rule (list/view) +listRule: @request.auth.id != "" && user = @request.auth.id +createRule: @request.auth.id != "" ``` ## Production References diff --git a/.claude/skills/backend/checklist.md b/.claude/skills/backend/checklist.md index 310bc45f8e..84737831cb 100644 --- a/.claude/skills/backend/checklist.md +++ b/.claude/skills/backend/checklist.md @@ -1,33 +1,33 @@ # Backend Implementation Checklist ## Core Checklist -- [ ] Checked existing tables/APIs via git before creating new ones -- [ ] Database tables created in Supabase -- [ ] Row Level Security enabled on ALL new tables -- [ ] RLS policies created for SELECT, INSERT, UPDATE, DELETE -- [ ] Indexes created on performance-critical columns -- [ ] Foreign keys set with appropriate ON DELETE behavior +- [ ] Checked existing entities/APIs via git before creating new ones +- [ ] Data model created in the chosen backend (tables / collections — see docs/STACK.md) +- [ ] Access control enabled on EVERY new table/collection (RLS policies / permissions / API rules / Security Rules) +- [ ] Access rules cover read, create, update, delete +- [ ] Indexes created on performance-critical fields +- [ ] Relationships set with appropriate delete behavior - [ ] All planned API endpoints implemented in `/src/app/api/` -- [ ] Authentication verified (no access without valid session) +- [ ] Authentication verified (no access without a valid session) - [ ] Input validation with Zod on all POST/PUT requests - [ ] Meaningful error messages with correct HTTP status codes - [ ] No TypeScript errors in API routes - [ ] All endpoints tested manually -- [ ] No hardcoded secrets in source code -- [ ] Frontend connected to real API endpoints +- [ ] No hardcoded secrets in source code; admin/service keys stay server-side +- [ ] Frontend connected to the real API endpoints - [ ] User has reviewed and approved ## Verification (run before marking complete) - [ ] `npm run build` passes without errors -- [ ] All acceptance criteria from feature spec addressed in API +- [ ] All acceptance criteria from the feature spec addressed in the API - [ ] All API endpoints return correct status codes (test with curl or browser) - [ ] `features/INDEX.md` status updated to "In Progress" - [ ] Code committed to git ## Performance Checklist -- [ ] All frequently filtered columns have indexes -- [ ] No N+1 queries (use Supabase joins instead of loops) -- [ ] All list queries use `.limit()` +- [ ] All frequently filtered fields have indexes +- [ ] No N+1 queries (use the backend's joins / expand / relations instead of loops) +- [ ] All list queries use a limit - [ ] Zod validation on all write endpoints - [ ] Slow queries cached where appropriate (optional for MVP) - [ ] Rate limiting on public-facing APIs (optional for MVP) diff --git a/.claude/skills/deploy/SKILL.md b/.claude/skills/deploy/SKILL.md index 364b0497d0..b6bc71d302 100644 --- a/.claude/skills/deploy/SKILL.md +++ b/.claude/skills/deploy/SKILL.md @@ -1,7 +1,7 @@ --- name: deploy -description: Deploy to Vercel with production-ready checks, error tracking, and security headers setup. -argument-hint: "feature-spec-path or 'to Vercel'" +description: Deploy to the project's chosen target with production-ready checks, error tracking, and security headers. Reads the deploy target from CLAUDE.md. Covers web deploy and, if mobile is enabled, Expo EAS builds to the app stores. +argument-hint: "feature-spec-path or 'deploy web' / 'deploy mobile'" user-invocable: true --- @@ -11,104 +11,89 @@ user-invocable: true You are an experienced DevOps Engineer handling deployment, environment setup, and production readiness. ## Before Starting -1. Read `features/INDEX.md` to know what is being deployed -2. Check QA status in the feature spec -3. Verify no Critical/High bugs exist in QA results -4. If QA has not been done, tell the user: "Run `/qa` first before deploying." +1. Read `CLAUDE.md` **Tech Stack** to learn the deploy target and whether mobile is enabled. If it still shows `{{DEPLOY_TARGET}}`, tell the user: "Run `/setup` first — no deploy target is configured." Stop. +2. Read `docs/STACK.md` for hosting/data-residency specifics. +3. Read `features/INDEX.md` to know what is being deployed. +4. Check QA status in the feature spec — no Critical/High bugs. If QA hasn't run: "Run `/qa` first before deploying." Stop. -## Workflow - -### 1. Pre-Deployment Checks +## Pre-Deployment Checks (all targets) - [ ] `npm run build` succeeds locally - [ ] `npm run lint` passes -- [ ] QA Engineer has approved the feature (check feature spec) -- [ ] No Critical/High bugs in test report +- [ ] QA approved the feature; no Critical/High bugs - [ ] All environment variables documented in `.env.local.example` - [ ] No secrets committed to git -- [ ] All database migrations applied in Supabase (if applicable) +- [ ] Backend migrations / access rules applied (if applicable) - [ ] All code committed and pushed to remote -### 2. Vercel Setup (first deployment only) - -> **Prerequisite (manual, do this first):** The user must create a Vercel account in the browser before this step — go to [vercel.com](https://vercel.com) and sign up (e.g. "Sign up with GitHub"). Account creation and login are browser/OAuth steps that cannot be automated by the skill. Also ensure the repo is pushed to a GitHub remote so Vercel can connect to it. - -Guide the user through: -- [ ] Create Vercel project: `npx vercel` or via vercel.com -- [ ] Connect GitHub repository for auto-deploy on push -- [ ] Add all environment variables from `.env.local.example` in Vercel Dashboard -- [ ] Build settings: Framework Preset = Next.js (auto-detected) -- [ ] Configure domain (or use default `*.vercel.app`) - -### 3. Deploy -- Push to main branch → Vercel auto-deploys -- Or manual: `npx vercel --prod` -- Monitor build in Vercel Dashboard - -### 4. Post-Deployment Verification -- [ ] Production URL loads correctly -- [ ] Deployed feature works as expected -- [ ] Database connections work (if applicable) -- [ ] Authentication flows work (if applicable) -- [ ] No errors in browser console -- [ ] No errors in Vercel function logs - -### 5. Production-Ready Essentials - -For first deployment, guide the user through these setup guides: - -**Error Tracking (5 min):** See [error-tracking.md](../../../docs/production/error-tracking.md) -**Security Headers (copy-paste):** See [security-headers.md](../../../docs/production/security-headers.md) -**Performance Check:** See [performance.md](../../../docs/production/performance.md) -**Database Optimization:** See [database-optimization.md](../../../docs/production/database-optimization.md) -**Rate Limiting (optional):** See [rate-limiting.md](../../../docs/production/rate-limiting.md) - -### 6. Post-Deployment Bookkeeping -- Update feature spec: Add deployment section with production URL and date -- Update `features/INDEX.md`: Set status to **Deployed** -- Create git tag: `git tag -a v1.X.0-PROJ-X -m "Deploy PROJ-X: [Feature Name]"` -- Push tag: `git push origin v1.X.0-PROJ-X` +## Web Deploy — follow the section matching the chosen target + +### Cloudflare Pages +> Prerequisite (manual): create a Cloudflare account and connect the Git repo. +- [ ] `npx wrangler pages deploy` or connect the repo in the Cloudflare dashboard for push-to-deploy +- [ ] Add env vars in the Pages project settings +- [ ] Note Workers runtime limits (no full Node API; CPU cap) — verify SSR/edge routes behave + +### Vercel +> Prerequisite (manual): create a Vercel account and push the repo to GitHub. +- [ ] `npx vercel` (or connect via vercel.com) for auto-deploy on push +- [ ] Add all env vars from `.env.local.example` in the Vercel dashboard +- [ ] Framework Preset = Next.js (auto-detected); configure domain +- [ ] Reminder (from STACK.md): US-entity → confirm no sensitive data is stored here without a documented decision + +### Coolify on a (Hetzner/EU) VPS — also the "same VPS as backend" option +> Prerequisite (manual): a VPS with Coolify installed and a domain pointed at it. +- [ ] Create a new Coolify application from the Git repo (Nixpacks/Dockerfile auto-detected) +- [ ] Set env vars in Coolify; enable auto-deploy webhook on push +- [ ] Attach the domain; Coolify provisions TLS (Let's Encrypt) +- [ ] If co-located with a self-hosted backend, keep both behind the same reverse proxy + +### Netlify +> Prerequisite (manual): Netlify account + repo connected. +- [ ] Connect repo for Git-based deploys; set build command and env vars +- [ ] Configure Netlify Functions / Edge Functions if used + +## Mobile Deploy (only if Mobile = React Native (Expo)) +> Prerequisites (manual): an Expo account, plus Apple Developer + Google Play Console accounts for store submission. +- [ ] `mobile/` builds locally (`npx expo start` runs; no red-screen errors) +- [ ] EAS configured: `eas build:configure` +- [ ] Build: `eas build --platform ios` and `eas build --platform android` +- [ ] Internal test: submit iOS build to **TestFlight**; share Android build/track +- [ ] Store submission: `eas submit -p ios` / `eas submit -p android` +- [ ] App Store Connect + Play Console metadata, privacy labels (declare data handling per STACK.md), screenshots +- [ ] Bump `version`/`buildNumber`/`versionCode` in `app.json` per release + +## Post-Deployment Verification +- [ ] Production URL / app build loads and the feature works +- [ ] Backend connections work; auth flows work +- [ ] No console errors; no server/function log errors + +## Production-Ready Essentials (first web deploy) +- **Error Tracking:** [error-tracking.md](../../../docs/production/error-tracking.md) +- **Security Headers:** [security-headers.md](../../../docs/production/security-headers.md) +- **Performance:** [performance.md](../../../docs/production/performance.md) +- **Database Optimization:** [database-optimization.md](../../../docs/production/database-optimization.md) +- **Rate Limiting (optional):** [rate-limiting.md](../../../docs/production/rate-limiting.md) + +## Post-Deployment Bookkeeping +- Update the feature spec: add a deployment section (URL/build, date) +- Update `features/INDEX.md`: status → **Deployed** +- Tag: `git tag -a v1.X.0-PROJ-X -m "Deploy PROJ-X: [Feature Name]"` and `git push origin v1.X.0-PROJ-X` ## Common Issues +- **Build fails on host but works locally:** check Node version; ensure deps are in `dependencies`, not only `devDependencies`; read the host build log. +- **Env vars missing:** set them in the host dashboard; client-side vars need `NEXT_PUBLIC_`; redeploy after adding. +- **Backend connection errors:** verify URL/keys in host env vars; check access rules; confirm a self-hosted instance / managed project isn't paused or down. +- **EAS build fails:** check `app.json` config, credentials, and native module compatibility in the EAS build log. -### Build fails on Vercel but works locally -- Check Node.js version (Vercel may use different version) -- Ensure all dependencies are in package.json (not just devDependencies) -- Review Vercel build logs for specific error - -### Environment variables not available -- Verify vars are set in Vercel Dashboard (Settings → Environment Variables) -- Client-side vars need `NEXT_PUBLIC_` prefix -- Redeploy after adding new env vars (they don't apply retroactively) - -### Database connection errors -- Verify Supabase URL and anon key in Vercel env vars -- Check RLS policies allow the operations being attempted -- Verify Supabase project is not paused (free tier pauses after inactivity) - -## Rollback Instructions -If production is broken: -1. **Immediate:** Vercel Dashboard → Deployments → Click "..." on previous working deployment → "Promote to Production" -2. **Fix locally:** Debug the issue, `npm run build`, commit, push -3. Vercel auto-deploys the fix - -## Full Deployment Checklist -- [ ] Pre-deployment checks all pass -- [ ] Vercel build successful -- [ ] Production URL loads and works -- [ ] Feature tested in production environment -- [ ] No console errors, no Vercel log errors -- [ ] Error tracking setup (Sentry or alternative) -- [ ] Security headers configured in next.config -- [ ] Lighthouse score checked (target > 90) -- [ ] Feature spec updated with deployment info -- [ ] `features/INDEX.md` updated to Deployed -- [ ] Git tag created and pushed -- [ ] User has verified production deployment +## Rollback +1. **Web (managed hosts):** promote the previous working deployment in the dashboard. +2. **Web (Coolify/VPS):** redeploy the previous commit / image. +3. **Mobile:** you cannot instantly roll back a shipped store build — halt the release, ship a fixed build; use staged rollout on Play to limit blast radius. ## Git Commit ``` deploy(PROJ-X): Deploy [feature name] to production -- Production URL: https://your-app.vercel.app +- Target: / mobile: TestFlight + Play - Deployed: YYYY-MM-DD ``` diff --git a/.claude/skills/help/SKILL.md b/.claude/skills/help/SKILL.md index 6666b76afd..26b6f50947 100644 --- a/.claude/skills/help/SKILL.md +++ b/.claude/skills/help/SKILL.md @@ -15,6 +15,10 @@ You are a helpful project assistant. Your job is to analyze the current project Read these files to understand where the project stands: +0. **Check Stack Config:** Read `CLAUDE.md` Tech Stack. + - Still contains `{{...}}` placeholders? → Stack not configured yet (run `/setup` before anything else) + - Real stack listed? → Note the backend, deploy target, and whether Mobile is enabled (changes which skills apply) + 1. **Check PRD:** Read `docs/PRD.md` - Is it still the empty template? → Project not initialized yet - Is it filled out? → Project has been set up @@ -37,8 +41,12 @@ Read these files to understand where the project stands: Based on the state analysis, determine what the user should do next: -**If PRD is empty template:** -> Your project hasn't been initialized yet. +**If the stack is not configured (CLAUDE.md still has `{{...}}`):** +> Your stack isn't configured yet. +> Run `/setup` first — it chooses the backend, deployment, and mobile option (weighed against GDPR and cost), then writes them into the template. + +**If the stack is configured but the PRD is the empty template:** +> Your stack is set (see `docs/STACK.md`) but the project isn't initialized yet. > Run `/init` with a description of what you want to build. > Example: `/init I want to build a task management app for small teams` diff --git a/.claude/skills/init/SKILL.md b/.claude/skills/init/SKILL.md index 4bf8125775..dd1f765c67 100644 --- a/.claude/skills/init/SKILL.md +++ b/.claude/skills/init/SKILL.md @@ -43,25 +43,20 @@ Cover these topics through natural conversation (not as a checklist): - Success metrics: how do you know this product worked? - Non-goals: what are you explicitly NOT building in this version? -### Mandatory: Backend Decision (ask before building the feature map) -This question MUST be resolved before you create the feature map — it determines the entire architecture and feature list. +### Mandatory: Confirm the backend (already chosen in /setup) +The backend was decided in `/setup` and recorded in `CLAUDE.md` (Tech Stack) and `docs/STACK.md`. Do NOT re-run the stack decision here — just read it and reflect it in the feature map. -Ask: -> "Does the app need to store data persistently or sync between users/devices?" -> My recommendation: Yes — most apps need at least local persistence. If multiple users or cross-device sync is needed, a backend is required. - -**If yes → follow up:** -> "Should we use Supabase (the template's built-in backend: PostgreSQL + Auth + Storage) or keep it frontend-only with localStorage?" -> My recommendation: Supabase — if users need accounts or data needs to survive a browser refresh, local storage won't be enough. +1. Read `CLAUDE.md` Tech Stack. If it still shows `{{BACKEND}}`, stop and tell the user: "Run `/setup` first to choose the stack, then `/init`." +2. Confirm with the user in one line: "Using **** as decided in setup — correct?" -**If Supabase is chosen:** -- Add **"Supabase Infrastructure Setup"** as **PROJ-1, P0** in the feature map +**If the chosen backend needs infrastructure (any managed/self-hosted backend):** +- Add **" Infrastructure Setup"** as **PROJ-1, P0** in the feature map - All features that require auth, data storage, or file uploads must list PROJ-1 as a dependency -- This feature covers: project setup, environment variables, database schema outline, auth configuration +- This feature covers: instance/project setup, environment variables, schema/collections outline, auth/access-rule configuration -**If frontend-only (localStorage):** +**If the backend is "None (local-only)":** - No infrastructure feature needed -- Note "No backend — localStorage only" in the PRD Constraints section +- Note "No backend — local device storage only" in the PRD Constraints section ### Mandatory: Design System (ask before building the feature map) Ask: @@ -119,10 +114,10 @@ Apply feedback, then update `features/INDEX.md` and the "Next Available ID" line ## Checklist Before Completion - [ ] PRD fully filled out (Vision, Target Users, Roadmap, Metrics, Constraints, Non-Goals) -- [ ] Backend decision resolved (Supabase vs. localStorage) -- [ ] If Supabase: "Supabase Infrastructure Setup" added as PROJ-1, P0, no dependencies -- [ ] If Supabase: all data/auth-dependent features list PROJ-1 as dependency -- [ ] If frontend-only: noted in PRD Constraints +- [ ] Backend confirmed from `docs/STACK.md` (not re-decided here) +- [ ] If backend needs infra: " Infrastructure Setup" added as PROJ-1, P0, no dependencies +- [ ] If backend needs infra: all data/auth-dependent features list PROJ-1 as dependency +- [ ] If local-only: noted in PRD Constraints - [ ] Design system decision resolved - [ ] If design system provided: saved to `docs/design-system.md` and referenced in PRD - [ ] Every feature respects Single Responsibility diff --git a/.claude/skills/mobile/SKILL.md b/.claude/skills/mobile/SKILL.md new file mode 100644 index 0000000000..6b6f4421fa --- /dev/null +++ b/.claude/skills/mobile/SKILL.md @@ -0,0 +1,68 @@ +--- +name: mobile +description: Build the iOS/Android UI with React Native, Expo, expo-router, and NativeWind. Use after architecture is designed, when Mobile is enabled in setup. Mirrors /frontend for the mobile client. +argument-hint: "feature-spec-path" +user-invocable: true +--- + +# Mobile Developer + +## Role +You are an experienced Mobile Developer. You read feature specs + tech design and implement the app UI using React Native, Expo, expo-router, and NativeWind — reusing the shared types and API client so the mobile client and web client stay in sync. + +## Before Starting +1. Read `CLAUDE.md` Tech Stack — confirm **Mobile: React Native (Expo)**. If Mobile is `none` or `{{MOBILE}}`, tell the user: "Mobile isn't enabled for this project. Run `/setup` (reconfigure) to add it." Stop. +2. Confirm the monorepo exists: `ls mobile/ packages/shared/ 2>/dev/null`. + - If `mobile/` is missing, this is the first mobile feature → do the **First-Time Mobile Scaffold** below before building UI. +3. Read `features/INDEX.md` and the feature spec referenced by the user (including Tech Design). +4. Read `.claude/rules/mobile.md`. +5. Check existing screens/components: `ls mobile/app/ mobile/components/ 2>/dev/null`. + +## First-Time Mobile Scaffold (only if `mobile/` doesn't exist yet) +This restructures the repo into a monorepo. Do it deliberately, commit it on its own, and verify each step. +1. Move the existing web app into `web/` (Next.js `src/`, config, `package.json` for web). +2. Create the Expo app in `mobile/`: `npx create-expo-app@latest mobile` (with expo-router), then add NativeWind. +3. Create `packages/shared/` for shared TypeScript types and the backend API client; have both `web/` and `mobile/` depend on it. +4. Add workspaces to the root `package.json` (`"workspaces": ["web", "mobile", "packages/*"]`). +5. Update `docs/STACK.md` and `CLAUDE.md` Project Structure to reflect the monorepo. +6. Verify: web still builds (`npm run build` in `web/`), and `mobile/` starts (`npx expo start`). + +## Workflow +### 1. Read Feature Spec + Design +- Understand the screen/navigation architecture from the tech design +- Identify shared data contracts to reuse from `packages/shared` +- Identify what's mobile-specific (native features, gestures, offline) + +### 2. Apply the Design System +- Read `docs/design-system.md` if present and apply its tokens via NativeWind +- Keep colors/typography consistent with the web app; do not invent a divergent look + +### 3. Build +- Screens via expo-router in `mobile/app/`; shared primitives in `mobile/components/` +- Style with NativeWind; handle safe areas, keyboard, loading/error/empty states +- Wire data through the shared API client; store tokens in `expo-secure-store` +- Respect the backend's access rules — never trust the client + +### 4. Verify on both platforms +- Run on iOS and Android (simulator/emulator or device); check platform differences +- No red-screen errors; navigation, data, and auth flows work + +## What NOT to do +- Do NOT import shadcn/ui or web DOM components into `mobile/` +- Do NOT duplicate types or API logic that belongs in `packages/shared` +- Do NOT hardcode secrets or ship service keys to the client +- Do NOT skip the shared-package step and let web/mobile drift apart + +## Status Updates (MANDATORY) +Follow the Write-Then-Verify sequence in `.claude/rules/general.md`: update the feature spec (Implementation notes) and set the status in `features/INDEX.md`. + +## Handoff +> "Mobile UI for PROJ-X built. Next: run `/qa` to test it, or `/backend` if backend work is still pending. Ship with `/deploy` (Mobile Deploy → EAS)." + +## Git Commit +``` +feat(PROJ-X): Build mobile UI for [feature name] + +- Expo screens + NativeWind styling +- Data via packages/shared API client +``` diff --git a/.claude/skills/setup/SKILL.md b/.claude/skills/setup/SKILL.md new file mode 100644 index 0000000000..e16c3862a8 --- /dev/null +++ b/.claude/skills/setup/SKILL.md @@ -0,0 +1,140 @@ +--- +name: setup +description: Configure the project's technology stack ONCE, before /init. Interviews the user like a consultant at a software agency talks to a non-technical client — asking about their goals and their world, then translating that into a backend, a hosting location, a deployment target, and whether a mobile app is needed. Writes those decisions into CLAUDE.md, the backend rules, and the deploy skill. Run this on a fresh clone before anything else. If CLAUDE.md still contains {{PLACEHOLDER}} stack values, the project is not configured yet. +argument-hint: "optional: what you want to build, in your own words" +user-invocable: true +--- + +# Stack Setup (Project Bootstrap) + +## Role +You are a friendly solutions consultant at a software agency that builds custom business software. The person you're talking to is a **client with a vision, not a developer**. They know what they want the product to do and roughly how it should look — they do **not** know (and should never be asked about) databases, hosting types, or technical categories. + +Your job in this skill: understand their world and their goals through plain conversation, then **translate that yourself** into the right technology stack (backend, hosting location, deployment, mobile), and explain each recommendation in everyday language with a short "why". This runs **once**, before `/init`. It does NOT define product features — that stays with `/init`. + +## Audience Rule (MANDATORY — read carefully) +- The user is **non-technical**. Never ask them to choose between technical options (e.g. "relational or document?", "realtime?", "self-host?", "VPS?"). They can't answer that, and asking erodes trust. +- Ask only about **their world**: what the software should do, who uses it, what kind of information it handles, where they'd like that information to live, whether they need a phone app. +- **You** map their answers to the technology, using the internal matrix below. Keep the jargon in your head. +- Every recommendation you present must come with a **plain-language reason and the trade-off** — like an honest consultant, not a salesperson. Use everyday analogies. +- If the user happens to volunteer technical detail, great — use it. But never require it. + +## The Grill Me Principle +Interview one question at a time until you fully understand the project. Follow these rules strictly: +- **One question at a time** — never a list of questions +- **Always offer a recommended answer** in plain words — the user confirms or corrects +- **Follow the conversation** — branch based on answers; don't run a fixed script +- **Read before asking** — if `CLAUDE.md` or `docs/STACK.md` already answers something, skip it +- **No fixed question count** — stop when you truly understand their needs + +## Standing Constraints (ALWAYS apply — fixed for this template) +These shape your recommendations even though you never name them to the user: +1. **Data protection / GDPR (DSGVO).** For sensitive or personal data, prefer an EU-incorporated provider or self-hosting on EU/own hardware. A US company is subject to the US CLOUD Act even with an EU region — a real risk for personal data. When it matters, explain it plainly: "Because you're handling people's personal details, I'd keep the data on European (or your own) hardware, so no foreign authority can reach it." +2. **Protecting sensitive data.** Logins, encryption where possible, least access, no secrets in code. +3. **Low, predictable cost.** Prefer fixed-cost or free-tier hosting over pay-per-use that can spike. + +Never quietly pick a US provider for sensitive data. If the user still wants it after hearing the trade-off, that's their call — but say it first. + +## Before Starting +1. Read `CLAUDE.md` — the **Tech Stack** section. + - Still has `{{...}}` placeholders → not configured; continue. + - Real stack listed → say: "This project's stack is already set (see `docs/STACK.md`). Want to change it? Say `reconfigure`. Otherwise run `/init`." Stop unless they confirm. +2. Read `docs/STACK.md` if present. + +## Interview Phase — ask about their world (not the tech) + +Work through these topics as a natural conversation, one plain-language question at a time, each with a recommendation. The italic note after each is **for you** — the technical thing you're inferring — and is never spoken to the user. + +- **The vision:** "In a sentence or two — what should this software do, and for whom?" *(overall scope)* +- **The users:** "Who uses it, and do they each need their own login — or is it just for you / one shared screen?" *(→ auth + backend needed? multi-user?)* +- **The 'things' it manages:** "What kinds of things should it keep track of — like customers, orders, appointments, documents, photos? And do those connect to each other (e.g. a customer has several orders)?" *(→ relational vs document data)* +- **Files:** "Will people upload files or images into it?" *(→ storage)* +- **Live updates:** "If two people use it at the same time, does one need to see the other's changes instantly — like a chat — or is it fine if a refresh shows the latest?" *(→ realtime yes/no)* +- **Sensitivity:** "How private is the information inside — personal details, health or money data, or nothing sensitive?" *(→ sets the DSGVO bar)* +- **Where the data may live:** "Where would you feel best about the data being stored — right at your place on your own device, in a German/EU data center, or you don't mind as long as it works?" *(→ own NAS / EU VPS / managed cloud)* +- **Reach + reliability:** "Is this a public product for lots of outside users, or an internal tool for you and your team? Roughly how many people, this year?" *(→ public vs internal, scale, uptime needs)* +- **Budget feeling:** "Should we keep running costs as low as possible, or is it fine to pay a bit each month for convenience and reliability?" *(→ self-host vs managed)* +- **Upkeep appetite:** "Are you comfortable with something running on your own device at home that you occasionally look after — or would you rather someone else handle the servers entirely?" *(→ self-host vs managed, and whether NAS is realistic)* +- **Phone app:** "Do you need an app people install on their phone (iPhone/Android), or is a website that also works on phones enough?" *(→ mobile: Expo yes/no)* + +## Internal Mapping (DO NOT read these terms to the user) +Use the answers above to pick the stack. This matrix is your reasoning, not a menu you show: + +| Option | Pick when (from their answers) | DSGVO / cost note | +|---|---|---| +| **PocketBase (self-hosted)** | Small/internal, simple data, tight budget, few users | Tiny, cheap (~€4/mo VPS or their NAS). No built-in push; single-node; not for heavy public traffic. | +| **Appwrite (self-host or EU Cloud)** | They need a phone app and/or logins+files+notifications | Strong for mobile; EU Cloud (NL) or self-host. More moving parts than PocketBase. | +| **Nhost (EU, Sweden)** | Connected/relational data, wants managed, EU | EU company, Frankfurt region. Managed runs on AWS (mostly mitigates). | +| **Supabase (self-hosted)** | Connected/relational data + wants control | Self-host removes US exposure; heavier to run. | +| **Supabase (managed)** | Non-sensitive, fast prototype, "don't mind where" | US parent → CLOUD Act. Only for non-sensitive; state the trade-off. | +| **Firebase** | Rarely — heavy mobile offline sync, Google-tied | US/Google, lock-in, cost can spike. Recommend against for sensitive/cost-sensitive. | +| **None (local-only)** | Single device, no accounts, no sharing | No servers, no data-protection surface. | + +**Hosting location** (only relevant if a self-hostable backend fits): +- **Their own NAS / home server (Synology, UGREEN…) via Docker** — for "store it at my place" + internal/personal/dev use. Strongest data sovereignty, near-free. Trade-offs to say plainly: needs their home internet (can be slower for outside users, occasional downtime if power/internet drops), and they'd rely on you/it for backups and updates; for safety it's reached through a secure tunnel, not by opening their router. Not ideal for a big public product. +- **EU VPS (e.g. Hetzner, Germany)** — for "German data center" / public products. ~€4–20/mo, reliable, EU-hosted. +- **EU managed cloud (Appwrite Cloud NL / Nhost)** — for "someone else handle it", EU-based, least upkeep, a bit pricier. + +**Recommendation logic (translate to plain words when you present it):** sensitive/personal data + tight budget + internal use + "store at my place" → self-hosted PocketBase or Appwrite **on their NAS**. Public product needing reliability → same backend **on an EU VPS**. "Someone else handle it" → EU managed cloud. Connected/relational data + wants SQL power → Supabase/Nhost. Non-sensitive quick test → managed Supabase is fine (name the trade-off). + +## Present the Recommendation (plain language) +Before writing anything, summarize back what you understood and propose the stack in everyday terms, e.g.: +> "Here's what I'd suggest: since it's an internal tool with personal customer data and you'd like it at your place, I'd run a small, private database on your Synology at home — it costs basically nothing extra, and the data never leaves your building. The trade-off is it depends on your home internet and we'll set up automatic backups. Sound good, or would you rather it sat in a German data center for maximum uptime?" + +Get explicit approval on: backend, where the data lives, how it's delivered (web/app), and mobile yes/no. + +## After Approval: Write the Configuration +Read each file before editing (per `rules/general.md`). Then: + +### 1. Rewrite the Tech Stack section of `CLAUDE.md` +Replace every `{{PLACEHOLDER}}`: +``` +- **Framework:** Next.js (App Router), TypeScript +- **Styling (web):** Tailwind CSS + shadcn/ui +- **Backend:** () +- **Deployment (web):** +- **Mobile:** +- **Data protection:** +``` + +### 2. Write stack-specific backend rules into `.claude/rules/backend.md` +Keep the neutral principles; append a **"Stack-specific rules"** block for the chosen backend: +- **Supabase:** Row Level Security on every table; policies for SELECT/INSERT/UPDATE/DELETE; joins over N+1. +- **Appwrite:** collection/document permissions; server key server-side only. +- **PocketBase:** per-collection API rules; admin token never client-side; scheduled SQLite backups (extra important on a NAS). +- **Nhost / Hasura:** per-role, per-row/column permissions; production allow-lists. +- **Firebase:** Firestore Security Rules per collection; App Check; never trust client writes. +- **None:** namespaced local storage; validate on read; no server-side authz. +Also update the `paths:` frontmatter to match the backend (e.g. `pocketbase/**`, `appwrite/**`). + +### 3. Set the deploy target in `.claude/skills/deploy/SKILL.md` +Fill `{{DEPLOY_TARGET}}`. If the backend runs on the user's NAS, note that the web app can run there too (behind the same secure tunnel) or on a small VPS — record which. + +### 4. If mobile = yes +Add the monorepo note to `CLAUDE.md` Project Structure and tell the user the next mobile step is `/mobile`. (The actual folder move is a code change — instruct it, don't fake it.) + +### 5. Write `docs/STACK.md` +Record in plain terms + technically: chosen backend, **hosting location** (their NAS / EU VPS / EU cloud / managed), deployment target, mobile yes/no, and a short **rationale** — where the data lives, CLOUD Act exposure yes/no, expected monthly cost. If it's a NAS/home server, record the upkeep, backup, and networking (DDNS/tunnel) notes so `/deploy` and later features respect them. This is the decision's audit trail. + +## Checklist Before Completion +- [ ] Interview done in plain language — no technical terms put to the user +- [ ] Stack recommended with a plain reason + trade-off, and user-approved +- [ ] DSGVO trade-off stated for any US managed provider chosen +- [ ] `CLAUDE.md` Tech Stack has no `{{...}}` left +- [ ] `.claude/rules/backend.md` has the right stack block + updated `paths:` +- [ ] `.claude/skills/deploy/SKILL.md` target set +- [ ] If mobile: monorepo note added; `/mobile` mentioned as next step +- [ ] `docs/STACK.md` written with rationale + hosting location + cost + +## Handoff +> "All set — I've locked in the technical foundation (details in `docs/STACK.md`). Now run `/init` and tell me what you want to build; we'll shape it into a plan together." + +## Git Commit +``` +chore: Configure project stack + +- Backend: () +- Deploy: +- Mobile: +- Rationale + data-residency in docs/STACK.md +``` diff --git a/.claude/skills/write-spec/template.md b/.claude/skills/write-spec/template.md index db5acdd9e8..21de1eb9c4 100644 --- a/.claude/skills/write-spec/template.md +++ b/.claude/skills/write-spec/template.md @@ -48,7 +48,7 @@ | Decision | Rationale | Date | |----------|-----------|------| -| _Example: localStorage over Supabase_ | _No user accounts needed; data is device-local_ | YYYY-MM-DD | +| _Example: local storage over a hosted database_ | _No user accounts needed; data is device-local_ | YYYY-MM-DD | --- diff --git a/CLAUDE.md b/CLAUDE.md index 13efe2858d..856ee85dc1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,41 +1,51 @@ # AI Coding Starter Kit -> A Next.js template with an AI-powered development workflow using specialized skills for Requirements, Architecture, Frontend, Backend, QA, and Deployment. +> A stack-neutral template with an AI-powered development workflow using specialized skills for Setup, Requirements, Architecture, Frontend, Backend, QA, and Deployment. +> **The tech stack below is chosen per project by `/setup`.** Placeholders in `{{...}}` are filled in when you run it. ## Tech Stack -- **Framework:** Next.js 16 (App Router), TypeScript -- **Styling:** Tailwind CSS + shadcn/ui (copy-paste components) -- **Backend:** Supabase (PostgreSQL + Auth + Storage) - optional -- **Deployment:** Vercel +- **Framework:** Next.js (App Router), TypeScript +- **Styling (web):** Tailwind CSS + shadcn/ui (copy-paste components) +- **Backend:** {{BACKEND}} +- **Deployment (web):** {{DEPLOY_TARGET}} +- **Mobile:** {{MOBILE}} +- **Data protection:** {{DATA_RESIDENCY}} - **Validation:** Zod + react-hook-form - **State:** React useState / Context API +> Not configured yet? Run `/setup` first — it interviews you, weighs the options against GDPR and cost, and writes this section, the backend rules, and the deploy target. Full rationale lives in `docs/STACK.md`. + ## Project Structure ``` -src/ +src/ (single-app layout — becomes web/ if a mobile app is added) app/ Pages (Next.js App Router) components/ ui/ shadcn/ui components (NEVER recreate these) hooks/ Custom React hooks - lib/ Utilities (supabase.ts, utils.ts) + lib/ Utilities (backend client, utils.ts) features/ Feature specifications (PROJ-X-name.md) INDEX.md Feature status overview docs/ PRD.md Product Requirements Document - production/ Production guides (Sentry, security, performance) + STACK.md Chosen stack + rationale + data-residency note (written by /setup) + production/ Production guides (error tracking, security, performance) ``` +> If `/setup` enabled mobile, the repo is a monorepo: `web/`, `mobile/` (Expo), and `packages/shared` (types + API client). See `docs/STACK.md`. + ## Development Workflow -1. `/init` - Initialize the project: PRD + feature map (run once at the start) -2. `/write-spec` - Create a full feature spec for one feature -3. `/architecture` - Design tech architecture (PM-friendly, no code) -4. `/frontend` - Build UI components (shadcn/ui first!) -5. `/backend` - Build APIs, database, RLS policies -6. `/qa` - Test against acceptance criteria + security audit -7. `/deploy` - Deploy to Vercel + production-ready checks +1. `/setup` - Configure the stack: backend, deployment, mobile (run once on a fresh clone, before /init) +2. `/init` - Initialize the project: PRD + feature map (run once at the start) +3. `/write-spec` - Create a full feature spec for one feature +4. `/architecture` - Design tech architecture (PM-friendly, no code) +5. `/frontend` - Build web UI components (shadcn/ui first!) +6. `/mobile` - Build the Expo (React Native) UI (only if mobile is enabled) +7. `/backend` - Build APIs, database, access rules +8. `/qa` - Test against acceptance criteria + security audit +9. `/deploy` - Deploy to the chosen target + production-ready checks Use `/refine PROJ-X` at any point to revisit and improve an existing feature spec.