gentle-pi 0.11.0 → 0.11.2

package/README.md

@@ -88,9 +88,9 @@ pi
 ## Quick start
 
 ```text
-/gentle-ai:status          Check package, SDD assets, OpenSpec, and global model config.
-/gentle-ai:doctor          Run read-only diagnostics for SDD assets, config, tools, and guards.
-/gentle-ai:sdd-preflight   Run or reuse the session SDD preflight explicitly.
+/gentle:status          Check package, SDD assets, OpenSpec, and global model config.
+/gentle:doctor          Run read-only diagnostics for SDD assets, config, tools, and guards.
+/gentle:sdd-preflight   Run or reuse the session SDD preflight explicitly.
 /sdd-init                  Create or refresh openspec/config.yaml.
 /gentle:models             Assign global model/effort routing to SDD/custom agents.
 /gentle:persona            Switch between gentleman and neutral persona modes.
@@ -100,7 +100,7 @@ pi
 Typical flow:
 
 1. Open Pi in your repo.
-2. Run `/gentle-ai:status`.
+2. Run `/gentle:status`.
 3. Run `/sdd-init` once per project, or when test/project capabilities change. This also runs the session SDD preflight.
 4. For a substantial change, ask Pi to use SDD. Natural-language requests are classified by the parent agent, not by brittle runtime regexes.
 5. Review the phase artifacts instead of trusting floating chat context.
@@ -119,7 +119,7 @@ The goal is not ceremony. The goal is to avoid accidental chaos. Once a task sto
 
 ### Delegation triggers
 
-`gentle-pi` keeps the parent session thin and delegates at the narrowest useful point. When the Pi Subagents extension is installed, the preferred runtime is the `subagent_*` tool family because it runs the user's configured project/global subagent definitions and preserves history/background behavior. If those tools are unavailable, the parent should fall back to Pi's native `Agent` tool or another available delegation mechanism. The requirement is delegation; the runtime is capability-dependent.
+`gentle-pi` keeps the parent session thin and delegates at the narrowest useful point. When the Pi Subagents extension is installed, the preferred runtime is the `subagent_*` tool family because it runs the user's configured project/global subagent definitions and preserves history/background behavior. Use waiting/task mode when the parent must consume the result and continue the workflow; use background mode only for independent work where parent continuation is not required. If those tools are unavailable, the parent should fall back to Pi's native `Agent` tool or another available delegation mechanism. The requirement is delegation; the runtime is capability-dependent.
 
 | Trigger                                                                                                                     | Required behavior                                                             |
 | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
@@ -228,7 +228,7 @@ Engram-only mode is different by design: Engram is working memory and does not m
 
 ## SDD preflight and project files
 
-`gentle-pi` does not require SDD agents to be copied into every project. The package ensures global Pi SDD assets exist under the Pi agent home and treats project-local files only as overrides/debug copies. Slash SDD flows such as `/sdd-*`, `/sdd-init`, and the explicit `/gentle-ai:sdd-preflight` command run a lazy preflight and ask for session-scoped SDD preferences. For natural-language requests, the parent agent decides whether the work should use SDD and must run/reuse `/gentle-ai:sdd-preflight` before continuing.
+`gentle-pi` does not require SDD agents to be copied into every project. The package ensures global Pi SDD assets exist under the Pi agent home and treats project-local files only as overrides/debug copies. Slash SDD flows such as `/sdd-*`, `/sdd-init`, and the explicit `/gentle:sdd-preflight` command run a lazy preflight and ask for session-scoped SDD preferences. For natural-language requests, the parent agent decides whether the work should use SDD and must run/reuse `/gentle:sdd-preflight` before continuing.
 
 ```text
 ~/.pi/agent/agents/sdd-*.md
@@ -246,13 +246,12 @@ The preflight choices are reused for later SDD flows in the same session:
 It does **not** overwrite existing global assets unless you explicitly run:
 
 ```text
-/gentle-ai:install-sdd --force
+/gentle:install-sdd --force
 ```
 
