@qball-inc/the-bulwark 1.2.1 → 1.3.0

package/README.md

@@ -12,453 +12,175 @@
 
 <p align="center">
   <a href="#quick-install">Install</a> &middot;
-  <a href="#how-it-works">How it works</a> &middot;
-  <a href="#hooks">Hooks</a> &middot;
-  <a href="#skill-registry">Skills</a> &middot;
-  <a href="#agent-registry">Agents</a> &middot;
-  <a href="#planned-enhancements">Roadmap</a>
+  <a href="#common-workflows">Workflows</a> &middot;
+  <a href="#documentation">Docs</a> &middot;
+  <a href="docs/guides/how-it-works.md">How it works</a> &middot;
+  <a href="docs/roadmap.md">Roadmap</a>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@qball-inc/the-bulwark"><img src="https://img.shields.io/npm/v/@qball-inc/the-bulwark?label=npm" alt="npm version" /></a>
-  <a href="https://github.com/QBall-Inc/the-bulwark/releases/latest"><img src="https://img.shields.io/github/v/release/QBall-Inc/the-bulwark?label=release" alt="Latest GitHub release" /></a>
-  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/changelog-keep%20a%20changelog-orange" alt="Changelog" /></a>
+  <a href="https://www.npmjs.com/package/@qball-inc/the-bulwark"><img src="https://img.shields.io/npm/dm/@qball-inc/the-bulwark?label=downloads" alt="npm downloads" /></a>
+  <a href="https://github.com/QBall-Inc/plugins-market"><img src="https://img.shields.io/badge/dynamic/json?url=https://raw.githubusercontent.com/QBall-Inc/plugins-market/main/.claude-plugin/marketplace.json&query=$.plugins[0].version&label=marketplace&color=blue" alt="marketplace version" /></a>
+  <a href="https://github.com/QBall-Inc/the-bulwark/releases/latest"><img src="https://img.shields.io/github/v/release/QBall-Inc/the-bulwark?label=release&cacheSeconds=3600" alt="Latest GitHub release" /></a>
+  <a href="https://github.com/QBall-Inc/the-bulwark/commits/main"><img src="https://img.shields.io/github/last-commit/QBall-Inc/the-bulwark" alt="Last commit" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" /></a>
+  <a href="https://github.com/QBall-Inc/the-bulwark"><img src="https://img.shields.io/github/stars/QBall-Inc/the-bulwark?cacheSeconds=3600" alt="GitHub stars" /></a>
 </p>
 
 ---
 
-### If you find this useful, please give it a star. It helps others discover the project.
+## Latest stable release: v1.3.0
 
