bootstrap

name	bootstrap
description	Bootstrap a new project with a proper .claude/ setup for agentic development. Use when: setting up a new codebase for Claude Code, user says "set up this project", "bootstrap", "add Claude to this repo", or when .claude/ is missing in a project. Creates CLAUDE.md, CODEBASE.md, docs/, knowledge/, and optionally skills and hooks.
allowed-tools	Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
argument-hint	[project-path] [--type code|knowledge]

/bootstrap — Set Up a Project for Claude Code

First: Read LEARNINGS.md in this skill's directory.

Arguments: $ARGUMENTS

If no project path given, use the current working directory. If --type not specified, infer from context (has src/, package.json, Cargo.toml -> code; otherwise -> knowledge).

Step 1: Reconnaissance

Before creating anything, understand what exists.

1. Read the project's existing README, package.json/Cargo.toml/pyproject.toml, or equivalent
2. ls the top-level directory structure
3. Check if .claude/ already exists — if so, audit what's there and fill gaps instead of overwriting
4. Identify:
   • Tech stack (languages, frameworks, package manager)
   • Build/lint/test commands (from package.json scripts, Makefile, etc.)
   • Major modules (top-level dirs that represent distinct concerns)
   • Project type: code (has source code, build system) or knowledge (notes, docs, automation)

Present findings to the user in a table. Confirm before proceeding.

Step 2: Create Directory Structure

.claude/
  CLAUDE.md              # Behavioral core (always created)
  CODEBASE.md            # Project overview + module index (code projects only)
  docs/                  # Module documentation (code projects only)
    <module>.md          # One per major module
  knowledge/             # On-demand context
    <framework>.md       # Language/framework conventions
  settings.local.json    # Project-scoped settings (if hooks needed)

For knowledge projects, skip CODEBASE.md and docs/. Add instead:

.claude/
  rules/                 # Domain rules (always loaded)
  knowledge/sessions/    # Session logs

Create the directories. Do NOT create empty placeholder files.

Step 3: Write CLAUDE.md

Target: 30-40 lines max. This burns context tokens every session.

Structure — adapt sections to the project:

# <Project Name>

## Commands
- `<build command>` -- build the project
- `<test command>` -- run tests
- `<lint command>` -- lint/typecheck

## Process
- Before starting, read `.claude/CODEBASE.md` and relevant `.claude/docs/` files
- Do NOT use the Explore agent by default -- read documentation first
- After code changes, update documentation if interfaces or behavior changed
- When fetching context, state which documents you loaded

## Available Documentation
- `.claude/CODEBASE.md` -- project overview and module index
- `.claude/docs/<module>.md` -- <one-line description>

## Available Knowledge
- `.claude/knowledge/<topic>.md` -- <one-line description>

What goes in CLAUDE.md: commands, process instructions, file listings. What does NOT go in CLAUDE.md: architecture details (-> CODEBASE.md), code conventions (-> knowledge/), module descriptions (-> docs/).

Step 4: Write CODEBASE.md (Code Projects Only)

The entry point Claude reads first. Include:

1. What the project does (2-3 sentences)
2. Tech stack summary
3. Module index — one line per module linking to its doc file
4. <!-- docs-synced-at: <commit-hash> --> marker on line 1

<!-- docs-synced-at: abc1234 -->
# <Project Name> — Codebase Overview

<What this project does. 2-3 sentences.>

## Tech Stack
<Language, framework, database, key libraries>

## Modules
| Module | Description | Docs |
|--------|-------------|------|
| `src/api/` | REST API routes and handlers | [docs/api.md](docs/api.md) |
| `src/web/` | Frontend application | [docs/web.md](docs/web.md) |

Step 5: Write Module Docs (Code Projects Only)

One file per major module in docs/. Each file:

• What the module does (2-3 sentences)
• Key interfaces and type signatures (actual code, not prose)
• Links to source files
• Important design decisions and why
• Behavioral description (what happens when X is called)

These describe behavior and intent for an agent, not auto-generated API docs.

Use an Agent subagent per module (parallel) to scan source code and produce the doc.

Step 6: Write Knowledge Files

Create knowledge/<topic>.md for each relevant framework/language convention. Only create files for technologies actually used — don't speculate.

For knowledge projects, also create any needed rules/*.md files.

Knowledge file design principles:

• YAML frontmatter on every file (tags, created, last_reviewed, type)
• Imperative phrasing ("Use X for Y" not "X is used for Y")
• Tables over prose for structured data
• 40-80 lines per file, no redundancy — each fact lives in ONE place
• Actionable: "what do I need to know to act", not complete documentation

For knowledge projects, also set up MEMORY.md:

• Under 200 lines always (silently truncated beyond)
• Structure: Active State table, Key Decisions, Next Up, File Map
• Concise index pointing to topic files — not a comprehensive document
• "Next Up" section is mandatory — next session reads this first

Step 7: Configure Hooks (If Needed)

Only add hooks when the project has specific needs:

Need	Hook	Example
Security boundaries	PreToolUse guard	Block writes outside project dir
Session continuity	PreCompact state dump	Save critical context before compaction
Reminders	Stop hook	"Update docs before ending"

Write hooks to scripts/ and register in .claude/settings.local.json.

Step 8: Verify

Run through the checklist:

#	Item	Check
1	CLAUDE.md exists and is under 40 lines
2	CLAUDE.md lists all doc and knowledge files
3	CLAUDE.md has build/lint/test commands
4	CODEBASE.md exists with module index (code projects)
5	Each major module has a docs/ file (code projects)
6	knowledge/ files exist for each framework used
7	No placeholder/empty files
8	CLAUDE.md disables Explore agent by default

Present the completed checklist to the user.

Step 9: Initial Commit

Stage all .claude/ files. Commit message: feat: bootstrap .claude/ for agentic development

Do NOT push without user approval.

Rules

• Minimal CLAUDE.md is non-negotiable. 30-40 lines. Minimize noise, maximize signal — it gets very bad, very fast if you give information that you might not use.
• Never dump architecture into CLAUDE.md. That's what CODEBASE.md and docs/ are for.
• Docs describe behavior, not API surface. Write for an agent that needs to understand the codebase without reading every file.
• Only create files for things that exist. Don't create knowledge/react.md if the project doesn't use React.
• Third-party projects get isolation. Add to CLAUDE.md: Do NOT update ~/claude-assistant/knowledge/, MEMORY.md, or task backlog for this project.
• Don't over-document. Start lean. Fill gaps over time as you learn what's actually needed.
• Adapt, don't template. Every project is different. The structure above is a guide, not a rigid template. A 3-file Python script doesn't need module docs.