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.

Formerly claude-system.

Feb 26 2026: This project was archived for a full refactor, back by popular demand. Fixes backported, please git pull.

~/.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

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.

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.

# SSH
git clone --recurse-submodules git@github.com:juanandresgs/claude-ctrl.git ~/.claude

# Or HTTPS
git clone --recurse-submodules https://github.com/juanandresgs/claude-ctrl.git ~/.claude

If you already have a ~/.claude directory, back it up first: tar czf ~/claude-backup-$(date +%Y%m%d).tar.gz ~/.claude

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.

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).

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-update to disable.
• Manual update: cd ~/.claude && git pull --autostash --rebase
• Fork users: Your origin points to your fork, so you get your own updates. Add an upstream remote to also track the original repo.
• Local customizations safe: settings.local.json and CLAUDE.local.md are gitignored. If you edit tracked files, --autostash preserves your changes. If a conflict occurs, the update aborts cleanly and you're notified.

┌────────────────────────────────────────────────────────────────────┐
│  The model doesn't decide the workflow. The hooks do.              │
│  Plan first. Segment and isolate. Test everything. Get approval.   │
└────────────────────────────────────────────────────────────────────┘

                    ┌──────────┐
                    │   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
                    └──────────┘

The orchestrator dispatches to agents but never writes source code itself. Each agent handles its own approval cycle: present the work, wait for approval, execute, verify, suggest next steps.

For the complete agent protocol and dispatch rules, see ARCHITECTURE.md.

These are non-negotiable. Each one is enforced by hooks that run every time, regardless of context window state or model behavior.

All hooks are registered in settings.json and run deterministically — JSON in on stdin, JSON out on stdout. Hooks fire at four lifecycle points: before tool use (block or rewrite), after tool use (lint, track, validate), at session boundaries (context injection, cleanup), and around subagents (inject context, verify output).

For the full protocol, detailed tables, enforcement patterns, state files, and shared library APIs, see hooks/HOOKS.md.

Shared Libraries (not registered as hooks — sourced by hook scripts):

• context-lib.sh — Git state, plan status, worktree inventory, shared utilities
• source-lib.sh — Source file detection, language identification
• log.sh — Structured logging with levels and rotation

PreToolUse Hooks — fire before every tool call; can block or rewrite:

PostToolUse Hooks — fire after every tool call; can lint, track, validate:

Session & Notification Hooks:

Stop Hooks — fire when Claude finishes responding:

SubagentStart/Stop Hooks — fire around Task tool invocations:

The @decision annotation maps MASTER_PLAN.md decision IDs to source code. The Planner pre-assigns IDs (DEC-COMPONENT-NNN), the Implementer annotates code, the Guardian verifies coverage at merge time. doc-gate.sh enforces annotations on files over 50 lines.

/**
 * @decision DEC-AUTH-001
 * @title Use PKCE for mobile OAuth
 * @status accepted
 * @rationale Mobile apps cannot securely store client secrets
 */

Also supported: # DECISION: (Python/Shell) and // DECISION: (Go/Rust/C). Detection regex: @decision|# DECISION:|// DECISION:. See hooks/HOOKS.md for enforcement details.

Requirements and decisions live in a single artifact (MASTER_PLAN.md) with bidirectional linkage to source code:

MASTER_PLAN.md                         Source Code
REQ-P0-001 (requirement)               @decision DEC-AUTH-001
DEC-AUTH-001 (decision)                   Addresses: REQ-P0-001
  Addresses: REQ-P0-001

REQ-IDs (REQ-{CATEGORY}-{NNN}) are assigned during planning. DEC-IDs link to REQ-IDs via Addresses:. Phases reference which REQ-IDs they satisfy. surface.sh audits unaddressed P0 requirements at session end. plan-validate.sh validates REQ-ID format on every MASTER_PLAN.md write.

Governance:

Research:

Workflow:

Safe to change: settings.local.json (model, MCP servers, plugins), API keys for research skills, hook timeouts in settings.json.

Change with understanding: Agent definitions (agents/*.md), hook scripts (hooks/*.sh), CLAUDE.md dispatch rules and sacred practices.

Archived files are stored in .archive/YYYYMMDD/. Full backups at ~/claude-backup-*.tar.gz.

To debug a hook: echo '{"tool_name":"Bash","tool_input":{"command":"git status"}}' | bash hooks/guard.sh

Uninstall: Remove ~/.claude and restart Claude Code. It will recreate a default config directory. Your projects are unaffected.

• ARCHITECTURE.md — System architecture, 18 sections, design decisions (the authoritative deep-dive)
• hooks/HOOKS.md — Full hook reference: protocol, detailed tables, enforcement patterns, state files, shared libraries
• agents/planner.md — Planning process, research gate, MASTER_PLAN.md format
• agents/implementer.md — Test-first workflow, worktree setup, verification checkpoints
• agents/tester.md — Verification protocol, confidence levels, auto-verify conditions
• agents/guardian.md — Approval protocol, merge analysis, phase-boundary plan updates
• CONTRIBUTING.md — How to contribute
• CHANGELOG.md — Release history