-[![GitHub stars](https://img.shields.io/github/stars/QBall-Inc/the-bulwark?style=social)](https://github.com/QBall-Inc/the-bulwark)
+**v1.3.0** (2026-06-23) — *Fewer prompts, sharper reviews.* This release cuts permission-prompt friction and makes code review smarter about what it's reviewing. Every bundled skill and agent now pre-authorizes exactly the tools it needs, so routine operations stop interrupting you for approval. The `code-review` skill is now **language-aware** — it detects each changed file's language and runs only the checks that apply, backed by universal per-language recipes that skip gracefully when a tool isn't installed. And a new **opt-in permission hook** (off by default) can auto-approve tool calls scoped to Bulwark's own bundled files, for users who want an even quieter workflow.
 
-## What is The Bulwark?
-
-The Bulwark is a [Claude Code plugin](https://docs.anthropic.com/en/docs/claude-code/plugins) that adds automated quality enforcement to your development workflow. It ships 30 skills, 15 custom agents, and a set of hooks that run programmatic checks on every code change you make.
-
-The Bulwark is the culmination of close to 6 weeks and 100 sessions of intense planning & research, co-partnered by Claude and myself. The goal was straightforward: take everything I'd learned running Claude Code over 8 months and package it into a governance layer that actually enforces standards instead of suggesting them.
-
-## Who is it for?
-
-- Builders who want to stay in the driver's seat while giving Claude semi-autonomy over structured workflows
-- Teams that need repeatable, auditable AI-assisted development
-- Users on Claude Max & Enterprise plans (the multi-agent pipelines are token-intensive)
-
-## Who is it not for?
-
-- While it can be used by those who prefer to run `--dangerously-skip-permissions` on Claude Code, this plugin may work with slight modifications, I do not recommend it
-- Users on Claude Free, Pro, or Pro Plus plans. The multi-agent orchestration burns through tokens fast, and rate limits on lower tiers will interrupt pipelines mid-execution.
-
-## Why?
+See the [v1.3.0 release notes](https://github.com/QBall-Inc/the-bulwark/releases/tag/v1.3.0) and the full [CHANGELOG](CHANGELOG.md).
 
-Claude Code is remarkably capable on its own. But capability without consistency is a problem.
-
-Without guardrails, you get:
-- Code that compiles but skips type checks, lint, or tests
-- Reviews that miss security issues because a single pass can't cover everything
-- Test suites full of mocks that verify function calls instead of real behavior
-- Plans and estimates that vary wildly between sessions
-
-The Bulwark fixes this by making enforcement automatic. Hooks run quality checks after every write. Skills orchestrate multi-agent pipelines where each agent has a single focus. Rules are injected at session start and enforced throughout. You don't have to remember to ask Claude to run tests or check types. It just happens.
+## What is The Bulwark?
 
-## Recent additions
+The Bulwark is a [Claude Code plugin](https://docs.anthropic.com/en/docs/claude-code/plugins) that adds automated quality enforcement to your development workflow. It ships **30 skills, 15 custom agents, and 8 hooks** that run programmatic checks on every code change you make.
 
-**v1.2.0** (2026-05-17) — Hardening + observability bundle
+Claude Code is remarkably capable on its own — but capability without consistency is a problem. Without guardrails you get code that skips type checks, reviews that miss issues a single pass can't cover, test suites full of mocks that verify calls instead of behavior, and estimates that vary wildly between sessions. The Bulwark makes enforcement **automatic**: hooks run quality checks after every write, skills orchestrate single-focus multi-agent pipelines, and rules are injected at session start and enforced throughout. You don't have to remember to ask Claude to run tests or check types — it just happens.
 
-- **2 new skills**: [`plan-to-tasks`](docs/skills/plan-to-tasks.md) (transforms `plan-creation` output into CLEAR-compatible task structure), [`spec-drift-check`](docs/skills/spec-drift-check.md) (mandatory pre-WP claim verification with PROCEED/STOP verdict)
-- **New `SD1` rule** + **`init --update` mode** for guided drift remediation when `CLAUDE.md` or `Rules.md` fall out of sync with canonical templates
-- **3 new/redesigned hooks**: `check-template-drift` (SessionStart), `cleanup-review-registry` (SessionStart), file-type-aware `suggest-pipeline-stop` with post-fix grace period
-- **`MultiEdit` now triggers quality enforcement** (previously only `Write` / `Edit`)
-- Skill schema migration across 15+ assets for stricter validator compliance
+**Who it's for:** builders who want to stay in the driver's seat while giving Claude semi-autonomy over structured workflows; teams that need repeatable, auditable AI-assisted development; users on Claude **Max or Enterprise** plans (the multi-agent pipelines are token-intensive — Pro Plus works for single-agent skills but hits rate limits on pipelines).
 
-Detail in the [v1.2.0 release notes](https://github.com/QBall-Inc/the-bulwark/releases/tag/v1.2.0) and full history in [CHANGELOG.md](CHANGELOG.md).
+→ For the design (defense-in-depth, multi-agent pipelines), see **[How it works](docs/guides/how-it-works.md)** and **[architecture.md](docs/architecture.md)**.
 
 ## Quick install
 
 Two ways to install. Pick whichever works for you.
 
-### Option A: npm
-
 ```bash
+# Option A — npm
 claude /plugin install npm:@qball-inc/the-bulwark
-```
-
-### Option B: Marketplace
 
-First, add the QBall-Inc marketplace (one-time setup):
-
-```bash
+# Option B — marketplace (one-time add, then install)
 claude /plugin marketplace add QBall-Inc/plugins-market
-```
-
-Then install:
-
-```bash
 claude /plugin install the-bulwark@qball-inc
 ```
 
-### Post-install
-
-After installing, restart your Claude Code session and run the init skill:
+After installing, restart your session and run the guided setup:
 
 ```
 /the-bulwark:init
 ```
 
-This walks you through a guided setup: Rules.md injection, CLAUDE.md configuration, and optional tooling (LSP, Justfile scaffolding, statusline). It auto-detects brownfield projects and adjusts accordingly.
-
-> Having trouble installing? See [FAQ and troubleshooting](#faq-and-troubleshooting). If your issue isn't covered, please [open an issue](https://github.com/QBall-Inc/the-bulwark/issues).
-
-## Prerequisites
-
-| Requirement | Details |
-|-------------|---------|
-| Claude Code | Latest version recommended. Plugin support required. |
-| Node.js | v18+ (for TypeScript tooling and `just` recipes) |
-| [just](https://github.com/casey/just) | Command runner used for build/typecheck/lint recipes. `/the-bulwark:init` offers to install it for you. |
-| Language Servers | TypeScript (`typescript-language-server`), Python (`pyright`), etc. The LSP setup within `/the-bulwark:init` will offer to install language servers for your project's languages. |
-| Platform | Linux, macOS, WSL2. Native Windows is not tested. |
-| Claude Plan | Max or Enterprise recommended. Pro Plus works for single-agent skills but will hit rate limits on multi-agent pipelines. |
+This walks you through Rules.md injection, CLAUDE.md configuration, and optional tooling (LSP, Justfile scaffolding, statusline), auto-detecting brownfield projects.
 
-## How it works
+Full walkthrough + prerequisites: **[Getting started](docs/guides/getting-started.md)**.
 
-The Bulwark has different orchestration models for coding and non-coding workflows.
+Trouble installing? See the **[FAQ](docs/faq.md)**.
 
-### Coding workflows
+## Adoption
 
-The coding side operates as a defense-in-depth system with three layers:
+The Bulwark is growing through word of mouth. These charts auto-update daily — GitHub clone traffic (top) and npm downloads (bottom), each shown daily and as a cumulative running total. Data is self-snapshotted to a [`traffic-stats`](https://github.com/QBall-Inc/the-bulwark/tree/traffic-stats) branch because GitHub purges clone traffic after 14 days.
 
-```mermaid
-flowchart TD
-    A[Session Start] --> B[Inject Governance Protocol]
-    B --> C[Rules.md Loaded]
-    C --> D[Claude/You Write Code]
-    D --> E{PostToolUse Hook}
-    E -->|typecheck| F{Pass?}
-    E -->|lint| F
-    E -->|build| F
-    F -->|No| G[Blocked - Fix Required]
-    G --> D
-    F -->|Yes| H[Change Accepted]
-    H --> I[Quality Governance Pipeline]
-    I --> I1[Code Review]
-    I1 --> I2[Test Audit]
-    I2 --> I3[Test Fixes]
-    I3 --> I4[Code Fixes]
-    I4 --> J{More Work?}
-    J -->|Yes| D
-    J -->|No| K[Session Handoff]
-    K --> L[Session Stop]
-```
-
-**Layer 1: Rules.** Injected into Claude's context at session start via the `SessionStart` hook. They define coding standards, testing requirements, and verification rules. Claude follows them because they're part of its active instructions, not because you asked nicely.
-
-**Layer 2: Hooks.** Run after every `Write` or `Edit` operation. The `enforce-quality.sh` hook fires `typecheck`, `lint`, and `build` checks. If any fail, the change is flagged and Claude sees the errors. No silent failures.
+<table>
+  <tr>
+    <td align="center"><img width="100%" alt="GitHub clones — last 14 days" src="https://raw.githubusercontent.com/QBall-Inc/the-bulwark/traffic-stats/clones.svg"></td>
+    <td align="center"><img width="100%" alt="GitHub clones — cumulative total" src="https://raw.githubusercontent.com/QBall-Inc/the-bulwark/traffic-stats/clones-cumulative.svg"></td>
+  </tr>
+  <tr>
+    <td align="center"><img width="100%" alt="npm downloads — daily" src="https://raw.githubusercontent.com/QBall-Inc/the-bulwark/traffic-stats/npm-downloads.svg"></td>
+    <td align="center"><img width="100%" alt="npm downloads — cumulative total" src="https://raw.githubusercontent.com/QBall-Inc/the-bulwark/traffic-stats/npm-downloads-cumulative.svg"></td>
+  </tr>
+</table>
 
-**Layer 3: Pipelines.** Multi-agent workflows orchestrated by skills. A code review spawns 3-4 specialized agents (security, type safety, standards, synthesis). A test audit classifies every test file and checks for mock abuse. Each agent writes structured output to `logs/`, and only a summary returns to the main context.
+## Common workflows
 
-### Non-coding workflows
+Each workflow chains skills into a repeatable pipeline. The diagrams are the shape; the linked guides have the detail and full sample prompts.
 
-The Bulwark also orchestrates research, brainstorming, and planning workflows that don't involve writing code. These run entirely through multi-agent pipelines.
-
-**Research.** The `/the-bulwark:bulwark-research` skill spawns 5 parallel sub-agents, each researching a different viewpoint on your topic. After a short user interview, agents run concurrently and their findings merge into a single synthesis document. Useful for market research, competitor analysis, or deep dives on technical topics before you commit to a direction.
-
-**Product Ideation.** The `/the-bulwark:product-ideation` skill spawns a full ideation team (6 agents) after a short user interview: market researcher, idea validator, competitive analyzer, segment analyzer, pattern documenter, and strategist. The pipeline produces a structured BUY/HOLD/SELL recommendation backed by evidence from each stage.
-
-**Brainstorm & Plan Creation.** These two skills share a dual-mode orchestration pattern. You choose the mode based on how contested the topic is:
+**Initialize** — set up governance in any project.
 
 ```mermaid
-flowchart TD
-    A[User Interview] --> B{Mode Selection}
-    B -->|Sequential| C[Task Tool Pipeline]
-    C --> C1[Role 1] --> C2[Role 2] --> C3[Role 3] --> C4[Critic]
-    C4 --> E[Structured Output]
-    B -->|Agent Teams| D[Peer Debate]
-    D --> D1[All Roles + Critic Run Concurrently]
-    D1 --> D2[Real-time Collaboration & Challenge]
-    D2 --> E
+flowchart LR
+    A["/the-bulwark:init"] --> B[Rules.md + CLAUDE.md] --> C[optional: LSP · Justfile · statusline]
 ```
 
-**Sequential mode.** Each role writes its output, then the next role reads it and builds on it. Structured, predictable, lower token cost. Best for well-understood topics where roles won't disagree much.
-
-**Agent Teams mode.** All roles run concurrently and debate in real-time. The Critic challenges assumptions as they form, not after they've hardened. Better convergence on contested topics, more token-intensive. Best for novel problems where you want genuine adversarial pressure on every claim.
-
-## Conventions
-
-The Bulwark enforces a specific set of conventions through `Rules.md`. When you run `/the-bulwark:init`, it installs these rules into your project at `.claude/rules/rules.md` where Claude Code automatically loads them every session. It also creates a `CLAUDE.md` with project-specific instructions (backing up any existing one first), and lets you choose scope — project-level (checked into the repo, shared with your team) or user-level (local to your machine, not committed).
-
-The rules cover four areas:
-
-**Coding Standards (CS1-CS4).** Single responsibility, no magic, fail fast, clean code. Every function does one thing. No hidden dependencies. Validate inputs at boundaries. Delete dead code instead of commenting it out.
-
-**Testing Rules (T1-T4).** Never mock the system under test. Verify observable output, not function calls. Integration tests use real systems. Write tests with implementation, not after. These four rules alone eliminate the most common failure modes in AI-generated test suites.
-
-**Verification Rules (V1-V4).** Never declare a fix complete without running it. Use `just` for all execution. Check logs for full output before attempting fixes. Verify compilation after every change.
-
-**Issue Debugging (ID1-ID3).** Understand the root cause before fixing. Rank complexity. Run the right level of tests. Document the debugging journey.
-
-Rules are not advisory. They're injected as binding instructions. Claude treats them as contract obligations, not suggestions.
-
-## Hooks
-
-The Bulwark installs eight hooks that run automatically. No manual invocation needed.
-
-| Hook | Event | Trigger | Timeout | What It Does |
-|------|-------|---------|---------|--------------|
-| `enforce-quality.sh` | PostToolUse | Every `Write`, `Edit`, or `MultiEdit` on code files | 60s | Runs `just typecheck`, `just lint`, `just build`. Flags failures to Claude with full error output. Skips non-code files (`tmp/`, `logs/`, `.claude/`, `docs/`). |
-| `suggest-pipeline-stop.sh` | Stop | End of every Claude turn | 30s | Suggests relevant review/audit pipelines based on session activity. File-type-aware routing, per-file registry, post-fix grace period to suppress redundant suggestions. |
-| `inject-protocol.sh` | SessionStart | Every new session | 5s | Injects the governance protocol into Claude's context. Loads Rules.md, activates quality enforcement, displays the activation banner. |
-| `cleanup-stale.sh` | SessionStart | Every new session | 30s | Deletes files older than 10 days from `logs/` and `tmp/`. Preserves `.gitkeep` files. Keeps your repo from accumulating stale pipeline output. |
-| `cleanup-review-registry.sh` | SessionStart | Every new session | 5s | Wipes stale review-accumulator state so pipeline gating works correctly across sessions. |
-| `check-template-drift.sh` | SessionStart | Every new session in a Bulwark-initialized project | 5s | Detects drift between project's `CLAUDE.md`/`Rules.md` and the canonical templates shipped with the current plugin version. Surfaces drifting sections for `/the-bulwark:init --update`. |
-| `track-pipeline-start.sh` | SubagentStart | Any sub-agent spawned | 30s | Logs pipeline invocation metadata (agent name, timestamp, parent context) for observability. |
-| `track-pipeline-stop.sh` | SubagentStop | Any sub-agent exits | 30s | Logs pipeline completion metadata (agent name, duration, exit status) for observability. |
-
-All hooks use `${CLAUDE_PLUGIN_ROOT}` for path resolution, so they work regardless of where the plugin is installed.
-
-## Skill registry
-
-The Bulwark ships 30 skills. Each one is invoked with `/the-bulwark:{skill-name}` or triggered automatically by hooks and pipelines. Skills are grouped by what they do.
-
-### Product & strategy
-
-Skills for ideation, research, and planning. These don't write code. They run multi-agent pipelines that produce structured documents.
-
-| Skill | What it does | Sub-agents |
-|-------|-------------|------------|
-| [product-ideation](docs/skills/product-ideation.md) | Evaluates product ideas through a 6-agent pipeline. Produces a BUY/HOLD/SELL recommendation with market analysis, competitive intelligence, and segment targeting. | [market-researcher](docs/agents/product-ideation-market-researcher.md), [idea-validator](docs/agents/product-ideation-idea-validator.md), [competitive-analyzer](docs/agents/product-ideation-competitive-analyzer.md), [segment-analyzer](docs/agents/product-ideation-segment-analyzer.md), [pattern-documenter](docs/agents/product-ideation-pattern-documenter.md), [strategist](docs/agents/product-ideation-strategist.md) |
-| [bulwark-research](docs/skills/bulwark-research.md) | Spawns 5 parallel sub-agents to research different viewpoints on a topic. Merges findings into a synthesis document. | 5 parallel Sonnet agents (dynamically created) |
-| [bulwark-brainstorm](docs/skills/bulwark-brainstorm.md) | Dual-mode brainstorming. `--scoped` runs 5 roles sequentially via Task tool. `--exploratory` runs 4 roles concurrently via Agent Teams with real-time peer debate. | Sequential: 5 role agents. Agent Teams: 4 concurrent agents + Critic. |
-| [plan-creation](docs/skills/plan-creation.md) | Creates implementation plans with a 4-role scrum team. Produces phases, workpackages, tasks, and delivery schedules. Dual-mode (Task tool or Agent Teams). | [PO](docs/agents/plan-creation-po.md), [Architect](docs/agents/plan-creation-architect.md), [Eng Lead](docs/agents/plan-creation-eng-lead.md), [QA/Critic](docs/agents/plan-creation-qa-critic.md) |
-| [plan-to-tasks](docs/skills/plan-to-tasks.md) | Transforms a `plan-creation` plan into CLEAR-compatible execution structure — `tasks.yaml` workpackage index plus per-WP YAML files. Supports parent/child plan linkage with bidirectional references. | None (single-context pipeline) |
-
-### Code quality
-
-Skills that review, test, and fix code. These are the enforcement layer that runs after you write code.
-
-| Skill | What it does | Sub-agents |
-|-------|-------------|------------|
-| [code-review](docs/skills/code-review.md) | Three-phase code review: static tools, LLM judgment across 3-4 aspects (security, type safety, standards), and diagnostic log. | 3-4 Sonnet agents (aspect-specific) |
-| [test-audit](docs/skills/test-audit.md) | Audits test suites for T1-T4 violations using AST analysis, mock detection, and multi-stage synthesis. Triggers automatic rewrites when quality gates fail. | Haiku (classification), Sonnet (mock detection, synthesis) |
-| [fix-bug](docs/skills/fix-bug.md) | 5-stage fix validation pipeline: analyze, implement, write tests, audit tests, validate fix. | [issue-analyzer](docs/agents/bulwark-issue-analyzer.md), [implementer](docs/agents/bulwark-implementer.md), [fix-validator](docs/agents/bulwark-fix-validator.md) |
-| [issue-debugging](docs/skills/issue-debugging.md) | Systematic debugging methodology with root cause analysis, impact mapping, tiered validation plans, and confidence assessment. | [issue-analyzer](docs/agents/bulwark-issue-analyzer.md), [fix-validator](docs/agents/bulwark-fix-validator.md) |
-| [spec-drift-check](docs/skills/spec-drift-check.md) | Audits a WP brief, plan doc, or memory entry for drift against current code state. Extracts claims, verifies each, emits PROCEED/STOP verdict. Mandatory Stage 0 (per `SD1` rule) of any new or resumed WP implementation. | None (single-context pipeline) |
-| [mock-detection](docs/skills/mock-detection.md) | Deep mock appropriateness analysis. Determines whether mocks in a test file are legitimate or T1-T4 violations. | Sonnet agent (analysis) |
-| [test-classification](docs/skills/test-classification.md) | Classifies test files by type (unit, integration, E2E) and identifies which files need deeper mock analysis. | Haiku agents (batch classification) |
-| [test-fixture-creation](docs/skills/test-fixture-creation.md) | Creates unbiased test fixtures using a Sonnet agent that can't read the implementation. Fixtures integrate with project infrastructure and hook automation. | Sonnet agent (fixture generation) |
-| [bulwark-verify](docs/skills/bulwark-verify.md) | Generates runnable verification scripts for components by orchestrating assertion-patterns and component-patterns. | Sonnet agent (script generation) |
-| [assertion-patterns](docs/skills/assertion-patterns.md) | Reference for transforming T1-T4 violating tests into real output verification. Loaded by other skills as context. | None (reference skill) |
-| [component-patterns](docs/skills/component-patterns.md) | Per-component-type verification approaches. Loaded by bulwark-verify as context for generating verification scripts. | None (reference skill) |
-| [bug-magnet-data](docs/skills/bug-magnet-data.md) | Curated edge case test data for boundary testing. Provides pre-organized data by type (dates, strings, numbers, Unicode, etc.) for test generation. | None (reference skill) |
-
-### Project setup & tooling
-
-Skills for initializing projects, configuring tooling, and managing sessions.
-
-| Skill | What it does | Sub-agents |
-|-------|-------------|------------|
-| [init](docs/skills/init.md) | Guided project initialization. Installs Rules.md, creates CLAUDE.md, offers LSP setup, Justfile scaffolding, and statusline configuration. Auto-detects brownfield projects. | None (orchestrates other skills) |
-| [bulwark-scaffold](docs/skills/bulwark-scaffold.md) | Generates Justfile with build/typecheck/lint recipes, creates logs directory, and optionally configures hooks. | None |
-| [setup-lsp](docs/skills/setup-lsp.md) | Configures Language Server Protocol integration. Detects project languages, offers to install language servers, verifies post-restart initialization. | None |
-| [bulwark-statusline](docs/skills/bulwark-statusline.md) | Configures the Claude Code status line to show token usage and cost in real-time. Supports preset switching and customization. | [statusline-setup](docs/agents/statusline-setup.md) |
-| [session-handoff](docs/skills/session-handoff.md) | Creates session handoff documents for context transfer between sessions. Ensures proper YAML headers, LF line endings, and complete documentation of progress and decisions. | None |
-| [governance-protocol](docs/skills/governance-protocol.md) | The governance protocol injected at session start via the SessionStart hook. Not invoked directly. | None |
-
-### Meta skills
-
-Skills for building more skills, orchestrating pipelines, and improving existing workflows.
-
-| Skill | What it does | Sub-agents |
-|-------|-------------|------------|
-| [create-skill](docs/skills/create-skill.md) | Generates Claude Code skills from requirements. Runs an adaptive interview, classifies complexity, and produces SKILL.md with references and templates. | Sonnet agent (validation) |
-| [create-subagent](docs/skills/create-subagent.md) | Generates single-purpose sub-agents for use via the Task tool. Produces agent definition with diagnostics and permissions setup. | Sonnet agent (validation) |
-| [continuous-feedback](docs/skills/continuous-feedback.md) | Parses past session learnings and memory files to identify improvement targets. Proposes concrete skill/agent modifications with copy-paste ready patches. | Sonnet agents (analysis, proposal generation) |
-| [anthropic-validator](docs/skills/anthropic-validator.md) | Validates Claude Code assets (skills, hooks, agents, plugins) against official Anthropic standards. Fetches latest docs dynamically. | [standards-reviewer](docs/agents/bulwark-standards-reviewer.md) |
-| [pipeline-templates](docs/skills/pipeline-templates.md) | Pre-defined workflow templates for multi-agent orchestration. Provides code review, fix validation, test audit, new feature, and research pipelines. | None (reference skill) |
-| [subagent-prompting](docs/skills/subagent-prompting.md) | Template for structured sub-agent invocation using 4-part prompting (GOAL/CONSTRAINTS/CONTEXT/OUTPUT) and F# pipeline notation. | None (reference skill) |
-| [subagent-output-templating](docs/skills/subagent-output-templating.md) | Template for structured sub-agent output including YAML log format and task completion reports. | None (reference skill) |
-
-## Agent registry
-
-Agents are single-purpose sub-agents spawned by skills via the Task tool. You don't invoke them directly. Each agent has a defined model, reads input from a previous pipeline stage, and writes structured output to `logs/`.
-
-### Fix validation agents
-
-| Agent | Model | Purpose | Invoked by |
-|-------|-------|---------|------------|
-| [bulwark-issue-analyzer](docs/agents/bulwark-issue-analyzer.md) | Sonnet | Root cause analysis, impact mapping, debug report with tiered validation plan | [fix-bug](docs/skills/fix-bug.md), [issue-debugging](docs/skills/issue-debugging.md) |
-| [bulwark-implementer](docs/agents/bulwark-implementer.md) | Opus | Implements fixes and features. Runs implementer-quality.sh after every write. | [fix-bug](docs/skills/fix-bug.md) |
-| [bulwark-fix-validator](docs/agents/bulwark-fix-validator.md) | Sonnet | Executes tiered test plan from the issue analyzer's debug report. Assesses fix confidence. | [fix-bug](docs/skills/fix-bug.md), [issue-debugging](docs/skills/issue-debugging.md) |
-| [bulwark-standards-reviewer](docs/agents/bulwark-standards-reviewer.md) | Sonnet | Validates Claude Code assets against official Anthropic standards. Produces severity-rated findings. | [anthropic-validator](docs/skills/anthropic-validator.md) |
-
-### Plan creation agents
+**Greenfield** — idea to executable plan. → [Feature development](docs/guides/feature-development.md)
 
-| Agent | Model | Purpose | Invoked by |
-|-------|-------|---------|------------|
-| [plan-creation-po](docs/agents/plan-creation-po.md) | Opus | Product Owner. Explores codebase, produces requirements analysis with scope, acceptance criteria, and user value. | [plan-creation](docs/skills/plan-creation.md) |
-| [plan-creation-architect](docs/agents/plan-creation-architect.md) | Opus | Technical Architect. Analyzes system design, component decomposition, integration points, and technical trade-offs. | [plan-creation](docs/skills/plan-creation.md) |
-| [plan-creation-eng-lead](docs/agents/plan-creation-eng-lead.md) | Sonnet | Engineering & Delivery Lead. Produces WBS, effort estimates, dependency graphs, milestones, and risk registers. | [plan-creation](docs/skills/plan-creation.md) |
-| [plan-creation-qa-critic](docs/agents/plan-creation-qa-critic.md) | Sonnet | QA / Critic. Adversarially challenges assumptions, stress-tests estimates, issues APPROVE/MODIFY/REJECT verdict. | [plan-creation](docs/skills/plan-creation.md) |
-
-### Product ideation agents
-
-| Agent | Model | Purpose | Invoked by |
-|-------|-------|---------|------------|
-| [product-ideation-market-researcher](docs/agents/product-ideation-market-researcher.md) | Sonnet | Researches market size, growth trends, key players, regulatory landscape. Produces TAM/SAM/SOM estimates. | [product-ideation](docs/skills/product-ideation.md) |
-| [product-ideation-idea-validator](docs/agents/product-ideation-idea-validator.md) | Sonnet | Assesses feasibility, timing, uniqueness, problem-solution fit. Produces PASS/CONDITIONAL/FAIL verdict. | [product-ideation](docs/skills/product-ideation.md) |
-| [product-ideation-competitive-analyzer](docs/agents/product-ideation-competitive-analyzer.md) | Sonnet | Profiles competitors, analyzes positioning and pricing, identifies market gaps using Porter's Five Forces. | [product-ideation](docs/skills/product-ideation.md) |
-| [product-ideation-segment-analyzer](docs/agents/product-ideation-segment-analyzer.md) | Sonnet | Identifies target user segments, builds personas using Jobs-to-be-Done, estimates willingness to pay. | [product-ideation](docs/skills/product-ideation.md) |
-| [product-ideation-pattern-documenter](docs/agents/product-ideation-pattern-documenter.md) | Sonnet | Documents success/failure patterns, competitor trajectories, and opportunity gaps from competitive data. | [product-ideation](docs/skills/product-ideation.md) |
-| [product-ideation-strategist](docs/agents/product-ideation-strategist.md) | Sonnet | Final synthesis. Produces BUY/HOLD/SELL recommendation with confidence level and actionable next steps. | [product-ideation](docs/skills/product-ideation.md) |
-
-### Utility agents
-
-| Agent | Model | Purpose | Invoked by |
-|-------|-------|---------|------------|
-| [statusline-setup](docs/agents/statusline-setup.md) | Haiku | Handles settings.json updates and config file placement for statusline configuration. | [bulwark-statusline](docs/skills/bulwark-statusline.md) |
-
-## FAQ and troubleshooting
-
-### Plugin clone fails with "Permission denied (publickey)"
-
-If you see this error when installing from the marketplace:
-
-```
-git@github.com: Permission denied (publickey).
-fatal: Could not read from remote repository.
+```mermaid
+flowchart LR
+    A[product-ideation] --> B[bulwark-research] --> C[bulwark-brainstorm] --> D[plan-creation] --> E[plan-to-tasks] --> F[implement]
 ```
 
-Your git is defaulting to SSH for GitHub, but you don't have SSH keys configured. Fix by telling git to use HTTPS:
+**Brownfield** — onboard onto an existing codebase. → [Feature development](docs/guides/feature-development.md)
 
-```bash
-git config --global url."https://github.com/".insteadOf "git@github.com:"
+```mermaid
+flowchart LR
+    A["subagent-prompting (map the codebase)"] --> B["planned: codebase & documentation understanding"] --> C[bulwark-research] --> D[bulwark-brainstorm] --> E[plan-creation] --> F[plan-to-tasks] --> G[implement]
 ```
 
-Then retry the install. This applies globally and redirects all GitHub SSH URLs to HTTPS.
+> The **codebase & documentation understanding** skill is [planned](docs/roadmap.md), not yet shipped — today, use `subagent-prompting` to map the code first.
 
-### Hooks aren't firing after install
+**New feature** — add to an existing plan. → [Research & planning](docs/guides/research-and-planning.md)
 
-Restart your Claude Code session. Hooks only load at session start. If they still don't fire, check that the plugin is installed:
-
-```bash
-claude /plugin list
+```mermaid
+flowchart LR
+    A[bulwark-research] --> B[bulwark-brainstorm] --> C["plan-creation (sub-plan linked to master)"] --> D[plan-to-tasks] --> E[implement]
 ```
 
-If `the-bulwark` appears in the list but hooks still don't run, check `hooks/hooks.json` exists in the plugin directory. The `${CLAUDE_PLUGIN_ROOT}` variable must resolve to the plugin's install location.
-
-### Quality gate keeps failing on non-code files
+**Analyze · Fix · Verify** — the issue lifecycle. → [Fixing bugs](docs/guides/fixing-bugs.md)
 
-The `enforce-quality.sh` hook skips files in `tmp/`, `logs/`, `.claude/`, `docs/`, and `node_modules/`. If you're editing a file outside these directories that isn't code (like a config file), the hook may still trigger. This is by design. If the failure is a false positive, check that your `Justfile` recipes handle the file type correctly.
-
-### Multi-agent pipelines time out or get interrupted
-
-This usually means you're hitting rate limits on your Claude plan. The product-ideation pipeline spawns 6 agents sequentially, and plan-creation can spawn 4. Each agent consumes tokens independently. Max and Enterprise plans handle this without issues. Pro Plus will work for single-agent skills but may hit limits on pipelines with 3+ agents.
-
-### `just` command not found
-
-The `/the-bulwark:init` skill offers to install `just` for you during setup. If you skipped that step, install it manually:
-
-```bash
-curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
+```mermaid
+flowchart LR
+    A["Analyze (issue-debugging)"] --> B["Fix (fix-bug)"] --> C["Verify (bulwark-fix-validator)"]
 ```
 
-Or via your package manager: `brew install just` (macOS), `cargo install just` (Rust), `apt install just` (Debian/Ubuntu).
-
-### Rules.md conflicts with my existing project rules
-
-The Bulwark installs its rules at `.claude/rules/rules.md`. If you already have rules in `.claude/rules/`, they won't be overwritten. The Bulwark's rules and your project rules both load at session start and coexist. If there's a conflict, your project-specific CLAUDE.md instructions take precedence since they load after the rules.
-
-### Can I use this with other Claude Code plugins?
-
-Yes. The Bulwark doesn't interfere with other plugins. Its hooks use `${CLAUDE_PLUGIN_ROOT}` for path resolution, so there's no collision. The only potential issue is if another plugin also installs PostToolUse hooks on Write/Edit, in which case both hooks run (Claude Code runs all matching hooks, not just the first one).
-
-### How do I update the plugin?
-
-Use the plugin update command:
-
-```bash
-claude plugin update the-bulwark@qball-inc
+```
+/the-bulwark:issue-debugging  Analyze the root cause of <symptom>; no code change.
+/the-bulwark:fix-bug          Fix <bug> end-to-end and prove the fix with tests.
+# Verify a fix you already applied: validate it against the debug report.
 ```
 
-You can also enable auto-updates per marketplace. Open `/plugin`, go to the Marketplaces tab, select the QBall-Inc marketplace, and toggle auto-update on. Note that auto-update is disabled by default for third-party marketplaces.
-
-If you installed via npm, the same update command works. Claude Code resolves the source from the installed plugin metadata.
-
-Your project's Rules.md and CLAUDE.md are not affected by updates since they live in your project repo, not in the plugin directory.
-
-### The statusline shows token usage but not cost
-
-Cost tracking depends on your Claude Code version and plan. If cost data isn't available from the API, the statusline falls back to showing token counts only. Run `/the-bulwark:bulwark-statusline` to reconfigure or switch presets.
-
-### I want to disable a specific hook temporarily
-
-You can't disable individual plugin hooks without modifying `hooks/hooks.json` in the plugin directory. But you can work around it by adding the file path to the skip list in `enforce-quality.sh`, or by working in a directory that the hook already skips (`tmp/`, `logs/`, etc.).
-
----
-
-## What's new in v1.2.0
-
-The first major post-launch bundle. v1.0.0 → v1.1.0 was a single hook redesign. v1.2.0 covers 13+ phases (P10.5 → P10.25) of hardening, observability, and workflow improvements that emerged from real-world dogfooding.
-
-### Spec drift enforcement
-
-`Rules.md` was a single document users could quietly let fall behind canonical templates. The new `SD1` (Spec Drift) rule makes a pre-WP drift check mandatory: before any new or resumed implementation, the [`spec-drift-check`](docs/skills/spec-drift-check.md) skill extracts every claim from the brief — file paths, line numbers, function names, behavioral assertions — and verifies each against current code. It emits a structured PROCEED/STOP verdict with a per-claim log. STOP requires explicit user sign-off before implementation begins. This eliminates an entire class of failures where a brief said "modify function `foo` at line 142" but the function had moved or been renamed three sessions ago.
-
-### `init --update` mode for stale CLAUDE.md / Rules.md
-
-A new SessionStart hook (`check-template-drift`) detects when your project's `CLAUDE.md` or `Rules.md` have drifted from the canonical templates and surfaces the diff for review. The new `/the-bulwark:init --update` flow walks you through accepting each drifting section, with batched/tabbed prompts when 4+ sections need review and full pre-flight visibility into what's about to change. Parent/child section anchors are handled correctly so nested sections never duplicate.
-
-### Plan → tasks workflow
-
-[`plan-to-tasks`](docs/skills/plan-to-tasks.md) closes the gap between [`plan-creation`](docs/skills/plan-creation.md) output (markdown plan with phases and workpackages) and execution-ready task tracking. It transforms a `plan_v{N}.md` into a `tasks.yaml` workpackage index plus per-WP YAML files, with bidirectional parent/child plan linkage. Parallel Sonnet sub-agents do the per-WP transform.
-
-### Stop hook redesign
-
-The `Stop` hook (`suggest-pipeline-stop`) is rebuilt around a per-file registry, file-type-aware pipeline routing (code vs test vs doc vs config), log-pattern suppression, and a post-fix grace period that prevents re-suggesting a pipeline immediately after a fix lands. False-positive pipeline suggestions on doc-only or test-only changes are gone.
-
-### Quality enforcement covers `MultiEdit`
-
-The `PostToolUse` matcher previously caught only `Write` and `Edit`. v1.2.0 widens it to `Write|Edit|MultiEdit` so the same typecheck/lint/build gates apply to bulk edits — `MultiEdit` was a silent quality escape hatch.
-
-### Other notable improvements
-
-- **Hook output schema validation** in `anthropic-validator` (catches hook output that violates Claude Code's hook contract before it ships)
-- **`bun` runtime installer** (`scripts/install-bun.sh`) — platform-aware, idempotent, scaffolded into the Justfile templates for the upcoming evaluation framework
-- **Statusline reliability**: `--no-optional-locks` flag avoids contention with concurrent git operations
-- **Schema migration across 15+ assets** for stricter `anthropic-validator` compliance
+## Documentation
 
----
+### Hooks
 
-## Planned enhancements
+Eight hooks run automatically — no manual invocation. All use `${CLAUDE_PLUGIN_ROOT}` for path resolution, so they work wherever the plugin is installed.
 
-These are on the roadmap. No timeline commitments, but they represent the direction The Bulwark is heading.
+| Hook | Event | What it does |
+|------|-------|--------------|
+| `enforce-quality.sh` | PostToolUse | Runs `just typecheck`/`lint`/`build` after every `Write`/`Edit`/`MultiEdit` on code; flags failures. Skips `tmp/`, `logs/`, `.claude/`, `docs/`. |
+| `suggest-pipeline-stop.sh` | Stop | Suggests relevant review/audit pipelines; file-type-aware, per-file registry, post-fix grace period. |
+| `inject-protocol.sh` | SessionStart | Injects the governance protocol; loads Rules.md; shows the activation banner. |
+| `cleanup-stale.sh` | SessionStart | Deletes `logs/`+`tmp/` files older than 10 days (preserves `.gitkeep`). |
+| `cleanup-review-registry.sh` | SessionStart | Wipes stale review-accumulator state so pipeline gating works across sessions. |
+| `check-template-drift.sh` | SessionStart | Detects `CLAUDE.md`/`Rules.md` drift from canonical templates; feeds `init --update`. |
+| `track-pipeline-start.sh` | SubagentStart | Logs pipeline invocation metadata for observability. |
+| `track-pipeline-stop.sh` | SubagentStop | Logs pipeline completion metadata for observability. |
 
-**Evaluation framework.** Skills and agents are the new code layer in agentic development. They need the same rigor as code: versioned, tested, measured. We're building two new skills — `create-eval` and `run-eval` — that generate and execute evaluations for any Claude Code asset. Define test prompts, expected outputs, and grading criteria. Run them across skill versions to catch regressions. Measure conversational invocation success, checklist compliance, and output quality with structured grading reports.
+The Bulwark also ships one **optional, opt-in** hook (off by default) that auto-approves access to its *own* bundled files, so Claude Code stops re-prompting for assets you already trusted at install — handy if you don't run in auto mode. Full detail, safety boundaries, and how to enable it: **[hooks reference](docs/reference/hooks.md)**.
 
-**Asset baselines.** Once the eval skills exist, we'll baseline all 30 skills and 15 agents with versioned evaluations. Every asset gets a `version` field in its frontmatter and a set of evals that serve as regression references. Future changes get measured against these baselines automatically.
+### Registries & guides
 
-**Enterprise traceability.** Enhanced logging with version stamps (skill version, model, rules hash) in every sub-agent log header. Run manifests that tie together all artifacts from a pipeline execution into a single auditable record. Decision lineage: trace any output back to which model, skill version, and rules produced it.
+- **[Skill registry](docs/reference/skills.md)** — all 30 skills, grouped (product & strategy · code quality · setup & tooling · meta)
+- **[Agent registry](docs/reference/agents.md)** — all 15 sub-agents, by pipeline
+- **[Conventions](docs/reference/conventions.md)** — the CS / T / V / ID rules `Rules.md` enforces
+- **Guides** — [Getting started](docs/guides/getting-started.md) · [How it works](docs/guides/how-it-works.md) · [Research & planning](docs/guides/research-and-planning.md) · [Feature development](docs/guides/feature-development.md) · [Fixing bugs](docs/guides/fixing-bugs.md)
 
-**Security pattern updates.** A helper skill that pulls the latest vulnerability patterns and edge cases into the test-audit pipeline. Keeps your security coverage current without manual curation.
+## FAQ & troubleshooting
 
-**Framework-specific Justfiles.** Auto-detect your project's framework (Next.js, Django, FastAPI, Actix, etc.) and generate tailored `just` recipes with the right build, test, and lint commands out of the box.
+Common install and runtime issues — SSH clone failures, hooks not firing, `just` not found, rate-limited pipelines, and more — are covered in the **[FAQ](docs/faq.md)**. If your issue isn't there, [open an issue](https://github.com/QBall-Inc/the-bulwark/issues).
 
-**Agent memory.** Persistent memory for sub-agents across invocations. Agents remember patterns from previous runs — common failure modes, project-specific conventions, recurring issues — and apply that context automatically.
+## Roadmap
 
-**Smarter pipeline routing.** Better orchestration for review-then-fix workflows. When a code review finds issues, automatically route to fix validation without manual intervention. Tighter feedback loops between review, fix, and retest stages.
-
----
+Language-aware code review, an evaluation framework for skills/agents, a codebase-understanding skill for brownfield onboarding, enterprise traceability, and more. No timeline commitments — see **[docs/roadmap.md](docs/roadmap.md)** for the direction.
 
 ## Releases & changelog
 
 - **Latest release**: [github.com/QBall-Inc/the-bulwark/releases/latest](https://github.com/QBall-Inc/the-bulwark/releases/latest)
-- **Full version history**: [CHANGELOG.md](CHANGELOG.md)
-- **npm releases**: [npmjs.com/package/@qball-inc/the-bulwark](https://www.npmjs.com/package/@qball-inc/the-bulwark)
+- **Full version history**: [CHANGELOG.md](CHANGELOG.md) — follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the project adheres to [SemVer](https://semver.org/spec/v2.0.0.html)
+- **npm**: [npmjs.com/package/@qball-inc/the-bulwark](https://www.npmjs.com/package/@qball-inc/the-bulwark)
 - **Update an installed plugin**: `claude plugin update the-bulwark@qball-inc`
 
-The changelog follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Each release on GitHub includes release notes plus a link to the corresponding CHANGELOG section.
+## Contributing
 
----
+Issues and PRs are welcome. The Bulwark is developed in a private repo and mirrored here, so contributions follow a specific porting model — see **[CONTRIBUTING.md](CONTRIBUTING.md)** before opening a PR. The fastest way to help: [open an issue](https://github.com/QBall-Inc/the-bulwark/issues) for a bug or feature request.
+
+## Credits
+
+Built with [`just`](https://github.com/casey/just) (Casey Rodarmor) and [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (Anthropic). Badges by [shields.io](https://shields.io).
 
 ## License
 
@@ -466,6 +188,8 @@ The changelog follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) a
 
 ---
 
-### If you find this useful, please give it a star. It helps others discover the project.
-
-[![GitHub stars](https://img.shields.io/github/stars/QBall-Inc/the-bulwark?style=social)](https://github.com/QBall-Inc/the-bulwark)
+<p align="center">
+  <em>If you find this useful, please give it a star — it helps others discover the project.</em>
+  <br /><br />
+  <a href="https://github.com/QBall-Inc/the-bulwark"><img src="https://img.shields.io/github/stars/QBall-Inc/the-bulwark?style=social" alt="GitHub stars" /></a>
+</p>