🏗️ Cody Master Project Bootstrap v2.0

Every project starts here. No exceptions. Inspired by best practices from Amp, Codex, Cursor, Lovable, and Manus agents.

Core Principles

ASK FIRST. BUILD SECOND. NEVER ASSUME IDENTITY.
STAGING IS MANDATORY. PRODUCTION IS EARNED.
I18N FROM DAY 1. NOT "LATER."
DESIGN SYSTEM BEFORE COMPONENTS. TOKENS BEFORE PIXELS.
SEO IS NOT AN AFTERTHOUGHT. IT'S INFRASTRUCTURE.
EVERY PROJECT GETS AN AGENTS.MD. NO EXCEPTIONS.

11-Phase Bootstrap Process

Phase 0:    Identity Lock           — WHO are you deploying as?
Phase 0.5:  Security Foundation     — HOW do we prevent secret leaks?
Phase 1:    Project Type Detection   — WHAT kind of project?
Phase 2:    Repository & Environments — WHERE does code live?
Phase 3:    Design System Foundation — HOW does it look?
Phase 4:    i18n From Day 1         — WHICH languages?
Phase 5:    SEO Foundation          — HOW will people find it?
Phase 6:    AGENTS.md + Git Safety  — HOW do agents collaborate?
Phase 7:    Test Infrastructure     — HOW do we catch bugs?
Phase 8:    Deploy Pipeline (8 Gates) — HOW does code ship?
Phase 9:    Development Workflow    — HOW do we work daily?

Phase 0: Identity Lock 🔐

MANDATORY. Cannot proceed without this. Values are NOT hardcoded — check history, suggest, let user confirm.

Step 1: Check Identity History

Before asking anything, check if ~/.cm-identity-history.json exists. If it does, load previous identities and suggest the most recently used values.

// ~/.cm-identity-history.json — Auto-maintained across projects
{
  "lastUsed": "2026-03-17",
  "identities": [
    {
      "github": { "org": "my-work-org" },
      "cloudflare": { "accountId": "abc123def456ghi789jkl012mno345pqr" },
      "i18n": { "primary": "en", "targets": ["es", "fr", "de"] },
      "usedCount": 5,
      "lastProject": "my-awesome-project",
      "lastUsed": "2026-03-17"
    }
  ]
}

Step 2: Ask with Suggestions

Present the 6 questions, pre-filling from history where available. User only needs to confirm or change:

📋 NEW PROJECT — Identity Setup
(Values from your last project shown as suggestions)

1. Project name (kebab-case):       ___________
2. GitHub org [my-work-org]:         → Enter to keep, or type new
3. Cloudflare ID [abc12...5pqr]:     → Enter to keep, or type new
4. Domain:                           ___________
5. Primary language [en]:            → Enter to keep, or type new
6. Target languages [es, fr, de]:    → Enter to keep, or type new

RULE: Never assume. Always show. Let user confirm. If no history exists, ask all 6 from scratch.

Step 3: Verify Identity

⚠️ BEFORE PROCEEDING — CONFIRM:
🔐 GitHub Org:     {org}
☁️  Cloudflare:     {accountId}
🌐 Domain:         {domain}
🗣️  Languages:      {primary} (primary), {targets}
✅ Correct? → proceed
❌ Wrong?  → fix before continuing

Step 4: Create .project-identity.json

{
  "projectName": "{name}",
  "github": {
    "org": "{org}",
    "repo": "{name}"
  },
  "cloudflare": {
    "accountId": "{accountId}",
    "projectName": "{name}",
    "productionBranch": "production"
  },
  "domain": {
    "production": "{domain}",
    "staging": "staging.{domain}"
  },
  "i18n": {
    "primary": "{primary}",
    "targets": ["{targets}"]
  },
  "createdAt": "{date}",
  "bootstrapVersion": "2.0"
}

Step 5: Save to History

After creating .project-identity.json, update ~/.cm-identity-history.json:

• Add or update the identity entry
• Increment usedCount
• Update lastProject and lastUsed
• This ensures next project gets pre-filled suggestions automatically

Call cm-identity-guard to verify git config matches the GitHub org BEFORE any git push.

