ai-workflow-framework: Skill for Claude Code

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.