agent-browser Skill

Browser automation CLI designed for AI agents. Uses "snapshot + refs" paradigm for 93% less context than Playwright MCP.

Quick Start

# Install globally
npm install -g agent-browser

# Download Chromium (one-time)
agent-browser install

# Linux: include system deps
agent-browser install --with-deps

# Verify
agent-browser --version

Core Workflow

The 4-step pattern for all browser automation:

# 1. Navigate
agent-browser open https://example.com

# 2. Snapshot (get interactive elements with refs)
agent-browser snapshot -i
# Output: button "Sign In" @e1, textbox "Email" @e2, ...

# 3. Interact using refs
agent-browser fill @e2 "user@example.com"
agent-browser click @e1

# 4. Re-snapshot after page changes
agent-browser snapshot -i

Project-Specific Setup

For project-specific connection patterns, logged-in session reuse through chrome-debug, and when to use agent-browser vs chrome-devtools vs direct non-browser verification, see the project's browser-automation testing notes in the consuming repo, if present. This skill file stays a generic tool reference only and should not redefine the project's broader testing policy.

When to Use (vs chrome-devtools)

Token efficiency: ~280 chars/snapshot vs 8K+ for Playwright MCP.

Command Reference

Navigation

agent-browser open <url>       # Navigate to URL
agent-browser back             # Go back
agent-browser forward          # Go forward
agent-browser reload           # Reload page
agent-browser close            # Close browser

Analysis (Snapshot)

agent-browser snapshot         # Full accessibility tree
agent-browser snapshot -i      # Interactive elements only (recommended)
agent-browser snapshot -c      # Compact output
agent-browser snapshot -d 3    # Limit depth
agent-browser snapshot -s "nav" # Scope to CSS selector

Interactions (use @refs from snapshot)

agent-browser click @e1        # Click element
agent-browser dblclick @e1     # Double-click
agent-browser fill @e2 "text"  # Clear and fill input
agent-browser type @e2 "text"  # Type without clearing
agent-browser press Enter      # Press key
agent-browser hover @e1        # Hover over element
agent-browser check @e3        # Check checkbox
agent-browser uncheck @e3      # Uncheck checkbox
agent-browser select @e4 "opt" # Select dropdown option
agent-browser scroll @e1       # Scroll element into view
agent-browser scroll down 500  # Scroll page by pixels
agent-browser drag @e1 @e2     # Drag from e1 to e2
agent-browser upload @e5 file.pdf  # Upload file

Information Retrieval

agent-browser get text @e1     # Get text content
agent-browser get html @e1     # Get HTML
agent-browser get value @e2    # Get input value
agent-browser get attr @e1 href  # Get attribute
agent-browser get title        # Page title
agent-browser get url          # Current URL
agent-browser get count "li"   # Count elements
agent-browser get box @e1      # Bounding box

State Checks

agent-browser is visible @e1   # Check visibility
agent-browser is enabled @e1   # Check if enabled
agent-browser is checked @e3   # Check if checked

Media

agent-browser screenshot           # Capture viewport
agent-browser screenshot --full    # Full page
agent-browser screenshot -o ss.png # Save to file
agent-browser pdf -o page.pdf      # Export PDF
agent-browser record start         # Start video recording
agent-browser record stop          # Stop and save video
agent-browser record restart       # Restart recording

Wait Conditions

agent-browser wait @e1                    # Wait for element
agent-browser wait --text "Success"       # Wait for text to appear
agent-browser wait --url "/dashboard"     # Wait for URL pattern
agent-browser wait --load                 # Wait for page load
agent-browser wait --idle                 # Wait for network idle
agent-browser wait --fn "() => window.ready"  # Wait for JS condition

Browser Configuration

agent-browser viewport 1920 1080   # Set viewport size
agent-browser device "iPhone 14"   # Emulate device
agent-browser geolocation 40.7 -74.0  # Set geolocation
agent-browser offline true         # Enable offline mode
agent-browser headers '{"X-Custom":"val"}'  # Set headers
agent-browser credentials user pass  # HTTP auth
agent-browser color-scheme dark    # Set color scheme

Storage Management

agent-browser cookies              # List cookies
agent-browser cookies set name=val # Set cookie
agent-browser cookies clear        # Clear cookies
agent-browser storage local        # Get localStorage
agent-browser storage session      # Get sessionStorage
agent-browser state save auth.json # Save browser state
agent-browser state load auth.json # Load browser state

Network Control

agent-browser network route "**/*.jpg" --abort    # Block requests
agent-browser network route "**/api/*" --body '{"data":[]}'  # Mock response
agent-browser network unroute "**/*.jpg"          # Remove specific route
agent-browser network requests                    # List intercepted requests

Semantic Finding

agent-browser find role button           # Find by ARIA role
agent-browser find text "Submit"         # Find by text content
agent-browser find label "Email"         # Find by label
agent-browser find placeholder "Search"  # Find by placeholder
agent-browser find testid "login-btn"    # Find by data-testid
agent-browser find first "button"        # First matching element
agent-browser find last "li"             # Last matching element
agent-browser find nth 2 "li"            # Nth element (0-indexed)

Advanced

agent-browser tabs                 # List tabs
agent-browser tab new              # New tab
agent-browser tab 2                # Switch to tab
agent-browser tab close            # Close current tab
agent-browser frame 0              # Switch to frame
agent-browser dialog accept        # Accept dialog
agent-browser dialog dismiss       # Dismiss dialog
agent-browser eval "document.title"  # Execute JS
agent-browser highlight @e1        # Highlight element visually
agent-browser mouse move 100 200   # Move mouse to coordinates
agent-browser mouse down           # Mouse button down
agent-browser mouse up             # Mouse button up

Global Options

Environment Variables

Common Patterns

Form Submission

agent-browser open https://example.com/login
agent-browser snapshot -i
agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"
agent-browser click @e3  # Submit button
agent-browser wait url "/dashboard"

State Persistence (Auth)

# Save authenticated state
agent-browser open https://example.com/login
# ... login steps ...
agent-browser state save auth.json

# Reuse in future sessions
agent-browser state load auth.json
agent-browser open https://example.com/dashboard

Video Recording (Debugging)

agent-browser open https://example.com
agent-browser record start
# ... perform actions ...
agent-browser record stop  # Saves to recording.webm

Parallel Sessions

# Terminal 1
agent-browser --session test1 open https://example.com

# Terminal 2
agent-browser --session test2 open https://example.com

Cloud Browsers (Browserbase)

For CI/CD or environments without local browser:

# Set credentials
export BROWSERBASE_API_KEY="your-api-key"
export BROWSERBASE_PROJECT_ID="your-project-id"

# Use cloud browser
agent-browser -p browserbase open https://example.com

See references/browserbase-cloud-setup.md for detailed setup.

Troubleshooting

Resources

• GitHub Repository
• Official Documentation
• Browserbase Docs

vc-agent-strategy-compare

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Evaluate 4 execution strategies for any RIPER-5 phase or fan-out task. Computes the 7-signal score, shows explicit agent count math, applies cost guards, and outputs a ranked strategy recommendation.

All strategies use the existing vc-system agents and skills. The question is only how they are orchestrated.

Model Selection Policy

Every spawned agent — across ALL four strategies (sequential, parallel subagents, dynamic workflow, agent team) — defaults to sonnet. Spawn opus ONLY when the agent is carrying out real source-code or build execution (writing/editing code, running builds, applying migrations). Planning, research, analysis, validation, review, and synthesis all run on sonnet.

Concrete rules:

• Default = sonnet for any teammate, parallel subagent, or agent() call in a workflow. State the model explicitly when spawning.
• opus ONLY for execution work: the agent that actually implements code (the vc-execute-agent leg, or a workflow agent() step whose job is to modify source / run a build). The RIPER-5 phase that runs on opus is EXECUTE; all other phases (RESEARCH, SPEC, INNOVATE, PLAN, VALIDATE, UPDATE PROCESS) run on sonnet.
• Agent-team members: assign sonnet to reviewers, researchers, validators, and planners; assign opus only to the teammate doing real code execution.
• Dynamic workflows: pass model: 'sonnet' on agent() calls by default; pass model: 'opus' only on the execution stage that writes code or runs builds.
• Parallel subagents: fan-out investigation/review subagents are sonnet; only an implementing subagent is opus.

Rationale: opus is reserved for the one place judgment-under-execution materially changes code quality. Everything upstream is sonnet-cheap without quality loss, and this keeps fan-outs (which multiply agent count) on the cost-efficient tier. This mirrors the live agent frontmatter: vc-execute-agent, vc-fast-mode-agent, and vc-quick-fix-agent are opus; every other vc-agent is sonnet.

Mode Selection

This skill runs in one of two modes. Choose based on context availability and decision stakes.

Simple Mode (default)

Score the 7 signals from information already present in the conversation context. No additional file scanning.

Use Simple Mode when:

• File count and blast radius are already clear from the current plan or research summary
• Test infrastructure status is already mentioned or irrelevant
• The strategy decision is not gating a phase program kickoff
• No signal is ambiguous given current context

Output format: Signal 3: +1 (estimated 5-10 files)

Deep Mode

Run targeted codebase scans BEFORE scoring signals, then score each signal with concrete evidence.

Trigger conditions — any one is sufficient:

• Signal 3 (file count / directions) cannot be accurately determined from context alone
• Signal 5 (test infra maturity) is unknown — no test files have been mentioned yet
• The strategy recommendation will gate a phase program kickoff (high-stakes decision)
• Caller explicitly requests deep mode (e.g. "run deep mode", "scan first")

Scans to run before scoring:

Signal 3 scan — count actual touchpoint files:

find . -path '*/active/*' -name '*.md' | head -5
grep -A 30 "Touchpoints" [plan path] | grep -E "^\s*-"

Signal 5 scan — assess test infra maturity:

# Check if local test script exists
grep -l "test:local" packages/*/package.json apps/*/package.json 2>/dev/null | head -5
# Count test files in blast radius directories
find [blast-radius-dirs] -name '*.test.ts' -o -name '*.spec.ts' 2>/dev/null | wc -l
# Check validate-contract for tier assignments
grep -A 5 "tier:" [plan path] | head -20

Signal 6 scan — find independent phases for parallelization:

grep -A 5 "Phase Ordering\|phase.*depend" [umbrella plan path] | head -20

Signal 7 scan — check prior parallel execution outcomes:

find process/features/[feature]/active/ process/features/[feature]/completed/ -name '*_REPORT_*' 2>/dev/null | grep -i "parallel\|execute" | head -5

After scanning, score each affected signal with concrete evidence: Signal 3: +1 (14 files confirmed via Touchpoints scan: packages/api/src/router/billing.ts, apps/web/src/components/billing/*, ...)

When To Invoke

Invoke this skill at these five RIPER-5 checkpoints:

1. RESEARCH — when 2+ distinct investigation directions are identified before fanning out (Checkpoint 1: Research Fan-Out)
2. INNOVATE — after 2-3 approaches are surfaced and before the Decision Summary is locked (Checkpoint 2: Innovate Fan-Out)
3. PLAN — when 3+ phase plans will be created (phase program detected; Checkpoint 4: Phase-Program Validation Fan-Out)
4. VALIDATE — at V4 (Validate Menu) — always runs as part of the mandatory VALIDATE sequence
5. UPDATE PROCESS — when post-execute review involves multiple dimensions simultaneously (Checkpoint 5: Post-Execute Review Fan-Out)

Phase-END Invocation Rule

Invoke at the END of each RIPER-5 phase to recommend the execution strategy for the NEXT phase. The skill receives the current phase's output as context and produces a strategy recommendation that the orchestrator carries into the next phase handoff.

Fan-Out-Level Invocation Rule

When any agent is about to spawn multiple parallel subagents for work WITHIN the current phase, invoke vc-agent-strategy-compare FIRST to determine the execution method.

• Input context: describe the specific fan-out task (not the whole phase). Example: "run feasibility checks on 5 phase plans" or "review 3 independent API surface changes."
• Output: Workflow / Parallel-subagents / Agent team / Sequential recommendation for THIS fan-out only.
• This prevents defaulting to parallel subagents for tasks that are better served by a deterministic workflow or a single sequential agent.

Orchestrator Pre-Spawn Rule

Before any multi-file edit begins, the orchestrator surfaces a strategy recommendation from this skill and waits for user confirmation before spawning vc-execute-agent. This is not optional for non-trivial plans (blast radius ≥ 3 files or any high-risk class present).

7-Signal Scoring Table

Count how many signals are present. Each signal counts as 1. Use the score to select a strategy threshold.

Seven Signals

Total score: [0–7]

Threshold Table

Auto-skip rule: single-file or trivial changes always use sequential regardless of score. Do not mention other strategies for trivial changes.

Fit note: the right strategy is the one that fits the work — not the highest tier. Sequential is correct for trivial changes. Workflow is correct for deterministic pipelines and full RIPER-5 automation. Agent team is correct only when 2+ specialists need to coordinate mid-execution.

Strategy Options Table

ALL 4 strategies must always be evaluated and presented. Never omit one.

Cost Guard Rules

• >30 agents total: show the full breakdown (strategy × count math) so the user can judge before proceeding.
• >100 agents total: show breakdown AND ask for explicit confirmation before spawning.
• >6 team members (vc-team only): show each member's role and ask for explicit confirmation.

Note: V5 "Accept" in the VALIDATE sequence satisfies both the cost-guard confirmation and the plan-approval confirmation in one gate. The cost guard is surfaced at V4 (Validate Menu) so the user sees it before deciding at V5. No separate yes/no prompt is required for the cost guard alone.

Recommendation Output

After computing the score and filling the table, output a single recommendation block. Use plain English labels alongside technical ones so readers unfamiliar with the system can follow along.

Score: [N]/7 — signals: [list present signal IDs]
Recommended strategy: [Sequential (one agent at a time) | Parallel subagents (independent work, no coordination) | Workflow (automated pipeline) | Agent team (specialists coordinating live)]
Agent count: [explicit math per row above]
Model: [sonnet for all spawned agents; opus ONLY for the code-execution leg — see §Model Selection Policy]
Cost guard: [triggered / not triggered]
Rationale: [one sentence on dominant signal and why this strategy fits]

Strategy-by-Fit Rules

Use these rules to select and justify the recommendation — not the threshold table alone:

• Sequential: right for trivial or single-file changes; right for /goal phase-program execution where each phase clearly depends on the previous. Hard limit: single context window per phase. Each vc-agent (vc-research-agent, vc-plan-agent, etc.) runs one at a time; orchestrator hands off between them.
• Parallel subagents: right when there are 5+ independent items in different file domains with no mid-task communication needed. Each spawned agent uses the same vc-system agents and skills but works on a scoped slice. Orchestrator must stay clean (parent context must not accumulate all output). Time savings: 50–70%. Cost: approximately N× linear token multiplier.
• Workflow: right for deterministic pipelines (full RIPER-5 automation, TDD loop, metric iteration, quality gate sequences), tasks too big for a single context window, or when the item count is unknown upfront. The workflow script calls vc-system agents as agent() calls in pipeline() or parallel() steps. Quality > cost priority. Up to 1000 agents, 16 concurrent. Total tokens roughly the same as sequential — most cost-effective for large volume.
• Agent team: right when 2+ specialist workstreams must share findings mid-execution (not just consume the same input), when named roles are known upfront (e.g. security reviewer + implementer + tester coordinating live), or when an adversarial challenge pattern is required. Uses Claude Code TeamCreate + TaskCreate + SendMessage. Each teammate runs its own vc-agent and skills. NOT for simple fan-out where agents work independently — use parallel subagents for that. Mechanism: a team shares a TaskList and uses SendMessage to coordinate mid-run; parallel subagents have NO inter-agent channel and CANNOT coordinate — so any task that needs mid-execution coordination (e.g. blast-radius non-overlap across phase plans) MUST be agent-team, never parallel subagents.

Phase Program Rule

When a plan describes a program with 3+ phases (phase program classification, signal S4 present):

• Sequential is NEVER valid for plan creation fan-out OR validate fan-out across the phases.
• 3+ phase-plan CREATION default: AGENT TEAM. Phase plans share files (CLAUDE.md, agent .md files) and MUST coordinate blast-radius non-overlap + dependency declarations — only an agent team can do this (TeamCreate + shared TaskList + SendMessage). Fire-and-forget subagents cannot communicate, so they cannot keep blast radii disjoint and are the WRONG strategy for plan creation. (Outer-PVL VALIDATE fan-out across already-written phase plans, where each validator reads one finished plan with no cross-talk, MAY use independent read-only subagents — see the reconciliation note below.)
• Reconciliation (CREATION vs read-only VALIDATE fan-out): validating N already-written plans needs no inter-agent talk, so bare parallel subagents are valid there; plan CREATION needs cross-talk, so it is agent-team. Note orchestration.md even describes Outer PVL as an agent-team — prefer agent-team for both and reserve bare parallel subagents only for truly independent read-only fan-out.
• If phases have complex interdependencies requiring mid-draft communication (e.g., phase 2 plan depends on design decisions surfaced during phase 1 planning): use agent team instead. Assign one teammate per phase, use SendMessage for cross-phase coordination.
• If the total phase count is unknown upfront (e.g., the program scope is discovered incrementally): use workflow so the pipeline can expand without re-spawning the orchestrator. Each agent() call in the workflow runs the appropriate vc-agent for that phase.

Strategy Reference

1 — Sequential (one vc-agent at a time)

The orchestrator runs one vc-agent, waits for it to complete, then routes to the next.

orchestrator → vc-research-agent → (result) → vc-innovate-agent → (result) → vc-plan-agent → ...

• Each agent invokes its own skills (vc-scout, vc-docs-seeker, vc-sequential-thinking, etc.) independently.
• Simplest option. No fan-out overhead. Single context window per phase.
• Hard limit: cannot parallelize. If a phase has 5 independent sections, all 5 run back-to-back.
• Best for: standard single-feature RIPER-5 runs, /goal phase-program execution, trivial fixes delegated directly to vc-execute-agent.

2 — Parallel Subagents (one agent per direction)

The orchestrator spawns multiple vc-agents simultaneously via the Agent tool. Each agent goes in one direction independently, invokes its own skills, and returns a result. The orchestrator merges all results before proceeding.

orchestrator ──► vc-research-agent (direction A)
             ──► vc-research-agent (direction B)   (all run simultaneously)
             ──► vc-research-agent (direction C)
             └── merge all results → route to vc-innovate-agent

• Parent context must stay clean — pass only scoped input to each agent; collect structured output.
• Time savings: 50–70% vs sequential for the fan-out step. Cost: approximately N× token multiplier.
• NOT appropriate when one agent's findings should influence another agent mid-run — use agent team for that.
• Best for: parallel RESEARCH across 5+ distinct codebase areas; parallel VALIDATE across 5+ phase plans; parallel dimension checks in PLAN.

3 — Dynamic Workflow (full RIPER-5 pipeline)

A deterministic Workflow script orchestrates the vc-system agents as programmatic steps. Each agent() call in the script corresponds to a vc-agent running its phase. pipeline() handles per-item fan-out without a barrier. parallel() handles all-results-needed barriers.

workflow script
  phase('Research')   → agent('run vc-research-agent for feature X', {agentType: 'vc-research-agent'})
  phase('Plan')       → pipeline(items, item => agent('write phase plan for ' + item))
  phase('Validate')   → parallel(plans.map(p => () => agent('validate plan ' + p)))
  phase('Execute')    → agent('run vc-execute-agent for plan path', {agentType: 'vc-execute-agent'})

• Supports loop-until-dry, budget-aware iteration, and unknown item counts.
• Each agent() call runs the appropriate vc-system agent and its skills.
• Up to 1000 agents / 16 concurrent. Total tokens roughly equal to sequential — work is distributed.
• Best for: full RIPER-5 automation across many items, TDD fan-out loops, lint/test sweeps, phase-program pipelines where count is unknown upfront.

4 — Agent Team (multiple specialist teammates)

Claude Code's built-in TeamCreate feature provisions named teammates. Each teammate is assigned a specialized role via TaskCreate. Teammates communicate via SendMessage. TaskList tracks in-flight work.

TeamCreate("security-review") → teammate A: runs vc-validate-agent (security dimension)
TeamCreate("implementation")  → teammate B: runs vc-execute-agent (implements)
TeamCreate("test-coverage")   → teammate C: runs vc-tester (writes/runs tests)
SendMessage: A → B (security findings mid-implementation, not after)

• Each teammate runs its own vc-agent (vc-research-agent, vc-plan-agent, vc-execute-agent, vc-tester, vc-debugger, etc.) and invokes the relevant skills for their specialty.
• Named roles known upfront. Mid-execution coordination via SendMessage.
• Highest cost — all teammates are active simultaneously.
• NOT appropriate for simple fan-out where agents work independently — use parallel subagents for that.
• Best for: security reviewer + implementer + tester coordinating live; adversarial plan challenge (one agent proposes, another attacks); multi-specialist investigation where findings from specialist A must reach specialist B before B finalizes.

Source References

• process/development-protocols/orchestration.md — Two-Tier Fan-Out Escalation, Parallel Fan-Out Checkpoints
• process/development-protocols/orchestration.md §VALIDATE Gate — skip conditions, gate verdicts, BLOCKED escalation path

Audit Context

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Use this skill to verify that the project's durable context layer is discoverable and organized.

Optional input: a context group, agent, skill, or folder scope to prioritize during the audit.

Workflow

0. Run find process/context/ -type f | sort to get the full file listing before routing. This ensures no context file is silently skipped when the router is incomplete or drifted.
1. Read process/context/all-context.md for the context routing protocol.
2. Read references/audit-context.md for the full audit process.
3. Run the context discovery validator:

   node .claude/skills/vc-audit-context/scripts/validate-context-discovery.mjs
   

3a. Run the protocol discovery frontmatter validator (enforces discovery frontmatter on every process/development-protocols/**/*.md, recursive incl. vc-system-behavior/; note.md is the only intentional exclusion):

node .claude/skills/vc-audit-context/scripts/validate-protocol-discovery.mjs

4. Run the shared skill routing coverage validator:

   node .claude/skills/vc-audit-context/scripts/validate-skill-routing.mjs
   

5. Run the skill cross-reference validator:

   node .claude/skills/vc-audit-context/scripts/validate-skill-cross-refs.mjs
   

6. Run the skill dependency/confusable analysis:

   node .claude/skills/vc-audit-context/scripts/validate-skill-dependencies.mjs
   node .claude/skills/vc-audit-context/scripts/validate-confusable-skills.mjs
   

7. Regenerate or check the machine-readable skill catalog:

   node .claude/skills/vc-audit-context/scripts/generate-skills-catalog.mjs --write
   node .claude/skills/vc-audit-context/scripts/generate-skills-catalog.mjs --check
   

8. Validate that every SKILL.md carries trigger_keywords + a valid layer (contract|helper) and that the catalog is in sync:

   node .claude/skills/vc-audit-context/scripts/validate-skill-keywords.mjs
   

9. If any script reports failures, inspect the referenced files and patch the smallest relevant surface.
10. Re-run the failed validators until they pass.

For agent/skill harness validation (agent parity, skill frontmatter, README.md sync, protocol wiring), use the audit-vc skill.

