braedensc/claude-project-kit

**Claude Code is at its best with permission prompts off — and that's dangerous.**
This template makes it safe: a GitHub template repo that starts your project with a
tested hook suite that hard-blocks the failure modes (secret reads, pushes to main,
self-merged PRs, edits to the guards themselves), git-level secret scanning, CI gates,
ready-to-adapt deploy/backup workflows, and the process docs that keep multi-session
agentic development coherent.
Everything here is **distilled, not invented** — generalized from a production app
built with Claude Code in a 10-day staged build, plus its retrospective. Every
generalized file carries a provenance header saying where it came from and what was
verified in production. (Some headers cite artifacts from that build — ADR-00xx,
PR numbers — as provenance breadcrumbs; they aren't links into *this* repo.)
The template is deliberately project-neutral, so contributions shouldn't reference any
other specific project by name. MIT licensed.
Prerequisites
| Tool | Version | Why |
|---|---|---|
| macOS or Linux | POSIX shell | Hooks are python3 + sh. **Windows: not supported natively — use WSL2** |
| git + GitHub CLI (gh), authenticated | recent | The workflow guards (merged-PR, Stop-hook PR checks) query GitHub via gh and fail open without it |
| Python 3 | 3.9+ on PATH as python3 | Every hook + the self-check scripts |
| Node.js | ≥ 20 (see .nvmrc) + npm | husky + secretlint (layer 2), regardless of your app's stack |
Quickstart
1. **Use this template** (button above) → create your repo → clone it.
(CLI: gh repo create --template braedensc/claude-project-kit --clone)
2. Open a fresh **Claude Code** session in the clone — the hooks are already active.
3. Paste the prompt from **BOOTSTRAP-PROMPT.md**. It interviews
you for stack choices, adapts every stack-specific file, fills every placeholder
(PLACEHOLDERS.md), deletes what doesn't apply, and runs the
kit's self-checks. You keep the human-only steps (secrets, dashboards, branch
protection).
**What you'll see on first open** (all expected — none of it is broken):
- A one-time **workspace trust** dialog, and a **Bypass Permissions warning** —
the kit ships defaultMode: bypassPermissions *because* the hooks hard-block the
dangerous operations in every mode. Uncomfortable anyway? Flip it to acceptEdits
in .claude/settings.local.json — every guard still enforces.
- A short **orientation line** injected at session start (branch, PR, dirty tree) —
that's the SessionStart hook.
- Occasional **hook blocks** (e.g. editing on main) — that's the system working;
branch and retry, exactly as the block message says.
- A growing .claude/audit.log (gitignored) — the local record of every command.
What's inside
| Path | What it is |
|---|---|
| .claude/ | Settings (hooks wiring + native permissions.deny) + the PreToolUse/PostToolUse/Stop hook suite + advisory SessionStart hook + test_hooks.py (the block/allow battery, runs in CI) — hooks/README.md |
| .claude/skills/ | /ship (commit → push → PR → watch CI → stop), /fix-ci, /work (ticket → PR, pipeline projects only) and /new-adr custom slash-commands |
| .husky/ + .secretlintrc.json | Layer-2 pre-commit: branch block, forbidden paths, worktree-aware secretlint |
| .github/workflows/ci.yml | The kit's own CI (battery, JSON/YAML validation, forbidden paths, secretlint, placeholder integrity) |
| .github/workflows/pr-conflict-monitor.yml + scripts/pr_conflict.py | The kit's own standing conflict watch — when an open PR goes CONFLICTING (a conflicted PR skips the required CI and can still look green), requests a fix — answered by the conflict waker, a supervised LaunchAgent that wakes a local session in its worktree (scripts/pipeline_conflict_waker_setup.py), or for a dispatcher's PR by the bounce driver in the session's own thread — and pages a person (the PR's author, or PR_CONFLICT_PAGE_TO) only when that stalls |