PCV Workflow Guide

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.

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).

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.

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.

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.10 — 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.

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.

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.10 — MyProject (Lite)
■ Charge validated
■ Lite Plan approved
□ Verification complete

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.

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.10 — 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.

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.

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 manually create the settings file. See the installation page for details.

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.

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.