Context Bootstrap (when process/context/ doesn't exist or needs full init)

Use when initializing a new project's context layer from scratch:

1. Run vc-scout in parallel across major source directories (skip .git, node_modules, .claude, caches) to gather codebase summaries.
2. Create process/context/all-context.md (routing table, architecture, conventions) and group all-{group}.md entrypoints for any durable domains identified.
3. Parallel reader strategy for existing context files — before updating, spawn subagents proportional to file count: 1-3 files read directly; 4-6 files use 2-3 reader agents; 7+ files use 4-5 reader agents (max 5), distributing by LOC.
4. After generating or updating context files, run find process/context -name '*.md' -print0 | xargs -0 wc -l | sort -rn — files over 800 LOC should be split into a context group or the user asked.
5. Finish by running the discovery validator (step 3 above) before declaring done.

Rules

• Treat .claude/skills/ as canonical; .agents/skills/ is the Codex discovery symlink.
• Treat .claude/skills/vc-audit-context/references/skill-routing-policy.json as the explicit allowlist for intentionally non-routed shared skills.
• Do not move large context files without updating process/context/all-context.md.
• Do not delete compatibility wrappers unless no current reference points to them.
• Keep context groups durable-domain based, not one group per temporary feature.
• When updating agents, mirror Claude markdown and Codex TOML surfaces together.
• Treat validator warnings as audit findings unless the user asks for a strict cleanup.
• Prefer validator-backed routing truth over adding more soft prose.
• Treat process/context/generated-skills-catalog.json as the machine-readable catalog owned by audit-context.

Audit Plans

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Use this skill to review active plan artifacts and reconcile them with the current codebase.

This is a maintenance and recovery skill, not an automatic post-task hook.

Optional input: a feature, folder, plan filename, or maintenance scope to prioritize.

Prefer it when:

• UPDATE PROCESS was skipped and active-plan cleanup drift accumulated
• the user wants a periodic active-plan cleanup pass
• multiple active plans need reconciliation after a burst of work

Workflow

1. Read references/audit-plans.md for the full audit process.
2. Run the inventory validator:

   node .claude/skills/vc-audit-plans/scripts/validate-plan-inventory.mjs
   

3. Inventory plans in process/general-plans/active/ and process/features/*/active/. Plans now live inside {slug}_{date}/ task subfolders — scan one level deep. Do NOT count _REPORT_, _REF_, or _SPEC_ files inside task folders as plans; only _PLAN_ files count. For feature-scoped audits, first run find process/features/{feature}/ -type f | sort for full artifact visibility. For full audits, run find process/features/ -type f | sort to see all feature artifacts across all subdirs (active, completed, backlog, references, reports). 3.5. Scan task folder contents (co-located REPORT/REF/SPEC files) alongside each plan. Per task-folder artefact colocation, the correct home for every artefact (plan, spec, reports, references) is INSIDE its {slug}_{date}/ task folder; flag any task artefact found in the deprecated sibling reports//references/ dirs or any ad-hoc location as mis-located, and recommend moving it into the owning task folder. Match by feature slug, date proximity (7 days), or content reference to the plan filename.
4. Cross-check each plan against the actual codebase with file existence checks and targeted rg searches.
5. Classify each plan as Completed, Partially Done, Obsolete, Stale, Active, or Reference.
6. Move only clearly completed or obsolete plans to the appropriate completed/ folder. Use git mv active/{slug}_{date}/ completed/{slug}_{date}/ — move the WHOLE task folder; no completed_ prefix added.
7. Ask before deleting anything.
8. Re-run the inventory validator after moving or editing plan files.

Output

Return a concise summary table with classification, action taken, and any user decisions needed. Include stale artifact findings (reports/references tied to completed or obsolete plans) with recommended actions.

Audit VC (Version Control Harness Health)

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Use this skill to verify that the agent harness layer is internally consistent and correctly wired across Claude, Codex, README.md, and protocol files.

For context routing, grouping, and discoverability audits, use the audit-context skill instead.

Workflow

1. Run the Claude/Codex agent parity validator:

   node .claude/skills/vc-audit-vc/scripts/validate-agent-parity.mjs
   

2. Run the shared skill discovery validator:

   node .claude/skills/vc-audit-vc/scripts/validate-skills.mjs
   

3. Run the README.md sync validator:

   node .claude/skills/vc-audit-vc/scripts/validate-guide-sync.mjs
   

4. Run the protocol wiring validator:

   node .claude/skills/vc-audit-vc/scripts/validate-protocol-wiring.mjs
   

5. Run the seed/scaffold consistency validator:

   node .claude/skills/vc-audit-vc/scripts/validate-seeds.mjs
   

6. Run the kit portability validator:

   node .claude/skills/vc-audit-vc/scripts/validate-kit-portability.mjs
   

7. Run the skill invocation wiring validator:

   node .claude/skills/vc-audit-vc/scripts/validate-skill-invocation-wiring.mjs
   

8. Run the agent frontmatter validator:

   node .claude/skills/vc-audit-vc/scripts/validate-agent-frontmatter.mjs
   

9. If any script reports failures, inspect the referenced files and patch the smallest relevant surface.
10. Re-run the failed validators until they pass.

Rules

• Treat .claude/agents/ as canonical for agent definitions; .codex/agents/ mirrors them.
• Treat .claude/skills/ as canonical for skills; .agents/skills/ is the Codex discovery symlink.
• When updating agents, mirror Claude markdown and Codex TOML surfaces together.
• Treat process/_seeds/ as an optional legacy scaffold surface in the live repo. Its absence is a warning-only audit result unless the user is explicitly auditing export-kit scaffolding.
• Treat validator warnings as audit findings unless the user asks for a strict cleanup.
• For context routing and discoverability audits, delegate to audit-context.

vc-autopilot

Contract skill that owns the provisional goal block artifact for Autopilot Mode sessions. This skill is invoked by the orchestrator to emit, validate, and resume from the goal block. The canonical protocol lives in process/development-protocols/autopilot.md.

When To Invoke

Invoke this skill when:

• The orchestrator has just received an autopilot trigger phrase and needs to emit the provisional goal block after the consolidated clarification round.
• The orchestrator detects a pasted goal block at session start and needs to determine whether it is a resume scenario (goal block already present → no new clarification round).
• The validate-autopilot-goal-block.mjs D1 validator needs to be run against an artifact.

Skill Artifact

The provisional goal block — a structured text block of ≤ 4000 characters with exactly 9 named fields. The canonical field spec lives in process/development-protocols/autopilot.md §Provisional Goal Block Format. This skill does not redefine the spec — it references it.

Required fields (exact string anchors — do not rename or abbreviate):

1. SESSION GOAL:
2. ENTRY PHASE:
3. REMAINING PHASES:
4. CLARIFICATIONS LOCKED:
5. EXECUTE CONSENT: — must contain the literal text standing-granted
6. DECISION POLICY:
7. HARD STOPS:
8. TEST GATES:
9. START:

Emission Procedure

Step-by-step for the orchestrator:

1. Complete the consolidated clarification round (process/development-protocols/autopilot.md §Consolidated Clarification Round).
2. Determine ENTRY PHASE from on-disk artifact detection (autopilot.md §Trigger-Anywhere Detection Flow).
3. Build the REMAINING PHASES checklist: for each phase not yet complete in canonical RIPER-5 order, add a [ ] checkbox line with the phase name and planned execution strategy.
4. Fill in all 9 fields using the locked clarification answers.
5. Count total characters. If > 4000: compress DECISION POLICY and CLARIFICATIONS LOCKED to summaries and reference autopilot.md for full detail.
6. Print the block to chat as a fenced code block.
7. Write the block to disk: {task-folder}/{slug}_AUTOPILOT_GOAL_{dd-mm-yy}.md (header: "Emitted: [datetime]. Provisional block. V7 will emit (UPDATE) variant.").
8. Emit AUTOPILOT_ACTIVATED: [task] — entry phase: [phase] — goal block emitted.

Resume Detection

How the orchestrator recognizes a pasted goal block at session start:

• If the user message contains all 9 field names as headings/labels, treat it as an autopilot resume.
• On resume: skip the consolidated clarification round entirely. Read ENTRY PHASE and REMAINING PHASES from the pasted block. Read CLARIFICATIONS LOCKED as the already-locked decisions. Read DECISION POLICY and HARD STOPS as the standing policy.
• Emit [MODE: AUTOPILOT | <ENTRY PHASE>] and begin the run from START:.
• Do NOT issue a new clarification round (SPEC AC-14).

V7 UPDATE Variant

When VALIDATE V7 completes during an autopilot run, the orchestrator:

1. Reads the real gate commands from the new validate-contract.
2. Copies the provisional block.
3. Prefixes SESSION GOAL: with (UPDATE) .
4. Replaces TEST GATES: TBD — populated after VALIDATE with the actual gate commands.
5. Updates START: to reflect post-VALIDATE state.
6. Prints the updated block to chat.
7. Appends an ## (UPDATE) [YYYY-MM-DD] section to the disk file (never overwrites the original).

Validator

Run after writing any goal block artifact to confirm it passes D1 checks:

node .claude/skills/vc-autopilot/scripts/validate-autopilot-goal-block.mjs <artifact-path>

Exit 0 = PASS (all 9 required fields present, EXECUTE CONSENT contains standing-granted, total ≤ 4000 chars). Exit 1 = FAIL (one or more checks failed — error printed to stdout). WARN printed (exit 0) when TEST GATES: contains TBD (reminder that V7 UPDATE is pending).

See scripts/validate-autopilot-goal-block.mjs and fixtures/ for the D1 validator and pass/fail fixture pair.

vc-autoresearch

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Reusable loop primitive. Runs: find gaps → write report → fix → check → repeat.

Used directly for spec/doc/UX hardening. Wired into PVL (plan-validate-fix loop — the fix cycle between writing a plan and approving EXECUTE) and EVL (execute-validate-fix loop — the confirmation run after EXECUTE) as the shared bookkeeping layer.

When To Invoke

• Standalone: user says "harden this spec", "fix all lint errors", "improve test coverage"
• PVL: the ORCHESTRATOR invokes it when vc-validate-agent returns a first-pass CONDITIONAL/BLOCKED verdict (validate-fix loops are needed)
• EVL: the ORCHESTRATOR invokes it at the EVL confirmation run — unconditionally after every EXECUTE DONE, before UPDATE PROCESS

Do NOT invoke during RESEARCH or INNOVATE phases.

Who Runs This (Loop Driver)

The ORCHESTRATOR is the loop driver. It executes every bookkeeping step itself:

• Step 0 setup — creates the task folder and the results.tsv tracking file.
• Cycle counter + per-cycle iteration report — writes one report file per loop iteration.
• TSV row — appends a row to results.tsv after each cycle.
• Plateau/cap/regression checks — stops the loop when no progress is made for 3 cycles (HALT_PLATEAU — no improvement after 3 tries), when the hard 10-cycle limit is hit (HALT_CAP), or when a test that was passing now fails (HALT_REGRESSION).

Subagents (vc-validate-agent, vc-tester, vc-plan-agent, vc-execute-agent) are fire-and-forget: they emit a verdict and terminate. They cannot invoke this skill on the orchestrator's behalf, cannot loop themselves, and cannot spawn each other.

If no one runs Step 0, the loop never exists and verdicts silently become "proceed" — that failure mode is exactly what this section forbids.

Per-verdict routing tables: process/development-protocols/orchestration.md §PVL/EVL Loop Routing.

Subcommands

Not ported (already covered by existing vc-system skills): debug → vc-debugger, security → vc-security, scenario → vc-scenario, predict → vc-predict.

Parameters

Canonical Domain Defaults

Full configs in process/development-protocols/vc-autoresearch-spec.md §Canonical domain configs.

* harness full config: .claude/skills/vc-autoresearch/domains/harness.md

Loop Execution

Step 0 — Setup

1. Parse parameters, apply domain defaults for any missing values
2. If auto_run: not set and NOT under /goal: prompt once — "Auto-run (no pauses) or confirm before each fix batch?" Choice is sticky for the full loop.
3. Create task folder: process/features/{feature}/active/{task_slug}_{dd-mm-yy}/
4. Initialize TSV at {task_folder}/results.tsv with header row and baseline row (iteration 0, gaps_found: TBD, loop_status: baseline)

Step 1 — Research

Spawn research_agents: parallel agents. Each agent:

• Reads the corpus files assigned to it
• Investigates its thread list (cross-file consistency, missing cases, contradictions, undefined behaviors, etc.)
• Returns a structured gap list: SEVERITY: FAIL | CONCERN | OBSERVATION per finding

Collect all findings. Count: gaps_found, fail_count, concern_count.

Apply severity floor: if iteration > severity_escalation_at, discard CONCERN findings (add to backlog section of report — do not fix).

Step 2 — Convergence check

"Until agents find no gaps" (no verify: param):

• If all agents returned zero findings above the severity floor: increment consecutive_all_clear counter
• If counter >= consecutive_all_clear: → SUCCESS
• Else: reset counter, continue to Step 3

"Hit the metric goal" (verify: param set):

• Run verify command, parse numeric output
• If output reaches target: → SUCCESS
• Else: continue to Step 3

Step 3 — Termination check (non-success)

Check in priority order:

1. PLATEAU — gaps_found unchanged or increased for 3 consecutive iterations → HALT_PLATEAU
2. CAP — iteration >= max_iterations → HALT_CAP
3. REGRESSION — more than 2 new gaps in areas that were gap-free last iteration → HALT_REGRESSION (always pauses for user, even under /goal)

If none triggered: continue to Step 4.

Step 4 — Write iteration report

Write a NEW per-iteration report file: {task_folder}/{task_slug}-iteration-{NNN}_REPORT_{dd-mm-yy}.md — {NNN} is the zero-padded 3-digit iteration number (001, 002, … 042), so files sort correctly and every iteration is uniquely named no matter how many run.

ONE FILE PER ITERATION — hard rule. NEVER append iterations to a single rolling file (no ITERATION-NOTES.md, no shared {task_slug}_REPORT_*.md updated in place). The rolling cross-iteration view is results.tsv, nothing else.

Append a row to {task_folder}/results.tsv.

If auto_run: false: surface gap summary, wait for user confirmation before fixing.

Step 5 — Fix

Spawn fix_agents: parallel agents. Each agent:

• Receives its assigned gap IDs and file targets
• Applies fixes
• Reports: APPLIED (fixed in this iteration) or BACKLOG (deferred, with reason)

Step 6 — Safety check

If guard: is set: run guard command.

• Passes → loop back to Step 1
• Fails → revert fix batch, log regression flag, retry this iteration. If regression budget exceeded (> 2 flags in one iteration) → HALT_REGRESSION

Step 7 — Loop

Increment iteration counter. Go to Step 1.

Termination Output

On any terminal state, write final iteration report with loop_status: set, then emit:

AUTORESEARCH COMPLETE
Domain:          {domain}
Iterations run:  N
Terminal state:  SUCCESS | HALT_PLATEAU (no progress after 3 cycles) | HALT_CAP (10-cycle hard limit) | HALT_REGRESSION (passing test now fails) | HALT_SEVERITY (critical gap found)
Gaps remaining:  N (FAIL: N, CONCERN: N)
Files updated:   [list]
Report:          {task_folder}/{task_slug}-iteration-{NNN}_REPORT_{dd-mm-yy}.md  (final iteration)
TSV:             {task_folder}/results.tsv

PVL Wiring

When vc-autoresearch is the bookkeeper for a PVL (plan-validate-fix loop):

• domain: plan, corpus: = the plan .md file
• Research step = vc-validate-agent runs V1–V3 gates; autoresearch does NOT run these itself. The validate step itself fans out in parallel via vc-validate-findings (Layer 1 dimension agents + Layer 2 feasibility agents) — that parallelism is owned by vc-validate-agent.
• Gap signal = FAIL / CONDITIONAL / CONCERN from validate-agent
• Fix step (parallel) = when the gap set spans independent plan sections, the orchestrator spawns multiple parallel plan-fix agents, one per independent gap group, partitioned so no two agents edit the same plan region. fix_agents: defaults to the count of independent gap groups (cap to the plan-domain default unless raised). Each fixer is scoped to its assigned gap IDs only. When gaps are interdependent or touch one section, fall back to a single plan-fix agent.
• Convergence = validate-agent returns PASS → SUCCESS
• Cap = 10 plan-validate-fix loops
• Per-cycle report = every PVL cycle writes its own report file {task_folder}/{plan-slug}-pvl-iteration-{NNN}_REPORT_{dd-mm-yy}.md (zero-padded {NNN}) capturing: gaps found (with severity), fixes applied vs backlogged, and the validate verdict for that cycle. Never a single rolling notes file.

Boundary:

• vc-autoresearch owns: iteration counter, plateau detection, per-cycle iteration report, regression flag, parallel-fix partitioning (which gap groups go to which fixer) — all executed by the ORCHESTRATOR at each cycle boundary; no agent runs these implicitly
• vc-validate-agent owns: V1–V7 gate sequence + its own Layer-1/Layer-2 fan-out, SUPPLEMENT REQUEST format, validate-contract write, known-gap exclusion — it emits its verdict and terminates; the orchestrator re-spawns it from V1 after each SUPPLEMENT_APPLIED

EVL Wiring

When vc-autoresearch is the bookkeeper for an EVL (execute-validate-fix loop):

• domain: tests, verify: = validate-contract gate commands (read from contract — never invented)
• Research step = a SPAWNED vc-tester agent runs the validate-contract fully-automated gate commands (vc-tester may run independent gate groups in parallel). The orchestrator NEVER runs gate commands in its own shell — a gate result not produced by a vc-tester spawn does not count as an EVL confirmation, even if green.
• Gap signal = failing gate (non-zero exit)
• Fix step (parallel) = when multiple independent gates fail across non-overlapping file groups, the orchestrator spawns multiple parallel execute-fix agents (vc-execute-agent in supplement mode), one per failing gate / file group, partitioned so no two agents edit the same file. Each fixer is scoped to exactly its failing gate — no scope expansion. When failing gates share files or a single root cause, fall back to a single execute-fix agent. The fix is ALWAYS a vc-execute-agent spawn — the orchestrator never edits source files itself, no matter how small the fix.
• Convergence = all validate-contract fully-automated gates pass → SUCCESS
• Cap = 10 execute-validate-fix loops
• Per-cycle report = every EVL cycle writes its own report file {task_folder}/{plan-slug}-evl-iteration-{NNN}_REPORT_{dd-mm-yy}.md (zero-padded {NNN}) capturing: which gates ran, which failed (with trimmed failure output), fixes applied, and the re-run result for that cycle. Never a single rolling notes file.

Boundary:

• vc-autoresearch owns: iteration counter, plateau detection, TSV log, per-cycle iteration report, HANDOFF SUMMARY trigger, parallel-fix partitioning (which failing gate goes to which fixer) — all executed by the ORCHESTRATOR at each cycle boundary; no agent runs these implicitly
• vc-tester owns: which gate commands to run, HANDOFF SUMMARY format, agent-probe re-invocation — its confirmation run is UNCONDITIONAL after every EXECUTE DONE (execute-agent's internal iterate-until-green loop never substitutes for it); it reports failing gates and terminates; the orchestrator runs the fix cycle and re-spawns it

Iteration Report Format

See process/development-protocols/vc-autoresearch-spec.md §Iteration report for full frontmatter schema and body sections.

Gap entry format:

### GAP-I{N}-{ID} — {short title}
- **SEVERITY:** FAIL | CONCERN | OBSERVATION
- **LOCATION:** {file} §{section}
- **GAP:** {what is missing or wrong}
- **RESOLUTION:** {what was changed}
- **STATUS:** APPLIED | BACKLOG

Each iteration report is written inside the active task folder as {slug}-iteration-{NNN}_REPORT_{dd-mm-yy}.md with {NNN} zero-padded to 3 digits (task-folder artefact colocation — never a sibling reports/ dir). One file per iteration; PVL/EVL cycles use the {plan-slug}-pvl-iteration-{NNN} / {plan-slug}-evl-iteration-{NNN} slug variants.

TSV Log Format

Header row:

iteration	timestamp	gaps_found	fail_count	concern_count	applied	saturation_status	loop_status	notes

• Baseline row = iteration 0, before any fixes, loop_status: baseline
• One row appended after each iteration's fix batch completes
• saturation_status: ACTIVE | PLATEAU | SATURATED
• loop_status: CONTINUE | HALTED_SUCCESS | HALTED_PLATEAU | HALTED_CAP | HALTED_REGRESSION

Run vc-autoresearch:evals {task_folder}/results.tsv to analyze trends and get a plateau/recommendation report.

Hook Notes

• iteration-context.cjs — injects last 3 TSV rows at UserPromptSubmit; must scan process/features/*/active/*/results.tsv (not project-root autoresearch/ paths)
• session-init.cjs — active plan summary at SessionStart; adapted to scan process/general-plans/active/ and process/features/*/active/
• stop-notify.cjs — terminal notification at SessionEnd; no changes needed
• Do NOT register scout-block.cjs or privacy-block.cjs from the autoresearch reference repo — vc-system settings.json has superior versions; registering them would cause conflicts

vc-context-discovery

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Discover and load all relevant context for the current task. This skill lists feature group nested files with full paths and loads process/context/ files by domain routing table. It is the canonical context-loading entrypoint for every agent session.

When To Invoke

At the start of every agent session (research, innovate, plan, validate, execute, update-process, fast-mode). Also at the start of any skill that needs repo context before operating.

Frontmatter Schemas

Document the canonical schemas for three file types used across the repo. These schemas enable frontmatter-aware routing and filtering.

Context file frontmatter schema:

name: context:{slug}
description: "one-line scope — used by vc-context-discovery for routing"
keywords: comma, separated, task, vocabulary, terms   # drives grep-first keyword routing
related: [context:{other-slug}, context:{another-slug}]  # sibling/cross-group links (optional)
date: dd-mm-yy

• keywords — strongly recommended, non-empty. Comma-separated task-vocabulary terms an agent would use to describe a task this doc serves (e.g. session, token, refresh, jwt, login). This is the match surface for discover-context.mjs --match; weak/absent keywords are why a relevant doc never gets routed to. Lint WARNS when empty (so existing projects don't break on sync) — backfill at UPDATE-PROCESS.
• related — OPTIONAL list of context:{slug} values for sibling docs that are usually needed together (the markdown-native equivalent of cross-links). Every slug listed MUST resolve to a real context: doc; dangling links fail lint. Discovery follows these after the primary match so a task touching two domains loads both.

Plan file frontmatter schema:

name: plan:{slug}
description: "one-line scope and feature"
date: dd-mm-yy
feature: {feature-folder-name}
phase: "{phase-id}"  # optional, for phase program plans only

Report file frontmatter schema:

name: report:{slug}
description: "one-line scope"
date: dd-mm-yy
metadata:
  node_type: memory
  type: report
  feature: {feature-folder-name}
  phase: {phase-id}

Invocation

Primary method — run the auto-discovery script. It lists all nested files under process/context/, process/development-protocols/, process/general-plans/active/, and (with --feature) the feature folder, extracting ONLY the leading YAML frontmatter block of each .md file (no whole-file reads):

node .claude/skills/vc-context-discovery/scripts/discover-context.mjs [--feature <name>] [--json]

The script groups output into: context files with frontmatter, protocol files, feature files by subfolder, active general plans, and files-without-frontmatter (path only). It never throws on a missing root and exits 0 unless given a bad flag. Use --json for a machine-readable object. Prefer this over manually reading each file — it is deterministic and avoids loading huge files into context.

Keyword-first routing (deterministic, not judgment). When the task vocabulary does not obviously map to a routing-table row, do not guess — let the index do the matching:

node .claude/skills/vc-context-discovery/scripts/discover-context.mjs --match "update the user ORM model"

This tokenizes the task and ranks context docs by overlap with their frontmatter keywords, then appends any related: siblings of the top hits. Read the ranked docs in order. This is the fallback that fixes "the right doc existed but the agent walked past it."

Routing-table generation (drift-proof index). The "Current Root Entry Points" and "Current Context Groups" tables in all-context.md are GENERATED from frontmatter, not hand-authored — they live between <!-- GENERATED:routing --> / <!-- /GENERATED:routing --> markers. Rebuild them after any context-org change:

node .claude/skills/vc-context-discovery/scripts/discover-context.mjs --emit-routing   # rewrites the block
node .claude/skills/vc-context-discovery/scripts/discover-context.mjs --check-routing  # lint: block in sync?

The hand-authored Task Routing Table (task-type → file) stays editorial and is NOT generated.

Per task-folder artefact colocation, the script surfaces each task's plan, spec, reports, and references INSIDE its own {slug}_{date}/ task folder; the sibling reports//references/ dirs are deprecated and only hold legacy artefacts.

Workflow (manual FALLBACK)

Use these steps only if the script above fails or is unavailable.

Step 1. Run find process/context/ -type f | sort and record all available context files.

Step 2. Run find process/development-protocols/ -type f | sort and record all protocol files.

Step 3. Read process/context/all-context.md to get the routing table and current feature list.

Step 4. If a feature name was provided as the argument, run find process/features/{feature}/ -type f | sort to list ALL artifacts across all subfolders (active/, completed/, backlog/, plus any legacy reports/, references/). Surface full file paths — not just folder names. Per task-folder artefact colocation, expect each task's plan, spec, reports, and references INSIDE its own {slug}_{date}/ task folder; the sibling reports//references/ dirs are deprecated and only hold legacy artefacts.

Step 5. If no feature name was provided, run find process/general-plans/active/ -type f | sort to surface any active plans relevant to the current task. Note: plan files are inside {slug}_{date}/ task subfolders — look one level deep for *_PLAN_*.md files.

Step 6. From the routing table in all-context.md, identify the context group files relevant to the current task domain (e.g. tests, container, infra, skills, uxui, workflows). Do NOT read every context file — only the ones the routing table says apply to this domain. If no row obviously matches, run discover-context.mjs --match "<task>" and use its ranked keyword hits instead of guessing.

Step 7. Read the domain context file(s) identified in step 6. Each all-{group}.md is a router — after reading it, follow its routing table to load the deeper domain file(s) for the task. Then load any related: siblings of the docs you read — a task spanning two domains (e.g. auth + tests) needs both, and related is how the cross-domain link is declared.

Step 8. Frontmatter extraction: For each file in the discovered set, if the file has YAML frontmatter (a --- block at top), extract the name, description, and date fields. Surface in output as "[path] (name: X — description: Y)". Files without frontmatter: surface path only (no error, do not skip them).

Step 9. Report: full file listing for the feature folder (if applicable), active context files loaded, and any open gaps in context that would block the task.

Output Format

Context file paths with frontmatter:
  process/context/skills/skill-apps.md (context:skill-apps — Skill app runtime, vite architecture, ctx-gateway, deployment)
  process/context/tests/all-tests.md (context:all-tests — Test routing, runner split, debugging procedures)

Plan files with frontmatter:
  process/features/{feature}/completed/{slug}_{date}/{slug}_PLAN_{date}.md (plan:{plan-name} — short description...)

Files without frontmatter (path only):
  process/context/ui/design.md

Context Envelope

At session start, every inner-loop agent (research / plan / execute / update-process) emits a Context Envelope — a 10-field table capturing the orientation an agent needs to act. All 10 fields are required (use best-effort values; TBD — [reason] when not yet determinable). The fields MUST appear in the EXACT canonical C-2 order below — identical order in this SKILL and in all four inner-loop agents:

Canonical order (memorize): feature → phase → session-goal → branch → worktree → context-group → blast-radius-packages → active-plan → test-runner → validate-contract.

test-runner multi-runner rule: the pipe-delimited bun test | vitest value is a DISPLAY convention only. The phase-loop workflow template (.claude/skills/vc-generate-phase-program/templates/phase-loop-workflow-template.js) expands it into SEQUENTIAL test steps (bun test THEN vitest) — a literal bun test | vitest shell pipe is NEVER emitted or run. See 03-session-start.md for the matching field table.

Frontmatter-Aware Routing

After collecting file paths, read YAML frontmatter from each file where present.

Surface the following fields alongside path: name, description, keywords, related, date, type, feature, phase.

Use the description and keywords fields for routing decisions instead of filename inference.

Group plan files by their feature field value.

Filter and sort by type field (context / plan / report / references).

Discover all nested files under feature group subdirs: active/, completed/, backlog/, reports/, references/.

Files without frontmatter: surface path only (no error), do not skip them.

Important Rules

• This skill is INDEPENDENT — it does not invoke other skills.
• Read all-context.md as a router, then load the deeper file(s). Do not treat all-context.md as sufficient on its own.
• Always produce the full find output, not a summary. The exact file paths are the output.
• Never hardcode context file paths — always discover via the find command and the routing table in all-context.md.

Debugging & System Investigation

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Comprehensive framework combining systematic debugging, root cause tracing, defense-in-depth validation, verification protocols, and system-level investigation (logs, CI/CD, databases, performance).

Core Principle

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

Random fixes waste time and create new bugs. Find root cause, fix at source, validate at every layer, verify before claiming success.

When to Use

Code-level: Test failures, bugs, unexpected behavior, build failures, integration problems System-level: Server errors, CI/CD pipeline failures, performance degradation, database issues, log analysis Always: Before claiming work complete

Techniques

1. Systematic Debugging (references/systematic-debugging.md)

Four-phase framework: Root Cause Investigation → Pattern Analysis → Hypothesis Testing → Implementation. Complete each phase before proceeding. No fixes without Phase 1.

Load when: Any bug/issue requiring investigation and fix

2. Root Cause Tracing (references/root-cause-tracing.md)

Trace bugs backward through call stack to find original trigger. Fix at source, not symptom. Includes scripts/find-polluter.sh for bisecting test pollution.

Load when: Error deep in call stack, unclear where invalid data originated

3. Defense-in-Depth (references/defense-in-depth.md)

Validate at every layer: Entry validation → Business logic → Environment guards → Debug instrumentation

Load when: After finding root cause, need comprehensive validation

4. Verification (references/verification.md)

Iron law: NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE. Run command. Read output. Then claim result.

Load when: About to claim work complete, fixed, or passing

5. Investigation Methodology (references/investigation-methodology.md)

Five-step structured investigation for system-level issues: Initial Assessment → Data Collection → Analysis → Root Cause ID → Solution Development

Load when: Server incidents, system behavior analysis, multi-component failures

6. Log & CI/CD Analysis (references/log-and-ci-analysis.md)

Collect and analyze logs from servers, CI/CD pipelines (GitHub Actions), application layers. Tools: gh CLI, structured log queries, correlation across sources.

Load when: CI/CD pipeline failures, server errors, deployment issues

7. Performance Diagnostics (references/performance-diagnostics.md)

Identify bottlenecks, analyze query performance, develop optimization strategies. Covers database queries, API response times, resource utilization.

Load when: Performance degradation, slow queries, high latency, resource exhaustion

8. Reporting Standards (references/reporting-standards.md)

Structured diagnostic reports: Executive Summary → Technical Analysis → Recommendations → Evidence

Load when: Need to produce investigation report or diagnostic summary

9. Task Management (references/task-management-debugging.md)

Track investigation pipelines via Claude Native Tasks (TaskCreate, TaskUpdate, TaskList). Hydration pattern for multi-step investigations with dependency chains and parallel evidence collection. Fallback: Task tools are CLI-only — if unavailable (VSCode extension), use TodoWrite for tracking. Debug workflow remains fully functional.

Load when: Multi-component investigation (3+ steps), parallel log collection, coordinating debugger subagents

10. Frontend Verification (references/frontend-verification.md)

Visual verification of frontend implementations via Chrome MCP (Claude Chrome Extension) or vc-agent-browser skill fallback. Detect if frontend-related → check Chrome MCP availability → screenshot + console error check → report. Skip if not frontend.

Load when: Implementation touches frontend files (tsx/jsx/vue/svelte/html/css), UI bugs, visual regressions

Quick Reference

Code bug       → systematic-debugging.md (Phase 1-4)
  Deep in stack  → root-cause-tracing.md (trace backward)
  Found cause    → defense-in-depth.md (add layers)
  Claiming done  → verification.md (verify first)

System issue   → investigation-methodology.md (5 steps)
  CI/CD failure  → log-and-ci-analysis.md
  Slow system    → performance-diagnostics.md
  Need report    → reporting-standards.md

Frontend fix   → frontend-verification.md (Chrome/devtools)

Tools Integration

• Database: sqlite3 CLI and drizzle-kit studio for SQLite/libSQL diagnostics
• CI/CD: gh CLI for GitHub Actions logs and pipeline debugging
• Codebase: vc-docs-seeker skill for package/plugin docs; vc-scout skill for codebase exploration
• Scouting: /vc-scout or /vc-scout ext for finding relevant files
• Frontend: Chrome browser or vc-agent-browser skill for visual verification (screenshots, console, network)
• Skills: Activate vc-problem-solving skill when stuck on complex issues

Red Flags

Stop and follow process if thinking:

• "Quick fix for now, investigate later"
• "Just try changing X and see if it works"
• "It's probably X, let me fix that"
• "Should work now" / "Seems fixed"
• "Tests pass, we're done"

All mean: Return to systematic process.

Documentation Discovery

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Overview

Use Context7 MCP as the default path for documentation lookup. The local scripts in this skill are fallback helpers for llms.txt-based discovery when Context7 does not cover the target cleanly.

Primary Workflow

Default workflow: Context7 first

1. Resolve the library with Context7.
2. Query the exact API/config/setup question with Context7.
3. Only fall back to the scripts below when Context7 coverage is missing, incomplete, or the user explicitly wants llms.txt/repository-oriented discovery.

Fallback script workflow:

# 1. DETECT query type (topic-specific vs general)
node scripts/detect-topic.js "<user query>"

# 2. FETCH documentation using script output
node scripts/fetch-docs.js "<user query>"

# 3. ANALYZE results (if multiple URLs returned)
cat llms.txt | node scripts/analyze-llms-txt.js -

Scripts handle URL construction, fallback chains, and error handling automatically.

Scripts

detect-topic.js - Classify query type

• Identifies topic-specific vs general queries
• Extracts library name + topic keyword
• Returns JSON: {topic, library, isTopicSpecific}
• Zero-token execution

fetch-docs.js - Retrieve documentation

• Constructs context7.com URLs automatically
• Handles fallback: topic → general → error
• Outputs llms.txt content or error message
• Zero-token execution

analyze-llms-txt.js - Process llms.txt

• Categorizes URLs (critical/important/supplementary)
• Recommends agent distribution (1 agent, 3 agents, 7 agents, phased)
• Returns JSON with strategy
• Zero-token execution

Workflow References

Topic-Specific Search - Fastest path (10-15s)

General Library Search - Comprehensive coverage (30-60s)

Repository Analysis - Fallback strategy

References

context7-patterns.md - URL patterns, known repositories

errors.md - Error handling, fallback strategies

advanced.md - Edge cases, versioning, multi-language

Execution Principles

1. Context7 first - Use Context7 MCP before any local script fallback
2. Zero-token overhead - Scripts run without context loading
3. Automatic fallback - Scripts handle topic → general → error chains
4. Progressive disclosure - Load workflows/references only when needed
5. Scripts are fallback helpers - Use them only when Context7 coverage is missing or the user wants llms.txt-style discovery

Quick Start

Topic query: "How do I use date picker in shadcn?"

node scripts/detect-topic.js "<query>"  # → {topic, library, isTopicSpecific}
node scripts/fetch-docs.js "<query>"    # → 2-3 URLs
# Use Context7 results first; only use script-discovered URLs when you intentionally fall back

General query: "Documentation for Next.js"

node scripts/detect-topic.js "<query>"         # → {isTopicSpecific: false}
node scripts/fetch-docs.js "<query>"           # → 8+ URLs
cat llms.txt | node scripts/analyze-llms-txt.js -  # → {totalUrls, distribution}
# Use Context7 results first; only use script-discovered URLs when fallback discovery is required

Environment

Scripts load .env: process.env > .claude/skills/vc-docs-seeker/.env > .claude/skills/.env > .claude/.env

Optional env vars: CONTEXT7_API_KEY (Bearer token for Context7 API), DEBUG=true (verbose logging).

vc-feasibility-test

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

One-shot empirical probe skill. Used when SPEC or INNOVATE encounters an approach hinging on an unverified external/runtime/library mechanism — the question is "does this mechanism actually work the way the design assumes?", asked before the decision locks.

Boundary vs vc-test-coverage-plan

These two skills are complementary and must not be confused:

• vc-feasibility-test (this skill) = PRE-decision. "Does the mechanism work at all?" Run before SPEC/INNOVATE locks an approach, when the answer is unknown. Output: a one-shot VERDICT artifact.
• vc-test-coverage-plan = POST-plan. "How do I cover this blast radius across the 4 test tiers?" Run after a plan exists, when the design is already chosen. Output: a per-area tier table.

If the approach is already decided and you are assigning test tiers → use vc-test-coverage-plan. If you cannot decide because a mechanism is unverified → use this skill first.

When To Invoke

• When vc-spec-agent, vc-innovate-agent, or a vc-validate-agent Layer 2 dimension agent emits VC-FEASIBILITY-PROBE-NEEDED
• When a mechanism cannot be verified from source code alone
• One-shot: not an iterative loop (use vc-autoresearch for iteration)

Skill Executor

Always executed by vc-debugger (via the VC-FEASIBILITY-PROBE-NEEDED signal routing in orchestration.md). SPEC, INNOVATE, and VALIDATE Layer 2 agents do not run probes themselves.

Probe-Method Taxonomy (pick one family)

Every probe belongs to one of these 8 families. Name the chosen family in the VERDICT. Each family has a default cost/safety class (see next section) — the probe inherits it.

If none of the 8 fit, the question is probably not a feasibility probe — reconsider whether vc-research-agent (unknown context) or vc-test-coverage-plan (known design) is the right tool instead.

Probe Cost / Safety Class (MANDATORY GATE)

Every VERDICT declares one cost class. The class governs whether the probe may run unattended or needs explicit opt-in. A probe that cannot be run within its safety gate produces an INCONCLUSIVE verdict — it is never silently skipped or faked.

The emitted VC-FEASIBILITY-PROBE-NEEDED signal SHOULD carry the anticipated cost class so the orchestrator can resolve the opt-in gate before dispatching vc-debugger (see orchestration.md §VC-FEASIBILITY-PROBE-NEEDED Signal Routing).

Probe Execution Steps

1. Read the hypothesis from the VC-FEASIBILITY-PROBE-NEEDED signal
2. Pick the probe family (1–8) and its cost class
3. Confirm the safety gate for that cost class is met. If not → write an INCONCLUSIVE verdict with the gate-not-met reason and stop. Do NOT escalate to a higher-cost probe or run against a shared resource.
4. Design the minimal probe within that family
5. Run the probe empirically — capture actual output, not expected output
6. Analyze the evidence: does it confirm or refute the hypothesis?
7. Assign a verdict: VIABLE | NOT-VIABLE | INCONCLUSIVE
8. Write the VERDICT artifact to the active task folder

VERDICT Artifact Format

Filename: {slug}_FEASIBILITY_{dd-mm-yy}.md Location: same active task folder as the SPEC/plan that triggered the probe

Required frontmatter fields (MUST be present — validated by validate-feasibility-verdict.mjs):

---
slug: [task-slug]
date: YYYY-MM-DD
verdict: VIABLE | NOT-VIABLE | INCONCLUSIVE
originating-phase: spec | innovate | pvl
---

The originating-phase: field is REQUIRED. Valid values:

• spec — probe triggered by vc-spec-agent ([SP3])
• innovate — probe triggered by vc-innovate-agent ([I2.5])
• pvl — probe triggered by vc-validate-agent Layer 2 ([V2-PROBE])

Required sections (MUST be present — validated by validate-feasibility-verdict.mjs):

Hypothesis

One-sentence statement of what is being tested.

Mechanism Under Test

The specific external, runtime, or library behavior being probed.

Probe Family

One of the 8 families above (e.g. 5 — Container exec / internal-port curl).

Probe Cost Class

One of: cheap-local | needs-container | needs-live-provider | needs-browser | needs-cf. State whether the safety gate was met.

Probe Method

The exact command(s) or steps run to test the hypothesis.

Evidence Captured

The raw output from the probe (trimmed to relevant lines). For an INCONCLUSIVE gate-not-met verdict, state explicitly that the probe was not run and why.

Verdict

One of: VIABLE | NOT-VIABLE | INCONCLUSIVE

Resulting Design Constraint

The "action consequence" of the probe, split into three explicit parts:

• What this licenses: what the approach is now allowed to depend on.
• What this forbids: what the approach must NOT depend on.
• What remains uncertain (known-gap): what the probe did not settle and must be treated as an open risk (for INCONCLUSIVE, this is the main content).

Completion Signal

After writing the VERDICT artifact, emit:

VC-FEASIBILITY-VERDICT-READY: [verdict keyword] — [full path to VERDICT file]

Example:

VC-FEASIBILITY-VERDICT-READY: NOT-VIABLE — process/features/model-selector/active/model-selector_10-06-26/model-selector_FEASIBILITY_10-06-26.md

Re-spawn Handoff

The orchestrator reads the VERDICT artifact and extracts a Prior Feasibility: summary. Format passed to the re-spawned agent:

Prior Feasibility: [hypothesis] — verdict: [VIABLE|NOT-VIABLE|INCONCLUSIVE] — licenses: [one line] — forbids: [one line] — uncertain: [one line]

Example:

Prior Feasibility: Does the gateway forward params.provider.sort? — verdict: NOT-VIABLE — licenses: nothing new — forbids: any approach depending on params.provider.sort being forwarded (the layer strips it) — uncertain: whether a different forwarding field survives

The re-spawned SPEC, INNOVATE, or VALIDATE agent reads this block and uses the verdict to lock or reject the approach. When originating-phase: pvl, the re-spawned vc-validate-agent resumes from V1 and records resolved probes in a ## Feasibility Probes Resolved subsection of the validate-contract (omitted when no probe ran).

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.

IMPORTANT: MUST follow Design Thinking, Frontend Aesthetics Guidelines, Asset & Analysis References, and Anti-Patterns (AI Slop) sections below. DO NOT skip these rules.

Workflow Selection

Choose workflow based on input type:

All workflows: Invoke the ui-ux-designer subagent FIRST for design intelligence.

Precedence: When anti-slop rules (below) conflict with ui-ux-designer recommendations (e.g., Inter font, AI Purple palette, Lucide-only icons), substitute with alternatives from ./references/anti-slop-rules.md unless the user explicitly requested the conflicting choice.

Screenshot/Video Replication (Quick Reference)

1. Analyze with Claude's built-in multimodal vision - extract colors, fonts, spacing, effects
2. Plan with ui-ux-designer subagent - create phased implementation
3. Implement - match source precisely
4. Verify - compare to original
5. Document - read process/context/all-context.md, then update process/context/all-context.md, the project's UI/UX context doc (if present), or the relevant grouped context file if approved

See specific workflow files for detailed steps.

Design Dials

Three configurable parameters that drive design decisions. Set defaults at session start or let user override via chat:

Usage: These values drive specific rules. At DESIGN_VARIANCE > 4, centered heroes are overused — force split-screen or left-aligned layouts. At MOTION_INTENSITY > 5, embed perpetual micro-animations. At VISUAL_DENSITY > 7, remove generic cards and use spacing/dividers.

See ./references/bento-motion-engine.md for dial-driven SaaS dashboard implementation.

Design Thinking

Before coding, commit to a BOLD aesthetic direction:

• Purpose: What problem does this interface solve? Who uses it?
• Tone: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
• Constraints: Technical requirements (framework, performance, accessibility).
• Differentiation: What makes this UNFORGETTABLE? What's the one thing someone will remember?

CRITICAL: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.

Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:

• Production-grade and functional
• Visually striking and memorable
• Cohesive with a clear aesthetic point-of-view
• Meticulously refined in every detail

Frontend Aesthetics Guidelines

Focus on:

• Typography: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
• Color & Theme: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
• Motion: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
• Spatial Composition: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
• Backgrounds & Visual Details: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.

NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.

Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.

IMPORTANT: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.

Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.

Assets: Generate images with Claude's built-in multimodal vision, process with imagemagick CLI or browser Canvas API

Asset & Analysis References

Quick start: ./references/ai-multimodal-overview.md

Anti-Patterns (AI Slop)

Strongly prefer alternatives to these LLM defaults. Full rules: ./references/anti-slop-rules.md

Typography — Avoid Inter/Roboto/Arial. Prefer: Trending Google Fonts that supports Vietnamese characters, Geist, Outfit, Cabinet Grotesk, Satoshi (search for best matches)

Font size — ALWAYS use font size larger than 16px for input fields to avoid zoom on mobile devices.

Color — Avoid AI purple/blue gradient aesthetic, pure #000000, oversaturated accents. Use neutral bases with a single considered accent.

Layout — Avoid 3-column equal card feature rows, centered heroes at high variance, h-screen. Use asymmetric grids, split-screen, min-h-[100dvh]. Mobile-first approach is a must.

Content — Avoid "John Doe", "Acme Corp", round numbers, AI copy clichés ("Elevate", "Seamless", "Unleash"). Use realistic names, organic data, plain specific language.

Effects — Avoid neon/outer glows, custom cursors, gradient text on headers (unless you're asked to do so). Use tinted inner shadows, spring physics.

Components — Avoid default unstyled shadcn, Lucide-only icons, generic card-border-shadow pattern at high density. Always customize, try Phosphor/Heroicons, use spacing over cards.

Quick check: See the "AI Tells" checklist in ./references/anti-slop-rules.md before delivering any design.

Performance: Animation and blur rules in ./references/performance-guardrails.md

Remember: Claude is capable of extraordinary creative work. Commit fully to distinctive visions.

vc-generate-closeout

Output style: closeout packet leads with the verdict/recommendation, tables for drift/readiness, one-line TL;DR — process/development-protocols/communication-standards.md.

Generate the post-EXECUTE closeout packet for a completed plan or phase. Produces a structured summary with archive-readiness classification, drift signal scoring, commit checkpoint recommendation, and the single best next valid state.

When To Invoke

Invoke this skill at the end of:

• Any non-trivial EXECUTE completion (the execute-agent's own closeout block)
• ENTER UPDATE PROCESS MODE flows before archiving a plan
• fast-mode-agent session end, after implementation and verification are complete
• Phase program closeout between phases (after validate + regression checkpoint, before inter-phase UPDATE PROCESS)

Do not invoke for trivial single-file fixes where the plan file is not involved.

Mode Selection

Choose one mode before generating the closeout packet.

Simple Mode (default)

Use when:

• The execute session just ended and all context is fresh in the conversation.
• The plan was a single-phase, straightforward implementation.
• No context compaction occurred during the session.

Behavior: write the 8-item closeout packet directly from the plan file and conversation context. No additional git or file scanning is required.

Deep Mode

Trigger conditions — use Deep Mode if any one of the following applies:

• The session was resumed after a context compaction (conversation context may be incomplete).
• The execute session was long — many sub-steps, multiple checklist sections, or multiple commits.
• The caller explicitly requests deep mode.
• The phase is part of a multi-phase program and accurate phase-completion status is required for the umbrella plan.

Behavior: gather evidence before writing the closeout packet. Run these steps in order:

1. git diff HEAD~1 --name-only — confirm which files were actually changed. Cross-reference against the plan's blast radius.
2. git log --oneline -5 — confirm commit messages match what was planned. Flag any commits that touch files outside the plan's scope.
3. Read the phase report if one was already written — confirm its claims match actual execution output.
4. Read the validate-contract test gates — confirm each gate's final status: green, known-gap, or skipped. Do not rely on memory for gate outcomes.
5. Read the plan Implementation Checklist — for every checked item, confirm a matching file appears in the git diff. Flag any checked item with no corresponding change.

After gathering evidence, write the closeout packet with explicit source citations for every material claim.

Quality difference between modes:

• Simple: "Section 2 completed — billing router updated" (from memory)
• Deep: "Section 2 completed — git diff HEAD~1 confirms packages/api/src/router/billing.ts modified (+47/-12 lines); test gate pnpm test:billing confirmed green in execute log"

When in doubt, prefer Deep Mode. A false-confident Simple closeout is worse than a slightly slower Deep one.

Closeout Packet Schema

Every closeout packet must include these 9 items. Present them in order.

1. Selected plan path

   • The exact file path of the plan being closed out (e.g. process/features/foo/active/foo-phase-01_PLAN_03-06-26.md). Never leave this implicit.

2. Closeout classification (one of three states — see §Closeout Classification States)

3. What was finished

   • A concrete list of what was actually implemented or changed. Not a restatement of the plan checklist — what was done in practice.

4. What was verified vs still unverified

   • What tests or evidence exist that confirm the work.
   • What still requires manual verification, user confirmation, or future test coverage.

4b. Validate-contract compliance

• Was VALIDATE run for this plan?
• Is a ## Validate Contract section present in the plan file?
• If VALIDATE was skipped, state the documented skip reason.
• A plan cannot be classified Ready for UPDATE PROCESS archival without a present validate-contract or a documented skip reason.

5. Cleanup done vs still needed

   • What context docs, reports, or process artifacts were already updated.
   • What remains: open TODOs, uncommitted changes, missing reports, stale references, or plan debt.

6. Single best next valid state (one of the allowed states from §Move-On Semantics)

   • Name the exact next action or plan path. Never end with a generic "move to next task."

7. Commit-checkpoint recommendation (see §Commit Checkpoint Classification)

   • Whether to invoke vc-git-manager before UPDATE PROCESS, or whether the remaining changes are process-only and the commit belongs after UPDATE PROCESS.

8. Regression status (phase programs only)

   • Which previously verified surfaces were checked for regression against this phase's blast radius.
   • Whether all passed, or whether fixes were applied before re-verification.
   • If regression checking was skipped (e.g., first phase with no prior verified surfaces), state why explicitly.

9. SPEC achievement

   • For each acceptance criterion in the locked *_SPEC_*.md, score met or unmet.
   • Each unmet criterion → a backlog NOTE (the SPEC is frozen; gaps go to backlog only).
   • If there is no SPEC for this plan (e.g. trivial or phase-program inner loop governed by the umbrella SPEC), state that explicitly.

Closeout Classification States

Exactly three states are allowed. Choose one and state it verbatim.

• Ready for UPDATE PROCESS archival

  • The selected plan path still matches the implemented work.
  • Required verification evidence exists.
  • No material deviations remain unresolved.
  • The user has confirmed or approved cleanup.
  • validate-contract is present in the plan file, or VALIDATE was explicitly skipped with a documented reason.

• Keep in active/testing

  • Implementation is substantially complete.
  • But testing, manual verification, or explicit user confirmation is still pending.
  • Do not archive until those are resolved.

• Needs PLAN/UPDATE PROCESS reconciliation

  • Material deviations from the selected plan were required during execution.
  • Context or process updates are needed before the plan can be archived.
  • The work should route through UPDATE PROCESS or back to PLAN first.

Drift Signal Scoring

After building the closeout packet, score the UPDATE PROCESS urgency by counting signals.

Signal sources (5 sources, max score 6):

• (a) Files touched during the EXECUTE phase: +1 if ≥1 file, +1 more if ≥10 files (max 2 from this source)
• (b1) Any .claude/, .codex/, or agent harness file (agent .md/.toml, SKILL.md, settings, hooks) changed: +1
• (b2) Any README.md, AGENTS.md, CLAUDE.md, or process/development-protocols/ file changed: +1
• (c) Session involved 3 or more memory-worthy observations (new patterns discovered, deviations documented, architectural decisions made): +1
• (d) Feature-folder structural change (new {slug}_{date}/ task folder created, backlog NOTE written, or task folder archived/moved): +1
• (e) Validate-contract deviation (execution diverged from the validate-contract or the plan's declared blast radius): +1

Thresholds and required wording:

The exact phrase for each band must appear word-for-word in the closeout output (do not rephrase — these are machine-matched strings):

• LOW (0–1 signals): (few files changed, nothing critical) include "UPDATE PROCESS available if you want."
• MEDIUM (2–3 signals): (notable scope — worth capturing learnings) include "Recommend UPDATE PROCESS -- significant changes detected."
• HIGH (4+ signals): (harness, agents, or protocol docs were edited — durable capture is urgent) include "Strongly recommend UPDATE PROCESS -- harness/protocol files touched."

Always include the exact threshold phrase verbatim in the closeout output. Do not summarize or rephrase the wording.

Move-On Semantics

"Move on" does not include an automatic transition into UPDATE PROCESS. It still must not silently archive work or widen scope.

The orchestrator should:

1. Finish the closeout packet.
2. Recommend the next valid state explicitly.
3. Name the exact next plan or phase when one clear successor exists.
4. Avoid reopening broad research when the next step is already known from the current program structure.

Allowed next-state examples (use these exact forms when applicable):

• If the selected plan is verified and the next phase is explicit: ENTER UPDATE PROCESS MODE, then continue with process/features/.../next-phase_PLAN_...md
• If the selected plan is verified and implementation changes are still uncommitted: Invoke vc-git-manager for a logical execution commit, then ENTER UPDATE PROCESS MODE for plan/context reconciliation
• If the selected plan is code-complete but still testing: Keep the plan active and continue validation on the same selected plan
• If the selected plan exposed follow-up work outside its boundary: ENTER UPDATE PROCESS MODE to capture the split and route the follow-up into its own plan

Archive-Readiness Semantics

Do not treat every successful code change as immediately archive-ready.

Use these three states (see also §Closeout Classification States for the exact criteria):

• Ready to archive

  • The selected plan path still matches the implemented work.
  • Required verification evidence exists.
  • No material deviations remain unresolved.
  • The user has confirmed or approved cleanup.
  • validate-contract is present in the plan file, or VALIDATE was explicitly skipped with a documented reason.

• Keep in active / testing

  • Implementation is substantially complete but testing, manual verification, or explicit user confirmation is still pending.

• Needs reconciliation before archival

  • Material deviations from the selected plan were required.
  • Context/process updates are needed before the plan can be archived.
  • The work should route through UPDATE PROCESS or back to PLAN first.

For non-trivial work, prefer routing archive decisions through UPDATE PROCESS so context updates, lessons learned, and selected-plan archival happen together.

Phase Program Closeout Shape

After each executed phase in a phase program, produce a short closeout packet with these 7 items:

1. Selected phase plan path — the exact file path of the completed phase plan.
2. Phase status — one of:
   • ✅ VERIFIED
   • Keep in active/testing
   • 🚧 BLOCKED
   • Needs reconciliation
3. What green actually proves — a precise statement of what the passing gates confirm, and what they do not cover.
4. Regression status — surfaces checked, results, any fixes applied. Format each entry as:

   Regression: [surface] — [PASS | FIXED | BLOCKED]
   Command: [exact command or manual step]
   Result: [1-line outcome]
   

5. What remains outside this phase — scope explicitly deferred, planned follow-up work, or items that would require a new phase or feature folder.
6. Whether UPDATE PROCESS is the next required step — inter-phase UPDATE PROCESS is mandatory between phases, not optional. Phase outputs must survive compaction.
7. The exact next phase or follow-up plan if known — name the path explicitly. If the next phase is already in the umbrella plan, name it. Do not make the user infer it from folder state.

This is how a phase program moves on without losing durable state or requiring the user to reconstruct context from a long transcript.

Commit Checkpoint Classification

For validated phase work, classify the commit checkpoint explicitly using one of two forms:

• Execution commit recommended before UPDATE PROCESS

  • Implementation or test changes from the selected phase are well-tested and ready for a logical code/test commit.
  • Later UPDATE PROCESS edits are expected to touch process/, .claude/, .codex/, or AGENTS.md separately.
  • Recommend invoking vc-git-manager before routing to UPDATE PROCESS.

• Process commit belongs after UPDATE PROCESS

  • The remaining changes are primarily plan, report, context, or harness-governance artifacts.
  • Splitting execution and process commits will keep the history easier to review and resume.
  • Do not invoke vc-git-manager before UPDATE PROCESS; route to UPDATE PROCESS first, then commit.

When both execution and process changes are present, always recommend the execution commit first, then UPDATE PROCESS, then the process commit.

Output Format

Present the closeout packet as a structured Markdown block with each numbered item as a heading or bold label. End with the drift signal score and required threshold phrase, and the single best next valid state as a clear final recommendation.

Per task-folder artefact colocation, when the closeout packet is persisted as a file, write it INTO the plan's own task folder (process/features/{feature}/active/{slug}_{date}/ or process/general-plans/active/{slug}_{date}/) as {slug}_REPORT_{date}.md — never into a sibling reports/ dir or any ad-hoc location. On completion the whole folder moves as a unit.

Example shape:

**Closeout Packet**

1. Selected plan path: `process/features/foo/active/foo_03-06-26/foo_PLAN_03-06-26.md`
2. Closeout classification: Ready for UPDATE PROCESS archival
3. What was finished: [...]
4. Verified: [...] | Unverified: [...]
4b. Validate-contract: present (inline in plan, PASS)
5. Cleanup done: [...] | Still needed: [...]
6. Next valid state: ENTER UPDATE PROCESS MODE
7. Commit checkpoint: Execution commit recommended before UPDATE PROCESS — invoke vc-git-manager first
8. Regression status: (phase programs only) [...]

Drift score: HIGH (3 signals: 12 files touched, .claude/ skill added, 3 memory-worthy observations)
Strongly recommend UPDATE PROCESS -- harness/protocol files touched.

Generate Context

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Use this skill to maintain process/context/all-context.md, the broad portable project knowledge layer shared by Codex and Claude. Use process/context/all-context.md as the context router before reading grouped docs.

Optional input: a package, app, feature, context group, or architectural area to refresh first.

Workflow

1. Read references/generate-context.md for the full context contract.
2. Determine mode:
   • Full scan when process/context/all-context.md is missing.
   • Delta update when it exists.
3. Read process/context/all-context.md when present to identify relevant grouped context files.
4. Inspect current repo state, active plans, feature folders, package scripts, tooling, important architecture files, and relevant process/context/**/*.md docs.
5. Produce process/context/all-context.md PLUS process/context/{group}/all-{group}.md for each detected or approved group (see Invocation Modes below).
6. Include scan timestamp, repo HEAD if available, changes since last update, open questions, and source references.
7. Validate the generated context:

   node .claude/skills/vc-generate-context/scripts/validate-all-context.mjs
   

8. If routing or grouped context changed, also run:

   node .claude/skills/vc-audit-context/scripts/validate-context-discovery.mjs
   

Rules

• Treat process/context/ as durable cross-agent knowledge.
• Treat process/context/all-context.md as the durable routing protocol; do not replace it with generated prose.
• Do not store agent-specific mechanics here unless they affect project workflow.
• Do not rewrite grouped context docs; if they are stale or mis-grouped, flag audit-context.
• Prefer concise, factual, path-specific documentation.
• Use pnpm terminology for package management.
• Treat validation failures as blockers before presenting context as refreshed.

Invocation Modes

See references/generate-context.md for per-mode instructions, the Context Group Detection Table, and delta-mode group-creation rules.

vc-generate-phase-program

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Generate kickoff artifacts for a multi-phase RIPER-5 program: umbrella plan, Program Goal Charter, session-goal block, per-phase plan stubs, and the 7-step per-phase inner loop reference (R → I → P → PVL → E → EVL → UP, which SKIPS SPEC).

The 7 steps are: Research → Innovate → Plan-Supplement → PVL (plan-validate loop — the gate that confirms the plan is ready before EXECUTE runs) → Execute → EVL (execute-validate loop — the confirmation run after EXECUTE, re-running gate tests independently) → Update-Process.

Source of truth: process/development-protocols/phase-programs.md

When To Invoke

Invoke this skill at PLAN phase when phase-program initiation is detected (3 or more dependent phases), or at ORCHESTRATOR when the incoming request involves 3 or more dependent phases.

Signal patterns that trigger this skill:

• the work naturally breaks into 3 or more dependent phases
• each phase needs its own validation gate before the next phase starts
• the work spans multiple packages, services, or runtime surfaces
• the user wants high-confidence progress with durable checkpoints
• repeated research is needed because new facts will emerge during execution

Do not invoke for a simple one-session feature or a small bug fix. Use the normal RIPER flow instead.

Kickoff Procedure

Before creating any plan files, follow these steps in order:

Step 1 — invoke vc-agent-strategy-compare. For programs with 3 or more phases, output will always recommend parallel-subagents (one per phase plan) or dynamic workflow. Plans are created in the recommended parallel mode, not sequentially.

Per-phase strategy invocation (mandatory): For each individual phase during scaffold, invoke vc-agent-strategy-compare with that phase's scope before writing that phase's plan stub — not once at the program level. Each phase may have a different recommended execution strategy.

Step 1a — Read template files. Before creating any plan artifacts, execute Read on both template files:

• .claude/skills/vc-generate-phase-program/templates/umbrella-plan-template.md
• .claude/skills/vc-generate-phase-program/templates/phase-stub-template.md

Use the template structure as the basis for all generated artifacts. Substitute {placeholder} values with program-specific content. Do not reconstruct structure from memory.

Step 2 — research the full problem space. Read process/context/all-context.md. Run find process/context/ -type f and find process/development-protocols/ -type f. Load domain-specific context files relevant to the program. Understand the full problem space before proposing any structure.

Step 3 — emit a kickoff recommendation (stop for approval before creating files). Present the recommendation using the format in "Kickoff Recommendation Format" below. Do not create plan artifacts yet. Stop and wait for user approval.

Step 4 — after approval, create the required artifacts:

• feature folder under process/features/{feature}/ with subdirs active/, completed/, backlog/ (no reports/ or references/ — new repos omit these deprecated sibling dirs)
• ONE program task folder in active/: active/{program-slug}_{date}/ holding the umbrella _PLAN_, every phase _PLAN_, every phase _REPORT_, the phase registry, and _REF_ files — all FLAT (no per-phase subfolders)
• the umbrella/orchestration plan: active/{program-slug}_{date}/{program-slug}-umbrella_PLAN_{date}.md — the filename MUST carry the literal umbrella token (enforced by validate-plan-artifact.mjs and validate-umbrella-artifact.mjs for any plan whose frontmatter declares phase: umbrella)
• one direct phase plan per phase, FLAT in the same program folder: active/{program-slug}_{date}/phase-NN-{slug}_PLAN_{date}.md

Per task-folder artefact colocation, the umbrella plan, every phase plan, the phase registry, and all reports/references each live FLAT INSIDE the ONE program task folder; never write program artefacts to the deprecated sibling reports/ or references/ dirs, and never create per-phase subfolders. The whole program folder moves as a unit on completion.

Step 5 — emit the compressed session-goal block in chat. Once the umbrella plan and its Program Goal Charter exist, emit the session-goal block directly in chat (not to a file). See "Kickoff Recommendation Format" step 5 for the exact shape and the 4000- character limit rule.

Goal Block Requirements

Every phase program umbrella plan must include a ## Stable Program Goal section containing a copy-pasteable /goal block. Requirements:

• Hard limit: ≤ 4000 characters (the /goal command rejects longer blocks). Verify char count before writing.
• Required sections (in order): TARGET / PER-PHASE LOOP / HARD STOPS / SAFETY / TEST GATES / VALIDATE CONTRACT / START
• PER-PHASE LOOP must state:
  • Loop steps (7-step inner loop R → I → P → PVL → E → EVL → UP, SKIPS SPEC): 1 RESEARCH → 2 INNOVATE → 3 PLAN-SUPPLEMENT → 4 PVL → 5 EXECUTE → 6 EVL → 7 UPDATE-PROCESS
  • PVL never skipped rule
  • Placeholder contract = blocked rule
  • Every subagent first action: vc-context-discovery + vc-plan-discovery (once available)
  • Every phase-END: invoke vc-agent-strategy-compare
  • Correct test tier names: automated / hybrid / agent-probe
• TEST GATES must list all 5 validator commands with full paths
• START must name the current phase and loop step explicitly
• When updating the goal block after phases complete, re-verify char count before writing — compress if needed, never truncate required sections

Kickoff Template

Use this template as the starting prompt when handing off to a program-capable agent or when opening a new long-running session. Replace all placeholders with real program content.

Build [PROJECT OR PROGRAM NAME] end-to-end using the repo's phase-program workflow.

Goal:
- [state the real end goal in one or two sentences]

Scope:
- Start by reading `process/context/all-context.md`
- Use `process/development-protocols/phase-programs.md`
- Treat this as a large multi-phase program, not a normal single-plan task
- First do the necessary research to understand the whole problem space
- First recommend:
  - whether this should be a standard complex plan or a phase program
  - the proposed feature folder
  - the umbrella/orchestration plan shape
  - the proposed phase sequence
  - the recommended immediate next action
- Present that recommendation clearly and stop for approval
- Only after approval, create or confirm:
  - one feature folder
  - one umbrella/orchestration plan
  - one direct phase plan per phase
- Make the phase boundaries explicit
- Define what each phase green check proves
- Separate foundation proof from later expansion if they are different scopes

Execution rule:
- Do not execute the whole program at once
- For each phase, follow the required 7-step inner loop `R → I → P → PVL → E → EVL → UP` (SKIPS SPEC):
  research -> innovate -> plan-supplement -> PVL (validate-contract) -> execute -> EVL (validate + regression) -> update-process (capture + commit + move-on)
- Re-research at the start of every phase before implementation
- After validation, run regression checks against previously verified surfaces that overlap with this phase's blast radius
- Commit execution changes via vc-git-manager before moving to the next phase
- Run inter-phase UPDATE PROCESS to archive the completed phase and capture learnings
- Do not mark a phase `✅ VERIFIED` without both phase evidence and regression evidence
- If blocked, document the blocker, safest next action, and update later phase plans/reports so the work survives compaction

Deliverables:
- initial recommendation on plan shape, sequencing, and next actions
- feature folder under `process/features/{feature}/`
- umbrella/orchestration plan
- phase plans
- durable reports and references as phases execute
- context updates when durable operational knowledge changes

Working instruction:
- Proceed phase by phase
- Do not stop at analysis if the selected phase is approved and unblocked
- Do not silently widen scope across phases
- Keep status honest and keep future work split cleanly

Practical Operator Kickoff

Shorter version for day-to-day reuse when the full template is overkill:

Build [NAME] as a phase program per process/development-protocols/phase-programs.md.

Goal: [1-2 sentences]

First: recommend structure (feature folder, phases, immediate next action). Stop for approval.
Then: advance one phase at a time using the 7-step inner loop `R → I → P → PVL → E → EVL → UP` (SKIPS SPEC): research -> innovate -> plan-supplement -> PVL -> execute -> EVL (validate + regression) -> update-process (capture + commit + move-on).

Template Files

Two copy-pasteable template files exist for generating structurally correct artifacts:

Mandatory Read steps: Before writing any umbrella plan or phase stub, execute:

1. Read(".claude/skills/vc-generate-phase-program/templates/umbrella-plan-template.md")
2. Read(".claude/skills/vc-generate-phase-program/templates/phase-stub-template.md")

The template files are the source of truth for required sections and placeholder wording. Do not reconstruct structure from memory.

Kickoff Recommendation Format

Before creating any plan files for a new large program, present a short recommendation with these five items:

1. Program fit

• should this be standard complex or a phase program
• why

2. Recommended structure

• feature folder name
• umbrella plan name
• proposed phase list in order

3. Recommended immediate next action

• what should happen now
• what should wait until later

4. Approval checkpoint

• ask whether to proceed with creating the plan artifacts

5. Compressed session-goal block (printed in chat) Once the umbrella plan and its Program Goal Charter exist, emit a compressed, copy-pasteable "session goal" block directly in chat (do NOT write it to a file). This is the launch packet a user pastes to start an unattended, long-running session. Keep it to roughly 8-12 lines with this shape:

SESSION GOAL: [PROGRAM NAME]
Charter + umbrella plan: process/features/{feature}/active/{program-slug}-umbrella_{date}/{program-slug}-umbrella_PLAN_{date}.md
Autonomy: Run autonomously under this persistent goal. Execute phases on your own
recommendation via the 7-step inner loop `R → I → P → PVL → E → EVL → UP` in phase-programs.md
(the inner loop SKIPS SPEC); report conflicts, errors, and learnings in the phase report (the
report is the communication channel, not a question). Only pause for outward-facing /
irreversible / costful / destructive actions (see feedback_autonomous_phase_execution.md).
Hard stop conditions / safety constraints:
- [hard safety constraint 1 from the charter]
- [hard safety constraint 2 from the charter]
Next phase: process/features/{feature}/active/{program-slug}_{date}/phase-NN-{slug}_PLAN_{date}.md
Validate contract: [path to validate-contract or "inline in plan"]
Execute start: [fully-auto commands] | [e2e spec] | [probe scenario] | high-risk pack: [yes/no]

The block must name the charter/umbrella plan path, state the autonomy rule (citing feedback_autonomous_phase_execution.md: execute phases on own recommendation under a persistent goal; only pause for outward-facing/irreversible/costful actions), and list the charter's hard stop-conditions/safety constraints verbatim.

Hard rule: the session-goal block MUST be under 4000 characters total — it is pasted into a persistent /goal whose ceiling is ~4000 chars. If the program's safety constraints and definition-of-done won't compress under 4000 chars, summarize and reference the charter's plan path for the full detail rather than inlining everything.

Autonomous Session-Goal Variant

This is an explicit opt-in variant. It does NOT weaken the default supervised loop; it only applies when the user sets a persistent autonomous session-goal (e.g. a standing /goal).

When the user sets a persistent autonomous session-goal:

• the per-phase Execution Approval Checkpoint (the PVL step — step 4 of the 7-step inner loop) is treated as STANDING-GRANTED. The agent does not pause for approval between phases.
• the agent self-decides, executes, and reports learnings after each phase. On failure it diagnoses, writes a new plan/fix, and continues.
• the safety boundary REPLACES the approval gate: never take irreversible or costful actions (deploys, live/costful provider gates, billing, destructive schema/data ops). These are DEFERRED AND REPORTED — never executed and never paused-on.
• every step must stay rollback-able: commit each phase before the next, keep process/plan commits separate from execution commits, and prefer disposable targets.
• all other loop steps still apply unchanged: re-research at phase entry, validate, regression check, durable capture, commit, inter-phase UPDATE PROCESS, and honest phase status.

Shared-runtime 2-tier policy: direct interaction with the shared E2E container — including rebuilding the image and recreating/restarting it via the project's dedicated managed script — is normal, autonomous test work. It is NOT forbidden. Only irrecoverable persistent-state loss, prod-state mutation, production image push/deploy, and live/costful gates are deferred-and-reported. See your project's container/test context docs for the exact sanctioned commands. Do not re-list those commands here.

The Required Per-Phase Loop

The canonical per-phase loop is the 7-step inner loop R → I → P → PVL → E → EVL → UP (it SKIPS SPEC — SPEC runs once in the outer program loop). The detailed orchestration steps below are the prose EXPANSION of those 7 steps: RESEARCH (1) → INNOVATE (decide approach) → PLAN-SUPPLEMENT → PVL = the execution approval checkpoint / validate-contract (2) → EXECUTE (3) → EVL = validate + regression + regression-found workflow (4–6) → UPDATE-PROCESS = durable capture + commit + inter-phase UPDATE PROCESS + move-on (7–10). The numbering below is orchestration detail, not a separate loop.

For every phase, run this loop:

1. Research subagent

   • reread the selected phase plan
   • reread the latest relevant reports, references, and context docs
   • inspect codebase drift since the plan was written
   • supplement the phase plan or create a research report if new facts matter
   • Also always read process/context/all-context.md and run find process/context/ -type f to see all available context files. Note: protocol files needed for this phase (orchestration.md, plan-lifecycle.md, phase-programs.md) live in process/development-protocols/ and must be explicitly read — they are not discoverable via the context router.

2. Execution approval checkpoint

   • summarize what changed since planning
   • identify risks, scope adjustments, and exact gates
   • get user approval before substantial implementation
   • For phase programs with a standing /goal, VALIDATE runs here and is treated as STANDING-APPROVED. The orchestrator does not pause for validate approval between phases; the validate-contract is written and execution proceeds. STANDING-APPROVED means the approval pause is skipped — not the VALIDATE run itself. The validate-contract must still be written for each phase; a phase cannot reach VERIFIED without it.

3. Execute subagent

   • implement only the selected phase scope
   • stop if the work no longer matches the approved plan
   • Per-section test-gate loop: After completing each checklist section, immediately run the validate-contract test gates for that section — do not batch all test gates to the end. Fix failures inline before moving to the next section.
   • Test-failure escalation ladder:
     1. If the failing test is in this phase's blast radius → fix inline, re-run until green, then continue.
     2. If the fix is out of scope (would change a different module) → create a follow-up phase plan inside a new task folder under process/features/{feature}/active/{new-slug}_{date}/, document the gap, and continue.
     3. If there is no fix path → classify as backlog artifact, add to known-gaps in the phase report, and continue without blocking.

4. Validate subagent

   • run the exact phase gates
   • inspect artifacts, logs, DB state, screenshots, traces, or runtime evidence as required
   • decide whether the phase is genuinely green, blocked, or only partially proven
   • run all applicable test tiers per the validate-contract: fully automated (fix failures and re-run until green), hybrid (record outcome, fix if in blast radius), agent probe (record judgment). Phase cannot advance to VERIFIED until all in-blast-radius tiers are green.

5. Regression checkpoint

   • run the narrowest representative check against previously verified surfaces that overlap with this phase's blast radius
   • see "Regression Checkpoint Standard" below for scope selection and evidence format
   • if all regression checks pass, proceed to durable capture
   • if any regression is found, follow "Regression-Found Workflow" before advancing

6. Regression-found workflow (conditional)

   • only enters this step when step 5 finds a regression
   • classify, fix or route, revalidate, then return to step 5
   • see "Regression-Found Workflow" below for the full decision tree

7. Durable capture

   • update the phase report with commands, outcomes, deviations, and blockers
   • include regression check results (pass or fix-and-revalidate) in the report
   • update context docs if durable operational knowledge changed
   • update later phase plans if the new learning changes future work
   • if execution reveals a concrete missing downstream lane, create the new follow-up phase plan or backlog artifact instead of leaving the follow-up only in chat
   • keep the parent or umbrella plan in sync when follow-up routing or phase sequencing changes

8. Commit checkpoint

   • if the phase produced implementation changes, recommend vc-git-manager for a logical execution commit before continuing
   • keep process/plan/context artifact commits separate from execution commits
   • do not defer the commit to a later phase — stale worktrees make regression checking unreliable

9. Inter-phase UPDATE PROCESS

   • route through UPDATE PROCESS to archive the completed phase plan and capture learnings
   • update context docs, reports, and downstream phase plans as needed
   • this step is mandatory between phases, not optional — phase outputs must survive compaction

10. Move-on recommendation

    • name the exact next valid state after the phase closeout
    • if the next phase is already known, name the exact next phase plan path
    • if the current phase is not really green, keep the work on the same phase instead of pretending to advance

This loop is mandatory. Do not jump straight from phase plan to implementation without a fresh research pass on large programs.

Regression Checkpoint Standard

After validating the current phase's own gates (step 4), check that previously verified work still holds.

Scope selection:

• identify previously verified surfaces that overlap with this phase's blast radius
• run the narrowest representative check for each overlapping surface
• if the phase touches shared infrastructure (DB, container, proxy, auth), include at least one check from each earlier phase that depends on that infrastructure
• if no earlier phases are verified yet, skip this step

Evidence format:

Record regression results in the phase report as:

Regression: [surface] — [PASS | FIXED | BLOCKED]
Command: [exact command or manual step]
Result: [1-line outcome]

What counts as a representative check:

• a single test command that exercises the core path of the earlier phase
• a manual verification step that confirms the earlier phase's key artifact still works
• do not re-run the full validation suite of every earlier phase — pick the narrowest check that would catch breakage

Regression-Found Workflow

When a regression is detected in step 5:

Classify the regression:

Decision tree:

1. Fix in place when the regression is small, the fix is obvious, and it does not widen the current phase scope. Fix, revalidate both the regression surface and the current phase gates, then continue.
2. Revalidate only when the regression is a false alarm (e.g., flaky test, transient infra). Record the finding and move on.
3. Route as BLOCKED when the regression is real but fixing it would materially widen scope. Create a follow-up artifact (backlog plan or blocker note in the phase report), mark the current phase BLOCKED, and stop.

Never paper over a regression. Always classify it and record it in the phase report, even if the fix is trivial.

Program Goal Charter

Every phase program must carry a Program Goal Charter as part of its umbrella orchestration plan. Generate it automatically when building the umbrella plan, fill in only program-specific content, and keep it tight.

Required charter structure (placeholders are program-specific only):

# [PROGRAM NAME] — Program Goal Charter

North star:
- [one sentence stating the real end goal]

Definition of done:
- [the concrete capabilities an unattended agent must be able to perform when the program is complete]

What "verified" means (program level):
- [the exact bar for promoting work to VERIFIED for this program — gate surface, evidence, coverage]
- validate-contract gates must be recorded alongside phase gates and regression evidence for a phase to reach VERIFIED. A phase without a validate-contract (or documented skip reason) cannot be marked VERIFIED.

Scope tiers → phase mapping:
- Tier 1 [name] → Phases [n, n, ...]
- Tier 2 [name] → Phases [n, n, ...]
- Tier 3 [name] → Phases [n, n, ...]
- This program retires Tiers [1-N].

Explicitly out of scope (deferred tier):
- [the tier and items intentionally not addressed by this program]

Hard safety constraints (non-negotiable, per phase):
- [program-specific irreversible/destructive boundaries, e.g. "never mutate prod X"]

Important: execution discipline (the required 7-step inner loop R → I → P → PVL → E → EVL → UP, re-research at phase entry, and honest phase status) is already governed by process/development-protocols/phase-programs.md. Do NOT re-paste that prose into the charter — the charter is program-specific intent and safety only, not workflow rules.

A blank template plus a filled-in reference example live at .claude/skills/vc-generate-phase-program/references/program-goal-charter-template.md.

Generate Plan

Output style: write the plan answer-first with tables/bullets and a one-line TL;DR per the canonical rule — process/development-protocols/communication-standards.md.

Use this skill to produce the authoritative implementation plan artifact set for the project's work.

This skill is the canonical planning contract for the repo. Planning discipline previously spread across vc-plan now belongs here plus the plan-agent prompt.

Normal output is one plan file.

For large multi-phase programs, this skill instead defines how to create an umbrella plan plus phase-plan set under one feature folder. See process/development-protocols/phase-programs.md.

Optional input: a feature idea plus simple or complex when the user already knows the intended depth.

Workflow

1. Read references/generate-plan.md for the full plan contract.
2. Run date +%d-%m-%y before choosing the filename.
3. If complexity is not obvious, ask whether the plan is SIMPLE or COMPLEX.
4. Save the plan inside a task folder: process/general-plans/active/{slug}_{date}/{slug}_PLAN_{date}.md (or process/features/{feature}/active/{slug}_{date}/{slug}_PLAN_{date}.md). Create the {slug}_{date}/ subfolder first. Per task-folder artefact colocation, every artefact this plan produces — the plan, any {slug}_SPEC_{date}.md, reports, and references — lives INSIDE this same task folder; never write to the deprecated sibling reports/ or references/ dirs.
5. Read process/context/all-context.md when present to choose relevant context docs.
6. For complex plans, read .claude/skills/vc-generate-plan/references/example-complex-prd.md before writing.
7. Include automated and manual verification gates from process/context/tests/all-tests.md.
8. For new or newly touched direct *_PLAN_*.md plans, include explicit sections for Touchpoints, Public Contracts, Blast Radius, Verification Evidence, Test Infra Improvement Notes, and Resume and Execution Handoff.
9. Keep resume/dependency notes Markdown-structured for now; do not invent a second machine-only schema.
10. If the work is a large multi-phase program, create or update a feature folder plan set:

• one umbrella/orchestration plan
• one direct plan file per phase
• one durable report destination per phase

11. Validate the generated artifact:

node .claude/skills/vc-generate-plan/scripts/validate-plan-artifact.mjs <plan-path>

Important Rules

• For standard work, create exactly one plan file.
• For a phase program, create one umbrella plan plus one direct plan file per phase.
• Prefer process/features/{feature}/active/{slug}_{date}/ task folder when the topic maps to an existing feature folder.
• Keep phase status honest: code-only completion is CODE DONE, not VERIFIED.
• Make execution trust explicit inside the plan: what code or data can change, what contracts are exposed, what proof is required, and how EXECUTE should resume after compaction.
• End with the next instruction for RIPER-5 or Cursor Plan mode.
• Treat validation failures as blockers before presenting the plan as ready.
• Fold red-team questions, dependency mapping, verification gates, and ambiguity checks into the generated plan itself instead of relying on a parallel plan-owner workflow.
• Do not hide a large program inside one giant plan if execution will actually happen phase by phase.
• Preserve the older complex-plan behavior by keeping pre-phase research and proof gates inside each phase plan; the new protocol changes the artifact shape, not the rigor.

Required Plan Sections

For new or newly touched direct *_PLAN_*.md files, include all of the following sections:

• Touchpoints — files, packages, or services that will be changed or read
• Public Contracts — interfaces, APIs, schemas, or behaviors visible to other packages or callers
• Blast Radius — the scope of change: how many files, which packages, and what risk class
• Verification Evidence — table with columns | Gate / Scenario | Strategy | Proves SPEC criterion |; each row maps a test gate to the SPEC acceptance criterion it proves and the strategy (Fully-Automated / Hybrid / Agent-Probe)
• Test Infra Improvement Notes — placeholder at plan-write time ("(none identified yet)"); updated with test infrastructure gaps found during vc-test-coverage-plan and EVL
• Resume and Execution Handoff — required sub-fields:
  1. selected plan file path
  2. last completed phase or step
  3. validate-contract status (written / skipped with reason / pending)
  4. supporting context files loaded
  5. next step for a fresh agent picking up mid-execution
• Validate Contract — written by vc-validate-agent after VALIDATE runs; leave a placeholder heading during PLAN (## Validate Contract\n\n(placeholder — vc-validate-agent writes this section before EXECUTE))

Use Markdown-structured sections, not a second machine-only schema. Markdown sections are stable across all agents (Claude, Codex, future systems) without requiring a parser.

Generate SPEC

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Use this skill to produce the authoritative product-discovery SPEC artifact for a task — a plain-language requirements document written for user review, not for an engineer.

A SPEC captures what the user wants and why so the user can read it, recognize their own intent, and confirm "yes, build that" before any approach or code is chosen. It is the bridge between RESEARCH (the facts) and INNOVATE (the how). PLAN cannot start until a SPEC exists for non-trivial work.

SPEC consumes: RESEARCH findings + the user's stated intent/brainstorm. It does NOT consume a chosen approach or a Decision Summary — no approach exists yet at SPEC time.

Normal output is one SPEC file: {slug}_SPEC_{dd-mm-yy}.md.

For a phase program, the program-level (umbrella) SPEC is written once during the outer loop and governs every inner phase. Use templates/program-spec-template.md for that case. The inner loop never writes a SPEC.

Workflow

1. Read references/spec-contract.md for the full section-by-section writing rules.
2. Run date +%d-%m-%y before choosing the filename.
3. Confirm the inputs are present: RESEARCH findings + the user's stated intent. If neither is present, emit SPEC_INTENT_BLOCKED instead of writing.
4. Read process/context/all-context.md first, then load the relevant context group. When the work touches testing/verification, read process/context/tests/all-tests.md so acceptance-criteria scenarios are grounded in the real test-context chain.
5. Save the SPEC inside the task folder alongside the plan: process/features/{feature}/active/{slug}_{date}/{slug}_SPEC_{date}.md (or process/general-plans/active/{slug}_{date}/{slug}_SPEC_{date}.md). For a phase program, the umbrella task folder holds {program-slug}_SPEC_{date}.md. Per task-folder artefact colocation, never write to the deprecated sibling reports/ or references/ dirs.
6. Write the SPEC sections in canonical order (see references/spec-contract.md):
   • ## Summary
   • ## User Stories / Jobs To Be Done
   • ## What The User Wants (Behavioral Outcomes)
   • ## Flow / State Diagram (ASCII)
   • ## Acceptance Criteria (Testable Outcomes) — each criterion carries proven by: + strategy:
   • ## Out Of Scope
   • ## Constraints
   • ## Open Questions
   • ## Background / Research Findings
7. Keep the document oriented for user review: plain language, no file paths, no library names, no schema or code. Anything engineer-only moves to Background or a later phase.
8. Each acceptance criterion MUST be provable by comprehensive tests, with a fully-automated E2E/integration gate wherever the behavior is automatable. Agent-Probe / Known-Gap stand only as an explicitly-justified residual. Vacuous-green is banned.
9. If ## Open Questions is non-empty at finalize (interactive session): emit SPEC_INTENT_BLOCKED and stop. Under /goal: record each as a backlog note and continue.
10. Once Open Questions is empty/"None" (or backlogged under /goal): save the file and the agent emits PHASE_COMPLETE: SPEC.

Important Rules

• The SPEC is written for a human reviewer. If a sentence only makes sense to an engineer, rewrite it or move it to Background.
• Do NOT choose an implementation approach (INNOVATE's job, downstream), write implementation steps (PLAN), make schema decisions, or include code/library references.
• Do NOT modify any file except the SPEC file being created.
• Acceptance-criteria scenarios must be grounded in the RESEARCH test-context-discovery, not invented here.
• Once INNOVATE/PLAN begins the SPEC is frozen — later scope gaps go to the phase report ## SPEC Gaps heading and a backlog note, never an edit to the SPEC.
• For a phase program, write the umbrella SPEC once; the inner loop reads it and never writes a per-phase SPEC.

Required SPEC Sections

Every SPEC file must include all of the following, in this order:

• ## Summary — one plain-language paragraph: what changes for the user and why
• ## User Stories / Jobs To Be Done — the heart of the doc; "As a [user], I want [X], so that [Y]" or JTBD
• ## What The User Wants (Behavioral Outcomes) — observable behavior only, no implementation
• ## Flow / State Diagram — at least one ASCII flow/state diagram
• ## Acceptance Criteria (Testable Outcomes) — observable outcomes, each with proven by: + strategy:; max 20
• ## Out Of Scope — at least one item
• ## Constraints — user-stated, system/process, and technical limits from research
• ## Open Questions — each with an owner; empty/"None" required to finalize (interactive)
• ## Background / Research Findings — key facts from RESEARCH that shaped the requirements

Use Markdown-structured sections, not a second machine-only schema. Markdown sections are stable across all agents (Claude, Codex, future systems) without requiring a parser.

vc-intent-clarify

Output style: lead each question with the recommended option; plain language, no filler — process/development-protocols/communication-standards.md.

Two-mode intent clarification: SIMPLE (direct, 3-5 reads) and DEEP (research subagent first, then questions).

Scores a user request's ambiguity and — when Tier 2 triggers — produces a structured, multi-dimension clarification suite with option-rich questions rather than open-ended prompts. Uses vc-scenario, vc-predict, and vc-sequential-thinking style reasoning to generate questions, not just to answer them.

This is the highest-leverage skill in the system. Poor intent clarification wastes entire phase programs. Invest in the question generation step.

When To Invoke

At ORCHESTRATOR before every routing decision for new user requests. Check auto-skip conditions first. If none apply, score the four signals and act on the resulting tier.

Auto-Skip Conditions

These conditions force Tier 0 regardless of the ambiguity score. Check these FIRST.

1. Continuation phrases — "go", "continue", "proceed", "just do it", or similar standalone instruction
2. Mid-phase-program execution — active phase plan is selected and approved, user is advancing
3. Trivial fix — single-file, under 15 lines, no schema/API/auth changes
4. Explicit mode command — "ENTER EXECUTE MODE", "ENTER RESEARCH MODE", etc.
5. Resuming active plan — an existing active plan is identified and confirmed
6. Pure information question — "What is X?", "How does Y work?" mapping to a single obvious routing target

When an auto-skip condition matches, produce only a 1-sentence restatement of intent and route immediately per the existing routing protocol. Do not announce the tier. Do not surface any questions.

Priority ordering when multiple conditions match simultaneously:

1. Explicit mode command (highest priority)
2. /goal mid-program execution
3. Continuation phrase
4. Trivial fix / active-plan resume (lowest priority)
5. Pure information question / resuming active plan (lowest priority — treated as Tier 0, auto-route to vc-research-agent or answer directly)

Apply only the highest-priority matching condition's abbreviated behavior. Do not combine behaviors from multiple matching conditions.

Under /goal autonomous execution: Even when an auto-skip condition matches and Tier 0 applies, the 1-sentence restatement MUST be emitted to the chat log as an audit entry. Never skip the restatement emit under /goal — it proves Tier-0 ran and serves as the audit log for that phase's intent confirmation.

4-Signal Scoring Formula

Each signal is worth +1. Sum to get the ambiguity score.

Score thresholds:

Mode Selection

Before running any tier, the orchestrator selects the operating mode. Mode affects only HOW option values are populated in questions — the question FORMAT, CRITICAL/USEFUL grouping, and wait-for-go-ahead footer are identical in both modes.

SIMPLE MODE (default)

• Orchestrator runs the skill directly in the main thread
• 3–5 file reads max (the Light Research Pass below)
• Works when concrete option values can be derived from active plans + context routing alone
• No subagent spawning

Trigger conditions (all must be true for SIMPLE):

• Ambiguity score ≤ 3
• Request is scoped to a known file, package, or named feature
• Orchestrator can fill option values from active plans + context routing alone
• Continuation, resume, or single-package scenario

DEEP MODE

• Spawns a full research subagent BEFORE generating questions
• The subagent returns structured findings; the orchestrator uses those findings to populate question options with real file paths, concrete values, and risk-aware implications
• No generic {X} placeholders ever — this mode's entire purpose is to eliminate them
• Questions are materially better because they are grounded in actual codebase discovery

Trigger conditions (any ONE triggers DEEP):

• Ambiguity score is 4/4 (all four signals)
• Request involves a phase program kickoff (new umbrella + N phases)
• Request touches 3+ packages or feature folders
• Request involves an architectural decision (new pattern, library swap, schema design)
• User explicitly requests deep analysis ("deep dive", "investigate before asking", "thorough")
• Orchestrator judges that good option values CANNOT be generated without a codebase scan

Deep Mode — Research Subagent Protocol

When DEEP MODE is triggered, the orchestrator spawns a research subagent before generating questions. The subagent's only job is to return raw findings — it does NOT generate questions.

Research Subagent Prompt Template

Pass this prompt to the subagent verbatim, substituting the bracketed values:

INTENT CLARIFY — DEEP MODE RESEARCH
Request: [user's exact request]
Relevant feature: [if known, else "unknown"]
Active plans found: [list from plan-discovery]

Your job: investigate the request deeply so the orchestrator can generate high-quality clarifying questions.

Required steps (all must run):
1. vc-review-situation — current branch, worktrees, active plans, uncommitted changes
2. vc-scout — scan codebase for files/modules relevant to: [keywords from request]
3. vc-sequential-thinking — map the decision dimensions: what must be decided first? what is downstream?
4. vc-scenario — for each plausible interpretation: what are the top 3 failure modes?
5. vc-predict — 5-persona debate: senior dev / PM / security reviewer / QA / end user — what does each want to know before starting?

Return structured output with these sections:
- DISCOVERED CONTEXT: actual file paths, module names, package names found
- DECISION DIMENSIONS: ordered list of decisions that have downstream impact
- RISK SURFACE: for each interpretation, top 2 failure modes
- PERSONA DISAGREEMENTS: what different stakeholders would want prioritized differently
- CONCRETE VALUES: real paths, command strings, feature names to use in question options

Do NOT generate questions — that is the orchestrator's job. Just return raw findings.

After Receiving Subagent Output

The orchestrator uses the subagent's DISCOVERED CONTEXT and CONCRETE VALUES sections to replace every option value in the Tier 2 question suite. The question generation steps (Steps 1–6 in Tier 2 below) proceed as normal, but option text is populated from real findings instead of the light research pass.

Tier 0: Silent Auto-Route

No user interaction added. Score 0–1 or auto-skip triggered.

Route to the detected agent per the existing routing protocol. Do not show a routing summary.

Tier 1: Routing Summary

Perform a light research pass (see section below). Then present:

Routing: [detected intent] → [target agent]
Scope: [what I think you want changed]
Plan: [existing plan if found, or "new work"]

WAIT for the user's next message before routing. Do NOT route in the same response. Do NOT say "I'll proceed unless you correct me."

If the user confirms, proceed. If the user corrects, re-score and re-route.

Tier 2: Full Structured Clarification Suite

Tier 2 is the core of this skill. When triggered, the orchestrator does the following:

Step 1 — Research pass (mode-dependent)

In SIMPLE MODE: Perform a light research pass (see Light Research Pass section). Budget: 3–5 file reads. Scan active plans, context routing table, recent git state, and the named file/package if any. This populates concrete values in question options.

In DEEP MODE: The research subagent has already run (see Deep Mode section above) and returned structured findings. Use the DISCOVERED CONTEXT and CONCRETE VALUES sections from those findings instead of performing a light research pass. Skip the 3–5 file read budget — the subagent already covered it.

In both modes, the goal of Step 1 is identical: replace every generic placeholder in question options with concrete values (package paths, plan IDs, file names, feature names).

Step 2 — Question generation using vc-scenario + vc-predict style reasoning

Before writing the questions, THINK across these axes:

• What are the plausible failure modes if we pick the wrong scope? (vc-scenario thinking)
• What would 5 different people (senior dev, PM, security reviewer, QA, end user) want to know before starting? (vc-predict thinking)
• What ordering of decisions has the most downstream impact? (vc-sequential-thinking)

Use this analysis to GENERATE questions — not to answer them. The goal is to surface the decisions that, if made wrong, will cause the most rework.

Step 3 — Classify each dimension as CRITICAL or USEFUL

• CRITICAL — getting this wrong derails the entire phase or causes rework
• USEFUL — helpful context but can default to recommendation without blocking

CRITICAL dimensions appear first. The user can say "skip useful questions" to answer only CRITICAL ones.

Step 4 — Format each question using AskUserQuestion tool

REQUIRED: use the AskUserQuestion tool to render all Tier 2 questions. Do NOT render questions as markdown text. The AskUserQuestion tool renders clickable option selections in the Claude Code UI, which is far faster for the user than typing answers.

How to call it:

• Pass all questions in a single AskUserQuestion call (up to 4 per call)
• Group CRITICAL questions into the first call(s), USEFUL questions after
• Use multiSelect: false for mutually exclusive choices (default)
• Use multiSelect: true only when the user genuinely needs to pick multiple options (e.g. "which packages are in scope")
• The header field (max 12 chars) is the chip label — use the dimension name abbreviated
• Set description to the 1–2 sentence consequence explanation
• Each option label is the short choice text; description is the implication

Option rules (same as before, now applied to AskUserQuestion fields):

• Minimum 3 options per question (the tool supports up to 4; always include an "Other" option as the last one)
• Mark exactly one option as (Recommended) by appending it to the label: "Sequential — single agent (Recommended)"
• Fill option labels with concrete values from the research pass (real file paths, package names, plan IDs) — never generic placeholders
• The "Other" option label: "Other" with description: "Describe your preference in the next message"

If AskUserQuestion is unavailable (tool not in scope, non-interactive context): fall back to the markdown format below, but always prefer the tool when available.

**Q[N]: [Question title]**
[1–2 sentences explaining why this decision matters and what goes wrong if we choose incorrectly.]

Options:
  A) [option] — [implication] *(Recommended)*
  B) [option] — [implication]
  C) [option] — [implication]
  D) Other: describe your preference

Step 5 — Group questions by dimension with headers

Each dimension header format:

### [Dimension name] 🔴 CRITICAL

or

### [Dimension name] 🟡 USEFUL

Step 6 — Emit wait-for-go-ahead footer

After all questions, always emit:

Answer what you want — partial answers are fine. I'll use the (Recommended) defaults for anything you skip. Ready to proceed when you confirm.

Do NOT route to any subagent before receiving at least a partial response or explicit "go".

The 8 Standard Dimensions

For a substantial request, cover all 8 dimensions. For a narrower request, use only the dimensions that are genuinely ambiguous. Do not pad — every question should require a real decision.

Dimension 1 — Scope and Boundaries 🔴 CRITICAL

Clarify what changes and — equally important — what must NOT change.

Example questions:

• Which packages/files are in scope?
• Are there components or APIs that must remain untouched?
• Is this isolated to one package or cross-cutting?

Dimension 2 — Success Criteria 🔴 CRITICAL

Clarify what the user truly wants to see as a result.

Example questions:

• What does "done" look like to you?
• Is the goal a passing test suite, a deployed change, a passing code review, or visible UI behavior?
• Is there a specific user action or flow that must work?

Dimension 3 — Failure Modes and Risk Surface 🔴 CRITICAL

Clarify what the user is most worried about going wrong.

Example questions:

• What are the most likely ways this change breaks something?
• Are there auth, billing, schema, or public API surfaces this touches?
• Is there a rollback requirement?

Dimension 4 — Prior Context 🟡 USEFUL

Clarify what has already been tried or is already in progress.

Example questions:

• Is there an existing plan file for this?
• Has this been attempted before? What happened?
• Is this a continuation of recent work (visible in git status or active plans)?

Dimension 5 — Priority and Urgency 🟡 USEFUL

Clarify the expected speed/quality tradeoff.

Example questions:

• Is this a hotfix that needs to ship now, or a proper implementation with full plan/test coverage?
• Does this block other work in flight?
• Quick patch acceptable, or must it be production-grade immediately?

Dimension 6 — Autonomy Boundaries 🟡 USEFUL

Autopilot Mode — CRITICAL promotion: When an autopilot trigger phrase is detected, Dimension 6 is treated as 🔴 CRITICAL rather than 🟡 USEFUL. It must appear in the first AskUserQuestion call alongside the CRITICAL dimensions, not after them. The question must explicitly name the three hard stops and ask the user to confirm they understand those remain manual-first gates.

Clarify how much the agent can decide on its own vs. checkpoint with the user.

Example questions:

• Can the agent pick the implementation approach, or does the user want to choose?
• Should the agent pause for approval before destructive changes (schema migrations, API removals)?
• Is a /goal-style autonomous run acceptable, or does each phase need a checkpoint?

Autopilot-specific example (when trigger detected):

• "This run will proceed autonomously. The following gates remain manual regardless: (1) irreversible/outward-facing actions not in the validate-contract, (2) live-provider billed feasibility probes (cost-class: needs-live-provider), (3) cascade BLOCKED (two consecutive phases BLOCKED). All other gates auto-proceed. Are there any additional gates you want to keep manual for this run?"

Dimension 7 — Technical Constraints 🟡 USEFUL

Clarify any specific libraries, patterns, or constraints the solution must conform to.

Example questions:

• Is there a specific library or pattern required?
• Are there style/lint rules that constrain the approach?
• Must the solution work in a specific runtime environment (Bun vs Node, edge vs server)?

Dimension 8 — Phase Program Questions 🔴 CRITICAL (multi-phase only)

Only include when the request implies multiple dependent phases or a long-running program.

Example questions:

• Should phases run sequentially or can some parallelize?
• Which phase is the hard dependency for the rest?
• What is the acceptable stopping point if a later phase is blocked?

Full Tier 2 Example

Below is a complete example of good Tier 2 output for a request like "refactor the billing flow to add credit top-up support."

Intent understood: Add credit top-up support to the billing flow. Before routing, I need to resolve a few key decisions.

Scope and Boundaries 🔴 CRITICAL

Q1: Which layers does this change touch? Getting scope wrong here means re-opening files mid-phase and invalidating earlier test gates.

Options: A) Prisma schema + tRPC billing router + UI billing page — full stack (Recommended) B) tRPC billing router + UI only — skip schema migration for now C) UI only — wire to existing endpoints, validate assumptions first D) Other: describe your preference

