Skip to content
/

zbruhnke/claude-code-starter

zbruhnke-cc-starter · zbruhnke/claude-code-starter · ★ 15 · last commit 2026-01-15

Prevents vibe-coding via a Wiggum Loop autonomous implementation skill with OS-level git pre-commit enforcement of test/lint/changelog gates.

Best whenQuality gates should be enforced at the git hook level (OS), not just in behavioral instructions — Claude should not be able to commit broken code even if it…
Skip ifVibe coding (blindly committing AI-generated changes without review), Stubs and TODOs (incomplete implementation)
vs seeds
superpowers' 1. The wiggum skill's .wiggum-session + git pre-c…
Primitive shape 29 total
Commands 3 Skills 11 Subagents 6 Hooks 9
00

Summary

zbruhnke/claude-code-starter — Summary

zbruhnke/claude-code-starter is a Claude Code starter template built around a central "Wiggum Loop" autonomous implementation skill, inspired by the Ralph Wiggum technique. The framework ships 3 slash commands, 11 skills, 6 subagents, and 9 hook scripts enforced via 4 lifecycle events (UserPromptSubmit, PreToolUse, PostToolUse, Stop). Its most distinctive primitive is the wiggum skill: a spec-driven autonomous implementation loop that enforces pre-commit quality gates (test/lint/changelog) via a .wiggum-session file and a git pre-commit hook, structurally preventing commits without passing all gates. A skill-eval.js hook evaluates every user prompt against skill descriptions to auto-trigger the right skill. The validate-bash.sh PreToolUse hook blocks fork bombs, disk-format commands, and piped shell execution before they run. An auto-format.sh PostToolUse hook auto-formats after every Edit/Write.

differs_from_seeds: Closest to superpowers (skills-only behavioral framework, Ralph Loop philosophy) but adds heavy hook enforcement. Unlike superpowers, the Wiggum Loop enforces git pre-commit quality gates at the OS level via a .wiggum-session state file — meaning the agent cannot commit without passing tests even if it tries. The skill-eval.js UserPromptSubmit hook is a self-routing mechanism not found in any seed. Compared to spec-driver (24 skills, 2 hooks), zbruhnke prioritizes hooks over skill count and ships explicit subagents for delegation.

01

Overview

zbruhnke/claude-code-starter — Overview

Origin

Personal Claude Code starter by a single developer (1 contributor, zbruhnke). 15 GitHub stars. Default branch: main. Last commit: 2026-01-15. Shell-based (shell language classification). MIT license.

Philosophy

The CLAUDE.md captures the anti-"vibe coding" stance explicitly:

"Before committing changes, always: 1. Show the user what files are being committed. 2. Briefly explain the key changes. 3. Ask for confirmation before proceeding. This prevents 'vibe coding' — blindly committing AI-generated changes without review."

The Wiggum skill's motto encapsulates the implementation philosophy:

"Iteration beats perfection. Keep going until it's truly done."

Core principles:

  1. Plan before implementing — enter plan mode, get user approval before writing code
  2. Iterate until complete — each cycle reads its own git commits to see what changed
  3. No stubs, ever — writing // TODO means not done
  4. Document as you go — documentation and changelog entries are part of the work
  5. Commit incrementally — each completed chunk gets its own atomic commit

Wiggum Mechanism

The "Wiggum Loop" is named after the Ralph Wiggum technique (autonomous loop until complete). The skill coordinates with specialized subagents (researcher, code-reviewer, test-writer, documentation-writer, adr-writer, code-simplifier) and enforces quality through:

  • A .wiggum-session state file created by hooks at session start
  • A git pre-commit hook (wiggum-precommit.sh) that reads .wiggum-session and blocks commits if CHANGELOG is empty, tests fail, or lint fails

Security Philosophy

The security-model.md rule is explicit about limitations:

"Important: This is a safety net, not a security boundary. A sophisticated user can bypass these protections."

Runtime validation via validate-bash.sh is the real enforcement layer, not settings.json deny rules (which are "coarse heuristics only").

02

Architecture

zbruhnke/claude-code-starter — Architecture

Distribution

Standalone GitHub repository. Install via git clone + ./setup.sh.

Install Method

git clone https://github.com/zbruhnke/claude-code-starter
cd claude-code-starter
./setup.sh

Directory Tree

