Skip to content

newproject: extract scaffold logic into scripts/scaffold.sh #14

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
nsmiller2501 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

newproject: extract scaffold logic into scripts/scaffold.sh #14

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a1f7c44
Expand newproject research scaffold
nsmiller2501 May 8, 2026
3a5ba80
Extract newproject scaffold script
nsmiller2501 May 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 91 additions & 0 deletions .claude/skills/newproject/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
# `/newproject` — Standard Project Scaffold

Invoked at the start of every new research project to create a consistent directory structure.

## Usage

```
/newproject my-project-name
```

## What It Creates

```
my-project-name/
├── CLAUDE.md # Research rules & estimation philosophy (from template)
├── README.md # This file — project-specific notes
├── code/
│ ├── config.do # Canonical Stata globals & paths
│ ├── config.py # Canonical Python paths (pathlib)
│ ├── config.R # Canonical R paths
│ ├── requirements.txt # Python dependencies
│ ├── download/ # Scripts for pulling raw data
│ ├── data/
│ │ └── validation/ # Data validation scripts
│ └── analysis/
│ ├── stata/
│ ├── R/
│ └── python/
├── data/
│ ├── raw/ # Original source data (never modify)
│ └── clean/ # Cleaned/merged datasets
├── output/
│ ├── figures/
│ ├── tables/
│ └── logs/ # Log files from all scripts
├── documents/ # Outside PDFs, papers (split with /split-pdf)
├── references/
│ └── raw/ # Paper PDFs for reference-ingest skills
├── decks/ # Beamer presentations
├── notes/ # Personal scratch notes; ignored by git in git-enabled projects
├── agent_memory/ # Shared Claude/Codex reference files
│ ├── key_decisions.md # Methodological choices and rationale
│ ├── dropped_analyses.md # Paths abandoned and why
│ ├── codebook.md # Variable definitions
│ └── sample_restrictions.md # Who's in/out of the sample
├── correspondence/ # Letters, emails, audit reports
│ # `referee2/` and `blindspot/` subdirs are created
│ # lazily by those skills on first use
└── progress_logs/ # Session logs for continuity across Claude conversations
```

Use `references/raw/` for PDFs of papers or other sources you want to process with `/split-pdf`, `/read-pdf`, `/bib-update`, and/or `/wiki-update`. The reference-ingest skills create their own derived files lazily: `/wiki-update` creates `references/wiki/`, and `/bib-update` creates `references/references.bib`.

If wanting to link your project to Obsidian, simply go to `Obsidian → Manage vaults → Open folder as vault` and select your project folder as a new vault. This allows each project to be cleanly differentiated and you won't have to worry about backlink-collision across projects.

## Philosophy

### Two Configuration Files, Two Purposes

Every project has both a `CLAUDE.md` and a `README.md`. They serve different roles:

- **`CLAUDE.md`** is copied from a permanent template at `~/.claude/skills/newproject/templates/project_CLAUDE.md`. It contains research rules that apply across all sessions: estimation philosophy ("design before results"), coding conventions, collaborator information, and key methodological decisions. It is the *institutional memory* of the project — the file that keeps Claude aligned across conversations.

- **`agent_memory/`** holds the shared reference files that Claude and the user should version over time: decisions, dropped analyses, codebook entries, and sample restrictions.

- **`notes/`** is for private scratch notes and anything you do not want versioned.

- **`README.md`** is auto-generated by this command and then edited as the project evolves. It is project-specific: what the research question is, who's involved, current status, and how files are organized. It's the file a human reads to understand the project.

### Session Continuity

The `progress_logs/` directory solves a real problem: Claude Code sessions don't persist. If a session crashes, times out, or you start fresh, the progress log tells the next session exactly where you left off. Logs are dated (`YYYY-MM-DD_description.md`) and maintained regularly.

### Documents and Decks

- `documents/` holds outside PDFs — papers you're reading, referee reports, data documentation. These are candidates for the `/split-pdf` skill, which splits large PDFs into safe 4-page chunks for reading.

- `decks/` holds Beamer presentations built following the rhetoric of decks philosophy (`~/.claude/skills/beautiful_deck/rhetoric_of_decks.md`). Titles are assertions, one idea per slide, beauty is function.

### Data Discipline

- `data/raw/` is **read-only** by convention. Original source data goes here and is never modified.
- `data/clean/` holds everything that's been transformed, merged, or constructed. Scripts in `code/` take raw data and produce clean data.

## First-time setup

Before using a generated project, fill in the placeholders in its root `CLAUDE.md`, especially `[NAME]`, collaborators, project overview, data sources, and key files. Put durable project memory in `agent_memory/`, not `notes/`.

## Installation

This skill lives at `~/.claude/skills/newproject/SKILL.md`. Invoke with `/newproject`.
128 changes: 61 additions & 67 deletions .claude/skills/newproject/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,87 +1,81 @@
---
name: newproject
description: Scaffold a new research project with standard directory structure, CLAUDE.md template, and documented README. Use this at the start of every new project to ensure consistent organization.
allowed-tools: Bash(mkdir*), Bash(cp*), Bash(ls*), Write, Read
description: Scaffold a new research project with standard directory structure, CLAUDE.md template, and language-agnostic config files (Stata/Python/R). Use this at the start of every new project to ensure consistent organization.
allowed-tools: Bash(ls*), Bash(~/.claude/skills/newproject/scripts/scaffold.sh:*), Read
argument-hint: [project-name]
---