Q2: Which existing billing surfaces must NOT change? We need to know what is off-limits before touching shared code paths.

Options: A) Stripe webhook handlers and subscription models are frozen (Recommended) B) Only the credit transaction model is frozen C) Nothing is frozen — all billing code is in scope D) Other: describe your preference

Success Criteria 🔴 CRITICAL

Q3: What does "done" look like? If the success bar is wrong, the agent will stop too early or overshoot.

Options: A) User can trigger a top-up from the UI and credit balance updates — end-to-end (Recommended) B) Backend complete with tests passing; UI is out of scope for this phase C) Plan written and approved — no implementation yet D) Other: describe your preference

Failure Modes and Risk Surface 🔴 CRITICAL

Q4: Is there a risk surface we must protect? Billing changes can silently double-charge or under-credit users if guard logic is missing.

Options: A) Add explicit idempotency key to the top-up Stripe call (Recommended) B) No idempotency needed — amount is small enough that duplicates are acceptable C) Not sure — flag for code review D) Other: describe your preference

Priority and Urgency 🟡 USEFUL

Q5: Speed vs. quality tradeoff? Affects whether we write a full plan with validate-contract or skip to a lightweight execute.

Options: A) Proper plan + validate-contract + full test coverage (Recommended) B) Quick implementation with tests deferred to a follow-up C) Research and plan only — no implementation this session D) Other: describe your preference

