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 (an empty board and an empty planning tree offer it too). A modal asks how to run it, and it asks for two things:

  • Project — which project grounds the session. 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).
  • The idea — a sentence or a paragraph; the interview fills in the rest. Drop files onto the box to attach them, and the agent reads them with your opening message.

Everything else is derived, not decided, and stays folded behind + Machine, engine, model, thread: the machine defaults to the project's first online one, engine and model pre-fill from the project's planning phase (set in project settings; claude by default), and the thread override aims the plan at a specific Context Thread instead of the project's own — rarely needed. The disclosure opens by itself whenever the machine pre-flight has something to say, so an offline machine is caught before you submit rather than after.

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.

There is one flow, and it is a conversation. Start conversation → opens a live session with the agent — there is no sit-and-wait mode that files an item while you look away. The agent 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.

You don't classify your own request. There is no kind to pick and no intake mode to set: say what you want, and the agent reads the opening message and adopts the right posture — a defect (pin the repro first), a change in behaviour (lead with the problem), maintenance (prove nothing changed), or open-ended. It names its reading in one clause and moves on; correct it in a sentence and it switches.

The exceptions are the three intents whose deliverable isn't a build plan, offered under Not building yet? as verbs rather than settings, because a wrong guess would hand you the wrong artifact:

  • Challenge an idea — red-team it before anyone commits. You get a verdict (proceed / reshape / kill) and a risk register, not tasks.
  • Investigate a question — a time-boxed spike. You get an answer and the evidence behind it, recorded as one item.
  • Author an agent template — interview a persona that runs unattended when a webhook wakes it. You get the persona, including the stop rules that let it refuse.

Finalize

When the plan is ready, Finalize records it in the planning tree as an epic ▸ feature ▸ task tree. The kinds are the agent's output, not your input — it decides whether your idea is one task or an epic of features, and how to cut the leaves. Each task leaf carries 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.

Filing a plan does not start it

Finalize files the plan. Nothing runs. Filing records the tree — it commits no machine, no worktree, no model spend and no pull request. Starting the work is a separate, deliberate act: Start on the Build Board, or promote_work_item from an agent (with container: true for an epic or feature, which runs its task leaves as one ordered chain).

This matters most when an agent is the one doing the filing, because "I've filed the plan" and "I've started the work" are a single sentence apart and only one of them is true. An agent that finalizes a plan should say plainly that nothing has started yet, and where to read what landed, so the person can decide.

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; /quick and /deep switch 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.

The terminal interview is where --kind still lives: it's a one-item interview, so you tell it up front whether you're specifying an epic, a feature, or a task. The web flow has no equivalent because it always decomposes.

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.

Refining something that already exists

A planning tree item offers + Plan from this item — the same modal, with the idea box pre-filled from that item's title and document, so refining a plan is a new conversation seeded with the old one rather than a blank page. An item that came from a planning session offers ↺ Reopen planning session instead: refinements reconcile back onto the items that session produced.

Next: Build & Ship · Trust gates · How it works.

Comparing two work items

/work/compare puts two items side by side with their specificity scores, so a duplicate or a near-duplicate is visible before either one is started. Reach it from a plan tree when two items look like they describe the same change.