create-claude-cabinet 0.11.1 → 0.11.2

package/README.md

@@ -1,7 +1,7 @@
 # Claude Cabinet
 
 A cabinet of expert advisors for your Claude Code project. One command
-gives Claude a memory, 20 domain experts, a planning process, and the
+gives Claude a memory, 27 domain experts, a planning process, and the
 habit of starting sessions informed and ending them properly.
 
 Built by a guy who'd rather talk to Claude than write code. Most of it
@@ -12,7 +12,7 @@ was built by Claude. I just complained until it worked.
 Your project gets a cabinet — specialist advisors who each own a domain
 and weigh in when their expertise matters:
 
-- **Cabinet members** — 20 domain experts (security, accessibility,
+- **Cabinet members** — 27 domain experts (security, accessibility,
   architecture, QA, etc.) who review your project and surface what
   you'd miss alone
 - **Briefings** — project context members read before weighing in
@@ -37,7 +37,9 @@ say `/onboard`. It'll interview you about your project and set everything
 up based on your answers.
 
 **New to this?** See [GETTING-STARTED.md](GETTING-STARTED.md) for a
-step-by-step walkthrough.
+step-by-step walkthrough. Then [WORKFLOW-GUIDE.md](WORKFLOW-GUIDE.md)
+for how to use everything — when to plan, when to audit, what the
+cabinet does for you, and how the system grows with your project.
 
 ### For developers
 

package/lib/cli.js

@@ -163,6 +163,70 @@ function generateSkillIndex(projectDir) {
   const skillsDir = path.join(projectDir, '.claude', 'skills');
   if (!fs.existsSync(skillsDir)) return 0;
 
+  // Read project directive overlay if it exists
+  const projectDirectives = {};
+  const directivesFile = path.join(projectDir, '.claude', 'cabinet', 'directives-project.yaml');
+  if (fs.existsSync(directivesFile)) {
+    const dContent = fs.readFileSync(directivesFile, 'utf8');
+    // Parse simple YAML: top-level keys are member names, nested keys are
+    // standing-mandate (list) and directives (map)
+    let currentMember = null;
+    let inDirectives = false;
+    let currentDirectiveKey = null;
+    let currentDirectiveValue = '';
+    for (const line of dContent.split('\n')) {
+      if (/^\s*#/.test(line) || line.trim() === '') continue;
+      const indent = line.length - line.trimStart().length;
+      const content = line.trim();
+
+      // Flush previous directive value
+      if (currentDirectiveKey && indent <= 4 && !/^\s/.test(line.charAt(0)) || (indent <= 4 && currentDirectiveKey)) {
+        if (currentMember && currentDirectiveKey) {
+          if (!projectDirectives[currentMember]) projectDirectives[currentMember] = {};
+          if (!projectDirectives[currentMember].directives) projectDirectives[currentMember].directives = {};
+          projectDirectives[currentMember].directives[currentDirectiveKey] = currentDirectiveValue.trim();
+        }
+        currentDirectiveKey = null;
+        currentDirectiveValue = '';
+      }
+
+      if (indent === 0) {
+        // Top-level: member name
+        const m = content.match(/^(cabinet-[\w-]+):\s*$/);
+        if (m) {
+          currentMember = m[1];
+          projectDirectives[currentMember] = projectDirectives[currentMember] || {};
+          inDirectives = false;
+        }
+      } else if (indent === 2 && currentMember) {
+        const kv = content.match(/^([\w-]+):\s*(.*)$/);
+        if (kv) {
+          if (kv[1] === 'standing-mandate') {
+            // Parse [item1, item2] or item1, item2
+            const val = kv[2].replace(/^\[|\]$/g, '');
+            projectDirectives[currentMember].standingMandate = val.split(/,\s*/).map(s => s.trim()).filter(Boolean);
+            inDirectives = false;
+          } else if (kv[1] === 'directives') {
+            inDirectives = true;
+          }
+        }
+      } else if (indent === 4 && inDirectives && currentMember) {
+        const kv = content.match(/^([\w-]+):\s*(.*)$/);
+        if (kv) {
+          currentDirectiveKey = kv[1];
+          currentDirectiveValue = kv[2].replace(/^[>|]\s*$/, '');
+        }
+      } else if (indent >= 6 && currentDirectiveKey) {
+        currentDirectiveValue += ' ' + content;
+      }
+    }
+    // Flush last directive
+    if (currentMember && currentDirectiveKey) {
+      if (!projectDirectives[currentMember].directives) projectDirectives[currentMember].directives = {};
+      projectDirectives[currentMember].directives[currentDirectiveKey] = currentDirectiveValue.trim();
+    }
+  }
+
   const entries = [];
   const dirs = fs.readdirSync(skillsDir, { withFileTypes: true });
   for (const dir of dirs) {
@@ -202,6 +266,21 @@ function generateSkillIndex(projectDir) {
       entry.directives = fm.directives;
     }
 
+    // Merge project directive overlay (if any)
+    const overlay = projectDirectives[dir.name];
+    if (overlay) {
+      // Append project standing mandates (union, no duplicates)
+      if (overlay.standingMandate) {
+        const existing = entry.standingMandate || [];
+        const merged = [...new Set([...existing, ...overlay.standingMandate])];
+        entry.standingMandate = merged;
+      }
+      // Merge project directives (project wins on conflict)
+      if (overlay.directives) {
+        entry.directives = { ...(entry.directives || {}), ...overlay.directives };
+      }
+    }
+
     entries.push(entry);
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-claude-cabinet",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "description": "Claude Cabinet — opinionated process scaffolding for Claude Code projects",
   "bin": {
     "create-claude-cabinet": "bin/create-claude-cabinet.js"

package/templates/EXTENSIONS.md

@@ -226,8 +226,8 @@ command queue processing (needed by any project with an async work queue).
 
 ## Writing Domain-Specific Cabinet Members
 
-CC ships 14 generic cabinet members. Flow has 19 additional domain-specific
-cabinet members. Here are three examples showing how to write your own.
+CC ships 27 generic cabinet members. Your project can add domain-specific
+cabinet members on top of these. Here are three examples showing how to write your own.
 
 ### Example 1: GTD (encoding domain expertise)
 

package/templates/README.md

@@ -1,486 +1,227 @@
-# Process-in-a-Box
+# Claude Cabinet — Template Reference
 
-Generic methodology artifacts extracted from Flow, a cognitive workspace
-built on Claude Code. These are the transferable parts of a development
-process that emerged from months of iterative building — the patterns
-that work regardless of what you're building.
+These are the upstream templates that the `create-claude-cabinet` installer
+copies into your project. Everything here mirrors the `.claude/` directory
+structure. The installer handles copying, hook merging, and index generation
+— you don't need to copy files manually unless you want to.
 
-For the full methodology and the reasoning behind these artifacts, see
-the [methodology essay](../areas/flow-development/process-in-a-box-methodology.md).
+For the adoption story and user-facing docs, see the root
+[README.md](../README.md). For how Flow and other projects extend these
+templates, see [EXTENSIONS.md](EXTENSIONS.md).
 
 ## What's Here
 
-This package contains **Waves 1-7** artifacts. Wave 1 is generic as-is.
-Wave 2 parameterizes mixed-extractable artifacts — replacing hardcoded
-paths with references to `_briefing.md` and environment variables. Wave 3
-skeletons the session loop — orient and debrief — using the `phases/`
-pattern established by validate in Wave 2. Wave 4 skeletons the
-compliance stack — enforcement pipeline, plan, and execute. Wave 5
-skeletons the audit loop — audit, pulse, triage-audit — with a reference
-data layer, cabinet member infrastructure, and scripts that make the
-whole system work out of the box. Wave 6 documents how Flow extends
-and will adopt the package — see [EXTENSIONS.md](EXTENSIONS.md) for
-annotated phase file overrides, reusable patterns, and cabinet member
-writing examples. Wave 7 adds the lifecycle layer — onboarding,
-capability seeding, upgrades, and Claude Cabinet health monitoring.
-
-Everything is organized to mirror the `.claude/` directory structure, so
-adoption is straightforward: copy what you need into your project's
-`.claude/` directory.
-
-### Hooks (4)
-
-| Artifact | Wave | What It Does |
-|----------|------|-------------|
-| `hooks/git-guardrails.sh` | 1 | PreToolUse hook that blocks destructive git operations (force push to main, hard reset, git clean). Zero configuration needed. |
-| `hooks/stop-hook.md` | 1 | Template for a Stop event hook that checks whether the session-closing skill ran. Prompt-type (advisory, not blocking). |
-| `hooks/skill-telemetry.sh` | 2 | UserPromptSubmit hook that detects /skill-name invocations and logs to JSONL. Configurable via env vars. |
-| `hooks/skill-tool-telemetry.sh` | 2 | PostToolUse hook that captures programmatic Skill tool invocations. Configurable via env vars. |
-
-### Rules (1)
-
-| Artifact | Wave | What It Does |
-|----------|------|-------------|
-| `rules/enforcement-pipeline.md` | 4 | Generic enforcement pipeline: capture → classify → promote → encode → monitor. Describes the compliance stack, enforcement types, promotion criteria. |
-
-### Skills (13)
-
-| Artifact | Wave | What It Does |
-|----------|------|-------------|
-| `skills/menu/SKILL.md` | 1 | Dynamically discovers and displays all skills by scanning `.claude/skills/*/SKILL.md`. No hardcoded content. |
-| `skills/investigate/SKILL.md` | 2 | Structured codebase exploration: frame → observe → hypothesize → test → conclude. Pure methodology, no project-specific content. |
-| `skills/validate/SKILL.md` | 2 | **First `phases/` skeleton.** Orchestrates validators and presents a unified summary. Validators defined in `phases/validators.md`. |
-| `skills/orient/SKILL.md` | 3 | **Session start skeleton.** Loads context, syncs data, scans work, runs health checks and maintenance, presents briefing. 7 phase files. |
-| `skills/debrief/SKILL.md` | 3 | **Session close skeleton.** Inventories work, closes items, updates state, records lessons, captures loose ends. 8 phase files. |
-| `skills/plan/SKILL.md` | 4 | **Planning skeleton.** Research, overlap check, draft, cabinet member critique, completeness check, present, file work item. 7 phase files. |
-| `skills/execute/SKILL.md` | 4 | **Execution skeleton.** Load plan, activate cabinet members, 3-checkpoint protocol (pre-implementation, per-file-group, pre-commit), validate, verify AC. 5 phase files. |
-| `skills/audit/SKILL.md` | 5 | **Audit skeleton.** Select cabinet members, fast structural checks, load triage suppression, spawn parallel cabinet member agents with two-phase protocol, merge and persist findings. 5 phase files. |
-| `skills/pulse/SKILL.md` | 5 | **Pulse skeleton.** Self-description accuracy check: count freshness, dead reference spot-check, staleness detection. Two modes: embedded (silent in orient/debrief) and standalone. 3 phase files. |
-| `skills/triage-audit/SKILL.md` | 5 | **Triage skeleton.** Load findings, prepare commentary, present via local web UI or CLI, apply verdicts (fix/defer/reject), create actions for approved findings. 3 phase files. |
-| `skills/onboard/SKILL.md` | 7 | **Onboarding skeleton.** Conversational interview that generates the initial context layer. Re-runnable: first run generates, subsequent runs refine. 6 phase files. |
-| `skills/seed/SKILL.md` | 7 | **Capability seeding skeleton.** Detects technology adoption signals, proposes expertise conversations, builds and maintains cabinet members collaboratively. 4 phase files. |
-| `skills/cc-upgrade/SKILL.md` | 7 | **Upgrade skeleton.** Conversational merge when new Claude Cabinet skeletons arrive. Intelligence is the merge strategy — conversation, not mechanical copy. 4 phase files. |
-
-### Scripts (6)
-
-| Artifact | Wave | What It Does |
-|----------|------|-------------|
-| `scripts/pib-db.js` | 5 | Reference data layer CLI. SQLite database for work tracking (actions, projects) and audit findings. Commands: init, query, create-action, list-actions, create-project, ingest-findings, triage, triage-history. |
-| `scripts/pib-db-schema.sql` | 5 | Database schema: projects, actions, audit_runs, audit_findings (with triage status). |
-| `scripts/merge-findings.js` | 5 | Merges per-cabinet-member JSON outputs into unified run-summary.json. Optional `--db` flag to ingest into pib-db. |
-| `scripts/load-triage-history.js` | 5 | Builds suppression lists from triage history. Tries pib-db first, falls back to filesystem scan. |
-| `scripts/triage-server.mjs` | 5 | Self-contained Node.js HTTP server for triage UI. Zero external dependencies. In-memory data shuttle. |
-| `scripts/triage-ui.html` | 5 | Browser-based triage interface. Dark-themed, findings grouped by cabinet member, severity badges, Fix/Defer/Reject/Question verdicts, bulk actions, progress bar. |
-| `scripts/finding-schema.json` | 5 | JSON Schema for audit finding validation. |
-
-### Cabinet Members (15 + 7 infrastructure)
-
-Generic expert lenses that activate at structured checkpoints (planning,
-execution, audit). Each is a named domain expert encoded in markdown.
-
-**Wave 1 — generic as-is (8):**
-
-| Cabinet Member | Domain | Activation |
-|------------|--------|-----------|
-| `anti-confirmation` | Reasoning quality, cognitive bias detection | On high-stakes decisions |
-| `boundary-man` | Implicit guards, silent exclusions, ZOMBIES analysis | Always-on during execution |
-| `debugger` | Dependency chains, environment prereqs, pre-flight investigation | Always-on during execution |
-| `small-screen` | Viewport adaptability, touch targets, responsive layout | During audits + layout code |
-| `organized-mind` | Levitin's cognitive neuroscience applied to system design | During audits + planning |
-| `speed-freak` | Database queries, render efficiency, bundle size, perceived speed | During audits |
-| `qa` | Active testing, acceptance criteria, regression verification | Always-on during plan + execute |
-| `technical-debt` | Fowler's debt quadrant, Beck's four rules, structural sustainability | During audits |
-
-**Wave 2 — parameterized via `_briefing.md` (6):**
-
-| Cabinet Member | Domain | What's Parameterized |
-|------------|--------|---------------------|
-| `accessibility` | WCAG compliance, keyboard nav, screen reader, focus management | Scan scope paths, UI framework references |
-| `data-integrity` | Cross-store consistency, referential integrity, API contracts | Database paths, entity types, server paths |
-| `record-keeper` | Docs-code drift, convention compliance, CLAUDE.md coverage | File paths, validation scripts, entity types |
-| `process-therapist` | Skill/cabinet member effectiveness, overlap/gap analysis | Audit infrastructure paths, prompt guide location |
-| `workflow-cop` | Development lifecycle, human burden, guardrail effectiveness | Deployment platform, sync mechanisms, scheduled tasks |
-| `security` | Threat model, secrets management, API protection, deployment security | Server paths, deployment config, secret names |
-
-**Wave 7 — lifecycle (1):**
-
-| Cabinet Member | Domain | Activation |
-|------------|--------|-----------|
-| `cc-health` | Claude Cabinet adoption health, phase file coverage, configuration drift, anti-bloat | Always-on during audit |
-
-**Infrastructure files (7):**
-
-| File | Wave | Purpose |
-|------|------|---------|
-| `_eval-protocol.md` | 1 | Structured assessment framework for evaluating skill/cabinet member effectiveness |
-| `_composition-patterns.md` | 1 | Five patterns for combining cabinet members: parallel, sequential, adversarial, nested, temporal |
-| `_briefing-template.md` | 1+2 | Template for the project-specific briefing every cabinet member reads. Wave 2 added: Scan Scopes, API Configuration, Entity Types, User Context. |
-| `_prompt-guide.md` | 2 | Craft knowledge for writing cabinet member prompts. 17 principles including Levitin's cognitive architecture. |
-| `output-contract.md` | 5 | How cabinet members produce structured findings for the audit system. Defines the assumption/evidence/question triad, severity calibration, positive findings, autoFixable field, JSON output format. |
-| `committees.yaml` | 5 | Upstream committee definitions for organizing cabinet members (ux, code, health, process, strategic). Upstream-owned; project customizations go in `committees-project.yaml`. |
-| `_lifecycle.md` | 5 | When to adopt, retire, and assess cabinet members. Cross-cutting vs grouped distinction. |
+### Hooks (5)
+
+| Artifact | What It Does |
+|----------|-------------|
+| `hooks/git-guardrails.sh` | PreToolUse hook that blocks destructive git operations (force push to main, hard reset, git clean). Zero configuration. |
+| `hooks/stop-hook.md` | Stop event hook that checks whether the session-closing skill ran. Prompt-type (advisory, not blocking). |
+| `hooks/skill-telemetry.sh` | UserPromptSubmit hook that detects /skill-name invocations and logs to JSONL. Configurable via env vars. |
+| `hooks/skill-tool-telemetry.sh` | PostToolUse hook that captures programmatic Skill tool invocations. Configurable via env vars. |
+| `hooks/cc-upstream-guard.sh` | PreToolUse hook that blocks edits to manifest-tracked upstream files. Prevents downstream drift. |
+
+### Rules (2)
+
+| Artifact | What It Does |
+|----------|-------------|
+| `rules/enforcement-pipeline.md` | Generic enforcement pipeline: capture, classify, promote, encode, monitor. Describes the compliance stack and promotion criteria. |
+| `rules/memory-capture.md` | When and how to capture memories to omega. What to capture, what not to, cadence guidance. |
+
+### Skills (22 workflow + 27 cabinet members)
+
+**Workflow Skills:**
+
+| Skill | What It Does |
+|-------|-------------|
+| `skills/audit/` | Convene the full cabinet for a quality review. Select members, run structural checks, spawn parallel agents, merge and persist findings. 5 phase files. |
+| `skills/cabinet/` | Front door to browse and consult expert cabinet members. Reads from `_index.json`. |
+| `skills/cc-upgrade/` | Conversational upgrade when new Claude Cabinet versions arrive. Intelligence is the merge strategy. |
+| `skills/debrief/` | Session close. Inventory work, close items, run cabinet consultations, update state, persist, record lessons. 9 phase files. |
+| `skills/debrief-quick/` | Quick debrief variant — core phases only, skip presentation. |
+| `skills/execute/` | Execute a plan with cabinet member checkpoints. 3-checkpoint protocol (pre-implementation, per-file-group, pre-commit). 5 phase files. |
+| `skills/execute-plans/` | Batch execution of multiple plans with conflict detection. |
+| `skills/extract/` | Analyze project artifacts and propose upstream extraction candidates for Claude Cabinet. |
+| `skills/investigate/` | Structured codebase exploration: frame, observe, hypothesize, test, conclude. |
+| `skills/link/` | Set up local development linking for Claude Cabinet source repo work. |
+| `skills/memory/` | Browse, search, and manage semantic memory via omega. |
+| `skills/menu/` | Dynamically discover and display all available skills. Reads from `_index.json`. |
+| `skills/onboard/` | Conversational onboarding. Interviews you, generates briefings, wires the session loop. Re-runnable. 8 phase files. |
+| `skills/orient/` | Session start. Load context, sync data, scan work, run health checks, spawn cabinet consultations, show skills menu. 7 phase files. |
+| `skills/orient-quick/` | Quick orient variant — core phases only, skip presentation. |
+| `skills/plan/` | Structured planning with cabinet critique. Research, overlap check, draft, critique, completeness, present, file. 9 phase files. |
+| `skills/publish/` | Publish workflow (CC source repo only, not shipped to consumers). |
+| `skills/pulse/` | Self-description accuracy check. Count freshness, dead references, staleness. 3 phase files. |
+| `skills/seed/` | Recruit new cabinet members. Detect technology signals, propose expertise, build collaboratively. 4 phase files. |
+| `skills/triage-audit/` | Audit finding triage via local web UI or CLI. Load, present, apply verdicts. 3 phase files. |
+| `skills/unlink/` | Remove local development linking. Returns to published npm package. |
+| `skills/validate/` | Run structural validation checks. Validators defined in phase files. |
+| `skills/work-tracker/` | Open the work tracking UI interactively. Starts local server. |
+
+**Cabinet Members (27):**
+
+Generic expert lenses that activate at structured checkpoints. Each is a
+domain expert encoded in markdown with frontmatter declaring standing
+mandates and scoped directives.
+
+| Cabinet Member | Domain |
+|----------------|--------|
+| `cabinet-accessibility` | WCAG compliance, keyboard nav, screen reader, focus management |
+| `cabinet-anti-confirmation` | Reasoning quality, cognitive bias detection |
+| `cabinet-architecture` | System fit, infrastructure leverage, CTO-level evaluation |
+| `cabinet-boundary-man` | Implicit guards, silent exclusions, ZOMBIES analysis |
+| `cabinet-cc-health` | Claude Cabinet adoption health, configuration drift, anti-bloat |
+| `cabinet-data-integrity` | Cross-store consistency, referential integrity, API contracts |
+| `cabinet-debugger` | Dependency chains, error modes, environment prerequisites |
+| `cabinet-framework-quality` | UI framework utilization, API coverage, anti-patterns |
+| `cabinet-goal-alignment` | Strategic purpose alignment, feature-mission fit |
+| `cabinet-historian` | Institutional memory, decision archaeology, context preservation |
+| `cabinet-information-design` | Spatial composition, visual hierarchy, layout decisions |
+| `cabinet-mantine-quality` | Mantine v8 specialist (opt-in pre-built variant) |
+| `cabinet-organized-mind` | Levitin's cognitive neuroscience applied to system design |
+| `cabinet-process-therapist` | Skill/process effectiveness, overlap/gap analysis |
+| `cabinet-qa` | Active testing, acceptance criteria, regression verification |
+| `cabinet-record-keeper` | Documentation accuracy, docs-code drift, convention compliance |
+| `cabinet-roster-check` | Skill ecosystem strategy, coverage gaps, redundancy |
+| `cabinet-security` | Threat model, secrets management, API protection |
+| `cabinet-small-screen` | Viewport adaptability, touch targets, responsive layout |
+| `cabinet-speed-freak` | Database queries, render efficiency, perceived speed |
+| `cabinet-system-advocate` | Feature adoption tracking, capability discoverability |
+| `cabinet-technical-debt` | Fowler's debt quadrant, structural sustainability |
+| `cabinet-ui-experimentalist` | Bleeding-edge UI patterns, experimental techniques |
+| `cabinet-usability` | Interaction model coherence, UX design |
+| `cabinet-user-advocate` | End-user perspective, system education |
+| `cabinet-vision` | Strategic direction, what the project should become |
+| `cabinet-workflow-cop` | Development lifecycle, human burden, guardrail effectiveness |
+
+**Cabinet Infrastructure (8):**
+
+| File | Purpose |
+|------|---------|
+| `cabinet/committees.yaml` | Upstream committee definitions (ux, code, health, process, strategic). Project customizations go in `committees-project.yaml`. |
+| `cabinet/directives-project.yaml` | Template for project-level directive overlay. Extends upstream members with project-specific mandates and directives. |
+| `cabinet/composition-patterns.md` | Five patterns for combining cabinet members: parallel, sequential, adversarial, nested, temporal. |
+| `cabinet/eval-protocol.md` | Structured assessment framework for evaluating skill/cabinet member effectiveness. |
+| `cabinet/lifecycle.md` | When to adopt, retire, and assess cabinet members. |
+| `cabinet/output-contract.md` | How cabinet members produce structured findings for the audit system. |
+| `cabinet/prompt-guide.md` | Craft knowledge for writing cabinet member prompts. 17 principles. |
+
+### Scripts (12)
+
+| Script | What It Does |
+|--------|-------------|
+| `scripts/cabinet-memory-adapter.py` | Python adapter for omega memory. Project-scoped tiered retrieval. |
+| `scripts/cc-drift-check.cjs` | Compare installed file hashes against manifest. Detect upstream drift. |
+| `scripts/finding-schema.json` | JSON Schema for audit finding validation. |
+| `scripts/load-triage-history.js` | Build suppression lists from triage history. Tries pib-db first, falls back to filesystem. |
+| `scripts/merge-findings.js` | Merge per-cabinet-member JSON outputs into unified run-summary. Optional `--db` flag for pib-db ingestion. |
+| `scripts/pib-db.js` | Reference data layer CLI. SQLite for work tracking (actions, projects) and audit findings. |
+| `scripts/pib-db-schema.sql` | Database schema: projects, actions, audit_runs, audit_findings. |
+| `scripts/resolve-committees.cjs` | Merge upstream `committees.yaml` with project `committees-project.yaml`. Deterministic output. |
+| `scripts/triage-server.mjs` | Self-contained Node.js HTTP server for triage UI. Zero external dependencies. |
+| `scripts/triage-ui.html` | Browser-based triage interface. Dark-themed, severity badges, bulk actions. |
+| `scripts/work-tracker-server.mjs` | Self-contained Node.js HTTP server for work tracking UI. |
+| `scripts/work-tracker-ui.html` | Browser-based work tracking interface. Projects, actions, filtering. |
+
+### Briefing Templates (6)
+
+| Template | What It Generates |
+|----------|-------------------|
+| `briefing/_briefing-template.md` | Hub template. Describes all briefing files and the member-to-briefing mapping. |
+| `briefing/_briefing-identity-template.md` | Project identity: what it is, core principles, user context. |
+| `briefing/_briefing-architecture-template.md` | Tech stack, data stores, deployment. |
+| `briefing/_briefing-jurisdictions-template.md` | Directory layout, file ownership, conventions. |
+| `briefing/_briefing-cabinet-template.md` | Active members, portfolio rules, invocation patterns. |
+| `briefing/_briefing-work-tracking-template.md` | Work tracking setup, query patterns. |
+| `briefing/_briefing-api-template.md` | API endpoints, auth, entity types (only if project has an API). |
 
 ### Memory (1 pattern + 1 template)
 
 | Artifact | What It Does |
 |----------|-------------|
-| `patterns/pattern-intelligence-first.md` | Universal principle: use LLM for semantic work, JSON for pipelines, research before coding |
-| `patterns/_pattern-template.md` | The pattern file format itself — frontmatter schema for the feedback-to-enforcement pipeline |
+| `memory/patterns/pattern-intelligence-first.md` | Universal principle: use LLM for semantic work, JSON for pipelines, research before coding. |
+| `memory/patterns/_pattern-template.md` | Pattern file format for the feedback-to-enforcement pipeline. |
 
 ## How to Adopt
 
-### Minimum viable adoption
+### Recommended: use the installer
+
+```bash
+npx create-claude-cabinet
+```
+
+The CLI walks you through module selection, copies templates, sets up
+hooks, generates the skill index, and optionally installs a SQLite work
+tracker. Then run `/onboard` in Claude Code for conversational setup.
+
+For non-developers or fresh machines:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/orenmagid/claude-cabinet/main/install.sh | bash
+```
+
+### Manual adoption (copy what you need)
+
+If you prefer manual control, copy files from this `templates/` directory
+into your project's `.claude/` directory. The minimum viable adoption:
 
 1. Copy `hooks/git-guardrails.sh` to `.claude/hooks/`
-2. Add the hook to your `.claude/settings.json`:
-   ```json
-   {
-     "hooks": {
-       "PreToolUse": [{
-         "matcher": "Bash",
-         "hooks": [{
-           "type": "command",
-           "command": ".claude/hooks/git-guardrails.sh"
-         }]
-       }]
-     }
-   }
-   ```
-3. Copy `skills/menu/SKILL.md` to `.claude/skills/menu/`
-
-You now have git safety and skill discovery.
-
-### Adding telemetry
-
-1. Copy `hooks/skill-telemetry.sh` and `hooks/skill-tool-telemetry.sh`
-   to `.claude/hooks/`
-2. Add to your `.claude/settings.json`:
-   ```json
-   {
-     "hooks": {
-       "UserPromptSubmit": [{
-         "matcher": "",
-         "hooks": [{ "type": "command", "command": ".claude/hooks/skill-telemetry.sh" }]
-       }],
-       "PostToolUse": [{
-         "matcher": "Skill",
-         "hooks": [{ "type": "command", "command": ".claude/hooks/skill-tool-telemetry.sh" }]
-       }]
-     }
-   }
-   ```
-3. Optionally set `TELEMETRY_DIR` to control where JSONL records are written
-   (defaults to `~/.claude/telemetry/`)
-
-### Adding cabinet members
-
-1. Copy `skills/cabinet/` to `.claude/skills/cabinet/`
-2. Create your own `_briefing.md` from `_briefing-template.md` — fill in
-   your project's specifics (scan scopes, data store, entity types, etc.)
-3. Wave 2 cabinet members reference `_briefing.md` sections by name — fill in
-   the sections relevant to the cabinet members you adopt
-4. Cabinet members are now available for your planning, execution, and audit
-   skills to invoke
-
-### Adding the validate skeleton
-
-1. Copy `skills/validate/` (including `phases/`) to `.claude/skills/validate/`
-2. Edit `phases/validators.md` — uncomment and adapt the example validators
-   for your project's type checker, linter, build step, etc.
-3. Run `/validate` to confirm your validators work
-
-This is the first skill using the `phases/` pattern. The skeleton defines
-the orchestration; you write your validators in the phase file.
-
-### Guided onboarding (recommended)
-
-Instead of manually copying files, run `/onboard` after copying the
-onboard skill. It interviews you about your project, generates the
-context layer, wires the session loop, and presents opt-in modules.
-Re-run it as your project matures to refine what was generated.
-
-### Adding the session loop (orient + debrief) — manual
-
-1. Copy `skills/orient/` and `skills/debrief/` (including `phases/`)
-   to `.claude/skills/orient/` and `.claude/skills/debrief/`
-2. Edit the orient phase files:
-   - `phases/context.md` — what files and state to read at session start
-   - `phases/data-sync.md` — how to sync fresh data (skip if purely local)
-   - `phases/work-scan.md` — what work items to check
-   - Leave other phase files empty until you need them
-3. Edit the debrief phase files:
-   - `phases/close-work.md` — how to match and close work items
-   - `phases/update-state.md` — what state files to update
-   - `phases/record-lessons.md` — how to capture lessons
-   - Leave other phase files empty until you need them
-4. Add the stop hook (`hooks/stop-hook.md`) to verify debrief ran
-
-Start with context + work-scan + close-work + record-lessons. Add more
-phases as your project matures and you discover what decays without them.
-
-To add project-specific phases the skeleton doesn't define, create new
-files in `phases/` — each declares when it runs relative to the core
-phases. Claude discovers them at runtime.
-
-### Adding the planning/execution workflow
-
-1. Copy `skills/plan/` and `skills/execute/` (including `phases/`)
-   to `.claude/skills/plan/` and `.claude/skills/execute/`
-2. Edit the plan phase files:
-   - `phases/overlap-check.md` — how to search for existing work (skip if
-     no work tracker yet)
-   - `phases/plan-template.md` — customize your plan sections (or leave
-     empty for the default template)
-   - `phases/work-tracker.md` — how to file work items
-3. Edit the execute phase files:
-   - `phases/load-plan.md` — where your plans live (or leave empty if
-     plans are always in conversation)
-   - `phases/commit-and-deploy.md` — your commit and deploy workflow
-   - `phases/validators.md` — what validation to run
-   - `phases/verification-tools.md` — tools for checking manual AC
-4. Fill in the **Work Tracking** section of your `_briefing.md`
-
-Start with plan-template + work-tracker + commit-and-deploy. Other phase
-files have sensible defaults. To actively suppress a default phase, write
-`skip: true` in the file instead of leaving it empty.
-
-### Adding the enforcement pipeline
-
-1. Copy `rules/enforcement-pipeline.md` to `.claude/rules/`
-2. Copy `memory/patterns/` to your memory directory
-
-1. Copy `memory/patterns/` to your memory directory
-2. Use `_pattern-template.md` as the format for capturing your own
-   project's friction patterns
-3. Over time, patterns accumulate and some get promoted to rules or hooks
-
-### Adding the audit loop
-
-The audit loop has three skills (audit, pulse, triage-audit), a reference
-data layer, and supporting scripts. The design philosophy is "Claude
-Cabinet" — sensible defaults that work out of the box, easy to override
-when you outgrow them.
-
-1. **Initialize the reference data layer:**
-   ```bash
-   cp process-in-a-box/scripts/pib-db*.* your-project/scripts/
-   cd your-project && node scripts/pib-db.js init
-   ```
-   This creates a local SQLite database for work tracking and audit
-   findings. The session loop skills (orient work-scan, debrief close-work,
-   plan overlap-check and work-tracker) will use it automatically via
-   their default behaviors.
-
-2. **Copy audit skills:**
-   ```bash
-   cp -r process-in-a-box/skills/audit/ .claude/skills/audit/
-   cp -r process-in-a-box/skills/pulse/ .claude/skills/pulse/
-   cp -r process-in-a-box/skills/triage-audit/ .claude/skills/triage-audit/
-   ```
-
-3. **Copy cabinet member infrastructure:**
-   ```bash
-   cp process-in-a-box/skills/cabinet/output-contract.md .claude/skills/cabinet/
-   cp process-in-a-box/skills/cabinet/committees.yaml .claude/skills/cabinet/
-   cp process-in-a-box/skills/cabinet/_lifecycle.md .claude/skills/cabinet/
-   ```
-
-4. **Copy audit scripts:**
-   ```bash
-   cp process-in-a-box/scripts/merge-findings.js your-project/scripts/
-   cp process-in-a-box/scripts/load-triage-history.js your-project/scripts/
-   cp process-in-a-box/scripts/triage-server.mjs your-project/scripts/
-   cp process-in-a-box/scripts/triage-ui.html your-project/scripts/
-   cp process-in-a-box/scripts/finding-schema.json your-project/scripts/
-   ```
-
-5. **Customize committees** (optional):
-   Create a `committees-project.yaml` in `.claude/cabinet/` to add custom
-   members or committees. The upstream `committees.yaml` is installed
-   automatically. Run `node scripts/resolve-committees.cjs` to see the
-   merged result.
-
-6. **Run your first audit:** `/audit` — it discovers cabinet members, runs
-   them, and persists findings. Then `/triage-audit` to review results.
-
-The reference data layer is designed to be replaced. When your project
-outgrows local SQLite (needs a team dashboard, external API, deployed
-database), override the relevant phase files in each skill. The phase
-file protocol means you replace one piece at a time without touching
-the skill orchestration.
-
-## What You and Claude Build Together
-
-The package provides skeletons and infrastructure. You and Claude fill
-in the project-specific parts together — Claude helps you write the
-phase files, configure cabinet members, and set up validators. This is
-the working relationship the methodology is built around: the human
-provides judgment and domain knowledge, Claude implements, evaluates,
-and proposes.
-
-These are the project-specific pieces to build as you adopt:
-
-- **`_briefing.md`** — Project-specific briefing that all cabinet members read.
-  Start from `_briefing-template.md`. Claude helps you fill in the sections
-  relevant to the cabinet members you adopt.
-- **Orient phase files** — Session startup specifics (what to read, what
-  to sync, what work to scan). The skeletons have commented-out examples;
-  Claude helps you adapt them for your project.
-- **Debrief phase files** — Session close specifics (how to close work,
-  what state to update, how to capture lessons). Same pattern — skeletons
-  guide, Claude helps implement.
-- **Validators** — Edit `skills/validate/phases/validators.md` with your
-  project's specific checks. Claude can help identify what to validate.
-- **Plan phase files** — Planning specifics (how to check for existing work,
-  your plan template, how to file work items). Skeletons have defaults for
-  each phase; customize when your project needs something different.
-- **Execute phase files** — Execution specifics (where plans live, what
-  verification tools to use, how to commit and deploy). Same pattern.
-
-- **Audit phase files** — Audit specifics (which cabinet members to run,
-  fast structural checks, how to persist findings). Defaults use pib-db
-  and the included scripts; customize when your project needs external
-  storage or different workflows.
-- **Pulse checks** — What self-description accuracy to verify (counts,
-  references, staleness). Start empty for defaults; add project-specific
-  checks as you discover what drifts.
-- **Triage phase files** — Where findings come from, how to present them,
-  how to apply verdicts. Defaults use the local triage UI and pib-db.
-- **Committees** — The upstream `committees.yaml` is installed automatically.
-  Create `committees-project.yaml` to add custom members to upstream
-  committees or define new project-specific committees.
-
-None of this requires working alone. Claude is the constant companion
-throughout — the package provides the structure, and you build the
-specifics together through use.
+2. Add the hook to `.claude/settings.json`
+3. Copy `skills/menu/` to `.claude/skills/menu/`
+
+You now have git safety and skill discovery. Add more modules as needed:
+
+- **Session loop:** `skills/orient/`, `skills/debrief/`, `hooks/stop-hook.md`
+- **Planning:** `skills/plan/`, `skills/execute/`
+- **Audit:** `skills/audit/`, `skills/pulse/`, `skills/triage-audit/`, plus `cabinet/` infrastructure and `scripts/`
+- **Cabinet members:** Copy individual `skills/cabinet-*/` directories for the experts you want
 
 ## Configuration
 
-There is no `box.yaml` or template engine. Configuration uses two mechanisms:
-
-1. **`_briefing.md`** — For cabinet members. Fill in the sections relevant to
-   the cabinet members you adopt. Cabinet members reference sections by name
-   (e.g., `_briefing.md § Data Store`).
-
-2. **`phases/` directories** — For skills. Skeleton SKILL.md defines the
-   generic workflow. You write your implementations in phase files. Claude
-   reads whatever phase files exist at runtime. All skeleton skills use
-   this pattern: validate, orient, debrief, plan, and execute.
-
-   Phase files have **three states**:
-   - **Absent or empty** → use the skeleton's default behavior
-   - **Contains `skip: true`** → explicitly opt out, skip entirely
-   - **Contains content** → custom behavior replaces the default
-
-   This three-state protocol means a new project gets useful behavior
-   out of the box, while mature projects can customize or suppress any
-   phase. All skeleton skills use this pattern: validate, orient,
-   debrief, plan, execute, audit, pulse, triage-audit, onboard, seed,
-   and upgrade.
-
-3. **Environment variables** — For hooks and scripts. Telemetry hooks read
-   `TELEMETRY_DIR`, `TELEMETRY_FILE`, `DEBUG_LOG`, `SKILL_DIR`. Database
-   scripts read `PIB_DB_PATH` (default: `./pib.db`), `REVIEWS_DIR`
-   (default: `./reviews`). All have sensible defaults.
-
-## What This Package Does NOT Include
-
-- **Flow-specific skills** — 15 skills deeply specific to Flow's
-  architecture (inbox processing, voice capture, deploy verification,
-  etc.). The generic patterns (orient, debrief, plan, execute, audit,
-  pulse, triage-audit) are included as skeletons. See
-  [EXTENSIONS.md](EXTENSIONS.md) for annotated descriptions of these
-  skills and the reusable patterns they embody.
-- **Flow-specific cabinet members** — system-advocate, life-tracker,
-  life-optimization, and 19 other cabinet members tied to Flow's domain
-  (GTD expertise, Mantine quality, sync health, etc.). EXTENSIONS.md
-  includes examples showing how to write your own domain cabinet members.
-- **Distribution mechanism** — No npm package, no installer. Copy files.
-  The `/onboard` skill guides adoption. The `/cc-upgrade` skill handles updates.
-
-## Relationship to Flow
-
-Flow is the reference implementation — the project these artifacts were
-extracted from. Flow continues using its own copies in `.claude/`. The
-package is a standalone extraction that proves these artifacts are
-cleanly separable. Flow's specific implementations serve as extension
-examples showing what a mature deployment looks like. See
-[EXTENSIONS.md](EXTENSIONS.md) for annotated examples of how Flow
-extends, overrides, and will adopt the package's skeletons.
-
-## Waves
-
-This package includes all 7 waves of the extraction:
-
-1. **Package generic artifacts** — done (17 artifacts)
-2. **Parameterize paths** — done (14 artifacts: telemetry hooks, validate
-   skeleton, investigate, prompt guide, 6 parameterized cabinet members,
-   `_briefing.md` contract)
-3. **Skeleton the session loop** — done (orient + debrief skeletons with
-   7 + 8 phase files, custom phase injection for project extensions)
-4. **Skeleton the compliance stack** — done (enforcement pipeline rules,
-   plan skeleton with 7 phases, execute skeleton with 5 phases, three-state
-   phase protocol, `_briefing.md` Work Tracking section)
-5. **Skeleton the audit loop** — done (audit + pulse + triage-audit
-   skeletons with 5 + 3 + 3 phase files, reference data layer with SQLite
-   for work tracking and audit findings, cabinet member infrastructure with
-   output contract + committees + lifecycle, 7 scripts including triage UI,
-   interaction boundary documentation, default phase content using pib-db)
-6. **Document extension examples** — done (EXTENSIONS.md with annotated
-   Flow phase file overrides, accidentally-generic scan documenting 8
-   reusable patterns, cabinet member writing guide with 3 examples)
-7. **Lifecycle layer** — done (onboard skeleton for project adoption with
-   3-mode re-runnability, seed skeleton for capability seeding from tech
-   signals, upgrade skeleton for conversational box updates, cc-health
-   cabinet member for adoption monitoring, pib-db enhancements: status
-   tracking, tags, update-action command, migration logic)
+No config files, no YAML DSL, no template engine. Configuration uses:
 
-## Adopting Skeletons: Where Content Goes
+1. **Briefing files** — Project context that cabinet members read. Fill in
+   from the templates. Members reference sections by name.
+
+2. **Phase files** — Project-specific behavior for skeleton skills. Three
+   states: absent (use default), `skip: true` (disable), or content
+   (override).
+
+3. **Committee overlays** — `committees-project.yaml` extends upstream
+   committee definitions. `directives-project.yaml` extends upstream
+   member mandates and directives.
+
+4. **Environment variables** — For hooks and scripts. Telemetry hooks read
+   `TELEMETRY_DIR`, `TELEMETRY_FILE`. Database scripts read `PIB_DB_PATH`
+   (default: `./pib.db`). All have sensible defaults.
+
+## Skill Index
 
-When you adopt a skeleton — replacing a monolithic skill definition with
-the skeleton SKILL.md plus project-specific phase files — use these
-placement rules.
+The installer generates `.claude/skills/_index.json` at install time,
+caching metadata for all skills: name, description, type (workflow vs
+cabinet), standing mandates, scoped directives, and invocability flags.
+Consumers (`/menu`, `/cabinet`, orient, debrief, plan, execute,
+investigate, seed) read the index instead of scanning individual files.
+
+## Adopting Skeletons: Where Content Goes
 
 ### Skeleton SKILL.md (generic, lives in this package)
 
 - Orchestration (the sequence of phases and how they connect)
 - Phase protocol (the three-state table)
 - Identity (what the skill *is*)
-- Generic motivation (why this kind of skill exists — any project
-  recognizes the problem)
-- Boundary tables (generic: how this skill relates to other skeleton skills)
-- Assessment Log section (empty placeholder for runtime accumulation)
+- Generic motivation (why this kind of skill exists)
 - Calibration (without/with examples using generic scenarios)
-- Extending instructions (how to add phases, validators, checks)
 
 ### Phase files (project-specific)
 
 - Operational instructions (what to check, fix, report)
 - Specific commands (bash, file paths, API calls)
-- Specific file references (which files to count, verify, scan)
 - Domain logic (rotation tracking, drift detection, etc.)
-- Cadence and timing (when checks run relative to other steps)
-
-### Your project's SKILL.md (starts as skeleton copy, then extends)
-
-- Project frontmatter (`standing-mandate`, project-specific `related`
-  entries, `last-verified`)
-- Extended boundary tables: skeleton's generic rows PLUS rows for your
-  project-specific skills
-- Project-specific context that helps Claude understand *your*
-  deployment (but NOT operational instructions — those go in phases)
-
-### What stays outside phase files
-
-- **Runtime state** (e.g., `pulse-state.json`) stays alongside the
-  skill, not in `phases/`
-- **Contextual guidance** (boundary tables, identity) stays in SKILL.md
-- **Accumulation sections** (assessment logs) stay in SKILL.md
 
 ### The placement test
 
-1. Would a different project need this? → Skeleton SKILL.md
-2. Does it reference specific files, commands, or APIs? → Phase file
-3. Does it help Claude understand the skill but isn't executable? →
-   Your SKILL.md
-4. Does it accumulate over time? → SKILL.md section, not a phase
+1. Would a different project need this? -> Skeleton SKILL.md
+2. Does it reference specific files, commands, or APIs? -> Phase file
+3. Does it help Claude understand the skill but isn't executable? -> Your SKILL.md
+4. Does it accumulate over time? -> SKILL.md section, not a phase

package/templates/briefing/_briefing-template.md

@@ -74,19 +74,26 @@ Which cabinet members need which briefing files (identity is always loaded):
 | cc-health             |     |  x  |  x  |     |     |
 | data-integrity        |  x  |  x  |     |     |  x  |
 | debugger              |  x  |     |     |     |     |
-| record-keeper         |     |  x  |     |     |     |
+| framework-quality     |     |  x  |     |     |     |
+| goal-alignment        |     |     |     |     |     |
 | historian             |  x  |     |     |     |     |
-| process-therapist     |     |  x  |  x  |     |     |
-| small-screen          |     |  x  |     |     |     |
+| information-design    |     |  x  |     |     |     |
+| mantine-quality       |     |  x  |     |     |     |
 | organized-mind        |  x  |     |     |     |     |
-| speed-freak           |  x  |  x  |     |     |     |
-| workflow-cop          |     |  x  |     |     |     |
+| process-therapist     |     |  x  |  x  |     |     |
 | qa                    |  x  |  x  |     |     |     |
-| security              |  x  |  x  |     |     |  x  |
+| record-keeper         |     |  x  |     |     |     |
 | roster-check          |     |     |  x  |     |     |
-| system-advocate        |     |     |  x  |     |     |
+| security              |  x  |  x  |     |     |  x  |
+| small-screen          |     |  x  |     |     |     |
+| speed-freak           |  x  |  x  |     |     |     |
+| system-advocate       |     |     |  x  |     |     |
 | technical-debt        |  x  |     |     |     |     |
+| ui-experimentalist    |     |  x  |     |     |     |
 | usability             |     |  x  |     |     |     |
+| user-advocate         |     |  x  |     |     |     |
+| vision                |     |     |     |     |     |
+| workflow-cop          |     |  x  |     |     |     |
 
 ## Domain Extension Files
 

package/templates/cabinet/directives-project.yaml

@@ -0,0 +1,32 @@
+# Project-specific directive overlay for cabinet members.
+#
+# This file is project-owned — it is NOT overwritten by the installer.
+# Use it to extend upstream members with project-specific mandates and
+# directives for project-specific skills (e.g., /publish, /deploy).
+#
+# Consumed by: generateSkillIndex() in lib/cli.js (merged at install time
+# into _index.json alongside upstream frontmatter).
+#
+# Merge rules:
+#   - standing-mandate: APPENDED to upstream (union, no duplicates)
+#   - directives: MERGED with upstream (project wins on key conflict)
+#   - You cannot remove upstream mandates or directives from here
+#
+# Format:
+#
+#   cabinet-record-keeper:
+#     standing-mandate: [publish]
+#     directives:
+#       publish: >
+#         Check all docs for staleness and missing additions
+#         before the version is published.
+#
+#   cabinet-security:
+#     standing-mandate: [deploy]
+#     directives:
+#       deploy: >
+#         Review deployment config for exposed secrets and
+#         overly permissive access.
+#
+# The member name must match the directory name (e.g., cabinet-record-keeper).
+# Only cabinet-* members can be extended — workflow skills use phase files.

package/templates/cabinet/prompt-guide.md

@@ -220,6 +220,17 @@ Every cabinet member skill should have these sections:
 name: cabinet-{name}
 description: Rich 2-3 sentence description for ambient discovery
 user-invocable: false
+standing-mandate: audit, plan
+directives:
+  plan: >
+    One-sentence scoped task for this member during planning.
+  debrief: >
+    One-sentence scoped task for this member during debrief.
+files:
+  - "glob/pattern/*.ext"
+topics:
+  - keyword1
+  - keyword2
 ---
 
 # {Name}
@@ -229,9 +240,9 @@ What this expert thinks about. The analytical framework.
 What makes this cabinet member unique.
 
 ## Convening Criteria
-Files: glob patterns that trigger this cabinet member
-Topics: keywords that trigger this cabinet member
-Standing-mandate: which skill types always activate this cabinet member
+Files: glob patterns that trigger this cabinet member (also in frontmatter `files`)
+Topics: keywords that trigger this cabinet member (also in frontmatter `topics`)
+Standing-mandate: which contexts always activate this cabinet member (frontmatter `standing-mandate`)
 
 ## Research Method
 Where to get information, how to investigate, what to examine.

package/templates/skills/cabinet-record-keeper/SKILL.md

@@ -13,8 +13,12 @@ briefing:
 standing-mandate: audit, debrief
 directives:
   debrief: >
-    Review this session's changed files. Check if any CLAUDE.md,
-    system-status, briefing, or memory files now contain stale claims.
+    Own all documentation state updates for this session. Two jobs:
+    (1) Staleness — check if any CLAUDE.md, README, system-status,
+    briefing, or memory files now contain claims that became wrong.
+    (2) Additions — check if this session built, changed, or published
+    anything that should be recorded in those files but isn't yet
+    (new capabilities, version bumps, count changes, new conventions).
     Fix what you find — don't create findings.
 files:
   - CLAUDE.md
@@ -37,17 +41,22 @@ See `_briefing.md` for shared cabinet member context.
 ## Identity
 
 You verify that **every piece of documentation in this system accurately
-describes the current reality.** Stale docs are a force multiplier for
-confusion -- every Claude session starts by reading CLAUDE.md files and
-memory. If those are wrong, the session starts with wrong context, makes
-wrong assumptions, and compounds the drift.
-
-Documentation in this system isn't just for humans -- it's the operating
-system for AI sessions. CLAUDE.md files bootstrap understanding. Memory
-files persist context. Status docs track what's built. When any of these
-are wrong, the system's self-awareness degrades.
-
-There are two kinds of documentation problems:
+describes the current reality AND effectively guides people to use it.**
+Stale docs are a force multiplier for confusion -- every Claude session
+starts by reading CLAUDE.md files and memory. If those are wrong, the
+session starts with wrong context, makes wrong assumptions, and compounds
+the drift.
+
+Documentation in this system serves two audiences:
+- **Claude** -- CLAUDE.md files, memory, status docs, skill SKILL.md
+  files. These bootstrap AI understanding. When they're wrong, the
+  system's self-awareness degrades.
+- **Users** -- README, GETTING-STARTED, guides, inline help. These
+  teach people how to use the system. When they're unclear, incomplete,
+  or assume too much knowledge, people don't adopt features that exist
+  or use them wrong.
+
+There are three kinds of documentation problems:
 1. **The docs are wrong** -- the code has changed but the docs haven't
    been updated. Fix: update the docs.
 2. **The code has drifted from documented conventions** -- the docs
@@ -55,6 +64,10 @@ There are two kinds of documentation problems:
    Fix: either update the code to match, or update the convention to match
    reality. **You don't decide which -- you flag the divergence and let
    the human decide the direction.**
+3. **The docs are accurate but insufficient** -- everything they say is
+   true, but they don't say enough. A new user can't figure out what to
+   do next. A capability exists but nothing explains when or why to use
+   it. The user journey has gaps. Fix: write what's missing.
 
 ## Convening Criteria
 
@@ -113,6 +126,25 @@ Read all files in the project's memory directory:
 - Type definitions (see `_briefing.md` § App Source) that don't match actual
   API contracts
 
+### User-Facing Documentation
+
+User guides (README, GETTING-STARTED, workflow guides) serve a different
+audience than CLAUDE.md files. Check for:
+
+- **Journey completeness** -- can a new user go from install to
+  productive use without getting stuck? Is every phase of the user
+  journey documented: first install, first session, ongoing sessions,
+  when to use which skill, what the cabinet does for them?
+- **Assumed knowledge** -- do the docs assume familiarity with concepts
+  they haven't explained? "Standing mandates," "phase files," "skeleton
+  skills" mean nothing to someone who just installed.
+- **Feature discoverability** -- does every user-facing capability have
+  a path to being discovered? If a skill exists but no guide or menu
+  mentions it, it's invisible.
+- **Confidence gaps** -- after reading the docs, does the user know
+  what to do next? Uncertainty about "am I doing this right?" is a doc
+  failure, not a user failure.
+
 ### Convention Compliance
 
 CLAUDE.md files describe conventions. Check whether the codebase follows them.
@@ -136,6 +168,7 @@ grep -oP '`[^`]+\.(sh|js|ts|tsx|md|yaml|json)`' CLAUDE.md | \
 - `CLAUDE.md` -- Root system guide (highest priority)
 - `**/CLAUDE.md` -- All nested CLAUDE.md files
 - `system-status.md` -- Build status claims (if present)
+- `README.md`, `GETTING-STARTED.md`, workflow guides -- User-facing docs
 - The project's memory directory -- All memory files
 - Configuration files -- Entity type definitions, metadata files
 - See `_briefing.md § API / Server` -- Code comments, inline docs

package/templates/skills/debrief/SKILL.md

@@ -166,7 +166,36 @@ When closing an item that has documented follow-on work (sub-phases,
 next steps, future enhancements), create new items for each NOW. Known
 work that lives only in completed items' notes will be forgotten.
 
-### 3. Auto-Maintenance (core)
+### 3. Cabinet Consultations (core)
+
+Spawn cabinet members whose `standing-mandate` includes `debrief`.
+This runs early — right after inventory and work-item closing — so
+members can do their work (update docs, check state, verify lessons)
+before subsequent phases duplicate that effort.
+
+**Discovery:** Read `.claude/skills/_index.json` and filter to entries
+where `standingMandate` includes `"debrief"`. Each matching entry has
+a `directives.debrief` field — this is the scoped task for that member.
+If the index is missing, fall back to reading `cabinet-*/SKILL.md`
+frontmatter for `standing-mandate` and `directives`.
+
+**For each matching member**, spawn an agent with:
+- The member's full SKILL.md (read from the `path` in the index)
+- The session inventory from step 1 (what changed)
+- The member's `directives.debrief` as the task
+
+Spawn in parallel where possible. If a member has no directive for
+`debrief`, skip it — a standing mandate without a directive is a data
+error, not a reason to give the member an open-ended task.
+
+**Cost control:** These are lightweight passes, not full audits. Each
+agent should complete in under 2 minutes. If a member's directive
+produces no findings or changes, it returns silently. Include their
+results in the report only when they surfaced or changed something.
+
+If no cabinet members match, skip silently and proceed.
+
+### 4. Auto-Maintenance (core)
 
 Read `phases/auto-maintenance.md` for recurring automated tasks that
 should run at session end. Same principle as orient's auto-maintenance:
@@ -174,15 +203,27 @@ operations that decay if left to human memory.
 
 **Skip (absent/empty).**
 
-### 4. Update State (core)
+### 5. Update State (core)
 
 Read `phases/update-state.md` for what state files and documentation
 to update. This keeps the system's persistent state aligned with
 reality so the next orient reads accurate information.
 
-**Default (absent/empty):** Check whether `system-status.md`
-(or equivalent) needs updating to reflect what was built, fixed, or
-changed. Also check the user-level state below.
+**Division of labor with cabinet consultations (step 3):** If a
+record-keeper or similar doc-checking member ran in step 3, it owns
+all documentation updates — both staleness (wrong claims) and additions
+(missing claims). This step handles only what isn't doc work:
+- **User-level state** — preferences, registry entries (see below)
+- **Project-specific non-doc state** — whatever `phases/update-state.md`
+  defines beyond documentation
+
+If a record-keeper ran, don't duplicate its work on docs. If no
+record-keeper ran (no cabinet members, or none with a debrief mandate),
+fall back to the default below.
+
+**Default (absent/empty, no record-keeper):** Check whether
+`system-status.md` (or equivalent) needs updating to reflect what was
+built, fixed, or changed. Also check the user-level state below.
 
 #### User-Level State
 
@@ -197,7 +238,7 @@ needs updating:
   description still match reality? If the project has evolved
   significantly, propose updating the registry entry.
 
-### 5. Health Checks (core)
+### 6. Health Checks (core)
 
 Read `phases/health-checks.md` for end-of-session health checks. These
 verify that the session's work didn't break anything and that the system
@@ -205,7 +246,7 @@ is in a good state for next time.
 
 **Skip (absent/empty).**
 
-### 6. Persist Work
+### 7. Persist Work
 
 Commit and push the session's changes. Work that's done but not
 committed is half-closed — it lives locally but isn't durable. Persist
@@ -215,7 +256,7 @@ while lessons go to memory (which may live outside the repo).
 Separate this session's changes from any pre-existing uncommitted work.
 Don't silently bundle unrelated changes.
 
-### 7. Record Lessons (core)
+### 8. Record Lessons (core)
 
 Read `phases/record-lessons.md` for how to capture what was learned.
 This is the second irreducible purpose of debrief — the first is
@@ -255,7 +296,7 @@ in the debrief report:
 > different destinations (memory/feedback vs finding database). Both
 > feed the enforcement pipeline, but through different channels.
 
-### 8. Upstream Feedback (core)
+### 9. Upstream Feedback (core)
 
 Read `phases/upstream-feedback.md`. This is an **instruction phase**
 shipped with CC — it tells Claude to reflect on whether the session
@@ -272,7 +313,7 @@ what was confusing, what needed a workaround.
 
 **This phase should not be skipped.** It's how CC learns from use.
 
-### 9. Skill Discovery (core)
+### 10. Skill Discovery (core)
 
 Silently reflect: did this session involve a workflow the user is
 likely to repeat? Not every session produces one — most don't. But
@@ -303,7 +344,7 @@ generalizable pattern, cabinet member, or convention? If so, mention
 `/extract` as an option for proposing it upstream to CC. This is
 rarer than project-specific skills.
 
-### 10. Cabinet Check (core)
+### 11. Cabinet Check (core)
 
 Silently reflect: is this project's expertise coverage still right
 for what it's actually doing?
@@ -368,7 +409,7 @@ If the user says no, move on. Don't re-suggest the same gap next
 session. Track declined suggestions in system-status.md or equivalent
 so you don't nag.
 
-### 11. Capture Loose Ends (core)
+### 12. Capture Loose Ends (core)
 
 Read `phases/loose-ends.md` for non-project items and environmental
 concerns to capture before closing. Sessions generate non-project
@@ -377,30 +418,6 @@ these aren't captured somewhere, they rely on human memory.
 
 **Skip (absent/empty).**
 
-### 12. Cabinet Consultations (core)
-
-Spawn cabinet members whose `standing-mandate` includes `debrief`.
-
-**Discovery:** Read `.claude/skills/_index.json` and filter to entries
-where `standingMandate` includes `"debrief"`. Each matching entry has
-a `directives.debrief` field — this is the scoped task for that member.
-If the index is missing, fall back to reading `cabinet-*/SKILL.md`
-frontmatter for `standing-mandate` and `directives`.
-
-**For each matching member**, spawn an agent with:
-- The member's full SKILL.md (read from the `path` in the index)
-- The session inventory from step 1 (what changed)
-- The member's `directives.debrief` as the task
-
-Spawn in parallel where possible. If a member has no directive for
-`debrief`, skip it — a standing mandate without a directive is a data
-error, not a reason to give the member an open-ended task.
-
-**Cost control:** These are lightweight passes, not full audits. Each
-agent should complete in under 2 minutes. If a member's directive
-produces no findings or changes, it returns silently. Include their
-results in the report only when they surfaced or changed something.
-
 ### 13. Discover Custom Phases
 
 After running the core phases above, check for any additional phase
@@ -438,10 +455,10 @@ Phases are either **core** (maintain system state) or **presentation**
 (surface information for the user). For lightweight session closes,
 skip presentation phases. Core phases always run.
 
-- **Core phases** (always run): inventory, close-work, auto-maintenance,
-  update-state, health-checks, record-lessons, upstream-feedback,
-  skill-discovery, cabinet-check, loose-ends, cabinet-consultations,
-  persist work
+- **Core phases** (always run): inventory, close-work,
+  cabinet-consultations, auto-maintenance, update-state, health-checks,
+  persist-work, record-lessons, upstream-feedback, skill-discovery,
+  cabinet-check, loose-ends
 - **Presentation phases** (skippable): report
 
 A project that wants a quick debrief variant skips the report and