# Project Setup

> Bootstrap new projects with standardized structure, CLAUDE.md, scratchpad, docs directory, and git repo. Use when creating a new project, setting up a repo, or bootstrapping from source material.

- Skill: `cobuchan/project-setup` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cobuchan/project-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cobuchan/project-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: cobuchan (https://skillmd.com/u/cobuchan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cobuchan/project-setup

---


# Project Setup Skill

Set up a new project with a standardized, agent-legible structure.

## When to Use

- User asks to create/set up a new project
- User has a folder with source material (transcript, article, notes) to bootstrap from
- User wants a consistent starting structure for a new repo

## Inputs

| Input | Required | Description |
|-------|----------|--------------|
| Project name | Yes | Directory name (kebab-case, e.g., `cyber-readiness`) |
| Project path | Yes | Usually `~/projects/[project-name]` |
| Purpose | Yes | One sentence describing what the project is |
| Source material | No | Transcript, article, or notes to derive context from |
| Tech stack | No | If known; often TBD at setup time |

## Process

### 1. Gather Context

If source material exists:
- Read and analyze it
- Extract: purpose, key concepts, stakeholders, constraints, open questions
- Identify potential phases/milestones

If no source material:
- Ask user for: purpose, key context, any known constraints

### 2. Create Directory Structure

```
[project-name]/
├── CLAUDE.md
├── scratchpad.md
├── .gitignore
├── .claude/
│   ├── agents/        # Project-specific agents (empty)
│   └── skills/        # Project-specific skills (empty)
└── docs/
    ├── INDEX.md
    ├── plans/
    │   └── [project-name]-plan.md
    ├── sessions/      # Session history (empty)
    ├── research/      # Research outputs (empty)
    └── Archive/       # Obsolete docs (empty)
```

### 3. Configure .mcp.json Allowlist (if needed)

If the project needs project-scoped MCP servers, create `.mcp.json` at project root with an **explicit allowlist** — avoid a blanket "enable all project MCP servers" setting if your harness offers one. A server only belongs in `.mcp.json` if this project actually uses it; servers used by several of your projects are better configured globally instead. Skip this step entirely if the project has no MCP needs yet — add `.mcp.json` later when a server is actually needed.

### 4. Create CLAUDE.md

Use this template:

```markdown
# [Project Name] - Project Rules

Inherits from `~/.claude/CLAUDE.md`. This file contains project-specific context only.

## Purpose

[One paragraph describing the project goal]

## Quick Links

| Resource | Location |
|----------|----------|
| Active Work | `scratchpad.md` |
| Project Plan | `docs/plans/[project-name]-plan.md` |
| Documentation | `docs/INDEX.md` |
[Add source material link if applicable]

## Key Context

[Bullet points of important context from source material or user input]

## Project-Specific Rules

[Any rules specific to this project - can start with placeholder]

## Lessons (Project)

*None yet.*
```

**Optional sections** (include if information available):
- Tech Stack
- Architecture Reference (if leveraging another project)
- Client/Stakeholder info
- Timeline/Deadlines

### 5. Create scratchpad.md

Use this template:

```markdown
# Scratchpad - [Project Name]

<!--
INSTRUCTIONS FOR CLAUDE:
- Do not rename sections
- Append instead of deleting prior content (mark outdated content as such)
- Update this file frequently during work sessions
- Add lessons learned immediately when bugs/corrections occur
- Keep under 150 lines; move verbose history to sessions/
- Only the top-level session writes to this file (subagents report back verbally)
-->

## Background/Motivation

[Why this project exists — one or two sentences, e.g., "Bootstraps [X] to solve [Y] for [stakeholder]."]

## Active Plan

**Plan**: `docs/plans/[project-name]-plan.md`
**Current Phase**: [Phase name or "Setup complete"]

## Key Decisions

[Numbered list of key decisions, or placeholder if none yet]

## Work Completed

### [Date]: Project Setup

- Created project structure
- [Any other setup work]

## Work In Progress

*None — awaiting [next phase/action].*

## Open Questions

[Numbered list of open questions from source material or setup]

## Session Lessons

*None yet.*

## Respawn Prompt

```
You are picking up work on the [Project Name] project.

Read in order:
1. ~/projects/[project-name]/CLAUDE.md — Project rules
2. ~/projects/[project-name]/scratchpad.md — Current state
3. ~/projects/[project-name]/docs/plans/[project-name]-plan.md — Project plan

CURRENT STATE:
- [Brief state summary]

[Any critical context]

Then tell me: What would you like to work on?
```

---

**Last updated**: [Date]
```

**Machine scratchpads**: `scratchpad.md` above is the single shared file — create it always. If you work from more than one machine, only add per-machine files (`scratchpad.laptop.md`, `scratchpad.desktop.md`, etc.) once the project is actually worked from more than one — each holds that machine's env state and respawn prompt, keyed by `hostname`. Don't scaffold them speculatively for a single-machine project.

### 6. Create docs/INDEX.md

Use this template:

```markdown
# [Project Name] Documentation Index

## Document Map

### Root Files

| File | Purpose |
|------|---------|
| `CLAUDE.md` | Project rules and context |
| `scratchpad.md` | Current work state |
[Add source file if applicable]

### Plans (`docs/plans/`)

| File | Purpose | Status |
|------|---------|--------|
| `[project-name]-plan.md` | High-level project plan | Active |

### Research (`docs/research/`)

*To be populated as research progresses*

### Sessions (`docs/sessions/`)

*Session history will be added as work progresses*

### Archive (`docs/Archive/`)

*Obsolete documents will be moved here*

## Agent Audit Manifest

| Agent | Authoritative Specs | Purpose |
|-------|---------------------|---------|
| Researcher | `docs/research/*.md` | Gather information |
| Implementer | `docs/plans/`, reference projects | Build components |
| Reviewer | `CLAUDE.md`, patterns | Ensure quality |

[Customize based on project needs]
```

### 7. Create docs/plans/[project-name]-plan.md

Use this template:

```markdown
# [Project Name] Plan

**Status**: 🟡 Planning
**Created**: [Date]
**Goal**: [One-line goal]

---

## Vision

[1-2 paragraphs describing the project vision and why it matters]

## Background

[Context from source material or user input]

---

## Phases

### Phase 1: [Name]

**Goal**: [What this phase achieves]

**Tasks**:
- [ ] Task 1
- [ ] Task 2

**Deliverables**:
- Deliverable 1
- Deliverable 2

### Phase 2: [Name]

[Repeat structure]

---

## Success Criteria

1. [Criterion 1]
2. [Criterion 2]

---

## Open Questions

1. [Question 1]
2. [Question 2]

---

## Risk Factors

| Risk | Mitigation |
|------|------------|
| [Risk 1] | [Mitigation] |

---

*This plan will be updated as work progresses.*
```

### 8. Create .gitignore

```
# OS
.DS_Store

# Dependencies
node_modules/

# Environment
.env
.env.local
.env*.local

# Build outputs
dist/
build/
.next/
out/

# IDE
.idea/
.vscode/
*.swp

# Logs
*.log
npm-debug.log*
```

### 9. Initialize Git and Create Remote

Do this immediately at project start — a project folder without its own repo silently inherits the nearest parent repo (e.g. the home folder), which pollutes `git status` with unrelated files and blocks proper version control. `git init` first, before any other work, prevents this.

```bash
cd ~/projects/[project-name]
git init
git add -A
git commit -m "Initial project setup

- CLAUDE.md with project context and rules
- scratchpad.md with current state
- docs/INDEX.md with documentation map
- docs/plans/[project-name]-plan.md with phased approach
- Standardized directory structure

Co-Authored-By: Claude <noreply@anthropic.com>"

gh repo create your-github-user/[project-name] --private --source=. --push --description "[One-line description]"
```

### 10. Create a Shell Alias (optional)

If you like quick `cd`-and-launch aliases, add one to your shell rc file for fast access:

```bash
# [Project Name] project
alias [short-name]='cd ~/projects/[project-name] && claude'
```

**Naming convention for short-name**:
- Use a recognizable abbreviation (e.g., `cyber` for `cyber-readiness`, `mission` for `mission-control`)
- Keep it short but unambiguous
- Check existing aliases first to avoid conflicts

After adding, remind the user to reload their shell config to activate it immediately.

### 11. Register the Project (optional)

If you keep your own project index or portfolio doc across projects, this is the point to add the new project to it — name, purpose, path, and a one-line status. Skip this step entirely if you don't maintain one; it's a nice-to-have for people running many projects side by side, not a requirement of this skill.

## Output

Report to user:
- Project path and GitHub URL
- Directory structure created
- Plan summary (phases)
- Any open questions identified
- Shell alias created, if any
- Confirmation of project-index update, if applicable

## Notes

- This skill creates the **scaffolding only** — it does not implement the project
- The plan should be high-level and legible; detailed PRDs are created separately (see `prd-creation`)
- Tech stack section in CLAUDE.md is optional (often TBD at setup)
- Source material is optional — skill works with or without it
- Always use kebab-case for project directory names
- **Group related deliverables under a topic subdirectory.** When a project produces multiple files about one topic, put them in a dedicated subdirectory (e.g. `docs/<topic>/`) rather than flat in the docs root. This keeps the docs tree legible as it grows; flat topic-files in the root become unmanageable quickly.