repo-init

Initialize a repository with a standard, opinionated project structure. Run once per project. Re-running (or running on an existing repo) adds missing pieces only — it never overwrites or repairs existing files.

The intake is a hard gate. Create nothing — no directories, no files, not even git init — until the step-2 intake is either completed with the user or skipped by an explicit flag (--no-grill / --dry-run). Scaffolding first and asking later defeats the skill: the answers determine what gets scaffolded.

File templates (loaded at runtime)

D="${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/skills/repo-init}"; D="${D:-$HOME/.claude/skills/repo-init}"; cat "$D/TEMPLATES.md" 2>/dev/null || echo "(TEMPLATES.md not found — abort and report a broken install)"

Live state

pwd && git rev-parse --show-toplevel 2>/dev/null || echo "(not a git repo yet)"

Modes

Ground rules

1. Never destructive. Before writing any file: if it already exists, skip it — never overwrite, never merge silently. mkdir -p for directories is always fine. Report skipped (exists); reserve skipped (exists — differs from template) for files that look like a broken or partial scaffold (unfilled placeholders, a template skeleton with no real content). Pre-existing real content is normal, not a warning.
2. Two sanctioned exceptions to "never touch an existing file":
   • .gitignore — never rewrite; diff it against the template entries, report which standard entries are missing, and ask before appending (gitignoring is a deliberate choice). After any append, run git ls-files against the newly ignored patterns: if matches exist, warn explicitly that .gitignore does not untrack already-committed files (they stay in the repo and its history until git rm --cached / a history rewrite) — this matters most before a repo ever goes public.
   • docs/DECISIONS.md — an append-only ledger: a re-run appends a new dated init entry recording that run's intake answers; existing entries are never edited or rewritten.
3. CLAUDE.md / AGENTS.md on retrofit: if CLAUDE.md already exists and is not the redirect stub (compare against the CLAUDE-STUB template), do not create AGENTS.md — ask the user: keep CLAUDE.md canonical (scaffold no AGENTS.md, or an inverted 3-line AGENTS.md stub pointing at CLAUDE.md), or migrate to the AGENTS-canonical pattern. Never leave both files substantive — that split-brain is exactly what the redirect convention exists to prevent.
4. Substitute all {{PLACEHOLDERS}} and <angle-bracket> fills per the header of TEMPLATES.md before writing. {{AUTHOR}}/{{EMAIL}} come from git config user.name/user.email; if unset, use a <fill me in> placeholder and flag it in the report. If the intake changes the mode, redo step-1 resolution (including {{PKG_NAME}}) before scaffolding.

Steps

1. Resolve target dir, provisional mode (from flags), repo name (dir basename), and — package mode — {{PKG_NAME}}. State all four before anything else.

