spx-plan

name	spx-plan
description	Lean technical-planning workflow for advanced coding models. Use when a planning-ready specification needs repository-grounded architecture, interfaces, risks, verification, rollout, and rollback decisions.

SPX Plan

Read references/project-learning.md and apply its consume-capture policy. Read references/workflow-runtime.md and let its CLI own phase state. Read references/project-cognition.md, using cognition intent plan. Always read references/planning-contract.md. Read references/consequence-gate.md only on its triggers. Read references/ui-quality-gate.md when the specification is UI-bearing.

Resolve FEATURE_DIR without creating plan.md, using an explicit feature argument, lane state, or the installed prerequisite helper's paths-only mode. Transition from the validated specify stage into plan through the workflow runtime. Only after the transition succeeds, run the installed .specify/scripts/bash/setup-plan.sh --json or PowerShell equivalent to create or preserve the plan skeleton. Run {{specify-subcmd:specify-runtime hook validate-state --command plan --feature-dir <feature-dir> --autofix --format json}} and stop if it remains invalid.

Require spec-contract.json with status: planning-ready, a ready transition to sp-plan, a current source revision, locked target boundary, zero hard unknowns, and zero open conflicts. Fail closed to the owning upstream workflow when any gate fails. Verify architecture claims against cognition-selected live repository paths.

Treat plan-contract.json#/acceptance_refs as the exact complete fail-closed Spec-to-Plan denominator. For a ready version-2 plan it is the unique ordered list spec-contract.json#/acceptance_criteria/0..N-1, covering every live specification acceptance criterion exactly once; never select a subset, reconstruct prose labels, or reorder, duplicate, rename, or omit a criterion.

When deep-research.md exists, read and validate it before choosing the design. Consume every PH-### Planning Handoff item according to its mandatory, optional, or user-decision contract. Add a level-2 ## Deep Research Traceability Matrix to plan.md with Plan Decision, Handoff ID, Evidence / Spike ID, Evidence Quality, and Plan Action columns. Missing mandatory handoffs or untraceable evidence keep planning blocked; a validated **Status**: Not needed handoff carries no invented PH IDs.

Render plan-contract.json and plan.md from the canonical machine template .specify/templates/plan-contract-template.json and this Skill's compact assets/plan.md. Cover affected components and files, interfaces and data, compatibility or migration, security, verification, rollout or rollback, and material risks only when relevant.

For UI-bearing work, consume DESIGN.md, ui-brief.md, original fidelity sources, and the spec design contract. Set ui_design_contract.ui_applicable: true, preserve ui_brief_ref, and record design_readiness. Populate it with the current direction contract, surface/platform classification, approved visual, preview/manifest SHA-256 values, DS-* decisions, component/color-mode/ responsive/motion contracts, reference intents, real content/image plans, design-system adoption, required states, must-preserve rules, real entry points, viewport/state acceptance matrix, comparison tolerance, accepted deviations, and the evidence triad. Carry verified cognition routes into the compact context capsule. Do not defer these decisions to tasks.

If design-changing feasibility remains unproven, stop and route the named question to $spx-deep-research; do not hide research inside generic plan prose. Repair requirement contradictions through $spx-clarify.

Create conditional outputs only when they carry independent design evidence: research.md for bounded implementation-shaping research, data-model.md for new data/state or persistence design, contracts/ for external or protocol interfaces, and quickstart.md for a material end-to-end validation scenario. Otherwise record the skip reason in plan-contract.json. Refresh existing agent contexts with the installed update-agent-context script after the plan is valid.

Validate the plan contract and compact plan view against confirmed requirements and live owners. Do not create tasks or task artifacts such as tasks.md or task-index.json; also do not create checklists, issues, production source, tests, migrations, or runtime configuration in this workflow. Preserve canonical /sp.* state identifiers. This invocation authorizes only this workflow stage. Run {{specify-subcmd:specify-runtime hook validate-artifacts --command plan --feature-dir <feature-dir> --format json}} and repair or block on a non-OK result. Stop after reporting the validated plan and recommend $spx-tasks when ready. Do not invoke $spx-tasks in this run; a handoff is not authorization to execute it.