-Manual preflight commands:
+Manual preflight command:
 
 ```text
-/gentle-ai:sdd-preflight
 /gentle:sdd-preflight
 ```
 
@@ -356,10 +355,12 @@ A project can still override the global default with:
 
 The modal discovers:
 
-- project agents in `.pi/agents/` and `.agents/`;
-- user agents in `~/.pi/agent/agents/` and `~/.agents/`;
+- project agents in `.pi/subagents/`, `.pi/agents/`, and `.agents/`;
+- user agents in `~/.pi/agent/subagents/`, `~/.pi/agent/agents/`, and `~/.agents/`;
 - built-in agents from `pi-subagents-j0k3r` when present.
 
+When applying routing, project agents write runtime profiles to `.pi/subagents.json`; global and built-in agents write profiles to `~/.pi/agent/subagents.json`.
+
 Recommended model/effort shape:
 
 | Agent kind                 | Recommended model                                    | Recommended effort (`thinking`) |
@@ -400,8 +401,8 @@ Legacy string entries are still accepted and treated as `model`-only config.
 
 | Command                          | What it does                                                        |
 | -------------------------------- | ------------------------------------------------------------------- |
-| `/gentle-ai:status`              | Shows package, SDD asset, OpenSpec, and global model config status. |
-| `/gentle-ai:doctor`              | Runs read-only diagnostics for SDD assets, model/persona config, memory tools, and safety guards. |
+| `/gentle:status`              | Shows package, SDD asset, OpenSpec, and global model config status. |
+| `/gentle:doctor`              | Runs read-only diagnostics for SDD assets, model/persona config, memory tools, and safety guards. |
 | `/gentle:models`                 | Opens global model + effort assignment UI. Press `x` to export and `r` to restore saved routing. |
 | `/gentle:persona`                | Switches global persona mode, with project override support.        |
 | `/gentle:banner`                 | Configures startup banner rose, text logo, and color preset.        |
@@ -409,14 +410,14 @@ Legacy string entries are still accepted and treated as `model`-only config.
 | `/gentle:toggle-text-logo`       | Toggles the startup text logo.                                      |
 | `/gentle:banner-color`           | Selects a startup banner color preset.                              |
 | `/sdd-init`                      | Initializes or refreshes `openspec/config.yaml`.                    |
-| `/gentle-ai:install-sdd`         | Repairs missing global SDD runtime assets without overwriting files. |
-| `/gentle-ai:install-sdd --force` | Force-refreshes installed global SDD assets.                         |
+| `/gentle:install-sdd`         | Repairs missing global SDD runtime assets without overwriting files. |
+| `/gentle:install-sdd --force` | Force-refreshes installed global SDD assets.                         |
 | `/skill-registry:refresh`        | Regenerates `.atl/skill-registry.md`.                               |
 | `/skill-creation`                | Creates or updates an LLM-first skill using the packaged `skill-creator` contract and style guide. |
 
 Package-owned global SDD runtime assets are also refreshed automatically on session start when `gentle-pi` changes. Project-local `.pi/agents` and `.pi/chains` remain manual overrides and are never overwritten by startup refresh.
 
-Startup banner settings are global and default to the current pink rose + text logo. Supported color presets are `pink`, `cyan`, `yellow`, and `green`. The `/gentle-ai:*` aliases are also available for every banner command.
+Startup banner settings are global and default to the current pink rose + text logo. Supported color presets are `pink`, `cyan`, `yellow`, and `green`.
 
 Startup flag:
 
@@ -426,19 +427,6 @@ pi --no-skill-registry
 
 Use it when you want skills available normally but do not want Gentle AI to refresh/watch `.atl/skill-registry.md` on startup. `pi -ns` / `pi --no-skills` also skip the registry startup work because Pi is already disabling skill loading.
 
-Compatibility aliases:
-
-```text
-/gentle-ai:models
-/gentleman:models
-/gentle-ai:persona
-/gentleman:persona
-/gentle-ai:banner
-/gentle-ai:toggle-rose
-/gentle-ai:toggle-text-logo
-/gentle-ai:banner-color
-```
-
 ## Included skills
 
 - `gentle-ai` — harness discipline for controlled Pi work.