2. Intake grill — the hard gate (skipped only under --no-grill or --dry-run): invoke the grilling skill on the tree below; if it is not available, ask the questions yourself — the gate stands either way. The tree is hierarchical — later questions are gated and shaped by earlier answers. Ask in order, one at a time, waiting for each answer — this pins the cadence deliberately (the grilling core otherwise asks a whole frontier per round), because the gate's verbatim-answer record depends on one answer per question. Evidence (dir name, flags, visible files) supplies the default offered inside the question — never a silently assumed answer.

   Answers are the user's words. Record each answer verbatim in the DECISIONS init entry (quoted; shorten only with a marked ellipsis). Never write an answer the user did not give: an unasked or unanswered question is recorded as (not asked — <reason>), and a skipped intake as (intake skipped). An invented answer is worse than a skipped question — it forges the decision log.

   #	Question	Asked when	Shaped by earlier answers	Lands in
   1	Purpose — what is this repo for, and what is the end artifact (paper, report, software release, operational product)?	Always	—	AGENTS.md Purpose; README.md description; sets the defaults offered in Q2/Q4/Q5
   2	Shape & lifespan — analysis project or distributable library? One-off or long-lived?	Always (--package pre-answers "library")	Q1: software artifact → default library; paper/analysis → default research; operational products start as research mode	Final mode (if this changes it, redo step-1 resolution); operational posture note in AGENTS.md
   3	Audience & visibility — private, shared with collaborators, public later (e.g. at publication), or public now?	Always	Q1: a published-paper artifact defaults to "public at publication"	README tone; gates Q3b; reminder to match the GitHub remote's visibility
   3b	License & ownership — who owns the copyright: the author personally, or an employer (work-for-hire)? Which license?	Skipped only if Q3 = private and the user accepts skipping. An explicit --no-license pre-answers the license half as "skip" (never re-ask it); if Q3 indicates a public trajectory, still ask the ownership half and note the flag in DECISIONS	Q3: any public trajectory makes this required, not optional	LICENSE (correct holder via {{COPYRIGHT_HOLDER}}); pyproject license line (deleted if skipped); CITATION.cff
   4	Data — where will input data come from (scripted download, delivered, cloud store)? Anything restricted that must never be committed? Any dependency on an existing repo or its data?	Skipped if Q1+Q2 imply no data (e.g. pure library)	Q3: restricted data + a future-public answer → strongest warning; on retrofit, triggers the ground-rule-2 tracked-file check immediately	data/README.md provenance seeds; extra .gitignore guards; repo dependencies documented in AGENTS.md
   5	Reproducibility bar — will anyone (future-you, a coauthor, a reviewer) need to rerun this after the project goes cold?	Skipped if Q4 was skipped and Q1 has no analysis component	Q3/Q4: public visibility or non-scripted data raise the suggested default	Recorded in docs/DECISIONS.md; if the bar is high, next-steps suggests pinning an environment (environment setup is out of scope for init)

   Every answer is recorded, dated and attributed, in the docs/DECISIONS.md init entry (see DECISIONS template) — day-zero answers drift, and the log is what lets a future session tell current truth from initial guess.

3. git init if not already a repository.

4. Scaffold per mode:

   Common core (both modes): .gitignore (CORE + mode section) · .ai/ dir · CLAUDE.md (thin stub) · AGENTS.md (subject to ground rule 3 on retrofit) · README.md · docs/DECISIONS.md (append the init entry if it already exists) · LICENSE (per Q3b; skipped under --no-license).

   Research mode: notebooks/ + README · scripts/ + README · data/inputs/ + data/outputs/ + data/README.md · figures/ + README.

   Package mode: src/{{PKG_NAME}}/__init__.py · tests/test_import.py · pyproject.toml · .pre-commit-config.yaml · .github/workflows/pytest.yaml · CITATION.cff. Adapt the AGENTS.md Layout table and data rule to what was actually created.

5. Report a table: every path → created / skipped (exists) / skipped (exists — differs from template) / appended (.gitignore, with approval). Flag unfilled placeholders and any tracked files matching newly ignored patterns (ground rule 2).
6. Suggest next steps (do not execute unasked): fill in anything the report flagged; pre-commit install && pre-commit autoupdate (package mode); pin an environment if the Q5 bar was high; first commit; connect a Zenodo webhook before the first release (package mode).

Anti-Rationalization

Verification

• Nothing was created before the intake completed (or an explicit --no-grill/--dry-run was stated in the report)
• Every applicable intake question was actually put to the user, one at a time
• Every recorded answer is the user's verbatim reply — nothing invented, unasked questions marked (not asked)
• All intake answers recorded, stamped, in the docs/DECISIONS.md init entry (appended, if the file pre-existed)
• Unfilled placeholders and tracked-but-newly-ignored files flagged

Does not

• Overwrite or restructure existing content — retrofit means adding what's missing, only.
• Set up environments or lockfiles (suggests it as a next step when Q5 warrants), install anything, or make commits.
• Scaffold helper modules like utilities.py — if the user maintains a shared helper library (their global CLAUDE.md will say so), point the scaffolded AGENTS.md at it; otherwise leave the placeholder comment.
• Carry any project-specific or person-specific references — templates stay neutral and fully usable on a clean machine.