@emiliosp/pi-maestro 0.15.0 → 0.17.0

package/ADR.md

@@ -275,3 +275,130 @@ Approval can finish at `candidate-ready` without agent execution. Agent and mode
 ### Evidence
 
 [Approved design](.specs/20261103-161424-maestro-27-make-implementation-phases-optional/design.md) and [phase selection](docs/configuration.md#phase-selection).
+
+## ADR-010: Use the Pi SDK for sequential agent delegation
+
+### Status
+
+Design decisions confirmed by the `owner`. Not implemented.
+
+### Context
+
+`Maestro` currently depends on `pi-subagents` to execute the `builder`, `verifier`, and `simplifier`. Its delegation needs are limited: only one workflow and one child
+agent execute at a time, and `Maestro` waits for each child to finish. `Maestro` already owns workflow transitions, role instructions, saved `handoffs`, and result
+validation.
+
+The `owner` wants to remove the `pi-subagents` dependency without building a general-purpose delegation framework. Pi provides `createAgentSession()` for direct SDK
+integration and `RpcClient` for subprocess control. Separate conversations do not require separate processes.
+
+### Decision
+
+1. Replace `pi-subagents` delegation with direct use of the Pi SDK through `createAgentSession()`, rather than RPC subprocesses.
+2. Preserve sequential execution: one workflow at a time, one child agent at a time, with `Maestro` waiting for completion.
+3. Use task-and-handoff communication, not a live supervisor dialogue. `Maestro` assigns the task; the child works, saves its `handoff`, and finishes.
+4. When an `owner` decision is needed, the `builder` saves an `escalation` and ends its `run`. `Maestro` discusses it with the `owner` and records the decisions through
+   the existing workflow. Any subsequent `builder` `run` starts a fresh conversation and reads the saved decisions.
+5. Child sessions must have access to the same working tools available to `Maestro`, plus the tools needed to save their own `handoffs`. Do not load the main `Maestro`
+   extension into child sessions. Tools supplied by other extensions may remain available even if they support delegation; role instructions forbid using them to
+   delegate. This is a tool-access requirement, not merely an extension-loading policy.
+6. Automatically load enabled global and project extensions, excluding the main `Maestro` extension. Provide the corresponding working-tool environment through Pi's
+   native APIs and configuration, including separate Pi support such as MCP and `codemode` where needed. Loading the same extensions alone does not reproduce every CLI
+   capability. Compatibility of arbitrary extensions, tools, and model providers is outside Maestro's responsibility; do not add custom compatibility checks or adapters.
+7. All three child roles receive the owner's global instruction file, normally `~/.pi/agent/AGENTS.md`, preserving the current `inheritGlobalContext: true` behavior.
+   These instructions are not the parent's conversation history.
+8. All three child roles automatically receive project instructions discovered by Pi, such as applicable `AGENTS.md` files, preserving the current
+   `inheritProjectContext: true` behavior. These instructions supplement global instructions and role-specific guidance.
+9. All three child roles can discover and use available skills, preserving the current `inheritSkills: true` behavior. Expose the skill catalog without loading every
+   skill's full contents into the conversation. Skills remain subject to the child's role boundaries and permitted tools; they do not authorize delegation or workflow
+   management.
+10. During a child `run`, report the role, elapsed time, current tool, and recent normal assistant text through Pi's standard tool-progress updates (`onUpdate`). Use Pi's
+    built-in presentation, including its default layout, truncation, and expansion behavior. Do not build a custom renderer or implement a fixed visible-line count or
+    terminal-height adaptation. Update progress in place instead of appending intermediate messages to the main conversation. Do not include internal reasoning or full
+    command output. Continue reporting activity when the child produces no text; do not prompt it to generate artificial progress messages.
+11. Intermediate activity text is UI-only and must not enter the main model's context. `Maestro` continues to receive the existing workflow result. Pi's display limits do
+    not truncate the saved child conversation. The five-, ten-, and twenty-line alternatives are superseded by the decision to use Pi's standard presentation.
+12. Persist child conversations using Pi's native session format, rather than a custom transcript format. Saved sessions remain available after execution for diagnosis,
+    including unsuccessful executions. Each child `run` starts a new conversation; persistence does not introduce automatic session reuse or workflow recovery.
+13. At child completion or failure, show the `owner` the path to its saved Pi session file, when one exists. The `owner` can inspect the file directly or use Pi's native
+    HTML export with `pi --export <session-file> conversation.html`. Do not build a transcript inspector inside `Maestro`. Reading or exporting a transcript does not
+    resume child execution.
+14. Do not impose an automatic child `run` timeout in `Maestro`. Remove `builder.timeoutMinutes`, `verifier.timeoutMinutes`, and `simplifier.timeoutMinutes` from
+    `.pi/maestro.json` configuration support, including schema validation, defaults, launch inputs, and configuration documentation. A child continues until it finishes,
+    fails, or is manually interrupted. This removes the workflow-level deadline, not the elapsed-time progress display or timeouts internal to Pi and its tools.
+15. Remove `timeoutMinutes` from the configuration schemas and retain `additionalProperties: false`. Existing TypeBox-based validation rejects configuration files that
+    still contain the field. Do not add a migration, ignored legacy fields, or special compatibility handling. The `owner` removes obsolete fields manually.
+16. Preserve the existing execution-error policy. Launch failures, failed child executions, and missing or invalid `handoffs` stop the workflow and report the error.
+    `Maestro` does not automatically start another child session to retry, repair saved state, or roll back files. Preserve the remaining project files and saved workflow
+    state for manual `owner` follow-up, including partial protocol writes. Errors do not introduce recovery transitions or synthetic `escalations`.
+17. Propagate manual cancellation of the main tool to its active child through `session.abort()` and await the interruption before releasing the child session. Do not
+    send a final model prompt asking the child to finish, and do not generate a synthetic `handoff`. Leave project files and saved workflow state unchanged by cleanup.
+    Close child sessions and release progress subscriptions and session resources on completion, failure, or cancellation. Do not start another child while the previous
+    child remains active.
+18. Store child sessions in a `subagents/` subdirectory of Pi's normal project session directory, normally `~/.pi/agent/sessions/--<project-path>--/subagents/`. Resolve
+    the parent directory through Pi's session-directory API rather than reimplementing project-path encoding. Use Pi's native `SessionManager` with this directory. Do not
+    create a `subagents/` directory inside the project repository.
+19. Require Pi 1.5.0 or later for the SDK-based implementation. Update the declared Pi requirement and align implementation verification with this baseline. Do not add
+    compatibility fallbacks for earlier Pi versions. This minimum is a scope choice, not a claim that all earlier versions lack the required APIs.
+20. Do not build an additional tool allowlist or exclusion list to prevent child delegation. Children may have delegation tools available, but their role instructions
+    forbid using them. This deliberately relies on instruction compliance rather than technical removal of delegation capabilities. The main `Maestro` extension remains
+    excluded.
+21. Leave compatibility of external integrations to Pi and the `owner`. Do not add a preflight that compares parent and child tool availability, extension health checks,
+    special adapters, or a fallback system for incompatible integrations. This scope boundary does not suppress errors actually reported during launch or execution; those
+    follow the existing stop-and-report policy.
+
+### Consequences
+
+The replacement does not need supervisor request routing or a mechanism that makes the main model answer a child while waiting for it. Saved `handoffs` remain the
+communication boundary for completed work and `escalations`.
+
+SDK sessions share a Node.js process. Separate conversation histories do not isolate module-level mutable state or project files. Child resource loading must account for
+this distinction.
+
+Automatic extension loading intentionally differs from the current foreground behavior of `pi-subagents` 0.78.0, which does not automatically load the parent's global and
+project extensions. Shared working-tool access is provided through Pi's native environment, not an independent compatibility guarantee for every integration. The
+replacement must use Pi's tool activation and support such as MCP and `codemode`, rather than assuming the SDK supplies the CLI's capabilities by default. There is no
+custom parity check, health gate, or adapter layer for third-party integrations. Children do not inherit the parent's conversation, but they share the process and may
+interact with process-wide mutable state. Loaded extensions can create additional connections, timers, and process-wide effects. Excluding the main `Maestro` extension
+does not establish compatibility with every other extension or remove delegation tools supplied by other extensions. `Maestro` launches its own children sequentially;
+compliance with the broader no-delegation rule relies on child instructions. A child that ignores those instructions could launch other agents. This accepted limitation
+avoids maintaining tool classifications and exclusion lists and does not claim a sandbox; even ordinary shell access can launch processes.
+
+Pi's standard tool-progress presentation replaces FleetView's live activity display, not its full transcript inspector. `Maestro` owns the progress data, not a new
+rendering system or a guaranteed panel size. Displaying text already produced by the child requires no additional model generation and does not add that text to the main
+model's context. Full transcript inspection uses saved session files and Pi's existing export capability rather than a replacement inspector. The main tool must connect
+cancellation to the child SDK session and perform session cleanup; selecting the SDK alone does not wire these operations together.
+
+Native session files retain child messages, tool calls, and tool results beyond the lifetime of the child session. They may contain project data present in those messages
+and results. Persistence is separate from the live progress display and does not add the transcript to the main model's context. The dedicated `subagents/` subdirectory
+keeps child session files separate from the main session files without adding transcript files to the project repository or introducing a custom storage format.
+
+Removing the configured deadline simplifies child execution but permits indefinitely running work until manual interruption. This is a breaking configuration change:
+files that still contain `timeoutMinutes` fail existing configuration validation until the `owner` removes the obsolete fields. Document the removal without adding legacy
+compatibility code.
+
+Manual cancellation uses Pi's in-process cancellation lifecycle, not termination of a separate operating-system process. It does not undo completed writes or introduce a
+final model turn. `Maestro` uses Pi's cancellation and cleanup lifecycle; behavior of third-party integrations remains outside its compatibility contract.
+
+The Pi minimum increases from the currently documented 1.0.0 to 1.5.0. Earlier hosts are outside the new compatibility contract. At decision time, the project has Pi
+1.0.3 installed locally and the active harness uses Pi 1.5.0; the implementation must be verified against the selected baseline rather than treating the older local
+installation as sufficient verification. This ADR changes no installed dependencies.
+
+### Evidence
+
+During the architecture discussion, the `owner` selected the SDK and task-and-handoff communication, then clarified the tool-access contract: the same working tools as
+`Maestro`, plus child handoff tools, with the main `Maestro` extension excluded. The `owner` subsequently accepted that delegation tools from other extensions may remain
+available, with their use forbidden by instructions rather than additional tool filters. The `owner` also confirmed that all three roles continue receiving global and
+automatically discovered project instructions, as declared by `inheritGlobalContext: true` and `inheritProjectContext: true` in the existing role definitions. All three
+roles also retain access to the skill catalog and can load relevant skill instructions, consistent with their existing `inheritSkills: true` setting and subject to role
+and tool restrictions. After discussing bounded display sizes, the `owner` selected Pi's standard tool-progress presentation rather than custom rendering, while retaining
+recent assistant text without sending intermediate text to the main model. The `owner` selected persistent transcripts in Pi's native session format, while keeping each
+child conversation fresh. The `owner` chose to receive the saved session path and use direct file inspection or Pi's native HTML export, without a `Maestro` transcript
+inspector. The `owner` chose the simplest execution option: no automatic child deadline, with the timeout settings removed from configuration. The `owner` accepted that
+existing TypeBox-based validation rejects configurations retaining `timeoutMinutes`, without migration or compatibility handling, and confirmed the existing
+execution-error policy: stop and report, retain files, and leave follow-up to the `owner`, without automatic retries, repair, or rollback. The `owner` selected manual
+interruption through `session.abort()` followed by session cleanup, without a final model turn or synthetic `handoff`, and placed saved child sessions in `subagents/`
+beneath Pi's project session directory, not inside the repository. The `owner` chose Pi 1.5.0 as the minimum supported version, without fallbacks for earlier hosts. The
+`owner` explicitly excluded compatibility handling for external integrations from scope; no custom checks, adapters, or reduced-capacity fallback system are required.
+Existing boundaries are described in [subagent integration](docs/subagent-integration.md), [delegation](src/tools/utils/pi-subagent-delegation.ts),
+[builder execution](src/tools/main/run-builder.ts), and the [child extension](extensions/maestro-subagent.ts). These links describe the current implementation, not the
+planned SDK replacement.

package/CHANGELOG.md

@@ -3,6 +3,28 @@
 This file summarizes meaningful changes to the codebase, including behavior, data formats, architecture, and development tools. Git tags identify version boundaries;
 GitHub Releases are not required.
 
+## 0.17.0
+
+1. Added a standalone internal Pi SDK executor. Each invocation starts a fresh conversation with supplied model, thinking level, role guidance, working directory, and
+   additional tools. Native resource discovery loads instructions, skills, enabled extensions, and configured MCP, codemode, and tool search support, excluding the main
+   `Maestro` extension.
+2. Added native child session persistence in `subagents/` beneath Pi's project session directory.
+3. Replaced the `acceptance criterion` `probe` and `expected result` fields with `GIVEN`, `WHEN`, and `THEN`, keeping the concrete example. Requirement bodies now use a
+   named actor followed by `MUST` in the requirement heading. Added an optional bullet-list `## Assumptions` section to `spec.md`.
+
+The `builder`, `verifier`, and `simplifier` still use `pi-subagents`. Workflow migration and dependency removal remain separate work.
+
+## 0.16.0
+
+1. Required Pi 1.5.0 or later and pinned the development Pi dependencies to that baseline, so type checks and tests run against the declared host. The extension now uses
+   TypeBox `Type.Enum` with an explicit string type instead of the `StringEnum` helper, calls `before_agent_start` with Pi's message object, and expects the `truncated`
+   field on `exec` results. See [PR #46](https://github.com/emilioSp/pi-maestro/pull/46).
+2. Breaking: removed `timeoutMinutes` from the agent configuration. Configuration files that still contain the field fail validation until the `owner` removes it; no
+   migration or legacy handling is provided.
+3. Replaced the configured per-agent timeout with a fixed, non-configurable deadline passed to `pi-subagents` for every `run`. A `run` is no longer bounded by a
+   configured duration.
+4. Updated `ADR.md`, `ROADMAP.md`, `README.md`, and `docs/` for the new baseline and the removed timeout settings. `MAESTRO-FREE-1` is recorded as completed.
+
 ## 0.15.0
 
 1. Added per-agent `required` booleans in `.pi/maestro.json`, all defaulting to `true`. Disabling `builder` completes the workflow at `spec` approval without agents;

package/README.md

@@ -45,7 +45,7 @@ The following official sources document the conceptual references. The links poi
 2. **Describe behavior, not routine implementation choices.** [OpenSpec's schema][openspec-schema] defines a `specification` as a behavior contract, not an implementation
    plan. `Maestro` records required behavior, constraints, and approved architectural decisions in the `spec`, leaving routine implementation choices to the `builder`.
 3. **Use concrete, testable scenarios.** [OpenSpec's schema][openspec-schema] pairs requirements with scenarios; [Spec Kit's template][spec-kit-template] uses
-   Given/When/Then acceptance scenarios. Each `Maestro` `acceptance criterion` includes a `probe`, an `expected result`, and a concrete example.
+   Given/When/Then acceptance scenarios. Each `Maestro` `acceptance criterion` includes a `GIVEN`, a `WHEN`, a `THEN`, and a concrete example.
 4. **Clarify requirements progressively.** [Spec Kit's clarify command][spec-kit-clarify] asks one question at a time and integrates accepted answers into the
    `specification`. `Maestro` likewise asks one focused question, waits for the owner's answer, and updates the `spec` before asking the next question.
 5. **Review requirements separately from testing code.** [Spec Kit's checklist command][spec-kit-checklist] evaluates requirements for completeness, clarity, consistency,
@@ -54,7 +54,7 @@ The following official sources document the conceptual references. The links poi
 6. **Separate motivation, behavior, and design.** [OpenSpec's schema][openspec-schema] separates these concerns and calls for `design.md` only when significant technical
    decisions need recording, including reasons, alternatives, and risks.
 7. **Make requirement changes explicit.** [OpenSpec's schema][openspec-schema] distinguishes added, modified, removed, and renamed requirements. `Maestro` adapts this
-   concept with one `Delta` field per requirement: `added`, `modified`, or `removed`. Each requirement states the complete required outcome.
+   concept with one `Delta` field per requirement: `added`, `modified`, or `removed`. Each requirement heading states the required outcome with a named actor and `MUST`.
 8. **Make requirement coverage traceable.** [Spec Kit's analyze command][spec-kit-analyze] maps requirements to implementation tasks and identifies coverage gaps.
    `Maestro` applies a related principle to verification: each requirement has a `Verified by` field linking to its `acceptance criteria`, existing tests covering exact
    scenarios, or both. The mapping connects requirements to verification.
@@ -83,7 +83,7 @@ An `escalation` asks the `owner` to decide an implementation question. A `findin
 
 1. macOS.
 2. Node.js 26 or later.
-3. Pi 1.0.0 or later.
+3. Pi 1.5.0 or later.
 4. `pi-subagents` installed and enabled in Pi when `builder` is enabled.
 5. Access to the models for enabled agents.
 6. A project directory that Pi trusts.
@@ -151,9 +151,9 @@ files do not automatically restore or resume an incomplete workflow. The `owner`
 ## Configuration
 
 `Maestro` uses default values when `.pi/maestro.json` is absent from the project root. The `owner` can add this file to change the `spec` directory, models, thinking
-levels, timeouts, or selected phases. Each agent has a `required` boolean that defaults to `true`. Set flags before activation and keep configuration unchanged during the
-workflow. With `builder.required: false`, approval finishes with only an approved `spec` for implementation elsewhere. Otherwise `verifier` and `simplifier` can be
-disabled independently. Skipped work is identified in the final summary and is not claimed as completed. See [Configuration](docs/configuration.md#phase-selection).
+levels, or selected phases. Each agent has a `required` boolean that defaults to `true`. Set flags before activation and keep configuration unchanged during the workflow.
+With `builder.required: false`, approval finishes with only an approved `spec` for implementation elsewhere. Otherwise `verifier` and `simplifier` can be disabled
+independently. Skipped work is identified in the final summary and is not claimed as completed. See [Configuration](docs/configuration.md#phase-selection).
 
 ## Documentation
 
@@ -161,7 +161,7 @@ The reading order is:
 
 1. [Glossary](docs/glossary.md): terms and identifiers used in `specs`, reports, and `Maestro` messages. Read this before the first workflow.
 2. [Workflow](docs/workflow.md): approvals, decisions, and how each `run` produces `artifacts`.
-3. [Configuration](docs/configuration.md): project paths, models, and timeouts.
+3. [Configuration](docs/configuration.md): project paths, models, and thinking levels.
 4. [Subagent integration](docs/subagent-integration.md): agent context, execution, and activity tracking.
 
 ## Project constitution

package/ROADMAP.md

@@ -10,30 +10,38 @@ reaching `candidate-ready`. Linear onboarding and test issues are not project ro
 
 ## Overview
 
-| ID         | Item                                                                                                                               | Status                                |
-| ---------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
-| MAESTRO-6  | [Display specs in a browser](#maestro-6-display-specs-in-a-browser)                                                                | Backlog                               |
-| MAESTRO-7  | [Route builder failures through owner escalations](#maestro-7-route-builder-failures-through-owner-escalations)                    | Completed                             |
-| MAESTRO-8  | [Store escalations and owner decisions in builder handoffs](#maestro-8-store-escalations-and-owner-decisions-in-builder-handoffs)  | Completed                             |
-| MAESTRO-9  | [Format glossary terms consistently](#maestro-9-format-glossary-terms-consistently)                                                | Completed                             |
-| MAESTRO-10 | [Improve status presentation and activation feedback](#maestro-10-improve-status-presentation-and-activation-feedback)             | Completed                             |
-| MAESTRO-11 | [Introduce Maestro at activation](#maestro-11-introduce-maestro-at-activation)                                                     | Completed                             |
-| MAESTRO-12 | [Verify code quality against AGENTS.md instructions](#maestro-12-verify-code-quality-against-agentsmd-instructions)                | Completed                             |
-| MAESTRO-13 | [Check subagent extensions at activation](#maestro-13-check-subagent-extensions-at-activation)                                     | Completed                             |
-| MAESTRO-14 | [Rename the test support directory](#maestro-14-rename-the-test-support-directory)                                                 | Completed                             |
-| MAESTRO-15 | [Match handoff criteria to the approved spec](#maestro-15-match-handoff-criteria-to-the-approved-spec)                             | Completed                             |
-| MAESTRO-16 | [Route finding-driven spec revisions through drafting-spec](#maestro-16-route-finding-driven-spec-revisions-through-drafting-spec) | Completed                             |
-| MAESTRO-17 | [Keep acceptance criterion numbering continuous](#maestro-17-keep-acceptance-criterion-numbering-continuous)                       | Completed                             |
-| MAESTRO-18 | [Record escalation resolutions when the spec changes](#maestro-18-record-escalation-resolutions-when-the-spec-changes)             | Completed                             |
-| MAESTRO-19 | [Guide initial configuration](#maestro-19-guide-initial-configuration)                                                             | Backlog                               |
-| MAESTRO-20 | [Rename the npm package](#maestro-20-rename-the-npm-package)                                                                       | Backlog                               |
-| MAESTRO-21 | [Label acceptance criterion coverage](#maestro-21-label-acceptance-criterion-coverage)                                             | Completed                             |
-| MAESTRO-22 | [Avoid acceptance criteria already covered by tests](#maestro-22-avoid-acceptance-criteria-already-covered-by-tests)               | Completed                             |
-| MAESTRO-23 | [Change agent models before a builder run](#maestro-23-change-agent-models-before-a-builder-run)                                   | Backlog                               |
-| MAESTRO-24 | [Add a simplifier with one clear purpose per agent](#maestro-24-add-a-simplifier-with-one-clear-purpose-per-agent)                 | Completed                             |
-| MAESTRO-25 | [Define workflow reconciliation](#maestro-25-define-workflow-reconciliation)                                                       | Backlog                               |
-| MAESTRO-26 | [Exit Maestro mode automatically at workflow completion](#maestro-26-exit-maestro-mode-automatically-at-workflow-completion)       | Completed                             |
-| MAESTRO-27 | [Make all implementation phases optional](#maestro-27-make-all-implementation-phases-optional)                                     | Implemented, acceptance not confirmed |
+| ID                 | Item                                                                                                                               | Status      |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| MAESTRO-6          | [Display specs in a browser](#maestro-6-display-specs-in-a-browser)                                                                | Backlog     |
+| MAESTRO-7          | [Route builder failures through owner escalations](#maestro-7-route-builder-failures-through-owner-escalations)                    | Completed   |
+| MAESTRO-8          | [Store escalations and owner decisions in builder handoffs](#maestro-8-store-escalations-and-owner-decisions-in-builder-handoffs)  | Completed   |
+| MAESTRO-9          | [Format glossary terms consistently](#maestro-9-format-glossary-terms-consistently)                                                | Completed   |
+| MAESTRO-10         | [Improve status presentation and activation feedback](#maestro-10-improve-status-presentation-and-activation-feedback)             | Completed   |
+| MAESTRO-11         | [Introduce Maestro at activation](#maestro-11-introduce-maestro-at-activation)                                                     | Completed   |
+| MAESTRO-12         | [Verify code quality against AGENTS.md instructions](#maestro-12-verify-code-quality-against-agentsmd-instructions)                | Completed   |
+| MAESTRO-13         | [Check subagent extensions at activation](#maestro-13-check-subagent-extensions-at-activation)                                     | Completed   |
+| MAESTRO-14         | [Rename the test support directory](#maestro-14-rename-the-test-support-directory)                                                 | Completed   |
+| MAESTRO-15         | [Match handoff criteria to the approved spec](#maestro-15-match-handoff-criteria-to-the-approved-spec)                             | Completed   |
+| MAESTRO-16         | [Route finding-driven spec revisions through drafting-spec](#maestro-16-route-finding-driven-spec-revisions-through-drafting-spec) | Completed   |
+| MAESTRO-17         | [Keep acceptance criterion numbering continuous](#maestro-17-keep-acceptance-criterion-numbering-continuous)                       | Completed   |
+| MAESTRO-18         | [Record escalation resolutions when the spec changes](#maestro-18-record-escalation-resolutions-when-the-spec-changes)             | Completed   |
+| MAESTRO-19         | [Guide initial configuration](#maestro-19-guide-initial-configuration)                                                             | Backlog     |
+| MAESTRO-20         | [Rename the npm package](#maestro-20-rename-the-npm-package)                                                                       | Backlog     |
+| MAESTRO-21         | [Label acceptance criterion coverage](#maestro-21-label-acceptance-criterion-coverage)                                             | Completed   |
+| MAESTRO-22         | [Avoid acceptance criteria already covered by tests](#maestro-22-avoid-acceptance-criteria-already-covered-by-tests)               | Completed   |
+| MAESTRO-23         | [Change agent models before a builder run](#maestro-23-change-agent-models-before-a-builder-run)                                   | Backlog     |
+| MAESTRO-24         | [Add a simplifier with one clear purpose per agent](#maestro-24-add-a-simplifier-with-one-clear-purpose-per-agent)                 | Completed   |
+| MAESTRO-25         | [Define workflow reconciliation](#maestro-25-define-workflow-reconciliation)                                                       | Backlog     |
+| MAESTRO-26         | [Exit Maestro mode automatically at workflow completion](#maestro-26-exit-maestro-mode-automatically-at-workflow-completion)       | Completed   |
+| MAESTRO-27         | [Make all implementation phases optional](#maestro-27-make-all-implementation-phases-optional)                                     | Completed   |
+| MAESTRO-FREE-1     | [Require Pi 1.5.0](#maestro-free-1-require-pi-150)                                                                                 | Completed   |
+| MAESTRO-FREE-2     | [Remove Maestro run timeouts](#maestro-free-2-remove-maestro-run-timeouts)                                                         | Completed   |
+| MAESTRO-FREE-PRE-3 | [Implement internal SDK delegation](#maestro-free-pre-3-implement-internal-sdk-delegation)                                         | In progress |
+| MAESTRO-FREE-3     | [Run the builder through the Pi SDK](#maestro-free-3-run-the-builder-through-the-pi-sdk)                                           | Backlog     |
+| MAESTRO-FREE-4     | [Run the verifier through the Pi SDK](#maestro-free-4-run-the-verifier-through-the-pi-sdk)                                         | Backlog     |
+| MAESTRO-FREE-5     | [Run the simplifier through the Pi SDK](#maestro-free-5-run-the-simplifier-through-the-pi-sdk)                                     | Backlog     |
+| MAESTRO-FREE-6     | [Show SDK agent activity through Pi](#maestro-free-6-show-sdk-agent-activity-through-pi)                                           | Backlog     |
+| MAESTRO-FREE-7     | [Remove the pi-subagents dependency](#maestro-free-7-remove-the-pi-subagents-dependency)                                           | Backlog     |
 
 ## Backlog
 
@@ -90,8 +98,193 @@ Explore how `Maestro` can reconcile saved `artifacts` and workflow state. The re
 
 Not yet defined. The `owner` must define the intended outcome, recovery boundaries, and completion condition before this item can move forward.
 
+### MAESTRO-FREE-PRE-3: Implement internal SDK delegation
+
+#### Implementation and evidence
+
+The standalone executor is implemented under `src/delegation/` against the [approved specification](.specs/20261105-212231-implement-internal-pi-sdk-delegation/spec.md).
+Execution orchestration, session lifecycle, and pure reply interpretation are separated into `executeTask`, `SubSession`, and `readTaskResult`. Manual verification on Pi
+1.5.0 exercised fresh context, native and additional tools, MCP through tool search and codemode, sequential waiting, failure, cancellation, cleanup, and native session
+persistence. See [manual evidence](docs/subagent-integration.md#manual-verification). The three workflow roles still use `pi-subagents`. Final `owner` acceptance and
+completion are not recorded. The caller's message is named `prompt`, execution is inlined in `executeTask`, and cancellation comments explain Node.js `AbortError`. At the
+owner's request, cancellation is forwarded only by the signal listener, without checks before or after the prompt or a retry at `agent_start`. An already cancelled signal
+does not prevent submission, and an aborted signal alone does not turn a normal Pi result into an interruption.
+
+#### Objective
+
+Implement and verify one internal execution operation using `createAgentSession()`, following [ADR-010](ADR.md#adr-010-use-the-pi-sdk-for-sequential-agent-delegation).
+The operation is independent of the `builder`, `verifier`, and `simplifier` roles. Callers supply the task, role instructions, model settings, working directory, and
+additional tools needed for that execution.
+
+#### Scope and dependencies
+
+Requires [MAESTRO-FREE-1](#maestro-free-1-require-pi-150) and [MAESTRO-FREE-2](#maestro-free-2-remove-maestro-run-timeouts). This item implements the execution mechanism
+without switching existing workflow tools away from `pi-subagents`. FREE-3, FREE-4, and FREE-5 connect the three roles to it together after it is verified.
+
+The executor manages child sessions, not the workflow. It does not select phases, interpret role outcomes, or validate `handoffs`. Those responsibilities remain with the
+callers and existing workflow operations. Communication remains task-and-`handoff`, without shared in-memory workflow state or a live supervisor dialogue. This is not a
+new public tool or a general-purpose orchestration framework. Live progress presentation remains in [MAESTRO-FREE-6](#maestro-free-6-show-sdk-agent-activity-through-pi).
+
+#### Completed when
+
+1. The operation executes a supplied task in a fresh SDK conversation with the supplied model and thinking level, role guidance, global and project instructions, skills,
+   working tools, and caller-supplied additional tools. It does not depend on any of the three workflow roles.
+2. Enabled global and project extensions and native Pi tool support load as defined in ADR-010, excluding the main `Maestro` extension. The main session retains its
+   `Maestro` mode while the child executes. No compatibility adapters, integration health gates, or delegation-prevention tool filters are added.
+3. Execution waits for the child to finish, fail, or be interrupted before another child starts. The executor imposes no automatic deadline and does not start a new
+   session to retry or repair failed work.
+4. Manual cancellation reaches `session.abort()` and waits for interruption. Sessions, subscriptions, and owned resources are released on every exit, without rollback,
+   workflow changes, or synthetic `handoffs`. Execution errors propagate to the caller.
+5. Native Pi sessions are persisted in `subagents/` beneath Pi's project session directory, resolved through Pi's API. The saved path is available to the caller on
+   completion or failure when a file exists. Every execution starts fresh; no automatic resumption is introduced.
+6. Successful execution, execution failure, cancellation, context and tool loading, and session persistence are verified independently of the workflow migration. The
+   existing three role tools still use `pi-subagents` at the end of this item.
+
+### MAESTRO-FREE-3: Run the builder through the Pi SDK
+
+#### Objective
+
+Connect `builder` delegation to the internal SDK executor delivered by [MAESTRO-FREE-PRE-3](#maestro-free-pre-3-implement-internal-sdk-delegation), following
+[ADR-010](ADR.md#adr-010-use-the-pi-sdk-for-sequential-agent-delegation). Preserve the existing role instructions, `handoffs`, and workflow behavior.
+
+#### Scope and dependencies
+
+Requires [MAESTRO-FREE-PRE-3](#maestro-free-pre-3-implement-internal-sdk-delegation). Implement FREE-3, [FREE-4](#maestro-free-4-run-the-verifier-through-the-pi-sdk), and
+[FREE-5](#maestro-free-5-run-the-simplifier-through-the-pi-sdk) as one migration of all three roles. Their identifiers retain the role-specific verification scope, not
+separate execution mechanisms or releases. Do not introduce temporary mixed-engine routing or an engine selector. Verify each role and the supported optional-phase
+combinations before completing the migration. Human documentation must describe the resulting SDK execution. Live progress remains in
+[MAESTRO-FREE-6](#maestro-free-6-show-sdk-agent-activity-through-pi); existing workflow-phase status remains available in the meantime.
+
+#### Completed when
+
+1. An approved `spec` can be implemented by an SDK `builder` with fresh conversation history, the configured model and thinking level, role guidance, global and project
+   instructions, skills, working tools, and existing `handoff` tools.
+2. It reuses the established executor's context and tool loading without another execution mechanism. Role instructions continue to forbid further delegation.
+3. `done` and `escalation` outcomes preserve existing saved `handoffs`, validation, phase transitions, and subsequent workflow routes. A later `builder` `pass` starts
+   fresh and reads saved decisions rather than restoring the previous conversation.
+4. Errors stop the workflow without rollback or repair. Manual cancellation reaches `session.abort()`, and child sessions and subscriptions are cleaned up on every exit.
+5. Native Pi session files are saved beneath the project's Pi session directory in `subagents/`. The `owner` receives the saved path on completion or failure when a file
+   exists; it can be inspected or exported with Pi, without automatic resumption.
+6. Existing trust, configuration, and model checks remain applicable. Activation and execution no longer require `pi-subagents` ping or launch-contract checks for any
+   role. A `builder`-only workflow uses the SDK without requiring a `pi-subagents` availability reply.
+7. Each `run` waits for its child to finish or be interrupted before another starts. Existing optional-phase behavior remains intact.
+
+### MAESTRO-FREE-4: Run the verifier through the Pi SDK
+
+#### Objective
+
+Connect the `verifier` to the SDK executor delivered by [MAESTRO-FREE-PRE-3](#maestro-free-pre-3-implement-internal-sdk-delegation), following
+[ADR-010](ADR.md#adr-010-use-the-pi-sdk-for-sequential-agent-delegation). Implement this role's switch together with FREE-3 and FREE-5 under the
+[shared migration scope](#maestro-free-3-run-the-builder-through-the-pi-sdk). Do not redesign verification or its reports.
+
+#### Completed when
+
+1. The SDK `verifier` independently checks the approved `spec` and saves existing numbered `handoffs`, preserving criterion validation, `finding` decisions, and phase
+   transitions.
+2. It reuses the established fresh-session context, tools, persistence, cancellation, cleanup, and error policy without a second execution mechanism.
+3. Activation and execution no longer use `pi-subagents` for the `verifier`.
+4. Workflows with verification enabled or disabled retain their existing routes, with all enabled roles using the common SDK executor.
+
+### MAESTRO-FREE-5: Run the simplifier through the Pi SDK
+
+#### Objective
+
+Connect the `simplifier` to the SDK executor delivered by [MAESTRO-FREE-PRE-3](#maestro-free-pre-3-implement-internal-sdk-delegation), following
+[ADR-010](ADR.md#adr-010-use-the-pi-sdk-for-sequential-agent-delegation). Implement this role's switch together with FREE-3 and FREE-4 under the
+[shared migration scope](#maestro-free-3-run-the-builder-through-the-pi-sdk). Keep its existing purpose and Git-only scope.
+
+#### Completed when
+
+1. The SDK `simplifier` preserves the current Git readiness decision, skip behavior, and entry routes. No Git readiness check moves into activation or an earlier phase.
+2. Successful execution saves the existing unnumbered `S.json` `handoff` and reaches `candidate-ready`; optional-phase behavior remains unchanged.
+3. It reuses the established context, tools, persistence, cancellation, cleanup, and error policy.
+4. Activation and execution no longer use `pi-subagents` for the `simplifier`. All roles migrate together, so no workflow path requires its ping, launch preflight, or
+   fixed delegation deadline.
+
+### MAESTRO-FREE-6: Show SDK agent activity through Pi
+
+#### Objective
+
+Show activity for SDK-based agent `runs` through Pi's standard `onUpdate` presentation, as decided in
+[ADR-010](ADR.md#adr-010-use-the-pi-sdk-for-sequential-agent-delegation). Requires the shared migration covered by
+[MAESTRO-FREE-3](#maestro-free-3-run-the-builder-through-the-pi-sdk), FREE-4, and FREE-5, and applies to all three roles through the common executor.
+
+#### Completed when
+
+1. Progress reports the role, elapsed time, current tool, and recent normal assistant text, including activity while the agent produces no text.
+2. Pi controls layout, truncation, and expansion. There is no custom renderer, fixed line count, transcript inspector, or artificial progress prompting.
+3. Intermediate text stays out of the main model's context. Final workflow results, saved session contents, and cancellation behavior remain unchanged.
+4. Progress subscriptions are released when the child finishes, fails, or is interrupted.
+
+### MAESTRO-FREE-7: Remove the pi-subagents dependency
+
+#### Objective
+
+Finish [ADR-010](ADR.md#adr-010-use-the-pi-sdk-for-sequential-agent-delegation) by removing the package dependency, bundling, and remaining integration metadata after
+[MAESTRO-FREE-3](#maestro-free-3-run-the-builder-through-the-pi-sdk), [MAESTRO-FREE-4](#maestro-free-4-run-the-verifier-through-the-pi-sdk), and
+[MAESTRO-FREE-5](#maestro-free-5-run-the-simplifier-through-the-pi-sdk). This is dependency removal, not another execution-engine switch.
+
+#### Completed when
+
+1. `Maestro` neither imports nor bundles `pi-subagents`, and package metadata, role frontmatter, tests, installation instructions, and current human documentation no
+   longer require it. Historical records remain historical evidence.
+2. A clean installation can activate and complete workflows without `pi-subagents` installed or enabled, including the supported optional-phase combinations.
+3. Existing workflow and `handoff` formats remain unchanged. No compatibility framework, engine-selection flags, or migration of interrupted workflows is added.
+
 ## Implemented, acceptance not confirmed
 
+### MAESTRO-26: Exit Maestro mode automatically at workflow completion
+
+Implemented in `0.13.0`. `Maestro` automatically turns off after successfully delivering the final summary of a completed workflow, including when Git is unavailable and
+simplification is skipped. Live tools, status, instructions, and active `spec` selection are cleared; saved workflow files and other extensions remain unchanged.
+Intermediate phases and interrupted workflows do not trigger automatic exit.
+
+Linear marks this item Done, but its description still says final `owner` acceptance is pending. Acceptance is not inferred from that status or the release.
+
+#### Evidence
+
+[Changelog](CHANGELOG.md#0130), [merged PR #43](https://github.com/emilioSp/pi-maestro/pull/43),
+[specification](.specs/20261030-145712-automatically-exit-maestro-mode-at-workflow-completion/spec.md), and
+[original issue](https://linear.app/emilio-spatola/issue/MAESTRO-26/feat-exit-maestro-mode-automatically-at-workflow-completion).
+
+## Completed
+
+Completed entries include historical records imported from Linear and work explicitly accepted by the `owner`. Historical verification evidence alone does not establish
+final `owner` acceptance.
+
+### MAESTRO-FREE-1: Require Pi 1.5.0
+
+#### Objective
+
+Adopt Pi 1.5.0 as the minimum supported host and verification baseline for [ADR-010](ADR.md#adr-010-use-the-pi-sdk-for-sequential-agent-delegation), without changing the
+delegation engine or adding compatibility fallbacks.
+
+#### Completed when
+
+1. Declared requirements and the development verification environment use the selected Pi baseline consistently.
+2. The existing extension and `pi-subagents` workflow continue to work on Pi 1.5.0.
+
+#### Implementation and evidence
+
+The `owner` confirmed completion. `README.md` declares Pi 1.5.0 as the minimum host. Development dependencies for the four Pi packages are pinned to 1.5.0, so type checks
+and tests run against that baseline. Schema enums use TypeBox `Type.Enum` with an explicit string type. `npm run check` passes on 1.5.0, including the extension and
+`pi-subagents` integration tests.
+
+### MAESTRO-FREE-2: Remove Maestro run timeouts
+
+#### Recorded outcome
+
+The `owner` confirmed completion of the timeout configuration removal implemented in `0.16.0`. The three `timeoutMinutes` settings, their defaults, and their
+configuration documentation were removed. Existing TypeBox validation rejects configuration retaining those fields, without migration or compatibility handling.
+
+The current `pi-subagents` integration still receives a fixed deadline of 9,999 minutes. This is not unlimited execution. Removal of that remaining deadline belongs to
+the SDK delegation replacement under [ADR-010](ADR.md#adr-010-use-the-pi-sdk-for-sequential-agent-delegation), not a separate prerequisite for it.
+
+#### Evidence
+
+[Changelog](CHANGELOG.md#0160), [PR #46](https://github.com/emilioSp/pi-maestro/pull/46), [configuration schema](src/config/schema.ts), and
+[current delegation deadline](src/tools/utils/pi-subagent-delegation.ts).
+
 ### MAESTRO-27: Make all implementation phases optional
 
 #### Objective
@@ -114,10 +307,10 @@ remain required.
 
 #### Implementation and evidence
 
-Implemented under the [specification](.specs/20261103-161424-maestro-27-make-implementation-phases-optional/spec.md), awaiting `owner` acceptance. Each agent's `required`
-boolean in `.pi/maestro.json` defaults to `true`. Flags are set before activation and remain unchanged during the workflow. Disabling `builder` skips all three agents;
-otherwise `verifier` and `simplifier` are independently optional. `Spec` preparation and approval remain required. The activation notice lists only enabled agents and no
-agents when `builder` is disabled.
+Implemented under the [specification](.specs/20261103-161424-maestro-27-make-implementation-phases-optional/spec.md). The `owner` confirmed completion. Each agent's
+`required` boolean in `.pi/maestro.json` defaults to `true`. Flags are set before activation and remain unchanged during the workflow. Disabling `builder` skips all three
+agents; otherwise `verifier` and `simplifier` are independently optional. `Spec` preparation and approval remain required. The activation notice lists only enabled agents
+and no agents when `builder` is disabled.
 
 The [README](README.md#the-idea) presents the two uses of `Maestro`: writing and approving a `spec` only, or also implementing it through optional agent phases.
 
@@ -127,24 +320,6 @@ The [README](README.md#the-idea) presents the two uses of `Maestro`: writing and
 choice. This item originally made only the post-`builder` phases optional. The `owner` expanded the scope to include the `builder`, so `Maestro` can also be used solely
 for writing and approving a `spec`.
 
-### MAESTRO-26: Exit Maestro mode automatically at workflow completion
-
-Implemented in `0.13.0`. `Maestro` automatically turns off after successfully delivering the final summary of a completed workflow, including when Git is unavailable and
-simplification is skipped. Live tools, status, instructions, and active `spec` selection are cleared; saved workflow files and other extensions remain unchanged.
-Intermediate phases and interrupted workflows do not trigger automatic exit.
-
-Linear marks this item Done, but its description still says final `owner` acceptance is pending. Acceptance is not inferred from that status or the release.
-
-#### Evidence
-
-[Changelog](CHANGELOG.md#0130), [merged PR #43](https://github.com/emilioSp/pi-maestro/pull/43),
-[specification](.specs/20261030-145712-automatically-exit-maestro-mode-at-workflow-completion/spec.md), and
-[original issue](https://linear.app/emilio-spatola/issue/MAESTRO-26/feat-exit-maestro-mode-automatically-at-workflow-completion).
-
-## Completed
-
-These entries were recorded as Done in Linear. Their historical verification evidence does not independently establish final `owner` acceptance.
-
 ### MAESTRO-7: Route builder failures through owner escalations
 
 Route reportable `builder` problems through `owner` `escalations` instead of a terminal failure phase.

package/agents/builder.md

@@ -51,17 +51,17 @@ discoveries without an owner decision in handoff `notes`. Do not turn notes into
 
 ## Prove every acceptance criterion
 
-Run every probe, including on repair passes. Previous evidence does not replace this pass's results. The spec defines probe scenarios, expected results, and concrete
-examples. Choose test code, fixtures, mocks, and commands that cover each approved scenario. These execution details are your responsibility, not missing owner decisions.
-Follow any explicit execution constraints in the approved spec. Run each executable probe against the implementation and compare the observed result with the expected
-result. Do not change approved probe scenarios, expected results, examples, or design decisions to obtain passing results. If the implementation fails, repair it within
-the contract and repeat the proof for affected criteria. If the contract needs clarification or revision, escalate instead of inventing a replacement probe. For visual
+Run every GIVEN, WHEN, and THEN scenario, including on repair passes. Previous evidence does not replace this pass's results. The spec defines those scenarios and
+concrete examples. Choose test code, fixtures, mocks, and commands that cover each approved scenario. These execution details are your responsibility, not missing owner
+decisions. Follow any explicit execution constraints in the approved spec. Run each scenario against the implementation and compare the observed result with the THEN
+outcome. Do not change approved GIVEN, WHEN, and THEN scenarios, examples, or design decisions to obtain passing results. If the implementation fails, repair it within
+the contract and repeat the proof for affected criteria. If the contract needs clarification or revision, escalate instead of inventing a replacement scenario. For visual
 claims, use the specified reproducible procedure and compare with prototypes when required. Run applicable repository checks. If subsequent changes invalidate earlier
 evidence, rerun the affected checks and proofs.
 
-For each criterion, record its exact `id`, actual command or procedure in `probe`, and `probeStatus`. Use `probeStatus: passed` when the observed result matches the
-expected result. Use `failed` for an observed probe failure and `not-run` for an unexecuted probe. Include every spec criterion once. Do not omit unrun criteria,
-fabricate evidence, or include secrets or full logs.
+For each criterion, record its exact `id`, actual command or procedure in `probe`, and `probeStatus`. Use `probeStatus: passed` when the observed result matches the THEN
+outcome. Use `failed` for an observed failure and `not-run` for a check that did not run. Include every spec criterion once. Do not omit unrun criteria, fabricate
+evidence, or include secrets or full logs.
 
 ## Record exactly one outcome
 

package/agents/verifier.md

@@ -40,28 +40,28 @@ candidate to make verification succeed.
 ## Regenerate every proof
 
 Verify every acceptance criterion from the candidate, including criteria checked in earlier runs. Do not trust the builder's results or silently change the approved
-behavior, probe scenarios, expected results, or examples. Read executable probes from the candidate and builder handoff. Independently check that they cover the approved
+behavior, GIVEN, WHEN, and THEN scenarios, or examples. Read executable checks from the candidate and builder handoff. Independently check that they cover the approved
 scenarios. The spec need not prescribe test code, fixtures, mocks, commands, or exact code edits. Missing execution details alone are not a contract gap. Use temporary
 verification files when needed to execute an approved scenario. Do not repair existing tests or weaken their coverage. If the builder's checks miss required behavior,
-record a finding even if your own probe passes. Follow any explicit execution constraints in the approved spec. Run each executable probe against the candidate and
-compare the observed result with the expected result. If a probe fails, record a finding. Do not repair the candidate. If a probe is unsafe, undefined, or impossible to
-execute, record the limitation as a finding. Continue with other criteria that can be checked safely. Do not stop the entire review at the first finding. Use temporary
-files only as needed for the specified probes. Remove them before handoff. For visual claims, produce reproducible evidence through the spec's procedure, including
-prototype comparisons when required.
+record a finding even if your own check passes. Follow any explicit execution constraints in the approved spec. Run each scenario against the candidate and compare the
+observed result with the THEN outcome. If the observed result does not match, record a finding. Do not repair the candidate. If a scenario is unsafe, undefined, or
+impossible to execute, record the limitation as a finding. Continue with other criteria that can be checked safely. Do not stop the entire review at the first finding.
+Use temporary files only as needed for the specified scenarios. Remove them before handoff. For visual claims, produce reproducible evidence through the spec's procedure,
+including prototype comparisons when required.
 
 Follow applicable repository commands and technical rules. Do not invent required commands. Inspect check scripts before execution. Do not use automatic fixes to repair
 the candidate. If a required check changes files, record that effect and restore those changes before further verification. A result obtained only after an automatic fix
 does not prove that the candidate passes.
 
-For each criterion, record its exact `id`, actual command or procedure in `probe`, and `probeStatus`. Use `probeStatus: passed` when the observed result matches the
-expected result. Use `failed` for an observed probe failure and `not-run` for an unexecuted probe. Include every spec criterion once. Never omit unrun criteria or
-fabricate evidence.
+For each criterion, record its exact `id`, actual command or procedure in `probe`, and `probeStatus`. Use `probeStatus: passed` when the observed result matches the THEN
+outcome. Use `failed` for an observed failure and `not-run` for a check that did not run. Include every spec criterion once. Never omit unrun criteria or fabricate
+evidence.
 
 ## Record findings, not decisions
 
-Record technical issues supported by fresh evidence. Do not add requirements, style preferences, or unrelated improvements. Give every criterion with a probe other than
-`passed` at least one related finding. Report required repository check failures as findings, even when every acceptance criterion passes. Do not copy an earlier
-rejection into a new finding. Only the owner can reject current findings through Maestro.
+Record technical issues supported by fresh evidence. Do not add requirements, style preferences, or unrelated improvements. Give every criterion with a `probeStatus`
+other than `passed` at least one related finding. Report required repository check failures as findings, even when every acceptance criterion passes. Do not copy an
+earlier rejection into a new finding. Only the owner can reject current findings through Maestro.
 
 For each finding, follow the tool schema: