@narumitw/pi-plan-mode 0.50.1 → 0.51.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +236 -130
- package/dist/chunks/{chunk-6SDTCIHD.ts → chunk-VMD6XCI5.ts} +605 -17
- package/dist/chunks/{chunk-6SDTCIHD.ts.map → chunk-VMD6XCI5.ts.map} +3 -3
- package/dist/chunks/{interactive-ui-JBSBPK6S.ts → interactive-ui-ROT43QBA.ts} +2 -2
- package/dist/index.ts +2 -2
- package/package.json +3 -3
- package/src/question-tool.ts +746 -18
- /package/dist/chunks/{interactive-ui-JBSBPK6S.ts.map → interactive-ui-ROT43QBA.ts.map} +0 -0
package/README.md
CHANGED
|
@@ -1,26 +1,20 @@
|
|
|
1
|
-
# 🧭 pi-plan-mode —
|
|
1
|
+
# 🧭 pi-plan-mode — Plan Before Pi Edits Code
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@narumitw/pi-plan-mode) [](https://pi.dev) [](./LICENSE)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Explore a codebase, resolve important questions, and produce an implementation-ready plan before Pi is allowed to edit files.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
This independently installable extension adds a Codex-like `/plan` collaboration mode that Pi core does not provide.
|
|
8
8
|
|
|
9
9
|
## ✨ Features
|
|
10
10
|
|
|
11
|
-
-
|
|
12
|
-
-
|
|
13
|
-
-
|
|
14
|
-
-
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
- Presents the complete plan and lets you implement with the planning conversation or start a fresh linked session carrying only the approved plan, as well as export, save, stay, or discard.
|
|
19
|
-
- Exports ready, saved, or active implementation plans with `/plan export [path]` without overwriting existing paths; the omitted-path destination is configurable, and exporting a ready plan completes and exits Plan mode.
|
|
20
|
-
- Lets each accepted plan remain active, serve only as the first implementation handoff, or clear after the first implementation run; the current retained-plan behavior remains the default.
|
|
21
|
-
- Keeps legacy `<proposed_plan>` responses compatible without advertising XML as the primary workflow.
|
|
22
|
-
- Shows Plan mode state in Pi's statusline as `plan active`, `plan ready`, `plan saved`, or `plan implementing`; `@narumitw/pi-statusline` adds the default `📝` icon unless configured otherwise.
|
|
23
|
-
- Persists Plan mode, one session-local saved plan, and active implementation state so resume and compaction retain the exact accepted plan.
|
|
11
|
+
- Starts and manages Plan mode through `/plan`, `/plan <prompt>`, or the `--plan` startup flag.
|
|
12
|
+
- Enables read-only exploration tools while blocking mutating tools and unsafe shell forms by default.
|
|
13
|
+
- Requires structured questions for important ambiguity and explicit completion for a decision-ready plan.
|
|
14
|
+
- Reviews the complete plan before implementation, export, save, continued planning, or discard.
|
|
15
|
+
- Starts implementation in the planning session or a fresh linked session with the exact approved plan.
|
|
16
|
+
- Persists Plan state and one saved plan across resume and compaction.
|
|
17
|
+
- Exposes statusline state and configurable tool visibility, export destination, handoff behavior, shortcut, and thinking level.
|
|
24
18
|
|
|
25
19
|
## 📦 Install
|
|
26
20
|
|
|
@@ -36,17 +30,21 @@ Try without installing permanently:
|
|
|
36
30
|
pi -e npm:@narumitw/pi-plan-mode
|
|
37
31
|
```
|
|
38
32
|
|
|
39
|
-
|
|
33
|
+
Build and try this package locally from the repository root:
|
|
40
34
|
|
|
41
35
|
```bash
|
|
36
|
+
npm --workspace @narumitw/pi-plan-mode run build
|
|
42
37
|
pi -e ./packages/pi-plan-mode
|
|
43
38
|
```
|
|
44
39
|
|
|
45
|
-
The package declares `dist/index.ts`, so an unbuilt local checkout must run
|
|
40
|
+
The package declares `dist/index.ts`, so an unbuilt local checkout must run the build before Pi loads the package directory.
|
|
46
41
|
|
|
47
|
-
|
|
42
|
+
## 🚀 Quick start
|
|
48
43
|
|
|
49
|
-
|
|
44
|
+
Run `/plan` to open the state-aware menu, then start Plan mode and ask the agent to inspect and design the change.
|
|
45
|
+
Run `/plan <prompt>` when the first planning request is already known.
|
|
46
|
+
|
|
47
|
+
## 💬 Commands
|
|
50
48
|
|
|
51
49
|
```text
|
|
52
50
|
/plan
|
|
@@ -61,111 +59,170 @@ The package declares `dist/index.ts`, so an unbuilt local checkout must run `npm
|
|
|
61
59
|
/plan exit
|
|
62
60
|
```
|
|
63
61
|
|
|
64
|
-
In TUI and RPC, use bare `/plan` to open the menu for the current Plan state.
|
|
65
|
-
and no plan is stored, the launch menu shows the effective next-start tools and offers **Start Plan
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
`
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
62
|
+
In TUI and RPC, use bare `/plan` to open the menu for the current Plan state.
|
|
63
|
+
When Plan mode is off and no plan is stored, the launch menu shows the effective next-start tools and offers **Start Plan mode**, **Choose tools, then start…**, **Settings**, and **How Plan mode works**.
|
|
64
|
+
Settings edits the persistent defaults for later workflows.
|
|
65
|
+
Launch-menu tool changes remain a draft until **Done — start Plan mode** is selected; Back, Escape, Ctrl+C, disposal, session replacement, and shutdown discard the draft without changing Plan state, active tools, thinking, or the stored selection.
|
|
66
|
+
|
|
67
|
+
Use `/plan start` when you want to enter Plan mode directly without sending a model message.
|
|
68
|
+
Use `/plan <prompt>` to enter Plan mode and immediately submit `<prompt>` as the first Plan-mode user message.
|
|
69
|
+
The exact argument `start` is reserved for direct activation; longer text such as `/plan start a migration` remains an inline planning prompt.
|
|
70
|
+
`--plan` also remains a direct activation path.
|
|
71
|
+
|
|
72
|
+
Use **Choose tools, then start…** or the `/plan tools` compatibility shortcut to choose a session-specific override before Planning starts.
|
|
73
|
+
Both routes use the same draft selector: **Done — start Plan mode** stores the selection and starts the workflow, while cancellation leaves Plan mode off and changes nothing.
|
|
74
|
+
The bounded multi-select shows 10 rows at a time, supports viewport paging, descriptions, and explicit unavailable rows for blocked tools.
|
|
75
|
+
In TUI mode, type to fuzzy-search tool names, descriptions, policy, and source metadata; RPC keeps the complete unfiltered list.
|
|
76
|
+
Once Plan mode is active, tools are locked: `/plan` no longer offers tool or Settings actions, and `/plan tools` rejects the request.
|
|
77
|
+
Exit and start a new workflow if a different tool set is required.
|
|
78
|
+
The `plan_mode_question` tool keeps a dedicated model-requested questionnaire instead of using command-menu navigation.
|
|
79
|
+
`/plan show` displays the stored plan without starting a model turn, including the accepted plan while implementation is active.
|
|
80
|
+
`/plan finalize` explicitly asks the agent to complete the plan or ask one remaining material question, `/plan save` stores a completed ready plan for later and leaves Plan mode, and `/plan export [path]` writes a ready, saved, or active implementation plan to Markdown.
|
|
81
|
+
Completed and saved plan menus offer **Implement here**, which continues with the planning conversation, and **Start fresh and implement**, which opens a new session and transfers only the approved plan.
|
|
82
|
+
The direct `/plan implement` compatibility route remains equivalent to **Implement here** and never opens a selector.
|
|
83
|
+
A successful ready-plan export also leaves Plan mode; saved and active implementation exports retain their existing state.
|
|
84
|
+
`show`, `save`, `export`, and `implement` fail closed when no applicable plan is stored; `finalize` requires active Plan mode.
|
|
85
|
+
|
|
86
|
+
`/plan export` uses the configured **Export destination**, which defaults to `PLAN.md`.
|
|
87
|
+
Supply a path to override that default for one export.
|
|
88
|
+
Relative paths resolve from the command's current `ctx.cwd` at export time, absolute paths remain absolute, a leading `@` is accepted for Pi path compatibility, and missing parent directories are created.
|
|
89
|
+
Explicit `/plan export <path>` input always wins over the setting.
|
|
90
|
+
Export never overwrites an existing file, directory, or symbolic link: choose another path or remove the existing target first.
|
|
91
|
+
A successful export adds one trailing newline but otherwise preserves the accepted Markdown exactly.
|
|
92
|
+
After a ready plan is written, Plan mode ends, its tools and thinking level are restored, and the ready state is cleared without starting a model turn.
|
|
93
|
+
Exporting a saved or active implementation plan leaves that state unchanged.
|
|
94
|
+
Failed or cancelled exports leave every Plan-mode state unchanged.
|
|
95
|
+
The resulting file is available to the agent through its normal file-reading tools.
|
|
96
|
+
Export is an explicit user-requested file mutation.
|
|
97
|
+
Model-initiated Plan-mode writes remain blocked.
|
|
98
|
+
|
|
99
|
+
In TUI and RPC, **Export plan…** opens a single-line path input from every ready, saved, or active plan menu.
|
|
100
|
+
The input shows both the configured value and its currently resolved path.
|
|
101
|
+
Submit an empty value to use the configured destination, or enter a relative or absolute one-off path.
|
|
102
|
+
A failed TUI export retains the draft for correction; RPC reopens its input dialog.
|
|
103
|
+
Escape returns to the owning menu without writing a file.
|
|
104
|
+
A successful ready-plan export closes the menu and ends Plan mode; saved and active implementation menus close without changing their stored state.
|
|
105
|
+
|
|
106
|
+
When Plan mode is active, ask the agent to design the change.
|
|
107
|
+
The agent may inspect files and run read-only commands, but it should not edit files or execute the implementation.
|
|
108
|
+
It should explore first, then use structured questions when your preference or a tradeoff materially changes the plan.
|
|
109
|
+
Configure persistent defaults or a one-workflow tool override before activation; Planning and ready menus deliberately keep those controls locked.
|
|
110
|
+
|
|
111
|
+
By default, Plan mode manages only Pi's built-in tools: `read`, limited `bash`, available read-only built-ins such as `grep`, `find`, and `ls`, plus the required `plan_mode_question` and `plan_mode_complete` tools.
|
|
112
|
+
Built-in `edit` and `write` are blocked.
|
|
113
|
+
`update_plan` is also blocked because it tracks execution progress rather than conversational planning.
|
|
114
|
+
Extension and custom tools are disabled by default because Pi tools do not expose standardized mutability metadata; enable them before starting from Settings or the staged workflow selector only when you accept the risk.
|
|
115
|
+
For example, you can opt into `firecrawl_scrape`, `firecrawl_search`, or `lsp_diagnostics` if those extensions are loaded and you want to use them during planning.
|
|
116
|
+
|
|
117
|
+
Limited `bash` uses a fail-closed policy, including when an extension overrides the canonical `bash` tool name.
|
|
118
|
+
It accepts common inspection commands, read-only Git and npm queries, pipelines and command lists composed entirely of accepted commands, plus selected checks such as `npm test`, `npm run typecheck`, and `cargo test`.
|
|
119
|
+
It rejects output/input redirects, shell expansion, substitutions, subshells, background jobs, mutating flags, dependency changes, editors, and unknown commands.
|
|
120
|
+
A rejected parsed command list or pipeline identifies its first blocked command segment; malformed or unsupported shell syntax reports the complete submitted input instead.
|
|
121
|
+
Tests and builds may still write ignored caches or build artifacts and may execute project-defined hooks; enable or invoke them only when the repository is trusted.
|
|
122
|
+
This is extension-level risk reduction, not an OS sandbox.
|
|
123
|
+
|
|
124
|
+
`plan_mode_question` follows Codex's `request_user_input` pattern: the agent can ask 1-3 concise questions, each with meaningful options and a free-form Other path.
|
|
125
|
+
In TUI mode, one question appears at a time with question tabs and a final Review tab.
|
|
126
|
+
Use Tab, Shift+Tab, left, or right to visit any question or Review, including unanswered future questions.
|
|
127
|
+
Use up and down to choose an option, Enter to record it and advance, or `n` to record the highlighted option and open its optional note editor. Press `n` again on an answered item to edit or clear its note.
|
|
128
|
+
Revisit a question to replace its answer; changing the chosen option clears its prior note.
|
|
129
|
+
Review lists every answer and note, lets up and down select an answer for note editing, and submits the ordered payload only after every question is answered.
|
|
130
|
+
Custom answers and notes retain their raw submitted text in the tool result, while terminal rendering is sanitized.
|
|
131
|
+
The TUI rejects either field above 4,000 characters instead of truncating it.
|
|
132
|
+
RPC keeps the existing sequential `select` and `editor` dialogs because Pi RPC cannot render custom TUI components.
|
|
133
|
+
If you cancel or no interactive UI is available, the agent should ask a concise plain-text question or proceed only with a clearly stated low-risk assumption instead of prematurely producing a final plan.
|
|
134
|
+
|
|
135
|
+
Pi activates tools by tool name.
|
|
136
|
+
The pre-start selector stores accepted session selections by name and shows each effective tool's source from Pi metadata, such as `built-in`, a user extension path, or a project extension path.
|
|
137
|
+
If an extension overrides a built-in tool with the same name, Pi exposes the effective tool for that name and the selector shows that source.
|
|
138
|
+
|
|
139
|
+
A complete Plan mode answer should appear only after the agent has resolved discoverable facts and high-impact user decisions.
|
|
140
|
+
The agent must call `plan_mode_complete({ plan })` alone as its final action, passing the complete Markdown plan.
|
|
141
|
+
The tool rejects empty or whitespace-only plans and plans longer than 50,000 JavaScript characters; it does not truncate.
|
|
142
|
+
Its visible result contains the full plan, and versioned result details let the extension restore it safely from the active session branch.
|
|
143
|
+
|
|
144
|
+
`plan_mode_complete` uses Pi's `terminate: true` hint.
|
|
145
|
+
Termination is best effort: if a model puts it in a parallel tool batch, Pi terminates the batch early only when every finalized sibling tool also terminates.
|
|
146
|
+
The prompt therefore requires the completion call to be standalone and last.
|
|
147
|
+
The extension deliberately does not infer completion from phrases such as “I will present the plan,” and it does not automatically retry a turn with no plan because research and clarification turns may legitimately remain unfinished.
|
|
148
|
+
If a turn ends without a plan, Plan mode stays active; use `/plan finalize` for explicit recovery.
|
|
149
|
+
|
|
150
|
+
Legacy sessions and models may still submit one non-empty `<proposed_plan>` block with tags on their own lines.
|
|
151
|
+
That compatibility path remains accepted, but it is not the primary workflow.
|
|
152
|
+
Empty, malformed, unclosed, or multiple legacy blocks keep Plan mode active and produce a warning.
|
|
153
|
+
|
|
154
|
+
After completion, `/plan` opens the ready actions when interactive UI is available.
|
|
155
|
+
The same flat menu shows **Implement here** and **Start fresh and implement**, explains which conversation context each choice uses, and previews how long the approved plan will remain active.
|
|
156
|
+
**Implement here**—and the compatibility route `/plan implement`—disables Plan mode, restores full tool access, captures the current **After Implement** policy, and starts implementation in the current session with its planning conversation.
|
|
157
|
+
**Start fresh and implement** waits for the source session to become idle, verifies the selected model and authentication, creates a new session linked to the persisted source as its parent, and transfers the exact approved plan without copying planning messages, tool results, or compaction/branch summaries.
|
|
158
|
+
The destination still loads its normal `AGENTS.md`, skills, project resources, and extensions.
|
|
159
|
+
Choosing **Export plan…** asks for a destination, writes the plan, restores normal tools and thinking, and leaves Plan mode without starting a model turn.
|
|
160
|
+
Choosing **Save for later**—or running `/plan save`—instead stores one plan in the current Pi session before leaving Plan mode.
|
|
161
|
+
|
|
162
|
+
When a workflow was started only with `--plan` and no `/plan` command has run in that session, the automatic menu cannot obtain Pi's command-only session replacement capability; choosing fresh asks you to reopen `/plan`, where the same action is available.
|
|
163
|
+
A successful fresh handoff does not delete or consume the source planning session.
|
|
164
|
+
Resume it later to inspect or hand off the ready/saved plan again; this deliberate duplication is the recovery path if the destination work is abandoned.
|
|
165
|
+
In-memory sessions create an unlinked fresh session because no parent file exists.
|
|
166
|
+
Escape, Ctrl+C, menu disposal, source replacement/shutdown, model/auth failure, or cancellation by another extension before replacement leaves the source plan unchanged.
|
|
167
|
+
Once replacement succeeds, the destination persists active-plan state before kickoff.
|
|
168
|
+
If persistence fails, the complete request is placed in the destination editor and the source remains resumable.
|
|
169
|
+
If kickoff fails, the destination retains the active plan; send a message to continue, use `/plan exit` to clear it, or resume the parent planning session.
|
|
170
|
+
|
|
171
|
+
A saved plan appears as `plan saved` and remains available after reload, resume, branch-local fork, and compaction in that session.
|
|
172
|
+
It does not expire automatically, cross into a new session, or participate in ordinary model context.
|
|
173
|
+
Open `/plan` to Show, Implement here, Start fresh and implement, Export, open Settings, or Clear it; `/plan show`, `/plan implement`, `/plan export [path]`, and `/plan exit`/`off` retain their direct routes in TUI and RPC.
|
|
174
|
+
Fresh implementation checks idle state, the selected model, and authentication before session replacement; Implement here keeps its established preflight behavior.
|
|
175
|
+
Starting another workflow with `/plan start`, `/plan <prompt>`, or `/plan tools` is blocked until the saved plan is implemented or cleared, so the single saved slot is never silently overwritten.
|
|
176
|
+
Resuming that session with `--plan` moves the saved plan back to ready Plan mode.
|
|
177
|
+
Cancellation or failed implementation preflight leaves it unchanged.
|
|
178
|
+
|
|
179
|
+
Text print and JSON modes cannot display the bare `/plan` menu and reject that route before changing state; use `/plan start` for direct no-prompt activation or `/plan <prompt>` to start planning with a prompt.
|
|
180
|
+
`/plan tools` also rejects before changing state because its staged selector requires TUI or RPC.
|
|
181
|
+
These modes can export any stored plan with `/plan export [path]`, save a ready plan with `/plan save`, and clear it with `/plan exit` or `/plan off`.
|
|
182
|
+
Successful export is observable through the created file; exporting a ready plan also leaves Plan mode, while saved and active implementation state remains unchanged.
|
|
183
|
+
An existing target or missing plan fails the command without changing state.
|
|
184
|
+
These modes reject saved-plan display and implementation before changing state because Pi provides neither printable custom-message output nor acknowledged extension-triggered turns; resume the session in TUI or RPC to show or implement it.
|
|
185
|
+
|
|
186
|
+
Both implementation paths apply the current **After Implement** policy in their destination; the fresh-session choice does not change retention semantics.
|
|
187
|
+
With the default **Keep plan active** policy, the exact accepted plan remains active across later turns, session resume, and manual or automatic compaction without depending on the compaction summary.
|
|
188
|
+
Plan mode avoids a duplicate context block while the original implementation handoff remains available and injects one hidden canonical copy after that handoff is compacted away.
|
|
189
|
+
This can consume up to the existing 50,000-character plan limit in model context when reinjection is needed.
|
|
190
|
+
**Use plan for handoff only** clears retained state immediately after the first implementation request receives the complete plan.
|
|
191
|
+
**Clear after first implementation run** keeps the plan through that run, including retries, compaction retries, and queued continuation, then clears it at `agent_settled`.
|
|
192
|
+
Cleanup is bound to the matching implementation, so an older run settling cannot clear a newer handoff.
|
|
193
|
+
|
|
194
|
+
While implementation is active, `/plan show` displays the accepted plan.
|
|
195
|
+
Interactive `/plan` offers Show, Export plan…, Settings, Start a new plan, and Clear; `/plan exit` and `/plan off` are the direct clear routes.
|
|
196
|
+
Settings changes never alter the policy already captured by the active implementation.
|
|
197
|
+
Automatic cleanup has the same observable result as clearing: its active status and future injected plan context disappear, while the implementation request that triggered cleanup still receives the complete plan.
|
|
198
|
+
Starting a new Plan-mode workflow or implementing a replacement plan supersedes the previous active plan.
|
|
199
|
+
The extension deliberately does not infer completion from assistant prose or agent settlement, so clear the active plan when the implementation no longer applies.
|
|
200
|
+
Choosing Stay before implementation keeps the plan ready.
|
|
201
|
+
Revision feedback starts another Plan-mode turn and clears the previous implementable plan until an updated completion arrives.
|
|
202
|
+
For clarification-only follow-ups, the agent answers and resubmits the complete unchanged plan so it remains implementable.
|
|
203
|
+
Before saving or implementation, exit/off discards the ready plan and removes its completion result from later non-Plan model context.
|
|
204
|
+
|
|
205
|
+
While Plan mode is enabled, the extension also publishes a compact status for Pi statuslines.
|
|
206
|
+
With `@narumitw/pi-statusline`, this appears in the extension status area:
|
|
157
207
|
|
|
158
208
|
- `plan active`: Plan mode is enabled and still gathering context or drafting a plan.
|
|
159
209
|
- `plan ready`: A completed plan is stored until you implement it, export it, save it, continue planning, or exit Plan mode.
|
|
160
210
|
- `plan saved`: One completed plan is stored outside model context in the current session until you implement or clear it.
|
|
161
211
|
- `plan implementing`: The exact accepted plan is currently retained under its captured **After Implement** policy.
|
|
162
212
|
|
|
163
|
-
You can also exit directly.
|
|
213
|
+
You can also exit directly.
|
|
214
|
+
Before implementation, direct exit discards the latest proposed plan; while a plan is saved, it clears that saved plan.
|
|
215
|
+
During implementation, it removes both the original implementation handoff and the extension's canonical active-plan block from later model calls; an earlier Pi-generated compaction summary may still describe prior work:
|
|
164
216
|
|
|
165
217
|
```text
|
|
166
218
|
/plan exit
|
|
167
219
|
```
|
|
168
220
|
|
|
221
|
+
## 🛠️ Tools
|
|
222
|
+
|
|
223
|
+
- `plan_mode_question` asks up to three structured questions, supports optional answer notes, and reviews the ordered result before TUI submission.
|
|
224
|
+
- `plan_mode_complete` records the complete approved Markdown plan and terminates the planning turn when called alone.
|
|
225
|
+
|
|
169
226
|
## ⚙️ Settings
|
|
170
227
|
|
|
171
228
|
Open **Settings** from an inactive `/plan` menu to edit one flat group of five workflow choices: **Plan thinking**, **Plan tools**, **After Implement**, **Export destination**, and **Plan mode shortcut**.
|
|
@@ -190,23 +247,48 @@ When omitted, the shortcut is disabled by default.
|
|
|
190
247
|
|
|
191
248
|
### Default Plan tools
|
|
192
249
|
|
|
193
|
-
`defaultPlanTools` defines the initial tool selection when a session has no stored pre-start selection.
|
|
250
|
+
`defaultPlanTools` defines the initial tool selection when a session has no stored pre-start selection.
|
|
251
|
+
Omit it—or choose **Use automatic safe built-ins**—to keep the available safe built-ins as the default.
|
|
252
|
+
An explicit empty array appears as **Required tools only** and enables only `plan_mode_question` and `plan_mode_complete`.
|
|
194
253
|
|
|
195
|
-
Tool names must be non-empty strings; duplicates are removed in first-seen order.
|
|
254
|
+
Tool names must be non-empty strings; duplicates are removed in first-seen order.
|
|
255
|
+
Unknown, unavailable, and Plan-mode-blocked names are ignored when tools are activated.
|
|
256
|
+
Settings retains configured unavailable names and shows them as unavailable; resetting to automatic removes the entire override.
|
|
257
|
+
A tool registered after Plan mode is already active is not added automatically; exit and start a new Plan workflow to apply another set.
|
|
258
|
+
Non-built-in tools named in this global setting are an explicit user-risk opt-in, just like selecting them in the pre-start workflow selector.
|
|
259
|
+
Plan mode does not interpret their arguments or actions: enabling one trusts the whole effective tool.
|
|
260
|
+
Pi resolves tools by name, so if an extension overrides a built-in name, the effective extension tool is selected instead.
|
|
261
|
+
An effective tool named `bash` remains subject to the limited-shell policy regardless of its source metadata.
|
|
196
262
|
|
|
197
|
-
A selection accepted through **Choose tools, then start…** or `/plan tools` is stored in that Pi session and takes precedence over `defaultPlanTools` when the session resumes.
|
|
263
|
+
A selection accepted through **Choose tools, then start…** or `/plan tools` is stored in that Pi session and takes precedence over `defaultPlanTools` when the session resumes.
|
|
264
|
+
The global setting remains the baseline for fresh sessions and sessions without an explicit selection.
|
|
265
|
+
Settings saves immediately, but the saved tools and thinking level apply only when a later Plan workflow starts; they never mutate a workflow already in progress.
|
|
198
266
|
|
|
199
267
|
### After Implement
|
|
200
268
|
|
|
201
|
-
`implementationPlanRetention` controls the result of the next Implement action.
|
|
269
|
+
`implementationPlanRetention` controls the result of the next Implement action.
|
|
270
|
+
Omit it or use `keep` for **Keep plan active**, the backward-compatible behavior that retains and reinjects the exact plan until `/plan exit` or supersession.
|
|
271
|
+
Use `clear-on-start` for **Use plan for handoff only**: the first matching implementation request receives the complete plan, then retained state clears before later requests.
|
|
272
|
+
Use `clear-after-first-run` to retain the plan until that implementation's first fully settled run ends.
|
|
273
|
+
A resumed cleanup policy re-arms against the first context in the replacement session.
|
|
274
|
+
Failed handoff delivery restores the ready or saved plan and does not run automatic cleanup.
|
|
202
275
|
|
|
203
|
-
Changing this setting applies to the next Implement action only.
|
|
276
|
+
Changing this setting applies to the next Implement action only.
|
|
277
|
+
Each active implementation stores its effective policy, so a later Settings save cannot shorten or extend an implementation already in progress.
|
|
278
|
+
`/plan exit` remains available under every policy.
|
|
204
279
|
|
|
205
280
|
### Export destination
|
|
206
281
|
|
|
207
|
-
`defaultPlanExportPath` controls only exports that omit a path.
|
|
282
|
+
`defaultPlanExportPath` controls only exports that omit a path.
|
|
283
|
+
Omit it—or submit an empty value in Settings—to use `PLAN.md`.
|
|
284
|
+
The value must be a non-empty string of at most 4,096 characters without terminal control characters or NUL.
|
|
285
|
+
Relative values are resolved against the current working directory at export time; the Settings detail and every export input preview the concrete resolved destination.
|
|
286
|
+
An explicit `/plan export <path>` is a one-off override and does not edit Settings.
|
|
287
|
+
Saving a new destination affects the next export immediately, including export of a currently active implementation.
|
|
208
288
|
|
|
209
|
-
The existing no-overwrite, cancellation, and atomic Plan-state behavior is unchanged.
|
|
289
|
+
The existing no-overwrite, cancellation, and atomic Plan-state behavior is unchanged.
|
|
290
|
+
A failed save rolls the row back to its previous value; a failed or cancelled export preserves the plan and target.
|
|
291
|
+
Long previews wrap or truncate to the available terminal width without changing the raw path used by the action.
|
|
210
292
|
|
|
211
293
|
### Toggle shortcut
|
|
212
294
|
|
|
@@ -217,12 +299,17 @@ Avoid values that conflict with editor shortcuts.
|
|
|
217
299
|
|
|
218
300
|
### Safe shell subcommands
|
|
219
301
|
|
|
220
|
-
`safeSubcommands` adds reviewed command validators to limited `bash`; it is not a raw shell allowlist.
|
|
302
|
+
`safeSubcommands` adds reviewed command validators to limited `bash`; it is not a raw shell allowlist.
|
|
303
|
+
Only the following exact values are accepted:
|
|
221
304
|
|
|
222
305
|
- `git`: `status`, `log`, `diff`, `show`, `branch`, `remote`, `ls-files`, `grep`, `rev-parse`, `blame`, `describe`, `merge-base`, `ls-tree`, and `cat-file`.
|
|
223
306
|
- `gh`: `pr view`, `pr list`, `issue view`, and `issue list`.
|
|
224
307
|
|
|
225
|
-
The first eight Git validators are built in and remain enabled when omitted, so listing them is valid but redundant.
|
|
308
|
+
The first eight Git validators are built in and remain enabled when omitted, so listing them is valid but redundant.
|
|
309
|
+
The other six Git validators and every `gh` path require an explicit opt-in.
|
|
310
|
+
Git entries select one exact subcommand; `gh` entries select one exact two-word path, so `"pr view"` never enables `pr merge`, `pr close`, or `pr edit`.
|
|
311
|
+
Omitted `safeSubcommands`, an empty object, and empty arrays preserve the default policy.
|
|
312
|
+
Duplicate values are removed in first-seen order.
|
|
226
313
|
|
|
227
314
|
With the example configuration above, commands such as these are accepted:
|
|
228
315
|
|
|
@@ -252,17 +339,34 @@ gh pr view 218 > pr.txt
|
|
|
252
339
|
gh pr list --json number,title && gh pr merge 218
|
|
253
340
|
```
|
|
254
341
|
|
|
255
|
-
Redirects, shell expansion and substitution, explicit pager or browser requests, explicit external diff/textconv/filter/signature helpers, output flags, malformed command layouts, and any chain containing an unsafe segment fail closed.
|
|
342
|
+
Redirects, shell expansion and substitution, explicit pager or browser requests, explicit external diff/textconv/filter/signature helpers, output flags, malformed command layouts, and any chain containing an unsafe segment fail closed.
|
|
343
|
+
Read-dominant Git validators accept ordinary inspection flags without requiring `--no-textconv` or `--no-ext-diff`; Git may therefore invoke a helper configured by the user or trusted repository even when the command does not request one explicitly.
|
|
344
|
+
Use the negative flags when you want to suppress those configured helpers.
|
|
345
|
+
Mixed read/write surfaces remain narrower: use `git remote show -n` to avoid invoking a transport helper, while mutating `branch` and `remote` forms remain blocked.
|
|
346
|
+
GitHub CLI read paths require `--json <fields>` output so Plan mode does not rely on `GH_PAGER`, `PAGER`, or gh pager configuration.
|
|
347
|
+
Unknown `safeSubcommands` keys or values, non-array values, and non-string entries invalidate the entire settings file and trigger the normal warning/default fallback on session start.
|
|
256
348
|
|
|
257
|
-
Read-only does not mean private: Git inspection can expose repository history and tracked secrets, while `gh` queries can expose remote repository, pull request, and issue data available to your authenticated account.
|
|
349
|
+
Read-only does not mean private: Git inspection can expose repository history and tracked secrets, while `gh` queries can expose remote repository, pull request, and issue data available to your authenticated account.
|
|
350
|
+
The policy reduces accidental mutation and explicit helper execution; it is not a sandbox or a confidentiality boundary.
|
|
258
351
|
|
|
259
352
|
### Thinking level
|
|
260
353
|
|
|
261
|
-
Plan mode inherits Pi's current thinking level by default.
|
|
354
|
+
Plan mode inherits Pi's current thinking level by default.
|
|
355
|
+
Set `thinkingLevel` to request a fixed level only while Plan mode is active.
|
|
356
|
+
Supported values are `inherit`, `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.
|
|
357
|
+
The extension snapshots the prior level and restores it on exit only if the level still matches the value it applied; a manual change made during Plan mode is preserved.
|
|
358
|
+
A Settings save does not change Pi's current or default thinking level and takes effect only when the next Plan workflow starts.
|
|
262
359
|
|
|
263
|
-
Settings saves are serialized in invocation order inside one Pi process.
|
|
360
|
+
Settings saves are serialized in invocation order inside one Pi process.
|
|
361
|
+
Each save re-reads the latest valid document, preserves unknown top-level fields and unedited `safeSubcommands`, then publishes through a same-directory temporary file and rename.
|
|
362
|
+
A missing file stays absent until an explicit save.
|
|
363
|
+
Invalid JSON, invalid values, oversized content, non-regular files, and read failures make Settings read-only; the existing bytes and previous effective settings remain.
|
|
364
|
+
This in-process queue is not a cross-process lock, so concurrent separate Pi processes can still race.
|
|
264
365
|
|
|
265
|
-
Invalid settings produce a warning and fall back to inherited thinking, available safe-built-in tool defaults, `keep`, and `PLAN.md`.
|
|
366
|
+
Invalid settings produce a warning and fall back to inherited thinking, available safe-built-in tool defaults, `keep`, and `PLAN.md`.
|
|
367
|
+
Compatibility: a valid legacy `plan-mode.json` remains readable with a warning and is never modified automatically.
|
|
368
|
+
If Settings is explicitly saved while only that legacy file exists, the extension creates canonical `pi-plan-mode.json` from the complete legacy document, applies the selected change, preserves unknown fields, and leaves the legacy file untouched.
|
|
369
|
+
If both files exist, the canonical filename takes precedence.
|
|
266
370
|
|
|
267
371
|
## 🧠 Codex-like behavior
|
|
268
372
|
|
|
@@ -295,7 +399,8 @@ packages/pi-plan-mode/
|
|
|
295
399
|
└── package.json
|
|
296
400
|
```
|
|
297
401
|
|
|
298
|
-
`index.ts` is the Pi entrypoint and forwards to `plan-mode.ts`; the other source modules are internal.
|
|
402
|
+
`index.ts` is the Pi entrypoint and forwards to `plan-mode.ts`; the other source modules are internal.
|
|
403
|
+
The package exposes its Pi extension through `package.json`:
|
|
299
404
|
|
|
300
405
|
```json
|
|
301
406
|
{
|
|
@@ -313,4 +418,5 @@ Pi extension, Pi coding agent, plan mode, Codex-like plan mode, AI coding workfl
|
|
|
313
418
|
|
|
314
419
|
## 📄 License
|
|
315
420
|
|
|
316
|
-
MIT.
|
|
421
|
+
MIT.
|
|
422
|
+
See [`LICENSE`](./LICENSE).
|