PCV Reference

Contents

Why This Workflow

When you ask an AI coding assistant to build software directly from a description, the AI makes dozens of implicit decisions — which packages to use, how components connect, what the interfaces look like, how errors are handled, what the GUI layout looks like. Many of these decisions are reasonable in isolation but don’t match what you intended. You discover this after the code is written, leading to costly rework or starting over.

The gap between “what you want software to do” and “the complexity of making it work in code” is where this workflow adds value. Package ecosystems, interface contracts, dependency management, build systems, runtime environments, GUI frameworks, testing infrastructure, data flow, and compatibility with existing code all create opportunities for the AI to guess wrong. Planning surfaces these decisions explicitly so you can make them before anything is built.

PCV separates deciding what to build from building it. During planning, Claude Code works with you to make decisions explicitly — surfacing trade-offs, asking you to choose, and recording the rationale. The result is a detailed plan that Claude Code then executes without guessing.

What PCV Adds Beyond Native Claude Code

Claude Code is already highly capable. PCV adds specific capabilities that native Claude Code does not provide on its own:

1. Sequential clarification. One question at a time, dependency-ordered, so each answer can inform subsequent questions. Native Claude Code tends to ask batched questions or skip clarification entirely.
2. Adversarial review. A separate Critic agent (running in its own context window) challenges the plan before you approve it, catching assumptions, contradictions, and gaps.
3. Human approval gates. Three explicit gates (MakePlan, planning artifacts, ConstructionPlan) where you review and approve before construction begins. Nothing is built without your sign-off.
4. Auditable decision trail. A verbatim decision log records every question, answer, and interpretation — useful for reviewing how decisions were made and for educational purposes.
5. Pattern-specific verification. Verification is tailored to the deliverable type: automated tests for code, structural review for prose, correctness checks for math, visual comparison for design.
6. Prior work analysis. When building on existing code or documents, a dedicated research agent analyzes your prior work in an isolated context and returns a structured assessment to determine the right scope — from verification-only to full rewrite — with guards against both over- and under-scoping.
7. Planning artifact gates. Wireframes, mathematical formulations, and test specifications are reviewed and approved before construction, preventing the costly rework that comes from building first and discovering misalignment later.
8. Adaptive agent configuration. PCV proposes economy or full agent configurations based on project complexity, with mid-project revision if the initial configuration proves insufficient.
9. Multi-phase project support. Projects with sequential dependencies can be structured as multiple phases, each a full PCV cycle, with cross-phase learning and coordinated phase transitions.
10. PCV Lite. A compressed two-gate workflow for simple projects — single combined plan, inline construction, streamlined verification. The critic still reviews independently. PCV proposes Lite when the project is straightforward.
11. Deployment awareness. When the charge specifies a deployment target (GitHub Pages, npm, etc.), PCV automatically executes mechanical deployment actions at closeout — version bumps, file copies, pushes — and flags content-heavy updates as follow-up items.
12. Project summary. At closeout, PCV generates a deliverable-focused summary (plans/project-summary.md) that captures the idea, key planning decisions, what was actually produced, and verification outcome — suitable for student submission or project audit.

Design Principles

These principles underlie PCV’s structure and should be understood by anyone using or adapting the workflow:

1. Human authority over all decisions. The AI proposes; you approve. No assumption, trade-off resolution, or scope change enters the plan without your explicit consent.
2. Explicit over implicit. Decisions made implicitly by the AI are the primary source of rework. PCV forces key decisions to be made explicitly during planning.
3. Separation of planning and execution. Planning requires reasoning about trade-offs, alternatives, and risks. Construction requires efficient execution of settled decisions. Separating them improves both.
4. Incremental verification. Building one component at a time with verification at each step catches errors early. Building everything then testing is consistently worse.
5. Auditable decision trail. The decision log creates a complete record of how the project went from idea to deliverable — valuable for learning, for comparing approaches, and for understanding why decisions were made.

The Three Phases

Plan

The planning phase transforms your project description (the “charge”) into two approved documents:

• MakePlan — High-level plan: what to build, trade-offs resolved, assumptions identified, scope determined, verification criteria set.
• ConstructionPlan — Detailed build specification: file structure, component design, dependency order, verification strategy. May include function signatures and pseudocode, but not full implementations.

Between these documents, PCV may also produce planning artifacts — wireframes for visual projects, mathematical formulations for analytical work, test specifications for code — that you review and approve at Gate 2.

Construct

PCV dispatches a builder agent for each component in the ConstructionPlan, one at a time in dependency order. Each builder works in its own context window — reading files, writing code, and running tests without accumulating overhead in the main session. The main session orchestrates: dispatch, review the summary, handle any deviations (which require your approval), then dispatch the next component. Git commits happen silently at milestones.

Verify

PCV dispatches a verifier agent with pattern-specific instructions (see Four Deliverable Patterns below). The verifier runs tests, checks structure, validates formulations, or compares designs in its own context, then returns a report. The main session maps each success criterion from your charge to specific deliverable components, compares deliverables against approved planning artifacts, and produces the final verification report. If an export target is configured, verified deliverables are copied to that location.

What to Expect at Each Stage

Describing your idea

When you run /pcv in an empty project directory, PCV scaffolds the workspace:

• idea.md — Where you describe your project idea (informal, freeform).
• charge.md — The structured project specification (PCV generates this for you).
• CLAUDE.md — A minimal project identity file (you customize it).
• .claude/settings.json — Permission pre-approvals so PCV can operate without per-action prompts.

