App Foundations

CRITICAL: Who is using this skill

The user is most likely a non-technical builder — someone using Claude Code to build a real product without a programming background. Treat every interaction with this in mind:

• Never use technical jargon without immediately translating it into plain language with a real-world example.
• Always offer a recommended default: "If you're not sure → I recommend X because Y."
• Group questions — ask all 8 in one or two messages, not eight back-and-forth turns.
• Match the user's language: if they write in Hebrew, respond in Hebrew. If Spanish, Spanish. Etc. Translate the questions below into their language.
• Be warm and patient, never condescending. They are smart people learning a new domain.

Exception: if the user explicitly identifies as a developer ("I'm a backend engineer", "I know SQL") or uses technical terms naturally, switch to technical mode and ask concisely with proper terminology.

Quick-start mode

If the user says any of these — "just build it", "you decide everything", "use defaults", "skip the questions", "I trust you" — skip the question phase entirely. Apply all defaults from the "Defaults" section below, write FOUNDATIONS.md documenting what was chosen, briefly summarize the choices in 5 bullet points, and start building.

Standard workflow

1. Acknowledge the build request with one warm sentence.
2. Set expectations — say something like:

   "Before I write any code, I want to ask you 8 quick questions. They take 2 minutes and they're the difference between a system that works in a demo and one that survives real customers. For any question — if you're not sure, just say 'you decide' and I'll pick the safe default. Ready?"

3. Ask the 8 questions in plain language, grouped into 2 messages (questions 1-4, then 5-8). Use the exact framing in "The 8 questions" section below.
4. Summarize the decisions back to the user in a friendly recap: "Great — here's what we decided…"
5. Get a final confirmation before writing code: "Does this look right? Any changes?"
6. Create FOUNDATIONS.md in the project root documenting every decision with a one-sentence rationale.
7. Build the system with the foundations baked in from the first line of code.

The 8 questions (use this exact framing)

Question 1: Sign-in

How should people sign into your app?

a) Email + password (the standard, like most websites) b) Email + password, plus "Sign in with Google" c) Phone number + SMS code (like WhatsApp) d) Magic link sent to email (no password — Slack-style)

If you're not sure → I recommend (a). Most products start here and add more options later.

Question 2: Privacy between users

When one user creates a record (a customer, a project, a note) — should other users in your app see it?

a) No — each user sees only their own data (like a personal Notion account) b) Yes — users on the same team share data (like Slack) c) Yes — everyone in the company sees everything (like a shared Google Sheet)

If you're not sure → (a) is the safest. Discovering later that user A could see user B's private data is a nightmare. We can loosen it later if needed.

Question 3: User roles

Will all users have the same powers, or are there different types?

Example: in a CRM you might have "admin" (sees billing, deletes customers) vs "salesperson" (only edits their own deals).

a) Everyone is equal — one type of user b) Two types — admin + regular user c) Three or more (tell me which and what each can do)

If you're not sure → (b). Almost every real product eventually needs admin vs regular.

Question 4: Deletion

When a user deletes something — a customer, a project, a file — what should happen?

a) Gone forever, immediately b) Goes to a "trash" that can be restored for 30 days (like Gmail trash) c) Hidden from the user but kept in the database forever

If you're not sure → (b). It has saved countless products from disaster — a user clicks delete by mistake and we can bring it back.

(Send the next 4 in the second message)

Question 5: Backups

If the database has a catastrophic failure tomorrow morning — how recent a copy do you want to restore from?

a) Up to 24 hours of data loss is OK (daily backups, cheapest) b) Up to 1 hour (hourly backups) c) Near-zero loss (continuous backup, more expensive)

If you're not sure → (a). Daily is plenty for most products until you have paying customers; we can upgrade later.

Question 6: Admin area

Will your app have an "admin panel" — a separate area only you (or your team) can access, to do things like view all users, ban accounts, see analytics?

a) Yes — build a separate admin area b) No — I'll do admin tasks manually in the database c) Not now — maybe later

If you're not sure → (a) but minimal. We'll start with a "see all users" page and grow from there.

Question 7: Money / payments

Will your app handle real money — payments, subscriptions, anything that charges the user?

a) Yes b) No — free product c) Maybe later, but not in the first version

If you say (a), I'll automatically turn on double-charge protection — it's not optional for payments. If a user clicks "pay" twice or their internet hiccups, they won't be charged twice.

Question 8: Tech stack

Last question — do you have a preference for the technology I should use?

a) You pick what's best b) I have a preference (tell me which) c) I have an existing project — match its stack

If you're not sure → (a). I'll pick a modern, well-supported stack.

Defaults (when user says "you decide everything")

Apply all of these without asking:

Critical rule: idempotency on payments

For payments, signups, and anything touching real money or external services — double-action protection is always on, no exceptions, never ask. A double-charge is the worst possible failure.

For notifications, emails, and audit logs — protection is off by default. Users actually want repeat notifications when they click "send" twice.

Don't bother the user with this nuance. Just apply the rule.

What to produce after the conversation

1. FOUNDATIONS.md in the repo root. Include every decision in plain language with a one-sentence rationale. This is the most important file — future Claude Code sessions will read it and stay consistent.
2. Database schema with user_id (or tenant_id), deleted_at, created_at, updated_at columns on every business table from day one.
3. Auth + authorization middleware stubs before any features.
4. API endpoint list annotated with scope (public / authenticated / admin).
5. A friendly summary message to the user: "Everything's set. Here's what I built and why. Now let's add features." Keep this in plain language.

Reference files (for technical implementation)

When actually writing code, load the matching technical reference for deep guidance:

• references/01-authentication.md — auth implementation, password hashing, MFA
• references/02-authorization.md — query filtering, row-level security
• references/03-rbac.md — role tables, permission middleware
• references/04-ownership.md — owner FK design, multi-tenant patterns
• references/05-soft-delete.md — deleted_at column, partial indexes, unique constraints
• references/06-backup-restore.md — managed DB setup, restore testing
• references/07-api-scopes.md — route grouping, middleware tiers
• references/08-idempotency.md — Idempotency-Key handling, dedup tables

The references contain technical detail; never paste their content at the user verbatim unless they explicitly ask for technical depth.