validating-setup-commands

Validating Setup Commands

Overview

Worktrees require dependency installation before tasks can execute. Projects MUST define setup commands in CLAUDE.md.

This skill validates setup commands exist BEFORE creating worktrees, preventing cryptic failures later.

When to Use

Use this skill when:

• Creating new worktrees (spec, execute commands)
• Before executing tasks that need dependencies
• Any time you need to verify project setup is documented

Use early: Validate during setup phase, not during task execution.

Why This Matters

Without validation:

• Worktrees get created
• Tasks start executing
• Fail with "command not found" errors
• User debugging nightmare: "Why is npm/pytest/cargo missing?"

With validation:

• Missing commands detected immediately
• Clear error with exact CLAUDE.md section to add
• User fixes once, all worktrees work

The Validation Process

Announce: "Validating CLAUDE.md setup commands before creating worktrees."

Step 1: Check File Exists

# Get repo root
REPO_ROOT=$(git rev-parse --show-toplevel)

# Check if CLAUDE.md exists
if [ ! -f "$REPO_ROOT/CLAUDE.md" ]; then
  echo "❌ Error: CLAUDE.md not found in repository root"
  echo ""
  echo "Spectacular requires CLAUDE.md to define setup commands."
  echo "See: https://docs.claude.com/claude-code"
  exit 1
fi

Why fail fast: No CLAUDE.md = no command configuration. Stop before creating any worktrees.

Step 2: Parse Setup Section

# Parse CLAUDE.md for setup section
INSTALL_CMD=$(grep -A 10 "^### Setup" "$REPO_ROOT/CLAUDE.md" | grep "^- \*\*install\*\*:" | sed 's/.*: `\(.*\)`.*/\1/')

if [ -z "$INSTALL_CMD" ]; then
  echo "❌ Error: Setup commands not defined in CLAUDE.md"
  echo ""
  echo "Worktrees require dependency installation before tasks can execute."
  echo ""
  echo "Add this section to CLAUDE.md:"
  echo ""
  echo "## Development Commands"
  echo ""
  echo "### Setup"
  echo "- **install**: \`npm install\`  (or your package manager)"
  echo "- **postinstall**: \`npx prisma generate\`  (optional - any codegen)"
  echo ""
  echo "Example for different package managers:"
  echo "- Node.js: npm install, pnpm install, yarn, or bun install"
  echo "- Python: pip install -r requirements.txt"
  echo "- Rust: cargo build"
  echo "- Go: go mod download"
  echo ""
  echo "See: https://docs.claude.com/claude-code"
  echo ""
  echo "Execution stopped. Add setup commands to CLAUDE.md and retry."
  exit 1
fi

# Extract postinstall command (optional)
POSTINSTALL_CMD=$(grep -A 10 "^### Setup" "$REPO_ROOT/CLAUDE.md" | grep "^- \*\*postinstall\*\*:" | sed 's/.*: `\(.*\)`.*/\1/')