/forge:plan-pro

Aliases

• /forge:plan-pro
• /forge:implementation-plan

Purpose

This skill orchestrates Stage 5 — Implementation Planning. It performs stage gating, profile loading, persona/reference loading, context verification, artifact/traceability/ownership verification, state advancement, and canonical next-stage guidance.

This skill does not perform implementation planning. agents/planner-pro.md and its mandatory references/plan/ documents are the sole authority for planning logic, artifacts, identifiers, task decomposition, validation, quality gates, revisions, failures, and completion behavior.

Stage Ownership

Do not duplicate or reinterpret persona/reference logic in this skill.

Pre-flight Check

Entry Gate

Before reading the persona, references, or planning artifacts, run:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/state-manager.py preflight --stage 5

If it exits non-zero, STOP. Display the returned message verbatim. Do not adopt Planner Pro, generate artifacts, or bypass the prerequisite. The user must complete the prior stage or use the repository’s approved force-advance flow.

Forge Project and Progress Verification

Read pipeline/state.md. Verify Forge is initialized, state exists, the current stage is valid, and a project profile is available. If any condition fails, STOP and report it.

If current_stage > 5, tell the user that Stage 5 appears complete and offer Review, Validate, Revise, or Regenerate. Never overwrite existing Stage 5 artifacts without explicit confirmation. If current_stage == 5, continue only as confirmed refinement work.

Upstream Handoff Verification

Verify the canonical Stage 1–4 handoff required by Planner Pro exists or resolves with read-doc.py. This includes the Stage 1 SRS/traceability, required Stage 2 product/traceability artifacts, required Stage 3 architecture/ traceability/ADRs, and every Stage 4 contract required by the Planner Pro foundation and workflow references.

If any required input is missing or cannot resolve, STOP. List every missing artifact. Do not infer, regenerate, or replace upstream work.

Load Project Profile

Run:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/load-profile.py --cwd . --stage 5

Load and pass its result unchanged to Planner Pro. The persona’s governance reference controls handling of replace_with, additional_artifacts, additional_steps, additional_concerns, and skip_steps. Never let a profile bypass entry, ownership, traceability, validation, quality, or advancement gates.

Context Depth for Stage 6 (REQ-BUILDCTX-002)

Stage 6 Pro (/forge:build-pro) resolves per-task context at one of three depths: spec_plan (default), spec_arch_plan, or full_chain — see references/build/02-context-resolution.md. This is decided once, here, at Stage 5 entry, not re-derived per build.

Read pipeline/state.md. If build_context_depth is already set, skip this step silently — never re-prompt or overwrite an explicit prior choice (AC-BUILDCTX-002c).

If unset, ask the user which depth Stage 6 should use for this project:

• spec_plan (recommended default) — spec + plan only. Matches Builder Pro's own principle that Stage 4's spec is already the distilled, implementation-ready contract; Stage 6 does not need to re-derive architecture.
• spec_arch_plan — also resolves matching architecture excerpts per task.
• full_chain — resolves the full Stage 1–5 canonical set (SRS, PRD/user stories/flows, architecture, spec, plan, sprint plan when present) as additional informational context per task.

Persist the answer:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/set-context-depth.py <depth> --cwd .

If the user has no preference, use the recommended default and move on — do not block Stage 5 planning on this decision.

Load Planner Pro and References

Read agents/planner-pro.md, adopt Planner Pro, and follow its Reference Loading Protocol exactly. The following files are mandatory agent instructions:

references/plan/01-foundation.md
references/plan/02-execution-planning.md
references/plan/03-delivery-governance.md
references/plan/04-traceability-validation.md
references/plan/05-workflow-governance.md

Load each reference when the agent requires it and load all five before final validation or completion. Do not omit, summarize away, substitute, or weaken a reference instruction.

Execute Stage

Provide Planner Pro only the context authorized by its foundation and workflow references. Use:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/read-doc.py <document-base-path>

for every canonical document that can have a single-file or split layout. Do not assume a flat planning or specification document exists, and do not use source code or later-stage output as authority for a new Stage 5 plan.

Execute the persona sequentially, apply loaded profile overrides exactly, and allow it to generate only the Stage 5 artifacts governed by its references.

Verification

Before advancement, verify through the document resolver that the canonical implementation-plan entry point and every required, profile-added, and non-skipped Stage 5 artifact resolve successfully.

Verify that Planner Pro reports PASS for all applicable planning-completeness, traceability, ownership, deterministic dependency/order, validation, and quality gates. Confirm every planning artifact has valid upstream lineage, no Stage 1–4 artifact was redefined, no implementation code was generated, and no unresolved validation error remains.

If verification fails, report the failures and affected artifacts. Do not advance. Let Planner Pro perform only the deterministic Stage 5 repair permitted by its references; stop and report upstream conflicts or unrecoverable failures.

Advance Pipeline State

Advance only after successful verification:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/state-manager.py advance --to 5

If advancement fails, display the returned message verbatim and stop. Do not claim completion.

Completion Report

Present the Planner Pro report derived from generated artifacts, then verify pipeline/state.md reports current_stage: 5. Do not summarize the full plan unless requested.

Next Stage

Only after successful advancement, run:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/state-manager.py next-hint --stage 5

Present the helper output verbatim.

Orchestration Rules

This skill SHALL run preflight first; load the profile; read Planner Pro and its mandatory references; use the document resolver; preserve upstream ownership; execute the persona; verify resolved artifacts, planning completeness, traceability, dependencies, determinism, and stage ownership; advance only after PASS; and present the canonical next hint.

This skill SHALL NOT duplicate planning logic; redefine upstream work; invent functionality, IDs, repository paths, owners, or dependencies; bypass a gate; advance on failure; write implementation code; overwrite confirmed existing planning artifacts without approval; or claim completion before advancement.