Write your idea in idea.md — what you’re building, any constraints, what success looks like. Be informal and detailed; PCV will structure it for you. Then tell Claude you’re ready.

Charge generation

PCV reads your idea.md and generates a draft charge. The draft is presented in chat as a preview (not written to disk) so you can see what PCV understood. Below the preview, PCV asks clarifying questions one at a time about fields it’s uncertain about.

After questions are resolved, PCV asks: “Should I write this charge to disk?” The charge is only written to charge.md on your confirmation. Planning begins automatically from there — no need to run /pcv again.

Clarification questions

PCV asks clarification questions one at a time. It starts with the question whose answer has the most downstream impact, waits for your response, then re-evaluates remaining questions — some may be resolved automatically, others may have narrowed options. Maximum 8 questions; if more are needed, PCV flags that the charge may need more detail.

Critic review and dispositions

After drafting the MakePlan, PCV spawns an adversarial Critic agent that reads the charge, the plan, and the decision log, then challenges the plan. The Critic looks for weak assumptions, internal contradictions, missing edge cases, unstated risks, requirements gaps, and verification holes.

For each finding, the Critic proposes a disposition:

• Resolved — The issue can be fixed by revising the plan. PCV describes the revision it will make.
• Escalate — The issue requires your judgment. PCV presents the finding and asks you a focused question. Escalated findings are presented one at a time, just like clarification questions.
• Acknowledge — The issue is genuine but unresolvable at planning time. PCV explains why.

You have final say on every disposition. If you think an “Acknowledge” item can actually be resolved, say so. Nothing enters Assumptions & Unknowns without your approval.

Approval gates

PCV has three gates where you explicitly approve before proceeding:

At each gate, you can request editorial changes (applied immediately) or substantive changes (PCV confirms interpretation, then revises). PCV does not proceed until you explicitly approve.

Construction

PCV dispatches a builder agent for each component in the ConstructionPlan’s dependency order — one at a time. Each builder works in an isolated context window, keeping the main session lean. You observe but typically don’t need to intervene unless a builder reports a deviation, which requires your approval and is logged.

At the end of construction, PCV generates a build record (plans/build-record.md) that captures the implementation narrative: files modified, design decisions made during construction, deviations from the plan, and lessons learned. The build record is assembled automatically from the decision log, construction plan, and Git history — you review it but don’t need to write it. It remains open through verification.

Verification

PCV dispatches a verifier agent with pattern-specific instructions. The verifier runs in its own context — executing tests, reading deliverables, checking formulations — and returns a structured report. The main session maps each success criterion to deliverable components, compares deliverables to planning artifacts, and produces the final summary. If verification reveals issues requiring fixes, those fixes and any new design decisions are appended to the build record.

Acceptance testing

After automated verification, PCV offers you the chance to test the deliverable hands-on before closing out. It suggests a pattern-appropriate approach:

• Code: run a demo notebook or test script
• Prose: read through the deliverable and flag issues
• Math: work through a formulation with known inputs
• Design: interact with the rendered output

Acceptance testing is optional — you can decline and proceed to closeout. Any issues you report are fixed and logged in both the decision log and build record.

Before closing out, PCV asks if you have any additional notes or observations to add to the build record — things like design considerations that didn’t come up in the workflow, advice for future work, or anything else worth preserving. The build record is then finalized alongside the decision log closeout.

The Four Deliverable Patterns

PCV adapts its planning, construction, and verification to the type of deliverable. Most projects combine multiple patterns.

Pattern 1 — Code

Examples: Applications, packages, data pipelines, simulations, tools.

Planning artifact: Test specification (when tests are part of success criteria) — what unit tests cover, known-input/known-output cases, edge cases, error scenarios.

Construction: Build-test cycle. Each component verified in isolation before proceeding to dependents.

Verification: Automated tests, compilation, runtime checks, error handling of edge cases.

Pattern 2 — Prose/Documents

Examples: SOPs, reports, technical documentation, guides.

Planning artifact: None required (the ConstructionPlan serves as specification). Optional artifacts if requested.

Construction: Build-review cycle. Sections constructed per plan.

Verification: All sections present, content is project-specific, coherent flow, meets readability standard.

Pattern 3 — Mathematical/Analytical

Examples: LP/MIP formulations, optimization models, analytical frameworks.

Planning artifact: Formal mathematical specification — index sets, parameters, decision variables with domains, objective function, all constraints with labels, in LaTeX.

Construction: Build-verify cycle against the approved formulation.

Verification: Correctness, constraint satisfaction, dimensional consistency, variable domain completeness, implementability from document alone.

Pattern 4 — Design-and-Render

Examples: Dashboards, HTML displays, Andon boards, visualizations.

Planning artifact: Wireframe or layout mockup — spatial layout, relative sizing, information hierarchy. Approved wireframes become binding layout contracts.

Construction: Build-review cycle. Implementation matches wireframe.

Verification: Visual comparison to approved wireframe, “glance test” for the target context, accessibility, display-target requirements.

Prior Work Analysis

When your charge references existing code, documents, or other prior work, PCV dispatches a research agent to perform a structured analysis in its own context window. This keeps file-reading overhead out of the main planning session. The research agent:

1. Inventories — What files and artifacts exist? What is the structure, quality, and completeness?
2. Three-category classification — Each finding is classified as: already decided by you (the charge addresses it), a new issue (becomes a clarification question), or a potential conflict (charge vs. prior work).
3. Scope determination — One of three outcomes:
   • Verification-only — Prior work meets all success criteria. Proceed directly to verification.
   • Scoped changes — Structure is sound but specific content needs targeted revision.
   • Full build — Prior work is architecturally flawed or fundamentally misaligned.

