piv-speckit: PIV Spec-Kit: The Zero-Tolerance Framework for AI-Driven Development

Moving beyond vibe coding with an automated Prime-Implement-Validate loop that deletes code if it lacks a failing test.

A heavy mechanical press poised over an unsupported bridge, held back only by a small, sturdy stone representing a test. — The Zero-Tolerance gate: Code without a test gets crushed.

Key Takeaways

The framework enforces a zero-tolerance policy that deletes implementation code if a failing test does not exist.
PIV Spec-Kit replaces monolithic prompts with a structured workflow of markdown-based specifications, plans, and atomic tasks.
The system prevents context drift by generating reference-based context sieves instead of feeding entire codebases into the LLM.
An adaptive learning mechanism records recurring bugs to evolve local coding standards and prevent future anti-patterns.

The Delete Key as a Feature

The era of letting an LLM write 500 lines of code from a single prompt is hitting a wall. Developers are realizing that unstructured generation creates a maintenance nightmare. PIV Spec-Kit is the anti-vibe framework. It treats the AI as a junior developer who cannot be trusted to touch the codebase without a signed-off plan and a failing test.

This repository enforces a strict, programmatic zero-tolerance policy. If the AI agent writes implementation code before a failing test exists, the framework deletes it. This radical architectural choice reframes the relationship from magic assistant to disciplined apprentice.

The Red-Green-Refactor state machine blocks implementation code until tests fail.

Architecture of the PIV Loop

The framework functions as a workflow engine that forces AI agents like Claude Code to follow a specific lifecycle known as PIV: Prime, Implement, and Validate. This solves the context drift problem inherent in long chat sessions.

During the Prime phase, the system generates a reference-based context instead of dumping the entire codebase into the prompt. The Implement phase executes a strict TDD loop. Finally, the Validate phase acts as a multi-level safety gate, checking for test coverage and security flaws before allowing a commit.

A vast library of books being fed into a funnel, with a mechanical arm picking out only specific bookmarks. — The Auto-Prime phase loads only relevant context to save tokens and maintain focus.

Context Engineering: The Artifact-First Workflow

PIV Spec-Kit transitions away from monolithic prompts by splitting a single idea into three distinct Markdown files. The specification defines the requirements, the plan dictates the architecture, and the tasks document outlines the atomic steps.

Standard AI Coding	PIV Spec-Kit
Vague, single-shot prompts	Structured Markdown specs
Code-first execution	Test-first execution
Context drift over time	Auto-context priming
Manual testing and review	Multi-level automated validation

The Self-Correcting Codebase

The system includes an adaptive learning mechanism. After a code review, the framework parses previous errors to find recurring bugs and anti-patterns. It records these lessons in a dedicated metrics file.

Over time, the framework identifies these recurring mistakes and updates its own rules. This localized evolution of coding standards ensures the development environment adapts to the team's specific technical debt patterns.