piv-speckit

PIV Spec-Kit

PIV (Prime-Implement-Validate) + Spec-Kit: Structured specs, strict TDD, for AI-assisted development.

Zero-setup workflow - just run /piv-speckit:plan-feature and context loads automatically!

A Claude Code plugin for structured AI-assisted development.

---

What is PIV?

PIV = Prime → Implement → Validate

A development methodology for AI-assisted software development:

• Prime (Auto): Context loads automatically when planning
• Implement: Write tests FIRST (strict TDD), then minimal code
• Validate: Automatic testing and verification

→ Interactive Visual Guide | → Full Methodology | → Changelog

---

Enhanced with Spec-Kit

This framework integrates best practices from GitHub's Spec-Kit, adding structured specification artifacts to the PIV methodology.

What This Adds

Artifact	Purpose	Created By
spec.md	Functional requirements (WHAT)	/piv-speckit:plan-feature
plan.md	Technical approach (HOW)	/piv-speckit:plan-feature
tasks.md	Implementation steps (DO)	/piv-speckit:plan-feature
quickstart.md	TL;DR for humans	/piv-speckit:plan-feature
prime-context.md	Codebase context (auto-generated)	Auto-prime in plan-feature

Artifact Format

All artifacts are structured Markdown - human-readable and version-controlled.

---

Installation

# Add marketplace
/plugin marketplace add galando/piv-speckit

# Install PIV + Spec-Kit
/plugin install piv-speckit

Commands: /piv-speckit:plan-feature (auto-primes), /piv-speckit:execute, /piv-speckit:prime (optional)

Features: Auto-activating skills (TDD, code-review, security), full reference docs, agent context system.

---

Architecture & Workflow

Complete Development Flow

┌─────────────────────────────────────────────────────────────────────────────┐
│                      PIV SPEC-KIT WORKFLOW                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  1. PLAN (Auto-Primes + Structured Specs)                                  │
│     ┌─────────────────────────────────────────────────────────────────┐    │
│     │ /piv-speckit:plan-feature "Add user authentication"              │    │
│     │                                                                  │    │
│     │ → Auto-prime: loads/refreshes context silently                  │    │
│     │ → Creates .claude/specs/{feature}/                              │    │
│     │   ├─ spec.md        (WHAT: requirements, user stories)          │    │
│     │   ├─ plan.md        (HOW: architecture, data model, APIs)       │    │
│     │   ├─ tasks.md       (DO: step-by-step implementation)          │    │
│     │   └─ quickstart.md  (TL;DR: quick reference)                   │    │
│     └─────────────────────────────────────────────────────────────────┘    │
│                                    ↓                                        │
│  2. IMPLEMENT (Strict TDD)                                               │
│     ┌─────────────────────────────────────────────────────────────────┐    │
│     │ /piv-speckit:execute .claude/specs/{feature}/tasks.md              │    │
│     │                                                                  │    │
│     │   For each task:                                                 │    │
│     │   ├─ RED:   Write failing test first                            │    │
│     │   ├─ GREEN: Write minimal code to pass                          │    │
│     │   └─ REFACTOR: Improve while tests stay green                   │    │
│     │                                                                  │    │
│     │   Skills auto-activate: TDD, code-review, security              │    │
│     └─────────────────────────────────────────────────────────────────┘    │
│                                    ↓                                        │