AI Coding Workflow Guide

---
name: project-bootstrap
description: Use when starting a new project or adding Claude Code to an existing project. Triggers on new project setup, initialize project, bootstrap, set up for development, configure claude for this project.
---

# Project Bootstrap

Interactive setup that configures a project with your preferred structure, tools, security, and design principles.

## What This Skill Does

1. **Asks questions** about your project (stack, vibe, integrations)
2. **Detects existing platform** if running on an existing codebase (scans for config files)
3. **Creates folder structure** with industry-standard conventions
4. **Initializes git + GitHub** with proper .gitignore and branch setup
5. **Installs CLIs** for your chosen stack (Firebase, Supabase, Vercel, etc.)
6. **Walks through secrets management** (never expose API keys)
7. **Generates CLAUDE.md** with security protocols and project rules
8. **Sets up documentation** in `docs/` with design narratives
9. **Configures the unified workflow** (THINK → PLAN → WORK → LEARN → SHIP)
10. **Offers skill installation** — lists available skills by category, recommends based on your stack
11. **Establishes design principles** based on your app's "vibe"

## Workflow

```dot
digraph bootstrap {
    rankdir=TB;

    "1. Project basics" [shape=box];
    "2. Platform detection" [shape=box, style=dashed];
    "3. Stack selection" [shape=box];
    "4. Design vibe" [shape=box];
    "5. Create structure" [shape=box];
    "6. Git + GitHub" [shape=box];
    "7. Install CLIs" [shape=box];
    "8. Secrets setup" [shape=box];
    "9. Generate CLAUDE.md" [shape=box];
    "10. Create docs" [shape=box];
    "11. Workflow setup" [shape=box];
    "12. Skill installation" [shape=box, style=dashed];
    "13. Initial commit + push" [shape=box];

    "1. Project basics" -> "2. Platform detection";
    "2. Platform detection" -> "3. Stack selection";
    "3. Stack selection" -> "4. Design vibe";
    "4. Design vibe" -> "5. Create structure";
    "5. Create structure" -> "6. Git + GitHub";
    "6. Git + GitHub" -> "7. Install CLIs";
    "7. Install CLIs" -> "8. Secrets setup";
    "8. Secrets setup" -> "9. Generate CLAUDE.md";
    "9. Generate CLAUDE.md" -> "10. Create docs";
    "10. Create docs" -> "11. Workflow setup";
    "11. Workflow setup" -> "12. Skill installation";
    "12. Skill installation" -> "13. Initial commit + push";
}
```

> **Dashed boxes** = new phases for existing project detection and skill setup. These are skipped or adapted based on your answers in Phase 1.

---

## Phase 1: Project Basics

Ask these questions (2-3 at a time, wait for answers):

**Round 1:**
1. What are you building? (One sentence)
2. New project or existing codebase?
3. Do you have any planning docs I should review? (PRDs, specs, etc.)

**Round 2:**
4. What problem does this solve for your users?
5. What does "done" look like for v1?

---

## Phase 2: Platform Detection (Existing Projects)

**Skip this phase if the user said "new project" in Phase 1.**

If the user has an existing codebase, scan the project root for platform indicators before asking stack questions. This avoids redundant questions about things you can detect.

### Detection Matrix

| File/Pattern | Detected Stack |
|-------------|---------------|
| `package.json` with `react` | React frontend |
| `package.json` with `next` | Next.js |
| `package.json` with `vue` | Vue |
| `package.json` with `svelte` | Svelte/SvelteKit |
| `*.xcodeproj` or `*.xcworkspace` | iOS/macOS (Xcode) |
| `Package.swift` | Swift Package Manager |
| `Podfile` | iOS (CocoaPods) |
| `Cargo.toml` | Rust |
| `go.mod` | Go |
| `requirements.txt` or `pyproject.toml` | Python |
| `Gemfile` | Ruby |
| `wrangler.toml` or `wrangler.jsonc` | Cloudflare Workers/Pages |
| `firebase.json` | Firebase |
| `vercel.json` | Vercel |
| `supabase/config.toml` | Supabase |
| `tailwind.config.*` | Tailwind CSS |
| `.env` or `.env.example` | Has secrets management |
| `CLAUDE.md` | Already has Claude Code config |
| `docs/` directory | Already has docs structure |
| `.git/` | Already has git |

