Skip to content

Latest commit

 

History

History
127 lines (96 loc) · 12 KB

ARCHITECTURE.md

File metadata and controls

127 lines (96 loc) · 12 KB

ARCHITECTURE.md — Workbench Topology

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.

Six layers

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

Who lives where and why

  • 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 secretaria persona queues priorities, filters noise, and delivers escalations. Personas that want operator attention route through the arquiteto → secretaria.
  • Council — strategic layer. The arquiteto plans complex / multi-domain tasks and designs personas; the analista consolidates logs and journal into filtered briefings; the auditor-de-processo runs the weekly retrospective (highs / lows / root cause / plan).
  • Management — tactical orchestration. The gerente-de-projetos receives 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-seguranca audits every dependency before adoption and watches runtime for anomalies; the eng-testes is the delivery gate (Law 18); the validador approves new/edited personas; the ux-planner does design discovery before code; the recrutador is the external scout for libraries / repos / AI; the orquestrador watches machine resources; the eng-automacao turns 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's CLAUDE.md.

Canonical flows

Flow A — Operator → feature request

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.

Flow B — Persona wants operator attention

Any persona → Council (arquiteto validates relevance) → Office (secretaria queues) → Operator. Personas never contact the operator directly.

Flow C — New dependency / tool adoption

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.

Flow D — Complex task planning

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.

Flow E — Sprint (macro, 2–3 tracks)

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.

Flow F — Delivery gate (Law 18)

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.

Flow G — TDD trail (Law 18.4)

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.

Hook substrate

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

Spec substrate (progressive disclosure)

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.

Script substrate

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.

Memory graph (canonical fact store)

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

Decision record

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.

Extending the topology

  • New persona — invoke arquiteto; it interviews, drafts, materialises under .claude/agents/<name>.md following persona-template.md, triggers validador before 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 in Justfile, add a project-specific CLAUDE.md that specialises rules without duplicating them.
  • New doctrine / protocol — draft a spec under .claude/specs/<name>.md, reference it from CLAUDE.md in one line, record an ADR.