gentle-pi 0.2.7 → 0.3.0

package/README.md

@@ -81,7 +81,7 @@ Then start Pi in a project:
 pi
 ```
 
-On session start, `gentle-pi` installs local SDD assets without overwriting your edits.
+`gentle-pi` waits until the first SDD request in a session, then runs a one-time SDD preflight and installs local SDD assets without overwriting your edits.
 
 ## Quick start
 
@@ -147,9 +147,9 @@ For substantial work, the parent session coordinates the flow and each phase wri
 - verification reports;
 - archive notes for future agents.
 
-## Project files installed
+## SDD preflight and project files
 
-On Pi `session_start`, `gentle-pi` copies these assets if they are missing:
+`gentle-pi` does not interrupt every new session. Slash SDD flows such as `/sdd-*`, `/sdd-init`, and the explicit `/gentle-ai:sdd-preflight` command run a lazy preflight, ask for session-scoped SDD preferences, and then copy these assets if they are missing. For natural-language requests, the parent agent decides whether the work should use SDD and must run/reuse `/gentle-ai:sdd-preflight` before continuing.
 
 ```text
 .pi/agents/sdd-*.md
@@ -158,12 +158,26 @@ On Pi `session_start`, `gentle-pi` copies these assets if they are missing:
 .pi/gentle-ai/support/strict-tdd-verify.md
 ```
 
+The preflight choices are reused for later SDD flows in the same session:
+
+- execution mode: `interactive` or `auto`;
+- artifact store: `openspec`, or `engram`/`both` when callable memory tools are available;
+- PR chaining strategy: `auto-forecast`, `ask-always`, `single-pr-default`, or `force-chained`;
+- review budget line threshold.
+
 It does **not** overwrite existing files unless you explicitly run:
 
 ```text
 /gentle-ai:install-sdd --force
 ```
 
+Manual preflight commands:
+
+```text
+/gentle-ai:sdd-preflight
+/gentle:sdd-preflight
+```
+
 ## Skill registry
 
 `gentle-pi` keeps a local registry at:
@@ -246,7 +260,7 @@ Saved at:
 
 Run `/reload` or start a new Pi session after switching persona.
 
-## Model assignment
+## Model and effort assignment
 
 ```text
 /gentle:models
@@ -258,15 +272,15 @@ The modal discovers:
 - user agents in `~/.pi/agent/agents/` and `~/.agents/`;
 - built-in agents from `pi-subagents`.
 
-Recommended model shape:
+Recommended model/effort shape:
 
-| Agent kind                 | Recommended model                                    |
-| -------------------------- | ---------------------------------------------------- |
-| Explore, proposal, archive | Fast and cheap is usually enough.                    |
-| Spec, design, tasks        | Strong reasoning model.                              |
-| Apply                      | Strong coding and tool-use model.                    |
-| Verify / review            | Strong fresh-context model.                          |
-| Tiny utilities             | Inherit active/default model unless they bottleneck. |
+| Agent kind                 | Recommended model                                    | Recommended effort (`thinking`) |
+| -------------------------- | ---------------------------------------------------- | ------------------------------- |
+| Explore, proposal, archive | Fast and cheap is usually enough.                    | `off` to `low`                  |
+| Spec, design, tasks        | Strong reasoning model.                              | `medium` to `high`              |
+| Apply                      | Strong coding and tool-use model.                    | `medium` to `high`              |
+| Verify / review            | Strong fresh-context model.                          | `high`                          |
+| Tiny utilities             | Inherit active/default model unless they bottleneck. | `inherit`                       |
 
 Saved at:
 
@@ -274,12 +288,28 @@ Saved at:
 .pi/gentle-ai/models.json
 ```
 
+Config shape (per agent):
+
+```json
+{
+  "sdd-design": {
+    "model": "anthropic/claude-sonnet-4",
+    "thinking": "high"
+  },
+  "sdd-archive": {
+    "model": "openai/gpt-5-mini"
+  }
+}
+```
+
+Legacy string entries are still accepted and treated as `model`-only config.
+
 ## Commands
 
 | Command                          | What it does                                                 |
 | -------------------------------- | ------------------------------------------------------------ |
 | `/gentle-ai:status`              | Shows package, SDD asset, OpenSpec, and model config status. |
-| `/gentle:models`                 | Opens model assignment UI.                                   |
+| `/gentle:models`                 | Opens model + effort assignment UI.                          |
 | `/gentle:persona`                | Switches persona mode.                                       |
 | `/sdd-init`                      | Initializes or refreshes `openspec/config.yaml`.             |
 | `/gentle-ai:install-sdd`         | Reinstalls SDD assets without overwriting local files.       |

package/assets/orchestrator.md

@@ -177,16 +177,25 @@ proposal → spec ─┬→ tasks → apply → verify → archive
 proposal → design ┘
 ```
 
-## Automatic Setup Expectations
+## Lazy SDD Preflight
 
-On startup, the package should ensure SDD assets are present for `pi-subagents` without the user needing to remember setup commands. If assets are missing, install them non-destructively into:
+Do not ask SDD setup questions on session start. The first time the user initiates an SDD process in a Pi session, run the SDD preflight once and keep those choices for the rest of that session. Runtime trigger detection is intentionally deterministic: slash SDD flows and `/sdd-init` run preflight automatically; for natural-language requests, the parent/orchestrator decides semantically whether SDD is needed and must run/reuse `/gentle-ai:sdd-preflight` before continuing.
+
+The preflight captures:
+
+- execution mode: `interactive` or `auto`;
+- artifact store: `openspec`, `engram`, or `both` when callable memory tools are available;
+- chained PR strategy: `auto-forecast`, `ask-always`, `single-pr-default`, or `force-chained`;
+- review budget in changed lines.
+
+During that lazy preflight, the package should ensure SDD assets are present for `pi-subagents` without the user needing to remember setup commands. If assets are missing, install them non-destructively into:
 
 ```text
 .pi/agents/sdd-*.md
 .pi/chains/sdd-*.chain.md
 ```
 
-Manual commands are recovery/debug paths, not the happy path.
+Manual install commands are recovery/debug paths, not the happy path. `/gentle-ai:sdd-preflight` and `/gentle:sdd-preflight` are the explicit preflight commands for agent/orchestrator use. If the user explicitly changes SDD preferences later in the same session, follow the new instruction.
 
 ## Init Guard
 
@@ -220,7 +229,7 @@ When Engram or another callable memory package is available, the parent owns mem
 
 ## Execution Mode
 
-For substantial SDD flows, choose or ask once per change:
+Use the session's SDD preflight choice:
 
 - `interactive`: default, pause between major phases and ask whether to continue.
 - `auto`: run phases back-to-back when the user explicitly wants speed and trusts the flow.