claude-code-playbook

Battle-tested patterns from 900+ sessions across production TypeScript projects.
Skills, hooks, templates, multi-agent orchestration, and hard-won lessons — all in one place.

The Core Loop

Every successful Claude Code session follows the same rhythm. Break this loop and you'll turn a 5-minute task into a 90-minute slog.

graph LR
    A(["Request"]) --> B["Implement"]
    B --> C{"Verify"}
    C -->|"pass"| D(["Close"])
    C -.->|"fail"| B
    D -->|"new task"| A

    classDef info fill:#4EA7FC,stroke:#2E86D9,color:#0B1220
    classDef primary fill:#5E6AD2,stroke:#4653B8,color:#FFFFFF
    classDef warn fill:#F0BF00,stroke:#B89200,color:#221A00
    classDef success fill:#27A644,stroke:#1F8737,color:#FFFFFF
    class A info
    class B primary
    class C warn
    class D success

The cardinal rule: Each step has a clear boundary. Don't blur them. Plan in one session, execute in another. Verify with real tests, not code inspection.

Why This Exists

Most Claude Code guides tell you how to install it. This one tells you how to use it well.

After months of daily production use — debugging at 2am, shipping features across 30+ file changes, managing fleets of sub-agents, and learning the hard way what breaks — we distilled everything into this playbook.

What's New (October 20 sync)

Second sync of the live setup since the 5 Oct refresh. Everything is scrubbed the same way; the
Setup Inventory lists what was left out.

