One entry point. /ideation picks how much planning the work needs, says why, and switches when you overrule it in a word. In Pi the same command also approves and controls runs. All five commands run in Claude Code, and in Pi as /skill:<name>; two of them Claude can reach for on its own. This page is the reference. The walkthroughs are one change in Pi and one idea through the planning path.
pi
$ pi install git:github.com/nicknisi/ideation
$ pi install npm:@nicknisi/pi-artifactsoptional: live plan and contract pages
pi · planning
$ pi install npm:@nicknisi/pi-subagents
$ pi install npm:@juicesharp/rpiv-ask-user-question
Claude Code
› /plugin marketplace add nicknisi/ideation
› /plugin install ideation@ideation
In Pi: /ideation
Bare /ideation or /ideation plan starts the ideation skill, which only ever starts when you ask. An approved plan runs here as one change: one approval, a live page, reviewed commits. Everything that grants permission is a command you type.
bare /ideation
With nothing in flight it starts planning from the conversation. Otherwise it offers only what applies to the current change:
Review the proposed contract
Approve and start
Revise the change
Open the live contract
Pause at a safe point
Resume approved work
Start fresh (new approval)
Accept the reviewed change
Plan a new change
Leave ideation
subcommands
/ideation plan<idea>
Start ideation from an idea. The agent picks a depth (just do it, short plan, interview or map), says why in one line, and takes a one-word overrule. Bare /ideation does the same when nothing is in flight.
/ideation approve[path]
Open the full contract and ask for one short confirmation of its paths and commands. With uncommitted files, it first asks whether to start from the last commit or include them. Yes starts work in an isolated worktree immediately. Remembers the prepared brief; a path is only for power users.
/ideation status
Show where every change stands, and refresh the widget and contract link.
/ideation review
Open the contract for a run (or the prepared draft) in your browser.
/ideation pause
Stop at the next safe boundary, with nothing lost.
/ideation resume
Continue a paused, interrupted or blocked run within its original approval, in the same worktree, told what failed last time. A stopped run doesn’t resume: Start fresh in the /ideation menu re-approves it in a new worktree.
/ideation stop
Set a run aside. It waits for owned processes to settle; the worktree and its commits stay.
/ideation accept
Record your acceptance of a ready-for-review run after reading its evidence and judgments, then leave ideation: it asks whether to bring the work into your checkout or keep it on its branch. It never merges, pushes or deploys.
/ideation exit
Leave ideation from any state. Stops a working run, brings its work into your checkout as uncommitted changes (or keeps it on its branch), and clears the widget. Nothing comes back on its own.
/ideation motion[on|off]
Turn the widget animation on or off (saved). PI_REDUCED_MOTION=1 or IDEATION_MOTION=off also switch it off.
/ideation respond<plan-folder>
Answer the latest plan.json in a plan folder: on its live page (with the artifacts service), in a terminal form, or by pasting the page’s Copy response. The response is shown in the session, and the next plan version is written only after you confirm. It never approves the plan.
the model's tool
The agent drives ideation_change. None of its actions can approve, accept or widen what was agreed.
prepare
Derive the run contract from a plan folder (or take a brief) and open its contract. Never approves.
status
Read a run’s state without restarting anything.
receipt
Read the source-bound record of what was verified.
feedback
File a note to the run’s inbox. Feedback is never permission.
answer
Reply to a question left on the contract page.
exit
Leave ideation when you ask to, bringing the work into your checkout.
what approval means
Approval is the only permission.Comments, questions, a selected option, or silence never approve, accept or widen scope. A change of intent, checks or authority needs a new plan version and a new approval.
Exact commands, trusted scripts.The commands you approve may run project scripts with your permissions. This is a trusted-command policy, not an OS sandbox, so read them before you approve.
No budgets.Approval fixes paths and commands, not time or tokens. Failing checks go back to the fixer, and each retry is told what failed. A run stops to ask only when it cannot make progress; Resume continues a paused or blocked run within the same approval, and a stopped one starts fresh with a new approval. Usage is shown for information only.
Never trapped./ideation exit, or Leave ideation in the menu, gets you out from any state: the run stops, its work comes into your checkout as uncommitted changes (or stays on its branch), and ideation goes away until you ask for it again. You can also just tell the agent.
Out of reach.Dependency manifests and protected internals are never in scope, and no install command is silently allowed.
Your uncommitted work is yours.It never blocks approval. Approval asks whether to start from the last commit or include your changes, and never stashes, commits or edits them.
The page can ask, not approve.Approve in Pi on a live draft contract page only brings up the terminal confirmation. It shows only while the owning session is listening, and needs pi-artifacts 1.6.0, which is not yet published; on 1.5.x the button stays hidden, and you approve with /ideation approve or the menu. Plan pages never ask for anything.
Humans only.A headless session cannot approve or accept. Human judgments are never marked passed by a check.
Stops at review.It commits locally on ideation/<run-id> and never pushes, merges or deploys. accept records your decision and nothing more.
live pagesWith @nicknisi/pi-artifacts 1.5.2+, plan pages and the contract update live in your browser and carry answers and comments back to the session. Without it, you answer plans in a terminal form or by paste, and the contract is saved locally for you to refresh by hand. Each change’s brief.json, contract.html and receipt.json land in docs/ideation/<slug>/, beside plan.json (or in <slug>-change/ when that folder is a 0.x project), for you to commit or not; run state stays under .git/ideation/.
Answer, approve, run
A short plan or an interview ends in a plan page: claims, and each open decision with a recommended answer. Your response is data, never instructions, and applying it writes the next plan version. It never approves.
In Pi
/ideation respond <plan-folder>: the live page through pi-artifacts (its Review layer is the one comment surface), a terminal form, or a paste. Pi shows the response, and only your confirmation writes the next version.
In Claude Code
plan-respond.mjs serve serves the page on 127.0.0.1 behind a one-time token; Send brings the response back, and the session applies it.
Paste, anywhere
Copy response on the page, paste it into the session. It always works: when Send fails, when the server times out, or when a local server is not allowed.
In Riker
A plan-first job opens the plan in Riker’s own viewer.
Approval is always a terminal confirmation, at every depth, and it freezes the same run contract in both harnesses. Every unit commit ends with the trailer Ideation-Unit: <plan id>/<unit id>, which is how verify.mjs counts it and how a resumed run skips it. What differs is who runs and commits it:
Pi
Claude Code
Freeze
ideation_changeprepare with plan: <folder>, then Pi's confirmation
node scripts/plan-data.ts run-contract <folder> after AskUserQuestion: run-contract.json and unit-<id>.md beside plan.json
Run
the change runner, in an isolated worktree, one unit per engine call
/ideation:autopilot <folder> (which runs node scripts/plan-data.ts manifest <folder>) on branch ideation/<plan id>; a one-unit plan runs through /ideation:execute-spec <packet> in the current checkout
Engine args
packet: true, hostCommits: true, strict: true, plus the brief's executionMode
packet: true, hostCommits: false, strict: true
Commits
the host, after independent review and the checks
the engine's commit stage (an agent), or execute-spec's Commit step
Unattended
the change runner already is
/ideation:get-goal-prompt prints a /goal from scripts/plan-goal.mjs
The commands
In the order you would meet them. You start with /ideation; it hands off to the execution commands itself once you approve.
Planning
One entry point. It picks how much planning the work needs, says why in one line, and switches when you overrule it in a word.
/ideationpi: /skill:ideationall tools
One entry point, at the right depth.
should we?
You are still deciding whether to build it. A conversation that ends in a decision and writes nothing.
just do it
One clear, low-risk change. No page: a compact plan, its checks, one confirmation, then the run.
short plan
Buildable now, with two to five real forks. You answer them on the page, then approve.
interview
The problem, goals or scope are not settled. The evidence-gated interview, the four critics, then the page.
map
Too big or foggy for one session. Its open questions are the map: research ones resolve in parallel, the rest one per session (more when you ask it to keep going), until the route is clear; then the interview.
reach for it
Anything from a one-line fix to an effort whose route you cannot see yet, or the question of whether to build it at all. In Pi, /ideation (or /ideation plan) starts it.
you get
Plan data in docs/ideation/<slug>/plan.json, a page to answer its decisions on, and, once you approve in the terminal, a run on the engine with reviewed commits.
worth knowing
A page never approves; only your terminal confirmation does. The "should we?" opening writes no files. The interview will not proceed on enthusiasm: every evidence gate must read ready, or the plan says why it stopped early.
/ideation:brainstormpi: /skill:brainstormwrites no files
Decide whether to build it, before any planning.
reach for it
You are weighing an idea, not committing to it. The same conversation as the "should we?" opening of /ideation, as its own command. In Pi, /skill:brainstorm starts it.
you get
A short conclusion in chat: the decision, its assumptions, the alternatives rejected, and what is out. If it is "build it", a pointer to the depth to run with /ideation.
worth knowing
It never starts planning itself. Its tool list has no way to write, so run /ideation in the same conversation to turn a "build it" into a plan.
Executing
Turning an approved plan into reviewed commits. In Claude Code, /ideation hands off to these itself; you reach for them to resume or to run one piece by hand. In Pi, the change workflow runs an approved plan instead.
/ideation:autopilotpi: /skill:autopilotclaude can start thiswrites files
Run every unit of an approved plan on the workflow engine.
reach for it
A plan was approved (its run-contract.json still matches plan.json), or a 0.x contract has specs. Independent units run in parallel waves; dependent ones wait.
you get
One reviewed commit per unit on ideation/<plan id>, each ending in its Ideation-Unit trailer, a run report beside the plan, and a VERIFY line stating whether the plan’s own checks pass.
worth knowing
It resumes rather than repeating: a unit whose trailer is already on the branch is skipped (for a 0.x contract, a phase whose spec path appears in a commit body). A plan edited after approval is refused until it is approved again.
/ideation:execute-specpi: /skill:execute-specclaude can start thiswrites files
Run a single unit by hand, with the same review loop.
reach for it
A one-unit plan, which /ideation hands here itself, or one unit (or 0.x spec) at a time, to watch it or to intervene.
you get
A scouted, built, reviewed and committed unit. The same scout → build → review ⇄ fix → commit cycle autopilot runs per unit, within the packet’s paths and commands.
Print a /goal that drives the whole plan unattended.
reach for it
You want an approved plan (or a 0.x contract) run long-haul without you in the loop, and re-driven if it stalls.
you get
A /goal string on your clipboard, printed by scripts/plan-goal.mjs so there is one owner for its wording.
worth knowing
A plan gets a goal only once approved. The goal is judged on the VERIFY line alone, and two identical failing runs in a row end it, so checks that have rotted cannot trap the run forever.
The five gates the interview will not skip
At the interview depth, a gate reads ready only when a concrete artifact backs it, not your confidence. The plan is written when no gate can move: all five ready, the rest blocked on written open questions, or you ended it. Approval then refuses a plan whose gates aren't ready unless it records why it stopped early.
01
Problem Clarity
Do I understand what problem we're solving, who has it, and why it matters?
ready whenThe problem is concrete (who, what, when, impact) — not "things are slow" or "it's broken".
02
Goal Definition
Are the goals specific and measurable?
ready whenEvery goal names what changes and by how much — not "make it better" or "users should be happier".
03
Success Criteria
Can every stated goal be checked pass/fail today?
ready whenEvery goal has at least one such criterion; none are subjective ("looks good", "feels fast"); criteria a command could verify name that command. A criterion checkable only by judgment is allowed but must say so explicitly — an unstated check is a gap, not a default.
04
Scope Boundaries
Do I know what's in and out of scope?
ready whenIn/out boundaries are explicit with rationale for exclusions — not "fix the checkout" or "nothing else".
05
Consistency
Are there contradictions I need resolved?
ready whenRequirements align and priorities are clear when tradeoffs exist — no "must be real-time" + "must work offline" + "no local storage".
What lands on disk
Everything for one plan lives in docs/ideation/<slug>/, a map included. A 0.x folder with contract-data.json gets a plan.json beside it the first time it is read, and its old files are kept.
plan.json
The source of truth: claims, decisions, checks, units, authority and gate evidence. Every page is rendered from it, and approval freezes it into the run contract.
plan.v1.json …
Every earlier version, kept. Each applied response becomes the next version (in Pi, only after you confirm it).
plan.html
The page you answer decisions on, rendered by plan-render. It never approves anything. In Pi the live page is published through pi-artifacts instead, and plan.html is written when that service is missing.
response.v<n>.json
Claude Code: the response plan-respond serve received for version n, before it is applied.
run-contract.json, unit-<id>.md
Claude Code, after you approve: the frozen run contract and one work packet per unit, which autopilot and execute-spec run.
brief.json, contract.html, receipt.json
Pi, once a plan is prepared: the run contract as the change workflow holds it, its contract page (draft, then live, then the record), and the receipt once the run is ready for review.
run-<date>.json, run-<date>.htmlrun output
Claude Code: autopilot’s record of a run and its report, which links back to plan.html. Written before the failure gate, so a failed run is recorded too.
context-map.mdrun output
Written by the scout when a 0.x spec runs: what it found in your codebase before anything was built. A plan’s units keep the map in the conversation instead.
implementation-notes-phase-N.htmlrun output
From a 0.x spec run: the decisions the spec did not cover. A plan’s units record theirs in the completion report. The learning loop reads both at the end of a watched run.
one exceptiondocs/ideation/learnings.md sits above the project folders and is meant to be committed. It is what the next interview applies; intake also offers, once, to mine notes an unattended 0.x run left behind.
Where it runs
Claude Code and pi. The same skills, agents, references, and scripts in both — nothing is conditional at load time. Five things carry a translation: the engine, agent names, Pi’s tool prerequisites, how a plan page’s response gets back, and who commits an approved plan. Each skill names its translation inline.
the engine
Claude CodeWorkflow
scriptPath: <abs path to execute-contract.mjs>, args: <manifest>. Runs in the background; watch /workflows.
pirun_ideation_contract
Bundled — registered by extensions/engine.ts, which vm-wraps the same engine file and backs agent() with the first-party in-process spawn runtime (@nicknisi/pi-shared). Call it with the manifest as parameters; the summary returns synchronously as the tool result.
agent names
Agent, subagent_type: "Explore"
Claude CodeCC built-in Explorepia read-only dispatch task
subagent_type: ideation:plan-critic
Claude Codeplugin-scoped ideation:plan-criticpia dispatch task with agents/plan-critic.md as systemPrompt
subagent_type: ideation:scout
Claude Codeplugin-scoped ideation:scoutpia dispatch task with agents/scout.md as systemPrompt
subagent_type: ideation:reviewer
Claude Codeplugin-scoped ideation:reviewerpia dispatch task with agents/reviewer.md as systemPrompt
subagent_type: general-purpose
Claude CodeCC built-in general-purposepia dispatch task with mutating tools + allowTreeMutation
pi installation
Approving and running a plan in Pi needs only the plugin. Planning also calls two tools, which are deliberately not bundled: pi allows one owner per tool name, so a bundled copy would fatally conflict with the same tool installed at the user level. Your installs are the ones the skills call. The contract engine needs no external tool; the plugin bundles it. Claude Code has the tools built in and ignores the pi manifest.
`npm:@nicknisi/pi-subagents`→ the `dispatch` + `fleet` tools (first-party in-process children)
Without it: every agent dispatch fails
`npm:@juicesharp/rpiv-ask-user-question`→ the `ask_user_question` tool
Without it: decision points fall back to plain text: ask with lettered options and state your recommendation; never skip the question. `extensions/preflight.ts` shows a startup notice naming the missing tool
the engine's own agentsNeither harness passes agentNames: Claude Code resolves the engine's stage agents from the plugin's registry, and the pi engine host reads agents/*.md directly. The respond loop and approved runs are covered above. The full matrix, including what does not differ, is references/harness-compat.md ↗.
From 0.x
1.0 has one planning command. The others are gone, with no shim and no deprecation release before them, because the change shipped as one release. Their work is a depth of /ideation:
/ideation:chart
/ideation at the map depth: the map's tickets are openQuestions in plan.json, still one non-research question per session unless you say to keep going
/ideation:express
/ideation at just do it for one clear change; at any depth, the terminal approval hands the plan straight to the engine
/ideation:change/skill:ideation-change
/ideation (in Pi, also /ideation plan): it picks the depth, a clear change lands on just do it, and Pi's approval runs it through the same change workflow
Existing projects convert on read: a folder with contract-data.json gets a plan.json beside it, and its old files are kept. A converted contract has no before and after, invariants or authority yet, so it needs one revision before it can run as a plan. Unrevised, during 1.0.x, autopilot still runs it as a 0.x contract, against its specs. To update: pi update git:github.com/nicknisi/ideation and restart Pi, or /plugin update in Claude Code. learnings.md carries over unchanged. The details are in the README ↗.
Every command name, argument hint and badge on this page is read at build time: skills from skills/*/SKILL.md, the Pi subcommands, menu and tool actions from extensions/change.ts, the gates from the rubric the interview itself uses, the harness tables from references/harness-compat.md, and the From 0.x table from the README. Anything that ships without an entry here fails the build rather than going undocumented.