@narumitw/pi-plan-mode 0.57.0 → 0.58.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 +68 -18
- package/dist/chunks/{chunk-YUFPCQVG.js → chunk-QHHHBTDO.js} +315 -362
- package/dist/chunks/chunk-QHHHBTDO.js.map +7 -0
- package/dist/chunks/{interactive-ui-M3GEZN4M.js → interactive-ui-UNJGC2RQ.js} +397 -188
- package/dist/chunks/interactive-ui-UNJGC2RQ.js.map +7 -0
- package/dist/index.ts +669 -322
- package/dist/index.ts.map +4 -4
- package/docs/command-workflows.md +1 -5
- package/docs/settings.md +26 -24
- package/package.json +1 -1
- package/src/command.ts +1 -0
- package/src/fresh-handoff-coordinator.ts +55 -0
- package/src/fresh-implementation.ts +155 -74
- package/src/implementation-models.ts +48 -0
- package/src/plan-action-controller.ts +78 -23
- package/src/plan-action-menus.ts +361 -67
- package/src/plan-mode.ts +450 -117
- package/src/saved-plan-menu.ts +7 -35
- package/src/settings-menu.ts +156 -35
- package/src/settings.ts +80 -34
- package/src/state.ts +62 -0
- package/dist/chunks/chunk-YUFPCQVG.js.map +0 -7
- package/dist/chunks/interactive-ui-M3GEZN4M.js.map +0 -7
- package/src/fresh-implementation-preferences.ts +0 -102
- package/src/implementation-options.ts +0 -127
- package/src/implementation-preferences.ts +0 -145
package/README.md
CHANGED
|
@@ -11,7 +11,7 @@ Use a Codex-like `/plan` mode to explore a codebase, resolve important questions
|
|
|
11
11
|
- Uses structured questions for important ambiguity and explicit completion for a decision-ready plan.
|
|
12
12
|
- Reviews the complete plan before implementation, export, save, further planning, or discard.
|
|
13
13
|
- Implements in the planning session or a fresh linked session with the approved plan.
|
|
14
|
-
-
|
|
14
|
+
- Configures persistent or one-shot destination model and thinking choices for fresh implementation.
|
|
15
15
|
- Restores Plan state and one saved plan across resume and compaction.
|
|
16
16
|
- Configures the Plan tool allowlist, reviewed shell commands, user-trusted subcommands, export path, plan reinjection, shortcut, and thinking level.
|
|
17
17
|
- Publishes statusline state and cooperates anonymously with Workflow Mutex Protocol v1 participants.
|
|
@@ -46,6 +46,45 @@ Install only from sources you trust because Pi extensions run with Pi's permissi
|
|
|
46
46
|
Run `/plan` to open the state-aware menu, then start Plan mode and ask the agent to inspect and design the change.
|
|
47
47
|
Run `/plan <prompt>` when the first planning request is already known.
|
|
48
48
|
|
|
49
|
+
## 🗺️ How it works
|
|
50
|
+
|
|
51
|
+
Plan mode keeps exploration and implementation on opposite sides of an explicit review boundary:
|
|
52
|
+
|
|
53
|
+
```mermaid
|
|
54
|
+
flowchart LR
|
|
55
|
+
start["Start: /plan or /plan with a prompt"]
|
|
56
|
+
start --> explore["Explore safely: inspect and clarify"]
|
|
57
|
+
explore --> complete["Complete the plan with plan_mode_complete"]
|
|
58
|
+
complete --> review["Review the ready plan"]
|
|
59
|
+
review -->|Revise| explore
|
|
60
|
+
review -->|Implement here| current["Current session: planning context retained"]
|
|
61
|
+
review -->|Start fresh| fresh["Fresh session: approved plan transferred"]
|
|
62
|
+
review -->|Save| saved["Saved for later"]
|
|
63
|
+
review -->|Export| exported["Markdown file"]
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
During planning, the agent can inspect the project and ask material questions, but Plan mode blocks editing tools and unsafe shell forms. Implementation starts only after the plan is complete and you choose a handoff:
|
|
67
|
+
|
|
68
|
+
```mermaid
|
|
69
|
+
sequenceDiagram
|
|
70
|
+
actor User
|
|
71
|
+
participant Pi
|
|
72
|
+
participant Plan as Plan mode
|
|
73
|
+
participant Work as Implementation
|
|
74
|
+
|
|
75
|
+
User->>Pi: Start planning
|
|
76
|
+
Pi->>Plan: Apply the configured Plan tool policy
|
|
77
|
+
Plan->>User: Ask material questions when needed
|
|
78
|
+
User-->>Plan: Answer or refine the request
|
|
79
|
+
Plan->>Pi: Submit the complete plan
|
|
80
|
+
Pi-->>User: Show the ready-plan review
|
|
81
|
+
alt Implement here
|
|
82
|
+
Pi->>Work: Restore Normal mode in the current session
|
|
83
|
+
else Start fresh and implement
|
|
84
|
+
Pi->>Work: Create a fresh session with the approved plan
|
|
85
|
+
end
|
|
86
|
+
```
|
|
87
|
+
|
|
49
88
|
## 💬 Commands
|
|
50
89
|
|
|
51
90
|
| Command | Purpose |
|
|
@@ -58,11 +97,12 @@ Run `/plan <prompt>` when the first planning request is already known.
|
|
|
58
97
|
| `/plan finalize` | Ask the active planner to finish or ask one remaining material question. |
|
|
59
98
|
| `/plan implement` | Implement a completed or saved plan in this session, without a selector. |
|
|
60
99
|
| `/plan save` | Save a ready plan in this Pi session and leave Plan mode. |
|
|
100
|
+
| `/plan settings` | Open the same Plan Settings screen available from the menus. |
|
|
61
101
|
| `/plan export [path]` | Write a ready, saved, or active implementation plan to Markdown. |
|
|
62
102
|
| `/plan exit` (alias: `off`) | Leave Plan mode and discard its ready plan, or clear a saved/active plan. |
|
|
63
103
|
|
|
64
104
|
All routes support TUI and RPC.
|
|
65
|
-
Print and JSON modes reject the menu and `
|
|
105
|
+
Print and JSON modes reject the menu, `tools`, and `settings`; stored-plan display and implementation have [additional mode restrictions](#-planning-and-implementation).
|
|
66
106
|
Exact subcommand words select routes; other text is a planning prompt, so `/plan start a migration` sends a prompt rather than rejecting trailing text.
|
|
67
107
|
There is no startup flag.
|
|
68
108
|
|
|
@@ -151,16 +191,24 @@ Empty, malformed, unclosed, or multiple legacy blocks keep Plan mode active and
|
|
|
151
191
|
|
|
152
192
|
After completion, `/plan` opens the ready actions when interactive UI is available.
|
|
153
193
|
The same flat menu shows **Implement here** and **Start fresh and implement**, explains which conversation context each choice uses, and previews the selected **Plan reinjection** policy.
|
|
154
|
-
**Implementation options…** stages model and thinking choices for either action in that menu; `/plan implement` uses saved defaults.
|
|
155
|
-
Choices take effect only when implementation starts and do not change Pi's global defaults.
|
|
156
|
-
After kickoff, run settlement, user abort, and active-plan clearing do not restore the previous model or thinking; subsequent manual choices remain yours.
|
|
157
|
-
Implementation preferences are characterized on Pi 0.85.0; use that release or newer for this feature.
|
|
158
|
-
See [implementation preferences](./docs/settings.md#implementation-model-and-thinking) for inheritance and failure behavior.
|
|
159
|
-
|
|
160
|
-
Selecting another provider with **Implement here** sends the retained planning conversation to that provider.
|
|
161
|
-
Fresh implementation transfers only the approved plan plus the destination's normal resources.
|
|
162
194
|
**Implement here**—and the compatibility route `/plan implement`—appends the Normal contract, lifts the Plan runtime policy, captures the reinjection setting, and starts implementation in the current session with its complete planning conversation and tool calls.
|
|
163
|
-
**Start fresh and implement**
|
|
195
|
+
**Start fresh and implement** opens a settings page before replacement.
|
|
196
|
+
Its searchable model list snapshots the session's scoped models when configured, otherwise Pi's currently available models, and shows each provider, model ID, and friendly name.
|
|
197
|
+
Pi 0.80.6–0.82.1 does not expose session model scopes to extensions, so the list uses all currently available models on those releases.
|
|
198
|
+
One-shot provider and model identifiers are limited to 512 characters each; longer custom identifiers are rejected before the source session is replaced.
|
|
199
|
+
The model and thinking rows start from the persistent **Fresh model** and **Fresh thinking** defaults; when either setting is omitted, they show the planning session's current value with **same as plan** and carry it into the fresh session independently.
|
|
200
|
+
The fixed thinking choices are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.
|
|
201
|
+
Back navigation preserves this menu-local draft, while closing and reopening the menu restores both persistent defaults.
|
|
202
|
+
If the configured model is outside the current scope or no longer available, the row reports the fallback and uses **same as plan** without deleting the stored preference.
|
|
203
|
+
The saved-plan menu keeps its direct fresh-session action without optional rows and applies the same persistent defaults and fallback.
|
|
204
|
+
|
|
205
|
+
Starting from that settings page waits for the source session to become idle, re-resolves and authenticates an explicit model, 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.
|
|
206
|
+
The destination consumes the one-shot choices before its first provider request, applies an explicit model first, and then applies explicit thinking.
|
|
207
|
+
Concurrent prompts that arrive while those choices are being applied are queued as follow-ups behind the kickoff prompt.
|
|
208
|
+
If durable consumption blocks the kickoff, the handoff reports a partial start and restores a conversation-history prompt to the editor instead of reporting success.
|
|
209
|
+
Changing only the model keeps the planning thinking level; changing only the thinking level keeps the planning model.
|
|
210
|
+
If Pi clamps an unsupported thinking level, the extension reports the effective level.
|
|
211
|
+
If the chosen model disappears or loses authentication after source preflight, the destination reports the race, consumes the intent without retrying it later, and continues with its default model.
|
|
164
212
|
The destination still loads its normal `AGENTS.md`, skills, project resources, and extensions.
|
|
165
213
|
Choosing **Export plan…** asks for a destination, writes the plan, appends the Normal contract, restores inherited thinking, and leaves Plan mode without starting a model turn or changing active tools.
|
|
166
214
|
Choosing **Save for later**—or running `/plan save`—instead stores one plan in the current Pi session before leaving Plan mode.
|
|
@@ -171,6 +219,8 @@ Resume it later to inspect or hand off the ready/saved plan again; this delibera
|
|
|
171
219
|
In-memory sessions create an unlinked fresh session because no parent file exists.
|
|
172
220
|
Escape, Ctrl+C, menu disposal, source replacement/shutdown, model/auth failure, or cancellation by another extension before replacement leaves the source plan unchanged.
|
|
173
221
|
Under **Off — conversation history only**, the destination receives the complete plan in its initial user prompt and does not persist active-plan state.
|
|
222
|
+
When a one-shot runtime choice exists, only that temporary non-model state is persisted and it is removed before the first request.
|
|
223
|
+
If that removal cannot be persisted, the request is not sent and can be retried after session persistence is available.
|
|
174
224
|
If that kickoff fails, the complete request remains in the destination editor and the source remains resumable.
|
|
175
225
|
Under either guaranteed-plan policy, the destination persists active-plan state before kickoff.
|
|
176
226
|
If guaranteed-plan persistence fails, the complete request is placed in the destination editor and the source remains resumable.
|
|
@@ -251,10 +301,6 @@ Only the latest active Plan contract authorizes the helpers; inactive or stale c
|
|
|
251
301
|
Plan mode does not widen a restrictive active-tool policy; start or restore fails when a required helper is unavailable.
|
|
252
302
|
Stable schemas preserve a cache-eligible prefix but cannot guarantee a hit because provider serialization, cache lifetime, minimum prefix size, implementation details, and session affinity remain external.
|
|
253
303
|
|
|
254
|
-
An explicit implementation model or thinking change is an intentional provider/cache boundary at handoff, not an ordinary-turn context rewrite.
|
|
255
|
-
Preferences and fresh-session acknowledgements are non-model state; they do not add tool schemas or leading prompt instructions.
|
|
256
|
-
Subsequent turns retain the existing append-only context behavior.
|
|
257
|
-
|
|
258
304
|
The default `thinkingLevel: "inherit"` avoids a Plan-specific reasoning-parameter change.
|
|
259
305
|
A fixed Plan thinking level remains supported, but changing reasoning parameters can prevent provider-side state reuse even when prompts and tool schemas stay stable.
|
|
260
306
|
|
|
@@ -295,19 +341,23 @@ Guaranteed coexistence with Goal requires `@narumitw/pi-goal` `0.53.0` or newer
|
|
|
295
341
|
|
|
296
342
|
## ⚙️ Settings
|
|
297
343
|
|
|
298
|
-
|
|
344
|
+
Run `/plan settings`, open **Settings** from an inactive `/plan` menu, or edit `<getAgentDir()>/pi-plan-mode.json` (normally `~/.pi/agent/pi-plan-mode.json`).
|
|
299
345
|
The optional file is read at session start and watched for changes; only an explicit save creates it.
|
|
300
346
|
|
|
301
347
|
```json
|
|
302
348
|
{
|
|
303
349
|
"thinkingLevel": "inherit",
|
|
304
350
|
"implementationPlanRetention": "clear-on-start",
|
|
351
|
+
"defaultImplementationModel": {
|
|
352
|
+
"provider": "anthropic",
|
|
353
|
+
"modelId": "claude-sonnet-4-5"
|
|
354
|
+
},
|
|
355
|
+
"defaultImplementationThinkingLevel": "high",
|
|
305
356
|
"defaultPlanExportPath": "PLAN.md"
|
|
306
357
|
}
|
|
307
358
|
```
|
|
308
359
|
|
|
309
|
-
By default, Plan mode inherits thinking, allows active safe built-ins, exports to `PLAN.md`, and relies on ordinary conversation history after implementation starts.
|
|
310
|
-
Implementation model and thinking defaults are optional Settings rows; unset values keep existing behavior, including normal restoration of Plan-specific thinking.
|
|
360
|
+
By default, Plan mode inherits thinking, allows active safe built-ins, uses the planning model and thinking level for fresh implementation, exports to `PLAN.md`, and relies on ordinary conversation history after implementation starts.
|
|
311
361
|
The shortcut is disabled unless configured.
|
|
312
362
|
Settings saves apply to later workflows; an active implementation keeps its captured reinjection policy.
|
|
313
363
|
The export destination affects the next export immediately.
|