Crucible - Code review with enforcement for Claude Code

WHAT HAPPENS

crucible review --mode staged

→ Static analysis:  semgrep, ruff, bandit (or slither for Solidity)
→ Pattern rules:    30 bundled + your .crucible/assertions/
→ LLM assertions:   Semantic checks with token budget
→ Domain detection:  python, backend, api
→ Skills loaded:     backend-engineer, security-engineer
→ Knowledge loaded:  API_DESIGN.md, SECURITY.md, DATABASE.md

Claude receives:
  - Deduplicated findings from all tools
  - Enforcement results (pattern + LLM)
  - Your team's review checklists
  - Domain-specific context
      

Git-aware: review staged changes, branch diffs, or recent commits.
Suppression: // crucible-ignore: rule-id inline comments.

ENFORCEMENT

Not suggestions. Constraints. Assertions that block bad code.

# Claude writes code with shell=True
→ PostToolUse hook triggers
→ Crucible runs pattern assertions
→ no-shell-true detected

Exit 2 # Block + feedback to Claude

Claude sees:
  "Crucible found 1 issue in src/runner.py:
  [ERROR] no-shell-true: shell=True enables shell injection
    at src/runner.py:15:1"

Claude fixes the issue automatically.
      

PRE-COMMIT HOOK

crucible hooks install

Runs on every git commit

Blocks bad code at the gate

CLAUDE CODE HOOKS

crucible hooks claudecode init

PostToolUse + SessionStart

Blocks violations + injects context

30 BUNDLED RULES

Pattern + LLM assertions

eval, shell, pickle, reentrancy...

Add your own in .crucible/assertions/

THE FULL STACK

Enforcement at every stage. From spec to commit.

PRE-WRITE

Review specs before code exists

crucible prewrite review spec.md

Catch drift at the source

SESSION START

Context injected automatically

What's enforced + recent findings

Claude knows before you ask

WHILE-WRITE

PostToolUse hook on Edit|Write

Violations blocked in real-time

Fix before commit

PRE-COMMIT

Git hook blocks bad commits

crucible hooks install

Nothing escapes

THE PIPELINE

STATIC ANALYSIS

semgrep, ruff, bandit, slither

Auto-selected by domain

Findings deduplicated

ASSERTIONS

Pattern + LLM rules

"Enforce your conventions"

30 bundled + custom

SKILLS

Review personas

"How to think about this"

20 bundled. Add yours.

KNOWLEDGE

Patterns and principles

"What to look for"

14 bundled. Add yours.

PRE-WRITE

Spec review templates

"Validate before you build"

5 templates. PRD, TDD, RFC...

PLUG YOUR OWN

Encode your team's knowledge. Claude gets it automatically.

TEAM CONVENTIONS

API patterns, error handling, naming

→ .crucible/knowledge/

DOMAIN EXPERTISE

Crypto, fintech, healthcare, etc.

→ .crucible/skills/

CUSTOM RULES

Pattern assertions, lint rules

→ .crucible/assertions/

Bundled templates (20 skills, 14 knowledge files) are starting points.
The value is YOUR patterns, loaded when relevant.

SESSION CONTEXT

Claude knows what's enforced before you start.

# SessionStart hook auto-injects:

→ Enforcement summary:   Active assertions by priority
→ Team context:          .crucible/system/*.md files
→ Recent findings:       Issues from last review

# Add team context
crucible system init               # Create .crucible/system/ templates

# Creates:
  .crucible/system/team-patterns.md  # Team conventions
  .crucible/system/focus.md          # Current priorities
      

No explicit tool calls needed. Context arrives with the session.
Add .crucible/system/*.md files for team-specific context.

CASCADE RESOLUTION

Project overrides user overrides bundled. First found wins.

1. Project: .crucible/ ← Team patterns, checked into repo

2. User: ~/.claude/crucible/ ← Personal preferences

3. Bundled: ← Starter templates (package defaults)

Skills link to knowledge files. security-engineer auto-loads SECURITY.md.
Override any bundled file by creating your own with the same name.

MCP NATIVE

Designed to chain with other MCPs.

# Code review
review(path="src/")                    # Full review with skills + knowledge
review(mode="staged")                   # Git-aware: staged changes
review(mode="branch", base="main")      # PR diff review

# Pre-write review
prewrite_review(path="spec.md")         # Review spec against assertions
prewrite_list_templates()               # List available templates

# Context loading
get_assertions()                        # Load enforcement rules
load_knowledge(files=["SECURITY.md"])   # Load specific knowledge

# Chain with other MCPs via mcpmon
mcpmon --watch ~/.crucible/ -- crucible-mcp   # Hot reload on changes
      

mcpmon enables hot reload - edit skills/knowledge, changes load without restarting Claude Code.

PRE-WRITE REVIEW

Catch drift before code exists. Review specs, PRDs, and design docs.

# Create spec from template
crucible prewrite init prd my-feature.md

# Review against assertions
crucible prewrite review spec.md

# 5 bundled templates:
  prd.md            # Product requirements
  tdd.md            # Technical design
  rfc.md            # Request for comments
  adr.md            # Architecture decision record
  security-review.md
      

Pre-write assertions check for missing auth specs, undocumented failure modes,
compliance gaps. Validate intent before you build.

CLI

# Quick start
crucible init --with-claudemd           # Initialize project + minimal CLAUDE.md
crucible hooks install                  # Git pre-commit hook
crucible hooks claudecode init          # Claude Code hooks (PostToolUse + SessionStart)

# Review
crucible review                         # Staged changes (default)
crucible review --mode branch           # Branch vs main
crucible review src/file.py --no-git    # Single file without git

# Pre-write
crucible prewrite init prd my.md        # Create spec from template
crucible prewrite review spec.md        # Review spec against assertions

# Session context
crucible system init                    # Create .crucible/system/ templates
crucible system show                    # Preview what gets injected

# Customize
crucible skills init security-engineer  # Copy skill to .crucible/skills/
crucible knowledge init SECURITY        # Copy knowledge to .crucible/knowledge/
crucible assertions list                # List all assertion files
      

INSTALL

pip install crucible-mcp

Add to Claude Code:

{
  "mcpServers": {
    "crucible": {
      "command": "crucible-mcp"
    }
  }
}
      

With hot reload (recommended):

{
  "mcpServers": {
    "crucible": {
      "command": "mcpmon",
      "args": ["--watch", "~/.crucible/", "--", "crucible-mcp"]
    }
  }
}
      