### Detection Steps

```bash
# Run these checks silently and report findings
ls package.json 2>/dev/null && echo "Found: package.json"
ls *.xcodeproj 2>/dev/null && echo "Found: Xcode project"
ls Package.swift 2>/dev/null && echo "Found: Swift package"
ls Cargo.toml 2>/dev/null && echo "Found: Rust project"
ls go.mod 2>/dev/null && echo "Found: Go project"
ls requirements.txt pyproject.toml 2>/dev/null && echo "Found: Python project"
ls wrangler.toml wrangler.jsonc 2>/dev/null && echo "Found: Cloudflare project"
ls firebase.json 2>/dev/null && echo "Found: Firebase project"
ls CLAUDE.md 2>/dev/null && echo "Found: Existing CLAUDE.md"
ls -d docs/ 2>/dev/null && echo "Found: docs/ directory"
ls -d .git/ 2>/dev/null && echo "Found: git repository"
```

### Report and Confirm

Present detected stack to the user:

> "I detected the following in your project:
> - **Frontend:** React with Tailwind CSS
> - **Platform:** Firebase
> - **Git:** Already initialized
> - **CLAUDE.md:** Already exists
>
> Does this look right? Anything I should add or correct?"

### Existing Project Adaptations

Based on detection, adjust later phases:
- **Has git?** → Skip git init in Phase 6
- **Has CLAUDE.md?** → Offer to enhance (not overwrite) in Phase 9
- **Has `docs/`?** → Skip creation, check for missing subdirectories (plans/, solutions/) in Phase 10
- **Has `.env`?** → Skip creation, verify .gitignore has it in Phase 8

---

## Phase 3: Stack Selection (or Confirm Detected Stack)

Ask about technical choices:

**Frontend:**
- Framework: React, Next.js, Vue, Svelte, vanilla?
- Styling: Tailwind (recommended), CSS Modules, styled-components?
- State: Context, Zustand, Redux, Jotai?

**Backend:**
- Platform: Firebase, Supabase, AWS, Vercel, custom Node?
- Database: Firestore, PostgreSQL, MongoDB, SQLite?
- Auth: Firebase Auth, Supabase Auth, NextAuth, Clerk?

**AI Integration:**
- Claude API, OpenAI, Gemini, local models?

**For each selection, note the CLI to install:**

| Platform | CLI | Install Command |
|----------|-----|-----------------|
| Firebase | firebase-tools | `npm install -g firebase-tools` |
| Supabase | supabase | `npm install -g supabase` |
| Vercel | vercel | `npm install -g vercel` |
| GitHub | gh | `brew install gh` |
| Stripe | stripe | `brew install stripe/stripe-cli/stripe` |

**If user is unsure:** Review their planning docs (if any) and make suggestions with trade-offs explained. Always prefer asking over assuming.

---

## Phase 4: Design Vibe Discovery

Design should match the app's purpose and audience. Ask:

1. **What's the emotional tone of your app?**
   - Serious/professional (banking, legal, enterprise)
   - Warm/friendly (wellness, community, personal)
   - Playful/energetic (gaming, social, creative)
   - Clean/minimal (productivity, tools, dev)
   - Bold/expressive (fashion, art, entertainment)

2. **Who is your primary user?**
   - Age range
   - Technical sophistication
   - Use context (mobile on-the-go, desktop focused work)

3. **What apps do you admire the design of?**
   - This gives concrete reference points

### Mood Board Generation

Based on answers, suggest:

**Color direction:**
- Warm neutrals vs cool neutrals
- Accent color family (not purple or generic blue unless intentional)
- Suggest searching for: "[app type] UI design Dribbble 2024"

**Typography direction:**
- Organic/humanist (plant app, wellness)
- Geometric/modern (tech, productivity)
- Classic/serif (editorial, luxury)
- Suggest specific font pairings to explore

**Layout principles:**
- Dense vs spacious
- Card-based vs flat
- Mobile-first priorities

### Anti-Patterns to Exclude