zbruhnke/claude-code-starter/
├── .claude/
│   ├── agents/              (6 subagents)
│   │   ├── adr-writer.md
│   │   ├── code-reviewer.md
│   │   ├── code-simplifier.md
│   │   ├── documentation-writer.md
│   │   ├── researcher.md
│   │   └── test-writer.md
│   ├── commands/            (3 slash commands)
│   │   ├── onboard.md
│   │   ├── pr-summary.md
│   │   └── status.md
│   ├── hooks/               (9 shell/JS scripts)
│   │   ├── README.md
│   │   ├── auto-format.sh          (PostToolUse: Edit|Write)
│   │   ├── pre-commit-review.sh
│   │   ├── skill-eval-wrapper.sh   (UserPromptSubmit)
│   │   ├── skill-eval.js           (skill matching logic)
│   │   ├── skill-rules.json        (skill trigger rules)
│   │   ├── test-validate-bash.sh
│   │   ├── validate-bash.sh        (PreToolUse: Bash)
│   │   ├── wiggum-precommit.sh     (git pre-commit hook)
│   │   ├── wiggum-session-end.sh   (Stop)
│   │   └── wiggum-session-start.sh (PreToolUse: Skill)
│   ├── rules/
│   │   └── security-model.md
│   ├── scripts/
│   ├── skills/              (11 skills)
│   │   ├── changelog-writer/
│   │   ├── code-review/
│   │   ├── explain-code/
│   │   ├── generate-tests/
│   │   ├── install-precommit/
│   │   ├── refactor-code/
│   │   ├── refresh-claude/
│   │   ├── release-checklist/
│   │   ├── review-mr/
│   │   ├── risk-register/
│   │   └── wiggum/             (autonomous implementation loop)
│   ├── core-settings.json
│   ├── settings.json           (hook registrations)
│   └── settings.local.json.example
├── .mcp.json.example
├── CLAUDE.md
├── bin/
│   └── claude-code-starter     (thin setup helper binary)
├── docs/
├── install.sh
├── setup.sh
└── stacks/                     (language-specific stacks)

Required Runtime

  • bash
  • node.js (for skill-eval.js)
  • Claude Code

Target AI Tools

Claude Code (primary). settings.json includes no AI-tool-specific config beyond Claude Code hooks.

Config Files

  • .claude/settings.json — permissions allow/deny lists + 4 hook events
  • .claude/settings.local.json.example — machine-local template
  • .mcp.json.example — MCP config template
03

Components

zbruhnke/claude-code-starter — Components

Slash Commands (3)

  • onboard.md — quick project orientation and overview for new sessions
  • pr-summary.md — generates PR description from current diff
  • status.md — checks git state and recent activity

Skills (11)

  • changelog-writer/ — maintains CHANGELOG.md with categorized entries
  • code-review/ — reviews code changes for quality and security
  • explain-code/ — explains how code works to the developer
  • generate-tests/ — generates comprehensive test suites
  • install-precommit/ — installs the git pre-commit review hook
  • refactor-code/ — improves code without changing behavior
  • refresh-claude/ — updates CLAUDE.md with recent project changes
  • release-checklist/ — final quality gate before shipping
  • review-mr/ — reviews merge/pull requests
  • risk-register/ — documents risks for auth/data/migration changes
  • wiggum/ — autonomous implementation loop from spec/PRD; coordinates all other agents; enforces quality gates via .wiggum-session file

Subagents (6)

  • adr-writer.md — creates Architecture Decision Records for significant decisions
  • code-reviewer.md — thorough code review including security checklist
  • code-simplifier.md — simplifies code for clarity and maintainability
  • documentation-writer.md — generates and updates documentation for code changes
  • researcher.md — explore and understand code (read-only)
  • test-writer.md — generates comprehensive tests

Hooks (9 scripts, 4 events)

UserPromptSubmit

  • skill-eval-wrapper.shskill-eval.js — evaluates user prompt against skill-rules.json; auto-triggers matching skill (5-second timeout)

PreToolUse

  • validate-bash.sh (matcher: Bash) — runtime bash validation; blocks: rm -rf /, fork bombs (:(){} patterns), disk formatting (mkfs, fdisk), direct disk writes (dd if=...), piped shell execution (curl | bash, wget | sh); warns on: sudo, force flags, eval
  • wiggum-session-start.sh (matcher: Skill) — creates .wiggum-session state file when wiggum skill is invoked

PostToolUse

  • auto-format.sh (matcher: Edit|Write) — auto-formats code after every file edit (30-second timeout)
  • pre-commit-review.sh (matcher: Bash, git commit) — triggers pre-commit review

Stop

  • wiggum-session-end.sh — cleans up .wiggum-session file at session end

Git Pre-Commit Hook (installed separately)

  • wiggum-precommit.sh — installed to .git/hooks/pre-commit; reads .wiggum-session; blocks commits if CHANGELOG empty, tests fail, or lint fails

Skill Evaluation System

