Starting a New Project
Every PP Core project begins by capturing intent before any code is written. This guide walks through bootstrapping a fresh project, the context PP Core gathers from you, and the planning artifacts it lays down on disk.
Before you begin
PP Core keeps all of its planning state inside a .planning/ directory at the root of your repository. If that directory already holds a PROJECT.md, the initializer treats the project as already set up and stops with a warning rather than overwriting your work. Starting clean? Read on.
Initialize from a conversation
The most common entry point is the interactive wizard:
/pp-new-project
PP Core will interview you. Expect questions across five areas:
- The project's name and the problem it exists to solve.
- Who the users are and the scenarios they care about.
- Functional and non-functional requirements.
- Technology preferences and anything you want to standardize on.
- Known constraints such as deadlines, team size, or hard dependencies.
Answer in plain language. The wizard turns your replies into structured planning documents, so the more concrete you are about goals and constraints, the sharper the roadmap.
Initialize from an existing document
If you already have a spec, PRD, or RFC, skip the interview and feed it straight in:
/pp-new-project --auto @spec-file.md
The --auto flag points PP Core at a file in your project and derives the same set of artifacts without asking questions interactively. This is the fastest path when the thinking has already happened elsewhere.
Pulling in scattered documentation
When relevant context is spread across several files already in the repository, use the ingest command instead:
/pp-ingest-docs
With no arguments it scans the repository and decides automatically whether to run in new mode (a full setup, when no .planning/ exists yet) or merge mode (folding new material into an existing setup). You can narrow the scan to a folder, or supply a manifest that encodes which sources win when they disagree:
/pp-ingest-docs docs/
/pp-ingest-docs --manifest ingest.yaml
A single invocation processes at most 50 documents. If the ingested material contains contradictions, PP Core writes an INGEST-CONFLICTS.md file describing them. Conflicts flagged as unresolved blockers will hold up execution until you settle them, so resolve those before moving on.
What gets created
However you initialize, PP Core populates .planning/ with a consistent set of files:
| File | What it holds |
|---|---|
PROJECT.md | The high-level description: goals, target users, and success criteria. |
REQUIREMENTS.md | Functional and non-functional requirements in structured form. |
ROADMAP.md | The sequence of milestones and phases that deliver the project. |
STATE.md | Live tracking of which phases are done, in progress, or pending. |
config.json | Settings: model profile, granularity, workflow toggles, and integrations. |
INGEST-CONFLICTS.md | Only when doc ingestion surfaces contradictions. |
Treat these as the source of truth. Every later command in PP Core reads from and writes to this directory.
Confirm and take the first step
Once setup finishes, check where things stand:
/pp-progress
This reports the project status and the phases waiting in the roadmap. When you are ready to start building, open the first phase for discussion:
/pp-discuss-phase 1
That hands you off into the phase lifecycle, where each phase moves from discussion through planning, execution, verification, and shipping.