ai-coding-starter-kit-v2/README.md

# AI Coding Starter Kit

> Build production-ready web apps faster with AI-powered Skills handling Requirements, Architecture, Development, QA, and Deployment. Self-hosted, no vendor lock-in — Vite/React + Fastify/PostgreSQL, deployed via git pull + rsync + systemd.

This template uses [Claude Code](https://docs.anthropic.com/en/docs/claude-code) with modern Skills, Rules, and Sub-Agents to provide a complete AI-powered development workflow.

## Quick Start

### 1. Clone & Install

```bash
git clone https://gitea.perlbach24.de/scripte/ai-coding-starter-kit-v2.git my-project
cd my-project
cd frontend && npm install && cd ..
cd backend && npm install && cd ..
```

### 2. Set Up PostgreSQL

1. Create a local PostgreSQL database and role for the app
2. Copy `backend/.env.example` to `backend/.env`
3. Set `DATABASE_URL` and `JWT_SECRET`
4. Run `cd backend && npm run db:generate && npm run db:migrate`

Skip the backend entirely if you're building frontend-only (landing pages, portfolios, etc.) — just run the frontend.

### 3. Start Development

```bash
cd backend && npm run dev    # localhost:4000
cd frontend && npm run dev   # localhost:5173, proxies /api to the backend
```

### 4. Initialize Your Project

Open Claude Code and describe your project. The `/requirements` skill automatically detects that this is a fresh project and enters **Init Mode**:

```
/requirements I want to build a project management tool for small teams
where users can create projects, assign tasks, and track progress.
```

The skill will:
1. Ask interactive questions to clarify your vision, target users, and MVP scope
2. Create your **Product Requirements Document** (`docs/PRD.md`)
3. Break the project into individual features (Single Responsibility)
4. Create all **feature specs** (`features/PROJ-1.md`, `PROJ-2.md`, etc.)
5. Update **feature tracking** (`features/INDEX.md`)
6. Recommend which feature to build first

You don't need to put everything in the first prompt - a brief description is enough. The skill asks follow-up questions interactively.

### 5. Build Features

After project initialization, build features one at a time using skills:

```
/architecture    Design the tech approach for features/PROJ-1-user-auth.md
/frontend        Build the UI for features/PROJ-1-user-auth.md
/backend         Build the API for features/PROJ-1-user-auth.md
/qa              Test features/PROJ-1-user-auth.md
/deploy          Deploy to your server
```

Each skill suggests the next step when it finishes. Handoffs are always user-initiated.

To add more features later, run `/requirements` again - it detects the existing PRD and adds a single feature.

---

## Available Skills

| Skill | Command | What It Does |
|-------|---------|-------------|
| Requirements Engineer | `/requirements` | Creates feature specs with user stories, acceptance criteria, edge cases |
| Solution Architect | `/architecture` | Designs PM-friendly tech architecture (no code, only high-level design) |
| Frontend Developer | `/frontend` | Builds UI with React, Tailwind CSS, and shadcn/ui |
| Backend Developer | `/backend` | Builds APIs, database schema, and auth with Fastify + Drizzle + PostgreSQL |
| QA Engineer | `/qa` | Tests features against acceptance criteria + security audit |
| DevOps | `/deploy` | Deploys to your server (git pull + rsync + systemd) with production-ready checks |
| Help | `/help` | Context-aware guide: shows where you are and what to do next |

### How Skills Work

- **Skills** are defined in `.claude/skills/` and auto-discovered by Claude Code
- **Rules** in `.claude/rules/` are auto-applied based on file context (no manual loading)
- **Sub-Agents** run heavy tasks (frontend, backend, QA) in isolated contexts for cost efficiency
- **CLAUDE.md** provides project context automatically at every session start

---

## Development Workflow

```
1. Define    /requirements  -->  Feature spec in features/PROJ-X.md
2. Design    /architecture  -->  Tech design added to feature spec
3. Build     /frontend      -->  UI components implemented
             /backend       -->  APIs + database (if needed)
4. Test      /qa            -->  Test results added to feature spec
5. Ship      /deploy        -->  Deployed to your server
```

### Feature Tracking

Features are tracked in `features/INDEX.md`:

| ID | Feature | Status | Spec |
|----|---------|--------|------|
| PROJ-1 | User Login | Deployed | [Spec](features/PROJ-1-user-login.md) |
| PROJ-2 | Dashboard | In Progress | [Spec](features/PROJ-2-dashboard.md) |

Every skill reads this file at start and updates it when done, preventing duplicate work.

---

## Tech Stack

| Category | Tool | Why? |
|----------|------|------|
| **Frontend** | Vite + React 19 | Fast dev server, no framework lock-in |
| **Language** | TypeScript | Type safety |
| **Styling** | Tailwind CSS | Utility-first CSS |
| **UI Library** | shadcn/ui | Copy-paste, customizable components |
| **Backend** | Fastify + Drizzle + PostgreSQL | Lightweight, typed, self-hostable |
| **Auth** | Own JWT (`@fastify/jwt`) | No third-party auth dependency |
| **Deployment** | git pull + rsync + systemd | Runs on any Linux server, updates pulled from Gitea |
| **Validation** | Zod | Runtime type validation |

---

## Project Structure

```
ai-coding-starter-kit/
+-- CLAUDE.md                        <-- Auto-loaded project context
+-- .claude/
|   +-- settings.json                <-- Team permissions (committed)
|   +-- settings.local.json          <-- Personal overrides (gitignored)
|   +-- rules/                       <-- Auto-applied coding rules
|   |   +-- general.md                   Git workflow, feature tracking
|   |   +-- frontend.md                  shadcn/ui, component standards
|   |   +-- backend.md                   Validation, queries, migrations
|   |   +-- security.md                  Secrets, headers, auth
|   +-- skills/                      <-- Invocable workflows (/command)
|   |   +-- requirements/SKILL.md        /requirements
|   |   +-- architecture/SKILL.md        /architecture
|   |   +-- frontend/SKILL.md            /frontend (runs as sub-agent)
|   |   +-- backend/SKILL.md             /backend (runs as sub-agent)
|   |   +-- qa/SKILL.md                  /qa (runs as sub-agent)
|   |   +-- deploy/SKILL.md              /deploy
|   |   +-- help/SKILL.md                /help
|   +-- agents/                      <-- Sub-agent configs
|       +-- frontend-dev.md              Model, tools, limits
|       +-- backend-dev.md
|       +-- qa-engineer.md
+-- features/                        <-- Feature specifications
|   +-- INDEX.md                         Status tracking
|   +-- README.md                        Spec format documentation
+-- docs/
|   +-- PRD.md                       <-- Product Requirements Document
|   +-- production/                  <-- Production setup guides
|       +-- error-tracking.md            Error tracking setup
|       +-- security-headers.md          XSS/Clickjacking protection
|       +-- performance.md               Lighthouse, optimization
|       +-- database-optimization.md     Indexing, N+1, caching
|       +-- rate-limiting.md             @fastify/rate-limit
+-- frontend/
|   +-- src/
|   |   +-- main.tsx, App.tsx        <-- Entry points
|   |   +-- components/ui/           <-- shadcn/ui components (35+ installed)
|   |   +-- hooks/                   <-- Custom React hooks
|   |   +-- lib/                     <-- Utilities
|   +-- public/                      <-- Static files
+-- backend/
    +-- src/
        +-- server.ts                <-- Fastify entry
        +-- routes/                  <-- Route handlers
        +-- db/                      <-- Drizzle schema + connection
```

---

## Getting Started

### 1. Fill Out Your PRD

Define your product vision in `docs/PRD.md`:
- What are you building and why?
- Who are the target users?
- What features are on the roadmap?

### 2. Build Your First Feature

Run `/requirements` with your feature idea. The skill will:
- Ask interactive questions to clarify requirements
- Create a feature spec in `features/PROJ-1-name.md`
- Update `features/INDEX.md` with the new feature
- Suggest running `/architecture` as the next step

### 3. Add shadcn/ui Components (as needed)

35+ components are pre-installed. Add more as needed (run inside `frontend/`):
```bash
npx shadcn@latest add [component-name]
```

### 4. Production Setup (first deployment)

When you're ready to deploy, the `/deploy` skill guides you through:
- Server setup (systemd unit, nginx reverse proxy, PostgreSQL)
- Error tracking
- Security headers configuration
- Performance monitoring with Lighthouse

See `docs/production/` for detailed setup guides.

---

## How It Works Under the Hood

### Skills (`.claude/skills/`)
Each skill is a structured workflow that Claude Code discovers automatically. Skills can run inline (in the main conversation) or as forked sub-agents (isolated context window).

| Skill | Execution | Why? |
|-------|-----------|------|
| `/requirements` | Inline | Needs live interaction with user |
| `/architecture` | Inline | Short output, user reviews in real-time |
| `/frontend` | Sub-agent (forked) | Heavy file editing, lots of output |
| `/backend` | Sub-agent (forked) | Heavy file editing, schema, route code |
| `/qa` | Sub-agent (forked) | Systematic testing, lots of output |
| `/deploy` | Inline | Deployment needs user oversight |
| `/help` | Inline | Quick status check and guidance |

### Rules (`.claude/rules/`)
Coding standards that are auto-applied based on which files Claude is working with. No manual loading needed.

### Sub-Agent Configs (`.claude/agents/`)
Lightweight configurations that define model, tool access, and turn limits for forked skills.

### CLAUDE.md
Auto-loaded at every session start. Contains tech stack, conventions, and references to PRD and feature index.

---

## Context Engineering

AI agents work best with clean, structured context - not longer prompts. This template is designed around these principles:

### State lives in files, not in memory

Every skill reads `features/INDEX.md` and the relevant feature spec at start. After context compaction or a new session, nothing is lost - the agent simply re-reads the files. Progress tracking, acceptance criteria, and tech designs all live in markdown files, not in the conversation.

### Context is layered

Not everything is loaded at once. Information is layered by relevance:

| Layer | What | When loaded |
|-------|------|-------------|
| `CLAUDE.md` | Tech stack, conventions, commands | Every session (auto) |
| `.claude/rules/` | Coding standards | When editing matching files (auto) |
| Skill `SKILL.md` | Workflow instructions | When skill is invoked |
| Feature spec | Requirements, AC, tech design | On demand (skill reads it) |
| `docs/production/` | Deployment guides | Only when referenced |

### Context is isolated

Heavy implementation skills (`/frontend`, `/backend`, `/qa`) run as **forked sub-agents** with their own context window. Research noise from one skill doesn't pollute another. Each fork starts clean and loads only what it needs.

### Context recovery is built in

All forked skills include a **Context Recovery** section: if the context is compacted mid-task, the agent re-reads the feature spec, checks `git diff` for progress, and continues without restarting or duplicating work.

### Always read, never guess

A global rule (`rules/general.md`) enforces: always read a file before modifying it, never assume contents from memory, verify import paths and API routes by reading. This prevents hallucinated code references - the most common source of AI coding errors.

---

## Customization for Your Team

This template is designed as a starting point. Customize it for your team:

1. **Edit CLAUDE.md** - Add your project-specific conventions and build commands
2. **Edit docs/PRD.md** - Define your product vision and roadmap
3. **Edit .claude/rules/** - Adjust coding standards for your team
4. **Edit .claude/skills/** - Modify workflows to match your process
5. **Edit .claude/settings.json** - Configure team permissions

---

## Production Guides

Standalone guides in `docs/production/`:

| Guide | What It Does |
|-------|-------------|
| [Error Tracking](docs/production/error-tracking.md) | Automatic error capture setup |
| [Security Headers](docs/production/security-headers.md) | XSS, Clickjacking, MIME sniffing protection |
| [Performance](docs/production/performance.md) | Lighthouse checks, image optimization, caching |
| [Database Optimization](docs/production/database-optimization.md) | Indexing, N+1 prevention, query optimization |
| [Rate Limiting](docs/production/rate-limiting.md) | `@fastify/rate-limit` for API abuse prevention |

---

## Scripts

```bash
# frontend/
npm run dev        # Vite dev server (localhost:5173)
npm run build      # Production build
npm run lint       # ESLint

# backend/
npm run dev        # tsx watch (localhost:4000)
npm run build      # tsc build
npm run start      # node dist/server.js
```

---

## License

MIT License - feel free to use for your projects!