wolverine-kit 0.0.3

Spec Enforcement Toolkit for AI Coding Agents

Wolverine Kit

Constraint-first governance for AI-assisted development.

Named after the animal: tenacious, ferocious, holds ground against much larger opponents.

The Problem

AI coding agents make architectural decisions on the fly. Without guardrails, you get implementations that contradict each other, spec drift that nobody notices, and code that passes every test but violates the design. The usual fix is ceremony: twelve-role workflows, checklists on every PR, role-play prompts. It doesn't scale and people start ignoring it.

What This Does Instead

You write invariants before code. The framework enforces them. It stops at first failure.

uvx wolverine-kit init my-project --agent claude

That gives you a spec/ directory with constraint files, agents that enforce them, and slash commands that wire it together.

Project Layout

my-project/
├── spec/                         # Your constraints (never overwritten on update)
│   ├── INVARIANTS.md             # Hard rules the gatekeeper enforces
│   ├── DECISIONS.md              # Binding ADRs
│   ├── ARCHITECTURE.md           # Module boundaries
│   └── ...
├── .claude/agents/               # Governance agents (managed by wolverine-kit)
│   ├── wk-gatekeeper.md            # Veto gate: PASS / BLOCK / NEEDS-DECISION
│   ├── wk-spec-synthesizer.md    # Produces implementation briefs
│   ├── wk-drift-detector.md      # Finds spec-code divergence
│   └── ...
└── .claude/commands/             # Slash commands
    ├── wk-check.md               # Full hygiene sweep
    ├── wk-impl.md                # Gate chain + handoff
    └── ...

The Gate Chain

Every /wk-impl runs these steps in order. A failure at any step stops the chain.

1. Gatekeeper checks the proposal against invariants and ADRs. BLOCK = stop.
2. Spec-synthesizer produces a brief a senior dev could implement from. DRAFT = stop.
3. Test-author generates Given/When/Then test specs.
4. Handoff to Claude Code for implementation. Only runs if everything above passed.

PASS -> READY -> tests -> implement
BLOCK -> stop. Fix the spec or the proposal.
NEEDS-DECISION -> record it in DECISIONS.md, then re-run.

Install

# One-shot (no install needed)
uvx wolverine-kit init my-project

# Or install persistently
uv tool install wolverine-kit
wk init my-project --agent claude

Only prerequisite: uv.

Current support: Claude Code + Python projects. Other agents (Cursor, Kiro, Copilot) and language stacks are coming soon.

Commands

Command	What it does
/wk-check	Gatekeeper gate + glossary consistency sweep
/wk-impl <module>	Full gate chain, then implementation handoff
/wk-impl-brief <module>	Gatekeeper + implementation brief (no handoff)
/wk-test <module>	Generate test specifications
/wk-drift	Scan for spec-code divergence
/wk-decision <title>	Draft an ADR interactively, propagate it
/wk-deps	Audit dependencies for upgrades
/wk-status	Roadmap burn-down
/wk-review-spec	Architect review of spec quality
/wk-propagate <doc>	Fan a spec change across all downstream files
/wk-help	List all commands

How It Differs

Unlike ceremony-heavy frameworks (BMAD, etc.) that run multiple roles on every feature, Wolverine Kit triggers agents selectively and enforces hard invariants with machine verdicts. When the spec is ambiguous, it stops and escalates instead of guessing.

Compared to GitHub's Spec Kit (which focuses on the spec-to-implementation generation workflow), Wolverine Kit focuses on enforcement: blocking violations, catching drift, and escalating ambiguity. Spec Kit helps you write good specs and hand them off. Wolverine Kit makes sure nobody violates them after.

Principles

1. Invariants first. Write rules before code.
2. Stewardship over ceremony. Few agents, triggered selectively.
3. Stop at first failure. Partial gate chains produce false confidence.
4. Escalate, don't guess. Silence in the spec means stop, not invent.
5. Generic over prescriptive. Opinions about process, not tech stack.

Upgrading

wk update

Regenerates managed agent/command files from the latest templates. Your spec/ files are never touched.

Packs

Packs add tech-stack-specific agents:

wk init my-project --agent claude --pack python-library

Available now: python-library (adds a protocol validator). More coming.

License

MIT