Getting Started

Quickstart

This guide walks you through your first full PP Core run, from an empty directory to a shipped phase. You will initialize a project, then take Phase 1 through the complete loop: discuss, plan, execute, verify, and ship.

Before You Start

Make sure PP Core is installed for your runtime. If you have not done that yet, see the Installation guide. Commands below use the /pp- prefix; adjust it to match your runtime if you are on Gemini CLI or Codex.

Step 1: Initialize the Project

Open your AI coding runtime in the directory where your project lives (or will live) and run:

/pp-new-project

PP Core gathers deep context about what you are building and lays down the foundation of your .planning/ directory. After initialization you will have:

• .planning/PROJECT.md — the high-level description of the project
• .planning/REQUIREMENTS.md — what the project must deliver
• .planning/ROADMAP.md — the project broken into phases
• .planning/STATE.md — the current workflow state
• .planning/config.json — project configuration
• .planning/research/ — supporting research materials

If you already have a written brief, you can hand it straight to the initializer and let it run with less back-and-forth:

/pp-new-project --auto @brief.md

Step 2: Discuss Phase 1

With a roadmap in place, start the first phase by gathering its specific context. The discuss step asks adaptive questions to pin down decisions before any planning happens:

/pp-discuss-phase 1

This produces a context artifact for the phase, for example .planning/phases/01-phase-name/01-CONTEXT.md. To roll straight from discussion into planning in one pass, add the --chain flag.

Step 3: Plan Phase 1

Turn the agreed context into a concrete, executable plan:

/pp-plan-phase 1

Planning typically runs research first and then writes one or more plan files, such as 01-RESEARCH.md, 01-01-PLAN.md, and 01-02-PLAN.md, inside the phase directory. If you want to skip the research stage for a simple phase, use --skip-research.

Step 4: Execute Phase 1

Run the plans. PP Core parallelizes the work into waves, each running in its own fresh context so quality does not degrade as the phase grows:

/pp-execute-phase 1

Execution implements the plan and records its progress in the phase's state artifacts.

Step 5: Verify Phase 1

Once execution finishes, confirm that what was built actually satisfies the requirements. This is the step that separates spec-driven development from hoping for the best:

/pp-verify-work 1

Verification produces records such as 01-VERIFICATION.md and 01-UAT.md, documenting what was checked and the outcome.

Step 6: Ship Phase 1

When verification passes, package the phase and prepare it for merge:

/pp-ship 1

To open the result as a draft instead of a finished package, add --draft.

Repeat for the Next Phase

A project is just its roadmap of phases run through this same loop. Move to the next phase by repeating discuss → plan → execute → verify → ship with the next number:

/pp-discuss-phase 2

Staying Oriented

A few commands help you keep track and pick up where you left off:

Because PP Core writes a .planning/continue-here.md marker and keeps every phase's state on disk, you can stop after any step and come back later without losing your place.