Spec Files¶

Every wolverine-kit project has a spec/ directory. These files are user-owned and never overwritten by wk update.

INVARIANTS.md¶

Non-negotiable rules. The guardian BLOCKs any change that violates these. Each invariant should be specific enough to check by reading code or spec.

Good: "No bare print() outside ui.py" Bad: "Code should be clean"

DECISIONS.md¶

Binding architectural decision records (ADRs). One per choice. Format:

## ADR-NNN: Title

- **Decision**: what was decided
- **Rationale**: why this over alternatives
- **Rejected**: alternatives considered
- **Consequences**: what changes as a result

ARCHITECTURE.md¶

Module boundaries, dependencies, package structure. Defines what exists and how it connects. The spec-synthesizer uses this to produce implementation briefs.

VISION.md¶

Purpose, design principles, non-goals. The "why" behind the project. Helps the guardian distinguish intended behavior from accidental behavior.

NFR.md¶

Non-functional requirements: performance targets, security constraints, compatibility floors. Things that are hard to test but easy to violate.

ROADMAP.md¶

Phases and sequencing. What's done, what's open, what depends on what. The phase-tracker agent reads this.

SCENARIOS.md¶

Concrete use cases in Given/When/Then format. Validates that the design covers real workflows.

GLOSSARY.md¶

Canonical terminology. The glossary-steward checks for inconsistent usage across spec files.

DX.md / API.md¶

Public-facing surface. CLI commands, options, exit codes (DX.md) or API endpoints and contracts (API.md).