PCV guards against over-scoping (defaulting to full rewrite when the structure is reusable) and under-scoping (calling generic content “substantially meets” when the charge requires project-specific detail).

PCV Lite

Not every project needs the full three-gate workflow. PCV Lite is a compressed two-gate path for straightforward projects — single deliverable pattern, 1–3 components, no complex prior work, and low cognitive complexity.

How Lite gets activated

PCV evaluates six criteria after clarification questions are resolved:

• Single deliverable pattern (typically Code or Prose)
• 1–3 estimated components
• No prior work as a build baseline, or minimal baseline (≤5 files)
• Straightforward success criteria (2–3 items)
• No multi-phase indicators
• Low cognitive complexity — bounded edits or template-driven generation, not analytical synthesis across many source files

If three or more criteria are clearly met, PCV proposes Lite mode. You can accept or decline (full PCV continues normally). You can also trigger Lite by using simplicity language in your charge (“simple,” “straightforward,” “quick”), or PCV may propose it mid-clarification if answers reveal simpler scope than expected.

What’s different in Lite

The progress display for Lite projects shows three milestones instead of five:

PCV v3.11 — MyProject (Lite)
■ Charge validated
■ Lite Plan approved
□ Verification complete

Multi-Phase Projects

Some projects have stages that must happen in order — you need to extract data before you can validate it, validate it before you can use it. In a single-phase project, everything is planned and built in one pass. A multi-phase project splits the work into sequential phases, where each phase is a complete PCV cycle (Plan-Construct-Verify) that produces deliverables the next phase depends on.

When does multi-phase apply?

PCV considers multi-phase when three or more of these are true:

• Later work depends on validating earlier work before proceeding
• There are 2+ clearly separable deliverables with distinct success criteria
• The estimated component count is 8+
• The viability of later steps depends on the outcome of earlier steps
• The project will likely span multiple Claude Code sessions

You can also declare multi-phase intent directly in the charge by using language like “phases,” “stages,” or “break this into sequential milestones.”

How multi-phase gets established

There are three ways a project becomes multi-phase, depending on when the need is recognized:

1. You declare it. The charge uses explicit multi-phase language. PCV flags it during charge validation and structures the project accordingly.
2. PCV proposes it during planning. After clarification questions reveal the scope, PCV evaluates the criteria above and presents a phase table. You accept, modify, or decline.
3. It emerges during construction. Unexpected sequential dependencies surface while building. PCV proposes restructuring the in-progress work into Phase 1 of a multi-phase project, with remaining work becoming Phase 2+.

In every case, you have final say. Declining continues single-phase as normal.

Project structure

A multi-phase project has a root directory that coordinates phases, plus a subfolder for each phase that is a complete, independent PCV workspace:

MyProject/
├── plans/
│   ├── make-plan.md           project-level plan with tentative phase plan
│   └── logs/
│       └── master-log.md      cross-phase decisions and outcomes
├── phase-1-extract/           ← complete PCV workspace
│   ├── charge.md
│   ├── plans/                 phase-specific plans, decision log, build record
│   └── deliverables/
├── phase-2-validate/          ← complete PCV workspace
│   ├── charge.md
│   ├── plans/
│   └── deliverables/
├── phase-3-populate/          (tentative — not yet scaffolded)
└── CLAUDE.md

Only Phase 1 is fully planned up front. Later phases appear in the project-level MakePlan as a tentative phase plan — a lightweight sketch showing the overall arc, dependencies, and open questions. Tentative phases are refined (or added, removed, merged, reordered) each time a phase completes.

Working in a multi-phase project

Running /pcv from the project root shows a master overview:

PCV v3.11 — MyProject (Multi-Phase)

Phase 1: Data Extraction [Sonnet builders]
  ■ Charge validated
  ■ MakePlan approved
  ■ ConstructionPlan approved
  ■ Construction
  ■ Verification complete

Phase 2: Validation [Sonnet builders]
  ■ Charge validated
  ■ MakePlan approved
  □ ConstructionPlan approved
  □ Construction
  □ Verification complete

Phase 3: Population (tentative)
Phase 4: Integration (tentative)

Running /pcv inside a phase subfolder shows standard single-phase progress for that phase only, with a note that it’s part of a larger multi-phase project.

Phase transitions

When a phase completes verification, PCV runs a transition protocol before starting the next phase:

1. Phase closeout — finalize the completed phase’s decision log and build record, including the agent configuration used and any lessons learned.
2. Master log update — record the completion, key outcomes, and lessons in the project-level master-log.md.
3. Tentative plan revision — revisit remaining phases in light of what was learned. Phase boundaries, scope, and even the number of remaining phases can change here.
4. Next phase scaffolding — create the next phase’s subfolder with its own charge, ready for a new PCV cycle. In v3.11, this is automated by scaffold-phase.sh.

The transition protocol includes exit ramps at each step. If results from the completed phase show that remaining phases are unnecessary, or that the scope has changed fundamentally, PCV surfaces this and lets you decide: continue as planned, restructure the remaining phases, or close out the entire project.

Cross-phase learning

When planning Phase 2 or later, PCV reads the master log to see what happened in prior phases. This is advisory — it informs the agent configuration proposal (e.g., if Phase 1 needed a mid-project upgrade to stronger builders, PCV starts Phase 2’s proposal at that level) but doesn’t override your judgment. Each phase’s charge is evaluated on its own merits.