Always exclude (per Impeccable design):
- Inter font as default
- Purple gradients
- Cards nested in cards
- Pure black (#000) or pure gray (#808080)
- Bounce/elastic animations
- Generic blue buttons without brand consideration

Document design decisions in `docs/design-system.md`.

---

## Phase 5: Create Folder Structure

### Standard Structure

```
project-name/
├── .claude/
│   ├── skills/           # Project-specific skills
│   ├── commands/         # Custom slash commands
│   │   └── ship.md       # Local CI + deploy pipeline
│   ├── rules/            # Auto-loaded coding conventions
│   │   ├── coding-conventions.md
│   │   └── workflow.md   # Unified workflow rule
│   └── settings.json     # Agent Teams config
├── .github/
│   └── workflows/        # CI/CD (optional)
├── docs/
│   ├── design-system.md  # Colors, fonts, spacing, principles
│   ├── architecture.md   # Technical decisions
│   ├── branding.md       # Voice, tone, personality
│   ├── plans/            # Design docs and implementation plans
│   ├── solutions/        # Compound learning library
│   └── SOLUTION_GUIDE.md # Solution doc schema
├── src/
│   ├── components/
│   ├── pages/ or routes/
│   ├── services/
│   ├── hooks/
│   ├── utils/
│   └── types/
├── tests/
├── .env.example          # Template for env vars (no real values)
├── .gitignore
├── CLAUDE.md             # AI assistant instructions
├── CHANGELOG.md          # Version history
└── README.md
```

### Create Commands

```bash
# Create directory structure
mkdir -p .claude/skills .claude/commands .claude/rules docs/plans docs/solutions src/{components,pages,services,hooks,utils,types} tests

# Create placeholder files
touch CHANGELOG.md
touch .env.example
```

---

## Phase 6: Git + GitHub Setup

### Initialize Git

```bash
git init
```

### Create .gitignore

Generate based on stack selection. Always include:

```gitignore
# Environment (NEVER commit secrets)
.env
.env.local
.env.*.local
*.pem
*credentials*.json

# Dependencies
node_modules/
.pnpm-store/

# Build outputs
dist/
build/
.next/
.vercel/

# IDE
.idea/
.vscode/
*.swp

# OS
.DS_Store
Thumbs.db

# Logs
*.log
npm-debug.log*

# Firebase
.firebase/
firebase-debug.log

# Test coverage
coverage/

# Worktrees
.worktrees/
```

### GitHub Repository

```bash
# Login if needed
gh auth login

# Create repo (ask user: public or private?)
gh repo create [project-name] --private --source=. --remote=origin

# Set up main branch
git branch -M main
```

### Branch Strategy Guidance

For solo developers or small teams:
- **main**: Production-ready code
- **Feature branches**: `feature/[feature-name]` for new work
- PR to main when ready

Explain: "You can work directly on main for small changes, or create feature branches for larger work. I'll commit and push with each change so nothing is lost."

---

## Phase 7: Install CLIs

Based on stack selection, install required CLIs:

```bash
# GitHub CLI (always)
which gh || brew install gh

# Based on platform choice:
# Firebase
which firebase || npm install -g firebase-tools

# Supabase
which supabase || npm install -g supabase

# Vercel
which vercel || npm install -g vercel

# Stripe (if payments)
which stripe || brew install stripe/stripe-cli/stripe
```

After installation, authenticate:

```bash
# Firebase
firebase login

# Supabase
supabase login

# Vercel
vercel login

# GitHub (if not already)
gh auth status || gh auth login
```

---

## Phase 8: Secrets Management Walkthrough

**Walk the user through this - never just tell them to do it.**

### Step 1: Create .env.example

```bash
# Create template showing required vars (no real values)
cat > .env.example << 'EOF'
# Copy this to .env and fill in real values
# NEVER commit .env to git

# Firebase (get from Firebase Console > Project Settings)
VITE_FIREBASE_API_KEY=
VITE_FIREBASE_AUTH_DOMAIN=
VITE_FIREBASE_PROJECT_ID=
VITE_FIREBASE_STORAGE_BUCKET=
VITE_FIREBASE_MESSAGING_SENDER_ID=
VITE_FIREBASE_APP_ID=

# API Keys (get from respective dashboards)
ANTHROPIC_API_KEY=
STRIPE_SECRET_KEY=
SENDGRID_API_KEY=
EOF
```

### Step 2: Create .env

```bash
cp .env.example .env
```

### Step 3: Guide User to Get Values

For each service, provide exact steps:

**Firebase:**
1. Go to https://console.firebase.google.com
2. Select your project (or create one)
3. Click the gear icon > Project settings
4. Scroll to "Your apps" section
5. If no web app exists, click "Add app" > Web
6. Copy the config values to .env

**Claude API:**
1. Go to https://console.anthropic.com
2. Click API Keys in sidebar
3. Create new key, copy to .env

### Step 4: Verify .gitignore

```bash
# Confirm .env is ignored
grep -q "^\.env$" .gitignore || echo ".env" >> .gitignore
```

### Platform-Specific Secrets

**Firebase Functions:** Use Firebase environment config
```bash
firebase functions:secrets:set ANTHROPIC_API_KEY
```

**Vercel:** Use Vercel environment variables
```bash
vercel env add ANTHROPIC_API_KEY
```

---

## Phase 9: Generate CLAUDE.md

Generate project-specific CLAUDE.md. See `claude-md-template.md` for full template.

Key sections:
1. Project Overview
2. Tech Stack Summary
3. Quick Commands
4. Security Protocols (CRITICAL)
5. Coding Conventions
6. Design Principles
7. Development Workflow (unified: THINK → PLAN → WORK → LEARN → SHIP)

### Security Protocols (Always Include)

```markdown
## Security Protocols

### NEVER Do
- Commit .env or any file containing secrets
- Hardcode API keys, tokens, or credentials in code
- Log sensitive data (passwords, tokens, PII)
- Use `*` for CORS origins in production
- Expose stack traces to users

### ALWAYS Do
- Use environment variables for all secrets
- Check .gitignore before committing
- Validate user input at boundaries
- Use parameterized queries (no string concatenation for SQL)
- Verify ownership before returning user data (prevent IDOR)

### Before Every Deploy
1. Verify .env exists and has required values
2. Run `npm run build` and fix any errors
3. Test locally with `npm run dev`
4. Deploy using CLI (not manual console)
5. Test deployed version with Chrome MCP
```

---

## Phase 10: Create Documentation

### docs/design-system.md

```markdown
# Design System

## Brand Personality
[From vibe discovery]

## Colors
- Primary: [hex]
- Secondary: [hex]
- Background: [hex]
- Surface: [hex]
- Text: [hex]
- Text Muted: [hex]
- Error: [hex]
- Success: [hex]

## Typography
- Headings: [font family]
- Body: [font family]
- Scale: 12/14/16/18/20/24/30px

## Spacing
Base: 4px
Scale: 4/8/12/16/20/24/32/40/48px

## Components
[Document as built]

## Anti-Patterns to Avoid
- [From Impeccable design principles]
```

### docs/architecture.md

```markdown
# Architecture

## Tech Stack
- Frontend: [framework]
- Backend: [platform]
- Database: [type]
- Auth: [provider]
- Payments: [if applicable]

## Data Flow
[Diagram or description]

## Key Decisions
| Decision | Choice | Rationale |
|----------|--------|-----------|
| [topic] | [choice] | [why] |
```

### docs/SOLUTION_GUIDE.md

```markdown
# Solution Guide

Solution docs capture lessons learned from non-trivial fixes and features.

## Schema

Every solution doc uses this frontmatter:

---
title: Short descriptive title
date: YYYY-MM-DD
category: [api-issues|auth-bugs|infrastructure|integration-issues|pdf-issues|performance|refactoring|security|ui-bugs]
tags: [relevant, tech, keywords]
severity: [low|medium|high|critical]
---

## Sections

1. **Problem** — What went wrong or what was needed
2. **Root Cause** — Why it happened (dig past symptoms)
3. **Solution** — What was done to fix it
4. **Prevention** — How to avoid this in the future
5. **Related** — Links to relevant files, PRs, or other solution docs
```

---

## Phase 11: Workflow Setup

Set up the unified development workflow infrastructure.

### Create Workflow Rule

Create `.claude/rules/workflow.md`:

```markdown
# Development Workflow (Auto-Loaded)

## The Pipeline

THINK → PLAN → WORK → LEARN → SHIP

| Phase | Default Tool | Upgrade When |
|-------|-------------|-------------|
| Think | /superpowers:brainstorming | Need formal specs → + /speckit.specify |
| Plan | /superpowers:writing-plans | Need API contracts → + /speckit.plan |
| Work | Determined by Execution Strategy in plan doc | See framework below |
| Learn | /workflows:compound | After non-obvious fixes |
| Ship | /ship | Always |

## When to Use the Full Loop

- New features (any feat: work)
- Bug fixes affecting multiple files
- Refactoring or architectural changes
- Security-sensitive changes

## When to Skip Think/Plan

- Single-file bug fixes
- Dependency bumps
- Documentation-only changes

## Execution Strategy Framework

Every plan must end with an Execution Strategy section. Decision framework:

1. Count independent task groups (tasks that touch different files)
   - 1 group or < 3 tasks → DIRECT IMPLEMENTATION
   - 2-3 groups, sequential or shared files → SUBAGENT-DRIVEN
   - 3+ groups with clear file ownership → AGENT TEAMS

2. Check for inter-task communication needs
   - Tasks need to share findings or coordinate? → Agent Teams
   - Tasks are fully independent? → Subagent-driven

3. Check risk level
   - Touching auth, payments, security? → Subagent-driven with mandatory review
   - Low-risk feature work? → Agent Teams for speed

## Agent Teams Quality Checklist

When using Agent Teams:
1. Enable delegate mode (Shift+Tab) — lead coordinates only
2. Require plan approval — teammates plan before implementing
3. Set up TeammateIdle hook — enforce lint/tests before idle
4. Set up TaskCompleted hook — run quality checks before done
5. Size tasks as self-contained units with clear file ownership
6. Target 5-6 tasks per teammate
7. Monitor and steer — don't leave unattended

## Phase Handoffs

Each phase writes output to a file and recommends the next step:

THINK → docs/plans/YYYY-MM-DD-<topic>-design.md
  Next: /clear → /superpowers:writing-plans

PLAN → docs/plans/YYYY-MM-DD-<feature>-plan.md (includes Execution Strategy)
  Next: /clear → execute per Execution Strategy

WORK → Code changes committed to branch
  Next: /clear → /workflows:compound (if non-trivial) or /ship

LEARN → docs/solutions/<category>/<slug>.md
  Next: /clear → /ship

SHIP → Code deployed
  Next: Done.

Files are the handoff, not context. Each phase reads its input fresh.
Plans survive across sessions. /clear and pick up tomorrow.

## Learning Is Non-Negotiable

After every non-trivial fix or feature, run /workflows:compound to capture:
- What problem was solved
- What was the root cause
- What prevention strategies apply
- Save to docs/solutions/<category>/ with proper frontmatter
```

### Create /ship Command

Create `.claude/commands/ship.md` adapted to the project's stack:

```markdown
---
name: ship
description: Local CI + deploy pipeline — lint, test, build, changelog, commit, push, deploy
---

# /ship — Pre-Deploy Pipeline

Run these steps in order. Stop on first failure.

1. **Lint**: `npm run lint` (fix errors, don't skip)
2. **Test**: `npm run test` (all tests must pass)
3. **Build**: `npm run build` (fix type errors)
4. **Changelog**: Update CHANGELOG.md if not already done
5. **Commit**: Stage and commit with descriptive message
6. **Push**: `git push`
7. **Deploy**: `{{DEPLOY_COMMAND}}`
8. **Verify**: Test deployed version with Chrome MCP
```

### Set Up Solution Library

```bash
mkdir -p docs/solutions
```

### Configure Agent Teams (Optional)

If user wants parallel development capability, create `.claude/settings.json`:

```json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
```

---

## Phase 12: Skill Installation

Present available skill categories and let the user choose what to install. Recommend based on the detected/chosen stack.

### Core Skills (Recommended for Everyone)

These provide the foundational workflow discipline:

| Skill | What It Does | Install |
|-------|-------------|---------|
| **superpowers** | Workflow discipline — brainstorming, planning, debugging, verification, code review, TDD, parallel agents | `npx superpowers install` or follow plugin docs |
| **compound-engineering** | Advanced workflows — brainstorm, plan, work, review, compound docs, frontend design | `npx compound-engineering install` or follow plugin docs |

### Stack-Specific Recommendations

Based on the user's stack, suggest relevant skills:

**Web / Frontend projects:**
| Skill | What It Does |
|-------|-------------|
| `design:ui-ux-pro-max` | Build distinctive web components and pages |
| `design:tailwind-design-system` | Tailwind CSS design systems |
| `infra:web-perf` | Web performance audits |
| **impeccable (i-\*)** | 14 design refinement commands (critique, polish, animate, simplify, etc.) |

**Cloudflare projects:**
| Skill | What It Does |
|-------|-------------|
| `infra:wrangler` | Deploy Workers/Pages |
| `infra:workers-best-practices` | Worker code patterns |
| `infra:cloudflare` | General Cloudflare platform |
| `infra:durable-objects` | Durable Objects patterns |

**iOS / Apple projects:**
| Skill | What It Does |
|-------|-------------|
| `ios:migrate-schema` | SwiftData/Core Data migrations |
| `ios:performance-check` | Memory/CPU/energy profiling |
| `ios:release-prep` | Pre-release checklist |
| **swift-concurrency** | Swift 6 migration, async/await, actors |
| **swift-testing-expert** | Swift Testing framework patterns |
| **core-data-expert** | Core Data stack, migrations, CloudKit sync |

**Full project lifecycle:**
| Skill | What It Does |
|-------|-------------|
| **gsd** | Roadmap, phases, plan, execute, verify, ship — full project lifecycle |

### The Overlap Warning

> **Important:** More skills = more overlap = more confusion. Each skill has trigger conditions, and when multiple skills trigger on the same task, they can give conflicting guidance.
>
> **Start lean.** Install the core skills (superpowers + compound-engineering), then add domain-specific skills only when you feel the gap. If you find yourself fighting skill recommendations, you probably have too many installed.
>
> **Custom slash commands** can help: create a `/plan` command that calls the specific planning skill you want, rather than letting multiple planning-related skills compete.

### Installation

For each selected skill, provide installation instructions. Skills are typically:
- **Plugins:** Installed via npm/npx with a single command
- **Custom skills:** Markdown files placed in `~/.claude/skills/<category>/`
- **Project skills:** Placed in `.claude/skills/` within the project

Ask the user which skills they'd like to install and walk them through each one.

---

## Phase 13: Initial Commit + Push

```bash
# Stage all files
git add -A

# Verify no secrets
git diff --cached --name-only | xargs grep -l "sk_live\|sk_test\|AKIA\|password\s*=" || true

# Commit
git commit -m "Initial project setup

- Created folder structure
- Configured CLAUDE.md with security protocols
- Set up documentation structure
- Configured unified development workflow

Co-Authored-By: Claude <noreply@anthropic.com>"

# Push
git push -u origin main
```

---

## Phase 14: Chrome MCP Testing Setup

Suggest testing workflow using Chrome MCP:

### Basic Smoke Test

After each deploy, verify:

```
1. Navigate to deployed URL
2. Take snapshot - verify page loads
3. Check for console errors
4. Test primary user flow (login, main action, etc.)
5. Verify no visual regressions
```

### Test Checklist Template

```markdown
## Deploy Verification Checklist

- [ ] Page loads without errors
- [ ] No console errors (check list_console_messages)
- [ ] Primary navigation works
- [ ] Auth flow works (if applicable)
- [ ] Main feature works
- [ ] Mobile viewport looks correct (resize_page to 375x667)
```

---

## Ongoing Workflow Rules

After setup, these rules apply to every session:

### Commit Workflow
Every meaningful change → commit → push
```bash
git add [files]
git commit -m "feat: [description]"
git push
```

### Deploy Workflow
```
1. npm run build (fix errors)
2. Deploy via CLI
3. Test with Chrome MCP
4. Report results to user
```

### Ask Before Assuming
If uncertain about:
- Design choices
- Architecture decisions
- Feature scope
- User preferences

**Ask. Don't assume.**

---

## Quick Reference

**Invoke:** "Bootstrap this project" / "Set up for development"

**Output:**
- Platform detected (existing projects) or stack chosen (new projects)
- Folder structure created
- Git + GitHub initialized
- CLIs installed and authenticated
- Secrets management configured
- CLAUDE.md generated (or enhanced if existing)
- Documentation structure created
- Unified workflow configured (THINK → PLAN → WORK → LEARN → SHIP)
- Skills installed based on stack
- Solution library ready for compound learning
- Initial commit pushed

**Time:** Interactive setup, ~10-15 minutes with user