add-project

What this skill does

# Add Project — Idea to Ralph Loop

Single entry point for new projects. Creates the project shell and ralph loop — ralph does the actual building.

**Project path:** The user provides the new project path (e.g. project name or full directory path). add-project creates the shell and the ralph loop at that path. In addition to everything below, add-project (1) **adds the ralph loop to the loops catalog** (`loops/<project-name>/`) so it is registered for future reference and evaluation, and (2) **creates the loop at the user-provided path** in `.ralph/` — the execution loop (PLAN.md, PROMPT.md, AGENT.md, etc.) lives in `{user-path}/.ralph/`.

```
Phase 1: Spec     — idea → docs/specs/{name}.md         (parallel scanning)
Phase 2: Shell    — spec → project dir with symlinks     (NO Next.js — ralph does that)
Phase 3: Ralph    — generate .ralph/ loop from spec      (PLAN.md, PROMPT.md, AGENT.md) + register in loops/
Phase 4: Secrets  — 1Password → .env.local               (batched — one biometric)
Phase 5: Report   — summary + next steps

SMS notification is sent after EVERY phase completes (see "Phase SMS Notifications" below).
Phase summary is presented after EVERY phase (see "Phase Summary" below).
```

**KEY PRINCIPLE: add-project creates the shell. Ralph builds the app.**

add-project currently runs in **fresh-only** mode. PLAN.md step 1.1 is always "Apply `create-next` skill" (Ralph scaffolds Next.js). add-project never runs `create-next-app` itself.

**Scaffold guide:** For skill ordering and the tiered scaffold model (what to install and in what order), use [references/SCAFFOLD.md](references/SCAFFOLD.md) and [references/scaffold-dag.json](references/scaffold-dag.json). The DAG defines Tier 0 (every project: app-shell → runtime → ui-data → testing), Tier 1 (most apps: auth, ai, background-jobs), Tier 2 (specialized packs: collaboration, video-media, visual), and Tier 3 (ops). Use it whenever you derive a skill list or PLAN step order from a no-frills spec.

---

## Subagent Strategy

### Model Routing

| Task Type | Model | Why |
|-----------|-------|-----|
| Skill catalog scanning | haiku | Read-only, fast, 5x cheaper |
| Plan/doc reading | haiku | Simple extraction |
| Template file generation | haiku | Filling known values |
| Dependency graph + mapping | sonnet | Moderate reasoning for toposort |
| Verification checks | haiku | Mechanical validation |
| User interaction + orchestration | opus (inherited) | Complex coordination |

### Parallelization Rules

1. **Independent work = parallel subagents**: Launch multiple Task calls in a single message
2. **Early-start where safe**: Phase 4 (1Password) can start during Phase 3
3. **Converge before user-facing steps**: Wait for all subagents before presenting results

---

## Phase 1: Generate the Project Spec (Delegate to add-spec)

**Invoke the add-spec skill** to produce the spec. add-spec runs the full brainstorming workflow (explore context → clarify → approaches → design approval → design doc), then writes a no-frills spec to `docs/specs/{project-name}.md`.

1. Invoke **add-spec** (load and follow [skills/add-spec/SKILL.md](skills/add-spec/SKILL.md)).
2. add-spec will create:
   - `docs/plans/YYYY-MM-DD-<topic>-design.md` (design doc)
   - `docs/specs/{project-name}.md` (no-frills spec: Mission, Main Features, Major User Flows, Required Screens, Required Features mapped to /skills, Open Gaps, Constraints)
3. Wait until add-spec completes and the spec file exists at `docs/specs/{project-name}.md`.
4. Proceed only after the user has approved the spec (add-spec obtains approval before writing).

**Do not proceed until spec is approved and add-spec has written the spec file.**

**→ Present Phase 1 Summary, then send Phase 1 SMS** (see "Phase SMS Notifications" below)

---

## Phase 2: Create Project Shell (Fast, Sequential)

**Project directory:** Use the path the user provided for the new project (e.g. `{project-name}` or full path). All shell and .ralph artifacts are created under that path; the ralph loop will live in `{user-path}/.ralph/`.

