Environment Setup Skill

Automatically configure a new user's local development environment for App Factory.

When This Skill Applies

User says /setup, "set me up", or "configure my environment"
User asks "how do I get started" or "what do I need to install"
First-time contributor onboarding

Setup Procedure

When triggered, execute the following checks in order. Skip tools that are already installed and at the correct version. Show a plan before executing any installations.

Phase 1: Core Requirements (BLOCKING)

These MUST pass before proceeding. If any fail, show the fix and stop.

1.1 Node.js (>= 18.0.0)

node --version 2>/dev/null

PASS: Version >= 18.0.0
FAIL: Prompt user to install via brew install node (macOS), nvm install 18, or https://nodejs.org

1.2 npm

npm --version 2>/dev/null

PASS: Any version (ships with Node.js)
FAIL: Reinstall Node.js

1.3 Git

git --version 2>/dev/null

PASS: Any version 2.x+
FAIL: xcode-select --install (macOS) or sudo apt-get install git (Linux)

1.4 Claude Code CLI

claude --version 2>/dev/null

PASS: Any version
FAIL: npm install -g @anthropic-ai/claude-code

Phase 2: Repository Integrity

Verify the repo is intact and all 6 pipelines are present.

2.1 Pipeline Directories

Check each directory exists and contains a CLAUDE.md:

app-factory/CLAUDE.md
website-pipeline/CLAUDE.md
dapp-factory/CLAUDE.md
agent-factory/CLAUDE.md
plugin-factory/CLAUDE.md
miniapp-pipeline/CLAUDE.md

PASS: All 6 exist
WARN: Missing pipelines (list which ones)

2.2 Core Infrastructure

Check these critical files/directories exist:

plugins/factory/commands/factory.md
scripts/local-run-proof/verify.mjs
scripts/factory_ready_check.sh
core/package.json
.claude/settings.json
.mcp.json

PASS: All present
WARN: List missing files with remediation

Phase 3: Dependencies

3.1 Root npm Install

# Check if node_modules exists
ls node_modules/.package-lock.json 2>/dev/null

PASS: node_modules exists and is populated
ACTION: Run npm install at repository root (requires user approval)

3.2 Husky Git Hooks

ls .husky/_/husky.sh 2>/dev/null

PASS: Husky hooks installed
ACTION: Run npx husky install (requires user approval)

Phase 4: Environment Configuration

4.1 Environment Variables

# Check .env exists
test -f .env

PASS: .env exists
ACTION: Copy from .env.example → .env, then prompt user to fill in ANTHROPIC_API_KEY

4.2 MCP Server Configuration

Check .mcp.json exists and .claude/settings.json has MCP servers enabled:

github, playwright, filesystem, context7, semgrep

PASS: Configuration files present and servers listed
WARN: Missing servers with instructions to enable

Phase 5: Optional Tools (Non-Blocking)

These improve the development experience but are not required.

5.1 watchman (for Expo/React Native hot reload)

watchman --version 2>/dev/null

PASS: Installed
SKIP: Not installed (suggest brew install watchman on macOS)
Only relevant if user plans to use app-factory

5.2 Xcode Command Line Tools (macOS only)

xcode-select -p 2>/dev/null

PASS: Installed
SKIP: Not installed (suggest xcode-select --install)
Only relevant on macOS for iOS simulator preview

5.3 Development Tools Check

Verify these work from root package.json scripts:

npx eslint --version 2>/dev/null
npx prettier --version 2>/dev/null
npx tsc --version 2>/dev/null

PASS: All return versions
WARN: Missing tools (will be available after npm install)

Phase 6: Validation

Run the validation script to confirm everything:

bash scripts/validate-setup.sh

Output: Status Report

After all phases, display a summary table:

============================================================
  App Factory Environment Setup Report
============================================================

  Core Requirements:
    Node.js 18+          PASS  (v20.11.0)
    npm                  PASS  (v10.2.4)
    Git                  PASS  (v2.43.0)
    Claude Code CLI      PASS  (v1.x.x)

  Repository Integrity:
    app-factory          PASS
    website-pipeline     PASS
    dapp-factory         PASS
    agent-factory        PASS
    plugin-factory       PASS
    miniapp-pipeline     PASS
    Core infrastructure  PASS

  Dependencies:
    npm install          PASS
    Husky hooks          PASS

  Environment:
    .env file            PASS
    MCP servers          PASS  (5/5 configured)

  Optional Tools:
    watchman             SKIP  (not needed unless using app-factory)
    Xcode CLI Tools      PASS  (macOS)
    ESLint               PASS
    Prettier             PASS
    TypeScript           PASS

============================================================
  Result: READY

  You're all set! Next steps:
  1. Run /factory help to see available commands
  2. Run ./quickstart.sh for an interactive guide
  3. cd into any pipeline directory and run claude
============================================================

Critical Rules

Show plan first - Never install anything without showing what will happen
Require approval - Ask before running npm install or brew install
Skip installed tools - Never reinstall something that's already at the right version
Non-destructive - Never overwrite existing .env files (only create if missing)
Parallel where safe - Version checks can run in parallel; installations must be sequential
Respect invariants - All 8 App Factory invariants apply (no silent execution, mandatory approval, etc.)
macOS awareness - Detect platform and adjust commands accordingly (brew vs apt)
Graceful degradation - Optional tools failing should not block setup completion

Error Recovery

If any BLOCKING check fails:

Show the specific error
Provide the exact fix command
Ask user to fix and re-run /setup
Do NOT attempt to continue past blocking failures

If any OPTIONAL check fails:

Mark as SKIP in the report
Note what functionality is affected
Continue with remaining checks

setup-environment