Revising a Completed Project

After a project completes a full PCV cycle, you may want to revise it — adding features, changing requirements, or improving what was built. Run /pcv in the completed project directory. PCV displays the progress checklist (all milestones filled), confirms the project is complete, and offers two options:

Revision cycle (new version)

Creates versioned sibling folders for major revisions. On the first revision, PCV restructures the directory:

MyProject/
├── v1/    (original project, archived)
├── v2/    (new revision, scaffolded)
└── CLAUDE.md

The restructure uses a safe protocol: PCV shows a dry-run list of what will be moved, waits for your confirmation, copies files to v1/, verifies the copies, then removes the originals. If Git is available, a checkpoint commit is made first. Each vN/ folder is an independent PCV workspace with its own charge, plans, and deliverables. Prior Work in v2/ points to ../v1.

Subsequent revisions simply scaffold v3/, v4/, etc. as new siblings.

Reopen for fixes (lightweight)

For small post-completion fixes that don’t warrant a full revision cycle, PCV reopens the existing project. It appends to the existing decision log and build record under “Post-Closeout Fixes” without creating new version folders. When fixes are complete, a “Project Re-Closeout” entry is appended.

Adaptive Agent Configuration

PCV doesn’t use a fixed set of models for every project. During planning, it evaluates your project’s complexity and your Anthropic plan, then proposes an agent configuration that balances quality against token cost. You approve (or override) the proposal before construction begins.

Plan tier

The first time you use PCV, it asks which Anthropic API plan you’re on. This is a one-time question — your answer is saved to ~/.claude/pcv-config.json and used for all future projects.

You can change your plan tier at any time by editing ~/.claude/pcv-config.json.

How PCV chooses a configuration

After validating the charge, PCV reads four signals from your project — deliverable patterns, prior-work file count, estimated component count, and technology complexity — then applies decision rules for each agent. The plan tier determines which models are available; the project complexity determines which are proposed.

What counts as complex? Pattern 3 (mathematical) projects, Pattern 1 (code) with 5+ components, or Pattern 4 (design) with strict wireframe compliance. Moderate is Pattern 1 with 2–4 components or standard Pattern 4. Simple is single-component projects or short Pattern 2 (prose) with bounded insertions. Note: Pattern 2 analytical or synthetic prose (10+ pages, multi-source synthesis) routes to Sonnet, not Haiku — analytical documents require more reasoning than template-driven generation.

The configuration table

PCV presents the proposed configuration as a table during planning, with a rationale for each choice:

Proposed agent configuration:

| Agent              | Model  | Effort | Dispatch | Rationale              |
|--------------------|--------|--------|----------|------------------------|
| Hub (planning)     | —      | High   | —        | Complex trade-offs     |
| Hub (construction) | —      | Medium | —        | Executing approved plan|
| Hub (verification) | —      | Medium | —        | Mechanical checks      |
| Research           | Sonnet | Medium | Subagent | 12 prior-work files    |
| Critic             | Haiku  | Medium | Subagent | Adversarial review     |
| Builder            | Sonnet | High   | Subagent | Code + 6 components    |
| Verifier           | Sonnet | Medium | Subagent | Mechanical verification|

Context: 200K (Pro plan). Phase transition compaction strongly recommended.

Approve this configuration, or tell me what you’d like changed.

You can override any row — for example, upgrading builders from Haiku to Sonnet if you want higher quality, or choosing inline research instead of a subagent. Your overrides are logged alongside the proposal.

Mid-project revision

If construction encounters repeated difficulty — two or more deviations that suggest the agent configuration is insufficient — PCV proposes an upgrade. For example, if Haiku builders are struggling with a component that turned out to be more complex than expected, PCV may propose switching to Sonnet builders for the remaining components. You approve or decline the change, and either way the proposal is logged.

Paths in the Charge

The charge template has three path fields: Project Directory, Export Target, and Prior Work.

• External locations (a separate Git repo, a shared folder): use absolute paths.
• Sibling or child directories (a previous version folder next door): use relative paths from the charge file (e.g., ../v1).

PCV validates all paths at the start of planning. Relative paths are resolved against the charge file’s directory and checked for existence — if a path doesn’t exist, you get a clear error before any work begins. The charge file retains the original path (relative or absolute) for portability.

Deployment

When the charge’s Deployment: field specifies where the project is published (e.g., GitHub Pages, npm, a standalone repository), PCV automatically handles deployment actions at closeout. No separate deployment step is needed.

PCV classifies each deployment action into one of three categories:

• Mechanical — version bumps, file copies to deployment targets, README version updates. Executed automatically.
• Push — git push or equivalent publish action. Executed automatically with a report of what was pushed and where.
• Content-heavy — substantial documentation rewrites (e.g., updating a multi-page guide). Flagged as follow-up items for a separate session.

Execution order is always: mechanical edits → commit → push. This ensures all deployment edits are committed before anything is pushed.

Project Summary

At closeout, PCV generates a project summary at plans/project-summary.md. The summary is written for student submission or project audit — it captures what the project produced, not how PCV operated.

The summary has five sections:

1. Idea — 2–3 sentence distillation of the project concept.
2. Charge Summary — key requirements and constraints.
3. Planning Decisions — the clarification Q&A that shaped the project scope. Focuses on decisions about what was built, not PCV configuration details.
4. Deliverable Summary — the most substantial section. PCV reads the actual deliverables and summarizes their content, findings, or functionality. For code projects: what the software does. For prose: key findings and recommendations. For math: formulation summary. For design: layout decisions.
5. Verification — pass/fail and substantive issues found.

