project-setup

name

project-setup

description

Initializes a standard AI-ready project structure in the current working directory. Use this skill when the user says "setup project", "project setup", "init project", "create project structure", or any variation of wanting to set up a new project folder with Claude's standard files and directories. Also use when the user wants to fix or complete an existing project that's missing parts of the standard structure. Always invoke this skill proactively when the user says they want to start a new project or organize a folder for AI-assisted work.

project-setup — Project Structure Initializer

Purpose

Create a standard AI-ready project structure in the current directory. Non-destructive — always skip files and folders that already exist. After setup, offer to fill in the skeleton sections interactively.

---

Step 1 — Detect current state

Check what already exists in the current working directory:

ls -la

Note which of these already exist (skip them, only create what's missing):

• CLAUDE.md
• SESSION.md
• TODO.md
• NOTES.md
• INSIGHTS.md
• .ai-notes/
• .reference/
• .tmp/
• .backups/
• .gitignore

Tell the user what you found and what you're about to create.

---

Step 2 — Create missing structure

CLAUDE.md

# PROJECT NAME — Reference

**Project:** ...
**Owner/Team:** ...
**Stack:** ...
**Status:** ...
**Last Updated:** DD-MM-YY

---

## 📁 PROJECT STRUCTURE

| File/Folder | Purpose |
|-------------|---------|
| `CLAUDE.md` | Master instructions — what Claude needs to know about this project |
| `SESSION.md` | Chronological log — gotchas, key findings, what was done and why |
| `TODO.md` | Open/closed tasks — single source of truth for what needs doing |
| `NOTES.md` | Quick personal scratchpad — raw notes, temp thoughts |
| `INSIGHTS.md` | Workflow improvement ideas — skill candidates, CLAUDE.md gaps, automation ideas |
| `.ai-notes/` | Deep-dive reports, incident docs, session-level investigations |
| `.reference/` | Stable evergreen reference docs (endpoint maps, runbooks, architecture references) |
| `.tmp/` | Claude's workspace — temporary scripts and batch files (never commit) |
| `.backups/` | File and DB backups (never commit) |

> 📋 **Where to find things:**
> - What was done last session → `SESSION.md` (CHRONOLOGICAL LOG section)
> - Critical gotchas and findings → `SESSION.md` (KEY LEARNINGS section)
> - What needs doing → `TODO.md`
> - Deep investigation reports → `.ai-notes/YYYY-MM-DD-topic.md`
> - Stable lookup docs → `.reference/<prefix>__<topic>.md`

---

## 🛠️ STACK
<!-- Fill in: languages, frameworks, hosting, DB, key services -->

---

## ⚙️ KEY COMMANDS
<!-- Fill in: run, validate, publish/release, common operations -->

---

## 🔀 GIT WORKFLOW
<!-- Fill in: branch/change naming convention, release pattern, remotes -->

---

## 🔒 SAFETY PROTOCOLS

- **Always confirm before high-risk release actions**
- **Never commit `.env`, credentials, or sensitive config**
- **Destructive operations** (DROP, DELETE, rm -rf, etc.) require explicit confirmation
- **`.tmp/` and `.backups/`** are for local use only — never commit

---

**Last Updated:** DD-MM-YY
**Project Owner:** ...
**Purpose:** Master reference for Claude sessions on this project.

SESSION.md

# PROJECT NAME — Session Log

**Project:** ...
**Start Date:** DD-MM-YY

---

## KEY LEARNINGS & GOTCHAS

Critical findings — check before starting anything new.
<!-- Add numbered entries as you discover them: -->
<!-- ### 1. Finding title -->
<!-- Description of what was learned and why it matters. -->

---

## CHRONOLOGICAL LOG

<!-- Append new entries at the bottom. Format: -->
<!-- ## [YYYY-MM-DD HH:MM] — Description -->
<!-- - What was done -->
<!-- - Key decisions made -->
<!-- - Links to relevant .ai-notes/ reports -->

TODO.md

# PROJECT NAME — TODO

Last Updated: YYYY-MM-DD
Format: title + meta + tags (description optional)
Markers: [ ] open | [!] urgent | [x] done

How to read this file:
- Check urgent [!] tasks first, then regular [ ] tasks.
- Each task uses 3 lines: title, metadata (scope/target/owner/next/updated), then tags.
- `next` is the immediate action to take.
- `desc` appears only when extra context is needed.
- Completed history stays in the `Done` section at the bottom.

## Open Tasks

<!--
- [ ] Task title
scope: ... | target: ... | owner: ... | next: ... | updated: YYYY-MM-DD
#tag1 #tag2 #tag3
desc: optional extra context only when needed
-->

<!-- Keep urgent [!] tasks first, then regular [ ] tasks. -->

## Done
<!--
- [x] Task title
scope: ... | target: ... | owner: ... | next: completed in session | updated: YYYY-MM-DD
#tag1 #tag2 #tag3
-->

NOTES.md

Create with a simple starter header:

# PROJECT NAME - Notes

Temporary scratchpad for quick session notes and raw thoughts.

INSIGHTS.md

# INSIGHTS — [Project Name]

> Captured during sessions — workflow ideas, skill candidates, context gaps,
> and patterns worth acting on.
> Review periodically and promote to CLAUDE.md, skills, or TODO.md.

---

## 🔁 Skill Candidates
<!-- Tasks repeated often enough to become a skill -->

---

## 🔧 Skill Upgrades
<!-- Improvements spotted for existing skills -->

---

## 📋 CLAUDE.md Gaps
<!-- Context that was missing and slowed down a session -->

---

## ⚡ Automation Ideas
<!-- Repetitive manual steps that could be scripted or automated -->

---

## 💡 General AI Workflow Ideas
<!-- Broader ideas — prompting patterns, session habits, tools -->

---

## 🗃️ Archive
<!-- Ideas promoted to action — moved here once acted on -->

Directories

Create if missing — no files inside:

• .ai-notes/
• .reference/
• .tmp/
• .backups/

---

Step 3 — Update .gitignore

If .gitignore doesn't exist, create it. If it exists, only append the entries that aren't already present.

# AI session files — may contain sensitive project info
CLAUDE.md
SESSION.md
TODO.md
NOTES.md
INSIGHTS.md

# AI working directories
.ai-notes/
.reference/
.tmp/
.backups/

# Claude Code (optional for private projects)
# .claude/

# History
.history/

---

Step 4 — Report what was created

Give a clean summary:

## ✅ Project structure ready

Created:
- CLAUDE.md
- SESSION.md
- TODO.md
- NOTES.md
- INSIGHTS.md
- .ai-notes/
- .reference/
- .tmp/
- .backups/
- .gitignore (updated)

Skipped (already existed):
- [list any]

---
Would you like to fill in the skeleton sections now?
- Stack (languages, frameworks, hosting)
- Key Commands (run, validate, publish/release)
- Git Workflow (branch/change naming, remotes)

Say "yes fill in" to go through them one by one, or "skip" to do it later.

---

Step 5 — Interactive fill-in (optional)

Only if the user says yes. Go through each skeleton section one at a time, ask for the info, update CLAUDE.md with the answer, then move to the next. Don't ask for everything at once.

Order:

1. Project name + owner/team (update all placeholders in all files)
2. Stack
3. Key Commands
4. Git Workflow

After filling in, remind the user: "You can always update CLAUDE.md directly or ask me to add more commands and details as the project evolves."

---

TODO archiving

Default behavior: keep completed task history in ## Done at the bottom of TODO.md.

When the user explicitly says "archive done tasks" or "move done to archive":

• Move all completed entries from ## Done in TODO.md to .ai-notes/TODO-archive.md
• Append (don't overwrite) — the archive is cumulative
• Keep TODO.md focused on active work + recent done history
• Report how many tasks were archived
• Never do this automatically