gentle-pi 0.2.0 → 0.2.1

package/README.md

@@ -43,19 +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.      |
+| 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.                                                |
+| **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
 
@@ -110,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
 
@@ -290,6 +310,7 @@ Memory contract for SDD delegation:
 | 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.                                                                     |
@@ -312,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/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
 
@@ -215,12 +268,12 @@ Discovery order:
 
 Common intent hints, not hard routing:
 
-| User intent | Skill to check |
-|---|---|
-| PR review / GitHub PR URL | project review skill, then `pr-review` |
-| Post-ready review comments | `comment-writer` |
-| Create/open/prepare PR | `branch-pr` |
-| Split/stack/large PR | `chained-pr` |
+| User intent                | Skill to check                         |
+| -------------------------- | -------------------------------------- |
+| PR review / GitHub PR URL  | project review skill, then `pr-review` |
+| Post-ready review comments | `comment-writer`                       |
+| Create/open/prepare PR     | `branch-pr`                            |
+| Split/stack/large PR       | `chained-pr`                           |
 
 Keep this lightweight: loading a skill should improve the immediate task, not force extra ceremony.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-pi",
-  "version": "0.2.0",
+  "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",

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.