claude-code-forge

Production-grade workflow enforcement for Claude Code.
Hooks, sprint gates, token budgets, and session continuity — in one drop-in kit.

Most Claude Code setups are just a CLAUDE.md file with rules. Rules without enforcement get ignored by session 3.
This kit adds three enforcement layers, a sprint gate system, slash commands, and token optimization — so your AI workflow stays disciplined on any project.

---

What makes this different

Feature	Most starter kits	claude-code-forge
CLAUDE.md template	✅	✅
Slash commands	Sometimes	✅ /commit /checkpoint /sprint-end /new-sprint
PostToolUse enforcement hook	❌	✅ Fires after every Write/Edit
Git pre-commit hard gate	❌	✅ Blocks commit if sprint gate missing
Sprint gate system (4D)	❌	✅ Define → Detail → Direct → Dialogue
Session continuity (MASTER_STATE)	❌	✅ Persistent truth between sessions
Token budget management	❌	✅ RTK + AUTOCOMPACT 50% + thinking cap
Language variants	Rarely	✅ Python, TypeScript, generic
One-command setup	Rarely	✅ bash setup.sh

---

Quick start

git clone https://github.com/chrisdev1187/claude-code-forge
cd claude-code-forge
bash setup.sh

Prompts for project name, stack, and hardware. Everything else is automatic.

---

What's in the box

setup.sh                      ← one-command project initializer

claude-global/                ← copy once to ~/.claude/ (all projects)
  settings.json               ← AUTOCOMPACT 50%, thinking cap, hooks wired
  hooks/
    post-write-gate.sh        ← PostToolUse hook: TDD + gate reminders after every write

project-template/             ← scaffolded per new project by setup.sh
  CLAUDE.md                   ← universal project law file (< 150 lines)
  CLAUDE.python.md            ← Python/pytest/pydantic variant
  CLAUDE.typescript.md        ← TypeScript/Node/vitest variant
  .gitignore                  ← sane defaults (secrets, large JSON, local overrides)
  .claude/
    commands/
      commit.md               ← /commit  — structured commit with security check
      checkpoint.md           ← /checkpoint — mid-session save + tag
      sprint-end.md           ← /sprint-end — close sprint, verify criteria, merge
      new-sprint.md           ← /new-sprint — create 4D gate for next sprint
    settings.local.json       ← project-level overrides (NOT committed to git)
  git-hooks/
    pre-commit                ← HARD GATE: blocks commit if sprint gate file missing
  docs/
    MASTER_STATE.md           ← authoritative project state (update every session end)
    SESSION_LOG.md            ← running session log
    GOLDEN_RULE_LOG.md        ← research-before-build log
    sprints/
      CURRENT_SPRINT.md       ← current sprint number
      sprint-1-gate.md        ← 4D gate template (D1 Define / D2 Detail / D3 Direct / D4 Dialogue)
  memory/
    MEMORY.md                 ← memory index (lives in ~/.claude/projects/[hash]/memory/)
    project_context.md        ← typed project memory template

---

How enforcement works

Claude Code sessions are stateless. Rules in CLAUDE.md are read once and forgotten under context pressure. This kit solves that with three layers:

Layer 1 — CLAUDE.md rules         always in context
Layer 2 — PostToolUse hook        fires after every Write/Edit → injects TDD + gate reminder
Layer 3 — git pre-commit hook     BLOCKS commit if sprint gate file is missing

No single point of failure. Layer 2 catches what Layer 1 misses. Layer 3 catches what Layer 2 misses.

Note on PreToolUse: GitHub issues #13744 and #24327 confirm that exit code 2 in PreToolUse hooks does NOT block Write/Edit tool operations — only Bash. This kit uses PostToolUse + pre-commit instead, which work reliably.

---

The 4D Gate system

Before any sprint begins, you fill out a gate file (docs/sprints/sprint-N-gate.md):

Gate	Question
D1 — Define	Exact problem? What does "done" look like?
D2 — Detail	All dependencies? Edge cases? Token budget?
D3 — Direct	Step-by-step sequence? Success criterion per step?
D4 — Dialogue	What could go wrong? Gaps? Human review checkpoint?

All 4 green = sprint is open. Any red = stop.

The git pre-commit hook reads docs/sprints/CURRENT_SPRINT.md and blocks every commit until docs/sprints/sprint-N-gate.md exists. No gate file = no commits.

---

Slash commands

Use these inside Claude Code by typing /command-name:

Command	What it does
/commit	Structured commit: reviews diff, picks type, runs security check
/checkpoint	Mid-session save: commit + optional git tag + MASTER_STATE update
/sprint-end	Close sprint: verify D1 criteria, tag, merge to dev
/new-sprint	Open next sprint: scaffold gate file, update CURRENT_SPRINT.md

