New Project

New Project Bootstrap

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 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 - which would you like installed?

• 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

1. 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.)

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 /src/features
mkdir -p /src/services
mkdir -p /src/utils
mkdir -p /src/types
mkdir -p /src/constants
mkdir -p /src/schemas
mkdir -p /src/entrypoints
mkdir -p /src/migrations
mkdir -p /tests
mkdir -p /docs
mkdir -p /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 /templates/CLAUDE.md /CLAUDE.md

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

**Project:** 
**Description:** 

3. Create config files

.gitignore at /.gitignore:

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

.env.example at /.env.example:

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

README.md at /README.md:

# 

## Getting Started

CLAUDE.local.md at /CLAUDE.local.md (gitignored above - personal, machine-local instructions that never get committed):

# Personal Instructions (local only)

.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 /.claude/rules

Write /.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`).
- Changing a fallible function's signature -> consider returning a Result
  (`guides/discriminated-union-results.md`).
- Touching an env read -> move it behind the env boundary
  (`guides/zod-at-the-boundary.md`).
- Adding a long-running operation -> thread cancellation through it
  (`guides/abort-signal-threading.md`).
- Adding a new tool -> use the directory-per-tool layout
  (`guides/tool-authoring-pattern.md`).

Optionally also create topic stubs (testing.md, git-workflow.md, code-style.md, security.md) per templates/NEW_PROJECT_PROMPT.md - offer these but don't force them.

Lint configs - if the stack is TypeScript/JavaScript:

cp /templates/biome.json /biome.json
cp /templates/eslint.config.mjs /eslint.config.mjs
cd  && npm i -D @biomejs/biome eslint typescript-eslint eslint-plugin-import \
  eslint-plugin-sonarjs eslint-plugin-security eslint-plugin-eslint-comments

If the stack is Python:

cp /templates/ruff.toml /ruff.toml
cp /templates/pyrightconfig.json /pyrightconfig.json
cd  && uv add --dev ruff pyright   # or: python -m pip install ruff pyright

See guides/lint-rules-for-ai.md for what the rules catch. Skip for other stacks.

4. Copy foundation templates (TypeScript/JavaScript or Python)

Reference: guides/error-id-registry.md, guides/zod-at-the-boundary.md, guides/large-codebase-best-practices.md

These are the "create from day one" foundation files (see templates/NEW_PROJECT_PROMPT.md -> Foundation Files): a centralized env boundary, a numbered error registry, and an output truncator. Copy them for the matching stack and adapt import paths to the layout.

If the stack is TypeScript/JavaScript:

cp /templates/env.ts /src/utils/env.ts
cp /templates/errorIds.ts /src/constants/errorIds.ts
cp /templates/truncate-for-context.ts /src/utils/truncate-for-context.ts

If the stack is Python:

cp /templates/env.py /src/utils/env.py
cp /templates/error_ids.py /src/constants/error_ids.py
cp /templates/truncate_for_context.py /src/utils/truncate_for_context.py

Skip for other stacks (Rust, Go, etc.) - point the developer at the guides above to build equivalents.

5. Install hooks (if selected)

Run the idempotent installer - it copies the hooks (and lib/) to ~/.claude/hooks/, stamps the installed version, and merges the hook wiring into ~/.claude/settings.json with jq. Existing entries are preserved and re-running never duplicates anything - do not hand-edit the JSON:

bash /install.sh

Hook behavior (wired by default):

• check-file-size.sh - runs after every Write/Edit. Blocks (exit 2) files over 300 lines; warns over 200 lines. Skips .md, .json, .yaml.
• lint-on-edit.sh - Biome + ESLint on save for JS/TS; ruff check + format for Python.
• check-silent-errors.sh - blocks writes that introduce swallowed exceptions.
• block-dangerous-commands.sh - blocks force-push, git reset --hard, recursive rm on //~, before they run.
• check-codebase-health.sh - runs at session start. Reports files over 500 lines that need splitting. Silent when healthy.

Optional: --with-read-guard also wires track-reads.sh + require-read-before-edit.sh. Recent Claude Code versions enforce read-before-edit natively, so only add it for older versions.

6. Install skills (if selected)

mkdir -p ~/.claude/skills
cp -r /skills/commit ~/.claude/skills/
cp -r /skills/commit-push-pr ~/.claude/skills/
cp -r /skills/simplify ~/.claude/skills/
cp -r /skills/remember ~/.claude/skills/
cp -r /skills/dream ~/.claude/skills/
# new-project skill is included in this repo at skills/new-project/
cp -r /skills/new-project ~/.claude/skills/
cp -r /skills/adopt-project ~/.claude/skills/
cp -r /skills/reflect ~/.claude/skills/

Installed skills:

• /commit - single well-crafted git commit with "why not what" message
• /commit-push-pr - full workflow: branch, commit, push, create/update PR
• /simplify - 3 parallel agents review your diff for reuse, quality, efficiency
• /remember - review auto-memory and promote to CLAUDE.md or CLAUDE.local.md
• /dream - memory consolidation: merge, prune, re-index memory files
• /new-project - this skill (bootstrap a new project)
• /adopt-project - apply these patterns to an existing codebase
• /reflect - read ledger, cluster recurring mistakes, propose improvements

7. Initialize the self-improvement ledger

mkdir -p /.harness/reflections
touch /.harness/reflections/.gitkeep
echo '.harness/ledger.jsonl' >> /.gitignore

The enforcement hooks use hooks/lib/log-event.sh to append structured events to .harness/ledger.jsonl as the agent works. Run /reflect periodically: it reads the ledger via harness-ledger-stats.sh, clusters recurring mistakes, and proposes rule / threshold / ADR changes for your approval. See templates/CLAUDE.md → "Self-improvement loop".

8. Initialize git and first commit

cd 
git init
git add .
git commit -m "$(cat <<'EOF'
Initial project scaffold

Bootstrapped using agent-starter patterns.
EOF
)"

Phase 3: Verify

Confirm each item before reporting done:

• [ ] Project directory with feature-based structure (src/features, src/services, src/utils, src/types, src/constants, src/schemas, src/entrypoints, src/migrations, tests/, docs/, scripts/)
• [ ] CLAUDE.md copied from templates/CLAUDE.md (not inlined) with project name and description filled in
• [ ] .gitignore, .env.example, README.md, and CLAUDE.local.md present (CLAUDE.local.md gitignored)
• [ ] .claude/rules/starter-patterns.md written
• [ ] Lint configs copied + deps installed - biome.json + eslint.config.mjs (TS/JS) or ruff.toml + pyrightconfig.json (Python); skipped for other stacks
• [ ] Foundation templates copied - env boundary + error registry + truncator for the stack (TS or Python); skipped for other stacks
• [ ] Hooks installed to ~/.claude/hooks/ and configured in settings.json (if selected)
• [ ] Skills installed to ~/.claude/skills/ (if selected)
• [ ] .harness/reflections/ created and .harness/ledger.jsonl added to .gitignore
• [ ] reflect skill installed to ~/.claude/skills/reflect
• [ ] Initial git commit created

Allowed Tools

Read, Write, Edit, Bash, Glob

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sneg55
• Source: sneg55/agent-starter
• License: MIT

Install and usage instructions live in the source repository linked above.