new-project

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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:

```bash
# 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").
   - **Tailwind design-system lint** - ask this follow-up only when the stack is
     TypeScript/JavaScript with a UI framework (React, Next.js, Remix, Vite +
     React): "Does the project use Tailwind v4, and should I add `@shadcn/lint`
     (blocks raw palette colors, arbitrary values, inline styles, unknown
     classes, and restyling design-system components via `className`)? yes/no".
     Record the answer; it drives the optional block in Phase 2 step 3. Skip
     the question for non-UI stacks.
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

```bash
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):

```bash
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
```

From sneg55/agent-starter, MIT.

More from sneg55/agent-starter