Seven commands, three of which Claude can reach for on its own. They divide by the question you are actually asking: which way to go at all, whetherto build the thing, how to build it, or getting it built. This page is the reference; the illustrated walkthrough is its own page.
In the order you would meet them. Only the charting stage writes files before a contract exists — and all it writes is a map of decisions, never a plan.
Charting the route
Too big for one session and the way is not yet visible? Map the decisions first — as many sessions as it takes.
/ideation:chartclaude can start thiswrites files
Map an effort too big for one session, one decision at a time.
reach for it
The work is huge and the route is fog — you cannot yet see the way from here to done, so a single interview cannot hold it. “We need a map before we plan.”
you get
A map and its decision tickets under docs/chart/<slug>/, worked one per session. When nothing is left to decide, the route hands off to the interview as its starting evidence.
worth knowing
It plans, and only plans — a ticket resolves a decision, never a build. If the fog lifts on first look, it says so and sends you straight to the interview.
Deciding whether
Is this worth building at all? No files are written at this stage.
/ideation:brainstormclaude can start thiswrites no files
Pressure-test an idea before committing to it.
reach for it
You are weighing options, or you suspect the idea might be wrong. “Should I do X?” “Which of these approaches?” “Am I over-engineering this?”
you get
A conclusion in chat, in four parts, and nothing on disk. A “yes” hands off to the interview with its rejected alternatives already recorded.
worth knowing
It is for a question, not a dump. Anything shaped like “I want to build…” belongs to the interview, however settled it sounds.
Planning how
The interview, the critics, the contract, the specs. This is where a plan becomes something you can approve.
/ideationclaude can start thisall tools
The one door. An evidence-gated interview to a contract you approve.
reach for it
You have something to build and you want a plan you can hold — from a one-spec change up to a multi-phase initiative.
you get
contract.html to decide on, contract.md and numbered spec files to execute against, and a run-mode recommendation.
worth knowing
It will not proceed on enthusiasm. All five evidence gates have to read ready first, and it reads your codebase rather than asking you about it.
/ideation:expresswrites files
The same interview with the routing pre-answered.
reach for it
The work is well understood and you would rather not review each artifact. You want planning that flows straight into execution.
you get
The same artifacts, one consolidated confirmation instead of per-artifact gates, and execution on an isolation branch.
worth knowing
Because no human reviewed the specs, execution runs fail-closed: a scout HOLD or a crashed reviewer stops the phase rather than committing anyway.
Executing
Turning approved specs into reviewed commits. Every one of these needs a contract that already exists.
/ideation:autopilotclaude can start thiswrites files
Run every phase of an approved contract on the workflow engine.
reach for it
The contract is approved and you want to walk away. Independent phases run in parallel waves; dependent ones wait.
you get
One commit per phase, each naming its spec path, and a VERIFY line stating whether the contract’s own checks pass.
worth knowing
It resumes rather than repeating: a phase whose spec path already appears in a commit body is skipped.
/ideation:execute-specclaude can start thiswrites files
Run a single phase by hand, with the same review loop.
reach for it
You want one phase at a time — to watch it, to intervene, or because the phase is risky enough to deserve your attention.
you get
A scouted, built, reviewed and committed phase. The same scout → build → review ⇄ fix → commit cycle autopilot runs per phase.
Print a /goal that drives the whole contract unattended.
reach for it
You want the project run long-haul without you in the loop, and re-driven if it stalls.
you get
A /goal string on your clipboard, generated by the contract generator so there is one owner for its wording.
worth knowing
The goal is judged on the VERIFY line alone, and its done-when is disjunctive so a contract whose checks have rotted cannot trap the run forever.
The five gates it will not skip
The interview keeps asking until every one of these reads ready. That is the whole reason it can refuse to generate a plan: a gate needs a concrete artifact, not your confidence.
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 project lives in docs/ideation/<slug>/. Charting is the exception: a route map lives in docs/chart/<slug>/, one Markdown file per decision ticket, and exists precisely because no project slug has been earned yet. Planning artifacts are HTML because they exist to be decided on; specs and tickets are Markdown because they exist to be executed.
contract-data.json
The source of truth. Every other artifact is rendered from it, and execution reads this rather than the HTML.
contract.html
The artifact you review and approve: gate evidence, scope tiers, the phase graph, the run model, and the decision log.
contract.md
The same contract as text. This is the path you hand to autopilot.
spec-phase-1.md …
One implementation spec per phase, numbered. Each carries the File Changes tables execution reads to work out which phases collide.
context-map.mdrun output
Written by the scout at run time and extended by each later phase — what it found in your codebase before anything was built.
implementation-notes-phase-N.htmlrun output
What actually happened during a phase, including what the reviewer caught. The learning loop reads these at the end of a run.
one exceptiondocs/ideation/learnings.md sits above the project folders and is meant to be committed. It is the only part of this the next project reads.
a second exceptiondocs/chart/<slug>/ holds an open route map — map.md plus one file per ticket — across as many sessions as the fog takes. When the route clears, the map hands off to the interview and its tickets become contract evidence.
Where it runs
Claude Code and pi. The same skills, agents, references, and scripts in both — nothing is conditional at load time. Three things carry a translation, and each skill names it inline at the point it dispatches.
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
Install the two tools the plugin calls, then the plugin itself —pi install npm:<tool> twice, thenpi install git:github.com/nicknisi/ideation. The tools 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 thepi 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: every interactive decision point fails — if no ask-user-question tool is available, ask in plain text with lettered options and state your recommendation — never skip the question
third differenceThe engine's own stage agents take their names from the manifest, so a pi run passesagentNames and a Claude Code run omits it. The full matrix, including what does not differ, is references/harness-compat.md ↗.