bootstrap/guides/bootstrap.md

# Project Bootstrap Guide

> Load this guide when setting up a new project for AI-assisted development.

## Overview

This guide covers how to bootstrap a project so AI agents (Claude, Codex, etc.) can work on it effectively. Proper bootstrapping ensures:

1. Agents understand the project structure and conventions
2. Orchestration works correctly with quality gates
3. Independent code review and security review are configured
4. Issue tracking is consistent across projects

## Quick Start

```bash
# Automated bootstrap (recommended)
~/.mosaic/rails/bootstrap/init-project.sh \
  --name "my-project" \
  --type "nestjs-nextjs" \
  --repo "https://git.mosaicstack.dev/owner/repo"

# Or manually using templates
export PROJECT_NAME="My Project"
export PROJECT_DESCRIPTION="What this project does"
export TASK_PREFIX="MP"
envsubst < ~/.mosaic/templates/agent/CLAUDE.md.template > CLAUDE.md
envsubst < ~/.mosaic/templates/agent/AGENTS.md.template > AGENTS.md
```

---

## Step 1: Detect Project Type

Check what files exist in the project root to determine the type:

| File Present | Project Type | Template |
|---|---|---|
| `package.json` + `pnpm-workspace.yaml` + NestJS+Next.js | NestJS + Next.js Monorepo | `projects/nestjs-nextjs/` |
| `pyproject.toml` + `manage.py` | Django | `projects/django/` |
| `pyproject.toml` (no Django) | Python (generic) | Generic template |
| `package.json` (no monorepo) | Node.js (generic) | Generic template |
| Other | Generic | Generic template |

```bash
# Auto-detect project type
detect_project_type() {
  if [[ -f "pnpm-workspace.yaml" ]] && [[ -f "turbo.json" ]]; then
    # Check for NestJS + Next.js
    if grep -q "nestjs" package.json 2>/dev/null && grep -q "next" package.json 2>/dev/null; then
      echo "nestjs-nextjs"
      return
    fi
  fi
  if [[ -f "manage.py" ]] && [[ -f "pyproject.toml" ]]; then
    echo "django"
    return
  fi
  if [[ -f "pyproject.toml" ]]; then
    echo "python"
    return
  fi
  if [[ -f "package.json" ]]; then
    echo "nodejs"
    return
  fi
  echo "generic"
}
```

---

## Step 2: Create CLAUDE.md

The `CLAUDE.md` file is the primary configuration file for AI agents. It tells them everything they need to know about the project.

### Using a Tech-Stack Template

```bash
# Set variables
export PROJECT_NAME="My Project"
export PROJECT_DESCRIPTION="Multi-tenant SaaS platform"
export PROJECT_DIR="my-project"
export REPO_URL="https://git.mosaicstack.dev/owner/repo"
export TASK_PREFIX="MP"

# Use tech-stack-specific template if available
TYPE=$(detect_project_type)
TEMPLATE_DIR="$HOME/.mosaic/templates/agent/projects/$TYPE"

if [[ -d "$TEMPLATE_DIR" ]]; then
  envsubst < "$TEMPLATE_DIR/CLAUDE.md.template" > CLAUDE.md
else
  envsubst < "$HOME/.mosaic/templates/agent/CLAUDE.md.template" > CLAUDE.md
fi
```

### Using the Generic Template

```bash
# Set all required variables
export PROJECT_NAME="My Project"
export PROJECT_DESCRIPTION="What this project does"
export REPO_URL="https://git.mosaicstack.dev/owner/repo"
export PROJECT_DIR="my-project"
export SOURCE_DIR="src"
export CONFIG_FILES="pyproject.toml / package.json"
export FRONTEND_STACK="N/A"
export BACKEND_STACK="Python / FastAPI"
export DATABASE_STACK="PostgreSQL"
export TESTING_STACK="pytest"
export DEPLOYMENT_STACK="Docker"
export BUILD_COMMAND="pip install -e ."
export TEST_COMMAND="pytest tests/"
export LINT_COMMAND="ruff check ."
export TYPECHECK_COMMAND="mypy ."
export QUALITY_GATES="ruff check . && mypy . && pytest tests/"

envsubst < ~/.mosaic/templates/agent/CLAUDE.md.template > CLAUDE.md
```

