@emiliosp/pi-maestro 0.14.0 → 0.16.0

package/ADR.md

@@ -247,3 +247,158 @@ failures during delegation still use the existing `run` failure path. Workflow r
 
 [Configuration](docs/configuration.md#model-access), [activation checks](src/maestro/checks/assertEnvironment.ts), and
 [delegation](src/tools/utils/pi-subagent-delegation.ts).
+
+## ADR-009: Select optional phases in the transition table
+
+### Status
+
+Accepted. Implemented under MAESTRO-27.
+
+### Context
+
+The `owner` selected configuration flags to support workflows with only an approved `spec` and independently optional later agents without a separate phase-selection
+interface.
+
+### Decision
+
+Each agent has a `required` boolean that defaults to `true`. Disabling `builder` skips all agents. Otherwise `verifier` and `simplifier` can be disabled independently.
+Flags are set before activation and stay unchanged during the workflow. Keep existing configuration reads, without caching or runtime controls.
+
+Keep destination selection in `src/workflow/transitions.ts`. A transition destination is either a fixed phase or a pure function of resolved configuration. Callers pass
+configuration to `transitionWorkflow` and save its returned state. No new workflow states, events, or persisted selection fields are needed.
+
+### Consequences
+
+Approval can finish at `candidate-ready` without agent execution. Agent and model availability checks apply only to selected phases; activation with only an approved
+`spec` needs no `pi-subagents` ping. Final summaries identify skipped work, without claiming implementation or independent verification occurred.
+
+### 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,25 @@
 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.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;
+   otherwise `verifier` and `simplifier` can be disabled independently. See [PR #45](https://github.com/emilioSp/pi-maestro/pull/45).
+2. Limited activation checks and displayed agent details to enabled phases. With `builder` disabled, activation requires no agents, models, or `pi-subagents` ping.
+3. Updated workflow transitions, tool messages, agent guidance, and documentation for optional phases. Final-summary guidance identifies skipped work without claiming
+   implementation, independent verification, or simplification occurred.
+
 ## 0.14.0
 
 1. Removed Maestro's model format regex while retaining activation checks against Pi's available model registry. Complete identifiers, including

package/README.md

@@ -2,23 +2,34 @@
 
 [![Coverage](https://img.shields.io/codecov/c/github/emiliosp/pi-maestro?logo=codecov)](https://codecov.io/gh/emiliosp/pi-maestro)
 
-Pi extension for a spec-driven multiagent development workflow.
+Pi extension for writing a `spec` and optionally implementing it through a spec-driven multiagent workflow.
 
 ![Maestro workflow](docs/maestro.png)
 
 ## The idea
 
-- A `specification` (`spec`) describes one reversible change.
-- The `builder` implements it.
-- An independent `verifier` checks every `acceptance criterion`.
-- A `simplifier` then refactors accepted code without changing behavior.
-- The `owner` performs the final review.
+`Maestro` has two goals:
+
+1. Help the `owner` write and approve a `specification` (`spec`) for one reversible change.
+2. Implement the approved `spec` through a multiagent workflow.
+
+The `owner` can use `Maestro` only to write and approve a `spec`, leaving implementation to another workflow, or to write the `spec` and implement it within `Maestro`.
+`Spec` preparation and approval are required. The entire implementation stage is optional, and each of its phases is optional too:
+
+1. The `builder` implements the approved `spec`.
+2. The independent `verifier` checks every `acceptance criterion`.
+3. The `simplifier` refactors accepted code without changing behavior.
+
+Disabling the `builder` skips the entire implementation stage. With the `builder` enabled, the `verifier` and `simplifier` can be disabled independently. All three are
+enabled by default. See [Phase selection](docs/configuration.md#phase-selection).
+
+The `owner` performs the final review.
 
 Five principles hold the workflow together:
 
 1. The approved `spec` defines the required work for the `builder` and `verifier`.
 2. No agent approves its own work.
-3. Every `acceptance criterion` is checked independently.
+3. When enabled, the `verifier` checks every `acceptance criterion` independently.
 4. The `owner` decides requirements, scope, and unresolved questions.
 5. Each agent has one and only one role. Specific and with clear instruction.
 
@@ -72,9 +83,9 @@ 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.
-4. `pi-subagents` installed and enabled in Pi.
-5. Access to the configured `builder`, `verifier`, and `simplifier` models.
+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.
 
 ## Installation
@@ -101,20 +112,20 @@ Activate `Maestro`:
 /maestro
 ```
 
-During activation, `Maestro` checks project trust, configuration, models, and agent availability. Model availability comes from Pi's model registry. If a check fails,
-`Maestro` stays disabled and reports the problem.
+During activation, `Maestro` checks project trust, configuration, and enabled agent and model availability. With `builder` disabled, only project trust and configuration
+are checked. Model availability comes from Pi's model registry. If a check fails, `Maestro` stays disabled and reports the problem.
 
 The `owner` follows this workflow:
 
 1. Describes one change to `Maestro`.
 2. Reviews the `spec`, including its `acceptance criteria` and concrete examples.
-3. Replies `GREEN FLAG` when `Maestro` asks for approval. `Maestro` records the approval and starts the `builder`.
+3. Replies `GREEN FLAG` when `Maestro` asks for approval. `Maestro` records the approval and starts the selected phases.
 4. Reviews every current `builder` `escalation` and gives `Maestro` an answer and reason for each question.
 5. Reviews `verifier` `findings` and chooses an action for every `finding`.
 6. Reads Maestro's summary at `candidate-ready` and performs the final review.
 
-`Maestro` starts the `verifier` after a successful `builder` `run`. All three agents run in the foreground: Pi waits for each `run` to finish and `Maestro` shows the
-current phase in Pi's status, while `pi-subagents` FleetView and `/subagents-fleet` show agent activity and transcripts.
+`Maestro` starts the `verifier`, when enabled, after a successful `builder` `run`. Selected agents run in the foreground: Pi waits for each `run` to finish and `Maestro`
+shows the current phase in Pi's status, while `pi-subagents` FleetView and `/subagents-fleet` show agent activity and transcripts.
 
 The `owner` must not edit product files while the workflow runs. `Maestro` can perform temporary experiments with `owner` agreement during `spec` preparation and
 permitted revisions. See [Workflow](docs/workflow.md#spec-approval).
@@ -126,8 +137,9 @@ changing phase.
 If any decision requires a `spec` change, the workflow returns to `drafting-spec` before the `owner` and `Maestro` revise the same `spec`. The `owner` reviews the revised
 `spec` and replies `GREEN FLAG` again. `Maestro` records renewed approval separately before another `builder` `run`.
 
-After successful verification or rejection of all `findings`, `Maestro` starts the `simplifier`. Only this step requires Git. If Git readiness cannot be confirmed,
-`Maestro` warns and skips simplification. The `simplifier` selects all uncommitted code changes, including pre-existing staged, unstaged, and untracked files.
+When enabled, `Maestro` starts the `simplifier` after successful verification, rejection of all `findings`, or `builder` completion with verification disabled. Only this
+step requires Git. If Git readiness cannot be confirmed, `Maestro` warns and skips simplification. The `simplifier` selects all uncommitted code changes, including
+pre-existing staged, unstaged, and untracked files.
 
 The workflow ends at `candidate-ready`. Rejected `findings` retain their reasons and accepted failures can remain. Maestro's summary separates independent verification
 from the later simplifier's report. After the final summary finishes successfully, `Maestro` automatically turns off. The `owner` controls later review, commits, pull
@@ -139,7 +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, or timeouts. See [Configuration](docs/configuration.md).
+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
 
@@ -147,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,37 @@ 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)       | Implemented, acceptance not confirmed |
-| MAESTRO-27 | [Make verifier and simplifier phases optional](#maestro-27-make-verifier-and-simplifier-phases-optional)                           | Backlog                               |
+| 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)                                                         | Backlog   |
+| 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,32 +97,107 @@ 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-27: Make verifier and simplifier phases optional
+### MAESTRO-FREE-2: Remove Maestro run timeouts
 
 #### Objective
 
-Make the `builder` the only required agent phase. Let the `owner` independently enable or disable the `verifier` and `simplifier` phases.
+Remove Maestro's per-agent deadline and the three `timeoutMinutes` settings, as decided in [ADR-010](ADR.md#adr-010-use-the-pi-sdk-for-sequential-agent-delegation).
+Remove schema fields, defaults, delegation timeout inputs, and related configuration documentation together.
 
-This request concerns agent execution phases, not removal of `spec` preparation or approval.
+#### Completed when
+
+1. `Maestro` no longer supplies a per-agent deadline. Elapsed-time display and timeouts internal to Pi, tools, or the remaining `pi-subagents` integration are unchanged.
+2. Configuration without `timeoutMinutes` works; configuration retaining it fails existing TypeBox validation with no migration or compatibility handling.
+3. Other configuration behavior and the existing workflow remain unchanged.
+
+### MAESTRO-FREE-3: Run the builder through the Pi SDK
+
+#### Objective
+
+Replace `builder` delegation with `createAgentSession()` and deliver a complete, usable SDK `builder` `run`, following
+[ADR-010](ADR.md#adr-010-use-the-pi-sdk-for-sequential-agent-delegation). This item includes the internal execution operation used by later role migrations; do not
+release an incomplete `builder` pending separate context, cancellation, or persistence work.
+
+#### Scope and dependencies
+
+Requires [MAESTRO-FREE-1](#maestro-free-1-require-pi-150) and [MAESTRO-FREE-2](#maestro-free-2-remove-maestro-run-timeouts). Keep the `verifier` and `simplifier` on
+`pi-subagents`. The temporary routing is fixed in code, not a configurable engine selector or a general-purpose delegation framework. Human documentation must describe
+the actual mixed-engine state. Live SDK progress is covered separately by [MAESTRO-FREE-6](#maestro-free-6-show-sdk-agent-activity-through-pi); existing workflow-phase
+status remains available in the meantime.
 
 #### Completed when
 
-1. The `builder` remains mandatory.
-2. The `owner` can select any of these combinations: `builder` only; `builder` and `verifier`; `builder` and `simplifier`; or all three.
-3. Disabled phases are not delegated and do not block workflow completion.
-4. The workflow reaches `candidate-ready` after the selected phases complete and any required `owner` decisions are resolved.
-5. The final summary clearly identifies skipped phases and does not describe skipped verification as passed.
+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. Enabled global and project extensions load through Pi, excluding the main `Maestro` extension. Instructions forbid further delegation; there are no additional tool
+   filters, integration health gates, compatibility adapters, or automatic retries.
+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. `pi-subagents` ping and launch-contract checks apply only to enabled roles still using that engine;
+   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
 
-#### Decisions to define in the spec
+#### Objective
 
-1. Where and when phase selection is configured.
-2. Default selections.
-3. Whether selections can change after a workflow starts.
+Move the `verifier` to the SDK execution operation delivered by [MAESTRO-FREE-3](#maestro-free-3-run-the-builder-through-the-pi-sdk), following
+[ADR-010](ADR.md#adr-010-use-the-pi-sdk-for-sequential-agent-delegation). Do not redesign verification or its reports.
 
-#### Context
+#### Completed when
 
-[MAESTRO-24](#maestro-24-add-a-simplifier-with-one-clear-purpose-per-agent) introduced the `simplifier`. Its existing Git-unavailable skip is not an explicit `owner`
-choice. This issue adds independent optionality for both post-`builder` agent phases.
+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 no longer asks `pi-subagents` to check or execute the `verifier`. Its remaining checks apply only to enabled roles still on that engine.
+4. Workflows with verification enabled or disabled retain their existing routes. If the `simplifier` is not yet migrated, it continues to use `pi-subagents` unchanged.
+
+### MAESTRO-FREE-5: Run the simplifier through the Pi SDK
+
+#### Objective
+
+Move the `simplifier` to the SDK execution operation delivered by [MAESTRO-FREE-3](#maestro-free-3-run-the-builder-through-the-pi-sdk), following
+[ADR-010](ADR.md#adr-010-use-the-pi-sdk-for-sequential-agent-delegation). 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 no longer asks `pi-subagents` to check or execute the `simplifier`. Once all roles have migrated, no workflow path requires its ping or launch preflight.
+
+### 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 [MAESTRO-FREE-3](#maestro-free-3-run-the-builder-through-the-pi-sdk) and applies to
+each role as it is migrated.
+
+#### 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. Roles still on `pi-subagents` retain their existing presentation.
+
+### 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
 
@@ -135,7 +217,61 @@ Linear marks this item Done, but its description still says final `owner` accept
 
 ## Completed
 
-These entries were recorded as Done in Linear. Their historical verification evidence does not independently establish final `owner` acceptance.
+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-27: Make all implementation phases optional
+
+#### Objective
+
+Make the entire implementation stage optional, including the `builder`, `verifier`, and `simplifier` phases. Let the `owner` use `Maestro` only to prepare and approve a
+`spec`, leaving implementation to another workflow.
+
+When implementation runs in `Maestro`, the `owner` can still independently enable or disable the `verifier` and `simplifier` phases. `Spec` preparation and approval
+remain required.
+
+#### Completed when
+
+1. The `owner` can complete a workflow with only an approved `spec`, without running the `builder`, `verifier`, or `simplifier`.
+2. Implementation can be performed through another workflow using the approved `spec`, without requiring further execution in `Maestro`.
+3. The existing requested combinations remain available: `builder` only; `builder` and `verifier`; `builder` and `simplifier`; or all three.
+4. Disabled phases are not delegated and do not block workflow completion.
+5. The workflow reaches `candidate-ready` after `spec` approval when no agent phases are selected, or after the selected phases complete and any required `owner`
+   decisions are resolved.
+6. The final summary clearly identifies skipped phases and does not claim that skipped implementation or verification has been completed.
+
+#### Implementation and evidence
+
+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.
+
+#### Context
+
+[MAESTRO-24](#maestro-24-add-a-simplifier-with-one-clear-purpose-per-agent) introduced the `simplifier`. Its existing Git-unavailable skip is not an explicit `owner`
+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-7: Route builder failures through owner escalations
 

package/agents/simplifier.md

@@ -21,7 +21,8 @@ delegate, approve work, implement new behavior, or raise findings or escalations
    files. The present documents form one approved contract: motivation and scope in the proposal, behavior and all acceptance criteria, including standalone regressions,
    in the spec, technical decisions in the optional design.
 3. Read relevant builder and verifier handoffs and embedded owner decisions. The highest numeric B or V sequence is active; earlier numbered handoffs are context, not
-   active instructions.
+   active instructions. When verification is disabled, no verifier handoff is required; use the builder report and its check baseline, without claiming independent
+   verification.
 4. Confirm that the saved workflow identifies this spec and is in `simplifier-running`. If inputs or phase do not match, report the mismatch to Maestro and stop. Do not
    repair protocol state.
 

package/agents/verifier.md

@@ -89,4 +89,5 @@ facts. If the tool already wrote an artifact or changed phase before an error, d
 force completion. If restoration or submission cannot be completed safely, report the exact blocker and remaining changes to Maestro and stop.
 
 After a successful handoff, return a concise summary and the saved artifact path to Maestro and stop. Do not run more checks. The handoff produces `finding-decisions`
-when findings exist and `simplifier-running` when none exist. Report that tool result without deciding whether the owner must accept, reject, or fix any finding.
+when findings exist. With no findings, it produces `simplifier-running` when simplification is enabled, otherwise `candidate-ready`. Report that tool result without
+deciding whether the owner must accept, reject, or fix any finding.