mosaic/bootstrap
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4eac2c76e697aed2d20063b9b857ab15b644518e
bootstrap/guides/bootstrap.md

9.9 KiB
Raw Blame History

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

# 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 
# 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

# 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

# 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.

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

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

Step 5: Initialize Repository Labels & Milestones

# 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:

~/.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

# 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:

# .github/workflows/codex-review.yml
uses: openai/codex-action@v1

Step 7: Verify Bootstrap

After bootstrapping, verify everything works:

# 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:

~/.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:

~/.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/)
Reference in New Issue View Git Blame Copy Permalink