The Bulwark

SDLC governance & enforcement for Claude Code.
Turn stochastic AI output into engineering-grade artifacts.

Install · How it works · Hooks · Skills · Agents · Roadmap

---

If you find this useful, please give it a star. It helps others discover the project.

What is The Bulwark?

The Bulwark is a Claude Code plugin 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?

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.

Quick install

Two ways to install. Pick whichever works for you.

Option A: npm

claude /plugin install npm:@qball-inc/the-bulwark

Option B: Marketplace

First, add the QBall-Inc marketplace (one-time setup):

claude /plugin marketplace add QBall-Inc/plugins-market

Then install:

claude /plugin install the-bulwark@qball-inc

Post-install

After installing, restart your Claude Code session and run the init skill:

/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. If your issue isn't covered, please open an issue.

Prerequisites

Requirement	Details
Claude Code	Latest version recommended. Plugin support required.
Node.js	v18+ (for TypeScript tooling and just recipes)
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.

How it works

The Bulwark has different orchestration models for coding and non-coding workflows.

Coding workflows

The coding side operates as a defense-in-depth system with three layers:

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.

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.

Non-coding workflows

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:

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

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 28 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	Evaluates product ideas through a 6-agent pipeline. Produces a BUY/HOLD/SELL recommendation with market analysis, competitive intelligence, and segment targeting.	market-researcher, idea-validator, competitive-analyzer, segment-analyzer, pattern-documenter, strategist
bulwark-research	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	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	Creates implementation plans with a 4-role scrum team. Produces phases, workpackages, tasks, and delivery schedules. Dual-mode (Task tool or Agent Teams).	PO, Architect, Eng Lead, QA/Critic
plan-to-tasks	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	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	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	5-stage fix validation pipeline: analyze, implement, write tests, audit tests, validate fix.	issue-analyzer, implementer, fix-validator
issue-debugging	Systematic debugging methodology with root cause analysis, impact mapping, tiered validation plans, and confidence assessment.	issue-analyzer, fix-validator
spec-drift-check	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	Deep mock appropriateness analysis. Determines whether mocks in a test file are legitimate or T1-T4 violations.	Sonnet agent (analysis)
test-classification	Classifies test files by type (unit, integration, E2E) and identifies which files need deeper mock analysis.	Haiku agents (batch classification)
test-fixture-creation	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	Generates runnable verification scripts for components by orchestrating assertion-patterns and component-patterns.	Sonnet agent (script generation)
assertion-patterns	Reference for transforming T1-T4 violating tests into real output verification. Loaded by other skills as context.	None (reference skill)
component-patterns	Per-component-type verification approaches. Loaded by bulwark-verify as context for generating verification scripts.	None (reference skill)
bug-magnet-data	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	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	Generates Justfile with build/typecheck/lint recipes, creates logs directory, and optionally configures hooks.	None
setup-lsp	Configures Language Server Protocol integration. Detects project languages, offers to install language servers, verifies post-restart initialization.	None
bulwark-statusline	Configures the Claude Code status line to show token usage and cost in real-time. Supports preset switching and customization.	statusline-setup
session-handoff	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	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	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	Generates single-purpose sub-agents for use via the Task tool. Produces agent definition with diagnostics and permissions setup.	Sonnet agent (validation)
continuous-feedback	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	Validates Claude Code assets (skills, hooks, agents, plugins) against official Anthropic standards. Fetches latest docs dynamically.	standards-reviewer
pipeline-templates	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	Template for structured sub-agent invocation using 4-part prompting (GOAL/CONSTRAINTS/CONTEXT/OUTPUT) and F# pipeline notation.	None (reference skill)
subagent-output-templating	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	Sonnet	Root cause analysis, impact mapping, debug report with tiered validation plan	fix-bug, issue-debugging
bulwark-implementer	Opus	Implements fixes and features. Runs implementer-quality.sh after every write.	fix-bug
bulwark-fix-validator	Sonnet	Executes tiered test plan from the issue analyzer's debug report. Assesses fix confidence.	fix-bug, issue-debugging
bulwark-standards-reviewer	Sonnet	Validates Claude Code assets against official Anthropic standards. Produces severity-rated findings.	anthropic-validator

Plan creation agents

Agent	Model	Purpose	Invoked by
plan-creation-po	Opus	Product Owner. Explores codebase, produces requirements analysis with scope, acceptance criteria, and user value.	plan-creation
plan-creation-architect	Opus	Technical Architect. Analyzes system design, component decomposition, integration points, and technical trade-offs.	plan-creation
plan-creation-eng-lead	Sonnet	Engineering & Delivery Lead. Produces WBS, effort estimates, dependency graphs, milestones, and risk registers.	plan-creation
plan-creation-qa-critic	Sonnet	QA / Critic. Adversarially challenges assumptions, stress-tests estimates, issues APPROVE/MODIFY/REJECT verdict.	plan-creation

Product ideation agents

Agent	Model	Purpose	Invoked by
product-ideation-market-researcher	Sonnet	Researches market size, growth trends, key players, regulatory landscape. Produces TAM/SAM/SOM estimates.	product-ideation
product-ideation-idea-validator	Sonnet	Assesses feasibility, timing, uniqueness, problem-solution fit. Produces PASS/CONDITIONAL/FAIL verdict.	product-ideation
product-ideation-competitive-analyzer	Sonnet	Profiles competitors, analyzes positioning and pricing, identifies market gaps using Porter's Five Forces.	product-ideation
product-ideation-segment-analyzer	Sonnet	Identifies target user segments, builds personas using Jobs-to-be-Done, estimates willingness to pay.	product-ideation
product-ideation-pattern-documenter	Sonnet	Documents success/failure patterns, competitor trajectories, and opportunity gaps from competitive data.	product-ideation
product-ideation-strategist	Sonnet	Final synthesis. Produces BUY/HOLD/SELL recommendation with confidence level and actionable next steps.	product-ideation

Utility agents

Agent	Model	Purpose	Invoked by
statusline-setup	Haiku	Handles settings.json updates and config file placement for statusline configuration.	bulwark-statusline

FAQ and troubleshooting

Plugin clone fails with "Permission denied (publickey)"

If you see this error when installing from the marketplace:

[email protected]: Permission denied (publickey).
fatal: Could not read from remote repository.

Your git is defaulting to SSH for GitHub, but you don't have SSH keys configured. Fix by telling git to use HTTPS:

git config --global url."https://github.com/".insteadOf "[email protected]:"

Then retry the install. This applies globally and redirects all GitHub SSH URLs to HTTPS.

Hooks aren't firing after install

Restart your Claude Code session. Hooks only load at session start. If they still don't fire, check that the plugin is installed:

claude /plugin list

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

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:

curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin

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:

claude plugin update the-bulwark@qball-inc

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

---

Planned enhancements

These are on the roadmap. No timeline commitments, but they represent the direction The Bulwark is heading.

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.

Asset baselines. Once the eval skills exist, we'll baseline all 28 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.

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.

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.

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.

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.

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.

---

Releases & changelog

• Latest release: github.com/QBall-Inc/the-bulwark/releases/latest
• Full version history: CHANGELOG.md
• npm releases: npmjs.com/package/@qball-inc/the-bulwark
• Update an installed plugin: claude plugin update the-bulwark@qball-inc

The changelog follows Keep a Changelog and the project adheres to Semantic Versioning. Each release on GitHub includes release notes plus a link to the corresponding CHANGELOG section.

---

License

MIT

---

If you find this useful, please give it a star. It helps others discover the project.