Read the spec. **Skill list:** Extract skill names from the no-frills spec's **Required Features (from /skills)** table. Include `create-next` if not already listed (needed for Ralph step 1.1). **Order** the skill list using [references/scaffold-dag.json](references/scaffold-dag.json): Tier 0 layers first (app-shell, runtime, ui-data, testing), then Tier 1 (auth, ai, background-jobs as present), then Tier 2 packs by dependency; this matches [references/SCAFFOLD.md](references/SCAFFOLD.md) and ensures symlinks and later PLAN steps follow the scaffold guide.

**Fresh mode** — This phase creates ONLY the directory and skill symlinks. No Next.js. No packages.

```bash
# 1. Create project directory
mkdir -p {project-name}/.claude/skills

# 2. Resolve the skills source root once
SKILLS_ROOT=$(cd "$(dirname "$(realpath skills/add-project/SKILL.md)")/../.." && pwd)

# 3. Symlink all skills from the spec using SKILLS_ROOT
cd {project-name}/.claude/skills
for skill in {skills-from-spec}; do
  ln -s "$SKILLS_ROOT/skills/$skill" "$skill"
done
```

**Verify:**

```bash
# All symlinks resolve
for link in {project-name}/.claude/skills/*/SKILL.md; do
  test -f "$link" || echo "BROKEN: $link"
done
```

### 2b: Generate .ralphrc (tool permissions)

**CRITICAL: Without this file, ralph has no tool permissions and will halt on loop 1.**

```bash
cat > {project-name}/.ralphrc << 'RALPHRC'
# Ralph Configuration for {PROJECT_NAME}
# Generated by add-project skill

# Claude Code CLI command
CLAUDE_CODE_CMD=claude

# Model — use sonnet for balanced cost/capability, opus for complex projects
CLAUDE_MODEL=claude-sonnet-4-6

# Rate limiting
MAX_CALLS_PER_HOUR=100

# Claude timeout per loop iteration (minutes)
CLAUDE_TIMEOUT_MINUTES=15

# Output format
CLAUDE_OUTPUT_FORMAT=json

# Allowed tools — MUST include Task for parallel subagents
# Bash(*) is used instead of granular Bash(cmd *) patterns because:
# 1. Skills install arbitrary packages (bun add, bunx, drizzle-kit, biome, etc.)
# 2. Docker commands vary by project (docker compose, docker exec, etc.)
# 3. Granular patterns are fragile — any new command halts ralph
# 4. Ralph runs locally under developer control, not in production
# playwright-cli is available globally — runs via Bash, no MCP needed
CLAUDE_ALLOWED_TOOLS="Write,Read,Edit,Glob,Grep,Bash(*),Task,WebFetch,WebSearch,ToolSearch,Skill"

# Session continuity — resume between loops
CLAUDE_USE_CONTINUE=true

# Session expiry (hours)
CLAUDE_SESSION_EXPIRY_HOURS=24

# Additional directories to reference (resolved skills root)
ADD_DIRS="{SKILLS_ROOT}"

# Circuit breaker settings
CB_NO_PROGRESS_THRESHOLD=3
CB_SAME_ERROR_THRESHOLD=5
CB_OUTPUT_DECLINE_THRESHOLD=70
CB_COOLDOWN_MINUTES=30
CB_AUTO_RESET=false
RALPHRC
```

Replace `{PROJECT_NAME}`, `{SKILLS_ROOT}` with actual values.

**Model selection for .ralphrc:**

- `claude-sonnet-4-6` — default for most projects (good balance of speed/capability)
- `claude-opus-4-6` — for complex multi-skill projects (20+ skills, heavy custom code)
- `claude-haiku-4-5-20251001` — for simple projects (few skills, mostly boilerplate)

**Why these specific tools:**

| Tool | Why Ralph Needs It |
|------|-------------------|
| `Task` | Parallel subagents (dynamic model selection in PROMPT.md) |
| `Bash(*)` | Skills run arbitrary CLI commands (bun, docker, drizzle-kit, biome, curl, op, playwright-cli) |
| `WebFetch/WebSearch` | Documentation lookups during skill application |
| `ToolSearch` | Discovers and loads MCP tools at runtime |
| `Skill` | Invokes project skills directly |

> **Note:** `playwright-cli` runs via `Bash(*)` — no MCP tool permissions needed.

### 2c: Initialize Git Repository

**CRITICAL: Without a git repo, Ralph's circuit breaker kills the loop.**

Ralph detects progress by running `git diff` to count changed files between loops.
Without a git repo, `files_changed` is always 0, the circuit breaker sees "no progress"
for 3 con