/new-project

name: new-project
description: Full project bootstrap - interviews the developer (name, description, stack, components), then scaffolds directory structure, CLAUDE.md, config files, hooks, skills, and first commit.
user_invocable: true
allowed-tools:
- Read
- Write
- Edit
- Bash
- Glob

New Project Bootstrap

<!-- Mirrors AGENT.md in the agent-starter repo. If guides change, update this skill to match. -->

Use when starting a new project from scratch. Scaffolds a complete AI-friendly project following the agent-starter patterns: feature-based directory structure, CLAUDE.md with memory taxonomy, config files, optional hooks and skills, first commit.

For existing projects, use `/adopt-project` instead.

Phase 0: Detect what's already installed

Hooks and skills install **system-wide** under `~/.claude/`, so they're shared across every project. Detect them first and never ask about components that are already present. Run:

# Hooks: install.sh stamps this file with the installed version
HOOKS_VER=$( [ -f ~/.claude/hooks/.agent-starter-version ] && cat ~/.claude/hooks/.agent-starter-version || echo "" )
HOOKS_N=$( ls ~/.claude/hooks/*.sh 2>/dev/null | wc -l | tr -d ' ' )

# Skills: the starter skills this bootstrap installs
for s in commit commit-push-pr simplify remember dream new-project adopt-project reflect; do
  [ -d ~/.claude/skills/$s ] && echo "skill:$s present" || echo "skill:$s missing"
done
echo "hooks: version ${HOOKS_VER:-none}, $HOOKS_N scripts"

Interpret the output:

• **Hooks installed** if `.agent-starter-version` exists (or hook scripts are

found). Record the stamped version.

• **Skills installed** per directory listed as `present`.

Carry this into the interview and scaffold: only ask about, and only install, what's **missing**. If a stamped hooks version is present but older than the repo `VERSION` (checked in Phase 1 once you have the repo path), note that an update is available and offer to re-run `install.sh` (idempotent) - don't force it.

Phase 1: Interview

Ask these questions **one at a time** before taking any action:

1. **Project name** - what is the name of the project? 2. **Description** - one sentence describing what it does. 3. **Tech stack** - language, framework, package manager (e.g. "TypeScript, Next.js, pnpm"). 4. **Optional components** - ask **only about what Phase 0 reported as missing**. If hooks and all skills are already installed, skip this question entirely - state what was detected ("Hooks v0.4.4 and all 8 skills already installed system-wide, skipping") and move on. Otherwise offer the missing set:

• Hooks (auto-enforce file size limits, lint-on-save, silent-error and dangerous-command blocking, codebase health checks at `~/.claude/hooks/`)
• Skills (commit, commit-push-pr, simplify, remember, dream, new-project, adopt-project, reflect at `~/.claude/skills/`)
• Both
• Neither

5. **Repo path** - what is the local path to the agent-starter repo? (e.g. `~/code/agent-starter`). Always required: the CLAUDE.md template, foundation templates, and lint configs are all copied from the repo. (Hooks and skills also install from here when selected and not already present.)

Do not proceed past this step until you have all answers.

Phase 2: Scaffold

Execute these steps in order.

1. Create directory structure

mkdir -p <project-name>/src/features
mkdir -p <project-name>/src/services
mkdir -p <project-name>/src/utils
mkdir -p <project-name>/src/types
mkdir -p <project-name>/src/constants
mkdir -p <project-name>/src/schemas
mkdir -p <project-name>/src/entrypoints
mkdir -p <project-name>/src/migrations
mkdir -p <project-name>/tests
mkdir -p <project-name>/docs
mkdir -p <project-name>/scripts

Design principle: organize by feature, not by technical layer. Each feature gets its own directory under `src/features/` with ALL related files (implementation, types, constants, validation, tests). Keep files under 200 lines each. Shared type definitions go in `src/types/` to break import cycles. Named constants go in `src/constants/` (no magic strings anywhere).

2. Generate CLAUDE.md

Copy the canonical template - do **not** inline or hand-write it, so it never drifts from `templates/CLAUDE.md` (which carries the Memory System, Git Safety, Implementation Notes, and Self-improvement loop sections):

cp <repo-path>/templates/CLAUDE.md <project-name>/CLAUDE.md

Then fill in the `## Project-Specific Instructions` section at the bottom:

**Project:** <project-name>
**Description:** <project-description>

3. Create config files

**`.gitignore`** at `<project-name>/.gitignore`:

node_modules/
dist/
.env
*.log
.DS_Store
.cache/
coverage/
CLAUDE.local.md

**`.env.example`** at `<project-name>/.env.example`:

# Required environment variables - copy to .env and fill in values

**`README.md`** at `<project-name>/README.md`:

# <project-name>

<project-description>

## Getting Started

<!-- Add setup instructions here -->

**`CLAUDE.local.md`** at `<project-name>/CLAUDE.local.md` (gitignored above - personal, machine-local instructions that never get committed):

# Personal Instructions (local only)

<!-- Your personal preferences for this project. Not committed. -->

**`.claude/rules/`** - modular instruction files the agent loads alongside CLAUDE.md. Create the directory and the apply-on-touch pattern index, which is the same file `/adopt-project` writes (Tier 4):

mkdir -p <project-name>/.claude/rules

Write `<project-name>/.claude/rules/starter-patterns.md`:

# Starter patterns - apply on touch

Apply these when already editing the relevant code. Never as a bulk refactor.

- Editing a file over 300 lines -> split per the file-size hook's suggestions
  (types / constants / validation / utils).
- Touching a `throw` / `raise` site -> route it through the error registry
  (`guides/error-id-registry.md`).
- Changin