A conditional Deployment section is included when the charge has a deployment target. The summary explicitly excludes PCV process details (agent model choices, builder dispatch mechanics, methodology lessons) — those belong in the build record.

For multi-phase projects, each phase gets its own summary file, and a lightweight master summary links them together at final closeout.

Global Settings Check

When PCV scaffolds a new project, it checks your global Claude Code settings at ~/.claude/settings.json. If the file is missing or has minimal permissions (fewer than 3 allow rules), PCV offers to add recommended global permissions:

Read(**), Write(**), Edit(**), Glob(*), Grep(*), Bash(*), Agent, WebSearch

These are broad but standard for active development. You can approve or decline — PCV proceeds either way. If you already have established settings, PCV skips this silently.

In v3.11, the global settings check and per-project settings generation are handled by scaffold-settings.sh, which is the single source of truth for settings structure.

Subagent Architecture

PCV uses a hub-and-spoke agent model to keep the main conversation context lean. The main session (the “hub”) orchestrates work by dispatching specialized agents (the “spokes”) that run in their own isolated context windows. Each agent reads files, does its work, and returns a compact summary — the main session never carries the intermediate file reads and tool outputs.

The four agents

* Configurable via Adaptive Agent Configuration. Builder may use Haiku for simple or prose-only projects. Research may run inline (no separate agent) for small prior-work sets.

How dispatch works

Each agent is defined as a standalone Markdown file in ~/.claude/agents/. When the protocol needs to dispatch an agent, it reads the agent file, inlines its behavioral instructions into the dispatch prompt, and spawns a general-purpose subagent. This is a workaround for a known Claude Code limitation: custom agent types defined in .claude/agents/ cannot be invoked directly via subagent_type.

Graceful degradation

If an agent fails to spawn or Claude builds inline instead of dispatching, the work product is identical — only token efficiency is reduced. The agents are an optimization, not a dependency. The workflow produces the same deliverables either way.

Token Efficiency

Claude Code is agentic: each tool-use step (read file, edit, run test, read error, fix) sends the entire accumulated conversation as input. With hundreds of tool-use round trips, total token usage can reach tens of millions of input tokens in a single session. PCV addresses this at three levels:

1. Subagent context isolation

The primary mechanism. When a builder agent reads 15 files and makes 20 edits to construct a component, those file contents and tool outputs live in the builder’s context — not the main session. The main session grows by only the compact summary the builder returns (~500 tokens). Without isolation, the same work would carry ~30,000+ tokens through every subsequent API call.

This applies to all four agents: the research agent’s file inventory, the critic’s document analysis, the builder’s construction work, and the verifier’s test execution all stay in isolated contexts.

2. Phase transition compaction

At each phase transition (Planning → Construction, Construction → Verification), PCV recommends running /compact to reduce the conversation context. All planning decisions, construction progress, and verification state are persisted to disk in the plans directory, so /clear (full context reset) is also safe at these boundaries — the next phase reads everything it needs from files.

3. Decision log preservation

PCV’s scaffolded CLAUDE.md includes an instruction to preserve the decision log and plans directory during compaction. This ensures that when Claude Code automatically compacts the conversation (as it approaches context limits), the critical planning state is retained rather than summarized away.

Effort-level recommendations

Each phase summary in the PCV routing file includes an effort-level recommendation:

• Planning: high/max — Planning requires reasoning about trade-offs, alternatives, and risks. Higher effort produces better plans.
• Construction: medium — Construction follows an approved plan. Standard effort is sufficient for executing settled decisions.
• Verification: medium — Verification checks deliverables against specifications. Standard effort is sufficient for pattern-specific checks.

These are recommendations, not enforced settings. You can adjust effort level via Claude Code’s settings at any time.

Protocol Architecture (v3.11)

Spine + fragment loading

PCV’s protocol files use a spine + fragment architecture that minimizes how much instruction text is loaded into context at any given moment. Each protocol file (planning, construction, verification, phase transition) is a compact spine (26–35 lines) containing a step table and loading instructions. Detailed per-step instructions live in fragment files in subdirectories, loaded on demand as the workflow progresses.

A shared pcv-common.md file (191 lines) contains patterns used across all protocols: decision log entry formats, agent dispatch boilerplate, gate handling, session resumption, and templates. It is loaded once per session rather than being duplicated in each protocol.

Context loaded per phase entry: spine (~30 lines) + pcv-common.md (191 lines) + current step fragment (~50–90 lines) = ~270–290 lines. Before this architecture, a single protocol file loaded 400–980 lines — a 60–70% reduction in protocol context.

File structure

~/.claude/skills/pcv/
  SKILL.md                         Entry point, routing, templates (271 lines)
  pcv-common.md                    Shared patterns (191 lines)
  planning-protocol.md             Spine (32 lines)
  planning/
    step1-charge-config.md         Charge resolution + agent config
    step2-prior-work.md            Prior work analysis
    step3-4-patterns-clarify.md    Patterns + clarification + assessments
    step5-makeplan.md              MakePlan / Lite plan
    step6-8-critic-gates.md        Critic + compliance + Gate 1
    step9-11-construction-gates.md ConstructionPlan + Gates 2–3
  construction-protocol.md         Spine (27 lines)
  construction/
    step1-3-baseline-build.md      Baseline + build loop
    step4-7-deviations-record.md   Deviations + build record
  verification-protocol.md         Spine (26 lines)
  verification/
    step1-verify.md                Pattern-specific verification
    step2-4-mapping-export.md      Mapping + comparison + export
    step4.5-acceptance.md          Acceptance testing
    step5-8-report-closeout.md     Report + closeout + summary + deployment
  phase-transition-protocol.md     Spine (35 lines)
  transition/
    step1-3-close-review.md        Phase close + master log
    step4-user-directs.md          User direction (options A–F)
    step5-6-scaffold-begin.md      Scaffold + begin next phase
  hooks/                           Bash hook scripts (unchanged)
  VERSION                          Version + date + changelog

