PCV: Plan-Construct-Verify

Structured planning discipline for Claude Code projects

NC State · ISE

What is PCV?

PCV is a skill for Claude Code that enforces a planning gate before any work begins. Describe your idea — PCV surfaces design decisions, records your choices, then builds and verifies the result against the approved plan.

PlanClarify & decide
→
ConstructBuild per plan
→
VerifyCheck & confirm

Prerequisites

Claude Code must be installed and working. PCV is a Claude Code skill — it runs inside Claude Code, not separately. Install Claude Code first if you haven’t already.

Installation

  1. Download the bootstrap file.
    Save bootstrap.md to any convenient location.
  2. Give it to Claude Code.
    Start a Claude Code session and say:
    Read [path-to-bootstrap.md] and follow the installation instructions inside it.
  3. Confirm the installation.
    Claude Code installs the skill files and agent definitions and reports success.

Updating. Download a fresh bootstrap.md and repeat the steps above. The installer only overwrites if the new version is higher.

Quick Start

  1. Create a project directory and open Claude Code in it.
  2. Type /pcv — PCV scaffolds the workspace (idea.md, charge.md template, settings).
  3. Describe your idea in idea.md — what you’re building, constraints, success criteria. Tell Claude you’re ready.
  4. Answer clarifying questions. PCV asks one at a time, then runs an adversarial review and presents a charge for your approval.
  5. Review and approve the plans. PCV writes finalized plan files on your approval, then begins construction.
  6. PCV builds and verifies. Optional hands-on acceptance testing before closeout.

When to Use

Good fit

  • Multi-component software projects
  • Visual interfaces (GUIs, dashboards)
  • Documents with domain-specific requirements
  • Mathematical formulations and analytical models
  • Multi-phase projects with sequential dependencies

Simpler option

  • Small projects (1–3 components) → PCV Lite: compressed 2-gate workflow, single plan document

Probably overkill

  • Quick scripts or one-off utilities
  • Simple bug fixes
  • Exploratory work with no clear goal

Four Deliverable Patterns

PCV adapts planning, construction, and verification to the deliverable type:

#PatternExampleVerification
1CodeApplications, packages, data pipelinesAutomated tests, compilation, runtime
2ProseSOPs, reports, documentationStructural review, completeness
3MathematicalLP/MIP formulations, analytical modelsCorrectness, constraint satisfaction
4Design & RenderDashboards, HTML displays, visualizationsVisual comparison to wireframe

See Reference for details on the subagent architecture, adaptive agent configuration, multi-phase projects, PCV Lite, deployment, and troubleshooting.

Version History

VersionDateSummary
3.14 2026-04-18 Protocol Reliability: mechanical gate handlers (M1–M8) replace prose conditional logic with deterministic shell scripts using announce + execute UX. Hook-written session-state.json sentinel eliminates env-var checks scattered across protocol prose. gate-context.json emitted at all 24 gates for future agent-as-user interop. Conflict-audit-driven prose reconciliation (Gate Protocol scope clause for judgment vs. mechanical). --repeat N=3 flag on run-all.sh for integration verification. Default permission expansion eliminates repetitive approval prompts for temp-dir and PCV-internal operations.
3.13 2026-04-15 Usability: plans/ renamed to pcvplans/ (breaking change); charge.md moves into pcvplans/; pcv_idea.md scaffolded in project root then relocated to pcvplans/idea.md after charge generation. Gate prompts include help footer. Interop feasibility assessment for future agent/skill assistance at gates.
3.12 2026-04-14 Automated testability: PCV_AUTO_APPROVE env var for gate auto-approval, PCV_TEST_RESPONSES for pre-scripted clarification answers with phase-scoped keys, [MILESTONE:*] tags on decision log headers, [TEST] prefix on test-mode entries. Regression test harness with Tier 1 (deterministic) and Tier 2 (LLM-in-the-loop) validation.
3.11 2026-04-14 Hook-based architecture migration (6 phases). Deterministic operations moved from protocol prose to bash hook scripts: reliability hooks (Stop, SessionStart, PreCompact, SubagentStop), routing dispatch, permissions and format enforcement (scaffold-settings.sh, tech-permissions-scan.sh, validate-pcv-format.sh, post-tool-use-format.sh). Protocol compressed to spine + fragment architecture (48% reduction). Scope-creep detection and persistence assurance rules. Token and speed optimization: always-loaded context reduced 27%, fragment mergers, shared pcv-lib.sh helpers, jq fast-path with auto-provisioning, deliverable surfacing, compact decision log format.
3.10 2026-04-05 PCV Lite compressed workflow, deployment/documentation checklist, auto-generated project summary, global settings check at bootstrap.
3.9 2026-03-28 Multi-phase project support, three entry paths, phase transition protocol, cross-phase learning.
3.8 2026-03-28 Plan tier declaration, adaptive agent configuration, inline research option, economy configurations.
3.7 2026-03-26 Bash safety rules in construction and builder protocols.
3.6 2026-03-24 Subagent architecture (critic, research, builder, verifier agents), bootstrap installer.