skill-rules.json + skill-eval.js + skill-eval-wrapper.sh:

  • Every user prompt passes through skill-eval-wrapper.sh at UserPromptSubmit
  • skill-eval.js loads skill-rules.json and matches prompt text against skill trigger patterns
  • On match: injects skill invocation into the session context
  • This is an automated skill-routing system at the prompt level

Rules

  • security-model.md — documents what is/isn't protected; explicit about limitations: "safety net, not a security boundary"

Permissions (settings.json)

Allow: git operations (status, diff, log, branch, checkout, stash, add, commit), ls, pwd, which, echo, mkdir Deny: Read/Edit/Write on .env, .env.*, /secrets/, rm -rf, rm -r, sudo, chmod 777, curl|bash, wget|bash

05

Prompts

zbruhnke/claude-code-starter — Prompts

Verbatim Excerpt 1: wiggum SKILL.md — Core Philosophy

---
name: wiggum
description: Start an autonomous implementation loop from a spec or PRD.
Enters plan mode for user approval, enforces command gates
(test/lint/typecheck/build), validates dependencies, commits incrementally,
and maintains documentation and changelog. Production-ready quality gates.
tools: Read, Grep, Glob, Edit, Write, Bash, Task
user-invocable: true
---

# Wiggum Loop - Autonomous Implementation

You are initiating a **Wiggum Loop** - an autonomous implementation cycle
(inspired by the Ralph Wiggum technique) that plans first, then iterates
until the spec is fully complete with all quality gates passed.

**Your motto**: "Iteration beats perfection. Keep going until it's truly done."

## Core Philosophy

1. **Plan before implementing**: Enter plan mode first, get user approval
   before writing code.
2. **Iterate until complete**: Each cycle builds on the previous. Read your
   own git commits, see what changed, fix what's broken.
3. **Quality over speed**: Better to take 10 iterations and ship solid code
   than 2 iterations of broken code.
4. **No stubs, ever**: If you write `// TODO` or stub out a function, you're
   not done. Implement it fully.
5. **Document as you go**: Documentation and changelog entries are part of
   the work, not afterthoughts.
6. **Commit incrementally**: Each completed chunk gets its own atomic commit
   with a meaningful message.
7. **Trace every path**: Follow every code path to ensure completeness.
   Don't assume - verify.

## Input Handling

You MUST receive a clear specification. If not provided:
1. Ask: "What would you like me to build? Please provide a spec, PRD, or
   detailed requirements."
2. Clarify: "I need clear success criteria to know when I'm done."

**Never start without understanding what 'done' looks like.**

Prompting technique: Declarative behavioral constraints ("No stubs, ever"). Loop-with-exit-condition pattern. Explicit success-criteria gate before starting. Self-reading loop (reads own git commits between iterations).


Verbatim Excerpt 2: validate-bash.sh hook (security enforcement via exit codes)

#!/bin/bash
# PreToolUse Hook: Bash Command Validation
# Reads JSON from stdin, validates bash command, exits 0 (allow) or 2 (block)

COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Block fork bombs
if echo "$COMMAND" | grep -qP ':\(\)\{.*\}.*:'; then
    echo '{"decision":"block","reason":"Fork bomb pattern detected"}'
    exit 2
fi

# Block dangerous disk writes
if echo "$COMMAND" | grep -qP 'dd\s+if=.*of=/dev/'; then
    echo '{"decision":"block","reason":"Direct disk write blocked"}'
    exit 2
fi

# Block piped shell execution
if echo "$COMMAND" | grep -qP '(curl|wget).*\|\s*(ba)?sh'; then
    echo '{"decision":"block","reason":"Piped shell execution blocked"}'
    exit 2
fi

Prompting technique: Not a prompt — a runtime gate. Uses regex pattern matching and exit code 2 to block commands before they execute. Demonstrates how hooks enforce behavioral constraints at the OS level rather than relying on Claude's judgment.


Verbatim Excerpt 3: skill-eval.js — Automated skill routing

// skill-eval.js: Evaluates user prompt against skill descriptions
// Returns: { matched: bool, skill: string, confidence: number }

const skillRules = require('./skill-rules.json');
const userPrompt = process.argv[2] || '';

const matches = skillRules.skills
  .map(skill => ({
    ...skill,
    score: computeRelevanceScore(userPrompt, skill.triggers)
  }))
  .filter(s => s.score > THRESHOLD)
  .sort((a, b) => b.score - a.score);

if (matches.length > 0) {
  console.log(JSON.stringify({ matched: true, skill: matches[0].name }));
} else {
  console.log(JSON.stringify({ matched: false }));
}

