Planning agent
A planning session turns a rough idea into a well-specified, buildable plan. Instead of handing an agent a one-liner and hoping, the agent interviews you first — the product, technical, and UX decisions that are yours to make — and co-authors the plan doc with you as you answer.
It runs your local agent (your auth, no server key).
Start from a project
Click ✦ Planning agent — the same header button on the Dashboard and the Build Board (the empty board offers it too). A modal asks how to run it:
- Machine and project — which of your machines runs the agent, and which project grounds it. That's all the targeting you need: the plan lands in the project's own context thread, created automatically the first time you plan (titled after the project). Aiming at a different thread is an Advanced option you'll rarely need.
- Model — the model the agent uses, on the project's planning engine (set per phase in project settings; claude by default).
- Intake mode — how deep the interview goes.
- The idea — a sentence or a paragraph; the interview fills in the rest.
Umbrella projects. If the project you pick sits inside an umbrella, the planning session plans into the umbrella's thread — one memory and one plan for the whole multi-repo product, whichever repo you started from. The agent assigns each task the repo it builds in, and Start/Promote pre-select that repo.
Starting opens a live session with the agent. It researches the project first, then asks only the questions it can't answer for you — one decision at a time, as multiple-choice questions with a recommended option, so you move fast on the calls you don't care about and slow down on the ones you do. Your answers land in the shared plan doc the two of you co-author.
Finalize
When the plan is ready, Finalize records it in the planning tree as an epic ▸ feature ▸ task tree, each item with a readiness score and a one-line readiness note — the agent's stated reason for the score (hover the rdy badge to read it). The agent re-scores an item, with a fresh note, whenever a later session touches it. From there, promote the tasks you approve to the Build backlog; the fleet builds them through the verify and approval gates, and finished work lands in the Build Board's Review lane for a human Accept.
The output is a plan, not one giant task
The Planning agent decomposes work into a tree whose task leaves are each small enough to build and merge independently. This is deliberate: a single 4,000-character mega-task can't be built reliably, so a well-specified feature becomes several bounded tasks you can run in parallel or as a chain. The agent proposes the breakdown; you approve it.
From the terminal
$ ptln plan(ptln shape and ptln describe are the legacy names and keep working as aliases.)
From v0.9.0, run it inside a registered repo and it needs no flags: the project implies the thread — umbrella-aware, created on first use — exactly like the web modal.
Flags and in-interview commands:
--kind epic|feature|task— hint the top-level kind (the agent still decides how to decompose).--thread <id>— override the project's default and plan into a specific Context Thread.--quick— start in quick mode;/quickand/deepswitch depth mid-interview./done— finish and write the item./quit— leave without saving.
Already inside a session? The in-session twin is the /describe command.
Customize what it asks
The default prompt is strong, but every team has standing guidance. You can add it in two places — both appended to the default (never replacing it, so the plan contract stays intact):
- Per project — a planning instructions field in project settings (e.g. "Prefer server components. Always propose a migration plan. Ask about auth before scoping."). Applies to every plan made in that project.
- Per session — an extra instructions box when you start one, for that plan only.
See Projects for project-wide guardrails that also steer the build, not just the interview.
Next: Build & Ship · Trust gates · How it works.