Design Philosophy

A working foundation you can understand, with guides that teach you how to build on it. Simplicity and robustness come before extra features.

Built for AI Coding

Ghoststack is designed to be edited by AI (Codex, Claude Code, Cursor). This means:

Simple structure — Easy for AI to understand
Self-contained files — No chasing dependencies
Consistent patterns — Same approach everywhere
Clear naming — Files named what they do

Key Principles

1. Local by Default

Everything a file needs is in the file or clearly imported.

For example, keep header links in the header when that is the only place they are used. Share configuration when it prevents real duplication, as lib/plans.ts does for pricing.

2. One Obvious Place

Each feature has one place to look:

Auth stuff → lib/supabase/
Payment stuff → lib/stripe.ts and app/api/stripe/
Email stuff → lib/resend.tsx

3. Small Files

Short files are easier to understand and modify:

Pages are mostly layout
Logic is in lib/ files
Components do one thing

App UI uses DaisyUI components and semantic colors with Tailwind layout utilities. Theme configuration and email styles have their own explicit files. The starter does not carry a documentation website or its rendering dependencies.

Consistent look
Easy to modify
Current component documentation your agent can consult

Rules for AI

Shared conventions already live in AGENTS.md. For a focused reminder:

Rules:
- Use DaisyUI components and semantic colors with Tailwind layout utilities
- Follow existing patterns in the codebase
- Keep files small and focused
- Server components unless you need interactivity
- Handle errors gracefully
- Check for TypeScript errors after changes

Prompt Template: Follow Patterns

I want to add [NEW FEATURE].

Please:
1. Look at how similar features are built in this codebase
2. Follow the same patterns
3. Keep files small and focused
4. Use DaisyUI components with Tailwind layout utilities
5. Add proper error handling

Success looks like: [WHAT THE USER CAN DO AND SEE].
Check the codebase first, implement the smallest complete change, and verify that result.
Explain the changed files and how I can try it myself.

Why This Matters

AI works best with:

Predictable code — Same patterns everywhere
Clear structure — Easy to find things
Simple components — Less to understand

Ghoststack is built this way so your coding agent can work with a small amount of context.