The Systems Thinker's Claude Code Governance Platform
A batteries-included governance layer for Claude Code. Four specialized agents handle planning, implementation, verification, and git operations. Shell scripts enforce the rules at every lifecycle event, regardless of context window pressure.
Instructions guide. Hooks enforce.
Platform at a Glance
~/.claude/
├── hooks/ # Hook scripts and shared libraries
├── agents/ # 4 agent definitions (Planner, Implementer, Tester, Guardian)
├── skills/ # 11 skills across 3 domains
├── commands/ # Slash commands (/compact, /backlog)
├── scripts/ # 7 utility scripts + lib/
├── observatory/ # Self-improving trace analysis
├── traces/ # Agent execution archive
├── tests/ # Hook validation suite
├── ARCHITECTURE.md # Definitive technical reference (18 sections)
├── CLAUDE.md # Session instructions (loaded every time)
└── settings.json # Hook registration + model config
Without This vs With This
Default Claude Code — you describe a feature and:
idea → code → commit → push → discover the mess
The model writes on main, skips tests, force-pushes, and forgets the plan once the context window fills up. Every session is a coin flip.
With this system — the same feature request triggers a self-correcting pipeline:
┌─────────────────────────────────────────┐
│ You describe a feature │
└──────────────────┬──────────────────────┘
▼
┌──────────────────────────────────────────┐
│ Planner agent: │
│ 1a. Problem decomposition (evidence) │
│ 1b. User requirements (P0/P1/P2) │
│ 1c. Success metrics │
│ 2. Research gate → architecture │
│ → MASTER_PLAN.md + GitHub Issues │
└──────────────────┬───────────────────────┘
▼
┌──────────────────────────────────────────┐
│ Guardian agent creates isolated worktree │
└──────────────────┬───────────────────────┘
▼
┌────────────────────────────────────────────────┐
│ Implementer codes │
│ │
│ write src/ ──► test-gate: tests passing? ─┐ │
│ ▲ no? warn, then block │ │
│ └──── fix tests, write again ◄────────┘ │
│ │
│ write src/ ──► plan-check: plan stale? ───┐ │
│ ▲ yes? block │ │
│ └──── update plan, write again ◄──────┘ │
│ │
│ write src/ ──► doc-gate: documented? ─────┐ │
│ ▲ no? block │ │
│ └──── add headers + @decision ◄───────┘ │
└────────────────────────┬───────────────────────┘
▼
┌──────────────────────────────────────────────┐
│ Tester agent: live E2E verification │
│ → proof-of-work evidence written to disk │
│ → check-tester.sh: auto-verify or │
│ surface report for user approval │
└──────────────────────┬───────────────────────┘
▼
┌──────────────────────────────────────────────┐
│ Guardian agent: commit (requires verified │
│ proof-of-work + approval) → merge to main │
└──────────────────────────────────────────────┘
Every arrow is a hook. Every feedback loop is automatic. The model doesn't choose to follow the process — the hooks won't let it skip. Try to write code without a plan and you're pushed back. Try to commit with failing tests and you're pushed back. Try to skip documentation and you're pushed back. Try to commit without tester sign-off and you're pushed back. The system self-corrects until the work is right.
The result: you move faster because you never think about process. The hooks think about it for you. Dangerous commands get denied or rewritten (--force → --force-with-lease, /tmp/ → project tmp/). Everything else either flows through or gets caught. You just describe what you want and review what comes out.
Why Hooks, Not Instructions
Most Claude Code configs rely on CLAUDE.md instructions — guidance that works early in a session but degrades as the context window fills up or compaction throws everything off a cliff. This system puts enforcement in deterministic hooks: shell scripts that fire before and after every event, regardless of context pressure.
Instructions are probabilistic. Hooks are mechanical. That's the difference.
Getting Started
1. Clone
# SSH
git clone --recurse-submodules git@github.com:juanandresgs/claude-system.git ~/.claude
# Or HTTPS
git clone --recurse-submodules https://github.com/juanandresgs/claude-system.git ~/.claude
If you already have a ~/.claude directory, back it up first: tar czf ~/claude-backup-$(date +%Y%m%d).tar.gz ~/.claude
2. Configure
cp settings.local.example.json settings.local.json
# Edit to set your model preference, MCP servers, plugins
Settings are split: settings.json (tracked, universal) and settings.local.json (gitignored, your overrides). Claude Code merges both, with local taking precedence.
3. Verify
On your first claude session, you should see the SessionStart hook inject git state, plan status, and worktree info. Try writing a file to /tmp/test.txt — guard.sh should rewrite it to tmp/test.txt in the project root.
Optional: /backlog command uses GitHub Issues via gh CLI (gh auth login). Research skills (deep-research) accept OpenAI/Perplexity/Gemini API keys but degrade gracefully without them. Desktop notifications need terminal-notifier (macOS: brew install terminal-notifier).
Staying Updated
The harness auto-checks for updates on every new session start. Same-MAJOR-version updates are applied automatically. Breaking changes (different MAJOR version) show a notification — you decide when to apply.
- Auto-updates enabled by default. Create
~/.claude/.disable-auto-updateto disable. - Manual update:
cd ~/.claude && git pull --autostash --rebase - Fork users: Your
originpoints to your fork, so you get your own updates. Add anupstreamremote to also track the original repo. - Local customizations safe:
settings.local.jsonandCLAUDE.local.mdare gitignored. If you edit tracked files,--autostashpreserves your changes. If a conflict occurs, the update aborts cleanly and you're notified.
How It Works
┌────────────────────────────────────────────────────────────────────┐
│ The model doesn't decide the workflow. The hooks do. │
│ Plan first. Segment and isolate. Test everything. Get approval. │
└────────────────────────────────────────────────────────────────────┘
Agent Workflow
┌──────────┐
│ User │
└────┬─────┘
│ requirement
▼
┌──────────────┐
│ Planner │──── MASTER_PLAN.md + GitHub Issues
│ (opus) │
└──────┬───────┘
│ approved plan
▼
┌──────────────┐
│ Guardian │──── git worktree create
│ (opus) │
└──────┬───────┘
│ isolated branch
▼
┌──────────────┐
│ Implementer │──── tests + code + @decision
│ (sonnet) │
└──────┬───────┘
│ tests passing
▼
┌──────────────┐
│ Tester │──── live E2E verification + evidence
│ (sonnet) │
└──────┬───────┘
│ verified (auto or user approval)
▼
┌──────────────┐
│ Guardian │──── commit + merge + plan update
│ (opus) │
└──────┬───────┘
│ approval gate
▼
┌──────────┐
│ Main │ ← clean, tested, annotated
└──────────┘
| Agent | Model | Role | Key Output | |-------|-------|------|------------| | Planner | Opus | Complexity assessment (Brief/Standard/Full tiers), problem decomposition, requirements (P0/P1/P2 with acceptance criteria), success metrics, architecture design, research gate | MASTER_PLAN.md (with REQ-IDs + DEC-IDs), GitHub Issues, research