Total: 1,522 lines across 22 files (was 2,928 lines across 5 files before compression). The terse instruction format uses imperative bullets rather than explanatory prose — optimized for LLM execution, not human reading. This reference document preserves the explanatory content.

Key Things to Know

Progress display

Every time you run /pcv, it shows a milestone checklist so you always know where the project stands:

PCV v3.11 — MyProject
■ Charge validated
■ MakePlan approved
□ ConstructionPlan approved
□ Construction
□ Verification complete

Filled squares (■) are completed milestones; empty squares (□) are remaining. This makes it clear at a glance whether the project is mid-planning, under construction, or fully complete.

Permissions are automatic

PCV scaffolds a .claude/settings.json file that pre-approves all general-purpose file operations (Read, Write, Glob, Grep, Git) at project creation. Technology-specific permissions (e.g., Julia, Python, npm) are added automatically when the ConstructionPlan is approved. You should not need to approve individual operations.

Session resumption works

If you need to start a new Claude Code session mid-project (e.g., due to token limits or a break), just run /pcv again in the same directory. PCV re-reads the charge, plan documents, and decision log from disk to reconstruct context. It will tell you where you left off and confirm before proceeding.

The decision log is your audit trail

PCV maintains plans/logs/decision-log.md automatically. It records the verbatim text of every clarification question and your answer, Critic findings and dispositions, gate approvals, and deviations during construction. Entries are written at the moment they occur (chronological order). You never edit this file directly.

The build record captures what actually happened

The decision log records clarifications, approvals, and deviations. The build record (plans/build-record.md) captures the broader implementation story: what files were created or modified, design decisions made on details the plan left unspecified (distinct from deviations), verification fixes, open items for future work, and consolidated lessons learned. It also includes a “User Notes” section where you can add final observations before closeout. The build record is generated automatically at the end of construction and finalized during verification.

#LEARN tags capture lessons

When PCV logs a revision, deviation, or correction that captures a reusable insight, it tags the entry with #LEARN. These create a searchable record of what worked and what didn’t across projects.

Git is silent and optional

PCV checks for an existing Git repository before doing anything with Git. If the current directory or a parent directory (up to 5 levels) has .git, PCV inherits that repo. If no Git exists anywhere, PCV asks whether to initialize or skip. It never silently runs git init. Commits happen at milestones with descriptive messages.

The charge must be a file

PCV requires the charge to exist as a file on disk (charge.md or any filename containing “charge”). Pasted text or attached content in the conversation is not accepted — the file is needed for auditing and decision reconstruction.

Single command: /pcv

There is no separate /pcv init command. Running /pcv handles everything: scaffolding new projects, detecting the current phase, and routing to the appropriate protocol. If you provide a filename argument (/pcv MyCharge.md), PCV uses that specific charge file.

Reliability Hooks (v3.11)

PCV v3.11 introduces a hook-based reliability layer that uses Claude Code’s native hook system to enforce workflow discipline automatically. Five hooks add backstops to the most failure-prone workflow transitions — session end without closeout, context loss after compaction, builder completion tracking, and real-time format validation. Hooks are per-project (registered in the project’s .claude/settings.json, not globally) and carry a kill switch for projects that do not need them.

Hooks replace manual protocol reminders for mechanical checks. Protocol text has been compressed to terse instruction format and split into a spine + fragment architecture for minimal context loading. Utility scripts (called by hooks or protocol) handle settings generation, permission scanning, format validation, and phase scaffolding.

The five hooks

Utility scripts

These scripts are not hooks but are called by hooks or protocol steps:

Input format and exit semantics