### Required Sections

Every CLAUDE.md should contain:

1. **Project description** — One-line summary
2. **Conditional documentation loading** — Table of guides
3. **Technology stack** — What's used
4. **Repository structure** — Directory tree
5. **Development workflow** — Branch strategy, build, test
6. **Quality gates** — Commands that must pass
7. **Issue tracking** — Commit format, labels
8. **Code review** — Codex and fallback review commands
9. **Secrets management** — How secrets are handled

---

## Step 3: Create AGENTS.md

The `AGENTS.md` file contains agent-specific patterns, gotchas, and orchestrator integration details.

```bash
TYPE=$(detect_project_type)
TEMPLATE_DIR="$HOME/.mosaic/templates/agent/projects/$TYPE"

if [[ -d "$TEMPLATE_DIR" ]]; then
  envsubst < "$TEMPLATE_DIR/AGENTS.md.template" > AGENTS.md
else
  envsubst < "$HOME/.mosaic/templates/agent/AGENTS.md.template" > AGENTS.md
fi
```

### Living Document

AGENTS.md is a **living document**. Agents should update it when they discover:
- Reusable patterns (how similar features are built)
- Non-obvious requirements (e.g., "frontend env vars need NEXT_PUBLIC_ prefix")
- Common gotchas (e.g., "run migrations after schema changes")
- Testing approaches specific to this project

---

## Step 4: Create Directory Structure

```bash
# Create standard directories
mkdir -p docs/scratchpads
mkdir -p docs/templates
mkdir -p docs/reports
```

---

## Step 5: Initialize Repository Labels & Milestones

```bash
# Use the init script
~/.mosaic/rails/bootstrap/init-repo-labels.sh

# Or manually create standard labels
~/.mosaic/rails/git/issue-create.sh  # (labels are created on first use)
```

### Standard Labels

| Label | Color | Purpose |
|-------|-------|---------|
| `epic` | `#3E4B9E` | Large feature spanning multiple issues |
| `feature` | `#0E8A16` | New functionality |
| `bug` | `#D73A4A` | Defect fix |
| `task` | `#0075CA` | General work item |
| `documentation` | `#0075CA` | Documentation updates |
| `security` | `#B60205` | Security-related |
| `breaking` | `#D93F0B` | Breaking change |

### Initial Milestone

Create the first milestone for MVP:

```bash
~/.mosaic/rails/git/milestone-create.sh -t "0.1.0" -d "MVP - Minimum Viable Product"
```

---

## Step 6: Set Up CI/CD Review Pipeline

### Woodpecker CI

```bash
# Copy Codex review pipeline
mkdir -p .woodpecker/schemas
cp ~/.mosaic/rails/codex/woodpecker/codex-review.yml .woodpecker/
cp ~/.mosaic/rails/codex/schemas/*.json .woodpecker/schemas/

# Add codex_api_key secret to Woodpecker CI dashboard
```

### GitHub Actions

For GitHub repos, use the official Codex GitHub Action instead:
```yaml
# .github/workflows/codex-review.yml
uses: openai/codex-action@v1
```

---

## Step 7: Verify Bootstrap

After bootstrapping, verify everything works:

```bash
# Check files exist
ls CLAUDE.md AGENTS.md docs/scratchpads/

# Verify CLAUDE.md has required sections
grep -c "Quality Gates" CLAUDE.md
grep -c "Technology Stack" CLAUDE.md
grep -c "Code Review" CLAUDE.md

# Verify quality gates run
eval "$(grep -A1 'Quality Gates' CLAUDE.md | tail -1)"

# Test Codex review (if configured)
~/.mosaic/rails/codex/codex-code-review.sh --help
```

---

## Available Templates

### Generic Templates