Answer what you want — partial answers are fine. I'll use the (Recommended) defaults for anything you skip. Ready to proceed when you confirm.

Bad vs. Good Question Format

Understanding the failure modes in question generation:

Bad (open-ended, no options)

Q: What scope should the refactor cover?

This forces the user to type a free-form answer. Slow. Vague. Hard to act on.

Bad (only 2 options, no recommendation marked)

Q: Full stack or UI only?
  A) Full stack
  B) UI only

Binary questions miss the third path. No recommendation means the user has no default to accept.

Bad (generic placeholders left in)

Q: Which areas? [A] just {X} [B] {X} and {Y}

Placeholders not replaced with concrete values from light research. Signals the skill was invoked lazily.

Good

**Q1: Which packages does this refactor touch?**
Scope determines which test gates apply and which blast-radius files need review before touching code.

Options:
  A) packages/api/src/router/billing.ts + apps/web/src/app/billing — full stack *(Recommended)*
  B) apps/web/src/app/billing only — frontend changes, read-only backend exploration
  C) packages/api/src/router/billing.ts only — backend logic, no UI changes yet
  D) Other: describe your preferred scope

Autonomy Mode

What Grants Autonomy

• Explicit autonomy phrases: "you decide", "just do it", "full autonomy", "don't ask", "autonomous"
• Mid-phase-program context where the current phase plan is selected and approved
• User has answered Tier 2 questions and said "go"
• Autopilot Mode trigger phrase detected (see orchestration.md §Autopilot Trigger Routing): autonomy is granted for the full run scope. Dimension 6 (Autonomy Boundaries) is treated as CRITICAL rather than USEFUL for this session.

