@maestria/pi 0.6.8 → 0.6.9

package/README.md

@@ -1,77 +1,41 @@
 # @maestria/pi
 
-A [Pi coding agent](https://pi.software/) extension that brings Maestria's structured agent orchestration to Pi.
+A [Pi coding agent](https://pi.software/) extension that brings Maestria's structured agent orchestration - specialist delegation, workflow modes, and maker/checker review - to Pi.
 
-## Features
-
-- **4 Methodology Skills** - Orchestrator dispatcher, global agent rules, handoff contract, and iteration limits - automatically injected into every session via Pi's standard skill system (`SKILL.md` files registered in `pi.skills`)
-- **3 Workflow Modes** - `fein` (full pipeline), `sonar` (research only), `blitz` (fast implementation)
-- **Skill-Based Prompt Injection** - Behavioral instructions injected via Pi's native skill mechanism, not custom event hooks. Skills are auto-discovered from the package manifest and loaded into the system prompt by Pi's resource loader - the standard pattern used by all major Pi extensions.
-- **Compaction Preservation** - Session state survives compaction with structured summaries
-- **Subagent Dispatch** - Delegation via `@gotgenes/pi-subagents` with 7-field handoff validation
-- **Maker/Checker Split** - Review mode blocks destructive tools. Dangerous bash patterns flagged.
+> This package is part of Maestria. See [VISION.md](https://github.com/agustinusnathaniel/maestria/blob/main/VISION.md) for the project vision, motivation, and scope. The agents and skills are **generated** from the canonical directives in `packages/core/agent-directives/` by the [sync pipeline](https://github.com/agustinusnathaniel/maestria/blob/main/CONTRIBUTING.md#3-the-sync-pipeline-core-concept).
 
 ## Installation
 
-### Recommended: via maestria CLI
-
 ```bash
+# Recommended: via the maestria CLI (installs the peer dependency too)
 pnpx maestria@latest install pi
-```
-
-The CLI automatically installs both `@gotgenes/pi-subagents` (required peer dependency for subagent dispatch) and `@maestria/pi` in the correct order.
-
-### Alternative: manual Pi CLI
 
-```bash
-# Install required peer dependency first
+# Manual: install the required peer dependency first, then the extension
 pi install npm:@gotgenes/pi-subagents
-
-# Install the extension
 pi install npm:@maestria/pi
 ```
 
-### Uninstall
+Uninstall via `pnpx maestria@latest uninstall pi`. The `@gotgenes/pi-subagents` peer dependency is shared with other Pi extensions; only remove it separately if nothing else needs it.
 
-```bash
-# Via maestria CLI (removes @maestria/pi)
-pnpx maestria@latest uninstall pi
-```
+## What It Provides
 
-Note: `@gotgenes/pi-subagents` is a shared dependency that other Pi extensions may use. Only remove it if no other extensions need it:
+- **4 methodology skills** - orchestrator dispatcher, global agent rules, handoff contract, and iteration limits, injected into every session via Pi's standard skill system.
+- **3 workflow modes** - `/fein` (full pipeline), `/sonar` (research only), `/blitz` (fast implementation).
+- **Compaction preservation** - session state survives compaction with structured summaries.
+- **Subagent dispatch** - delegation via `@gotgenes/pi-subagents` with 7-field handoff validation.
+- **Maker/checker split** - `/review` mode blocks destructive tools where Pi supports it.
 
-```bash
-pi uninstall @gotgenes/pi-subagents
-```
-
-## Commands
-
-| Command | Description |
-| --- | --- |
-| `/fein <goal>` | Set workflow mode to full pipeline (recon → design → impl → review) |
-| `/sonar <goal>` | Set workflow mode to research only (recon → design → stop) |
-| `/blitz <goal>` | Set workflow mode to fast implementation (builder directly) |
-| `/review <target>` | Enter review mode - blocks destructive tools, sets read-only toolset |
-| `/restore-model` | Restore the original model and tools active before review mode |
-| `/handoff <goal>` | Generate a structured handoff prompt for a new task context |
-| `/review-model <model-id>` | Set which model to use when entering review mode |
-| `/maestria-status` | Show current maestria session state including handoff history |
+## Support / Platform Notes
 
-## Development
+- Subagent dispatch depends on the `@gotgenes/pi-subagents` peer package; the maestria CLI installs it for you.
+- The methodology is advisory prompt guidance; the maker/checker split is enforced at the tool level only where Pi supports review-mode tool blocking.
+- Pi-specific: `@maestria/omp` is a separate package for Oh My Pi.
+- The agents and skills are projections of the canonical core directives. To change behavior, edit `packages/core/agent-directives/` and re-run the sync pipeline - never edit the generated files under `agents/` or `skills/` directly.
 
-```bash
-# Install dependencies
-pnpm install
-
-# Build
-vp pack
+## Documentation and Changelog
 
-# Test
-vp test
-
-# Format, lint, type-check
-vp check
-```
+- [User-facing documentation](https://maestria.sznm.dev/pi-omp/) on the docs site (shared with `@maestria/omp`)
+- [Changelog](https://github.com/agustinusnathaniel/maestria/blob/main/packages/pi/CHANGELOG.md)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maestria/pi",
-  "version": "0.6.8",
+  "version": "0.6.9",
   "description": "Maestria extension for the Pi coding agent",
   "keywords": [
     "agent-orchestration",

package/skills/global-rules/SKILL.md

@@ -41,6 +41,14 @@ This is the cross-platform behavior contract. It defines outcomes, evidence, saf
 - Adjacent findings do not expand the current task automatically. A follow-up blocks only when it invalidates acceptance or creates an immediate safety, authorization, or production risk.
 - Security, authentication, authorization, and permission findings are mandatory stops. Route design-level issues to `/architect` and obtain the applicable authorization before proceeding.
 
+## Session Continuation and Delivery
+
+- **!!! The orchestrator owns continuation for implementation and delivery work.** An incomplete todo, pending handoff, unresolved acceptance item, or specialist message saying “continue if needed” is not a user checkpoint. Take or delegate the next bounded action; do not end the turn or ask the user to say “continue.” Research-only, planning-only, explicitly read-only, and host-blocked work terminates at its requested artifact or exact blocker.
+- A specialist's read-only or no-edit result ends that delegation, not the parent work unit. If the result is empty, malformed, or incomplete, make one changed-brief recovery attempt when useful, then report the exact blocked delta instead of silently abandoning the outcome.
+- Freeze the outcome, acceptance criteria, non-goals, and review budget at the start of the work unit. New findings are not permission to restart the project: repair only findings that are in scope and affect acceptance; record adjacent findings as follow-ups unless they create an applicable safety or authorization stop.
+- Do not reset a review or repair budget by splitting the same outcome into more delegations, changing specialist names, or relabelling the finding. A new scope requires a new outcome and acceptance criteria.
+- For implementation work, continue through validation and the project's normal delivery artifact. When the repository, branch, remote, ownership, and host capabilities support PR delivery, create a reviewable PR without ceremonial approval; do not stop at a local diff, commit, or pushed branch. Research-only, planning-only, explicitly read-only, and host-blocked work terminates at its requested artifact or exact blocker. Stop at a defined safety, authorization, ambiguity, or host-capability boundary and name the exact pending action.
+
 ## Delegation and Context
 
 Supported specialists are `adventurer`, `architect`, `builder`, `diagnose`, `planner`, `reviewer`, and `writer`.

package/skills/iteration-limits/SKILL.md

@@ -15,8 +15,14 @@ description: >-
 - Define a verifiable termination condition before looping.
 - Set a practical repair bound, normally three rounds. Extend only when the
   latest attempt shows observable progress; never silently reset the bound.
+- The bound applies to the same user outcome, even when work is split across
+  more delegations or specialist types. Start a new bound only after recording
+  a genuinely new outcome with new acceptance criteria.
 - Repeated causes, repeated findings, restored diffs, or no new evidence mean
   non-progress. Change strategy or escalate rather than retrying unchanged.
+- Do not broaden the outcome merely because review found adjacent work. Keep
+  the accepted slice deliverable and record adjacent findings as follow-ups
+  unless they invalidate acceptance or trigger a safety/authorization stop.
 - Stop on safety ambiguity, authorization boundaries, or unresolved review
   blockers. Report: `Tried X, Y, Z. Blocked by [cause]. Need [input] to
   proceed.`

package/skills/orchestrator/SKILL.md

@@ -100,7 +100,13 @@ Modes are case-insensitive and per-turn unless the platform documents another li
 
 ## Commit and Session Flow
 
-For normal engineering work, own the delivery path: `inspect -> plan -> implement -> validate -> review -> repair material blockers -> commit -> push -> PR`. Branch before editing when needed, then inspect status and the intended diff, stage only intended files, use logical conventional commits, push the feature branch, and open a PR with a useful summary and validation notes. Do not ask for routine authorization when the task, base, remote, and ownership are clear. Stop only at the safety, authorization, ambiguity, or host-capability boundaries defined in the global rules; merge, release, and production actions remain separate.
+For implementation work, own the delivery path: `inspect -> plan -> implement -> validate -> review -> repair -> commit -> push -> PR`.
+
+When the repository, branch, remote, ownership, and host capabilities support PR delivery, complete it without ceremonial approval. Do not stop at a local diff, commit, pushed branch, or `PR pending`. Merge, release, and production actions remain separate.
+
+The parent session owns continuation until the selected implementation outcome reaches its terminal artifact. Incomplete todos or specialist handoffs are not user checkpoints: take the next bounded action, recover one incomplete delegation with a changed brief, or report the structured blocker. Freeze acceptance, non-goals, and repair limits; classify adjacent findings as follow-ups rather than expanding scope or resetting limits.
+
+Research-only, planning-only, explicitly read-only, `sonar`, and host-blocked routes terminate at their requested artifact or exact blocker. Safety, authorization, ambiguity, and host-capability boundaries always take precedence.
 
 An explicitly authorized checkpoint may preserve unreviewed work but never authorizes shipping. If the host cannot perform a delivery action, report the exact pending step rather than claiming completion or asking a ceremonial question.