| Template | Path | Purpose |
|----------|------|---------|
| `CLAUDE.md.template` | `~/.mosaic/templates/agent/` | Generic project CLAUDE.md |
| `AGENTS.md.template` | `~/.mosaic/templates/agent/` | Generic agent context |

### Tech-Stack Templates

| Stack | Path | Includes |
|-------|------|----------|
| NestJS + Next.js | `~/.mosaic/templates/agent/projects/nestjs-nextjs/` | CLAUDE.md, AGENTS.md |
| Django | `~/.mosaic/templates/agent/projects/django/` | CLAUDE.md, AGENTS.md |

### Orchestrator Templates

| Template | Path | Purpose |
|----------|------|---------|
| `tasks.md.template` | `~/src/jarvis-brain/docs/templates/orchestrator/` | Task tracking |
| `orchestrator-learnings.json.template` | `~/src/jarvis-brain/docs/templates/orchestrator/` | Variance tracking |
| `phase-issue-body.md.template` | `~/src/jarvis-brain/docs/templates/orchestrator/` | Gitea issue body |
| `scratchpad.md.template` | `~/src/jarvis-brain/docs/templates/` | Per-task working doc |

### Variables Reference

| Variable | Description | Example |
|----------|-------------|---------|
| `${PROJECT_NAME}` | Human-readable project name | "Mosaic Stack" |
| `${PROJECT_DESCRIPTION}` | One-line description | "Multi-tenant platform" |
| `${PROJECT_DIR}` | Directory name | "mosaic-stack" |
| `${PROJECT_SLUG}` | Python package slug | "mosaic_stack" |
| `${REPO_URL}` | Git remote URL | "https://git.mosaicstack.dev/mosaic/stack" |
| `${TASK_PREFIX}` | Orchestrator task prefix | "MS" |
| `${SOURCE_DIR}` | Source code directory | "src" or "apps" |
| `${QUALITY_GATES}` | Quality gate commands | "pnpm typecheck && pnpm lint && pnpm test" |
| `${BUILD_COMMAND}` | Build command | "pnpm build" |
| `${TEST_COMMAND}` | Test command | "pnpm test" |
| `${LINT_COMMAND}` | Lint command | "pnpm lint" |
| `${TYPECHECK_COMMAND}` | Type check command | "pnpm typecheck" |
| `${FRONTEND_STACK}` | Frontend technologies | "Next.js + React" |
| `${BACKEND_STACK}` | Backend technologies | "NestJS + Prisma" |
| `${DATABASE_STACK}` | Database technologies | "PostgreSQL" |
| `${TESTING_STACK}` | Testing technologies | "Vitest + Playwright" |
| `${DEPLOYMENT_STACK}` | Deployment technologies | "Docker" |
| `${CONFIG_FILES}` | Key config files | "package.json, tsconfig.json" |

---

## Bootstrap Scripts

### init-project.sh

Full project bootstrap with interactive and flag-based modes:

```bash
~/.mosaic/rails/bootstrap/init-project.sh \
  --name "My Project" \
  --type "nestjs-nextjs" \
  --repo "https://git.mosaicstack.dev/owner/repo" \
  --prefix "MP" \
  --description "Multi-tenant platform"
```

### init-repo-labels.sh

Initialize standard labels and MVP milestone:

```bash
~/.mosaic/rails/bootstrap/init-repo-labels.sh
```

---

## Checklist

After bootstrapping, verify:

- [ ] `CLAUDE.md` exists with all required sections
- [ ] `AGENTS.md` exists with patterns and quality gates
- [ ] `docs/scratchpads/` directory exists
- [ ] Git labels created (epic, feature, bug, task, etc.)
- [ ] Initial milestone created (0.1.0 MVP)
- [ ] Quality gates run successfully
- [ ] `.env.example` exists (if project uses env vars)
- [ ] CI/CD pipeline configured (if using Woodpecker/GitHub Actions)
- [ ] Codex review scripts accessible (`~/.mosaic/rails/codex/`)