Bureau 0.1.0

.gitignore

@@ -2,7 +2,8 @@ close-bureau
 .worktrees/
 *.pyc
 .serena/
-.vscode/
+.vscode/*
+!.vscode/settings.json
 .npm-cache/
 bureau.egg-info/
 .coverage
@@ -17,4 +18,7 @@ local.yml
 .archives/
 
 # MCP server clones (shared across worktrees)
-.mcp-servers/
+.mcp-servers/
+
+# Trained ML model (regenerated by bin/ensure-classifier-model)
+concierge/classifier/model.onnx

.shellcheckrc

@@ -0,0 +1,5 @@
+# For shellcheck (e.g. as extension in VSCode)
+
+# Equivalent of always passing `shellcheck -x`, which allows ShellCheck to follow 
+# `source`/`.` directives and lint the referenced files too
+external-sources=true

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    // ensure VSCode extension picks up Mypy when the uv-installed Python interpreter
+    //   (in bureau/.venv/) is selected in VSCode
+    "mypy-type-checker.importStrategy": "fromEnvironment"
+}

README.md

@@ -19,9 +19,11 @@
     - spawnable as **cross-CLI subagents** with *minimal* task delegation overhead
     - usable in *every* supported CLI as both: 
 
-        - **isolated subagents** 
+        - **isolated subagents**
         - **interactive main agents**
 
+- **Built-in workflow skills** — structured, multi-step protocols (like [two-phase code assessment](protocols/context/static/skills/assess-mode/SKILL.md)) that agents activate automatically when they recognise a matching task
+
 - A **<ins>*near-zero* learning curve</ins>** via:
 
   1. **context injection** that ensures:
@@ -56,7 +58,7 @@ rather than adapting to users' ad-hoc workflows, permitting open-ended explorati
 
 ### Consistent agent roles across 4 CLI platforms
 
-- [66 specialized roles](agents/role-prompts/) (architect, debugger, etc.) configured for use in *all* supported CLIs
+- [Specialized roles](agents/role-prompts/) (architect, code-reviewer, etc.) configured for use in *all* supported CLIs
 - Can choose a specific model per task (e.g. Claude for architecture, Gemini for broad code search)
 
 ### 2 ways of invoking agents
@@ -78,7 +80,7 @@ rather than adapting to users' ad-hoc workflows, permitting open-ended explorati
 | :--- | :--- | 
 | **Claude Code** | Activate at any time using **custom slash commands** set up by Bureau |
 | **OpenCode** | Use built-in [primary agent functionality](https://opencode.ai/docs/agents/#primary-agents) |
-| **Codex** & **Gemini CLI** | Use **custom role-specific launch wrappers** (e.g. `codex-debugger`, `gemini-architect`) set up by Bureau |
+| **Codex** & **Gemini CLI** | Use **custom role-specific launch wrappers** (e.g. `codex-code-reviewer`, `gemini-architect`) set up by Bureau |
 
 > [!TIP]
 > See details for these 2 invocation methods in the [*agent role usage patterns* section below](#agent-role-usage-patterns). 
@@ -105,20 +107,17 @@ Handling essential tasks like:
 
 All agents automatically read these files at startup:
 
-- [`protocols/context/static/handoff-guide.md`](protocols/context/static/handoff-guide.md) → when to delegate to subagents + which model to use
-- [`protocols/context/static/tools-guide.md`](protocols/context/static/tools-guide.md) → MCP tool selection guide
-
-    - Serves as an entrypoint to documentation progressively disclosing each MCP servers' tool capabilities
-
-- Guidance on automatically activating [skills](https://github.com/obra/superpowers/tree/main/skills) highly relevant and useful for key dev workflows/tasks *(provided by the [Superpowers plugin](https://github.com/obra/superpowers), currently **only for Claude Code or Codex**)*
+- [`ops-hub.md`](protocols/context/static/ops-hub.md) → central routing table that directs agents to task-specific spokes
+- Task-specific spokes in [`ops/`](protocols/context/static/ops/) → session start, task assessment, execution, completion
+- Protocol-owned generated `code-standards` skill → detailed, customizable coding standards activated for code-writing and code-editing tasks
 
-Injected via these files (created in setup steps)
+- **Custom Bureau skills**: structured workflow protocols (e.g. `assess-mode`) installed for all supported CLIs and activated automatically by matching prompts
+- **[Superpowers](https://github.com/obra/superpowers) skills** — community-maintained skill library *(currently Claude Code and Codex only)*
 
-- `~/.claude/CLAUDE.md` (Claude Code)
-- `~/.gemini/GEMINI.md` (Gemini CLI)
-- `~/.codex/AGENTS.md` (Codex)
+Injected via:
 
-with each of the 3 files above generated from templates (for portability regardless of repo clone location).
+- **Claude Code, Gemini CLI, Codex**: SessionStart hooks that `cat` the relevant protocol files into agent context at session start, plus per-prompt reminder hooks
+- **OpenCode**: native `instructions` array in its config file
 
 ### Spec-driven development *(maintainer favourite)* 
 
@@ -132,17 +131,52 @@ with each of the 3 files above generated from templates (for portability regardl
 - can seamlessly handle on-the-fly updates, accordingly synchronize/adjust specs, plans, tasks, etc. in a cascading fashion
 
 > [!TIP]
-> 
+>
 > To get started fast, **read [Bureau's 5-minute guide to `spec-kit`](docs/USAGE.md#using-github-speckit-cli)**.
 
+### Workflow skills that actually help
+
+> *Structured, multi-step protocols that agents activate automatically when they recognise a matching task.*
+
+> [!NOTE]
+> 
+> Bureau skill names match their source and install directory names (e.g. `assess-mode`).
+
+#### Skills installed by default
+
+| Skill | What it does |
+| :--- | :--- |
+| **[Assess mode](protocols/context/static/skills/assess-mode/SKILL.md)** | **Two-phase guided review**: first builds a mental model of changes (with 4 comprehension styles to choose from), then audits every file against [configurable quality standards](docs/CONFIGURATION.md#assess_mode). Interactive tour when used as a main agent; structured report when delegated to a subagent. |
+| **[Micro mode](protocols/context/static/skills/micro-mode/SKILL.md)** | **Step-gated editing with DAG-based planning:** offers maximum control over each atomic edit, with pause points after every change. |
+
+#### Additional skills available in the catalog
+
+The [`protocols/context/static/skills/`](protocols/context/static/skills/) directory ships several more skills that can be enabled on demand:
+
+| Skill | What it does |
+| :--- | :--- |
+| [Scrimmage mode](protocols/context/static/skills/scrimmage-mode/SKILL.md) | Systematic self-attack testing after every code change: generates attack vectors across 5 categories (input validation, state, failure modes, concurrency, security) and blocks progression until vulnerabilities are fixed. |
+| [Blast radius mode](protocols/context/static/skills/blast-radius-mode/SKILL.md) | Runs impact analysis before edits by enumerating callers, dependents, tests, and contracts affected, then classifying changes as *safe/needs review/breaking/blocked*. |
+| [Clearance mode](protocols/context/static/skills/clearance-mode/SKILL.md) | Rigorous completion verification that defines measurable "done" criteria upfront and blocks clearance until they're satisfied, with evidence. |
+| [Safeguard mode](protocols/context/static/skills/safeguard-mode/SKILL.md) | Defines system invariants (value constraints, state machines, relationships, ordering) that must never break and verifies them after all changes. |
+| [Prompt engineering](protocols/context/static/skills/prompt-engineering/SKILL.md) | Guided prompt creation and refinement for system prompts, agent instructions, skill definitions, or any LLM-facing text. |
+| [Shadow mode](protocols/context/static/skills/shadow-mode/SKILL.md) | Propose-only editing: the agent shows diffs without touching files, with the user applying changes manually. Ideal for learning, maximum transparency, or untrusted environments. |
+
+To enable any of these normal catalog skills, add them to the `skills.enabled` [config setting](docs/CONFIGURATION.md#skills):
+
+```yaml
+skills:
+  enabled: [micro-mode, assess-mode, shadow-mode, scrimmage-mode]
+```
+
 ## Agent role usage patterns
 
 ### Spawning subagents
 
 **Claude Code & OpenCode** *(via native subagents):*
 ```
 "Have the architect subagent design this system"
-"Use the debugger agent to investigate this stack trace"
+"Use the testing agent to isolate this failing test suite"
 "Spawn the security-compliance agent to audit these changes"
 ```
 
@@ -161,8 +195,8 @@ Use Bureau-configured slash commands:
 ```bash
 $ claude
 # ... startup output ...
-> /explainer
-# explainer role activated, interactive conversation begins
+> /architect
+# architect role activated, interactive conversation begins
 ```
 
 #### Gemini CLI & Codex
@@ -173,8 +207,8 @@ $ claude
 Use Bureau-configured launch wrapper scripts:
 
 ```bash
-# launch Gemini CLI w/ explainer role active
-$ gemini-explainer
+# launch Gemini CLI w/ architect role active
+$ gemini-architect
 
 # launch Codex using GPT-5.2-Codex w/ architect role active
 $ codex-architect --model gpt-5.2-codex
@@ -190,20 +224,20 @@ Use the built-in [primary agents mechanism](https://opencode.ai/docs/agents/#pri
 
 | File | Purpose | Tracked? |
 | :--- | :--- | :--- |
-| `charter.yml` | Fixed, rarely-changed system defaults | Yes |
-| `directives.yml` | Streamlined collection of user-oriented, often-tweaked settings | Yes |
+| `defaults.yml` | All git-tracked package defaults (ships with Bureau) | Yes |
+| `.bureau.yml` | Optional project-level config (discovered by CWD walk-up) | Yes (in *your* project) |
 | **`local.yml`** | **Personal customizations/overrides** (gitignored) | **No** (gitignored) |
 
 Configuration loads based on the following hierarchy *(later config sources override earlier ones)*: \
-**`charter.yml` → `directives.yml` → `local.yml` → environment variables**
+**`defaults.yml` → `.bureau.yml` → `local.yml` → environment variables**
 
 See [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md) for full reference.
 
 ## Repo structure
 
 ```
 bureau/
-├── bin/            # CLI entry points (open-bureau, close-bureau, check-prereqs)
+├── bin/            # CLI entry points (open-bureau, close-bureau, ensure-prereqs)
 ├── agents/         # Agent definitions and setup
 ├── protocols/      # Context/guidance files for agents
 ├── tools/          # MCP servers and their documentation