Prompting technique: Programmatic prompt routing — a Node.js script runs at every UserPromptSubmit to score the user's prompt against skill triggers and inject the matching skill automatically.

09

Uniqueness

zbruhnke/claude-code-starter — Uniqueness

differs_from_seeds

Closest to superpowers (skills-based, Ralph Loop philosophy) but with substantially heavier hook enforcement. Unlike superpowers (1 hook), zbruhnke ships 9 hooks across 4 events. The wiggum skill's .wiggum-session + git pre-commit hook combination is unique in the seeds: quality gates are enforced at the OS level (git hook) not just via agent instructions. This means Claude cannot commit without passing tests even if its behavioral instructions are overridden — the enforcement lives in bash wiggum-precommit.sh, not in a CLAUDE.md rule. The skill-eval.js UserPromptSubmit auto-router (Node.js + JSON rules) is a programmatic self-routing mechanism not present in any seed framework. Compared to spec-driver (24 skills, 2 hooks), zbruhnke has fewer skills but more mechanically-enforced quality gates.

Positioning

Anti-vibe-coding toolkit with explicit commit-blocking. The framework's central value proposition is preventing the "AI commits broken code" failure mode through mechanical enforcement rather than behavioral instructions.

Observable Failure Modes

  1. .wiggum-session orphan: If the session crashes before wiggum-session-end.sh runs, .wiggum-session remains and the git pre-commit hook blocks all subsequent commits. Manual cleanup required.
  2. skill-eval false positives: The automatic skill routing (skill-eval.js) could trigger wrong skills on ambiguous prompts. No override mechanism documented.
  3. Node.js dependency: skill-eval.js requires Node.js at UserPromptSubmit time (5-second timeout). Missing Node.js silently fails skill routing.
  4. Single contributor, dormant: 15 stars, last commit 2026-01-15. Maintenance uncertain.
  5. No cross-session memory: Unlike centminmod's dual-memory, zbruhnke has no structured memory bank. Long-running projects lose context on CLAUDE.md reset.

Cross-References

  • Inspired by Ralph Wiggum technique (named in skill)
  • wiggum skill is a direct implementation of the "ralphy-openspec" pattern identified in other batches
04

Workflow

zbruhnke/claude-code-starter — Workflow

Wiggum Loop Phases

Step Phase Action Gate
0 Hook Enforcement wiggum-session-start.sh creates .wiggum-session file automatically Mechanical (hook, not Claude)
1 Pre-commit hook install cp wiggum-precommit.sh .git/hooks/pre-commit Manual (one-time setup)
2 Spec intake User provides spec/PRD; wiggum refuses to start without clear success criteria Clarification gate
3 Planning Claude enters plan mode; identifies commands from CLAUDE.md; presents plan User approval required
4 Implementation Iterates in small chunks (blast-radius awareness); reads git commits after each Automated
5 Per-chunk consulting Dispatches researcher agent when stuck Automated
6 Per-chunk ADR adr-writer documents significant decisions Automated
7 Dependency validation Checklist for new packages (license, security, maintenance) Automated checklist
8 Testing test-writer generates comprehensive coverage Automated
9 Code review code-reviewer feedback including security checklist Automated
10 Simplification code-simplifier applied for clarity Automated
11 Documentation documentation-writer updates docs Automated
12 Per-chunk command gates test, lint, typecheck per chunk Blocking (pre-commit hook)
13 Atomic commit Commit with meaningful message Blocked if gates fail
14 Session end wiggum-session-end.sh removes .wiggum-session Automated

Quality Gate Mechanics

The .wiggum-session file is the key state artifact. Its presence activates the git pre-commit hook which enforces:

  • CHANGELOG.md must be non-empty for this session
  • Tests must pass
  • Lint must pass

Without .wiggum-session, the pre-commit hook is dormant — this means normal commits outside wiggum sessions are not blocked.

Standard Workflow (non-wiggum)

  1. User types /onboard [area] → quick project orientation
  2. User prompts → skill-eval-wrapper auto-matches and triggers skills
  3. User runs /pr-summary → generates PR description
  4. User runs /status → checks git state

Approval Gates

Gate Type Timing
Pre-wiggum spec confirmation freetext-clarify Before planning
Plan mode approval yes-no After planning, before implementation
Pre-commit quality gates (test/lint/changelog) typed-confirm Before each commit
Commit confirmation yes-no Before git commit
06

Memory Context

zbruhnke/claude-code-starter — Memory & Context

Memory Type

File-based. No database, no vector store.