package/assets/agents/sdd-init.md

@@ -7,6 +7,7 @@ tools:
   - grep
   - glob
   - write
+  - edit
   - bash
   - mem_search
   - mem_get_observation

package/assets/orchestrator.md

@@ -82,7 +82,12 @@ Examples:
 - run tests/builds and summarize results;
 - fresh-context review.
 
-Use the configured subagent runtime when available. Prefer the `subagent_*` tools (`subagent_run`, status/result helpers) when the Pi Subagents extension is installed, because they run the user's configured project/global subagent definitions and preserve history/background behavior. Prefer `subagent_run` with `mode: "background"` for long independent exploration, implementation, tests, or review, and `mode: "task"` when the parent needs the result before continuing.
+Use the configured subagent runtime when available. Prefer the `subagent_*` tools (`subagent_run`, status/result helpers) when the Pi Subagents extension is installed, because they run the user's configured project/global subagent definitions and preserve history/background behavior.
+
+Choose subagent mode by orchestration dependency, not by task length:
+
+- Use `mode: "task"` when the parent must consume the result and continue the workflow, including SDD phases, implementation batches, verification, review gates, and any delegated work whose output determines the next action.
+- Use `mode: "background"` only for independent work where automatic parent continuation is not required. Background completion may notify the user and preserve history, but it is not a guarantee that the parent model will resume orchestration.
 
 If `subagent_*` tools are unavailable, fall back to Pi's native `Agent` tool or another available delegation mechanism. The delegation trigger remains mandatory; the fallback changes the runtime, not the requirement to delegate. If no delegation mechanism is available, stop the complex work and explain the blocker instead of silently continuing inline.
 

package/assets/sdd-orchestrator-workflow.md

@@ -55,14 +55,14 @@ Do not guess the active change. If change selection is ambiguous, ask the user a
 
 ## Lazy SDD Preflight
 
-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.
+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:sdd-preflight` before continuing.
 
 **Hard gate:** `openspec/config.yaml`, existing SDD changes, installed `.pi`/global SDD assets, or a todo named "preflight" are not session preflight. They are project context only. Do not mark SDD preflight complete, start `sdd-init`, launch SDD subagents/chains, or move to explore/proposal/spec/design/tasks until this session has either:
 
 1. an injected `## SDD Session Preflight` block, or
 2. an explicit user answer in the current conversation covering all four preflight choices below.
 
-If neither exists and `/gentle-ai:sdd-preflight` cannot be invoked from the current context, ask the four choices manually with `ask_user_question` before any SDD phase work. Treat missing Engram availability as a reason to ask/confirm artifact store, not as permission to assume defaults.
+If neither exists and `/gentle:sdd-preflight` cannot be invoked from the current context, ask the four choices manually with `ask_user_question` before any SDD phase work. Treat missing Engram availability as a reason to ask/confirm artifact store, not as permission to assume defaults.
 
 The preflight captures:
 
@@ -78,7 +78,7 @@ The package should ensure SDD assets are present as global Pi runtime assets wit
 ~/.pi/agent/chains/sdd-*.chain.md
 ```
 
-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.
+Manual install commands are recovery/debug paths, not the happy path. `/gentle:sdd-preflight` is the explicit preflight command for agent/orchestrator use. If the user explicitly changes SDD preferences later in the same session, follow the new instruction.
 
 ## Init Guard
 
@@ -132,6 +132,10 @@ skill_resolution
 
 The parent should synthesize these envelopes, not paste long raw reports unless needed.
 
+## SDD Phase Delegation Mode
+
+Launch SDD phase subagents with `subagent_run` `mode: "task"` when the parent needs the phase result to route the next step. Do not use `mode: "background"` for SDD phases that must feed continuation; background completion is a notification/history mechanism, not an orchestration resume guarantee.
+
 ## Strict TDD Forwarding
 
 For `sdd-apply` and `sdd-verify`, read `openspec/config.yaml` when present.