All hooks are pure Bash scripts at ~/.claude/skills/pcv/hooks/*.sh. They receive the event payload as JSON on stdin. Input fields used:

• Stop, PreCompact, SessionStart: No payload fields consumed directly — hooks derive state from on-disk files (plans/logs/decision-log.md, plans/logs/pcv-state.json, plans/ existence).
• SubagentStop: Reads subagent_type, model, and status from the payload JSON.
• PostToolUse: Reads tool_name and tool_input.file_path from the payload JSON. Skips non-Write calls silently.

Exit semantics:

• Stop hook: Exits non-zero (blocking) only when the state matrix requires it (states 4 and 5 above). All other states exit 0 (allow). The block message instructs the user to write a closeout or abandonment entry, or set the kill switch.
• All other hooks: Always exit 0. Errors are logged to stderr and treated as advisory.

Auto-retrofit prompt

When you run /pcv in a project that lacks the hook entries in its .claude/settings.json (e.g., a v3.10-era project) and the project has not opted out, PCV prompts you to install them:

PCV: This project does not have reliability hooks registered.
Install hook entries in .claude/settings.json? (y/n)

Accepting writes the entries via scaffold-settings.sh. Declining creates a sentinel file at .claude/.pcv-hooks-opted-out and the prompt does not re-fire.

Kill switch

To disable all PCV hooks for a project, create the sentinel file:

echo "opted-out" > .claude/.pcv-hooks-opted-out

With this file present, all hook scripts exit 0 silently regardless of project state. To re-enable hooks, delete the file. The kill switch does not affect the PCV workflow itself — planning, construction, and verification proceed normally.

Format Enforcement (v3.11)

PCV artifact files — decision-log.md, build-record.md, and project-summary.md — have required structural formats. v3.11 adds automated enforcement so malformed artifacts are caught immediately, not discovered at closeout or audit.

What is validated

Two enforcement layers

Both layers call the same validate-pcv-format.sh script:

• PostToolUse(Write) hook — real-time layer. Fires immediately after any Write call that touches a PCV artifact file. Outputs a warning to stderr if the file does not meet structural requirements. Always exits 0 (advisory). Gives the model an opportunity to self-correct before the session ends.
• Stop hook — guaranteed floor. Runs format validation as part of its state-matrix check when the stop would otherwise block. If artifacts are malformed and the session is in a blocking state, the block message includes the format error. This layer is guaranteed to fire at session end regardless of whether the PostToolUse hook is installed.

The two-layer design means projects that install only the Stop hook (the minimum configuration) still get format checking at the final gate. Projects with both hooks get earlier feedback.

Permission Management (v3.11)

Before v3.11, the settings.json template was a 94-line JSON block embedded in SKILL.md. Technology-specific permissions were added manually during construction. v3.11 replaces both with scripts that are the single source of truth.

scaffold-settings.sh

Generates or merges .claude/settings.json at project scaffolding and hook retrofit. Key behaviors:

• Create mode: When no settings file exists, writes a minimal valid file with the standard PCV allow rules and all five hook registrations.
• Merge mode: When a settings file already exists, adds missing hook entries and allow rules without overwriting existing content. Uses jq for safe JSON merge; falls back to append-with-comment if jq is unavailable.
• Idempotent: Running it twice produces the same result. Existing entries are not duplicated.

tech-permissions-scan.sh

Called at Gate 3 approval (ConstructionPlan approved). Scans the ConstructionPlan text for technology keywords and adds the corresponding Bash() allow rules:

Rules are merged into the existing settings file by scaffold-settings.sh (also idempotent). Technology detection is keyword-based and may produce false positives for documentation-only mentions — you can remove rules manually after scaffolding if needed.

Phase Scaffolding (v3.11)

Before v3.11, the phase transition protocol included ~140 lines of manual instructions for creating a new phase subfolder: directory structure, charge template, CLAUDE.md identity file, settings stub. v3.11 replaces this with scaffold-phase.sh.

What scaffold-phase.sh creates

Given a phase name (e.g., phase-3-populate), the script creates:

phase-3-populate/
├── charge.md              (charge template with phase-specific fields pre-filled)
├── CLAUDE.md              (phase identity file referencing parent project)
├── .claude/
│   └── settings.json      (settings stub with hook registrations)
└── plans/
    ├── .gitkeep
    └── logs/
        └── .gitkeep

How it is called

The phase transition protocol calls scaffold-phase.sh at Step 4 (next phase scaffolding). The script is passed:

• The new phase directory name
• The project root path (for CLAUDE.md cross-reference)
• The previous phase’s deliverables path (pre-filled as Prior Work in the charge template)

The script writes all files and reports what was created. The protocol then confirms creation before proceeding. If the phase directory already exists (e.g., the script was run twice), it exits with a warning and takes no action.

Relationship to scaffold-settings.sh

scaffold-phase.sh calls scaffold-settings.sh to generate the new phase’s .claude/settings.json. This ensures the new phase starts with hook registrations already in place, without needing a separate retrofit prompt.

Behavioral Constraints (v3.11)

Three behavioral rules in pcv-common.md that prevent protocol failures discovered during v3.11 development.

Scope-Creep Check

Before executing user-directed work not in the approved plan (acceptance testing fixes, scope extensions, ad-hoc requests), PCV assesses the aggregate scope against three thresholds:

• 3+ new files to be created
• Changes spanning 3+ existing files
• Decisions not in the approved plan — changes to control flow, sequencing, gate behavior, or file/directory structure

If any threshold is met, PCV presents a scope assessment with three options: (a) approve as in-scope fix, (b) defer to a new phase, (c) reduce scope to fit the current phase. The user’s choice is logged in the decision log.

Thresholds are conservative by design. The check evaluates the aggregate scope of all reported work, not each item individually — preventing a sequence of small fixes from accumulating into a hidden scope bypass.

Origin: During v3.11 Phase 3 acceptance testing, a full phase of work (17 new files, 1,400+ line changes) was executed inline as a “scope extension” without any PCV quality gates. This check would have caught it.

Persistence Assurance

Any recommendation, decision, or deferred work item the user may need in a future session must be written to a file before the session ends. PCV must never assure availability of information that exists only in conversation context.

When a cross-session recommendation emerges, PCV writes it to the appropriate file (decision log, build record, or master log), then confirms: “I’ve written [item] to [file]. It will persist across sessions.”

Origin: During v3.11, recommendations for further improvement were made and the user was assured they would be available in the next session. They were never written to disk and were lost when the session ended.

Explicit Gate Approval

Every GATE presentation must end with a direct approval question (e.g., “Do you approve?”). PCV must not present information and stop silently — the user must be able to distinguish a gate from a pause.

Token & Speed Optimization (v3.11 Phase 6)

Phase 6 implements 16 ranked optimizations that reduce protocol overhead and improve execution speed without changing PCV behavior.

Always-Loaded Reduction (27%)

SKILL.md and pcv-common.md are read on every /pcv invocation. Phase 6 reduced their combined size from 520 to 380 lines:

• Template extraction (R1): CLAUDE.md, charge, idea templates, multi-phase scaffolding, and version chaining moved to scaffold-templates.md — loaded only during scaffold and version chaining.
• One-time content redistribution (R2): MakePlan sections, Build Record template, Deliverable Patterns table, and Agent Config defaults moved from pcv-common.md into the fragments that consume them.
• Routing fallback elimination (R11): 40 lines of duplicated routing logic replaced with a one-line hook invocation plus error handling.

Fragment & Spine Mergers

Reduces Read tool calls per session by consolidating small fragments:

• R8: Two construction fragments merged into construction/steps.md.
• R7: Verification steps 2–4 merged into step 1 fragment.
• R14: All four protocol spines merged into the top of their first fragment. Protocol entry files become 4-line pointers.

Deliverable Surfacing (R0, R0a)

• R0: Construction complete and closeout now name each deliverable file with its absolute path.
• R0a: Protocol convention: deliverables go in the project root, not in plans/. Pre-build check enforces this.

Protocol Simplifications

• R6: Compliance checklist replaced with silent pre-gate validation.
• R9: Agent configuration uses defaults-first approach. Full decision tree only when complexity signals are present (Pattern 3, 5+ components, etc.).
• R12: Compact format for mechanical decision log entries (gate approvals, assessments). Pipe-delimited single line instead of 5–8 lines.
• R13: Build record skipped for simple projects (≤3 files, no deviations, no design decisions).
• R5: Builder agent instructions cached after first dispatch; re-inlined from cache for subsequent components.

Hook Improvements

• R3: Dead probe scripts deleted (null-probe.sh, post-tool-use-probe.sh, subagent-start-probe.sh).
• R4: Shared helper functions extracted to pcv-lib.sh (string_in_file, normalize_allow_array, append_to_allow_array, is_valid_json_shape). Sourced by scaffold-settings.sh and tech-permissions-scan.sh.
• R10: stop-closeout.sh uses inline header-grep check instead of spawning validate-pcv-format.sh as a subprocess on every turn.
• R15: jq fast-path for scaffold-settings.sh JSON operations. Auto-provisions jq binary from GitHub releases if not installed. Pure-bash fallback preserved.

Automated Testing (v3.12)

PCV v3.12 adds protocol-level support for fully automated test runs, enabling regression testing after any workflow change.

Test Mode Environment Variables

Machine-Readable Milestones

Protocol milestones append [MILESTONE:<TAG>] to decision log entry headers (e.g., [MILESTONE:GATE_1], [MILESTONE:CONSTRUCTION_COMPLETE]). The pre-compact-snapshot.sh hook extracts these into a milestones_reached array in pcv-state.json.

Test Mode Annotation

When PCV_AUTO_APPROVE=1 is set, all decision log entry headers are prefixed with [TEST] for easy identification and filtering.

Regression Test Harness

Tier 1 (deterministic): Nine bash test scripts covering all hook scripts (156+ assertions). Run with bash run-tests.sh.

Tier 2 (LLM-in-the-loop): Three pre-built test charges (Lite, Standard, Multi-phase) with a Python driver (driver.py) that scaffolds a project, invokes claude -p "/pcv" with test env vars, and validates artifacts via validate-run.sh.

FAQ / Troubleshooting

PCV says it can’t find my charge file.

The charge must be a file on disk with “charge” in its name (case-insensitive). Check that the file exists in your current working directory, or provide the filename explicitly: /pcv MyProject_Charge.md.

I’m getting permission prompts for every file operation.

This usually means .claude/settings.json was not created or was deleted. Run /pcv in an empty directory to re-scaffold, or run scaffold-settings.sh directly to regenerate the settings file. In v3.11, the scaffold step is automated — see Permission Management.

Can I use PCV with a model other than Opus?

PCV is designed for Claude Code and works best with the strongest available model for planning (currently Opus). It will function with other models but planning quality may vary. The Critic agent uses Haiku for cost efficiency; the research, builder, and verifier agents use Sonnet.

Can I skip the planning phase and just build?

That’s just using Claude Code normally — and it’s fine for simple tasks. PCV is opt-in. Only invoke /pcv when the project complexity warrants structured planning.

What if I need to change the plan during construction?

If PCV encounters a deviation during construction, it stops, explains the issue, and waits for your approval before changing approach. The deviation is logged. For larger scope changes, you may need to return to the planning phase.

How do I update PCV?

Download a fresh bootstrap.md and provide it to Claude Code. The installer compares the version in the bootstrap against your installed version and updates if the new version is higher.

The Stop hook is blocking my session end unexpectedly.

The hook fires when the project is in verification or construction phase without a closeout entry. Add a ## Project Closeout or ## Verification Abandoned entry to plans/logs/decision-log.md, or set the kill switch (echo "opted-out" > .claude/.pcv-hooks-opted-out) if you want to end the session without a formal closeout.

The PostToolUse hook is reporting format warnings on my files.

The hook checks PCV artifact files for required section headers immediately after each write. If your file is mid-construction (not yet complete), the warning is expected and advisory — it does not block the write. Complete the file structure before the session ends to avoid the Stop hook also flagging it.