Phase 0.5: Security Foundation 🛡️

NEW — Defense-in-depth from day 0. Secrets leak at project start when security is "later." Calls cm-secret-shield for setup.

Step 1: Create .gitleaks.toml

Create project-level Gitleaks configuration:

# .gitleaks.toml — Secret Shield Config
title = "CM Secret Shield"

[extend]
useDefault = true

[[rules]]
id = "supabase-service-key"
description = "Supabase Service Role Key"
regex = '''eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\.[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+'''
tags = ["supabase", "jwt"]

[[rules]]
id = "generic-high-entropy"
description = "High entropy string that may be a secret"
regex = '''(?i)(api[_-]?key|secret[_-]?key|access[_-]?token|private[_-]?key|auth[_-]?token)\s*[=:]\s*['"][a-zA-Z0-9/+=]{20,}['"]'''
tags = ["generic"]

[allowlist]
paths = ['''\.gitleaks\.toml$''', '''\.dev\.vars\.example$''', '''node_modules/''', '''dist/''']

Step 2: Setup Pre-Commit Hook

# Install git pre-commit hook for secret scanning
mkdir -p .git/hooks
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/sh
echo "🛡️ Secret Shield: scanning staged files..."
if command -v gitleaks &> /dev/null; then
  gitleaks git --pre-commit --staged --verbose
  if [ $? -ne 0 ]; then
    echo "❌ SECRET DETECTED! Commit blocked."
    exit 1
  fi
  echo "✅ No secrets detected"
else
  echo "⚠️ Gitleaks not installed. Running basic checks..."
  STAGED=$(git diff --cached --name-only --diff-filter=ACM)
  PATTERNS="SERVICE_KEY|ANON_KEY|PRIVATE_KEY|DB_PASSWORD|SECRET_KEY|sk-[a-zA-Z0-9]{20,}"
  for file in $STAGED; do
    if echo "$file" | grep -qE '\.(js|ts|json|toml|yaml|env)$'; then
      if git diff --cached "$file" | grep -qE "$PATTERNS"; then
        echo "❌ Potential secret in: $file"
        exit 1
      fi
    fi
  done
  echo "✅ Basic check passed"
fi
EOF
chmod +x .git/hooks/pre-commit

Step 3: Add Security Script

Add to package.json:

{
  "scripts": {
    "security:scan": "node scripts/security-scan.js || echo 'Create scripts/security-scan.js from cm-secret-shield'"
  }
}

Step 4: Create .dev.vars.example

# .dev.vars.example — Template for local secrets (committed to repo)
# Copy to .dev.vars and fill in real values
SUPABASE_URL=https://YOUR_PROJECT.supabase.co
SUPABASE_SERVICE_KEY=your_service_key_here
SUPABASE_ANON_KEY=your_anon_key_here

RULE: .dev.vars = real secrets (gitignored). .dev.vars.example = template (committed).

Phase 1: Project Type Detection 🔍

Detect project type → auto-select the right stack. Default UI: shadcn/ui + Tailwind. Default layout: Mobile-first. Unless user explicitly requests otherwise.

Step 1: Ask Project Type

Present these options to the user:

UI Library Default Rules

🎨 DEFAULT UI LIBRARY: shadcn/ui + Tailwind CSS
📱 DEFAULT LAYOUT: Mobile-first responsive

These defaults apply UNLESS user explicitly says otherwise.
Examples of overrides:
  - "Use Ant Design" → switch to Ant Design
  - "No mobile needed" → skip mobile optimization
  - "Desktop only" → desktop-first layout

If user says nothing about UI → use shadcn/ui + mobile-first.

Step 2: Scaffold Based on Type

Type A: Static Website

mkdir -p public/static/{css,js,img} src tests/unit docs
touch public/index.html public/static/css/design-tokens.css public/static/css/style.css public/static/js/app.js

Type B: SPA (Vite) — with shadcn/ui

# Check available options first
npx -y create-vite@latest --help
# Scaffold React + TypeScript
npx -y create-vite@latest ./ --template react-ts
# Install Tailwind CSS
npm install -D tailwindcss @tailwindcs