Metadata-Version: 2.4
Name: wolverine-kit
Version: 0.0.3
Summary: Spec Enforcement Toolkit for AI Coding Agents
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: copier>=9.4
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.15
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: zensical>=0.0.40; extra == 'dev'
Description-Content-Type: text/markdown

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

```bash
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

```bash
# 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

```bash
wk update
```

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

## Packs

Packs add tech-stack-specific agents:

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

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

## License

MIT
