Phase Lifecycle
A phase is the unit of work in PP Core, and every phase travels the same path: discuss, plan, execute, verify, ship. This guide follows a single phase from its first conversation all the way to a pull request, and points out the gates you should not skip along the way.
Step 1: Discuss
/pp-discuss-phase N
Discussion exists to drag implementation decisions into the open before they harden into silent assumptions buried in a plan. PP Core asks about the gray areas of the phase and records your answers.
You can shape how the conversation runs:
| Flag | Effect |
|---|---|
--all | Skip selection and discuss every gray area. |
--auto | Accept the recommended default for each decision. |
--batch | Group questions together for faster intake. |
--analyze | Add trade-off analysis to the discussion. |
--power | Apply bulk answers from a prepared file. |
--assumptions | Generate assumptions without an interactive session. |
This step writes {phase}-CONTEXT.md, the structured decisions, and {phase}-DISCUSSION-LOG.md, an audit trail of how you got there.
Step 2: Plan
/pp-plan-phase N
Planning researches the problem, breaks the work into executable plans, and checks that each plan fits inside a fresh 200k-token context window so an agent can carry it out without losing the thread.
Useful flags include:
--skip-researchto omit the research pass, and--researchto force a fresh one.--prd <file>to plan from a PRD instead of the discussion output.--mvpto organize tasks as vertical feature slices, or--tddfor red-green-refactor sequencing.--granularity <coarse|standard|fine>to override task sizing.--gaps, which readsVERIFICATION.mdto plan remediation work.--bounceto run external validation after planning, and--reviewsto foldREVIEWS.mdfeedback into a replan.
Plans produce {phase}-RESEARCH.md, one or more {phase}-{N}-PLAN.md files, and {phase}-VALIDATION.md.
Step 3: Execute
/pp-execute-phase N
Execution runs the plans in dependency-ordered waves, using git worktrees so independent plans can run in parallel. Each plan leaves behind a {phase}-{N}-SUMMARY.md, and all code lands as git commits. When the phase finishes, PP Core writes {phase}-VERIFICATION.md.
If execution is interrupted, you can resume a specific wave with --wave N. Use --gaps-only to run just the remediation plans produced by verification, or --interactive to step through plans one at a time with checkpoints.
Step 4: Verify
/pp-verify-work N
Verification is user acceptance testing. PP Core validates the built work against the phase goals and requirements, recording acceptance status per requirement in {phase}-UAT.md. Where something falls short, it generates fix plans you can feed back into execution.
Gate: do not run /pp-ship until verification has passed. This is the checkpoint that keeps unverified work out of your pull requests.
Step 5: Ship
/pp-ship N
Shipping opens a GitHub pull request with a body auto-generated from the phase's planning artifacts, then updates STATE.md to mark the phase as shipped. Add --draft to open the PR in draft form.
Two prerequisites apply: the gh CLI must be installed and authenticated, and the phase must have passed /pp-verify-work.
Keeping your bearings
At any point, check status and advance the workflow with:
/pp-progress
Add --next to auto-advance to the next step, --do "<intent>" to route a freeform request to the right command, or --forensic to pair the standard report with an integrity audit.
The sequence at a glance
1. Discuss → /pp-discuss-phase N → CONTEXT.md + DISCUSSION-LOG.md
2. Plan → /pp-plan-phase N → RESEARCH.md + PLAN.md + VALIDATION.md
3. Execute → /pp-execute-phase N → SUMMARY.md + commits + VERIFICATION.md
4. Verify → /pp-verify-work N → UAT.md + fix plans (if needed)
5. Ship → /pp-ship N → GitHub PR + STATE.md update