Planning

Planning

/planx <task> puts the agent on the plan branch. It clarifies, researches, writes the plan, captures it once and stops.

What the agent does

1. Leaves plan mode first. An agent's own plan mode gates on accept/reject, and accepting it ends the planning phase — which is exactly where PlanX starts. The skill exits plan mode with a one-line stub before doing anything else.

2. Clarifies. One batch of questions about scope, approach and the trade-offs that decide what gets built, asked before any research and only where the answer materially changes the plan.

3. Researches and writes. It reads the code, makes the decisions and writes the plan as markdown.

4. Captures once, with planx capture, recording its own session id.

5. Hands back and stops. It prints the command to run and ends its turn. Nothing blocks and nothing polls — you exit the agent and open the review.

The hand-off line is verbatim, with no trailing period, because the command is there to be copied:

Plan created. Exit the agent, then run planx <plan-id> v<n>

The shape of a captured plan

The plan is written for the review to draw, so its structure is not incidental.

An H1 title. It becomes the plan's title in the picker, and the plan id is derived from it unless --name pins one.

##, ### and ####, used liberally, and nothing deeper. Those three are exactly what the review can fold: a ## folds and takes its subsections with it, a #### folds on its own, and a ##### does not fold at all. A plan of long flat ## sections is all-or-nothing to fold in the one tool built for folding it. The heading is also the label a comment comes back under, so a plan divided finely enough comes back with feedback you can place.

Hard-wrapped to 80 characters. The review draws the plan in a terminal, and a line that overruns is one you have to scroll sideways for.

Context near the top, verification at the end. The reader needs the why before the what, and the checks that prove the work are what the last section is for.

No out-of-scope section. A plan is what will be built; a list of what will not be built is not part of it. Anything you declined is said in the chat, immediately before the hand-off line.

Questions are answered in the chat

A comment that asks something — what does doctor do? — is answered in the agent's reply, not written into the plan. An answer is not part of what will be built, so putting it in the plan both bloats it and buries the reply where it has to be read as a diff.

The same rule covers boundaries. If the agent is about to narrow, widen or split what you asked for, it asks before capturing rather than stating an assumption in the plan. Stating it and flagging it in chat is not asking: it puts a decision you never made into a document that says what will be built, and the only way to undo it is a whole review round.

The session id, and why it is recorded

planx capture takes --session-id, and the skill passes whichever variable identifies the agent it is:

Agent	Passes
Claude Code	--source claude --session-id "$CLAUDE_CODE_SESSION_ID"
Codex	--source codex --session-id "$CODEX_THREAD_ID"
neither is set	--source <its own name>, and no --session-id

That id is what lets the review start the same conversation again on the other side of your feedback, with the repository research still in context. PlanX also records how that session's terminal was started, by walking its own process tree — a tab started with --model opus --add-dir ../shared comes back with both. See Hand-offs and Resuming a build.

An agent that passes no session id is still a normal way in. The review simply cannot restart it, so it hands you a command to paste instead.

This is the first-class difference, not a limit on the skill or review. PlanX knows how to record, launch and resume Claude Code and Codex sessions itself. Another agent can still plan, capture, revise and execute; install the skill and add its launch command with planx defaults.

Capturing by hand

You do not need the skill to store a plan.

planx capture --stdin --title "Guard the clock regression" < plan.md
planx capture --plan-id guard-clock-a3f9 --parent v2 --stdin

Every flag is in the CLI reference. Capturing content identical to the current latest is a no-op that hands back the existing version.

Revising

Revision is the same branch in reverse: planx revise <id> v<n> returns the stored version verbatim, every comment quoted against the lines it refers to, every line you rewrote by hand, and anything still unaddressed from an earlier version. The agent revises that text, not its own paraphrase in context, and re-emits untouched lines byte for byte so the next diff holds only real changes.

Then it captures with --parent v<n>, and you have a new version to read. See Versions and diffs.