claude-code-workbench

An opinionated scaffold for agentic polyglot development with Claude Code — a council of specialised subagents, hook-based guardrails, a 3-layer permission model, and a blocked execution protocol for complex work.

What this is

This repository ships the governance shell — not an application. It is the substrate you drop next to your projects so that Claude Code operates under:

• Hook-based guardrails — PreToolUse policies that enforce security boundaries, block secret exfiltration, stop arbitrary sudo, and protect the workbench's own integrity (C10–C19, R2, P1).
• Subagent council — twelve personas across Council / Office / Management / Staff layers: architect, analyst, secretary, project manager, security officer, test engineer, automation engineer, validator, orchestrator, recruiter, process auditor, UX planner.
• TDD discipline — Law 18.4 mandates red/green commit separation; the test engineer audits the RED and GREEN SHAs before delivery closes.
• 3-layer permission model — settings.local.json (UX wildcards) + pre-tooluse-guard.py (security exit 2) + governance sentinels (publication, sudo, push).
• Blocked execution protocol — large tasks decomposed into numbered blocks, each with its commit type, explicit operator gate, and canonical report. Template at .claude/templates/plano-tecnico.md.
• Sprint doctrine — feature-sets longer than a week run in 2–3 parallel tracks with typed DoDs (infra / feature / docs / refactor / discovery) and a hard operator closing gate.

Nothing runs autonomously by default — the workbench operates under reactive invocation. The operator (you) is the final authority on publication, deletion, merge, and dependency adoption.

Repository layout

.claude/
  agents/        # 12 sanitised persona definitions
  hooks/         # PreToolUse / SessionStart / SessionEnd hooks (stdlib Python + bash)
  skills/        # Claude Code skills — e.g. tdd-workflow
  specs/         # Behavioural specs (progressive disclosure)
  templates/     # plano-tecnico.md, sprint-plan.md, handoff.md
  scripts/       # Tooling + stdlib test suite (148 passing)
  settings.json  # Tool allow/deny lists
  settings.local.json.example  # Personal overrides template
Justfile         # Task runner
CLAUDE.md        # Governance manual — laws, principles, protocols
ARCHITECTURE.md  # Layered topology + persona duties + flows
LICENSE          # Apache-2.0

Requirements

• Claude Code CLI or IDE extension
• Python 3.11+ (hooks and scripts use stdlib only)
• just 1.40+
• git 2.30+

Optional: Node + pnpm / uv for adjacent projects that use them.

Quick start

# Clone and enter
git clone <this-repo> workbench
cd workbench

# Copy the local-settings template (gitignored)
cp .claude/settings.local.json.example .claude/settings.local.json

# Environment (optional)
cp .env.example .env
# edit WORKBENCH_PROJECTS_ROOT if your projects live elsewhere

# Sanity check
just check
just test         # runs 148 hook + script tests

Open this directory in Claude Code — the SessionStart hook will show a briefing of the current state.

Using the workbench

• just --list — every recipe with description
• just test — workbench hook + script suite (148 tests, stdlib only)
• just audit — read-only inventory (agents, hooks, git state)
• just tools — systems registered in the memory graph + orphan detection
• just locks — active per-scope session locks + sentinels
• just check — CLI tool health check
• just stage — stage workbench infra files for commit

For anything more ambitious, invoke the architect subagent — it plans complex tasks in numbered blocks, materialises new personas, and routes inter-persona communication.

Extending

Add your projects under $WORKBENCH_PROJECTS_ROOT/<name>/ (default ./projects/) as independent directories. Extend the test / lint / build / dev / setup dispatchers in Justfile to route commands to each project. The workbench itself stays agnostic; project-specific rules live in each project's own CLAUDE.md.

Philosophy

Three observations shaped this scaffold:

1. Ergonomics and security are orthogonal. Approving a command once in a session does not mean approving it always — fossilising approvals in settings.local.json is an anti-pattern. Use settings for semantic wildcards (UX) and the PreToolUse hook for security (exit 2).
2. Broad delegation without verification rots. A persona that invokes another persona and commits blindly on return will eventually commit a contradiction. Law 17 mandates an integrity check (git status --porcelain + touched tests) before proceeding.
3. The TDD trail must be auditable. Bundling test and implementation in a single commit erases the evidence that the test ever failed. Law 18.4 enforces separated RED and GREEN commits; the test engineer audits both SHAs.

Full reasoning in CLAUDE.md (laws, principles) and ARCHITECTURE.md (topology, flows).

License

Apache-2.0 — see LICENSE.