Phrase Matching Rule

Autonomy phrases must be standalone statements or sentence-initial. They do NOT match when embedded in descriptive text.

• "just do it" (standalone) → autonomy granted
• "just do the simple version" → NOT autonomy (descriptive use, user is specifying scope)
• "you decide how to implement it" → autonomy granted

What Autonomy Means

• All tiers collapse to Tier 0 for the current task chain
• Clarification questions are skipped
• Routing summaries are skipped

What Autonomy Does NOT Override

• EXECUTE approval gate ("ENTER EXECUTE MODE" still required)
• Plan review checkpoint
• Phase-program phase boundaries
• High-risk execution handoff gates
• The Consolidated Autopilot Clarification Round (see §Autopilot Clarification Mode below) — autopilot grants autonomy for the run, but the clarification round itself still fires once to lock the session. It is a different gate from the standard intent-clarify suite.

Autopilot Clarification Mode

When an autopilot trigger is detected (see orchestration.md §Autopilot Trigger Routing), the standard Tier 0/1/2 scoring flow is bypassed. A single Consolidated Autopilot Clarification Round replaces it.

When This Mode Fires: The orchestrator sets autopilot clarification mode when a recognized autopilot trigger phrase is detected at any RIPER-5 phase boundary. The trigger detection and phrase list live in orchestration.md §Autopilot Trigger Routing — this skill does not own the detection logic.

Consolidated-Round Rule: Issue exactly ONE AskUserQuestion call covering all four mandatory dimensions in a single round-trip: (1) Scope and task name (CRITICAL), (2) Definition of done (CRITICAL), (3) Risk tolerance / Hard-stop confirm (CRITICAL = Dimension 6 promoted), (4) Gate deviations (CRITICAL). After the user responds, the session is locked and the orchestrator proceeds to emit the provisional goal block.

Abort-to-Interactive Rule: If the user responds to the consolidated round with a phrase opting out of autopilot ("actually, let's do this step by step", "cancel autopilot", "stop", "interactive please"): (1) Acknowledge the opt-out, (2) Revert to standard RIPER-5 interactive behavior, (3) Re-issue the standard Combined Clarification Gate (Step 6.5), (4) Do NOT emit the provisional goal block, (5) Deactivate autopilot-mode for this session.

Validator Conformance: Autopilot clarification output MUST include all four validator markers: restatement, score (always 4/4 under autopilot), mode (always deep for phase-program kickoffs), reason/because justification. Full spec: process/development-protocols/autopilot.md §Consolidated Clarification Round.

Light Research Pass

Used in SIMPLE MODE only. In DEEP MODE, the research subagent replaces this step entirely.

Performed by the orchestrator in the main thread, not as a subagent delegation.

Budget: 3–5 file reads max.

What it checks:

1. Active plan inventory (process/general-plans/active/ and process/features/*/active/)
2. Context routing table in process/context/all-context.md (match keywords to domain)
3. Recent git status (uncommitted changes related to the request?)
4. If a specific package or file is named, one quick read of that file

Purpose: replace generic placeholders in question options with concrete names (package paths, plan IDs, model names, router file names). A question with concrete values is 3× more actionable than one with {X}.

This is NOT a full research-agent delegation. Route to research-agent after clarification resolves.

Intent Revalidation After Research

After the research-agent completes, the orchestrator checks whether the original intent still holds.

If research reveals the request is fundamentally different from what was assumed, re-present a Tier 1 routing summary with updated understanding.

If research confirms the original intent, proceed to INNOVATE or PLAN without re-asking. Never repeat clarification that was already resolved.

FAST Mode Integration

Intent clarification fires BEFORE the fast-mode agent is spawned. The orchestrator scores and clarifies in the main thread, then hands the clarified intent to the fast-mode-agent prompt.

Inside the fast-mode-agent, no additional clarification is needed — intent is already resolved.

Fallback (Still Ambiguous After Tier 2)

If the user answers Tier 2 questions but a single routing path still cannot be determined:

1. State what remains unclear in one sentence.
2. Ask one final direct question (plain, not multiple-choice).
3. If still unresolvable after that, default to the research-agent with the narrowest reasonable scope.

Never loop clarification more than twice. Two rounds max, then route to research.

Worked Scoring Examples

Example A — "Fix the login bug on the auth page"

• Ambiguous scope: No (+0) — "auth page" is a specific scope
• No explicit path: Yes (+1) — no file named, but scope is narrow
• Multiple intents: No (+0) — single intent (fix)
• First interaction: No (+0)

Score: 1 → Tier 0, auto-route to debugger/execute.

Example B — "Make the app faster"

• Ambiguous scope: Yes (+1) — bundle size, API perf, rendering, caching all possible
• No explicit path: Yes (+1) — no file or package named
• Multiple intents: Yes (+1) — refactor, config change, infra work, or research
• First interaction: Yes (+1)

Score: 4 → Tier 2, full structured clarification suite. Generate questions across Scope, Success Criteria, Failure Modes, Priority, Technical Constraints (all dimensions where "faster" is ambiguous).

Example C — "Add a top-up button to the billing page"

• Ambiguous scope: No (+0) — billing page is named
• No explicit path: Yes (+1) — no file path
• Multiple intents: Yes (+1) — could stop at UI only or require schema/Stripe changes
• First interaction: Yes (+1)

Score: 3 → Tier 2, but only 3–4 questions covering Scope, Success Criteria, Risk Surface (billing-specific failure modes). Skip Autonomy Boundaries and Phase Program since it's a single-phase feature.

vc-plan-discovery

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Invocation

Primary method — run the auto-discovery script. It applies the Scope Rules below (same-feature full depth; other features active-only; general-plans active always) and extracts ONLY the leading YAML frontmatter block of each .md file (no whole-file reads):

node .claude/skills/vc-plan-discovery/scripts/discover-plans.mjs [--feature <name>] [--json]

It groups output into Active Plans / Backlog / Completed / Reports / References (each line: - [name]: description (path)) and prints a trailing Found N active, N backlog, N completed, N reports, N references line. It never throws on a missing root and exits 0 unless given a bad flag. Use --json for a machine-readable object. Prefer this over the manual scan below — it is deterministic and avoids loading huge files into context.

Per task-folder artefact colocation, the script scans one level into each {slug}_{date}/ task folder and surfaces co-located _PLAN_/_REPORT_/_REF_ artefacts; the sibling reports//references/ dirs are deprecated and only hold legacy artefacts.

The manual scan in Scope Rules below is the FALLBACK for when the script fails.

Purpose

Surface all plans relevant to the current task so agents have full plan context — what was tried, what is in progress, what is deferred, and what reports and references exist — before doing any phase work.

Scope Rules

• Same feature folder (from task context or argument): read ALL of active/, backlog/, completed/, plus any legacy sibling reports/, references/ — surface every file with frontmatter
• Other feature folders: read active/ only — surface plans whose frontmatter description or feature field matches the task domain
• general-plans/active/: always scan
• general-plans/completed/, legacy reports/, references/: scan only when same-feature folder is not identified

Per task-folder artefact colocation, expect every current artefact (plan, spec, reports, references) INSIDE its {slug}_{date}/ task folder — scan one level into each task folder. The sibling reports//references/ dirs are deprecated and only hold legacy artefacts.

Frontmatter Reading

Read frontmatter fields: name, description, type, feature, phase

Route by description field for relevance matching (same approach as vc-context-discovery).

Skip files without frontmatter or with incomplete frontmatter — log as "no frontmatter, skipped".

Output: grouped list by folder — Active Plans / Backlog / Completed / Reports / References — with name + description per file.

When To Invoke

• First action alongside vc-context-discovery at the start of every loop step (research / validate / execute / update-process)
• Any time an agent needs to know: what plans exist for this feature, what was tried before, what is deferred, what references exist

Output Format

### Active Plans
- [name]: description (path)

### Backlog
- [name]: description (path)

### Completed
- [name]: description (path)

### Reports
- [name]: description (path)

### References
- [name]: description (path)

Found N active, N backlog, N completed, N reports, N references

vc-predict — Multi-Persona Pre-Analysis

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Five expert personas independently analyze a proposed change, then debate conflicts to produce a consensus verdict before a single line of code is written.

When to Use

• Before implementing a major or high-risk feature
• Before a significant refactor or architecture change
• Evaluating competing technical approaches
• Stress-testing assumptions in a proposed design

When NOT to Use

• Trivial or low-risk changes (use debugger for bugs, generate-plan / plan-agent for already-decided tasks)
• Already-approved work with no open design questions
• Pure dependency upgrades with no API changes

Mode Selection

vc-predict runs in Simple or Deep mode. Choose based on the conditions below.

Deep Mode — Trigger Conditions (any one is sufficient)

• The approach involves a pattern previously attempted in this codebase (git history may show prior attempts)
• The approach touches a surface with known failure history: auth, billing, container lifecycle, streaming, or WebSocket reconnect
• Caller explicitly requests deep mode (--deep flag or "use deep predict")
• The plan is COMPLEX shape and this is the pre-checklist predict call

Simple Mode — Trigger Conditions (default)

• Approach is a contained feature with clear scope
• No prior attempts at this surface area are likely
• Plan is SIMPLE shape and the design is not controversial

Deep Mode — Research Subagent Protocol

Before the 5-persona debate, spawn a research subagent that performs the following steps in order:

1. Git history scan — run git log --oneline --all -- [relevant files] for each file or directory the approach touches. Flag any commits within the last 6 months that suggest a prior attempt, revert, or known fix.
2. Prior phase reports — search task folders under process/features/{feature}/active/ and process/features/{feature}/completed/ for _REPORT_ files mentioning this surface (pattern: active/{slug}_{date}/{slug}_REPORT_{date}.md). Read any that contain keywords from the approach (e.g. "streaming", "SSE", "auth", "billing", "container lifecycle"). Legacy sibling reports/ dir may also exist — scan it too if present.
3. Test failure history — grep test output files and CI logs for FAIL or Error patterns on relevant module names. Note recurring failures.
4. Return a Historical Context block containing:
   • What was tried before (commit refs, dates, brief description)
   • What failed and why
   • Current state of the surface (is it stable, under active churn, recently refactored?)
   • Known landmines (specific lines, patterns, or edge cases that broke before)

The 5 personas then receive this Historical Context block before their independent analysis phase. Each persona incorporates it when relevant.

Output Quality Difference

Simple predict (no research):

"Senior dev: this streaming approach could cause a memory leak in the SSE proxy."

Deep predict (with historical research):

"Senior dev: we tried this exact streaming approach in commit a3f921 (2026-03-15) — it caused a memory leak in the SSE proxy because the Bun response body was never released on client disconnect. The current proposal has the same pattern in packages/api/src/routes/gateway-proxy.ts line 84. The fix at the time was adding an AbortController listener; verify that is still present or re-apply."

The 5 Personas

Debate Protocol

1. Read the proposed change/feature description from the argument
2. Read relevant code if file paths are provided (grep for affected areas)
3. Each persona analyzes independently — do not let personas influence each other during this phase
4. Identify agreements — points where all (or 4+) personas align
5. Identify conflicts — points where personas meaningfully disagree
6. Weigh tradeoffs — for each conflict, evaluate which concern has higher impact
7. Produce verdict — GO / CAUTION / STOP with actionable recommendations

Output Format

## Prediction Report: [proposal title]

## Verdict: GO | CAUTION | STOP

### Agreements (all personas align)
- [Point 1 — what they all agree on]
- [Point 2]

### Conflicts & Resolutions

| Topic | Architect | Security | Performance | UX | Devil's Advocate | Resolution |
|-------|-----------|----------|-------------|-----|-----------------|------------|
| [Issue] | [View] | [View] | [View] | [View] | [View] | [Recommendation] |

### Risk Summary

| Risk | Severity | Mitigation |
|------|----------|------------|
| [Risk description] | Critical/High/Medium/Low | [Concrete action] |

### Recommendations
1. [Action item — rationale]
2. [Action item — rationale]
3. [Action item — rationale]

Verdict Levels

STOP Triggers (any one is sufficient)

• Security persona identifies auth bypass or data exposure with no viable mitigation
• Architect identifies fundamental design incompatibility requiring significant rework
• Performance persona identifies unacceptable latency or query explosion with no workaround
• Devil's Advocate exposes a false assumption that invalidates the entire approach

Integration with Other Skills

Example Invocations

Simple Mode (default)

/vc-predict "Add WebSocket support for real-time notifications"
/vc-predict "Migrate authentication from JWT to session cookies"
/vc-predict "Add multi-tenancy to the database layer"
/vc-predict "Replace REST API with GraphQL" --files src/api/**/*.ts

Deep Mode

/vc-predict "Rework SSE streaming for chat responses" --deep
/vc-predict "Change container lifecycle on instance stop" --deep --files packages/api/src/infra/**/*.ts
/vc-predict "Refactor billing credit deduction" --deep

Deep mode is also auto-triggered (no flag needed) when the plan is COMPLEX shape or the approach touches auth, billing, container lifecycle, or streaming surfaces.

Problem-Solving Techniques

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Systematic approaches for different types of stuck-ness. Each technique targets specific problem patterns.

When to Use

Apply when encountering:

• Complexity spiraling - Multiple implementations, growing special cases, excessive branching
• Innovation blocks - Conventional solutions inadequate, need breakthrough thinking
• Recurring patterns - Same issue across domains, reinventing solutions
• Assumption constraints - Forced into "only way", can't question premise
• Scale uncertainty - Production readiness unclear, edge cases unknown
• General stuck-ness - Unsure which technique applies

Quick Dispatch

Match symptom to technique:

Core Techniques

1. Simplification Cascades

Find one insight eliminating multiple components. "If this is true, we don't need X, Y, Z."

Key insight: Everything is a special case of one general pattern.

Red flag: "Just need to add one more case..." (repeating forever)

2. Collision-Zone Thinking

Force unrelated concepts together to discover emergent properties. "What if we treated X like Y?"

Key insight: Revolutionary ideas from deliberate metaphor-mixing.

Red flag: "I've tried everything in this domain"

3. Meta-Pattern Recognition

Spot patterns appearing in 3+ domains to find universal principles.

Key insight: Patterns in how patterns emerge reveal reusable abstractions.

Red flag: "This problem is unique" (probably not)

4. Inversion Exercise

Flip core assumptions to reveal hidden constraints. "What if the opposite were true?"

Key insight: Valid inversions reveal context-dependence of "rules."

Red flag: "There's only one way to do this"

5. Scale Game

Test at extremes (1000x bigger/smaller, instant/year-long) to expose fundamental truths.

Key insight: What works at one scale fails at another.

Red flag: "Should scale fine" (without testing)

Application Process

1. Identify stuck-type - Match symptom to technique above
2. Load detailed reference - Read specific technique from references/
3. Apply systematically - Follow technique's process
4. Document insights - Record what worked/failed
5. Combine if needed - Some problems need multiple techniques

Combining Techniques

Powerful combinations:

• Simplification + Meta-pattern - Find pattern, then simplify all instances
• Collision + Inversion - Force metaphor, then invert its assumptions
• Scale + Simplification - Extremes reveal what to eliminate
• Meta-pattern + Scale - Universal patterns tested at extremes

References

Load detailed guides as needed:

• references/when-stuck.md - Dispatch flowchart and decision tree
• references/simplification-cascades.md - Cascade detection and extraction
• references/collision-zone-thinking.md - Metaphor collision process
• references/meta-pattern-recognition.md - Pattern abstraction techniques
• references/inversion-exercise.md - Assumption flipping methodology
• references/scale-game.md - Extreme testing procedures
• references/attribution.md - Source and adaptation notes

vc-publish

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Push harness improvements from the current development repo to the remote kit repository (vibecode-pro-max-kit). This is the maintainer counterpart to vc-update.

• vc-update = user pulls latest harness INTO their project FROM the remote
• vc-publish = maintainer pushes improvements FROM the development repo TO the remote kit repo

Prerequisites

• Local checkout of the kit repo (git clone git@github.com:withkynam/vibecode-pro-max-kit.git)
• .vc-publish-config file in the current repo root (see Configuration below)
• Git push access to the remote kit repo

Configuration

Create .vc-publish-config in the repo root:

{"kitRepoPath": "/path/to/vibecode-pro-max-kit"}

If this file is missing, ask the user for the kit repo checkout path and offer to create it.

Workflow

Step 1: Load Configuration

1. Read .vc-publish-config from the current repo root.
2. If missing, ask the user for the kit repo local checkout path.
3. Verify the path exists and contains vc-manifest.json.
4. Verify the kit repo worktree is clean (git -C <kitRepoPath> status --porcelain). If dirty, warn and ask whether to proceed or abort.

Step 2: Read Manifest

5. Read vc-manifest.json from the kit repo checkout.
6. Extract the current version.
7. Before computing a version bump, check if the current kit version already matches the intended target version (e.g. 3.0.0). If the kit version already equals the target: skip the bump step entirely and proceed directly to Step 3 with a tag-as-is note — do not increment the version. Record in the publish summary that the version was unchanged.

Catalog-regen (pre-publish): Before resolving files in Steps 3–4, regenerate the skills catalog in the dev repo:

node .claude/skills/vc-audit-context/scripts/generate-skills-catalog.mjs --write

This ensures process/context/generated-skills-catalog.json is current before it is copied into the kit repo.

Step 3: Resolve Kit File Set

7. Run the resolver against the kit repo to get the kit file list:

   node <kitRepoPath>/resolve-manifest.mjs --root <kitRepoPath> --json
   

   Extract files (kit managed files) and kitOnly (kit-exclusive files).

   Note: resolve-manifest.mjs reads vc-manifest.json from its --root directory and also scans files from that same root. vc-manifest.json is NOT installed into dev/user projects by install.sh, so the resolver must always be pointed at the kit repo checkout (which does have it). There is no separate dev-repo resolver call — the dev-side file comparison happens inside compute-sync-plan.mjs in Step 4.

Step 4: Compute Diff

9. Computation via compute-sync-plan.mjs: Use the shared computation core to produce the diff between the dev repo's managed files and the kit repo's current managed files.

   Direction note: compute-sync-plan.mjs loads vc-manifest.json from --kit-root and runs the resolver with --root <kit-root>. Since vc-manifest.json lives in the kit repo (not the dev repo), --kit-root must always be the kit repo checkout. --root is the dev repo (the project being compared). This is the same direction as a normal install — vc-publish uses it to see what a fresh install FROM dev INTO the kit would change.

   # --root = dev repo (the "project" being compared against the kit source)
   # --kit-root = kit repo (where vc-manifest.json lives; source of truth for file lists)
   # --resolver overrides the resolver path because compute-sync-plan
   # would otherwise look for resolve-manifest.mjs inside --kit-root,
   # which IS the kit repo here, so --resolver is optional but explicit for clarity.
   node <kitRepoPath>/compute-sync-plan.mjs \
     --root <devRepoRoot> \
     --kit-root <kitRepoPath> \
     --resolver <kitRepoPath>/resolve-manifest.mjs \
     --json
   

   Parse the JSON output: { toAdd, toModify, toDelete, toPreserve, staleWarnings }.

   • toAdd — files to copy from dev to kit (present in dev, not yet in kit).
   • toModify — files to overwrite in kit (tracked in both, content differs).
   • toDelete — files to remove from kit (no longer in dev managed set).
   • toPreserve — files to leave untouched (merge/copyIfMissing survivors, unchanged files).
   • staleWarnings — paths that failed the namespace guard — print to user; do NOT delete.

   The ownedPaths for the publish direction are the dev repo's resolved ownedPaths. CLAUDE.md and AGENTS.md are always in the merge category — they require special stripping regardless of diff status (see Step 7).

Step 5: Print Diff Summary

10. Print a summary table:

vc-publish diff: current repo -> kit repo (v2.1.0)
================================================

FILES:
  [modified]  .claude/agents/vc-execute-agent.md  (+8 -3)
  [modified]  .claude/hooks/lib/scout-checker.cjs  (+2 -1)
  [new]       .claude/skills/vc-new-skill/SKILL.md
  [merge]     CLAUDE.md (needs content review)
  [merge]     AGENTS.md (needs content review)
  [unchanged] .claude/settings.json
  ... (350 more unchanged)

Total changes: 4 files modified, 1 new, 0 removed

Step 6: STOP -- Confirm Publish

11. STOP and ask the user:
    • Confirm they want to publish these changes.
    • Specify version bump type: patch, minor, or major.
    • Optionally provide release notes (1–3 sentences for the GitHub Release body). Leave blank to auto-generate from the diff summary (e.g. "4 modified, 1 new, 0 removed.").
    • Or abort.

Version bump semantics:

• Patch (2.1.0 -> 2.1.1): hook fixes, skill doc updates, minor agent prompt tweaks
• Minor (2.1.0 -> 2.2.0): new skills, new agents, new development protocols
• Major (2.1.0 -> 3.0.0): CLAUDE.md structure changes, manifest schema changes, breaking workflow changes

Step 7: Apply Changes

12. On confirm:

    • Copy all modified and new managed files from current repo to kit repo checkout.

    • For each removed file: delete it from the kit repo checkout.

    • CLAUDE.md and AGENTS.md stripping: Do NOT copy the current repo's project-specific versions directly. Instead:

      1. Read the current repo's CLAUDE.md/AGENTS.md.
      2. Read the kit repo's existing harness-only version as base.
      3. Apply only methodology/structural changes from the dev repo to the kit's harness-only version.
      4. Strip all project-specific content:
         • Technology stack details (frameworks, databases, versions)
         • Feature list / "Current features" entries
         • Project-specific context groups
         • Hardcoded package manager (replace with generic)
         • MCP server instructions (project-specific config)
         • Project-specific routing rules
         • Absolute paths (/Users/...)
         • Product name references (the project's product name and repo/directory name)
      5. Verify the result is harness-only methodology with no project leaks.

    • Manifest reconciliation (vc-manifest.json) — the manifest is NOT a normally-copied managed file (it is dev-only on one side and kit-resolved on the other), so its fields do NOT auto-sync. Handle it explicitly:

      1. version: bump per the chosen bump type. Kit-authoritative.
      2. legacyDeletions (the deprecation ledger): dev is authoritative and always the superset. Whenever dev removes a skill/dir/file from the harness it appends the path here so downstream projects clean it up on their next vc-update. Set kit.legacyDeletions = dev.legacyDeletions (preserve dev order). This field is a literal path array, NOT a glob — it genuinely changes every time the harness deprecates something, so it MUST be reconciled at every publish. (Historically this was skipped, which silently stranded the kit with stale deletions — never skip it.)
      3. All OTHER non-version fields (include, exclude, strip, merge, copyIfMissing, symlinks, kitOnly): these legitimately diverge — the kit carries packaging-only rules (e.g. excluding **/*.test.mjs and __tests__/** so tests are not shipped to users; kitOnly tooling like compute-sync-plan.mjs). Do NOT blindly overwrite them — a blanket dev→kit copy would strip the kit's test-excludes and ship test files. Instead run the field-level drift report below and reconcile any unexpected drift by hand.

      Drift-report command (run during Step 4 summary AND here before writing):

      node -e '
      const d=require("<devRepoPath>/vc-manifest.json");
      const k=require("<kitRepoPath>/vc-manifest.json");
      let drift=0;
      for(const key of new Set([...Object.keys(d),...Object.keys(k)])){
        if(key==="version") continue;
        if(JSON.stringify(d[key])!==JSON.stringify(k[key])){
          drift++;
          console.log("DRIFT field:",key);
          console.log("  dev:",JSON.stringify(d[key]));
          console.log("  kit:",JSON.stringify(k[key]));
        }
      }
      console.log(drift?("\n"+drift+" manifest field(s) drift — legacyDeletions auto-syncs dev→kit; reconcile the rest consciously."):"manifest in sync (besides version)");
      '
      

      legacyDeletions appearing in the drift report is EXPECTED and is auto-resolved (dev→kit). Any OTHER field in the report is a conscious decision: confirm the kit value is the intended packaging rule, or update dev/kit so they converge. Never let a drift go unexamined.

    • Create symlinks if missing (.agents/skills -> ../.claude/skills).

Step 8: Leak Detection

13. Verify no project-specific content leaked into the kit repo. This is a resolved-set, two-check gate that scans the full shipped TEXT surface, not just CLAUDE.md/AGENTS.md.

    Resolve the shipped set via the kit's resolver, then restrict to TEXT surfaces:

    node <kitRepoPath>/resolve-manifest.mjs --root <kitRepoPath> --json
    

    Take the resolved files and keep only TEXT surfaces:

    • .claude/skills/** matching *.md, *.cjs, *.mjs, *.py, *.js, *.json
    • .claude/agents/** matching *.md
    • .codex/**
    • process/development-protocols/**
    • plus CLAUDE.md, AGENTS.md

    Exclude binaries and **/node_modules/**.

    Check (a) -- product-name grep over the resolved text set. Scan for the product names in the grep below ONLY. tRPC/Prisma are DROPPED from this skill-prose scan to avoid false positives in legitimate generic test guidance; the hosted-database product name is KEPT (see the pattern):

    grep -rIin "flowser\|CloakBrowser\|OpenClaw\|Supabase" <resolved-text-files>
    

    Allowlist the Bucket-4 lines that MUST keep the literal to function (otherwise the gate flags itself): author: flowser frontmatter; the isFlowserActivePlanPath identifier; this skill's OWN scrub-grep pattern lines below; the new validator's own pattern strings; and the one internal plan-generation validation comment in session-init.cjs.

    Check (b) -- non-portable context-path grep: any concrete backticked process/context/... file reference in the resolved text set, MINUS the shipped/seeded survivors, is a dangling-link leak → FAIL with file:line. Survivors (allowed): process/context/all-context.md, process/context/tests/all-tests.md. Portable directory refs (e.g. process/context/tests/) and the process/context/... placeholder are fine.

    Keep the existing narrow CLAUDE.md/AGENTS.md grep (this stays as-is on just those two files; tRPC/Prisma plus the hosted-database product name all REMAIN here, as shown in the pattern below):

    # Must return empty -- any matches indicate leaked content
    grep -ri "flowser\|tRPC\|Prisma\|Supabase\|CloakBrowser\|OpenClaw" CLAUDE.md AGENTS.md
    
    # Must return empty -- no absolute paths
    grep -r "/Users/" .
    

    Check (c) -- README badge counts: Verify the kit README.md badge counts match actual agent and skill counts:

    actual_agents=$(ls <kitRepoPath>/.claude/agents/*.md | wc -l | tr -d ' ')
    actual_skills=$(ls -d <kitRepoPath>/.claude/skills/vc-*/ | wc -l | tr -d ' ')
    readme_agents=$(grep -oE '[0-9]+-Agents' <kitRepoPath>/README.md | grep -oE '[0-9]+')
    readme_skills=$(grep -oE '[0-9]+-Skills' <kitRepoPath>/README.md | grep -oE '[0-9]+')
    echo "Agents: actual=$actual_agents badge=$readme_agents"
    echo "Skills: actual=$actual_skills badge=$readme_skills"
    [ "$actual_agents" = "$readme_agents" ] && [ "$actual_skills" = "$readme_skills" ] && echo "PASS" || echo "FAIL: badge counts mismatch"
    

    If FAIL: update README.md badges to match actual counts before committing.

    NOTE: the brand grep matches product names ONLY. It does NOT match .ck.json/.ckignore -- those Phase-2 legacy-fallback literals are intentional and must NOT be flagged. Do not add ck/ckignore to any leak grep.

    The standing validate-kit-portability.mjs validator (run by vc-audit-vc) mirrors checks (a) and (b) for between-release drift; this Step-8 gate is the publish-time enforcement.

14. If leak detection fails:

    • Print the offending lines (file:line).
    • Revert the changes in the kit repo (git -C <kitRepoPath> checkout .).
    • STOP and report the leak. Do NOT commit or push.

Step 9a: Commit and Tag

15. In the kit repo. If the version was already at the target (skip-bump path from Step 2): use tag-as-is and commit with the existing version number. Otherwise: bump the version in vc-manifest.json and commit with the new version.

cd <kitRepoPath>
git add -A
git commit -m "Release vX.Y.Z"
git tag vX.Y.Z

Step 9b: STOP — Explicit Push Approval (separate from Step 6 confirm)

Leak detection passed. The commit and tag are ready locally. Before running git push, you MUST stop and get explicit user approval:

"Leak detection passed. The commit is ready locally (git log --oneline -1 shows the new commit). Type 'push' to publish to remote, or 'abort' to keep the commit local."

Do NOT run git push or git push --tags until the user types 'push' (or a clear affirmative). This is a separate gate from the publish-confirm at Step 6 — even if the user approved publishing in Step 6, they must re-confirm before the actual remote push.

If the user says 'abort':

• The local commit and tag are preserved.
• Print: "Commit and tag preserved locally. Run git push origin main && git push --tags when ready."
• Stop.

Only on explicit 'push': proceed to Step 10 (git push origin main && git push --tags).

Step 10: Push

16. Push to remote (only after Step 9b approval):

git push origin main && git push --tags

17. If push fails (e.g., rejected, auth error), report the error. The commit and tag are preserved locally for retry.

Step 11: Create GitHub Release

18. After a successful push, create a GitHub Release so watchers are notified and the release appears in the Releases tab:

    gh release create vX.Y.Z \
      --repo <remote-owner>/<remote-repo> \
      --title "vX.Y.Z: <first sentence of release notes>" \
      --notes "<full release notes>"
    

    • If the user provided release notes at Step 6, use them verbatim.
    • If left blank, auto-generate: "N modified, M new, P removed. See commit log for details."
    • The --title one-liner should be the first sentence of the notes (truncate at 72 chars if longer).
    • If gh is unavailable or the push to remote failed, skip this step and note it in the summary.

Step 12: Post-Publish Remote Verify

After a successful push, clone the kit from remote to a temp dir and verify the catalog works on a fresh install:

TS=$(date +%s)
git clone <remote-kit-url> /tmp/vc-kit-verify-$TS
node /tmp/vc-kit-verify-$TS/.claude/skills/vc-context-discovery/scripts/discover-skills.mjs 2>&1
rm -rf /tmp/vc-kit-verify-$TS

Expected: exit 0 and expected skill count in output. If FAIL: note the error in the publish summary — the push succeeded but the remote install may have a catalog issue.

Step 13: Print Summary

19. Print publish summary:

vc-publish complete
===================
Version:       v2.2.0 (was v2.1.0)
Files changed: 4
Remote:        git@github.com:withkynam/vibecode-pro-max-kit.git
Tag:           v2.2.0
Release:       https://github.com/<owner>/<repo>/releases/tag/v2.2.0

Key Changes from v1.0

• Glob arrays are stable; the deprecation ledger is not. The glob patterns in include/exclude/kitOnly are stable — adding a new skill or agent requires zero manifest edits (new files are auto-included by the globs). BUT legacyDeletions is a literal path array, not a glob: it grows every time the harness deprecates a skill/dir/file, and it MUST be reconciled dev→kit at every publish (see Step 7 Manifest reconciliation). Skipping it strands the kit with a stale deletion ledger so downstream vc-updates never clean up the newly deprecated dirs. So publish-time manifest edits are: (1) version bump, (2) legacyDeletions sync, (3) conscious reconciliation of any other field flagged by the drift report.
• Resolver-driven diffing. The kit repo is resolved via resolve-manifest.mjs (which requires vc-manifest.json in its --root). The dev-side file comparison is handled inside compute-sync-plan.mjs, which reads the manifest from --kit-root (always the kit checkout). Dev repos do not carry vc-manifest.json.
• No managed/managedDirs arrays to update. The old workflow of adding new files to these arrays is eliminated.

Rules

• ALWAYS run the full resolver diff (Steps 3-4) even when changes already exist in the kit repo. Direct kit edits (README, translations, community files) do not replace the dev→kit diff. Both change sources must be captured in the same publish.
• NEVER copy project-specific files: process/context/all-context.md (with real content), process/features/*, process/general-plans/* (with real plans)
• ALWAYS verify no project-specific content leaked before committing (Step 8)
• ALWAYS show the diff summary before publishing (Step 5-6)
• NEVER auto-push. git push must be preceded by a separate explicit 'push' confirmation (Step 9b), distinct from the publish-confirm at Step 6. This rule holds even when VC_KIT_SOURCE is a local path.
• CLAUDE.md and AGENTS.md require special handling -- never copy the development repo's project-specific versions directly
• Kit repo checkout path is stored in .vc-publish-config (add to .gitignore)
• The only manifest edit at publish time is the version bump -- glob patterns are stable

Reference

See references/vc-publish.md for the detailed algorithm, CLAUDE.md/AGENTS.md stripping rules, error handling, and example outputs.

Review Situation

Output style: lead with the bottom line, bullets over prose, one-line TL;DR — process/development-protocols/communication-standards.md.

Summarize the current repo state for handoff and resume work.

This is a helper skill only.

• Do use it for read-only branch, worktree, and active-plan summaries.
• Do use it to surface likely selected-plan context when it can be proven or safely hinted.
• Do not use it to choose a plan authoritatively.
• Do not use it to approve execution, resume execution, or mutate repo/process state.

Mode Selection

vc-review-situation operates in two modes. Choose based on the trigger signals below.

Simple Mode (default)

Run review-situation-scan.cjs, return the scan summary.

Use when:

• User asks "what's in flight", "what's next", "give me a handoff summary"
• Quick orientation needed at the start of a session
• Orchestrator needs a branch/plan status check before routing

Output: Current State, Recent Work, In-Flight Plans, Next Steps, Warnings (standard scan sections).

Deep Mode

Run the scan plus read umbrella plan, latest phase report, and all active-plan handoff sections. Synthesize into a full handoff briefing sufficient for an agent to resume without follow-up questions.

Trigger conditions (any one):

• User asks for a full program review: "what are we building", "summarize all active plans", "where are we in the program"
• Session is resuming after a long break or context compaction occurred
• Orchestrator needs a thorough handoff before routing to a phase agent
• Caller explicitly requests deep mode
• Program Review Mode is active — Program Review Mode is Deep Mode

Deep mode steps:

1. Run review-situation-scan.cjs as normal (get branch state + active plan list)
2. If a phase program is active: read the umbrella plan in full — especially ## Current Execution State and ## Phase Ordering
3. Read the most recent phase report in full (if it exists)
4. If 3+ phases are completed: read the Forward Preview sections from earlier phase reports
5. For each active plan: read the ## Resume and Execution Handoff section
6. Synthesize: "You are at Phase N of M. Phase N-1 completed with these outputs. The next phase needs to know: X. These are the open gaps from prior phases: Y."

Output: Full handoff briefing — program position, prior-phase outputs, open gaps, next-phase inputs, and any hard-stop conditions.

Core Contract

vc-review-situation is advisory.

• Evidence comes from git, worktree metadata, and process/* plan inventory.
• Selected-plan awareness is a hint, not a command.
• Next-step recommendations are suggestions, not workflow gates.

If a user needs execution, the repo still requires explicit plan selection and ENTER EXECUTE MODE.

Invocation

Run the local scanner:

node .claude/skills/vc-review-situation/scripts/review-situation-scan.cjs --json

Useful flags:

node .claude/skills/vc-review-situation/scripts/review-situation-scan.cjs
node .claude/skills/vc-review-situation/scripts/review-situation-scan.cjs --json --max-branches 8 --plan-limit 6
node .claude/skills/vc-review-situation/scripts/review-situation-scan.cjs --selected-plan process/general-plans/active/example_27-05-26/example_PLAN_27-05-26.md
node .claude/skills/vc-review-situation/scripts/review-situation-scan.cjs --since "14 days ago"
node .claude/skills/vc-review-situation/scripts/review-situation-scan.cjs --fetch

Input Sources

The scanner reads from:

• git status --short --branch
• git worktree list --porcelain
• local and remote branch refs plus sampled recent commits
• process/general-plans/active/ (plans inside {slug}_{date}/ task subfolders — scan one level deep)
• process/features/*/active/ (same depth)
• optional session-state hints if a local session id is present

It does not scan upstream plans/**, and it never treats a selected-plan hint as execute authority.

Output Shape

The default output is a human-readable report with these sections:

• Current State
• Recent Work
• In-Flight Plans
• Next Steps
• Warnings

--json returns the same information as structured data.

If the scanner fails, say that explicitly and fall back to the minimal read-only commands:

git status --short --branch
git worktree list --porcelain
git for-each-ref --format='%(refname:short) %(committerdate:iso8601) %(objectname:short) %(subject)' refs/heads refs/remotes
find process/general-plans/active process/features -path '*/active/*' -type f | sort

Safety Rules

1. Read-only only. No branch switching, plan edits, or fetch unless --fetch is explicit.
2. Treat selected-plan inference as tentative unless it came from an explicit --selected-plan argument.
3. Remote branch data is stale-by-default unless --fetch is explicit.
4. Use this for session handoff and quick repo orientation, not for workflow control.
5. If the scan cannot prove something, emit a warning instead of guessing.

Good trigger phrases:

• what's in flight
• give me a handoff summary
• what active plans do we have
• show branch and worktree status
• what should I look at next

Load references/review-situation-workflow.md when you need the project's decision tree or hint-priority rules.

Program Review Mode

Program Review Mode = Deep Mode. All trigger conditions and synthesis steps from the Mode Selection — Deep Mode section apply here. The output format below is the required presentation layer for Deep Mode when the orchestrator or user needs a full visual summary before execution.

Trigger: User asks for plan review, program summary, "what are we building", "summarize all active plans"

Goal: Read ALL active plans for a program and produce a comprehensive visual summary for user feedback before execution.

Required output elements

• Macro goal + specific phase goals
• All important decisions made (DECISION / WHY / REJECTED format)
• Expected behaviors being hardened (before/after tables)
• Phase sequence with dependencies (ASCII box diagram using ─ │ ┌ ┐ └ ┘ ├ ┤ ┬ ┴ ┼ ► → characters — NEVER mermaid)
• Per-phase summary: purpose, key items, exit gate, dependencies, risks
• Validate contract status
• Gaps / out-of-scope items
• End with: "Anything to modify before execution?"

Output format rules

• Use ASCII box diagrams (─ │ ┌ ┐ └ ┘ ├ ┤ ┬ ┴ ┼ ► → characters) for phase sequence diagrams and dependency flows — NEVER mermaid (mermaid does not render in terminal)
• Use ASCII/markdown tables for before/after behavior comparisons
• Use numbered decision logs (DECISION / WHY / REJECTED)
• Never omit important details — output is for user feedback before execution
• End with: "Anything to modify before execution?"

Process steps

1. Run standard vc-review-situation check (branch, worktree, active plans list)
2. Identify target program (user-specified feature folder or all active plans)
3. Read ALL plan files in program fully (umbrella + all phase plans)
4. Extract: macro goal, per-phase goals, decisions, behavior changes, validate contract status
5. Produce visual summary using ASCII diagrams + markdown tables
6. Prompt for feedback

Artifact Review Mode

Read and compare process artifacts (plan file + validate-contract, or plan vs git diff) and produce a concise inline summary.

• Plan + validate-contract comparison: Read the plan file and its embedded validate-contract section; render a side-by-side summary of what was planned vs what the contract locked in, flagging gaps or conflicts.
• Plan vs diff view: Read the specified plan file and run git diff [ref] to show what changed; map changed files against the plan's blast-radius, highlighting covered vs uncovered areas.
• File viewer: Read any process artifact (plan, report, validate-contract) and emit a clean inline summary with key decisions, open items, and exit gates — useful before passing context to an execute subagent.
• Output format: ASCII tables and prose only — no Mermaid, no HTML, no server. Output is terminal-friendly and safe to paste into a subagent prompt.
• Trigger phrases: review the plan, show plan vs contract, what did we plan vs what changed, summarize this plan file, diff plan against code

vc-risk-evidence-pack

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Generate and validate the manual-first evidence pack required before finalizing, pushing, or handing off high-risk implementation work.

When To Invoke

• VALIDATE Layer 1 security surface check — when the plan touches a high-risk class, flag the need for an evidence pack before routing to execute-agent.
• EXECUTE before marking high-risk work complete — execute-agent must produce or verify the evidence pack exists before reporting DONE on any high-risk class.
• code-reviewer as pre-PR quality gate — code-reviewer checks for the evidence pack presence before approving changes that touch a high-risk surface.

6 High-Risk Class Definitions

From process/development-protocols/orchestration.md ("High-Risk Execution Handoff") and process/development-protocols/implementation-standards.md ("Risky Work Evidence Contract") — both sources agree:

1. auth or identity — authentication flows, session tokens, user identity resolution, Clerk JWT handling, or any surface that determines who the caller is.
2. billing or credits — billing events, credit balance mutations, Stripe charge flows, OpenRouter credit accounting, credit transaction records, or subscription state changes.
3. schema/data migration or destructive data mutation — Prisma migrations, raw SQL mutations, destructive writes that delete or overwrite persistent data, or schema changes to existing models.
4. public API or external contract changes — tRPC procedure signature changes visible to the frontend, Hono route contract changes consumed by external callers, webhook shape changes, or any API surface that third parties or the client app depend on.
5. deploy/runtime/container/proxy/gateway behavior — Dockerfile changes, supervisord config, start.sh, container service ports, Bun server entry, Hono route registration, Caddy proxy config, worker-node provisioning, or any change that affects how a running service starts or routes traffic.
6. permission, secret, or trust-boundary logic — instance token gating, verifyInstanceOwnership, BYOK secret fetch paths, MITM proxy key injection, Bright Data credential handling, or any logic that controls what a caller is allowed to access.

5-Artifact Schema

Per task-folder artefact colocation, all artifacts go inside the selected plan's task folder (e.g. process/features/{feature}/active/{slug}_{date}/harness/ or process/general-plans/active/{slug}_{date}/harness/), so the whole pack moves with the plan as a unit. Legacy path reports/harness/ is deprecated for new writes; never write the pack to a sibling reports/ dir or any ad-hoc location. The validator script lives at .claude/skills/vc-risk-evidence-pack/scripts/validate-risk-artifacts.mjs.

1. risk-gate.json

Records the risk class, work description, and approver identity before work begins or is finalized.

{
  "riskClass": "<one of the 6 classes above>",
  "workDescription": "<short description of the change>",
  "approver": "<person or agent that reviewed the risk classification>",
  "mustStopBeforeFinalize": true
}

2. context-snippets.json

Relevant code snippets with exact file and line citations for every surface the change touches in the high-risk class.

{
  "snippets": [
    {
      "file": "packages/api/src/router/billing.ts",
      "lines": "120-145",
      "description": "verifyInstanceOwnership call before secret read",
      "content": "<excerpt>"
    }
  ]
}

3. verification.json

Documents every verification step taken and its result. Steps must cover both the happy path and at least one failure or boundary case.

{
  "steps": [
    {
      "step": "<what was verified>",
      "command": "<command run, if applicable>",
      "result": "PASS | FAIL | SKIP",
      "notes": "<observations>"
    }
  ]
}

4. review-decision.json

The explicit reviewer decision record. Must contain APPROVE or REJECT with a written rationale — no implicit approvals.

{
  "reviewer": "<name or agent>",
  "decision": "APPROVE | REJECT",
  "rationale": "<written reason>",
  "timestamp": "<ISO 8601 date>"
}

5. adversarial-validation.json

Required when the path is high-risk or attack-sensitive (e.g. auth bypass, privilege escalation, secret exfiltration). Documents adversarial scenarios considered and whether each was ruled out.

{
  "scenarios": [
    {
      "scenario": "<attack or misuse description>",
      "ruled_out": true,
      "rationale": "<why this path is not exploitable>"
    }
  ]
}

Auto-Stop Rule

If risk is high, do not treat the work as ready to finalize until the evidence pack exists and the reviewer decision is recorded.

If the evidence pack is missing, say so explicitly — do not proceed silently, do not imply the work is proven, and do not report DONE.

Verbatim from implementation-standards.md:

Auto-stop rule:

• if risk is high, do not treat the work as ready to finalize until the evidence pack exists and the reviewer decision is recorded
• if the evidence pack is missing, say so explicitly instead of implying the work is proven

This contract is manual-first and opt-in by risk class. It is not a default blocking hook.

Verbatim from orchestration.md:

If the risk gate says mustStopBeforeFinalize: true, do not imply the work is fully proven until the pack exists and the reviewer decision is present. Keep this manual-first. Do not invent a blocking hook or alternate workflow owner.

Validation Checklist

Steps to confirm each artifact is complete before handoff:

• risk-gate.json populated with correct risk class, work description, approver, and mustStopBeforeFinalize flag
• context-snippets.json includes all affected file:line citations for every surface touching the high-risk class
• verification.json documents each test step and result, covering happy path and at least one boundary/failure case
• review-decision.json has explicit APPROVE or REJECT with written rationale and timestamp — no implicit approvals
• adversarial-validation.json present if the path is attack-sensitive (auth bypass, privilege escalation, secret exfiltration, trust-boundary violation)

High-Risk Work Evidence Contract

Verbatim from process/development-protocols/implementation-standards.md ("Risky Work Evidence Contract"):

For high-risk work, use a manual-first evidence pack before calling the change ready for finalize, push, or human handoff.

High-risk classes include:

• auth or identity flows
• billing, payments, or credit accounting
• schema/data migrations or destructive writes
• public API or external contract changes
• deploy/runtime/container/proxy/gateway behavior
• permission, secret, or trust-boundary logic

Preferred artifact set inside the selected plan's task folder ({slug}_{date}/harness/):

• risk-gate.json
• context-snippets.json
• verification.json
• review-decision.json
• adversarial-validation.json for high-risk or adversarial paths

Auto-stop rule:

• if risk is high, do not treat the work as ready to finalize until the evidence pack exists and the reviewer decision is recorded
• if the evidence pack is missing, say so explicitly instead of implying the work is proven

This contract is manual-first and opt-in by risk class. It is not a default blocking hook.

vc-scenario — Edge Case & Scenario Explorer

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Decompose any feature or code path across 12 dimensions to surface edge cases, risks, and test targets before implementation begins.

Mode Selection

Choose a mode before generating scenarios. Default is Simple unless a trigger condition applies.

Simple Mode (default)

Generates edge cases from the plan description, checklist item, or approach text provided in the prompt. No subagent spawned.

Use when:

• The checklist item is self-contained and clearly described
• Blast radius is narrow (1–2 files, single package)
• No auth, billing, schema, or external API surface is touched
• Speed matters and hypothetical coverage is sufficient

Deep Mode

Spawns a research subagent to read the actual source before generating scenarios. Scenarios reference real variable names, real function signatures, and real failure modes visible in the code rather than hypothetical ones.

Trigger conditions (any one):

• Checklist item modifies an auth, billing, schema, or external API surface
• Blast radius spans 3+ files or 2+ packages
• The plan marks the item as HIGH_RISK
• Caller explicitly requests deep mode

Deep mode subagent steps:

1. Reads the actual source files being modified (from plan Touchpoints)
2. Locates and reads existing test files for those files (via grep for import paths or describe blocks)
3. Reads any Public Contracts affected (from plan's Public Contracts section)
4. Returns: real function signatures, actual data shapes, existing test coverage gaps, real failure modes visible in the code

The orchestrator then generates scenarios using the research output.

Output quality difference

Simple mode surfaces generic edge cases quickly. Deep mode surfaces scenarios that are only discoverable by reading the actual implementation.

When to Use

• Before implementing complex or stateful features
• Before writing tests (generates test targets)
• Risk assessment during planning or code review
• API design review — surface contract edge cases early

When NOT to Use

• Trivial single-line changes or cosmetic UI tweaks
• Already well-tested, stable code with no recent modifications
• Pure configuration changes with no logic paths

12 Decomposition Dimensions

Not all 12 apply to every feature. Identify relevant dimensions first, then generate scenarios only for those.

Workflow

Step 0 — Select mode using the Mode Selection rules above.

Simple mode:

1. Parse feature description or checklist item from the prompt
2. Filter dimensions — mark which of the 12 apply; skip irrelevant ones explicitly
3. Generate 3–5 scenarios per relevant dimension
4. Categorize severity — Critical / High / Medium / Low
5. Output as structured table (see format below)
6. Summarize total scenario count by severity

Deep mode:

1. Spawn research subagent — pass Touchpoints, Public Contracts, and checklist item text
2. Subagent returns real function signatures, data shapes, coverage gaps, visible failure modes
3. Filter dimensions using research output to remove inapplicable ones
4. Generate 3–5 scenarios per relevant dimension, referencing actual variable/function names
5. Categorize severity — Critical / High / Medium / Low
6. Output as structured table annotated with source evidence (file + line where relevant)
7. Summarize total scenario count by severity

Severity Criteria

Output Format

## Scenario Report: [target]

Dimensions analyzed: [list]
Dimensions skipped: [list + reason]

| # | Dimension | Scenario | Severity | Expected Behavior |
|---|-----------|----------|----------|-------------------|
| 1 | Input Extremes | Empty string for required name field | High | Return 400 with field error |
| 2 | Authorization | Expired JWT accessing protected route | Critical | Redirect to login, invalidate session |
| 3 | Timing | Two users submit same form simultaneously | High | Idempotency key or conflict error |

### Summary
- Critical: N
- High: N
- Medium: N
- Low: N
- Total: N scenarios across X dimensions

Integration with Other Skills

Example Invocations

# Simple mode (default — self-contained, narrow blast radius)
/vc-scenario src/api/payment.ts
/vc-scenario "User registration with OAuth providers"
/vc-scenario src/middleware/auth.ts

# Deep mode (auto-triggered: billing surface, 3+ files)
/vc-scenario "Deduct credits on model usage — touches CreditBalance, CreditTransaction, usage-sync.ts"

# Deep mode (explicit request)
/vc-scenario --deep "Add multi-tenancy to the database layer"

Scout

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Fast, token-efficient codebase scouting using parallel agents to find files needed for tasks.

Arguments

• Default: Scout using local shell search plus optional parallel research-agent delegation (./references/internal-scouting.md)
• ext: Scout using external Gemini/OpenCode CLI tools in parallel (./references/external-scouting.md)

When to Use

• Beginning work on feature spanning multiple directories
• User mentions needing to "find", "locate", or "search for" files
• Starting debugging session requiring file relationships understanding
• User asks about project structure or where functionality lives
• Before changes that might affect multiple codebase parts

Quick Start

1. Analyze user prompt to identify search targets
2. Use a wide range of Grep and Glob patterns to find relevant files and estimate scale of the codebase
3. Use local shell search first, then optionally spawn parallel research-agent workers with divided directories when the search space is large
4. Collect results into concise report

Configuration

Read from .claude/.vc.json (falls back to legacy .claude/.ck.json if present):

• gemini.model - Gemini model (default: gemini-3-flash-preview)

Workflow

1. Analyze Task

• Parse user prompt for search targets
• Identify key directories, patterns, file types, lines of code
• Determine optimal SCALE value of subagents to spawn

2. Divide and Conquer

• Split codebase into logical segments per agent
• Assign each agent specific directories or patterns
• Ensure no overlap, maximize coverage

3. Register Scout Tasks

• Parallel task registration and external orchestration patterns are optional, not required for normal scouting in this repo
• See references/task-management-scouting.md only when you are intentionally coordinating a larger parallel scout workflow

4. Spawn Parallel Agents

Load appropriate reference based on decision tree:

• Internal (Default): references/internal-scouting.md (shell search plus optional research-agent parallelism)
• External: references/external-scouting.md (Gemini/OpenCode)

Notes:

• TaskUpdate each task to in_progress before spawning its agent (skip if Task tools unavailable)
• Prompt detailed instructions for each subagent with exact directories or files it should read
• Remember that each subagent has less than 200K tokens of context window
• Amount of subagents to-be-spawned depends on the current system resources available and amount of files to be scanned
• Each subagent must return a detailed summary report to a main agent

5. Collect Results

• Timeout: 3 minutes per agent (skip non-responders)
• TaskUpdate completed tasks; log timed-out agents in report (skip if Task tools unavailable)
• Aggregate findings into single report
• List unresolved questions at end

Report Format

# Scout Report

## Relevant Files
- `path/to/file.ts` - Brief description
- ...

## Unresolved Questions
- Any gaps in findings

References

• references/internal-scouting.md - Using shell search and optional parallel research-agent work
• references/external-scouting.md - Using Gemini/OpenCode CLI
• references/task-management-scouting.md - Optional task-registration patterns for larger scout coordination

vc-security — Security Audit

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Runs a structured STRIDE + OWASP security audit on a given scope. Produces a severity-ranked findings report. With --fix, applies fixes iteratively using the vc-autoresearch guard pattern.

When to Use

• Before a release or major deployment
• After adding auth, payment, or data-handling features
• Periodic security review (monthly/quarterly)
• Compliance check (SOC 2, GDPR, PCI-DSS prep)

When NOT to Use

• Purely cosmetic changes (CSS, copy edits)
• No user-facing code or data handling involved

Modes

Audit Methodology

1. Scope Resolution

Expand the provided glob or full keyword into a file list. Read all in-scope files before analysis.

2. STRIDE Analysis

Evaluate each threat category systematically:

• Spoofing — identity/authentication weaknesses
• Tampering — input validation, integrity controls
• Repudiation — audit logging gaps
• Information Disclosure — data leakage, secret exposure
• Denial of Service — rate limits, resource exhaustion
• Elevation of Privilege — broken access control, RBAC gaps

3. OWASP Top 10 Check

Map findings to OWASP categories (A01–A10). See references/stride-owasp-checklist.md for per-category checks.

4. Dependency Audit

Run the appropriate package audit tool for the detected stack:

• Node.js: pnpm audit
• Python: pip-audit
• Go: govulncheck
• Ruby: bundle audit

5. Secret Detection

Scan for hardcoded API keys, passwords, tokens, and private keys using regex patterns. See references/stride-owasp-checklist.md → Secret Patterns.

6. Finding Categorization

Assign each finding a severity level (see Severity Definitions below).

Output Format

## Security Audit Report

### Summary
- Files scanned: N
- Findings: X critical, Y high, Z medium, W low, V info

### Findings

| # | Severity | Category | File:Line | Description | Fix Recommendation |
|---|----------|----------|-----------|-------------|-------------------|
| 1 | Critical  | Injection | api/users.ts:45 | SQL string concatenation | Use parameterized queries |
| 2 | High      | Auth      | auth/login.ts:12 | No rate limiting | Add express-rate-limit |

Fix Mode (--fix)

When --fix is provided, apply fixes iteratively after the audit:

1. Sort all findings by severity (Critical → High → Medium → Low)
2. For each finding: a. Apply one targeted fix b. Run guard (tests or lint) to verify no regression c. Commit: security(fix-N): <short description> d. Advance to next finding
3. Stop early if guard fails — report the failure instead of proceeding
4. Uses vc-autoresearch guard pattern for regression prevention

Tip: Use --iterations N to cap total fix iterations when scope is large.

Severity Definitions

Integration with Other Skills

• Run after vc-predict when the security persona flags concerns
• Feed Critical/High findings into vc-autoresearch --fix for automated remediation
• Use vc-scenario with --focus authorization for deeper auth flow testing
• Pair with generate-plan / plan-agent to schedule Medium/Low findings as sprint tasks

Example Invocations

# Audit API layer only
/vc-security src/api/**/*.ts

# Audit entire src/ and auto-fix, max 15 iterations
/vc-security src/ --fix --iterations 15

# Full codebase audit (no fix)
/vc-security full

See references/stride-owasp-checklist.md for the detailed per-category checklist and secret detection regex patterns.

Sequential Thinking

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Structured problem-solving via manageable, reflective thought sequences with dynamic adjustment.

When to Apply

• Complex problem decomposition
• Adaptive planning with revision capability
• Analysis needing course correction
• Problems with unclear/emerging scope
• Multi-step solutions requiring context maintenance
• Hypothesis-driven investigation/debugging

Core Process

1. Start with Loose Estimate

Thought 1/5: [Initial analysis]

Adjust dynamically as understanding evolves.

2. Structure Each Thought

• Build on previous context explicitly
• Address one aspect per thought
• State assumptions, uncertainties, realizations
• Signal what next thought should address

3. Apply Dynamic Adjustment

• Expand: More complexity discovered → increase total
• Contract: Simpler than expected → decrease total
• Revise: New insight invalidates previous → mark revision
• Branch: Multiple approaches → explore alternatives

4. Use Revision When Needed

Thought 5/8 [REVISION of Thought 2]: [Corrected understanding]
- Original: [What was stated]
- Why revised: [New insight]
- Impact: [What changes]

5. Branch for Alternatives

Thought 4/7 [BRANCH A from Thought 2]: [Approach A]
Thought 4/7 [BRANCH B from Thought 2]: [Approach B]

Compare explicitly, converge with decision rationale.

6. Generate & Verify Hypotheses

Thought 6/9 [HYPOTHESIS]: [Proposed solution]
Thought 7/9 [VERIFICATION]: [Test results]

Iterate until hypothesis verified.

7. Complete Only When Ready

Mark final: Thought N/N [FINAL]

Complete when:

• Solution verified
• All critical aspects addressed
• Confidence achieved
• No outstanding uncertainties

Application Modes

Explicit: Use visible thought markers when complexity warrants visible reasoning or user requests breakdown.

Implicit: Apply methodology internally for routine problem-solving where thinking aids accuracy without cluttering response.

Scripts (Optional)

Optional scripts for deterministic validation/tracking:

• scripts/process-thought.js - Validate & track thoughts with history
• scripts/format-thought.js - Format for display (box/markdown/simple)

See README.md for usage examples. Use when validation/persistence needed; otherwise apply methodology directly.

References

Load when deeper understanding needed:

• references/core-patterns.md - Revision & branching patterns
• references/examples-api.md - API design example
• references/examples-debug.md - Debugging example
• references/examples-architecture.md - Architecture decision example
• references/advanced-techniques.md - Spiral refinement, hypothesis testing, convergence
• references/advanced-strategies.md - Uncertainty, revision cascades, meta-thinking

VibeCo Agent Harness Setup

CRITICAL — Dual-File Synchronization: This document and references/vc-setup.md must be edited together. Any change to Merge Mode logic, safe-inference rules, or migration flow MUST appear in both files in the same commit. Dual-file drift creates inconsistent user behavior.

Output style: Use BLUF (answer first), plain language, no unexplained jargon, TL;DR on long responses. Full rules in process/development-protocols/communication-standards.md once installed — on first run that file may not exist yet, so follow this inline rule instead.

Interactive setup for the agent development harness. Works on fresh projects and existing projects with pre-existing .claude/ or process/ configs.

The skill adapts its flow based on what it finds:

• New projects (no existing process/ or context): detect, ask the user about their project, scaffold, study, validate.
• Existing projects (has process/, context files, or CLAUDE.md): detect, study what exists first, present findings and ask what to keep vs change, scaffold with approval, re-study to fill gaps, validate.

In both cases, the skill asks questions and waits for approval at every major step. It never silently reorganizes files or overwrites good content.

CLAUDE.md and AGENTS.md are managed protocol files (orchestrator, RIPER-5 methodology, routing). They contain zero project-specific content and should NOT be adapted. Project-specific information lives in process/context/all-context.md, which is populated during the STUDY phase.

Prerequisites

• The target repo should have a project manifest. Detection order:
  1. package.json — Node/Bun/Deno projects (JS/TS)
  2. pyproject.toml or requirements.txt — Python projects
  3. go.mod — Go projects
  4. Gemfile — Ruby projects
  5. Cargo.toml — Rust projects
  6. None found — ask the user: "What language/runtime does this project use? I'll adapt the setup to match."
• That's it. The skill handles the rest.

Workflow

Read references/vc-setup.md for detailed phase instructions, detection heuristics, interactive question templates, parallel subagent delegation strategy, and validation checks.

Phase 0: BOOTSTRAP (handled by install.sh)

The install.sh script handles fetching and installing harness files before vc-setup runs. For existing projects, it backs up old .claude/, .codex/, .agents/ to .vibecode-backup/, then does a clean install of all kit files. User's .claude/settings.json is restored after install.

What install.sh DOES create under process/: process/_seeds/, process/development-protocols/, and process/context/generated-skills-catalog.json. These are kit-installed files, not user content.

What install.sh does NOT create: process/general-plans/, process/features/, process/context/all-context.md, or any context group directories. Those are vc-setup's job, created during the SCAFFOLD and STUDY phases.

If harness files are already present (.claude/agents/ and .claude/skills/ exist with 12+ agents and 20+ skills), skip Phase 0 and proceed directly to Phase 1 DETECT.

If harness files are NOT present, tell the user to run the installer first:

curl -fsSL https://raw.githubusercontent.com/withkynam/vibecode-pro-max-kit/main/install.sh | bash

Then re-run vc-setup.

Phase 1: DETECT

Gather information about the target project before making any changes.

1. Non-JS projects: if the detected manifest is NOT package.json (e.g. go.mod, pyproject.toml, Cargo.toml, Gemfile), SKIP the Package Manager / Framework / Test-Setup detection steps below and jump to Manifest Detection in references/vc-setup.md §DETECT Phase.

2. Read package.json to detect the package manager (packageManager field, lockfile presence), framework (dependencies), and test commands (scripts).

3. Detect monorepo structure: workspaces in package.json, pnpm-workspace.yaml, apps/, packages/ directories.

4. Scan for existing process/, docs/, .github/ directories and any context files.

5. Classify the project as one of:

   • New: no existing process/ directory, no all-context.md, no meaningful prior setup.
   • Existing: has process/, all-context.md, CLAUDE.md with project content, or other prior context.

   Classification corner cases (full 7-row table in references/vc-setup.md §Project Classification):

   • process/ contains ONLY kit-installed files (_seeds/, development-protocols/, context/generated-skills-catalog.json) and no user content → New / Flow A (install.sh ran but the user hasn't set up yet).
   • all-context.md exists but its non-comment body is all placeholder/stub (<!-- STUDY: -->) → Flow A, continue to STUDY (do NOT treat as existing project).

6. Present a detection summary to the user and wait for confirmation before proceeding.

After detection, the workflow branches based on project type. See the two flows below.

Flow A: New Project (no existing process/ or context)

For projects where the harness is being set up for the first time.

Step 1: ASK -- Before scaffolding or scanning anything, have a real conversation with the user about their project. Do not guess when you can ask. Do not ask a fixed list of questions and move on — this is an open-ended discovery conversation that continues until you have a thorough understanding.

Start with the basics, then follow up based on their answers:

Round 1 — Project identity:

• "What is this project? Give me a brief description in your own words."
• "Who uses it? Who is the target audience?"

Round 2 — Architecture and scope (adapt based on Round 1 answers):

• "What are the main product areas or features?"
• "How is the codebase organized? Any key services, packages, or modules I should know about?"
• "What are the most important or complex parts of the codebase?"

Round 3 — Workflow and conventions (adapt based on what you've learned):

• "Do you work solo or with a team?"
• "Any coding conventions, naming patterns, or architectural decisions that are important?"
• "How do you handle testing? CI/CD? Deployments?"
• "Any external services, APIs, or integrations that are central to the project?"

Round 4 — Follow-ups (ask as many as needed until everything is clear):

• Follow up on anything vague or interesting from previous answers.
• "You mentioned [X] — can you tell me more about how that works?"
• "Are there any pain points, tech debt, or things you want agents to be careful about?"
• "Anything else that is important context for working on this codebase?"

Keep asking follow-ups until you genuinely understand the project. If the user gives a short answer, probe deeper. If they mention something complex, ask for details. The goal is that after this conversation, you could explain the project to another developer — what it does, how it's built, what matters, and what to watch out for. Only move on when both you and the user are satisfied.

Step 2: SCAFFOLD -- Create the process/ directory structure from seed templates. (See Phase 2 details below.)

Step 3: STUDY -- Deep-scan the codebase and populate context files with real content, enriched by the user's answers from Step 1. (See Phase 3 details below.)

Step 4: VALIDATE -- Verify everything is wired correctly. (See Phase 4 details below.)

Flow B: Existing Project (has process/, context files, or prior setup)

For projects that already have some form of process/ directory, context files, or CLAUDE.md content.

Step 1: STUDY EXISTING -- Before proposing any changes, read and understand what is already there:

• Read all files under process/context/ (especially all-context.md).
• Read all files under process/general-plans/ and process/features/.
• Read the existing CLAUDE.md if it contains project-specific content (beyond the managed protocol).
• Read any existing all-tests.md, feature _GUIDE.md files, context group entrypoints.
• Build a complete picture of what the user already has.

Step 2: PRESENT and ASK -- Show the user what you found and propose changes. Format:

Here is what I found in your existing setup:

LOOKS GOOD (I recommend keeping these as-is):
- [list files/sections that have good content]

COULD BE IMPROVED (I can update these):
- [list files/sections that are stale, placeholder, or incomplete, with brief reason]

MISSING (I recommend adding these):
- [list files/directories that the harness expects but do not exist yet]

LAYOUT CHANGES (reorganization I would suggest):
- [list any directory moves or renames, if applicable]
- [if none needed, say "Your layout looks standard, no reorganization needed."]

Wait for the user to approve each category. The user may say "keep everything" or "go ahead with improvements" or selectively approve. Respect their choices.

Then have the same discovery conversation as Flow A, regardless of how much existing context you found. Existing context files may be stale, incomplete, or written by someone else. The user's own words are always more valuable than old docs:

• Start with: "I've read your existing context. Let me verify my understanding and fill in the gaps."
• Summarize what you learned from existing files, then ask: "Is this still accurate? What's changed?"
• Ask about anything the existing context doesn't cover (see Flow A Round 1-4 for question areas).
• Follow up on anything unclear. Keep asking until you thoroughly understand the project as it is today.

The combination of existing context + fresh user input produces the best results.

Step 3: SCAFFOLD -- Apply only the changes the user approved. Migrate old layouts if needed (using the migration table). Never touch files the user said to keep. (See Phase 2 details below.)

Step 4: STUDY -- Deep-scan and update/create context with real content. For existing files, merge intelligently -- fill gaps and update stale sections without replacing good user-written content. (See Phase 3 details below.)

Step 5: VALIDATE -- Verify everything is wired correctly. (See Phase 4 details below.)

Phase 2: SCAFFOLD (details)

Create the process/ directory with seed files and instructional content.

1. Determine the scaffold mode:
   • Fresh: no existing process/ directory -- create everything from process/_seeds/.
   • Merge: existing process/ with a different layout -- preserve content, migrate old layout, add missing directories, seed empty folders.
   • Refresh: existing harness process/ -- update protocol docs, seed missing files, preserve user-created content.

For Merge and Refresh modes, show the user what you plan to change before doing it. List every file you will create, move, or overwrite. Wait for approval.

Merge mode includes automatic layout migration. Before creating new directories, detect and migrate old layouts:

Merge Mode auto-migrate flow (orphaned-dir detection → display → confirm → execute)

When run on an existing project (Flow B), Merge Mode detects orphaned legacy dirs and offers a one-step migration:

1. Detect orphaned dirs: scan for process/reports/, process/references/, and any feature-level process/features/*/reports/, process/features/*/references/ sibling dirs (plus pre-v3 process/plans/, process/skills/, process/_seeds/ leftovers).
2. Display a migration summary table to the user — each row: source path, inferred destination task folder, file count, risk level (safe vs needs-review).
3. Confirm — present one-button confirmation: "Migrate and clean up all stale artifacts". The user approves under the LAYOUT CHANGES section before any move executes. vc-setup never moves files silently.
4. Execute — move safe artifacts into the inferred completed/{slug}_{date}/ (or active/{slug}_{date}/) task folder, then delete the now-empty source dir. Print a result summary ("moved X files, deleted Y dirs").

Safe-Inference Rules for Pre-Create

• Safe — a plan slug exists in process/general-plans/active/ or process/features/{feature}/active/ and exactly one matching {slug}_{date}/ task folder can be inferred → auto-create completed/{slug}_{date}/ as the destination and migrate the artifact.
• NOT safe — no matching plan slug is found, filenames are ambiguous, multiple task folders match, or there is a conflict with an existing dir → do NOT create any destination folder; show the fallback message below and pause for manual review.

Fallback Display Message

When orphaned dirs are detected but no plan slug can be inferred from project files (no safe inference possible), vc-setup displays:

"Found orphaned dir [path] but cannot safely infer destination task folder. Manual migration required. See reference docs for migration guide."

vc-setup will NOT auto-create ghost folders (false folders) when inference fails. The user must review and manually place the files. Conservative behavior: when in doubt, leave the artifact in place and surface it — never guess a destination.

Migration rules:

• Never overwrite existing files at the destination. If a file with the same name exists, keep both (rename the migrated copy with a -migrated suffix).
• Print every move action to the user so they can verify.
• After all moves, remove empty source directories.
• If process/plans/ contains files matching date-based patterns (e.g., 2026-05-22-*.md, *_PLAN_*.md), classify completed plans (look for "COMPLETE" or "DONE" in the file) and move them to completed/ instead of active/.
• Safe legacy artifact migration contract: for legacy reports/ / references/ sibling dirs, move an artifact automatically only when exactly one destination task folder can be inferred in the same scope (process/general-plans/ or one process/features/{feature}/). Safe inference signals are:
  • the artifact basename already starts with one task slug and only one matching {slug}_{date}/ folder exists
  • the artifact path or basename contains an exact {slug}_{date} token matching one task folder
  • there is exactly one task folder total in that scope
  • exactly one task-folder plan references the legacy artifact path or basename
• Treat an artifact as unsafe and leave it in place when multiple task folders match, when multiple plans reference it, when it is clearly cross-task/shared, or when no task folder exists yet in that scope.
• Preserve the original filename by default when moving legacy artifacts. Only add a -migrated suffix when the destination already has a same-name file.
• After migrating all safe artifacts from a legacy sibling reports/ or references/ dir, delete that dir if and only if it is empty. The target end-state is that each feature folder and process/general-plans/ keep only active/, completed/, and backlog/ unless unresolved legacy artifacts still block cleanup.

Seed and template handling:

1. Seeds live in process/_seeds/ (read-only during setup -- never modified by the scaffold process):
   • Files with .seed extension: copy with .seed removed, replace {{project_name}} with the detected project name.
   • Files without .seed extension: copy verbatim.
   • Context group seed folders use -seed suffix (e.g., tests-seed/, planning-seed/). When copying to real locations, drop the -seed suffix.
2. Copy development protocol docs from process/development-protocols/ (these are managed system files, not seeds -- they live in the real directory, not _seeds/).
3. Place _GUIDE.md files in empty process folders to explain what goes there.
4. Retain .seed originals alongside populated files: after copying and filling seed files, also copy the original .seed files to the target process/ directory as structural reference companions. These .seed files serve as reference for what sections are expected, and future vc-update can diff against them to detect structural drift.
5. Use _all-group-template.md.seed as the base when creating new context group entrypoints during the STUDY phase.
6. Use _feature-template/_GUIDE.md.seed as the base when creating new feature folder guides during the STUDY phase. The _feature-template/ includes 3 subdirectories (active/, completed/, backlog/) with their own _GUIDE.md files. Do NOT create reports/ or references/ sibling dirs for new repos — these are deprecated; new artifacts go inside task folders under active/ or completed/.
7. See references/vc-setup.md for the full target directory tree and placeholder list.

After scaffolding, show a summary of what was created/changed. Example: "Created 12 directories, 8 seed files, 6 protocol docs. No existing files were modified."

Phase 3: STUDY

Perform deep codebase analysis and populate context files with real, researched content.

This is the core value -- instead of leaving placeholder text, the STUDY phase actively reads the codebase and writes ready-to-use context.

1. Architecture and stack analysis: Scan source directories, detect frameworks with versions, map import aliases, catalog environment variables, identify key patterns and conventions.
2. Test setup analysis: Identify test runners, config files, test directories, and test commands per package/workspace.
3. Context group detection and per-group file authoring: Invoke the vc-generate-context skill in setup-delegation mode. Pass: (a) the approved-groups list from the context-group-detector subagent (Round 1 Subagent C), and (b) mode = setup-delegation. This skill will produce all process/context/{group}/all-{group}.md files for the approved groups. See .claude/skills/vc-generate-context/SKILL.md for the Invocation Modes reference and .claude/skills/vc-generate-context/references/generate-context.md for the detection table and per-mode instructions.
4. Feature area detection: Identify major product areas from route groups, packages, and existing docs. Create feature folders for areas meeting the threshold (3+ source files, distinct product area).
5. Populate all-context.md: Write real repository structure, technology stack details, key patterns, environment configuration, and routing tables -- not placeholders. Incorporate what the user told you in the ASK step. Note: per-group context-file authoring (process/context/{group}/all-{group}.md) is delegated to vc-generate-context (step 3 above); all-context.md itself is Subagent E's responsibility and is authored here in vc-setup.
6. Populate all-tests.md: Write actual test runner names, real test commands, and per-package breakdowns.
7. Migration intelligence (when existing process/ content is found): Read existing content, identify gaps vs fresh scan, fill only gaps while preserving user-written content.

For existing projects (Flow B): Before writing, compare your scan results against existing content. If the existing content is more detailed than what you scanned, keep it. Only replace placeholder or stale sections. Add missing sections with scanned data. Never silently overwrite good content.

After the STUDY phase, show a summary of what was populated. Example: "Populated all-context.md (8 sections with real content), all-tests.md (3 test runners, 12 commands), created 2 context groups (database/, container/), created 3 feature folders."

See references/vc-setup.md for the full STUDY phase checklist, parallel subagent delegation strategy, context group detection table, and feature detection heuristics.

Phase 4: VALIDATE

Verify the setup is complete, correct, and populated with real content.

1. Check all expected directories exist under process/.

2. Verify agent parity: agent names in .claude/agents/ should match .codex/agents/.

3. Check that .agents/skills symlink exists and resolves.

4. Verify STUDY phase output quality:

   • all-context.md has no remaining {{placeholder}} text (except {{project_name}} if seed was just created)
   • all-context.md has a populated Repository Structure section with real directory tree
   • all-context.md has a populated Technology Stack section with specific versions
   • all-tests.md has actual test commands (not placeholder text)
   • Context groups created have corresponding entries in the routing tables
   • Feature folders created have _GUIDE.md files with real scope descriptions

5. Placeholder scan (required): grep the populated all-*.md context files for remaining <!-- STUDY: or (pending markers. If any remain, STUDY is incomplete — return to STUDY and populate them before declaring VALIDATE done.

   grep -rn -e '<!-- STUDY:' -e '(pending' process/context/ && echo 'INCOMPLETE — populate before VALIDATE'
   

   A zero-match exit (no output, exit 1 from grep) means the scan is clean and VALIDATE may proceed.

6. Catalog generate-on-install safety check: If process/context/generated-skills-catalog.json is absent after setup, generate it now:

   node .claude/skills/vc-audit-context/scripts/generate-skills-catalog.mjs --write
   

   This file is required for discover-skills.mjs (Routing Step 0) to work correctly. Fresh installs that copy this file from the kit manifest include do not need this step, but if the file is missing for any reason (missing manifest include, partial install), generate it explicitly. Note: generate-skills-catalog.mjs (and its shared utils) works on non-git projects — it falls back to process.cwd() when git rev-parse is unavailable.

7. Report any issues found.

8. Suggest running validation scripts if they exist in the target repo:

   • node .claude/skills/vc-generate-context/scripts/validate-all-context.mjs
   • node .claude/skills/vc-audit-context/scripts/validate-context-discovery.mjs

   Validator cwd discipline: Run every validator from the project root: cd {project_root} && node .claude/skills/.... The scripts resolve the project via git rev-parse --show-toplevel; running from a parent directory resolves the wrong root and produces misleading results.

   Expected validator warnings on fresh projects: validate-context-discovery.mjs may report missing context group directories such as process/context/uxui/ (if project has UI/UX context group) or other groups. This is EXPECTED for projects that do not have content in those domains — do not create empty group directories just to silence the warning. Create a context group only when the project genuinely has substantial content for that domain (see Context Group Detection Table in the STUDY phase).

Present the final summary to the user: what was set up, what is ready to use, and recommended next steps (review context, start using the harness).

Interaction Principles

These principles apply throughout the entire setup flow:

• Never reorganize without asking. Show what you found, propose changes, wait for approval.
• Study before scaffold for existing projects. Understand what is already there before proposing changes.
• Have a real conversation, not a checklist. Do not ask a fixed list of questions and move on. Ask, listen, follow up, ask more. If an answer is vague, probe deeper. If the user mentions something interesting, explore it. Continue until you genuinely understand the project — what it does, how it's built, what matters, and what to watch out for.
• Show summaries at each step. After DETECT, show findings. After ASK, summarize your understanding and confirm it's correct. After SCAFFOLD, show what was created. After STUDY, show what was populated.
• Preserve the user's existing good content. If they have a well-written CLAUDE.md, detailed context files, or a working process/ layout, merge intelligently -- do not replace with generic scans.
• One step at a time. Complete each phase, show the result, and get confirmation before moving to the next phase.
• Verify your understanding before acting. After the discovery conversation, summarize what you learned back to the user: "Here's what I understand about your project: [summary]. Is this accurate? Anything I'm missing?" Only proceed when they confirm.

Rules

• CLAUDE.md and AGENTS.md are managed protocol files. Do NOT adapt or modify them.
• Do not modify RIPER-5 methodology sections, phase transition rules, or key principles.
• Do not modify tool restriction lists in agent prompts.
• Do not modify the status reporting format (DONE, DONE_WITH_CONCERNS, BLOCKED, NEEDS_CONTEXT).
• Always wait for user confirmation after the DETECT phase before making changes.
• Always ask the user about their project before populating context files. Do not rely solely on code scans.
• In Merge mode, never overwrite existing user content.
• In Flow B (existing projects), always present what you found and get approval before modifying anything.
• Project-specific information (tech stack, features, conventions) belongs in process/context/all-context.md, not in CLAUDE.md.
• In STUDY phase, write real researched content, not placeholder text. Every section should contain actual project-specific information discovered by scanning the codebase AND informed by the user's answers.
• For large repos (monorepos, 5+ source directories), spawn parallel subagents to maximize throughput and avoid context window exhaustion -- see reference doc for delegation strategy.

vc-test-coverage-plan

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Generate a TDD-first full test plan per blast radius area. Assigns all 4 test tiers with exact commands, what each proves, what it does NOT prove, and explicit resolution options for every gap.

Boundary vs vc-feasibility-test

This skill is POST-decision: the design is already chosen and you are assigning coverage tiers across a known blast radius. If instead an approach cannot be decided because a runtime/library/external mechanism is unverified — that is a PRE-decision question and belongs to vc-feasibility-test (a one-shot empirical probe producing a VIABLE/NOT-VIABLE/INCONCLUSIVE VERDICT), run before SPEC/INNOVATE locks. Do not use test tiers to answer "does this mechanism work at all?".

When To Invoke

• PLAN phase — populate the Verification Evidence section of a new plan
• VALIDATE Section III — generate the full test plan after V2 fan-out, before writing the validate-contract
• EXECUTE phase — as test gates at the end of each plan section and as a regression suite after all sections complete

Context Discovery (MANDATORY FIRST — do this before anything else)

This skill MUST NOT infer tiers, commands, or runners from training data. Before reading the plan or naming a single area:

1. Invoke vc-context-discovery to load the relevant context group files.
2. Read process/context/tests/all-tests.md and follow its downstream routing chain to the relevant deeper test docs (tests/container-e2e.md, tests/browser-automation.md, tests/live-e2e.md, etc.). The entry point is a router, not full knowledge — reading only the router and skipping the chain is insufficient.
3. Discover the existing test files inside the blast radius (real runners + real commands + real fixtures — not guesses).

Hard stop (mirrors vc-plan-agent TIER_ASSIGNMENTS_BLOCKED): if the all-tests.md routing chain was not loaded, or existing blast-radius test files were not discovered, STOP and emit TIER_ASSIGNMENTS_BLOCKED — report BLOCKED with "Test context chain not loaded; returning to RESEARCH to load all-tests.md and discover existing test files. Do not generate tier assignments from training data." Do NOT proceed to the waterfall. Every Command / Steps cell below must be an exact command sourced from the loaded test context, never an inferred placeholder.

Test Tier Decision Waterfall

For each area in the plan's blast radius, assign a tier using this waterfall:

1. Fully-automated — if a deterministic command exists that exercises the area end-to-end without human judgment. Must be runnable in CI without setup beyond env vars. Examples: pnpm test, bun test, node validate-script.mjs, grep checks.

2. Hybrid — if the test requires a precondition (running container, live DB, specific env) that is not always available in CI, but the test itself is deterministic once set up. Record the precondition explicitly. Examples: container E2E tests, DB migration checks.

3. Agent probe — if the area requires judgment that cannot be mechanically asserted. Describe the probe scenario and what the agent should judge. Examples: UI visual regression, prose quality, API response plausibility.

4. Known gap — if no test exists and none can be added within the blast radius of this plan. Document the gap explicitly. Do not use this tier to avoid writing tests.

High-Risk Classes

These classes always require at least a hybrid test gate (no known-gap allowed without explicit documented rationale):

• auth or identity flows
• billing, payments, or credit accounting
• schema/data migrations or destructive writes
• public API or external contract changes
• deploy/runtime/container/proxy/gateway behavior
• permission, secret, or trust-boundary logic

Required table format for high-risk class areas:

Hybrid Failure Resolution Priority

When a hybrid test fails during or after EXECUTE:

1. Fix now — if the failure is in the blast radius of the current plan and the fix is small. Fix, re-run the hybrid gate, confirm green, then continue.
2. New phase plan — if the failure requires work that is outside the current phase scope but has a clear fix. Create a follow-up phase plan and document the gap.
3. Update existing phases — if the failure is in a phase that is still active and the fix can be absorbed without scope expansion. Route the fix back to that phase.
4. Backlog note — if the failure is in a known-gap area, the fix is non-trivial, and deferral is acceptable. Write a backlog artifact. Do not silently absorb it.

Per-Area Test Plan Output Format

Produce one block per area in the blast radius. Area = package, service, or logical surface (e.g. packages/api — new route, packages/ui — UI component).

Area: [package/service name]

Rules:

• Include a row for every tier that applies. Omit a tier row only if the tier genuinely does not apply — do not omit to avoid work.
• Known-gap rows must have — in the Command/Steps column and a brief reason in the "What it does NOT prove" column.
• Fully-automated commands must be exact and runnable — do not use placeholder [command] in a real output.

Gap Resolution Options Format

After the per-area table, list every gap with four resolution choices:

Resolution option rules:

• A — Write new test: state file location and estimated effort (e.g. "30 min, new file packages/api/src/__tests__/route-shape.test.ts").
• B — Set up infra: name what infra is needed and how (e.g. "seed DB fixture via pnpm db:seed:test").
• C — Accept as known-gap: rationale is required — never blank. High-risk class gaps need especially strong rationale.
• D — Backlog artifact: state what to create and where (e.g. "prod-migration-smoke-test_NOTE_[date].md in process/features/development-process/backlog/").

Missing Test Areas Format

Areas with no coverage possible at any tier within this plan's scope:

Execution Protocol

0. Run Context Discovery (MANDATORY FIRST) above — load the all-tests.md routing chain and discover existing blast-radius test files. If not loaded, emit TIER_ASSIGNMENTS_BLOCKED and STOP; do not continue.
1. Read the plan file at the provided path (or parse the blast radius description if no path given).
2. Extract the blast radius areas from the plan + the loaded test context — never infer commands/runners from training data.
3. For each area, run the Test Tier Decision Waterfall.
4. Flag any area that matches a High-Risk Class — enforce hybrid minimum.
5. Produce the per-area test plan block (5-column table + gap resolution table).
6. Produce the missing test areas table.
7. If invoked during VALIDATE (Section III), embed output directly into the validate menu under "III. Test Coverage Plan" — do not write a separate file.
8. If invoked during PLAN or EXECUTE, output directly in chat for the caller to copy into the plan file.

TDD Stub Output Requirement

For every Fully-automated tier row in the per-area output table, append immediately after that row's 5-column entry an inline failing test skeleton in plain text:

Failing stub:
test("should [behavior from Scenario column]", () => {
  throw new Error("NOT IMPLEMENTED — TDD stub for: [behavior]")
})

Rules for the stub:

• The stub is destined for the validate-contract's Test Gates section, to be consumed by execute-agent as the red-first starting point (Mode A hard gate). It is NOT an on-disk .test.ts file — do not write it to disk during VALIDATE or PLAN phase.
• The stub content must match the Scenario cell verbatim so execute-agent can find it by scenario name.
• Hybrid / Agent-Probe / Known-Gap tiers do NOT receive stubs. A literal red E2E or container test is too costly to mandate; hybrid stubs are advisory only.

Clarification note: vc-test-coverage-plan retains its exhaustive behavior-inventory framing — "each row is a behavior to COVER, not a test to write upfront." The stubs make the coverage intent machine-executable at EXECUTE time, not upfront test implementation. The four tier words (Fully-automated / Hybrid / Agent-Probe / Known-Gap) remain verbatim; this requirement is additive to the per-area output format.

Absorption Note

This skill absorbs vc-test-tier-selector if that skill existed. If vc-test-tier-selector still exists on disk as a separate folder under .claude/skills/, treat this skill as its canonical replacement and note the duplication in the phase report. Do not route new work to vc-test-tier-selector.

vc-update

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Pull the latest agent harness improvements from the remote vibecode-pro-max-kit repository into the current project.

When to Use

• After being told a new harness version is available
• Periodically to check for updates
• After bootstrapping a project with vc-setup and wanting the latest improvements

Workflow

Follow these steps exactly. Do NOT skip the dry-run or confirmation step.

Step 1: Check Worktree Status

Run git status --porcelain in the project root.

• If output is non-empty: warn the user that they have uncommitted changes and suggest git stash or committing first. Do not block -- continue after warning.
• If output is empty: proceed silently.

Step 2: Read Current Version

Read the file .vc-version in the project root.

• If it exists: store its contents as currentVersion (a semver string like 2.0.4).
• If it does not exist: set currentVersion to "0.0.0" (treat as first update).

Step 3: Clone Remote Repository

# Respect VC_KIT_SOURCE override (local path or alternate URL).
# When unset, defaults to the official remote.
KIT_SOURCE="${VC_KIT_SOURCE:-https://github.com/withkynam/vibecode-pro-max-kit.git}"
VC_UPDATE_TMPDIR="/tmp/vc-update-$(date +%s)"
git clone --local --depth 1 --quiet "$KIT_SOURCE" "$VC_UPDATE_TMPDIR" 2>/dev/null \
  || git clone --depth 1 --quiet "$KIT_SOURCE" "$VC_UPDATE_TMPDIR"
# Note: --local is a no-op for remote URLs (git ignores it); the fallback covers all cases.

VC_KIT_SOURCE — if set, use this path or URL instead of the official remote. Accepts any value accepted by git clone. This enables offline testing (VC_KIT_SOURCE=/path/to/local/kit) and forks/pinned versions.

If the clone fails (network error, auth error, repo not found):

• Print the error message.
• Clean up the temp directory if it was partially created.
• Stop. Do not proceed.

Step 4: Resolve Remote Manifest

Run the resolver script from the cloned repo:

node "$VC_UPDATE_TMPDIR/resolve-manifest.mjs" --root "$VC_UPDATE_TMPDIR" --json

Parse the JSON output to extract:

• files (string[]) -- resolved managed file paths
• merge (string[]) -- files where user customizations are preserved (not overwritten)
• copyIfMissing (string[]) -- files only installed if they don't already exist locally
• strip (string[]) -- files needing content stripping (informational)
• symlinks (object) -- symlink path -> target mappings
• legacyDeletions (string[]) -- paths to delete on migration (present in kit v3.0.0+; absent in older kits)

Extract the remote version from the manifest:

node -e "console.log(JSON.parse(require('fs').readFileSync('$VC_UPDATE_TMPDIR/vc-manifest.json','utf8')).version)"

Retain Step 4 output through Step 7: Keep the full resolver JSON (especially symlinks) in memory. compute-sync-plan.mjs --json (Steps 6/10) does not re-emit symlinks, so Step 7 depends on the Step 4 value.

Legacy fallback: If resolve-manifest.mjs does not exist in the remote (very old kit version), fall back to reading vc-manifest.json directly and using the old managed/managedDirs/seedsDir fields for file resolution.

Step 5: Compare Versions

Compare the remote manifest version against currentVersion.

• If they are equal: do NOT stop yet. Version equality means the deterministic file-sync will be a no-op, but the ADAPTIVE legacy-layout migration (Part D) is NOT version-gated and may still have work to do — e.g. an old project was just brought to the current version by install.sh (which writes .vc-version but cannot run the adaptive migration), leaving legacy-format dirs un-migrated. So on equal versions, run the legacy-artifact scan before deciding:
  • Scan for any of: flat *_PLAN_*.md files directly under process/general-plans/active/ or process/features/*/active/; sibling process/general-plans/{reports,references}/; sibling process/features/*/{reports,references}/; process/development-protocols/references/ (any non-empty legacy layout dir in scope per Part D).
  • If the scan finds ZERO legacy artifacts: report "Already up to date (vX.Y.Z) — no legacy artifacts to migrate", clean up $TMPDIR, and Stop.
  • If the scan finds ANY legacy artifacts: report "Already up to date (vX.Y.Z), but N legacy artifact(s) found — running content migration" and CONTINUE to the diff/apply path. The file diff will be empty (no add/modify/delete), but Part D safe legacy-layout migration MUST run so the legacy content is moved into task folders. Skip the version-bump messaging; the version stays the same.
• If remote is newer (or currentVersion is 0.0.0): continue to diff.
• If remote is older than currentVersion: print ⚠ WARNING: downgrade v{remoteVersion} → v{currentVersion} detected. The source kit is older than your installed version. Continuing will overwrite newer harness files with older ones. then ask for explicit confirmation before continuing. If the user does not confirm, clean up $VC_UPDATE_TMPDIR and stop.

Step 6: Read Local Snapshot and Compute Diff

Computation via compute-sync-plan.mjs: Once the remote manifest is resolved (Step 4), invoke the shared computation core:

node "$VC_UPDATE_TMPDIR/compute-sync-plan.mjs" \
  --root "$PROJECT_ROOT" \
  --kit-root "$VC_UPDATE_TMPDIR" \
  --json

Parse the JSON output: { toAdd, toModify, toDelete, toPreserve, staleWarnings }.

• toAdd — files to copy from kit to project (not yet present or tracked).
• toModify — files to overwrite (tracked, present, content differs).
• toDelete — stale kit files to remove (in old snapshot, not in new ownedPaths, passed namespace guard).
• toPreserve — files to leave untouched (merge/copyIfMissing survivors, user-owned files).
• staleWarnings — paths that were in snapshot but failed namespace guard — print to user; do NOT delete.

The manual snapshot-reading and diff logic in the previous version of this step is replaced by this invocation. The prose description of the algorithm is preserved in references/vc-update.md for reference.

Fallback — no .vc-installed-files (first update with new system): When the snapshot file is absent, compute-sync-plan.mjs sets priorSnapshot = [] (empty — no disk scan). No stale removal occurs via the snapshot path because there are no prior entries to compare against. legacyDeletions from the manifest are still applied independently (step 4 in the function) and may delete old paths that exist on disk. .vc-installed-files is written only when --apply is passed, not during a --json dry-run.

Merge files (e.g. .claude/settings.json): files in the merge list that exist locally are placed in toPreserve by compute-sync-plan.mjs — they are never overwritten. Show the diff for manual review, flag for manual review.

Copy-if-missing files: files in the copyIfMissing list that already exist locally are also placed in toPreserve. Show the diff but note they will NOT be overwritten.

Step 7: Check Symlinks

For each entry in the symlinks object (key = symlink path, value = target):

• If the symlink exists and points to the correct target: mark as ok.
• If the symlink is missing or points to a different target: mark as will fix.
• If a real directory exists at the symlink path (not a symlink): mark as will replace dir with symlink.

Step 8: Print Dry-Run Summary

Print a summary with all collected results. Format:

vc-update dry run: v{currentVersion} -> v{remoteVersion}

FILES:
  [modified]  .claude/agents/vc-execute-agent.md  (+12 -3)
  [new]       .claude/hooks/lib/new-util.cjs
  [removed]   .claude/skills/deprecated-skill/SKILL.md
  [unchanged] .claude/agents/vc-debugger.md
  ...

MERGE (preserved, manual review needed):
  [differs]   .claude/settings.json  (+2 -1)

COPY-IF-MISSING (skipped, already present):
  (none)

SYMLINKS:
  [ok]        .agents/skills -> ../.claude/skills
  [will fix]  .codex/hooks -> ../.claude/hooks

STALE WARNINGS: N paths failed the namespace guard (showing first 5 — see full compute-sync-plan output)
  .claude/skills/my-custom-vc-tool/SKILL.md
  ...

Summary: 5 modified, 2 new, 1 removal, 1 merge skipped, 45 unchanged

If staleWarnings is empty, omit the STALE WARNINGS section entirely. If non-empty, print the count and the first 5 entries only — do not dump all paths. Stale warnings indicate vc-namespace paths in your prior snapshot that are not in the kit's known ownedPaths. If you have a custom vc-* skill at one of those paths, rename it before applying the update to prevent it from being deleted as a stale kit artifact.

Also print a LAYOUT MIGRATION section when legacy process artifacts are found:

• Scan for flat *_PLAN_*.md files directly under process/general-plans/active/ and process/features/*/active/.
• Scan for sibling process/general-plans/reports/, process/general-plans/references/, and process/features/*/reports|references/.
• Classify each discovered item as either:
  • safe move — exactly one destination task folder can be inferred in the same scope
  • needs review — ambiguous, shared, or no task folder exists yet
• Print the count of safe move items that will be migrated on apply and the count of unresolved needs review items that will stay in place.

Large-delete WARNING: After computing the dry-run summary, check toDelete.length. If it exceeds 20 files OR exceeds 10% of the prior install file count (line count of .vc-installed-files), print the following block prominently before asking for confirmation:

⚠ WARNING: {N} files scheduled for removal — unusually high.
Verify this is an expected upgrade before applying.
Do NOT blindly approve when this warning appears.

Do not suppress this warning or fold it into the summary line. It must appear as a standalone block so the user cannot miss it.

Step 9: Wait for Confirmation

STOP HERE. Tell the user:

"This is a dry-run summary. Type apply to proceed with the update and safe layout migration, or abort to cancel. The temp clone will be cleaned up either way."

Do NOT proceed until the user explicitly says "apply" (or a clear affirmative like "yes", "go", "do it").

If the user aborts:

• Remove $VC_UPDATE_TMPDIR.
• Print "Update cancelled. No changes made."
• Stop.

Step 10: Apply Changes

On user confirmation, run in two parts:

Isolation guarantee (Parts A/B): $VC_UPDATE_TMPDIR is a read-only clone — no changes are made to it between calls. The project root is also not mutated before Part B runs. Both invocations therefore see the same sync plan, so the backup in Part A covers the exact set that Part B will overwrite.

Part A — Back up files that will be modified or deleted (toModify + toDelete lists):

Before applying, back up every file in toModify AND every file in toDelete so both overwritten content and deleted files are recoverable:

node "$VC_UPDATE_TMPDIR/compute-sync-plan.mjs" \
  --root "$PROJECT_ROOT" \
  --kit-root "$VC_UPDATE_TMPDIR" \
  --json | PROJECT_ROOT="$PROJECT_ROOT" node -e "
    const plan = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));
    const fs = require('fs'), path = require('path');
    const root = process.env.PROJECT_ROOT;
    const backupDir = path.join(root, '.vibecode-backup');
    // Rotate any prior backup so re-runs never silently overwrite it
    if (fs.existsSync(backupDir) && fs.readdirSync(backupDir).length > 0) {
      const rotated = path.join(root, '.vibecode-backup-' + Math.floor(Date.now() / 1000));
      fs.renameSync(backupDir, rotated);
      console.log('Existing backup rotated to ' + path.relative(root, rotated) + '/');
    }
    for (const rel of [...plan.toModify, ...plan.toDelete]) {
      const src = path.join(root, rel);
      if (!fs.existsSync(src)) continue;
      const dst = path.join(backupDir, rel);
      const stat = fs.statSync(src);
      if (stat.isDirectory()) {
        fs.cpSync(src, dst, { recursive: true });
      } else {
        fs.mkdirSync(path.dirname(dst), { recursive: true });
        fs.copyFileSync(src, dst);
      }
    }
  "
# Note: this backup step assumes a POSIX shell. On Windows, skip or adapt it — /dev/stdin is unavailable.

(This preserves the pre-update versions of both overwritten and removed files, so any content is recoverable from .vibecode-backup/. If a .vibecode-backup/ directory already exists from a prior run, it is rotated to a timestamped name (.vibecode-backup-{unix-ts}/) before the new backup is written, so earlier backups are never overwritten.)

Part B — Apply the full plan with the single mechanical command:

node "$VC_UPDATE_TMPDIR/compute-sync-plan.mjs" \
  --root "$PROJECT_ROOT" \
  --kit-root "$VC_UPDATE_TMPDIR" \
  --resolver "$VC_UPDATE_TMPDIR/resolve-manifest.mjs" \
  --apply

--apply deterministically executes the computed plan:

• toAdd / toModify: mkdir -p parent + copy from kit to project. toPreserve entries (merge/copyIfMissing survivors) are never touched.
• toDelete: each entry is removed — directories via rmSync({recursive:true,force:true}), files via rmSync({force:true}).
• Empty-parent sweep: after all deletions, every ancestor directory of every deleted path is walked deepest-first and rmdirSync'd if empty. This is the guaranteed cleanup that prevents hollow deprecated skill dirs (e.g. empty references/, scripts/ subdirs) from surviving after a skill is removed.
• Snapshot: writes .vc-installed-files (sorted managedFiles — the files list from resolve-manifest; legacyDeletions are re-derived each run and not persisted).
• Version: writes .vc-version (manifest version string).
• .gitignore guard: after writing the version, apply ensures the project-root .gitignore contains .vibecode-backup*/ (additive — creates the file if absent, appends the glob form .vibecode-backup*/ if the glob form is missing even if a non-glob .vibecode-backup/ line already exists, no-ops if the glob form is already present). This prevents rotated backup dirs (.vibecode-backup-{ts}/) from being accidentally committed.
• staleWarnings (Type 1 — non-vc- namespace): paths in the prior snapshot that are not in the vc- namespace — moved to toPreserve, never deleted. Message form: 'X' in prior snapshot but not in kit namespace — preserved (verify manually).
• staleWarnings (Type 2 — vc- namespace, WARNING: prefix): vc- namespace paths that are in toDelete but not in the known ownedPaths/legacyDeletions — these ARE deleted. The warning is advisory: if the user has a custom vc- skill at that path, rename it before updating.

Do NOT hand-loop rm or cp commands — use only the --apply invocation above. The mechanical implementation guarantees correct empty-dir cleanup on every run, including directory-shaped deletions and deeply nested deprecated skill subdirs.

Part C — Symlinks (handled separately, unchanged):

For each entry in symlinks:

• If a real directory exists at the path: rm -rf it first.
• If a wrong symlink exists: rm it first.
• Create the symlink: ln -s {target} {path}

Part D — Safe legacy layout migration:

Sequencing — safe-migration (Part D) RUNS BEFORE legacyDeletions are applied. This ordering ensures user report/reference content is moved into task folders before the deprecated layout dirs (e.g. process/general-plans/reports, process/_seeds/.../references) are removed by the manifest's legacyDeletions pass. Never delete a deprecated layout dir until Part D has migrated its safe contents — otherwise user content would be lost.

After the harness files and symlinks are updated, migrate safe old-layout process artifacts into task folders:

• Scope:
  • flat *_PLAN_*.md files directly under process/general-plans/active/ and process/features/*/active/
  • sibling process/general-plans/reports/, process/general-plans/references/
  • sibling process/features/*/reports/, process/features/*/references/
• Safe inference rules: migrate automatically only when exactly one destination task folder can be inferred in the same scope by one of:
  • basename starts with one task slug and only one matching {slug}_{date}/ folder exists
  • basename or path contains an exact {slug}_{date} token matching one task folder
  • there is exactly one task folder total in that scope
  • exactly one task-folder plan references the legacy artifact path or basename
• Unsafe cases: leave in place and report when multiple candidates match, multiple plans reference the artifact, the file is clearly shared across tasks, or no task folder exists yet in that scope.
• Destination filename: preserve the original filename unless a same-name file already exists, then append -migrated.
• Cleanup: after all safe migrations, delete any now-empty legacy sibling reports/ or references/ dir. The target end-state is that each feature folder and process/general-plans/ keep only active/, completed/, and backlog/ unless unresolved legacy artifacts remain.

Part E — Clean up:

rm -rf "$VC_UPDATE_TMPDIR"

If --apply exits non-zero (permission error, missing kit file):

• Print the error message.
• Suggest running chmod on the affected path or checking file ownership.
• The command exits 1; do not treat a partial run as success.

Step 11: Print Applied Changes Summary and Post-Update NOTICE

vc-update complete: v{currentVersion} -> v{remoteVersion}

Applied:
  5 files modified
  2 files added
  1 file removed
  1 symlink fixed
  1 merge file preserved (review .claude/settings.json manually)

Snapshot written to .vc-installed-files
Version written to .vc-version: {remoteVersion}

If safe legacy artifacts were migrated, append lines such as:

Layout migration:
  4 legacy artifacts moved into task folders
  3 empty legacy dirs removed
  2 legacy artifacts left for manual review

After printing the summary, run three post-update checks and print a NOTICE block:

Check A — .agents/skills symlink vs real directory:

[ -L .agents/skills ] && echo "symlink" || echo "real-dir"

If the result is real-dir (Windows fallback — a real directory instead of a symlink), re-sync it now so it stays current with the updated .claude/skills/:

cp -r .claude/skills/. .agents/skills/

Print: NOTICE: .agents/skills is a real directory (Windows fallback) — re-synced from .claude/skills/

If it is a symlink, skip this step (the symlink already resolves to the updated .claude/skills/).

Check B — .claude/settings.json merge-preserved hooks gap:

If .claude/settings.json was in toPreserve (it was merge-protected), print the following NOTICE block verbatim so the user knows exactly what to add:

NOTICE: .claude/settings.json was preserved (merge-protected). New hooks added in
this release will NOT fire until you add them manually.

Missing hooks most likely absent from your v2.x install:

  PostToolUse (Write)  → post-write-plan-check.mjs   — validates plan artifact structure on every plan write
  PostToolUse (Bash)   → post-commit-lint.mjs         — lints commit messages for conventional-commit prefix
  Stop                 → stop-validator-sweep.cjs      — runs core validators on session end
  SubagentStart        → subagent-init.cjs             — injects compact context into every subagent

Paste-ready hooks block: see https://github.com/withkynam/vibecode-pro-max-kit/blob/main/MIGRATION.md#action-required-settingsjson-hooks
or diff .claude/settings.json .vibecode-backup/.claude/settings.json

If .claude/settings.json was NOT in toPreserve (it was freshly written), skip this notice.

Check C — orphaned old-layout / seed-template dirs (5 target classes):

Scan for orphaned deprecated layout dirs across these 5 classes:

1. process/general-plans/reports and process/general-plans/references (general-plans sibling dirs).
2. process/features/*/reports and process/features/*/references (feature-scoped sibling dirs).
3. process/development-protocols/references (deprecated protocol references dir).
4. process/_seeds/features/_feature-template/reports and process/_seeds/features/_feature-template/references (seed feature-template dirs).
5. process/_seeds/general-plans/reports and process/_seeds/general-plans/references (seed general-plans dirs).

Also scan for any flat *_PLAN_*.md file living directly in process/general-plans/active/ or process/features/*/active/ (not inside a {slug}_{date}/ subfolder).

For each orphaned dir found, log a line to .vc-orphaned-dirs.log in the project root:

DATE | DIR_PATH | STATUS: [EMPTY | USER_CONTENT | UNKNOWN]

• EMPTY — dir exists but has no files.
• USER_CONTENT — dir contains user files not yet migrated.
• UNKNOWN — could not classify (permission error, symlink, etc.).

After logging, print a stdout summary:

Found N orphaned dirs. See .vc-orphaned-dirs.log for details. Run vc-setup Merge Mode to migrate and cleanup.

If any orphaned dir or flat-plan signal is found after the safe migration pass, also print:

NOTICE: Some old-layout process/ artifacts could not be migrated safely.
The safe cases were already moved into task folders. Review the remaining
legacy paths manually — they are ambiguous, shared, or missing a clear task
folder destination.

If no orphaned dirs and no flat-plan signals are found, print nothing for Check C (no .vc-orphaned-dirs.log line written).

Recommended: run validators

After the NOTICE block, print:

Recommended next step — run the five core validators:

  node .claude/skills/vc-audit-vc/scripts/validate-agent-parity.mjs
  node .claude/skills/vc-audit-vc/scripts/validate-skills.mjs
  node .claude/skills/vc-audit-vc/scripts/validate-kit-portability.mjs
  node .claude/skills/vc-audit-context/scripts/validate-context-discovery.mjs
  node .claude/skills/vc-context-discovery/scripts/discover-skills.mjs

Rules

• VC_KIT_SOURCE: when set, overrides the remote URL for cloning. Used verbatim as the git clone source argument. No validation. Enables local testing and forks.
• process/_seeds/ is a legacy optional scaffold surface. If a remote release still includes it, treat it as managed reference and overwrite it entirely on update. Its absence in the live repo is valid.
• Real working files outside _seeds/ are preserved by default. The only allowed process/ mutations inside vc-update are the safe old-layout migrations described in Step 8 / Step 10 Part D for process/general-plans/ and process/features/*/.
• Always show the dry-run diff before applying. Never apply without user confirmation.
• Clean up the temp clone directory even on error or abort.
• If .vc-version is missing, treat as version 0.0.0 (first update, apply everything).
• CLAUDE.md and AGENTS.md are harness-only files -- overwritten freely on update. Project-specific content belongs in process/context/all-context.md, not in these files.
• Files in the merge list (e.g. .claude/settings.json) are never overwritten if they exist locally. Show the diff for manual review.
• Files in the copyIfMissing list are only installed if they don't already exist locally.
• Removals are detected by comparing the local .vc-installed-files snapshot against the new resolved file list.

Migration from v2.x

Kit v3.0.0 introduces the legacyDeletions key in resolveGlob()'s JSON output (Step 4 above). This note applies to users who are upgrading FROM a kit v2.x install that still has an OLD SKILL.md (one that predates v3.0.0 and does not reference compute-sync-plan.mjs). When such a user runs vc-update, the remote resolver already emits legacyDeletions in its JSON output. The current SKILL.md (this file, v3.0.0+) reads and applies that field in Step 6 via compute-sync-plan.mjs. No local SKILL.md change is required on the user's side — the update process itself installs the new SKILL.md in the same run.

The one-shot migration on next vc-update from kit v3.0.0:

1. Resolver emits legacyDeletions: [".claude/skills/vc-team", ".claude/skills/vc-chrome-devtools", ...] in the JSON output.
2. Step 6 applies those deletions in addition to the normal snapshot diff.
3. The 11 deprecated skill dirs (vc-team, vc-chrome-devtools, vc-docs, vc-repomix, vc-preview, vc-merge-worktree, vc-tech-graph, vc-watzup, vc-xia, vc-mcp-management, vc-context-engineering) plus 5 deprecated protocol paths are removed from the local install in one pass.
4. Snapshot is written with the new v3.0.0 file list — subsequent updates use normal diff logic.

Very old installs (SKILL.md predating legacyDeletions support): use install.sh for a clean reinstall instead of vc-update.

Reference

For detailed algorithm, error handling matrix, and edge cases, see references/vc-update.md.

vc-validate-findings

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Defines the role specs, prompts, and output schemas for the two-layer VALIDATE fan-out (a parallel check across 4 dimensions + per-section feasibility probes). Produces a net gate verdict (PASS / CONDITIONAL / BLOCKED) and all the inputs needed to write the validate-contract — the written checklist that gates EXECUTE.

References

• references/example-validate-output.md — full V4 menu + validate-contract template; calibrate output format against this file

When To Invoke

• VALIDATE V2–V3: invoked by vc-validate-agent after V1 pre-check passes
• Post-execute review in UPDATE PROCESS when re-validation of a plan is needed

Strategy Boundary

This skill is STRATEGY-AGNOSTIC. It defines the role specs, prompts, and output schemas for each dimension/section agent. It does NOT determine how those agents are executed (Workflow vs parallel Agent tool vs vc-team).

The execution method is determined by vc-agent-strategy-compare, which must be invoked BEFORE vc-validate-findings is called. vc-validate-findings outputs agent role definitions; the caller executes them using the recommended strategy.

Mode Selection

Choose before spawning any agents. Pass the selected mode to all Layer 1 and Layer 2 agents in their prompt context.

Simple Mode (default)

Runs the Layer 1 + Layer 2 fan-out using context available in the current conversation. Validation agents derive context from the plan file and what was passed in the prompt.

Appropriate when:

• Plan is self-contained (all context needed is in the plan text)
• Context is fresh in the current conversation window
• Blast radius is clear and confined to a single domain
• No container/infra/worker lifecycle surfaces are touched
• Fewer than 5 blast-radius packages

Deep Mode

Trigger when any one of the following is true:

• Plan blast radius touches container, infra, or worker lifecycle
• Plan has 5+ blast-radius packages
• Plan is a phase in a multi-phase program (prior phase outputs must be loaded)
• Caller explicitly requests deep mode

How Deep Mode works — run this context-loading step BEFORE spawning any Layer 1 or Layer 2 agents:

1. Read process/context/all-context.md routing table → identify which context groups are relevant to the blast radius
2. Load relevant context group all-*.md files (e.g. container/all-container.md, infra/all-infra.md, tests/all-tests.md, skills/all-skills.md) — only the groups that apply
3. If phase program: read the latest 1–2 phase reports from inside task folders (process/features/{feature}/active/{slug}_{date}/{slug}_REPORT_{date}.md) or legacy process/features/{feature}/reports/ (read-only legacy path)
4. Read existing test files in the blast radius (gives the Layer 1 test-coverage agent real data, not guesses)
5. Package all loaded material as a Context Bundle and pass it to every Layer 1 and Layer 2 agent

Quality difference in practice:

• Simple: Layer 1 infra agent infers container port assignments from plan description text
• Deep: Layer 1 infra agent reads the container context group (process/context/container/ or the repo's equivalent routing entrypoint) and knows the real port table (gateway:3000, file-server:3001, app-dev:3002, ctx-gateway:3099, browser-bridge:9377, MITM:9090/9091) — can catch real port conflicts the plan missed

Layer 1 — Four Always-On Dimension Agents

Always run all four, regardless of complexity score. These run in parallel.

Note: the security surface dimension INVOKES the vc-security skill — do not absorb vc-security's logic here.

Per-Agent Output Format

Dimension: [name]
Status: PASS | CONCERN | FAIL
Findings:
- [finding 1]
- [finding 2]
Confidence: HIGH | MEDIUM | LOW
Notes: [optional context]

Layer 2 — Per-Section Feasibility Agents

One agent per plan section or phase. These run in parallel with each other (and may overlap with Layer 1 in time, but Layer 2 results are presented after Layer 1 results are collected).

Each Layer 2 agent must answer four questions — not just "are edit targets findable?":

1. Mechanical feasibility — Are the edit target strings present and uniquely matchable in the named files? Can the described create/write steps be executed without collision?
2. Plan gaps — What is this section missing that it should include? Are there adjacent files or behaviors that should be updated but are not listed?
3. Conflicts — Does anything in this section contradict current file state, other plan sections, or repo conventions?
4. Risk — What is the single highest-risk edit in this section and how should the execute-agent sequence or mitigate it?

Per-Agent Output Format

Section: [section name or phase number]
Status: PASS | CONCERN | FAIL
Mechanical feasibility: [verdict + evidence]
Gaps found: [list or "none"]
Conflicts found: [list or "none"]
Highest-risk edit + mitigation: [description]

Warning: A Layer 2 agent that only confirms edit targets are findable without assessing gaps and conflicts is incomplete and must be re-run with the full four-question prompt.

[V2-PROBE] Feasibility Probe Emission Rule

When answering the 4 questions above, if a plan section depends on an untested runtime/system behavior (network/protocol/runtime/third-party response shape) that cannot be verified by reading source files, the Layer 2 agent MUST:

1. Emit VC-FEASIBILITY-PROBE-NEEDED: [hypothesis] — cost-class: [class] and halt.
2. NOT produce the standard per-agent output format.
3. NOT attempt to reason about the untested behavior as if it were mechanical.

Mechanical checks (NO probe): edit targets findable by Grep, file exists, schema field present, export names matchable, port in the container table, config key present in env.ts.

Examples of mechanical checks (NO probe): "does src/env.ts export a <SERVICE>_JWT_SECRET field?" → read the file; "does the container table list port 3000 for the gateway service?" → read the table.

Probe candidates (emit + halt): any behavior that requires a running system, live network call, or in-container exec to verify.

Examples of probe candidates: "does the gateway forward the X-Custom-Routing header to the upstream provider at runtime?", "does the container proxy honor the allow-list config field when injecting platform keys?", "does the OpenRouter API return pricing as a string or a number?".

Note: For each CONCERN found, INVOKE vc-scenario. For high-risk flagged concerns, INVOKE vc-predict.

V3 Synthesis Rules

The vc-validate-agent (or orchestrator) synthesizes all Layer 1 and Layer 2 outputs:

1. Collect all dimension and section verdicts.
2. List all FAILs prominently — any FAIL from any agent must be surfaced.
3. List all CONCERNs grouped by dimension.
4. Note contradictions between agents explicitly; do not resolve them silently.
5. Compute the net gate status:
   • Any FAIL → gate is BLOCKED (unless user explicitly converts to CONDITIONAL)
   • One or more CONCERNs, no FAILs → gate is CONDITIONAL (if user accepts) or re-runs
   • No FAILs, no CONCERNs → gate is PASS
6. Select test gates per the Test Tier Waterfall section.
7. Confirm or update the parallel strategy recommendation based on synthesized findings.

Note: Invoke vc-sequential-thinking at this synthesis step for contradiction ranking.

Net Gate Derivation Output Format

Present this exact table format after synthesis:

Layer 1 dimensions

Layer 2 sections

Totals: [N] FAILs / [N] CONCERNs / [N] PASSes

→ Net Gate: [PASS / CONDITIONAL / BLOCKED]

Decision rules:

• PASS: 0 FAILs, 0 CONCERNs. All plan fixes applied. Proceed to EXECUTE.
• CONDITIONAL: 0 FAILs, [N] CONCERNs. [N] fixed in plan, [N] as execute-agent instructions, [N] as known-gaps. Proceed to EXECUTE with gaps on record.
• BLOCKED: [N] unresolved FAILs. [List each.] Return to PLAN — do not route to EXECUTE until each FAIL is resolved or explicitly converted to CONDITIONAL by user.

Findings Output Format

Use this table format for each dimension's findings (Section I of the V4 menu):

Show PASS findings as ✅ PASS with — in the proposed fix column.

Section IV Output Format

Proposed Plan Updates

Show the summary below to the user before they approve EXECUTE (before gate V5). These changes are applied to the plan file when the user accepts.

Execute-Agent Instructions

Concerns that cannot be fixed in plan text — written to the validate-contract for execute-agent to follow:

Backlog Artifacts

/goal Block Output

After the validate-contract is written to the plan file (V6), the skill stores the /goal block.

Single plan: derive the /goal block from plan content (SESSION GOAL, charter, autonomy rules, hard stops, next phase, contract summary, execute start command). Write it to the plan file under a new ## Autonomous Goal Block section.

Multi-phase program: the /goal already exists in the umbrella ## Stable Program Goal. Do NOT rewrite it — only verify it is current and points to the umbrella path.

The /goal block must include:

• SESSION GOAL
• Autonomy rules
• Hard stops
• Next phase
• Contract summary
• Execute start command

Multi-phase program rule: If operating within a phase program (umbrella plan exists), emit the /goal block update automatically without asking — do not prompt the user.

Single-plan rule: Store the /goal block during V6. Whether it is printed for copy-paste is decided by the validate-agent's single V5 gate option (Accept vs Accept + print /goal). This skill does not open an extra prompt or separate user round-trip.

/goal must be fully copy-pastable (plain text block, no special formatting, under 4000 chars).

V5 during /goal autonomous execution: agent self-decides (CONDITIONAL → proceed, BLOCKED → backlog + proceed to next non-blocked phase). Skip any print ask — user is not present.

Web Testing Skill

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Comprehensive web testing: unit, integration, E2E, load, security, visual regression, accessibility.

Quick Start

npx vitest run                    # Unit tests
npx playwright test               # E2E tests
npx playwright test --ui          # E2E with UI
k6 run load-test.js               # Load tests
npx @axe-core/cli https://example.com  # Accessibility
npx lighthouse https://example.com     # Performance

Testing Strategy (Choose Your Model)

→ ./references/testing-pyramid-strategy.md

Reference Documentation

Core Testing

• ./references/unit-integration-testing.md - Vitest, browser mode, AAA
• ./references/e2e-testing-playwright.md - Fixtures, sharding, selectors
• ./references/playwright-component-testing.md - CT patterns (production-ready)
• ./references/component-testing.md - React/Vue/Angular patterns

Test Infrastructure

• ./references/test-data-management.md - Factories, fixtures, seeding
• ./references/database-testing.md - Testcontainers, transactions
• ./references/ci-cd-testing-workflows.md - GitHub Actions, sharding
• ./references/contract-testing.md - Pact, MSW patterns

Cross-Browser & Mobile

• ./references/cross-browser-checklist.md - Browser/device matrix
• ./references/mobile-gesture-testing.md - Touch, swipe, orientation

Performance & Quality

• ./references/performance-core-web-vitals.md - LCP/CLS/INP, Lighthouse CI
• ./references/visual-regression.md - Screenshot comparison
• ./references/test-flakiness-mitigation.md - Stability strategies

Accessibility & Security

• ./references/accessibility-testing.md - WCAG, axe-core
• ./references/security-testing-overview.md - OWASP Top 10
• ./references/security-checklists.md - Auth, API, headers

API & Load

• ./references/api-testing.md - Supertest, GraphQL
• ./references/load-testing-k6.md - k6 patterns

Checklists

• ./references/pre-release-checklist.md - Complete release checklist
• ./references/functional-testing-checklist.md - Feature testing

Scripts

Initialize Playwright Project

node ./scripts/init-playwright.js [--ct] [--dir <path>]

Creates best-practice Playwright setup: config, fixtures, example tests.

Analyze Test Results

node ./scripts/analyze-test-results.js \
  --playwright test-results/results.json \
  --vitest coverage/vitest.json \
  --output markdown

Parses Playwright/Vitest/JUnit results into unified summary.

CI/CD Integration

jobs:
  test:
    steps:
      - run: pnpm run test:unit      # Gate 1: Fast fail
      - run: pnpm run test:e2e       # Gate 2: After unit pass
      - run: pnpm run test:a11y      # Accessibility
      - run: npx lhci autorun       # Performance