# New Project Scaffold

Create a new research project folder with Scott's standard structure. This skill is invoked at the start of every project.
Create a new research project folder with the standard structure.

## Templates

All templates are stored locally in the skill at `~/.claude/skills/newproject/templates/`:

- `project_CLAUDE.md` — project root CLAUDE.md
- `config.do`, `config.py`, `config.R` — canonical paths for Stata / Python / R
- `requirements.txt` — Python dependencies stub

Templates use `{{PROJECT_ROOT}}` and `{{PROJECT_NAME}}` placeholders that this skill substitutes at scaffold time.

## What Gets Created

```
[project-name]/
├── CLAUDE.md # Permanent research rules (copied from template)
├── README.md # Project-specific overview (auto-generated)
├── CLAUDE.md # Research rules (from template)
├── README.md # Project-specific overview (auto-generated)
├── code/
│ ├── R/
│ ├── python/
│ └── stata/
│ ├── config.do # Canonical Stata globals & paths
│ ├── config.py # Canonical Python paths (pathlib)
│ ├── config.R # Canonical R paths
│ ├── requirements.txt # Python dependencies
│ ├── download/ # Scripts for pulling raw data
│ ├── data/
│ │ └── validation/ # Data validation scripts
│ └── analysis/
│ ├── stata/
│ ├── R/
│ └── python/
├── data/
│ ├── raw/ # Original source data (never modify)
│ └── clean/ # Cleaned/merged datasets
│ ├── raw/ # Original source data (never modify)
│ └── clean/ # Cleaned/merged datasets
├── output/
│ ├── figures/
│ ├── tables/
│ └── figures/
├── documents/ # Outside PDFs, papers (use /split-pdf on these)
├── decks/ # Beamer presentations (rhetoric of decks)
├── notes/ # Scratch notes, random ideas, misc
└── progress_logs/ # Session continuity across Claude conversations
│ └── logs/ # Log files from all scripts
├── documents/ # Outside PDFs, papers
├── references/
│ └── raw/ # PDFs for split-pdf/read-pdf/wiki-update/bib-update
├── decks/ # Beamer presentations
├── notes/ # Personal scratch notes; ignored by git in git-enabled projects
├── agent_memory/ # Shared Claude/Codex reference files for this project
├── correspondence/ # Letters, emails, referee reports (subdirs created lazily by /referee2 and /blindspot)
└── progress_logs/ # Session continuity logs
```

## Execution

1. **Get the project name** from the argument. If none provided, ask.
- Convert spaces to hyphens, lowercase

2. **Determine location** — default is current working directory. Confirm if unclear.

3. **Create all directories:**
```bash
mkdir -p [project-name]/{code/{R,stata,python},data/{raw,clean},output/{figures,tables},documents,decks,notes,progress_logs}
```

4. **Copy CLAUDE.md** from `~/mixtapetools/claude/CLAUDE.md`:
- Replace `[Your Name]` with `Scott`
- Update project name in the overview section

5. **Generate README.md** with:
- Project title
- Visual directory tree in a fenced code block (monospace)
- Explanation of each folder's purpose
- Note that CLAUDE.md is copied from a permanent template and edited per-project
- Note that README.md is for project-specific documentation
- Note that progress_logs/ maintains continuity across Claude sessions
- Placeholder sections: Overview, Collaborators, Status, Key Files

The README must include this tree block:

````markdown
```
[project-name]/
├── CLAUDE.md # Research rules & estimation philosophy (permanent)
├── README.md # This file — project-specific notes
├── code/
│ ├── R/ # R scripts
│ ├── python/ # Python scripts
│ └── stata/ # Stata do-files
├── data/
│ ├── raw/ # Original source data (never modify these)
│ └── clean/ # Cleaned and merged datasets
├── output/
│ ├── tables/ # Generated tables (LaTeX, CSV)
│ └── figures/ # Generated figures (PDF, PNG)
├── documents/ # Outside papers and PDFs (split with /split-pdf)
├── decks/ # Beamer presentations (rhetoric of decks philosophy)
├── notes/ # Scratch notes, ideas, miscellaneous
└── progress_logs/ # Session logs for continuity across Claude conversations
```
````

6. **Create initial progress log** at `progress_logs/YYYY-MM-DD_setup.md`:
- Record the creation date
- List next steps as a checklist

7. **Report success** — show structure with `ls`, remind user to update CLAUDE.md.
### Step 1 — Get project name and location
If no argument was provided, ask:
> "What should I name this project? (will be used as the folder name and in templates)"

Default to current working directory. If unclear, confirm with the user.

### Step 2 — Run scaffold script

Run:

```bash
~/.claude/skills/newproject/scripts/scaffold.sh "[project-name]" "[parent-directory]"
```

The script normalizes the project name, creates the directory tree, renders templates, writes agent-memory stubs, generates `README.md`, and creates the initial setup log. It prints the absolute project root.

### Step 3 — Report success

Show the created structure with `ls -R [project-name] | head -60`.
Remind the user to:
- Fill in the Project Overview in `CLAUDE.md`
- Update `code/config.*` files if the project root ever moves
- Add Python packages to `code/requirements.txt` as needed
Loading