Skip to content

piv-loop.mdx

Latest commit

 

History

History
73 lines (63 loc) · 3.62 KB

piv-loop.mdx

File metadata and controls

73 lines (63 loc) · 3.62 KB
Raw
title PIV Loop - Plan / Implement / Validate
tagline Three-phase iterative loop with an explicit five-layer validation pyramid that draws an ownership line between agent and human.
attribution Cole Medin
tier framework
canonical_url https://github.com/coleam00/ai-transformation-workshop
setup_command # Pull the workshop's command pack into your project: gh repo clone coleam00/ai-transformation-workshop /tmp/piv mkdir -p .claude/commands cp /tmp/piv/.claude/commands/piv-*.md .claude/commands/ # Inside Claude Code: /piv-plan "Build feature X" /piv-implement /piv-validate
when_to_use Default for most "build a feature" work, anything with both a spec and a checkable test surface.
when_not_to_use Spike work where you don't yet know the spec.
tags
loop
validation
pyramid
claude-code
use_cases
building-features
bug-fixing
sources
title author url year
Principles of Agentic Engineering (workshop)
Cole Medin
2026
title author url year
How to build an agentic coding workflow, the PIV loop explained
MindStudio
2026
related
patterns antiPatterns practices glossary tools workflows
plan-execute-verify-commit
plan-and-execute
evaluator-optimizer
skipping-verification-because-it-looked-right
premature-victory-declaration
verify-everything
use-plan-mode-for-multi-file-changes
human-in-loop-checkpoints
plan-and-execute
plan-mode
claude-code
plan-approval-gate
evaluator-optimizer-loop
tdd-red-green-refactor-skills
loop
trigger steps gate exit
Task
Plan
Implement
Verify (5-layer)
Validation passes?
Ship

A three-phase loop, Plan → Implement → Validate, popularized by Cole Medin's Principles of Agentic Engineering workshop. The differentiator is the validation phase, which Medin codifies as a five-layer pyramid that explicitly draws an ownership line between agent and human:

  1. Lint + types, agent owns; iterates until clean
  2. Unit tests, agent owns; iterates until green
  3. Integration / E2E (browser automation), agent owns; iterates
  4. Code review, human (with AI assist)
  5. Manual testing, golden path + edges, human

The Plan phase loads context (Jira ticket, codebase tree, recent git log) and produces a written plan with a validation strategy baked in before any code. Constraints (what the agent must not change), edge cases, and success criteria are spelled out explicitly. The Implement phase is the agent doing its thing, the user's job is to set it up and stay out of the way.

The loop is iterative by design. When validation fails, the user feeds the specific failure back as a discrete fix prompt rather than re-running the full Implement phase.

The workshop ships 15 reusable Claude Code commands that drop into any project. The most-used:

Command Purpose
/piv-plan Generate the written plan from ticket + repo context
/piv-implement Execute the plan step by step
/piv-validate Run the 5-layer pyramid
/piv-fix Targeted fix when a validation layer fails
/piv-review Self-review against the original plan

(Full set: coleam00/ai-transformation-workshop/.claude/commands/.)

Use for any task with both a spec and a checkable test surface. PIV is the closest thing to a default daily-driver workflow for feature work.

Avoid for spike work where the spec doesn't yet exist, start with a scout pattern or a Plan & Act conversation first to nail down what you're building.