gentle-pi 0.1.23 → 0.2.1

package/README.md

@@ -25,6 +25,8 @@ Follow the project and the community around it:
 - YouTube: [Gentleman Programming](https://www.youtube.com/c/GentlemanProgramming)
 - Community Discord: [Gentleman Programming](https://discord.com/invite/gentleman-programming-769863833996754944)
 
+Startup intro collaboration: thanks to [@aporcelli](https://github.com/aporcelli) for [`pi-gentle-startup`](https://github.com/aporcelli/pi-gentle-startup), which inspired the clean-screen startup animation, compact runtime panel, and pink visual treatment.
+
 ## The problem
 
 Most coding-agent sessions fail for operational reasons, not model reasons:
@@ -41,18 +43,19 @@ Most coding-agent sessions fail for operational reasons, not model reasons:
 
 ## What it adds
 
-| Capability                     | What it does                                                                                                                         |
-| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
-| **el Gentleman persona**       | Makes Pi behave like a senior architect and teacher, not a generic chatbot. Spanish responses use Rioplatense voseo by default.      |
-| **Work routing discipline**    | Small tasks stay inline. Context-heavy exploration can be delegated. Large or risky changes go through SDD/OpenSpec.                 |
-| **SDD/OpenSpec assets**        | Installs phase agents and chains for `init`, `explore`, `proposal`, `spec`, `design`, `tasks`, `apply`, `verify`, and `archive`.     |
-| **Subagent orchestration**     | Keeps one parent session responsible while child agents explore, implement, test, or review with focused context.                    |
-| **Strict TDD support**         | When project config declares a test command, apply/verify phases must record RED → GREEN → TRIANGULATE → REFACTOR evidence.          |
-| **Reviewer protection**        | Surfaces review workload risk before a task turns into an oversized PR.                                                              |
-| **Per-agent model assignment** | Pi-native modal for assigning stronger or cheaper models to specific SDD/custom agents.                                              |
-| **Skill discovery registry**   | Maintains `.atl/skill-registry.md` from project and user skills so review/comment/PR workflows do not silently miss the right skill. |
-| **Delivery skills**            | Includes issue-first PRs, chained PRs, work-unit commits, cognitive docs, comment writing, and Judgment Day review.                  |
-| **Shell safety**               | Blocks destructive shell commands and asks for confirmation for sensitive operations.                                                |
+| Capability                     | What it does                                                                                                                                  |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| **el Gentleman persona**       | Makes Pi behave like a senior architect and teacher, not a generic chatbot. Spanish responses use Rioplatense voseo by default.               |
+| **Rose startup intro**         | Adds a pink rose fade-in, compact project/runtime panel, and visible startup collaboration credit for @aporcelli's `pi-gentle-startup` ideas. |
+| **Work routing discipline**    | Small tasks stay inline. Context-heavy exploration can be delegated. Large or risky changes go through SDD/OpenSpec.                          |
+| **SDD/OpenSpec assets**        | Installs phase agents and chains for `init`, `explore`, `proposal`, `spec`, `design`, `tasks`, `apply`, `verify`, and `archive`.              |
+| **Subagent orchestration**     | Keeps one parent session responsible while child agents explore, implement, test, or review with focused context.                             |
+| **Strict TDD support**         | When project config declares a test command, apply/verify phases must record RED → GREEN → TRIANGULATE → REFACTOR evidence.                   |
+| **Reviewer protection**        | Surfaces review workload risk before a task turns into an oversized PR.                                                                       |
+| **Per-agent model assignment** | Pi-native modal for assigning stronger or cheaper models to specific SDD/custom agents.                                                       |
+| **Skill discovery registry**   | Maintains `.atl/skill-registry.md` from project and user skills so review/comment/PR workflows do not silently miss the right skill.          |
+| **Delivery skills**            | Includes issue-first PRs, chained PRs, work-unit commits, cognitive docs, comment writing, and Judgment Day review.                           |
+| **Shell safety**               | Blocks destructive shell commands and asks for confirmation for sensitive operations.                                                         |
 
 ## Install
 
@@ -107,7 +110,27 @@ Typical flow:
 | Unknown codebase area or context-heavy investigation                        | Focused subagent delegation. |
 | Large, ambiguous, architectural, product-facing, or high-review-risk change | SDD/OpenSpec flow.           |
 
-The goal is not ceremony. The goal is to avoid accidental chaos.
+The goal is not ceremony. The goal is to avoid accidental chaos. Once a task stops being small, delegation is expected rather than optional.
+
+### Delegation triggers
+
+`gentle-pi` keeps the parent session thin and uses subagents at the narrowest useful point:
+
+| Trigger                                                                                                                     | Expected behavior                                                    |
+| --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| Reading 4+ files to understand a flow                                                                                       | Launch `scout` or `context-builder` and synthesize its handoff.      |
+| Touching 2+ non-trivial code files                                                                                          | Use one `worker`, or require fresh review before completion.         |
+| Commit, push, or PR after code changes                                                                                      | Run a fresh-context `reviewer` unless the diff is trivial docs/text. |
+| Wrong cwd, worktree/git accident, merge recovery, confusing test/env issue                                                  | Stop and run a fresh audit reviewer before continuing.               |
+| Long monolithic session with accumulating complexity, roughly 20 tool calls, 5 exploratory reads, or 2 non-mechanical edits | Pause and delegate or explain why not.                               |
+
+The intended balanced loop for a bounded bugfix is:
+
+```text
+parent git/status + clarify → scout when context-heavy → one worker writes → fresh reviewer audits → parent validates and reports
+```
+
+Fresh reviewers are intentionally not token-saving devices; they buy independent judgment. `scout`/`context-builder` save parent context by compressing broad exploration. `worker` preserves a single writer thread.
 
 ## SDD/OpenSpec flow
 
@@ -275,11 +298,19 @@ pi install npm:gentle-engram
 
 When memory tools are actually active, el Gentleman can save decisions, bug fixes, discoveries, user prompts, and session summaries across Pi sessions.
 
+Memory contract for SDD delegation:
+
+- parent/orchestrator owns memory retrieval and passes selected context into subagent prompts;
+- subagents should not independently search memory during normal runtime unless explicitly instructed to retrieve a specific artifact or observation;
+- subagents should save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts before returning when memory tools are available;
+- in memory/hybrid mode, SDD artifacts use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, and `sdd/<change>/verify-report`.
+
 ## Package contents
 
 | Path                           | Purpose                                                                                                    |
 | ------------------------------ | ---------------------------------------------------------------------------------------------------------- |
 | `extensions/gentle-ai.ts`      | Injects identity, installs assets, registers commands, applies model config, and protects shell execution. |
+| `extensions/startup-banner.ts` | Shows the rose startup intro, compact runtime panel, and collaboration credit.                             |
 | `extensions/sdd-init.ts`       | Registers `/sdd-init` for OpenSpec initialization.                                                         |
 | `extensions/skill-registry.ts` | Maintains `.atl/skill-registry.md` from project/user skills.                                               |
 | `assets/orchestrator.md`       | Parent-session orchestration contract.                                                                     |
@@ -302,6 +333,8 @@ Validate before publishing:
 ```bash
 bun build extensions/skill-registry.ts --target=node --format=esm --outfile=/tmp/skill-registry.js
 node --experimental-strip-types --check extensions/gentle-ai.ts
+node --experimental-strip-types --check extensions/sdd-init.ts
+node --experimental-strip-types --check extensions/startup-banner.ts
 npm pack --dry-run
 ```
 

package/assets/agents/sdd-apply.md

@@ -13,6 +13,12 @@ Use your assigned executor/phase skill for this SDD phase. For project/user skil
 
 If Project Standards are missing, explicit fallback loading is allowed only as degraded self-healing. Report `skill_resolution` as `injected`, `fallback-registry`, `fallback-path`, or `none`; fallbacks mean the parent should inject compact rules next time.
 
+## Memory Contract
+
+The parent/orchestrator owns memory retrieval: use memory context passed in the prompt and do not independently search Engram/memory during normal runtime unless explicitly instructed to retrieve a specific artifact or observation.
+
+When callable memory tools are available, save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts before returning. In memory/hybrid mode, use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, or `sdd/<change>/verify-report`. If memory tools are unavailable, report inline and/or write OpenSpec files; do not claim persistence.
+
 
 ## Before Writing Code
 

package/assets/agents/sdd-archive.md

@@ -18,3 +18,9 @@ If Project Standards are missing, explicit fallback loading is allowed only as d
 - Preserve audit trail; never delete active artifacts silently.
 - Do NOT launch child subagents. Parent/orchestrator owns delegation.
 - Return archived paths and any migration risks.
+## Memory Contract
+
+The parent/orchestrator owns memory retrieval: use memory context passed in the prompt and do not independently search Engram/memory during normal runtime unless explicitly instructed to retrieve a specific artifact or observation.
+
+When callable memory tools are available, save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts before returning. In memory/hybrid mode, use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, or `sdd/<change>/verify-report`. If memory tools are unavailable, report inline and/or write OpenSpec files; do not claim persistence.
+

package/assets/agents/sdd-design.md

@@ -18,3 +18,9 @@ If Project Standards are missing, explicit fallback loading is allowed only as d
 - Keep design centered on `packages/coding-agent` unless scope explicitly expands.
 - Do NOT launch child subagents. Parent/orchestrator owns delegation.
 - Return the SDD result contract.
+## Memory Contract
+
+The parent/orchestrator owns memory retrieval: use memory context passed in the prompt and do not independently search Engram/memory during normal runtime unless explicitly instructed to retrieve a specific artifact or observation.
+
+When callable memory tools are available, save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts before returning. In memory/hybrid mode, use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, or `sdd/<change>/verify-report`. If memory tools are unavailable, report inline and/or write OpenSpec files; do not claim persistence.
+

package/assets/agents/sdd-explore.md

@@ -18,3 +18,9 @@ If Project Standards are missing, explicit fallback loading is allowed only as d
 - Use OpenSpec artifacts and session context truthfully; persistent memory is optional and handled by separate packages.
 - Do NOT launch child subagents. Parent/orchestrator owns delegation.
 - Keep output concise and return the SDD result contract.
+## Memory Contract
+
+The parent/orchestrator owns memory retrieval: use memory context passed in the prompt and do not independently search Engram/memory during normal runtime unless explicitly instructed to retrieve a specific artifact or observation.
+
+When callable memory tools are available, save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts before returning. In memory/hybrid mode, use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, or `sdd/<change>/verify-report`. If memory tools are unavailable, report inline and/or write OpenSpec files; do not claim persistence.
+

package/assets/agents/sdd-init.md

@@ -20,3 +20,9 @@ If Project Standards are missing, explicit fallback loading is allowed only as d
 - Ensure `.atl/skill-registry.md` exists when skill registry data is available, or report that it is missing.
 - Do NOT launch child subagents. Parent/orchestrator owns delegation.
 - Return the standard phase envelope with status, executive_summary, artifacts, next_recommended, risks, and skill_resolution.
+## Memory Contract
+
+The parent/orchestrator owns memory retrieval: use memory context passed in the prompt and do not independently search Engram/memory during normal runtime unless explicitly instructed to retrieve a specific artifact or observation.
+
+When callable memory tools are available, save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts before returning. In memory/hybrid mode, use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, or `sdd/<change>/verify-report`. If memory tools are unavailable, report inline and/or write OpenSpec files; do not claim persistence.
+

package/assets/agents/sdd-onboard.md

@@ -19,3 +19,9 @@ If Project Standards are missing, explicit fallback loading is allowed only as d
 - Respect strict TDD when project testing capabilities are present.
 - Do NOT launch child subagents. Parent/orchestrator owns delegation.
 - Return the standard phase envelope with status, executive_summary, artifacts, next_recommended, risks, and skill_resolution.
+## Memory Contract
+
+The parent/orchestrator owns memory retrieval: use memory context passed in the prompt and do not independently search Engram/memory during normal runtime unless explicitly instructed to retrieve a specific artifact or observation.
+
+When callable memory tools are available, save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts before returning. In memory/hybrid mode, use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, or `sdd/<change>/verify-report`. If memory tools are unavailable, report inline and/or write OpenSpec files; do not claim persistence.
+

package/assets/agents/sdd-proposal.md

@@ -18,3 +18,9 @@ If Project Standards are missing, explicit fallback loading is allowed only as d
 - Include intent, scope, affected areas, risks, rollback, and success criteria.
 - Do NOT launch child subagents. Parent/orchestrator owns delegation.
 - Persist planning output to OpenSpec artifacts; persistent memory is optional and handled by separate packages.
+## Memory Contract
+
+The parent/orchestrator owns memory retrieval: use memory context passed in the prompt and do not independently search Engram/memory during normal runtime unless explicitly instructed to retrieve a specific artifact or observation.
+
+When callable memory tools are available, save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts before returning. In memory/hybrid mode, use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, or `sdd/<change>/verify-report`. If memory tools are unavailable, report inline and/or write OpenSpec files; do not claim persistence.
+

package/assets/agents/sdd-spec.md

@@ -18,3 +18,9 @@ If Project Standards are missing, explicit fallback loading is allowed only as d
 - Store deltas under `openspec/changes/{change}/specs/`.
 - Do NOT launch child subagents. Parent/orchestrator owns delegation.
 - Return exact artifact paths and risks.
+## Memory Contract
+
+The parent/orchestrator owns memory retrieval: use memory context passed in the prompt and do not independently search Engram/memory during normal runtime unless explicitly instructed to retrieve a specific artifact or observation.
+
+When callable memory tools are available, save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts before returning. In memory/hybrid mode, use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, or `sdd/<change>/verify-report`. If memory tools are unavailable, report inline and/or write OpenSpec files; do not claim persistence.
+

package/assets/agents/sdd-tasks.md

@@ -13,6 +13,12 @@ Use your assigned executor/phase skill for this SDD phase. For project/user skil
 
 If Project Standards are missing, explicit fallback loading is allowed only as degraded self-healing. Report `skill_resolution` as `injected`, `fallback-registry`, `fallback-path`, or `none`; fallbacks mean the parent should inject compact rules next time.
 
+## Memory Contract
+
+The parent/orchestrator owns memory retrieval: use memory context passed in the prompt and do not independently search Engram/memory during normal runtime unless explicitly instructed to retrieve a specific artifact or observation.
+
+When callable memory tools are available, save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts before returning. In memory/hybrid mode, use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, or `sdd/<change>/verify-report`. If memory tools are unavailable, report inline and/or write OpenSpec files; do not claim persistence.
+
 
 ## Inputs
 

package/assets/agents/sdd-verify.md

@@ -13,6 +13,12 @@ Use your assigned executor/phase skill for this SDD phase. For project/user skil
 
 If Project Standards are missing, explicit fallback loading is allowed only as degraded self-healing. Report `skill_resolution` as `injected`, `fallback-registry`, `fallback-path`, or `none`; fallbacks mean the parent should inject compact rules next time.
 
+## Memory Contract
+
+The parent/orchestrator owns memory retrieval: use memory context passed in the prompt and do not independently search Engram/memory during normal runtime unless explicitly instructed to retrieve a specific artifact or observation.
+
+When callable memory tools are available, save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts before returning. In memory/hybrid mode, use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, or `sdd/<change>/verify-report`. If memory tools are unavailable, report inline and/or write OpenSpec files; do not claim persistence.
+
 
 ## Inputs
 

package/assets/orchestrator.md

@@ -34,9 +34,11 @@ el Gentleman is an ecosystem configurator and harness layer. After installation,
 - User says "use sdd" / "hacelo con sdd": run the SDD flow.
 - Parent session orchestrates; phase agents execute.
 
+Delegation is not optional once complexity appears. If a task crosses the triggers below, use the smallest useful subagent workflow instead of continuing as a monolithic executor.
+
 ## Work Routing Ladder
 
-Route work through the smallest harness that is safe.
+Route work through the smallest harness that is safe. "Smallest" means minimal safe coordination, not zero delegation by default.
 
 ### 1. Inline Direct
 
@@ -49,7 +51,7 @@ Examples:
 - focused verification over 1-3 files;
 - bash for state, e.g. `git status` or `gh issue view`.
 
-Do not add SDD ceremony. Do not delegate just to look sophisticated.
+Do not add SDD ceremony. Do not delegate just to look sophisticated. But do not use this exception to avoid delegation after the task stops being small.
 
 ### 2. Simple Delegation
 
@@ -66,6 +68,14 @@ Examples:
 
 Use `pi-subagents` when available. Prefer background/async for long exploration, implementation, tests, or review when the parent has independent work.
 
+Default balanced pattern for bounded implementation:
+
+```text
+parent clarifies and checks git → scout/context-builder when context-heavy → one worker writes → fresh reviewer audits diff → parent validates and reports
+```
+
+Do not make every task SDD. Do make non-trivial tasks multi-agent at the narrowest useful point.
+
 ### 3. SDD
 
 Use SDD for large, ambiguous, architectural, product-facing, multi-area, or high-review-risk work.
@@ -85,15 +95,58 @@ If the request is large enough for SDD, do not jump directly to implementation.
 
 Core question: does this inflate parent context without need?
 
-| Action                                     | Inline | Delegate |
-| ------------------------------------------ | -----: | -------: |
-| Read to decide/verify 1-3 files            |    yes |       no |
-| Read to explore/understand 4+ files        |     no |      yes |
-| Read as preparation for multi-file writing |     no |      yes |
-| Write atomic one-file mechanical change    |    yes |       no |
-| Write with analysis across multiple files  |     no |      yes |
-| Bash for state, e.g. git status            |    yes |       no |
-| Bash for execution, e.g. tests/builds      |     no |      yes |
+| Action                                               | Inline |                Delegate |
+| ---------------------------------------------------- | -----: | ----------------------: |
+| Read to decide/verify 1-3 files                      |    yes |                      no |
+| Read to explore/understand 4+ files                  |     no |                     yes |
+| Read as preparation for multi-file writing           |     no |                     yes |
+| Write atomic one-file mechanical change              |    yes |                      no |
+| Write with analysis across multiple files            |     no |                     yes |
+| Bash for state, e.g. git status                      |    yes |                      no |
+| Bash for execution, e.g. tests/builds                |     no |                     yes |
+| Commit, push, or open PR after code changes          |     no | yes, fresh review first |
+| Recover from wrong cwd/worktree/git/tooling incident |     no |  yes, fresh audit first |
+
+### Mandatory Delegation Triggers
+
+These are parent-orchestrator stop rules. Once any trigger fires, the parent must either delegate or explicitly tell the user why delegation would be unsafe or wasteful for this exact case. Do not inject these as child-agent permission to spawn subagents; children receive concrete role work and must not orchestrate.
+
+1. **4-file rule**: if understanding requires reading 4+ files, launch `scout` or `context-builder` with fresh context and a narrow mapping task.
+2. **Multi-file write rule**: if implementation will touch 2+ non-trivial files, use one `worker` or keep writing inline only if a fresh reviewer will audit before completion.
+3. **PR rule**: before commit/push/PR for code changes, run a fresh-context `reviewer` unless the diff is a trivial docs/text-only change.
+4. **Incident rule**: after wrong `cwd`, accidental repo/worktree mutation, failed merge recovery, confusing test command, or environment workaround, stop and run a fresh audit reviewer.
+5. **Long-session rule**: if accumulating work is no longer clearly local — roughly 20 tool calls, 5 exploratory file reads, or 2 non-mechanical edits without delegation — pause and choose `scout`, `worker`, or `reviewer` instead of silently continuing monolithically.
+6. **Fresh review rule**: use `context: "fresh"` for adversarial review of diffs, conflicts, PR readiness, and incident audits. Use forked context for continuity-oriented `worker`/`oracle` tasks.
+
+### Cost and Context Balance
+
+Prefer delegation when fresh context improves correctness more than token savings:
+
+- Use `scout`/`context-builder` to compress broad repo exploration into a short handoff instead of loading many files into the parent.
+- Use a single `worker` for one writer thread; do not run parallel writers unless isolated worktrees are explicitly approved.
+- Use fresh `reviewer` agents after implementation, conflict resolution, or incidents because their value is independence from the parent's assumptions.
+- Use `outputMode: "file-only"` for large child reports and summarize only decisions, blockers, and paths in the parent thread.
+- Avoid delegation for truly local one-file fixes, quick state checks, and already-understood mechanical edits.
+
+### Canonical Lightweight Workflows
+
+Bugfix with unfamiliar flow:
+
+```text
+parent git/status + clarify → scout fresh maps flow/files → parent decides → worker fork implements + tests → reviewer fresh audits diff → parent validates
+```
+
+Conflict or dependency-marker cleanup:
+
+```text
+parent reproduces/checks conflict → parent or worker resolves → reviewer fresh checks markers, package/lock consistency, and repo cleanliness → parent reports/pushes
+```
+
+After tooling/worktree incident:
+
+```text
+stop writes → parent captures git status → reviewer fresh audits affected repos/worktrees with no edits → parent applies only confirmed recovery steps
+```
 
 ## SDD Workflow
 
@@ -141,6 +194,16 @@ This package does not provide persistent memory by itself.
 - If a separate memory package is installed and callable, memory/hybrid flows may be used.
 - Never claim memory exists because Gentle AI is installed.
 
+## Memory Contract
+
+When Engram or another callable memory package is available, the parent owns memory retrieval and subagents own write-back for significant findings.
+
+- Read context: parent/orchestrator searches memory, selects relevant observations, and passes them into subagent prompts. Subagents should not independently search memory during normal runtime unless the parent explicitly instructs them to retrieve a specific artifact or observation.
+- Write context: subagents MUST save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts to memory before returning when memory tools are available.
+- Prompt forwarding: when delegating, add a concrete instruction such as: `If you make important discoveries, decisions, or fix bugs, save them to Engram via the available memory save tool with project: '<project>' before returning.`
+- SDD artifact keys: in memory/hybrid mode, phase artifacts should use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, and `sdd/<change>/verify-report`.
+- If memory tools are unavailable, do not pretend persistence exists; return artifacts inline and/or write OpenSpec files.
+
 ## Execution Mode
 
 For substantial SDD flows, choose or ask once per change:

package/extensions/gentle-ai.ts

@@ -8,18 +8,12 @@ import {
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { VERSION } from "@earendil-works/pi-coding-agent";
 import type {
 	ExtensionAPI,
 	ExtensionContext,
-	Theme,
 	ToolCallEventResult,
 } from "@earendil-works/pi-coding-agent";
-import {
-	matchesKey,
-	truncateToWidth,
-	visibleWidth,
-} from "@earendil-works/pi-tui";
+import { matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
 
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const ASSETS_DIR = join(PACKAGE_ROOT, "assets");
@@ -49,139 +43,6 @@ const NEUTRAL_PERSONA_PROMPT = `Persona:
 - Push back when the user asks for code without enough context or understanding.
 - Correct errors directly, explain why, and show the better path.`;
 
-const ROSE_LOGO_LINES = [
-	"             ⣠⣾⣷⣶⣦⣤⣤⣄⣠⣄⣀  ⢀⣀⣀",
-	"          ⢀⣴⣿⣿⠿⣋⣭⣭⣯⣭⣍⣭⣿⣟⠛⠛⠿⠿⣿⣷⣄",
-	"      ⢀⣴⣾⡟⢻⣿⡟⠁⣼⣿⠏⣵⢻⣿⣻⣿⣿⢿⡻⣿⣿⣶⡌⢿⣿⣷⣦⣤⡄",
-	"   ⣤⣶⣾⣿⣿⠏ ⠈⢿⣄ ⢹⣏⠠⠟⣾⣿⣿⣿⣿⣿⠷⣏⣼⠟⢡⣿⡟⠋⢻⣿⣿⡄",
-	"   ⠈⣿⣿⣿⣿⡆   ⣽⢧⡘⠈⠳⣦⣍⠛⠛⢦⣉⣴⣛⣫⣭⣴⡟⠋  ⣾⣿⣿⡿",
-	"   ⢀⠹⣿⣿⣿⣷⣤⡄ ⠋ ⠙⢆ ⣠⠴⠟⠛⣛⣛⣛⠟⠋⠁⠺⡇ ⣀⣴⣿⣿⡟⠁",
-	"   ⠈⣀⠈⠛⠷⠿⣿⣿⣷⣤⣀ ⢠⠋   ⠈⠉⠉    ⣠⣴⣥⠾⠛⠉⣰⣿⣷",
-	"          ⠹⣯⣝⠛⠛⠷⢶⣤⣤⣀   ⢀⡠⠖⠋⠉⢉⣀⣀⣴⣾⣿⠿⠟⠃ ⠠⠦",
-	"⠁       ⠖  ⠘⠻⢿⣦⣄⡀  ⠉⠛⢦⠠⢊⠤⠴⢒⣛⣛⣩⣽⡿⠟⠁⢀⡀",
-	"⠲⠶⣦⠴⠶⠶⠶⠶⡶⠶⢶⣤⣄⡀⠨⠭⠽⠟⣓⢦⣀⠈⢇⡥⠖⠛⠋⠉⠉⠉    ⠈  ⢠⡤",
-	"  ⠈⢷ ⠐⠂⢤⣽⣄ ⠰⡎⠙⠳⣄⡀ ⠈⢣⠘⢦⠋⣀⡬⠟⠛⠛⠉⢀⣀⣀⣠⡤⠄⠃",
-	"   ⠈⢳⣀⡒⠉⠉⣉⠙⡲⣽⣄ ⣏⠳⡄ ⠘⡇ ⡾⠁ ⢀⡤⠖⣻⣿⡏⢡⡎ ⠰⠄",
-	"     ⠛⠻⢦⣄⣉⡁⣀⣀⣈⣙⣺⣌⡇⢠⢀⡇⡾  ⣴⣿⡷⠊ ⢲⣠⠟",
-	"          ⠈⠉    ⠈⠳⡄⣸⢱⠇⢀⣰⣯⣭⣥⠭⠾⠛⠃",
-	"                  ⡷⠡⡯⢖⠉   ⢠⠤",
-	"                ⡠⢊⡴⠤⠂⠃ ⠒",
-	"             ⢀⡴⢪⠔⣉⠔⠋",
-	"               ⠐⠈",
-];
-
-const ROSE_FADE_STEPS = 12;
-const ROSE_FADE_INTERVAL_MS = 45;
-const ROSE_INTRO_HOLD_MS = 180;
-
-function rgb(r: number, g: number, b: number, text: string): string {
-	return `\x1b[38;2;${r};${g};${b}m${text}\x1b[39m`;
-}
-
-function italic(text: string): string {
-	return `\x1b[3m${text}\x1b[23m`;
-}
-
-function bold(text: string): string {
-	return `\x1b[1m${text}\x1b[22m`;
-}
-
-function centerLine(line: string, width: number): string {
-	const clipped = truncateToWidth(line, width, "");
-	const padding = Math.max(0, width - visibleWidth(clipped));
-	return `${" ".repeat(Math.floor(padding / 2))}${clipped}`;
-}
-
-function pinkFade(text: string, frame: number): string {
-	const progress = Math.max(0, Math.min(1, frame / ROSE_FADE_STEPS));
-	const eased = 1 - (1 - progress) ** 3;
-	const r = Math.round(72 + (255 - 72) * eased);
-	const g = Math.round(38 + (122 - 38) * eased);
-	const b = Math.round(58 + (198 - 58) * eased);
-	return rgb(r, g, b, text);
-}
-
-function buildGentlemanTitle(width: number, frame: number): string[] {
-	const title = "✧  𝓮𝓵 𝓖𝓮𝓷𝓽𝓵𝓮𝓶𝓪𝓷  ✧";
-	const version = `━━  v${VERSION}  ━━`;
-	return [
-		pinkFade(bold(italic(centerLine(title, width))), frame),
-		pinkFade(italic(centerLine(version, width)), frame),
-	];
-}
-
-function buildRoseHeader(
-	_theme: Theme,
-	width: number,
-	frame: number,
-): string[] {
-	return [
-		"",
-		...ROSE_LOGO_LINES.map((line) => pinkFade(centerLine(line, width), frame)),
-		...buildGentlemanTitle(width, frame),
-		"",
-	];
-}
-
-function installRoseHeader(ctx: ExtensionContext): void {
-	if (!ctx.hasUI) return;
-
-	process.stdout.write("\x1b[2J\x1b[3J\x1b[H");
-
-	let closeIntro: (() => void) | undefined;
-	const closeIntroSafely = () => {
-		const close = closeIntro;
-		closeIntro = undefined;
-		try {
-			close?.();
-		} catch {
-			// Ignore shutdown races during startup/reload.
-		}
-	};
-
-	void ctx.ui
-		.custom((_tui, _theme, _keybindings, done) => {
-			closeIntro = () => done(undefined);
-			return {
-				render: () => [""],
-				invalidate: () => {},
-				handleInput: () => {},
-			};
-		})
-		.catch(() => {
-			closeIntro = undefined;
-		});
-
-	const state: { frame: number; timer?: NodeJS.Timeout } = { frame: 0 };
-	ctx.ui.setHeader((tui, theme) => {
-		if (state.timer) clearInterval(state.timer);
-		state.timer = setInterval(() => {
-			state.frame += 1;
-			tui.requestRender();
-			if (
-				state.frame <
-				ROSE_FADE_STEPS + Math.ceil(ROSE_INTRO_HOLD_MS / ROSE_FADE_INTERVAL_MS)
-			) {
-				return;
-			}
-			if (state.timer) clearInterval(state.timer);
-			state.timer = undefined;
-			closeIntroSafely();
-		}, ROSE_FADE_INTERVAL_MS);
-
-		return {
-			render(width: number): string[] {
-				return buildRoseHeader(theme, width, state.frame);
-			},
-			invalidate() {
-				if (state.timer) clearInterval(state.timer);
-				state.timer = undefined;
-				closeIntroSafely();
-			},
-		};
-	});
-}
-
 function buildGentlePrompt(persona: PersonaMode): string {
 	const personaPrompt =
 		persona === "neutral" ? NEUTRAL_PERSONA_PROMPT : GENTLEMAN_PERSONA_PROMPT;
@@ -911,7 +772,6 @@ async function handlePersonaCommand(ctx: ExtensionContext): Promise<void> {
 
 export default function gentleAi(pi: ExtensionAPI): void {
 	pi.on("session_start", (_event, ctx) => {
-		installRoseHeader(ctx);
 		const result = installSddAssets(ctx.cwd, false);
 		const modelResult = applyModelConfig(ctx.cwd, readModelConfig(ctx.cwd));
 		if (

package/extensions/skill-registry.ts

@@ -1,13 +1,5 @@
 import { createHash } from "node:crypto";
-import {
-	existsSync,
-	mkdirSync,
-	readFileSync,
-	readdirSync,
-	statSync,
-	watch,
-	writeFileSync,
-} from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, watch, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join, relative } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -77,11 +69,7 @@ function findSkillFiles(root: string): string[] {
 	return out;
 }
 
-function parseFrontmatter(source: string): {
-	name?: string;
-	description?: string;
-	body: string;
-} {
+function parseFrontmatter(source: string): { name?: string; description?: string; body: string } {
 	if (!source.startsWith("---\n")) return { body: source };
 	const end = source.indexOf("\n---", 4);
 	if (end === -1) return { body: source };
@@ -93,10 +81,7 @@ function parseFrontmatter(source: string): {
 		if (!m) continue;
 		const key = m[1];
 		let value = m[2].trim();
-		if (
-			(value.startsWith('"') && value.endsWith('"')) ||
-			(value.startsWith("'") && value.endsWith("'"))
-		) {
+		if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
 			value = value.slice(1, -1);
 		}
 		if (key === "name") out.name = value;
@@ -123,10 +108,7 @@ function extractCompactRulesSection(body: string): string[] {
 	return rules;
 }
 
-function deriveSkillName(
-	file: string,
-	frontmatterName: string | undefined,
-): string {
+function deriveSkillName(file: string, frontmatterName: string | undefined): string {
 	if (frontmatterName) return frontmatterName;
 	return basename(join(file, ".."));
 }
@@ -165,9 +147,7 @@ function loadSkill(file: string): SkillEntry | undefined {
 		rules:
 			rules.length > 0
 				? rules
-				: [
-						"No compact rules declared; delegators should load the full skill file before direct work, or pass an explicit fallback path only when Project Standards cannot be injected.",
-					],
+				: ["No compact rules declared; delegators should load the full skill file before direct work, or pass an explicit fallback path only when Project Standards cannot be injected."],
 	};
 }
 
@@ -202,19 +182,13 @@ function fingerprint(files: string[]): string {
 	return createHash("sha1").update(lines.join("\n")).digest("hex");
 }
 
-function renderRegistry(
-	cwd: string,
-	sources: string[],
-	entries: SkillEntry[],
-): string {
+function renderRegistry(cwd: string, sources: string[], entries: SkillEntry[]): string {
 	const projectName = basename(cwd);
 	const today = new Date().toISOString().slice(0, 10);
 	const lines: string[] = [];
 	lines.push(`# Skill Registry — ${projectName}`);
 	lines.push("");
-	lines.push(
-		"<!-- Auto-generated by .pi/extensions/skill-registry.ts. Run /skill-registry:refresh to regenerate. -->",
-	);
+	lines.push("<!-- Auto-generated by .pi/extensions/skill-registry.ts. Run /skill-registry:refresh to regenerate. -->");
 	lines.push("");
 	lines.push(`Last updated: ${today}`);
 	lines.push("");
@@ -226,13 +200,9 @@ function renderRegistry(
 	lines.push("");
 	lines.push("## Contract");
 	lines.push("");
-	lines.push(
-		"**Delegator use only.** Any agent that launches subagents reads this registry to resolve compact rules, then injects matching rule text into subagent prompts under `## Project Standards (auto-resolved)`.",
-	);
+	lines.push("**Delegator use only.** Any agent that launches subagents reads this registry to resolve compact rules, then injects matching rule text into subagent prompts under `## Project Standards (auto-resolved)`.");
 	lines.push("");
-	lines.push(
-		"Subagents still read their assigned executor/phase skill. During normal runtime, they do **not** independently discover or load additional project/user `SKILL.md` files or this registry; project/user rules arrive pre-digested. Explicit fallback loading is degraded self-healing and must be reported in `skill_resolution` as `fallback-registry` or `fallback-path`.",
-	);
+	lines.push("Subagents still read their assigned executor/phase skill. During normal runtime, they do **not** independently discover or load additional project/user `SKILL.md` files or this registry; project/user rules arrive pre-digested. Explicit fallback loading is degraded self-healing and must be reported in `skill_resolution` as `fallback-registry` or `fallback-path`.");
 	lines.push("");
 	lines.push(SECTION_MARKER);
 	lines.push("");
@@ -269,20 +239,12 @@ function ensureAtlIgnored(cwd: string): void {
 		.some((line) => line === ".atl" || line === ATL_IGNORE_ENTRY);
 	if (hasAtlIgnore) return;
 	const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
-	const header = existing.includes("# Local Pi runtime state")
-		? ""
-		: "# Local Pi runtime state\n";
-	writeFileSync(
-		gitignorePath,
-		`${existing}${prefix}${header}${ATL_IGNORE_ENTRY}\n`,
-	);
+	const header = existing.includes("# Local Pi runtime state") ? "" : "# Local Pi runtime state\n";
+	writeFileSync(gitignorePath, `${existing}${prefix}${header}${ATL_IGNORE_ENTRY}\n`);
 }
 
 function regenerateRegistry(cwd: string, force: boolean): RegenResult {
-	const existingDirs = uniqueExistingDirs([
-		...projectSkillDirs(cwd),
-		...userSkillDirs(),
-	]);
+	const existingDirs = uniqueExistingDirs([...projectSkillDirs(cwd), ...userSkillDirs()]);
 	const files = existingDirs.flatMap(findSkillFiles).sort();
 	const cachePath = join(cwd, CACHE_REL_PATH);
 	const registryPath = join(cwd, REGISTRY_REL_PATH);
@@ -290,9 +252,7 @@ function regenerateRegistry(cwd: string, force: boolean): RegenResult {
 	let cached: string | undefined;
 	if (existsSync(cachePath)) {
 		try {
-			cached = (
-				JSON.parse(readFileSync(cachePath, "utf8")) as { fingerprint?: string }
-			).fingerprint;
+			cached = (JSON.parse(readFileSync(cachePath, "utf8")) as { fingerprint?: string }).fingerprint;
 		} catch {
 			cached = undefined;
 		}
@@ -312,25 +272,15 @@ function regenerateRegistry(cwd: string, force: boolean): RegenResult {
 	mkdirSync(join(cwd, ".atl"), { recursive: true });
 	writeFileSync(registryPath, md);
 	writeFileSync(cachePath, JSON.stringify({ fingerprint: fp }, null, 2));
-	return {
-		regenerated: true,
-		skillCount: deduped.length,
-		reason: force ? "forced" : "fingerprint-changed",
-	};
+	return { regenerated: true, skillCount: deduped.length, reason: force ? "forced" : "fingerprint-changed" };
 }
 
 const watchedCwds = new Set<string>();
 
-function startSkillRegistryWatcher(
-	cwd: string,
-	notify: (message: string) => void,
-): void {
+function startSkillRegistryWatcher(cwd: string, notify: (message: string) => void): void {
 	if (watchedCwds.has(cwd)) return;
 	watchedCwds.add(cwd);
-	const dirs = uniqueExistingDirs([
-		...projectSkillDirs(cwd),
-		...userSkillDirs(),
-	]);
+	const dirs = uniqueExistingDirs([...projectSkillDirs(cwd), ...userSkillDirs()]);
 	let timer: ReturnType<typeof setTimeout> | undefined;
 	const refresh = () => {
 		if (timer) clearTimeout(timer);
@@ -360,10 +310,7 @@ export default function (pi: ExtensionAPI) {
 			ensureAtlIgnored(ctx.cwd);
 			const result = regenerateRegistry(ctx.cwd, false);
 			if (result.regenerated && ctx.hasUI) {
-				ctx.ui.notify(
-					`Skill registry refreshed (${result.skillCount} skills)`,
-					"info",
-				);
+				ctx.ui.notify(`Skill registry refreshed (${result.skillCount} skills)`, "info");
 			}
 			startSkillRegistryWatcher(ctx.cwd, (message) => {
 				if (ctx.hasUI) ctx.ui.notify(message, "info");

package/extensions/startup-banner.ts

@@ -0,0 +1,463 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { VERSION } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import * as os from "node:os";
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const execAsync = promisify(exec);
+
+const TEXT_LOGO = [
+  "                  ▄▄▄▀▀▀▀▀██                                ▄▄▀▄▄           ▄▄█▀▀▀██   ▀▀█▄    ▄▄▄",
+  "              ▄▄█▀▀▒▒▒▒▒▄▄█▀▒                   ▄██     ▄▄█▀█▄█▀▒▒      ▄█▀▀ ▒▒▒▄█▀▀▒   ▄██▒ ▄█▀▒▒▒",
+  "          ▄▄██▀▒▒▒▒▒▄▄▄▀▀▒▒▒▒        ▄▄▄  ▀▀▀▀██▀▀▀▀▀███▀█▄▀▀▒▒▒▒      ██▒▒▒▒▄▄█▀▒▒▒▒▄▄█▀▀▄██▀▒▒▒",
+  "        ▄██▀▒▒▒▒     ▒▒▄▄█ ▄▄▄▀██ ▄▄▄▀▀▀▄  ▄██▀▒▒▒▒▄██▀▀▀▒▄▄███         ▒▒ ▄███▄▄▄█▀▀▀▒▒▄██▀▒▒▒",
+  "       ██▀▒▒▒     ▄▄▄███▀▄██▀▀▀▄▄██▀▀▄█▀▄▄██▀▒▒▒▄▄██▀▒▒▄██▀▀▀▄▄▀▀▀▀▀▀▀▀▀ ▄█▀▀▒▒▒▒▒▒▒▒▒▄██▒▒▒▒",
+  "       ▀█▄▄▄▄▄▀▀▀█▄▄███▄▒▀▀▀▀▀▀▒▀▀▒▒▀▀▀▀▒██▄▄▀▀▀ ▀█▄▀▀▀ ▀▀▀▀▀▒▒▒▒▒▒▒▒▒▒▄██▀▒▒▒       ███▒▒",
+  "        ▒▄▄▄█▀▀▀█▄█▀▀▒▒▒▒ ▒▒▒▒▒▒ ▒▒  ▒▒▒▒ ▒▒▒▒▒▒▒ ▒▒▒▒▒▒ ▒▒▒▒▒        ▀▀▀▒▒▒          ▒▒▒",
+  "     ▄▄▀▀ ▒▒▒▒▄██▀▒▒▒▒                                                 ▒▒▒",
+  "   ▄█ ▒▒▒▄▄██▀▀▒▒▒▒",
+  "    ▀▀▀▀▀▀▒▒▒▒▒▒",
+  "     ▒▒▒▒▒▒",
+];
+
+const ROSE_LARGE_RAW = [
+  "             ⣠⣾⣷⣶⣦⣤⣤⣄⣠⣄⣀  ⢀⣀⣀",
+  "          ⢀⣴⣿⣿⠿⣋⣭⣭⣯⣭⣍⣭⣿⣟⠛⠛⠿⣿⣷⣄",
+  "      ⢀⣴⣾⡟⢻⣿⡟⠁⣼⣿⠏⣵⢻⣿⣻⣿⣿⢿⡻⣿⣿⣶⡌⢿⣿⣷⣦⣤⡄",
+  "   ⣤⣶⣾⣿⣿⠏ ⠈⢿⣄ ⢹⣏⠠⠟⣾⣿⣿⣿⣿⣿⠷⣏⣼⠟⢡⣿⡟⠋⢻⣿⣿⡄",
+  "   ⠈⣿⣿⣿⣿⡆   ⣽⢧⡘⠈⠳⣦⣍⠛⠛⢦⣉⣴⣛⣫⣭⣴⡟⠋  ⣾⣿⣿⡿",
+  "   ⢀⠹⣿⣿⣿⣷⣤⡄ ⠋ ⠙⢆ ⣠⠴⠟⠛⣛⣛⣛⠟⠋⠁⠺⡇ ⣀⣴⣿⣿⡟⠁",
+  "   ⠈⣀⠈⠛⠷⠿⣿⣿⣷⣤⣀ ⢠⠋   ⠈⠉⠉    ⣠⣴⣥⠾⠛⠉⣰⣿⣷",
+  "          ⠹⣯⣝⠛⠛⠷⢶⣤⣤⣀   ⢀⡠⠖⠋⠉⢉⣀⣀⣴⣾⣿⠿⠟⠃",
+  "             ⠘⠻⢿⣦⣄⡀  ⠉⠛⢦⠠⢊⠤⠴⢒⣛⣛⣩⣽⡿⠟⠁",
+  "        ⠶⢶⣤⣄⡀⠨⠭⠽⠟⣓⢦⣀⠈⢇⡥⠖⠛⠋⠉⠉",
+  "           ⠈⢷ ⠐⠂⢤⣽⣄ ⠰⡎⠙⠳⣄⡀ ⠈⢣⠘⢦⠋",
+  "            ⠈⢳⣀⡒⠉⠉⣉⠙⡲⣽⣄ ⣏⠳⡄ ⠘⡇ ⡾⠁",
+  "              ⠛⠻⢦⣄⣉⡁⣀⣀⣈⣙⣺⣌⡇⢠⢀⡇⡾",
+  "                   ⠈⠉    ⠈⠳⡄⣸⢱⠇",
+  "                           ⡷⠡⡯⢖⠉",
+  "                        ⢀⡴⢪⠔⣉⠔⠋",
+  "                           ⠐⠈",
+];
+
+function rgb(r: number, g: number, b: number, text: string): string {
+  return `\x1b[38;2;${r};${g};${b}m${text}\x1b[39m`;
+}
+
+function normalizeAscii(lines: string[]): string[] {
+  const trimmed = lines.map((l) => l.replace(/\s+$/g, ""));
+  const nonEmpty = trimmed.filter((l) => l.trim().length > 0);
+  const minLead = nonEmpty.length
+    ? Math.min(...nonEmpty.map((l) => (l.match(/^\s*/) || [""])[0].length))
+    : 0;
+  return trimmed.map((l) => (l.length >= minLead ? l.slice(minLead) : l));
+}
+
+function padLines(lines: string[]): { lines: string[]; width: number } {
+  const width = Math.max(...lines.map((l) => l.length), 0);
+  return { lines: lines.map((l) => l.padEnd(width)), width };
+}
+
+type CellType =
+  | "banner"
+  | "rose"
+  | "label"
+  | "value"
+  | "dim"
+  | "accent"
+  | "none";
+type LayoutCell = { char: string; type: CellType };
+
+class LayoutBuilder {
+  lines: LayoutCell[][] = [];
+
+  addRow() {
+    this.lines.push([]);
+  }
+
+  add(type: CellType, text: string) {
+    const row = this.lines[this.lines.length - 1];
+    for (const char of text) row.push({ char, type });
+  }
+
+  center(width: number) {
+    const row = this.lines[this.lines.length - 1];
+    const pad = Math.max(0, Math.floor((width - row.length) / 2));
+    const prefix = Array.from({ length: pad }, () => ({
+      char: " ",
+      type: "none" as const,
+    }));
+    this.lines[this.lines.length - 1] = prefix.concat(row);
+  }
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("session_start", async (_event, ctx) => {
+    if (!ctx.hasUI) return;
+
+    // Si se está ejecutando un comando de CLI como "pi update" o "pi install", no mostramos la intro animada.
+    const isCLICommand =
+      process.argv.length > 2 &&
+      !process.argv.every((arg) => arg.startsWith("-") || arg.endsWith(".ts"));
+    if (isCLICommand) return;
+
+    process.stdout.write("\x1b[2J\x1b[3J\x1b[H");
+
+    let closeIntro: (() => void) | null = null;
+    const closeIntroSafely = () => {
+      if (!closeIntro) return;
+      const fn = closeIntro;
+      closeIntro = null;
+      try {
+        fn();
+      } catch {}
+    };
+
+    void ctx.ui
+      .custom((_tui, _theme, _keybindings, done) => {
+        closeIntro = () => done(undefined);
+        return {
+          render: () => [""],
+          invalidate: () => {},
+          handleInput: () => {},
+        };
+      })
+      .catch(() => {
+        closeIntro = null;
+      });
+
+    const roseBase = padLines(normalizeAscii(ROSE_LARGE_RAW));
+    const logoBase = padLines(TEXT_LOGO);
+
+    let gitBranch = "Not a git repo";
+    let mcpServersCount = 0;
+    let extensionsCount = 0;
+    let packagesCount = 0;
+
+    const allCommands = pi.getCommands();
+    const skills = allCommands.filter((c) => c.source === "skill");
+    const allTools = pi.getAllTools();
+    const customTools = allTools.filter(
+      (t) => !["builtin", "sdk"].includes(t.sourceInfo.source),
+    );
+
+    setTimeout(() => {
+      execAsync(`git -C "${ctx.cwd}" branch --show-current`)
+        .then(({ stdout }) => {
+          const b = stdout.trim();
+          gitBranch = b ? `On branch ${b}` : "Detached HEAD";
+        })
+        .catch(() => {});
+    }, 100);
+
+    setTimeout(() => {
+      (async () => {
+        try {
+          const raw = await readFile(
+            join(os.homedir(), ".pi", "agent", "mcp.json"),
+            "utf8",
+          );
+          const cfg = JSON.parse(raw);
+          mcpServersCount = Object.keys(cfg.mcpServers || {}).length;
+        } catch {
+          mcpServersCount = 0;
+        }
+      })();
+    }, 150);
+
+    setTimeout(() => {
+      (async () => {
+        try {
+          const raw = await readFile(
+            join(os.homedir(), ".pi", "agent", "settings.json"),
+            "utf8",
+          );
+          const cfg = JSON.parse(raw);
+          extensionsCount = Array.isArray(cfg.extensions)
+            ? cfg.extensions.length
+            : 0;
+          packagesCount = Array.isArray(cfg.packages) ? cfg.packages.length : 0;
+        } catch {
+          extensionsCount = 0;
+          packagesCount = 0;
+        }
+      })();
+    }, 200);
+
+    let tick = 0;
+    const state = { timer: null as NodeJS.Timeout | null };
+
+    setTimeout(() => {
+      ctx.ui.setHeader((tui, theme) => {
+        if (state.timer) clearInterval(state.timer);
+
+        state.timer = setInterval(() => {
+          tick++;
+          if (tick > 90) {
+            if (state.timer) {
+              clearInterval(state.timer);
+              state.timer = null;
+            }
+            closeIntroSafely();
+            return;
+          }
+          try {
+            tui.requestRender();
+          } catch {
+            if (state.timer) {
+              clearInterval(state.timer);
+              state.timer = null;
+            }
+          }
+        }, 50);
+
+        return {
+          render(width: number): string[] {
+            const flashStartTick = 16;
+            const roseOpacity = Math.min(1, tick / 16);
+            const flashPhase =
+              tick >= flashStartTick
+                ? Math.max(0, 1 - (tick - flashStartTick) / 20)
+                : 0;
+            const frame = Math.floor(tick / 2);
+
+            const sideBySideMinWidth = roseBase.width + 3 + logoBase.width + 4;
+            const wideStatsMinWidth = 122;
+            const horizontal = width >= sideBySideMinWidth;
+            const wideStats = width >= wideStatsMinWidth;
+
+            const b = new LayoutBuilder();
+            b.addRow();
+            b.center(width);
+
+            if (horizontal) {
+              const rowCount = Math.max(
+                roseBase.lines.length,
+                logoBase.lines.length,
+              );
+              const roseOffset = Math.max(
+                0,
+                Math.floor((rowCount - roseBase.lines.length) / 2),
+              );
+              const logoOffset = Math.max(
+                0,
+                Math.floor((rowCount - logoBase.lines.length) / 2),
+              );
+
+              for (let i = 0; i < rowCount; i++) {
+                const roseI = i - roseOffset;
+                const logoI = i - logoOffset;
+                const roseLine =
+                  roseI >= 0 && roseI < roseBase.lines.length
+                    ? roseBase.lines[roseI]
+                    : " ".repeat(roseBase.width);
+                const logoLine =
+                  logoI >= 0 && logoI < logoBase.lines.length
+                    ? logoBase.lines[logoI]
+                    : " ".repeat(logoBase.width);
+
+                b.addRow();
+                b.add("rose", roseLine);
+                b.add("none", "   ");
+                b.add("banner", logoLine);
+                b.center(width);
+              }
+            } else {
+              const showBanner = width >= logoBase.width + 2;
+              const showRose = width >= roseBase.width + 2;
+              if (showBanner) {
+                for (const logoLine of logoBase.lines) {
+                  b.addRow();
+                  b.add("banner", logoLine);
+                  b.center(width);
+                }
+                if (showRose) {
+                  b.addRow();
+                  b.center(width);
+                }
+              }
+              if (showRose) {
+                for (const roseLine of roseBase.lines) {
+                  b.addRow();
+                  b.add("rose", roseLine);
+                  b.center(width);
+                }
+              }
+            }
+
+            b.addRow();
+            b.center(width);
+
+            const fit = (v: unknown, w: number) =>
+              String(v ?? "")
+                .replace(/\s+/g, " ")
+                .trim()
+                .slice(0, w)
+                .padEnd(w);
+            const addWideRow = (
+              l1: string,
+              v1: string,
+              l2: string,
+              v2: string,
+            ) => {
+              b.addRow();
+              b.add("label", fit(l1, 10));
+              b.add("none", " ");
+              b.add("value", fit(v1, 48));
+              b.add("none", "   ");
+              b.add("label", fit(l2, 12));
+              b.add("none", " ");
+              b.add("value", fit(v2, 46));
+              b.center(width);
+            };
+            const narrowRows: Array<[string, string]> = [
+              ["GIT:", gitBranch],
+              ["PATH:", ctx.cwd],
+              ["MCP:", `${mcpServersCount} server(s)`],
+              ["PLUGINS:", `${packagesCount} package(s)`],
+              ["AGENTS:", `${skills.length} loaded`],
+              ["EXTENSIONS:", `${extensionsCount} active`],
+              ["VER:", `v${VERSION}`],
+              ["TOOLS:", `${customTools.length} custom`],
+            ];
+            const narrowLabelW = Math.max(...narrowRows.map(([l]) => l.length));
+            const narrowValueW = Math.max(
+              0,
+              Math.min(
+                Math.max(...narrowRows.map(([, v]) => v.length)),
+                Math.max(8, width - narrowLabelW - 4),
+              ),
+            );
+            const addNarrowRow = (label: string, value: string) => {
+              b.addRow();
+              b.add("label", label.padEnd(narrowLabelW));
+              b.add("none", "  ");
+              b.add("value", fit(value, narrowValueW));
+              b.center(width);
+            };
+
+            if (wideStats) {
+              addWideRow("GIT:", gitBranch, "PATH:", ctx.cwd);
+              addWideRow(
+                "MCP:",
+                `${mcpServersCount} server(s)`,
+                "PLUGINS:",
+                `${packagesCount} package(s)`,
+              );
+              addWideRow(
+                "AGENTS:",
+                `${skills.length} loaded`,
+                "EXTENSIONS:",
+                `${extensionsCount} active`,
+              );
+              addWideRow(
+                "VER:",
+                `v${VERSION}`,
+                "TOOLS:",
+                `${customTools.length} custom`,
+              );
+            } else {
+              addNarrowRow("GIT:", gitBranch);
+              addNarrowRow("PATH:", ctx.cwd);
+              addNarrowRow("MCP:", `${mcpServersCount} server(s)`);
+              addNarrowRow("PLUGINS:", `${packagesCount} package(s)`);
+              addNarrowRow("AGENTS:", `${skills.length} loaded`);
+              addNarrowRow("EXTENSIONS:", `${extensionsCount} active`);
+              addNarrowRow("VER:", `v${VERSION}`);
+              addNarrowRow("TOOLS:", `${customTools.length} custom`);
+            }
+
+            b.addRow();
+            b.center(width);
+
+            const out: string[] = [];
+            const layout = b.lines;
+
+            for (let y = 0; y < layout.length; y++) {
+              const row = layout[y] || [];
+              const firstBannerX = row.findIndex((c) => c.type === "banner");
+              let line = "";
+
+              for (let x = 0; x < row.length; x++) {
+                const cell = row[x] || { char: " ", type: "none" as const };
+                if (cell.char === " ") {
+                  line += " ";
+                  continue;
+                }
+
+                if (cell.type === "rose") {
+                  const pulse = 0.9 + Math.sin((x + y + frame) * 0.08) * 0.1;
+                  const k = Math.max(0.01, roseOpacity * pulse);
+                  const f = Math.pow(flashPhase, 0.4);
+
+                  const rBase = Math.floor(255 * k);
+                  const gBase = Math.floor(118 * k);
+                  const bBase = Math.floor(195 * k);
+
+                  if (f > 0.85) {
+                    line += `\x1b[1m\x1b[38;2;255;255;255m${cell.char}\x1b[0m`;
+                  } else {
+                    const r = Math.floor(rBase + (255 - rBase) * f);
+                    const g = Math.floor(gBase + (255 - gBase) * f);
+                    const bColor = Math.floor(bBase + (255 - bBase) * f);
+                    line += rgb(r, g, bColor, cell.char);
+                  }
+                  continue;
+                }
+
+                if (cell.type === "banner") {
+                  if (cell.char === "▒") {
+                    line += rgb(95, 30, 60, cell.char);
+                    continue;
+                  }
+                  const localX = firstBannerX >= 0 ? x - firstBannerX : x;
+                  const sweep = Math.floor((tick - 16) * 2.2);
+                  const isFlashing =
+                    tick >= 16 && localX >= sweep - 4 && localX <= sweep + 2;
+
+                  if (isFlashing) {
+                    line += `\x1b[1m\x1b[38;2;255;255;255m${cell.char}\x1b[0m`;
+                  } else {
+                    line += rgb(255, 120, 198, cell.char);
+                  }
+                  continue;
+                }
+
+                switch (cell.type) {
+                  case "label":
+                    line += rgb(200, 100, 160, cell.char);
+                    break;
+                  case "value":
+                    line += rgb(255, 140, 210, cell.char);
+                    break;
+                  case "dim":
+                    line += theme.fg("dim", cell.char);
+                    break;
+                  case "accent":
+                    line += theme.fg("accent", cell.char);
+                    break;
+                  default:
+                    line += cell.char;
+                }
+              }
+
+              out.push(truncateToWidth(line, Math.max(1, width), ""));
+            }
+
+            return out;
+          },
+          invalidate() {
+            if (state.timer) {
+              clearInterval(state.timer);
+              state.timer = null;
+            }
+            closeIntroSafely();
+          },
+        };
+      });
+    }, 50);
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-pi",
-  "version": "0.1.23",
+  "version": "0.2.1",
   "description": "Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.",
   "license": "MIT",
   "type": "module",
@@ -56,5 +56,8 @@
     "@earendil-works/pi-coding-agent": {
       "optional": true
     }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
   }
 }

package/skills/gentle-ai/SKILL.md

@@ -17,7 +17,8 @@ When asked who or what you are, answer as el Gentleman: a Pi-specific coding-age
 - Use OpenSpec-style artifacts for proposal, specs, design, tasks, apply progress, verify report, and archive notes.
 - If tests exist, follow strict TDD: RED, GREEN, TRIANGULATE, REFACTOR, and record evidence.
 - Keep one parent session responsible for orchestration; child subagents should receive concrete phase work and must not spawn more subagents.
-- Prefer fresh-context reviewers for adversarial review and forked workers only after direction is approved.
+- Parent-only delegation triggers apply after complexity appears: 4+ files for understanding, 2+ non-trivial files to write, commit/PR after code changes, tooling/worktree incidents, or long sessions with accumulating complexity.
+- As parent, prefer `scout`/`context-builder` for context-heavy exploration, one forked `worker` for implementation, and fresh-context `reviewer` agents for adversarial review before PRs and after incidents.
 - Keep writes single-threaded unless the user explicitly approves isolated parallel worktrees.
 - Forecast review workload before large changes; ask before producing oversized or multi-area diffs.
 - Never claim persistent memory is available because of el Gentleman itself; memory is provided by separate packages/tools when active.
@@ -43,7 +44,15 @@ clarify → explore → proposal → spec → design → tasks → apply → ver
 For bounded implementation with subagents:
 
 ```text
-clarify → planner/worker → fresh reviewers → worker fixes → verify
+clarify → scout/context-builder when context-heavy → one worker → fresh reviewers → worker fixes → verify
 ```
 
+Hard delegation triggers:
+
+- **4-file rule**: reading 4+ files to understand means delegate exploration.
+- **Multi-file write rule**: touching 2+ non-trivial files means use one worker or at least fresh review before completion.
+- **PR rule**: before commit/push/PR for code changes, run fresh review unless the diff is trivial docs/text.
+- **Incident rule**: after wrong cwd, accidental worktree/repo mutation, merge recovery, confusing test command, or environment workaround, run fresh audit.
+- **Long-session rule**: after roughly 20 tool calls, 5 exploratory reads, or 2 non-mechanical edits with no delegation and accumulating complexity, pause and choose a subagent or justify not doing so.
+
 The package auto-installs SDD agents and chains into the project when a Pi session starts. Use `/gentle-ai:install-sdd --force` only for recovery or intentional overwrite.