• Seven new guard hooks: worktree-gate.sh (one file per session in a shared checkout, then a worktree), explainer-gate.py (explain a folder before first editing it), restate-gate.sh (say back the ask before the first edit), test-gate.py (run the code before stopping), push-gate.py (one nudge for commits left unpushed), goal-pin.py (keep the session's goal and detour in view) and voice-queue.sh. Shared helpers in hooks/lib/. Wiring in examples/settings.hooks.json.
• Updated hooks: auto-mode.py, register-gate.py, verify-gate.sh, firewall.sh (heredoc-safe), context-threshold-nudge.sh, run-referee-guard.sh, daydream.sh, daydream-surface.sh, answer-shape-nudge.sh.
• New skills: autoclear, overnight, recap, clean-code, clean-code-score. Refreshed: anti-ai-prose (now with a scorer), myinsights, pr-review, prdforge, done, reboot.
• Incident replay: scripts/claude-ops/incident-replay.py plus a daily launchd job scores the code reviewer against past misses. A 14th background job.
• Ops scripts and tests: autoclear.sh, tmux-send-line.sh, session-rotate.sh, run-referee.py, graveyard-sweep.py, restore-sessions.sh, hooks-smoke-test.sh and a new scripts/claude-ops/tests/ folder.
• Third party, linked not copied: anatomy (isometric SVG figures).

What's New (October 2026)

The repo now mirrors the author's live setup, sanitised. Start with the
Setup Inventory: every layer, what is included, and what was left out and why.

• RTK: a Bash hook that trims command output before it reaches context. 80% fewer output tokens over about 240,000 commands.
• Guard Hooks: recorder plus gate pairs that block an edit until the right check has happened. Rules that were ignored as prose, enforced as hooks.
• Session Lifecycle: per-turn handoffs, /reboot, automatic rotation and an out-of-band referee for runaway sessions.
• Background Jobs: 14 launchd jobs, scripts in scripts/claude-ops/.
• Superpowers as the default process layer, the rules layout (CLAUDE.md plus five @-imports), 9 role agents and commands.

Architecture Overview

How all the pieces fit together in a well-configured Claude Code environment:

graph TB
    subgraph "Your Project"
        CM["CLAUDE.md<br/><em>Rules & conventions</em>"]
        SK["Skills/<br/><em>Custom /commands</em>"]
        HK["Hooks/<br/><em>Auto-checks</em>"]
    end

    subgraph "Claude Code Session"
        CC["Claude Code"]
        CC -->|"reads at start"| CM
        CC -->|"invokes"| SK
        CC -->|"triggers"| HK
    end

    subgraph "Plugins"
        SP["superpowers<br/><em>Process discipline</em>"]
        CX["Codex<br/><em>Second-model review</em>"]
        C7["Context7<br/><em>Documentation</em>"]
    end

    subgraph "Harness"
        RTK["RTK<br/><em>Trims shell output</em>"]
        GATE["Guard hooks<br/><em>Recorder + gate pairs</em>"]
        OPS["launchd jobs<br/><em>Referee, rotation, sweeps</em>"]
    end

    subgraph "MCP Servers"
        BR["Browser<br/><em>Screenshots & testing</em>"]
        DB["Database<br/><em>Queries & migrations</em>"]
        GH["GitHub CLI<br/><em>PRs & issues</em>"]
    end

    CC --> SP
    CC --> CX
    HK --> GATE
    CC -->|"every Bash call"| RTK
    OPS -.->|"watches"| CC
    CC --> C7
    CC --> BR
    CC --> DB
    CC --> GH

    classDef primary fill:#5E6AD2,stroke:#4653B8,color:#FFFFFF
    classDef info fill:#4EA7FC,stroke:#2E86D9,color:#0B1220
    classDef success fill:#27A644,stroke:#1F8737,color:#FFFFFF
    classDef danger fill:#EB5757,stroke:#C43D3D,color:#FFFFFF
    classDef warn fill:#F0BF00,stroke:#B89200,color:#221A00
    classDef dark fill:#232326,stroke:#3E3E44,color:#F7F8F8
    class CC primary
    class CM success
    class SK info
    class HK danger
    class SP,CX,C7 warn
    class RTK,GATE,OPS danger
    class BR,DB,GH dark

What's Inside

Quick Start

One-line install — installs all skills, hooks, and a default template automatically:

curl -sL https://raw.githubusercontent.com/ao92265/claude-code-playbook/main/scripts/install.sh | bash

Choose a specific stack template:

curl -sL .../install.sh | bash -s -- --all --template react
# Options: general, react, node, python, fullstack, go, rust, mobile, devops, java, csharp

Or run interactively to pick and choose:

git clone https://github.com/ao92265/claude-code-playbook.git && ./claude-code-playbook/scripts/install.sh

Or set up manually:

git clone https://github.com/ao92265/claude-code-playbook.git
cp claude-code-playbook/templates/CLAUDE.md your-project/CLAUDE.md

# Global (all projects)
cp -r claude-code-playbook/skills/check-env ~/.claude/skills/

# Project-local
cp -r claude-code-playbook/skills/deploy your-project/.claude/skills/

cp claude-code-playbook/hooks/*.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/*.sh

> /check-env        # Pre-flight checks
> /deploy           # Safe deployment
> /test-first       # TDD workflow
> /security-check   # OWASP scan
> /morning          # Cross-terminal briefing

Then dive into the docs — the Complete Guide hub maps every topic to its focused page:

Plugin Ecosystem

The playbook covers two major orchestration plugins in depth — see BMad Autonomous Development and Multi-Model Orchestration:

graph TB
    YOU["You"] --> BM["BMad Master"]
    BM --> AR["Architect<br/><em>Design & scalability</em>"]
    BM --> DEV["Developer<br/><em>Implementation</em>"]
    BM --> QA["QA Engineer<br/><em>Test coverage</em>"]
    BM --> SEC["Security Auditor<br/><em>Vulnerabilities</em>"]
    BM --> PM["Product Manager<br/><em>Scope & impact</em>"]

    classDef primary fill:#5E6AD2,stroke:#4653B8,color:#FFFFFF
    classDef info fill:#4EA7FC,stroke:#2E86D9,color:#0B1220
    classDef success fill:#27A644,stroke:#1F8737,color:#FFFFFF
    classDef warn fill:#F0BF00,stroke:#B89200,color:#221A00
    classDef danger fill:#EB5757,stroke:#C43D3D,color:#FFFFFF
    classDef dark fill:#232326,stroke:#3E3E44,color:#F7F8F8
    class YOU info
    class BM warn
    class AR primary
    class DEV success
    class QA warn
    class SEC danger
    class PM dark

graph LR
    subgraph "Execution Modes"
        AP["Autopilot<br/><em>Full lifecycle</em>"]
        UW["Ultrawork<br/><em>Max parallelism</em>"]
        RL["Ralph<br/><em>Until verified</em>"]
        TD["TDD<br/><em>Tests first</em>"]
    end

    subgraph "Model Routing"
        H["Haiku<br/><em>Simple tasks</em>"]
        S["Sonnet<br/><em>Standard work</em>"]
        O["Opus<br/><em>Complex reasoning</em>"]
    end

    AP --> H
    AP --> S
    AP --> O
    UW --> S
    RL --> S
    RL --> O

    classDef primary fill:#5E6AD2,stroke:#4653B8,color:#FFFFFF
    classDef info fill:#4EA7FC,stroke:#2E86D9,color:#0B1220
    classDef success fill:#27A644,stroke:#1F8737,color:#FFFFFF
    classDef warn fill:#F0BF00,stroke:#B89200,color:#221A00
    classDef dark fill:#232326,stroke:#3E3E44,color:#F7F8F8
    class AP primary
    class UW info
    class RL success
    class TD warn
    class H dark
    class S info
    class O primary

Skills Reference

Every skill is a drop-in /command that teaches Claude a specific workflow. All 52 are listed here — copy the ones you need.

Key Patterns

These are the highest-impact patterns from the playbook:

graph LR
    A["Fresh<br/><em>100%</em>"] --> B["Tasks<br/><em>90%</em>"]
    B --> C["Debug<br/><em>70%</em>"]
    C --> D["Failures<br/><em>50%</em>"]
    D --> E["Dumb<br/><em>30%</em>"]

    F["/clear"] --> A

    classDef success fill:#27A644,stroke:#1F8737,color:#FFFFFF
    classDef teal fill:#00B8CC,stroke:#00919F,color:#04252A
    classDef warn fill:#F0BF00,stroke:#B89200,color:#221A00
    classDef orange fill:#FC7840,stroke:#D9581F,color:#2A1204
    classDef danger fill:#EB5757,stroke:#C43D3D,color:#FFFFFF
    classDef primary fill:#5E6AD2,stroke:#4653B8,color:#FFFFFF
    class A success
    class B teal
    class C warn
    class D orange
    class E danger
    class F primary

graph LR
    subgraph "Session 1: Plan"
        P1["Discuss"] --> P2["Settle"] --> P3["Save"]
    end

    subgraph "Session 2: Execute"
        E1["Read"] --> E2["Build"] --> E3["Ship"]
    end

    P3 -->|"New session"| E1

    classDef primary fill:#5E6AD2,stroke:#4653B8,color:#FFFFFF
    classDef success fill:#27A644,stroke:#1F8737,color:#FFFFFF
    class P1,P2,P3 primary
    class E1,E2,E3 success

graph TB
    P["Parent"] --> W1["Worker 1<br/><em>Own worktree</em>"]
    P --> W2["Worker 2<br/><em>Own worktree</em>"]
    P --> W3["Worker 3<br/><em>Own worktree</em>"]

    classDef primary fill:#5E6AD2,stroke:#4653B8,color:#FFFFFF
    classDef success fill:#27A644,stroke:#1F8737,color:#FFFFFF
    class P primary
    class W1,W2,W3 success

Continuous Development — When the Loop Replaces the Ticket Queue

The end-state this playbook builds towards: ACT (Autonomous Continuous Development) — an AI loop doing the day-to-day work of a Software Developer (Level 3) — scoped features, bug fixes, tests, PRs — continuously, with a human in the loop at the merge boundary. The human sets objectives and reviews merges; the loop does the L3 work in between.

What makes it survivable is the gate ladder — quality enforcement ordered by what it costs and what it outlives:

Token limits are a scheduled failure mode for long loops, not a surprise. The playbook for it: continuous state handoffs so any fresh session resumes cold, cross-vendor fallback for reviews and grunt work, automated retry with backoff, budgeted stretches with a canary marker for context rot — and the one forbidden move: never bypass a gate to keep moving. Pause and queue instead.

→ Read the full guide: Continuous Development (ACT) — the operating model, the token-outage playbook in full, and the hard-won safety lessons (stage isolation, concurrency caps, sacrificial-repo certification).

Documentation

76 docs organised into sections on the docs site — highlights by section:

CLAUDE.md Templates

11 templates for different stacks — copy the one that fits your project:

Hooks

Hooks are deterministic guard rails — they fire on tool events whether or not the model remembers to check.

%%{init: {"themeVariables": {"actorBkg": "#5E6AD2", "actorTextColor": "#FFFFFF", "actorBorder": "#4653B8", "activationBkgColor": "#F0BF00"}}}%%
sequenceDiagram
    participant You
    participant Claude
    participant Hook
    participant TypeScript

    You->>Claude: "Fix the auth bug"
    Claude->>Claude: Edits user-service.ts
    Claude->>Hook: PostToolUse trigger
    Hook->>TypeScript: tsc --noEmit
    TypeScript-->>Hook: 2 type errors found
    Hook-->>Claude: Exit code 2 (block)
    Claude->>Claude: Fixes type errors
    Claude->>Hook: PostToolUse trigger
    Hook->>TypeScript: tsc --noEmit
    TypeScript-->>Hook: Clean
    Hook-->>Claude: Exit code 0 (pass)
    Claude-->>You: "Bug fixed, types clean"

85 hook scripts included. 11 are auto-wired when you install the playbook as a plugin (via hooks/hooks.json); the rest are opt-in via your settings.json.

Auto-wired (11): session-start-check.sh (environment validation) · pre-commit-guard.sh (debug statements) · env-guard.sh (secrets) · firewall.sh (dangerous command blocker) · protect-paths.sh (protected file guard) · ts-check.sh (type errors) · lint-check.sh (ESLint) · format-check.sh (Prettier) · build-check.sh (OOM-safe builds) · daydream.sh (idle memory → ideas → quick PRD) · daydream-surface.sh (surface daydreams at session start)

Opt-in (19): verify-gate.sh (Stop-blocking verify gate with baseline diffing) · audit-log.sh (raw-prompt compliance log) · secret-scanner.py (pattern-based secret detection) · codex-prepush-review.sh (second-model review on push) · pre-commit-verify.sh (typecheck before commit) · commit-message-check.sh (conventional commits) · tdd-gate.sh (warn on source edits without a failing test) · plan-gate.sh (warn on edits without a plan) · require-agent-model.sh (block subagent spawns without an explicit model) · research-only-guard.sh (enforce analysis-only mode) · test-on-save.sh (auto-run relevant tests) · auto-simplify.sh (simplification pass on commit) · stop-handoff.sh (write a "where I left off" handoff) · sessionstart-handoff.sh (re-inject the last handoff) · precompact-handoff.sh (preserve state before compaction) · notify-local-tts.sh (TTS notifications) · play-tts.sh (TTS wrapper) · dotnet-build.sh (dotnet build after C# edits; install with the guard; see .NET Teams) · dotnet-msbuild-guard.sh (deny Edit/Write to MSBuild and NuGet files and obj/ bin/)

See hooks/README.md for setup and config/hooks-example.json for an example configuration wiring 9 of the hook scripts.

Production Metrics

These numbers are from a real production project that used the patterns in this playbook:

graph LR
    subgraph "Before"
        B1["Features: 2-3 weeks"]
        B2["Bug fixes: 3-5 days"]
        B3["Tests: ~200"]
    end

    subgraph "After"
        A1["Features: 4-7 hours"]
        A2["Bug fixes: 30-45 min"]
        A3["Tests: 10,000+"]
    end

    B1 -.->|"85% faster"| A1
    B2 -.->|"99% faster"| A2
    B3 -.->|"50x more"| A3

    classDef danger fill:#EB5757,stroke:#C43D3D,color:#FFFFFF
    classDef success fill:#27A644,stroke:#1F8737,color:#FFFFFF
    class B1,B2,B3 danger
    class A1,A2,A3 success

Examples

Real session transcripts annotated with explanations of what's happening and why each decision matters.

Onboarding

New to Claude Code? Hand your team the onboarding package — a structured 2-hour program:

Also see: Getting Started | Team Setup | Adoption Playbook | Case Studies | Enterprise Governance | GitHub Actions

Contributing

Found a useful pattern? Built a skill that saved you hours? PRs welcome.

See CONTRIBUTING.md for detailed guidelines on contributing skills, hooks, templates, and documentation.