Vc Generate Phase Program

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.