/initialize-project

Initialize Project

Full project setup with Claude coding guardrails. Works for both new and existing projects.

**This command is idempotent** - run it anytime to update skills, add missing structure, or reconfigure.

---

Phase 0: Validate Bootstrap Installation

**FIRST**, verify Maggy is properly installed:

# Read bootstrap directory (saved during install)
BOOTSTRAP_DIR=$(cat ~/.claude/.bootstrap-dir 2>/dev/null)
# Run quick validation
"$BOOTSTRAP_DIR/tests/validate-structure.sh" --quick

This checks:

• Skills are installed with correct structure (folder/SKILL.md)
• Commands are installed (~/.claude/commands/)
• Hooks are installed (~/.claude/hooks/)

**If validation fails:**

• Show the error to user
• Suggest running: `cd "$BOOTSTRAP_DIR" && git pull && ./install.sh`
• Offer to continue anyway or abort

**If validation passes:**

• Continue to Phase 1

---

Phase 1: Detect Project State

First, check what already exists:

# Check for existing Claude setup
ls -la .claude/skills/ 2>/dev/null
ls -la CLAUDE.md 2>/dev/null
ls -la _project_specs/ 2>/dev/null

# Check for cross-tool setup (Kimi CLI, Codex CLI)
ls -la .kimi/skills/ 2>/dev/null
ls -la .codex/skills/ 2>/dev/null
ls -la .agents/skills/ 2>/dev/null
ls -la AGENTS.md 2>/dev/null

# Detect installed AI CLI tools
BOOTSTRAP_DIR=$(cat ~/.claude/.bootstrap-dir 2>/dev/null)
DETECTED_AGENTS=$("$BOOTSTRAP_DIR/scripts/detect-agents.sh" 2>/dev/null || echo "claude")
echo "Detected AI CLI tools: $DETECTED_AGENTS"

# Check for existing git repo
git remote -v 2>/dev/null

# Check for existing package files
ls package.json pyproject.toml 2>/dev/null

# Check for Flutter project
ls pubspec.yaml 2>/dev/null

# Check for Android project
ls android/build.gradle android/app/build.gradle 2>/dev/null

# Check for native language in Android projects
find android -name "*.java" -type f 2>/dev/null | head -1
find android -name "*.kt" -type f 2>/dev/null | head -1

Based on findings, determine:

• **New project**: No CLAUDE.md, no .claude/skills/, no code files
• **Existing project with skills**: Has .claude/skills/ - offer to UPDATE
• **Existing codebase without skills**: Has code but no Claude setup - **AUTO-RUN ANALYSIS**

Inform the user:

• "Detected new project - will do full setup"
• "Detected existing Claude project - will update skills and add any missing structure"
• "Detected existing codebase - **analyzing before making changes...**"

**For existing codebases without Claude setup, AUTOMATICALLY proceed to Phase 1b.**

---

Phase 1b: Analyze Existing Codebase (Auto-triggered)

**This phase runs automatically when an existing codebase is detected without Claude setup.**

Step 1: Repository Structure Detection

echo "=== Analyzing Repository Structure ===" && \

# Detect repo type
if [ -d "packages" ] || [ -d "apps" ] || grep -q '"workspaces"' package.json 2>/dev/null; then
    REPO_TYPE="MONOREPO"
elif [ -d "frontend" ] && [ -d "backend" ]; then
    REPO_TYPE="FULL_STACK"
elif [ -d "src" ] && grep -q '"react\|vue\|angular"' package.json 2>/dev/null; then
    REPO_TYPE="FRONTEND"
elif [ -f "pyproject.toml" ] || grep -q '"express\|fastify"' package.json 2>/dev/null; then
    REPO_TYPE="BACKEND"
else
    REPO_TYPE="STANDARD"
fi
echo "Repo Type: $REPO_TYPE"

# Directory structure (3 levels, excluding noise)
find . -type d -maxdepth 3 \
    -not -path "*/node_modules/*" \
    -not -path "*/.git/*" \
    -not -path "*/venv/*" \
    -not -path "*/__pycache__/*" \
    -not -path "*/dist/*" \
    -not -path "*/build/*" \
    2>/dev/null | head -30

Step 2: Tech Stack Detection

echo "=== Tech Stack ===" && \

# Primary language/framework
[ -f "package.json" ] && echo "JavaScript/TypeScript project"
[ -f "tsconfig.json" ] && echo "  → TypeScript configured"
[ -f "pyproject.toml" ] && echo "Python project"
[ -f "pubspec.yaml" ] && echo "Flutter project"
[ -d "android" ] && echo "Android project"

# Frameworks (from package.json)
if [ -f "package.json" ]; then
    grep -q '"react"' package.json && echo "  → React"
    grep -q '"next"' package.json && echo "  → Next.js"
    grep -q '"express"' package.json && echo "  → Express"
    grep -q '"fastify"' package.json && echo "  → Fastify"
fi

# Frameworks (from pyproject.toml)
if [ -f "pyproject.toml" ]; then
    grep -q "fastapi" pyproject.toml && echo "  → FastAPI"
    grep -q "django" pyproject.toml && echo "  → Django"
    grep -q "flask" pyproject.toml && echo "  → Flask"
fi

Step 3: Guardrails Audit

echo "=== Guardrails Status ===" && \

# Pre-commit hooks
echo "Pre-commit Hooks:"
[ -d ".husky" ] && echo "  ✓ Husky installed" || echo "  ✗ Husky NOT installed"
[ -f ".pre-commit-config.yaml" ] && echo "  ✓ pre-commit framework" || echo "  ✗ pre-commit NOT installed"

# Linting
echo "Linting:"
(grep -q '"eslint"' package.json 2>/dev/null && echo "  ✓ ESLint") || \
(grep -q "ruff" pyproject.toml 2>/dev/null && echo "  ✓ Ruff") || \
echo "  ✗ No linter detected"

# Formatting
echo "Formatting:"
(grep -q '"prettier"' package.json 2>/dev/null && echo "  ✓ Prettier") || \
(grep -q "ruff\|black" pyproject.toml 2>/dev/null && echo "  ✓ Ruff/Black") || \
echo "  ✗ No formatter detected"

# Type checking
echo "Type Checking:"
([ -f "tsconfig.json" ] && echo "  ✓ TypeScript") || \
(grep -q "mypy" pyproject.toml 2>/dev/null && echo "  ✓ mypy") || \
echo "  ✗ No type checker detected"

# Commit validation
echo "Commit Validation:"
([ -f "commitlint.config.js" ] && echo "  ✓ commitlint") || \
(grep -q "conventional-pre-commit" .pre-commit-config.yaml 2>/dev/null && echo "  ✓ conventional-pre-commit") || \
echo "  ✗ No commit validation"

# CI/CD
echo "CI/CD:"
[ -d ".github/workflows" ] && echo "  ✓ GitHub Actions" || echo "  ✗ No GitHub Actions"

Step 4: Convention Detection

echo "=== Conventions Detected ===" && \

# File naming pattern
echo "File Naming:"
ls src/**/*.ts 2>/dev/null | head -3 || ls src/**/*.py 2>/dev/null | h