State Files

  • CLAUDE.md — project context and behavioral instructions
  • .wiggum-session — ephemeral session state file (created at wiggum start, deleted at session end)
  • CHANGELOG.md — maintained by changelog-writer skill; required non-empty for commits during wiggum sessions

Memory Persistence

Session-scoped for .wiggum-session. Project-scoped for CLAUDE.md and CHANGELOG.md.

No memory bank system equivalent to centminmod's CLAUDE-*.md pattern. No auto-memory, no cross-session handoff beyond CLAUDE.md itself.

Context Loading

The skill-eval-wrapper.sh UserPromptSubmit hook loads skill context automatically when a prompt matches a skill trigger. This is the primary context injection mechanism.

Compaction Handling

The refresh-claude skill exists to update CLAUDE.md with recent changes. This is a manual invocation, not an automatic hook.

Cross-Session Handoff

Limited — CLAUDE.md is the only persistent state. No structured memory bank.

CLAUDE.md Maintenance

The refresh-claude skill: user invokes /refresh-claude → Claude updates CLAUDE.md to reflect recent code changes. This is one-directional (code → memory).

07

Orchestration

zbruhnke/claude-code-starter — Orchestration

Multi-Agent Support

Yes — 6 named subagents dispatched by the wiggum skill.

Orchestration Pattern

sequential — wiggum coordinates agents in a defined sequence: researcher → test-writer → code-reviewer → code-simplifier → documentation-writer → adr-writer. Not parallel.

Wiggum Agent Coordination

The wiggum skill dispatches agents via the Task tool:

  1. researcher — when stuck (read-only exploration)
  2. adr-writer — for significant decisions
  3. test-writer — for test coverage
  4. code-reviewer — for quality/security feedback
  5. code-simplifier — for clarity improvement
  6. documentation-writer — for docs updates

Multi-Model Usage

No — single model (Claude Code). No multi-model routing.

Isolation Mechanism

None. No git worktrees, no container isolation. In-place file editing.

Execution Mode

Interactive-loop during wiggum sessions. One-shot for individual commands (onboard, pr-summary, status).

Quality Gate Enforcement

The .wiggum-session state file + git pre-commit hook enforces quality at the OS level:

  • File present → pre-commit hook active → tests/lint/changelog required before commits
  • File absent → hook dormant → normal commits allowed

This is the most mechanically-enforced quality gate pattern in the batch — Claude cannot bypass the git hook even if it "decides" to commit without testing.

Consensus Mechanism

None.

Crash Recovery

None explicit. .wiggum-session may remain if session crashes without cleanup — wiggum-session-end.sh would need to be run manually.

08

Ui Cli Surface

zbruhnke/claude-code-starter — UI / CLI Surface

Dedicated CLI Binary

Yesbin/claude-code-starter binary (thin wrapper, installs the starter config via setup.sh). Single binary, no subcommands exposed to users.

Local Web Dashboard

No — no web UI.

IDE Integration

Claude Code only. No mention of other IDEs.

Setup Script

setup.sh — the primary install mechanism. install.sh also exists for one-liner installation.

Homebrew

homebrew/ directory exists — suggests Homebrew formula for macOS installation.

Observability

  • Pre-commit blocking output — when wiggum pre-commit hook fires, outputs failure reason to terminal
  • skill-eval.js output — JSON result of skill matching written to stdout during UserPromptSubmit

Git Automation

No automatic commits — each commit is controlled. Quality gates BLOCK commits until conditions are met. This is the inverse of automation: the framework prevents automatic commits rather than enabling them.

Stacks Support

stacks/ directory exists — language-specific configuration stacks (contents not explored in depth). Likely language-specific rule files.

Docs

docs/ directory with installation guides, stack documentation.

Related frameworks

same archetype · same primary tool · same memory type

Claude-Flow / Ruflo ★ 55k

Eliminates single-agent context limits and sequential bottlenecks by orchestrating fault-tolerant swarms of specialized AI agents…

Hermes Agent (NousResearch) ★ 168k

Self-improving personal AI agent with closed learning loop, 7 terminal backends, and messaging gateway — not tied to any AI…

OpenCode ★ 165k

Terminal-first AI coding agent with multi-model routing, native desktop app, and a typed .opencode/ configuration system for…

OpenHands ★ 75k

Open-source AI software development platform (open-source Devin alternative) with Docker sandbox isolation, 77.6% SWE-bench…

DeerFlow ★ 70k

Long-horizon superagent that researches, codes, and creates by orchestrating parallel sub-agents with isolated contexts in Docker…

oh-my-openagent (omo) ★ 60k

Multi-provider AI agent orchestration for OpenCode: escape vendor lock-in by routing Sisyphus (Claude/Kimi/GLM) and Hephaestus…