This document maps the workbench's six-layer hierarchy, the canonical flows between layers, and the technical substrate (hooks, specs, templates, scripts) the personas stand on. For the behavioural rules (laws, principles, gates) see CLAUDE.md.
┌───────────────────────────────────────────────────────┐
│ 1. OPERATOR ← the human invoking Claude │
└──────────────┬────────────────────────────────────────┘
│ via Secretary only
┌──────────────▼────────────────────────────────────────┐
│ 2. OFFICE secretaria │
└──────────────┬────────────────────────────────────────┘
│ routes escalations + queue
┌──────────────▼────────────────────────────────────────┐
│ 3. COUNCIL architect, analyst, │
│ auditor-de-processo │
└──────────────┬────────────────────────────────────────┘
│ plans, briefings, doctrine
┌──────────────▼────────────────────────────────────────┐
│ 4. MANAGEMENT gerente-de-projetos │
└──────────────┬────────────────────────────────────────┘
│ allocates work + runs checklist
┌──────────────▼────────────────────────────────────────┐
│ 5. STAFF orquestrador, recrutador, │
│ oficial-de-seguranca, │
│ eng-testes, eng-automacao, │
│ validador, ux-planner │
└──────────────┬────────────────────────────────────────┘
│ specialist services (transversal)
┌──────────────▼────────────────────────────────────────┐
│ 6. DEV (your project personas) │
└───────────────────────────────────────────────────────┘
- Operator — the single decision-maker for non-reversible actions (publish, delete, merge, adopt dependency). Claude Code is the executor; the operator is the authoriser.
- Office — the only structured output path to the operator. The
secretariapersona queues priorities, filters noise, and delivers escalations. Personas that want operator attention route through thearquiteto→secretaria. - Council — strategic layer. The
arquitetoplans complex / multi-domain tasks and designs personas; theanalistaconsolidates logs and journal into filtered briefings; theauditor-de-processoruns the weekly retrospective (highs / lows / root cause / plan). - Management — tactical orchestration. The
gerente-de-projetosreceives a feature / bug / refactor request, drafts the technical plan + checklist (TDD + tests + automation + security), allocates the right Dev, and dispatches the transversal Staff. - Staff — transversal specialists. Each serves every Dev and every project. The
oficial-de-segurancaaudits every dependency before adoption and watches runtime for anomalies; theeng-testesis the delivery gate (Law 18); thevalidadorapproves new/edited personas; theux-plannerdoes design discovery before code; therecrutadoris the external scout for libraries / repos / AI; theorquestradorwatches machine resources; theeng-automacaoturns recurring work into scripts / hooks / CI. - Dev — project-specific developers. The shipped workbench has no Dev personas — you add them per project in
.claude/agents/and register them in your project'sCLAUDE.md.
Operator → Office (secretaria queues) → Council (arquiteto plans, uses template plano-tecnico.md) → Management (gerente-de-projetos allocates) → Staff (eng-testes + oficial-de-seguranca as transversal gates) → Dev (executes) → Management (closes checklist) → Council (arquiteto reviews) → Office (secretaria reports) → Operator.
Any persona → Council (arquiteto validates relevance) → Office (secretaria queues) → Operator. Personas never contact the operator directly.
Recrutador finds → Oficial-de-seguranca audits (licence / CVE / maintenance / privacy) → Operator authorises (Law 5) → adopter executes the 5-step tool-adoption protocol (README, graph entity, uses relation, CLAUDE.md mention, commit body) → just tools confirms no orphan.
Operator (or any persona) detects complexity → Arquiteto interviews (AskUserQuestion), drafts plan in numbered blocks using plano-tecnico.md template → operator gate between blocks → each block closes with a canonical report (SHA + diff + Law 17 + tests) → next block, or stop on session-window limit.
Operator requests sprint / feature-set > 1 week → Arquiteto drafts dispatch using sprint-plan.md template in .claude/briefings/ → 2–3 parallel tracks, each with single persona-owner + typed DoD (infra / feature / docs / refactor / discovery) → hard visual gate mandatory on infra + feature → sprint closes only with operator "ok" via secretaria.
Persona finishes task → if touches executable / config / hook / agent → Eng-testes runs domain tests → RELEASE / REWORK verdict → if touches deps / hooks / secrets / publish config → Oficial-de-seguranca also audits (Law 18.1) → only then "done" reaches the operator.
New behaviour in executable file → RED commit first (only failing test, explicit stub, message test(scope): RED — ...) → GREEN commit second (minimal implementation, message feat(scope)|fix(scope): GREEN — ...) → Eng-testes audits both via git show <red-sha> and git show <green-sha>. A single mixed commit is REWORK.
Hooks are stdlib Python or bash scripts. Each responds to a Claude Code event:
| Hook | Event | Duty |
|---|---|---|
pre-tooluse-guard.py |
PreToolUse | Enforces 20+ guards (C10–C19, R2, P1) — secret leaks, sudo, destructive ops, cross-project boundary, self-integrity of .claude/hooks/ and settings*.json, per-scope session-lock, autopilot allow-list (C17 dormant), allow-push sentinel (C17). exit 2 always wins over settings.local.json allow. |
pre-playwright-resources.py |
PreToolUse | Blocks Playwright browser launches when system resources are below a threshold (prevents OOM from multiple parallel headless browsers). |
session-start-briefing.py |
SessionStart | Emits the Secretary's opening briefing — branch, uncommitted count, last commit, active personas, alerts. |
session-start-orphans.py |
SessionStart | Runs just-tools.py in orphan-scan mode and surfaces systems missing one of the 5 adoption steps. |
session-start-sanity.py |
SessionStart | Sanity checks workbench state (deleted-not-staged files, stale sentinels). |
session-journal.py |
SessionEnd | Appends a structured entry to .claude/journal/YYYY-MM.md. |
pause-check.sh |
SessionStart | Nuclear kill-switch: exits early if .claude/state/workbench-pause exists. |
The C19 self-integrity guard deserves special mention: any Write / Edit / destructive Bash operation (mv, cp, tee, redirect, sed -i, awk -i, perl -i) targeting .claude/hooks/, .claude/settings.json, or .claude/settings.local.json is blocked. To legitimately modify these files, the operator edits them outside Claude Code, or an authorised script uses the staging-plus-rsync pattern (rsync is outside the blocklist).
Personas avoid carrying bulky static data inline — instead they reference specs:
| Spec | Contains |
|---|---|
persona-template.md |
The nine canonical sections every persona must have (audit.py enforces). |
protocolo-execucao-blocada.md |
Block template, gate rules, stopping criterion, canonical report format. |
doutrina-sprint.md |
Sprint dispatch template, DoD typing, visual-gate rules, closing protocol. |
permission-model.md |
Full 3-layer map + wildcards philosophy + anti-pattern ("settings fossil"). |
Templates live in .claude/templates/: plano-tecnico.md, sprint-plan.md, handoff.md.
All scripts stdlib only — zero external dependencies — so the workbench runs anywhere Python 3.11 runs:
| Script | Purpose |
|---|---|
audit.py |
Read-only inventory: agents present, hooks present, git state summary. |
just-tools.py |
Lists systems registered in the memory graph with their README / consumers / last-seen; flags orphans (missing one of the 5 adoption steps). |
lock-status.py |
Snapshot of per-scope session locks + active sentinels (C16). |
pause-check.sh |
Checks the workbench-pause sentinel; used by both hook and CLI. |
resource-check.sh |
Machine snapshot (RAM / disk / load / top procs) as JSON. |
rotate-logs.sh |
Rotates .claude/logs/ files past 5 MB. |
workbench_log.py |
Structured log helper used by hooks (ISO timestamp + level + context). |
Each has a matching test in .claude/scripts/tests/ — 148 tests total, stdlib unittest, runnable via just test-hooks.
.claude/memory/knowledge-graph.jsonl — an append-only MCP memory store. Mandatory read before planning a complex task; mandatory write when a durable fact emerges (decision, incident, persona change, doctrine). Vocabulary in .claude/memory/README.md. The file is gitignored in the shipped workbench — teams can decide whether to commit theirs.
Architectural decisions are captured as ADRs in knowledge-vault/decisions/ (not shipped in this public scaffold — the workbench is the substrate, the team owns the vault). Cross-reference convention: each ADR has a short ID (ADR-NNN) referenced from CLAUDE.md where it binds behaviour.
- New persona — invoke
arquiteto; it interviews, drafts, materialises under.claude/agents/<name>.mdfollowingpersona-template.md, triggersvalidadorbefore promoting the persona to "active". - New hook — invoke
eng-automacao; it drafts under.claude/hooks/<name>.py, adds a test under.claude/scripts/tests/test_<name>.py, documents it in.claude/hooks/README.md, registers its event in.claude/settings.json. - New project — add under
$WORKBENCH_PROJECTS_ROOT/<name>/as an independent git repo, extend the relevant dispatchers inJustfile, add a project-specificCLAUDE.mdthat specialises rules without duplicating them. - New doctrine / protocol — draft a spec under
.claude/specs/<name>.md, reference it fromCLAUDE.mdin one line, record an ADR.