---

Token optimization

Mechanism	What it does	Savings
RTK (Rust Token Killer)	Filters noisy CLI output before it enters context	52–99% per command
AUTOCOMPACT_PCT=50	Compresses context at 50% full instead of default ~80%	~40% context headroom saved
MAX_THINKING_TOKENS=10000	Caps extended thinking budget	Prevents single responses consuming context
Session ritual	START reads MASTER_STATE — no re-discovery every session	Qualitative

RTK usage: prefix every Bash call — rtk git status, rtk tsc, rtk pnpm install

---

Session ritual

Every session, without exception:

START

1. Read docs/MASTER_STATE.md
2. Read last entry in docs/SESSION_LOG.md
3. rtk git log --oneline -5
4. rtk git checkout -b session/YYYY-MM-DD
5. Set ONE goal for this session

END

1. rtk git commit -m "session: [what was done]"
2. rtk git tag "verified-[name]" if component passed test loop
3. Update docs/MASTER_STATE.md
4. Update docs/SESSION_LOG.md
5. rtk git checkout dev && rtk git merge session/YYYY-MM-DD

---

CLAUDE.md variants

Rename the variant that fits your project to CLAUDE.md:

File	Use for
CLAUDE.md	Any project (generic, n8n/agent workflow centric)
CLAUDE.python.md	Python (pytest TDD, pydantic, venv, logging rules)
CLAUDE.typescript.md	TypeScript/Node/Next.js (vitest TDD, Zod, pnpm, strict)

All variants are under 150 lines. Domain knowledge lives in skills and docs, not in CLAUDE.md.

---

Setup in detail

Global (once per machine)

# Copy settings and hook to Claude's global config directory
cp claude-global/settings.json ~/.claude/settings.json

mkdir -p ~/.claude/hooks
cp claude-global/hooks/post-write-gate.sh ~/.claude/hooks/post-write-gate.sh
chmod +x ~/.claude/hooks/post-write-gate.sh

On Windows (Git Bash / WSL): replace ~/.claude with /c/Users/YOUR_USERNAME/.claude

Per project (or just run setup.sh)

cd /path/to/your-project
git init

# Copy template files
cp -r path/to/claude-code-forge/project-template/. .

# Install git hook
cp git-hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

# Install memory (find your project hash first by opening Claude Code once)
cp -r memory ~/.claude/projects/YOUR_PROJECT_HASH/memory

Edit your CLAUDE.md

Replace all [PLACEHOLDERS]:

• [PROJECT NAME] — your project name
• [your stack] — e.g., Claude Code + Node + n8n
• [OS] | [RAM] | [constraints] — e.g., Windows 11 | 8GB RAM | no GPU

Complete your Sprint 1 gate

Open docs/sprints/sprint-1-gate.md and fill in D1–D4 before writing any code.

---

Requirements

• Claude Code — CLI or desktop app
• git
• bash (WSL2 or Git Bash on Windows, native on macOS/Linux)
• RTK — npm install -g rtk
• Python (for PostToolUse hook — python on Windows, python3 on macOS/Linux)

---

Credits

This kit was built on top of community work. Everything worth knowing was found, not invented:

Project	What we learned / borrowed
cloudnative-co/claude-code-starter-kit	One-command bash setup pattern, .claude/commands/ directory structure
TheDecipherist/claude-code-mastery-project-starter-kit	Slash command set design (/commit, /progress, /sprint-end, /new-sprint)
abhishekray07/claude-md-templates	Language-specific CLAUDE.md variant pattern (Python, TypeScript, generic)
VoltAgent/awesome-agent-skills	Agent skill taxonomy, research-analyst system prompt (bias detection + triangulation rule borrowed)
rohitg00/awesome-claude-code-toolkit	Community practices survey, agent categories
darnfish/rtk (Rust Token Killer)	Token filtering for CLI output — the single biggest context saver
Anthropic Claude Code docs	CLAUDE.md < 200 lines best practice, .claude/ project directory pattern, hooks system

What's original to this kit:

• Three-layer enforcement architecture (CLAUDE.md + PostToolUse hook + git pre-commit)
• 4D Gate system (Define / Detail / Direct / Dialogue) applied to sprint planning
• PostToolUse gate feedback injection pattern (no public examples found — novel as of April 2026)
• MASTER_STATE + SESSION_LOG continuity system
• Token budget as a first-class architectural constraint

---

Contributing

Issues and PRs welcome. If you add a language variant (Go, Rust, PHP, etc.), follow the pattern in CLAUDE.python.md — under 150 lines, TDD-first, immutable patterns, env var secrets.

---

License

MIT — use it, fork it, ship it.