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.