@emiliosp/pi-maestro 0.13.1 → 0.15.0

package/ADR.md

@@ -219,3 +219,59 @@ Conflicting imported status and acceptance evidence remain explicit rather than
 ### Evidence
 
 [Roadmap](ROADMAP.md) and [repository instructions](AGENTS.md).
+
+## ADR-008: Use Pi's registry for model availability
+
+### Status
+
+Accepted. Implemented.
+
+### Context
+
+Maestro's model format regex rejected OpenRouter IDs containing additional slashes. The `owner` selected Pi as the source of truth for models and explicitly retained the
+activation availability check because it uses Pi's registry.
+
+### Decision
+
+Treat configured models as strings without a separate format regex. During activation, match each complete `provider/model` identifier against
+`context.modelRegistry.getAvailable()`, preserving slashes inside model IDs. Pass the configured identifier unchanged through `pi-subagents`.
+
+Keep Maestro's configuration structure, version, path, thinking-level, and timeout validation.
+
+### Consequences
+
+A model absent from Pi's available registry prevents activation. `Maestro` maintains no separate model catalog or authentication check. Provider or authentication
+failures during delegation still use the existing `run` failure path. Workflow recovery and phase transitions remain unchanged.
+
+### Evidence
+
+[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).

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 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.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
+   `openrouter/~openai/gpt-mini-latest`, are matched without truncation and passed unchanged to `pi-subagents`. Maestro's other configuration validation remains
+   unchanged.
+
 ## 0.13.1
 
 1. Restored `ROADMAP.md` as the planning source of truth from the current Linear issues, retaining their identifiers and recorded evidence. Updated repository guidance,

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.
 
@@ -73,8 +84,8 @@ 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.
+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,19 +112,20 @@ Activate `Maestro`:
 /maestro
 ```
 
-During activation, `Maestro` checks project trust, configuration, models, and agent availability. 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).
@@ -125,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
@@ -138,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, 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).
 
 ## Documentation
 

package/ROADMAP.md

@@ -3,12 +3,38 @@
 This file is the source of truth for planned outcomes and recorded completion. Roadmap entries are not permission to implement them. The `owner` selects work and approves
 its `specification` before implementation starts. Detailed requirements, technical decisions, and `acceptance criteria` belong in that `specification`.
 
-Items were restored from the Linear `MAESTRO` team. Existing identifiers remain stable; Linear is historical reference only and does not need to be read or updated.
 Backlog items have no agreed order or date. The `owner` approves priority and scope changes.
 
 Completed entries preserve recorded outcomes and evidence, which may describe behavior later changed. Completion requires `owner` acceptance, not only passing checks or
 reaching `candidate-ready`. Linear onboarding and test issues are not project roadmap items and are omitted.
 
+## 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 |
+
 ## Backlog
 
 ### MAESTRO-6: Display specs in a browser
@@ -64,34 +90,42 @@ 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
+## Implemented, acceptance not confirmed
+
+### MAESTRO-27: Make all implementation phases optional
 
 #### Objective
 
-Make the `builder` the only required agent phase. Let the `owner` independently enable or disable the `verifier` and `simplifier` phases.
+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.
 
-This request concerns agent execution phases, not removal of `spec` preparation or approval.
+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 `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. 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.
 
-#### Decisions to define in the spec
+#### Implementation and evidence
 
-1. Where and when phase selection is configured.
-2. Default selections.
-3. Whether selections can change after a workflow starts.
+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.
+
+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 issue adds independent optionality for both post-`builder` agent phases.
-
-## Implemented, acceptance not confirmed
+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
 

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.

package/docs/configuration.md

@@ -15,16 +15,19 @@ For example, if Pi starts in `/work/app/src`, `Maestro` reads `/work/app/src/.pi
   "version": "1.0.0",
   "specDirectory": ".specs",
   "builder": {
+    "required": true,
     "model": "openai-codex/gpt-5.6-luna",
     "thinking": "max",
     "timeoutMinutes": 60
   },
   "simplifier": {
+    "required": true,
     "model": "openai-codex/gpt-6.1-sol",
     "thinking": "high",
     "timeoutMinutes": 60
   },
   "verifier": {
+    "required": true,
     "model": "openai-codex/gpt-6.1-sol",
     "thinking": "high",
     "timeoutMinutes": 60
@@ -39,19 +42,25 @@ For example, if Pi starts in `/work/app/src`, `Maestro` reads `/work/app/src/.pi
 | `version`                   | Yes, when the file exists | `1.0.0`                     | Configuration format version. Only `1.0.0` is supported.        |
 | `specDirectory`             |                        No | `.specs`                    | Relative path below the project root.                           |
 | `builder`                   |                        No | `Builder` defaults          | Overrides supported `builder` fields.                           |
-| `builder.model`             |                        No | `openai-codex/gpt-5.6-luna` | Full `provider/model` identifier.                               |
+| `builder.required`          |                        No | `true`                      | Boolean selecting the `builder` phase.                          |
+| `builder.model`             |                        No | `openai-codex/gpt-5.6-luna` | Model string passed unchanged to Pi.                            |
 | `builder.thinking`          |                        No | `max`                       | One supported thinking level.                                   |
 | `builder.timeoutMinutes`    |                        No | `60`                        | Integer from `1` to `1440`. Applies to each `builder` `run`.    |
 | `verifier`                  |                        No | `Verifier` defaults         | Overrides supported `verifier` fields.                          |
-| `verifier.model`            |                        No | `openai-codex/gpt-6.1-sol`  | Full `provider/model` identifier.                               |
+| `verifier.required`         |                        No | `true`                      | Boolean selecting the `verifier` phase.                         |
+| `verifier.model`            |                        No | `openai-codex/gpt-6.1-sol`  | Model string passed unchanged to Pi.                            |
 | `verifier.thinking`         |                        No | `high`                      | One supported thinking level.                                   |
 | `verifier.timeoutMinutes`   |                        No | `60`                        | Integer from `1` to `1440`. Applies to each `verifier` `run`.   |
 | `simplifier`                |                        No | `Simplifier` defaults       | Overrides supported `simplifier` fields.                        |
-| `simplifier.model`          |                        No | `openai-codex/gpt-6.1-sol`  | Full `provider/model` identifier.                               |
+| `simplifier.required`       |                        No | `true`                      | Boolean selecting the `simplifier` phase.                       |
+| `simplifier.model`          |                        No | `openai-codex/gpt-6.1-sol`  | Model string passed unchanged to Pi.                            |
 | `simplifier.thinking`       |                        No | `high`                      | One supported thinking level.                                   |
 | `simplifier.timeoutMinutes` |                        No | `60`                        | Integer from `1` to `1440`. Applies to each `simplifier` `run`. |
 
-Model identifiers use the full `provider/model` form shown in the defaults. `Maestro` accepts these thinking levels:
+Model values use the full `provider/model` identifier supplied by Pi's model registry, such as `openrouter/~openai/gpt-mini-latest`. Model IDs may contain additional
+slashes. `Maestro` does not apply a separate format rule; it matches the complete identifier against Pi's available models and passes it unchanged through `pi-subagents`.
+
+`Maestro` accepts these thinking levels:
 
 ```text
 off
@@ -78,6 +87,25 @@ Only `version` is required when the file exists. Each other field overrides its
 
 This example keeps every default except the `builder` timeout.
 
+## Phase selection
+
+Set each agent's `required` boolean before activation and leave configuration unchanged until the workflow completes. Omitted flags default to `true`, even when an agent
+section or the entire file is absent. Strings, numbers, and `null` are invalid.
+
+With `builder.required: false`, approval completes the workflow with an approved `spec` and no agent execution, regardless of the other flags. The approved `spec` can be
+used for implementation in another workflow. With `builder` enabled, `verifier` and `simplifier` can each be disabled independently. Neither runs without `builder`.
+
+| `builder.required` | `verifier.required` | `simplifier.required` | Selected phases after approval |
+| ------------------ | ------------------- | --------------------- | ------------------------------ |
+| `false`            | Any                 | Any                   | None; approved `spec` only     |
+| `true`             | `false`             | `false`               | `Builder` only                 |
+| `true`             | `true`              | `false`               | `Builder`, then `verifier`     |
+| `true`             | `false`             | `true`                | `Builder`, then `simplifier`   |
+| `true`             | `true`              | `true`                | All three, in order            |
+
+Disabled phases do not require agent or model availability and produce no `handoff`. The final summary identifies skipped work rather than claiming it was performed.
+Enabled simplification can still be skipped if Git is unavailable.
+
 ## Schema version
 
 `version` identifies the configuration format, not the npm package version. The supported value is `1.0.0`. Other values stop activation.
@@ -95,7 +123,12 @@ For example, `specDirectory: "planning/specs"` places `specs` in `<project-root>
 
 ## Model access
 
-`Maestro` checks all three configured models during activation. Each model must exist and have valid authentication.
+During activation, `Maestro` checks only enabled agents and their configured models against `context.modelRegistry.getAvailable()`. Pi's registry is the source of truth
+for model availability; `Maestro` does not maintain a separate model list or authentication check. A missing enabled model stops activation and identifies the full
+configured identifier.
+
+With `builder` disabled, activation checks only project trust and configuration, with no agent checks, model lookup, or `pi-subagents` ping. With `builder` enabled, the
+availability ping remains required.
 
-A model error stops activation and identifies the affected model. The `owner` can correct the model identifier or authenticate the provider, then run `/maestro` again.
-Agent names and context are described in [Subagent integration](subagent-integration.md#roles-and-context).
+The `owner` can correct the identifier or authenticate the provider in Pi, then retry `/maestro`. Authentication or provider errors during delegation still appear as
+`run` failures. Agent names and context are described in [Subagent integration](subagent-integration.md#roles-and-context).

package/docs/glossary.md

@@ -20,7 +20,7 @@
 | `Candidate`                   | The project files created by agents after a workflow `run`                                                                                                                                                                            |
 | `Finding`                     | A technical issue that the `verifier` records for an `owner` decision.                                                                                                                                                                |
 | `Escalation`                  | An implementation question or reportable technical problem that the `builder` records in its `handoff` for an `owner` decision.                                                                                                       |
-| `GREEN FLAG`                  | The owner's explicit reply that approves the current `spec` and starts the `builder`.                                                                                                                                                 |
+| `GREEN FLAG`                  | The owner's explicit reply that approves the current `spec` and proceeds through the selected phases.                                                                                                                                 |
 | `fix-code`                    | An `owner` decision that requests code fixes without changing the approved `spec`.                                                                                                                                                    |
 | `revise-spec`                 | An `owner` decision that records a reason and agreed requirement change, then returns to `drafting-spec` for revision and renewed approval.                                                                                           |
 | `reject`                      | An `owner` decision that declines a `finding` and records a reason. It does not mean that verification passed.                                                                                                                        |

package/docs/subagent-integration.md

@@ -19,8 +19,9 @@ and available skills. The global file normally lives at `~/.pi/agent/AGENTS.md`.
 `Maestro` supplies the `spec` ID, project directory, model, thinking level, and timeout. The agents read all approved documents (`proposal.md`, `spec.md`, and `design.md`
 when present) and saved `artifacts` to understand the work. Earlier `artifacts` provide context, not proof.
 
-The `owner` does not call agent tools directly. `Maestro` starts the `builder` after `GREEN FLAG` approval. The `verifier` starts after successful `builder` completion,
-and the `simplifier` follows successful `verifier` completion.
+The `owner` does not call agent tools directly. `Maestro` starts the enabled `builder` after `GREEN FLAG` approval. The enabled `verifier` starts after successful
+`builder` completion. The enabled `simplifier` follows the selected preceding phases. Disabled agents are not delegated. See
+[Phase selection](configuration.md#phase-selection).
 
 ## Following a run
 
@@ -36,8 +37,9 @@ If a `run` fails or returns without a valid saved result, `Maestro` reports the
 
 ## External configuration
 
-The `pi-subagents` extension must be installed and enabled in Pi. `Builder`, `verifier`, and `simplifier` model choices, thinking levels, and timeouts come from
-[Maestro configuration](configuration.md). Other `pi-subagents` configuration remains the owner's responsibility.
+The `pi-subagents` extension must be installed and enabled in Pi when `builder` is enabled. Workflows with only an approved `spec` need no agent availability or ping.
+`Builder`, `verifier`, and `simplifier` model choices, thinking levels, and timeouts come from [Maestro configuration](configuration.md). Other `pi-subagents`
+configuration remains the owner's responsibility.
 
 Only `maestro_run_simplifier` checks Git readiness, with `git rev-parse --is-inside-work-tree`. If readiness cannot be confirmed, it warns and completes without
 delegation. The `simplifier` uses Git to select all uncommitted code changes. `Maestro` does not change the Git index or create commits or checkpoints.

package/docs/workflow.md

@@ -41,7 +41,14 @@ independently and which issues it found.
 
 ## Main flow
 
-The green arrows and lines show the path without `escalations` or `findings`.
+The diagram shows the default flow with all three agents enabled. The green arrows and lines show the path without `escalations` or `findings`.
+
+The `owner` selects phases through each agent's `required` boolean before activation and leaves configuration unchanged during the workflow. All flags default to `true`.
+See [Phase selection](configuration.md#phase-selection).
+
+With `builder` disabled, approval moves directly to `candidate-ready` and all agents are skipped. Otherwise, after `builder` completion, disabled verification is
+bypassed: the workflow enters `simplifier-running` if simplification is enabled, or `candidate-ready` otherwise. Successful verification and rejection of all current
+`findings` also move directly to `candidate-ready` when simplification is disabled. Skipped agents are not delegated and need no `handoffs`.
 
 ```mermaid
 flowchart TD
@@ -84,17 +91,17 @@ alone does not establish a completed action.
 
 The default path is `.specs/<spec-id>/workflow.json`. The `spec` directory is [configurable](configuration.md).
 
-| Phase                  | Meaning                                                                                                                        |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `drafting-spec`        | The `owner` and `Maestro` prepare the initial `spec` or revise it after recorded `escalation` answers or `finding` decisions.  |
-| `ready-for-builder`    | The approved `spec` or recorded `owner` decisions permit a `builder` `run`.                                                    |
-| `builder-running`      | A `builder` `run` is active.                                                                                                   |
-| `escalation-decisions` | The `owner` must decide how to handle every `escalation` question.                                                             |
-| `ready-for-verifier`   | The `builder` completed the work and the `verifier` can start.                                                                 |
-| `verifier-running`     | A `verifier` `run` is active.                                                                                                  |
-| `finding-decisions`    | The `owner` must decide how to handle every current `finding`.                                                                 |
-| `simplifier-running`   | Verification succeeded or the `owner` rejected all current `findings`. The `simplifier` can run or skip if Git is unavailable. |
-| `candidate-ready`      | Simplification completed. The workflow is complete.                                                                            |
+| Phase                  | Meaning                                                                                                                       |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `drafting-spec`        | The `owner` and `Maestro` prepare the initial `spec` or revise it after recorded `escalation` answers or `finding` decisions. |
+| `ready-for-builder`    | The approved `spec` or recorded `owner` decisions permit a `builder` `run`.                                                   |
+| `builder-running`      | A `builder` `run` is active.                                                                                                  |
+| `escalation-decisions` | The `owner` must decide how to handle every `escalation` question.                                                            |
+| `ready-for-verifier`   | The `builder` completed the work and the `verifier` can start.                                                                |
+| `verifier-running`     | A `verifier` `run` is active.                                                                                                 |
+| `finding-decisions`    | The `owner` must decide how to handle every current `finding`.                                                                |
+| `simplifier-running`   | Selected preceding phases finished. The enabled `simplifier` can run or skip if Git is unavailable.                           |
+| `candidate-ready`      | The selected phases completed or were skipped. The workflow is complete.                                                      |
 
 ## Specification documents
 
@@ -112,9 +119,9 @@ For the initial `spec`:
 
 1. `Maestro` creates `proposal.md`, `spec.md`, and `workflow.json` in `drafting-spec`, then prepares the documents with the `owner`. It adds `design.md` only when needed.
 2. The `owner` reviews the complete document set: motivation, scope, requirements, `acceptance criteria`, and any approved technical decisions.
-3. `Maestro` asks the `owner` to inspect `proposal.md`, `spec.md`, and `design.md` when present and reply `GREEN FLAG` once to approve the entire set and start the
-   `builder`.
-4. After that reply, `Maestro` saves `ready-for-builder` and starts the `builder` in the foreground.
+3. `Maestro` asks the `owner` to inspect `proposal.md`, `spec.md`, and `design.md` when present and reply `GREEN FLAG` once to approve the entire set and proceed through
+   the selected phases.
+4. After that reply, `Maestro` saves `ready-for-builder` and starts the enabled `builder` in the foreground, or saves `candidate-ready` with all agents skipped.
 
 Approval freezes all present `spec` documents and visual prototypes together. None may change during `builder`, `verifier`, or `simplifier` execution. See
 [Spec revision](#spec-revision) for permitted revisions.
@@ -230,11 +237,11 @@ that file's `findings` list, not a separate `F2.json` file. `Finding` numbers re
 `Maestro` records `owner` decisions in the same `verifier` report, e.g. decisions about `V1/F2` update `V1.json`, not a new `V2.json`. A new `verifier` result creates the
 next report (`V2.json`).
 
-| Decision      | Result                                                                                                         |
-| ------------- | -------------------------------------------------------------------------------------------------------------- |
-| `reject`      | Records the owner's reason. If every `finding` is rejected, the workflow reaches `simplifier-running`.         |
-| `fix-code`    | Keeps the current `spec` and returns to `ready-for-builder` for code fixes when no decision requires revision. |
-| `revise-spec` | Records the owner's reason and agreed requirement change, then returns to `drafting-spec`.                     |
+| Decision      | Result                                                                                                                                           |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `reject`      | Records the owner's reason. If every `finding` is rejected, the workflow reaches `simplifier-running` when enabled, otherwise `candidate-ready`. |
+| `fix-code`    | Keeps the current `spec` and returns to `ready-for-builder` for code fixes when no decision requires revision.                                   |
+| `revise-spec` | Records the owner's reason and agreed requirement change, then returns to `drafting-spec`.                                                       |
 
 `Maestro` saves every current decision together before the phase changes. If any `finding` requires revision, revision takes priority over code fixes and rejections. See
 [Spec revision](#spec-revision).
@@ -262,8 +269,8 @@ Cleanup relies on the `verifier`. If cleanup cannot finish safely, the `verifier
 
 ## Simplification
 
-After a successful verification, Maestro starts the `simplifier`. The `simplifier` runs only if Git is available, if not, a warning is displayed:
-`Simplifier skipped: Git repository unavailable.`
+When enabled, `Maestro` starts the `simplifier` after successful verification, rejection of all `findings`, or `builder` completion with verification disabled. The
+`simplifier` runs only if Git is available, if not, a warning is displayed: `Simplifier skipped: Git repository unavailable.`
 
 The `simplifier` starts from all staged, unstaged, and untracked code changes, including pre-existing changes. It preserves observable behavior and introduces no new
 check failures. If no code needs refactoring, the `simplifier` does not make any change.
@@ -271,7 +278,9 @@ check failures. If no code needs refactoring, the `simplifier` does not make any
 ## Workflow completion
 
 The workflow ends at `candidate-ready`. `Maestro` summarizes the changes, verification results, rejected `findings` and reasons, relevant `builder` notes from the saved
-`artifacts`, and simplifier's summary and notes.
+`artifacts`, and simplifier's summary and notes, only for phases that ran. It identifies every skipped phase and its reason. An approved `spec` alone does not mean code
+was implemented or verified. `Builder` checks and the simplifier's report are not independent verification when `verifier` is disabled. The `owner` can use an approved
+`spec` for implementation in another workflow without further `Maestro` execution.
 
 `Maestro` stays active while delivering this final summary, then automatically turns off after successful delivery. The `owner` performs the final review and controls any
 later Git use, pull request, or merge. Changes after completion are outside the completed verification.

package/extensions/maestro.ts

@@ -87,29 +87,27 @@ export default (pi: ExtensionAPI): void => {
       try {
         await assertEnvironment({ context, piEventsBus: pi.events });
         const config = await loadConfiguration(context.cwd);
+        const isImplementationEnabled = config.builder.required;
 
         maestroSessionState.activate();
         syncMainTools();
         await refreshMaestroStatus(context);
 
-        // Introduce Maestro and show configured agents only in the UI.
+        // Introduce Maestro and show enabled agents only in the UI.
         context.ui.notify(
           [
             context.ui.theme.fg('muted', 'Maestro active'),
             'Maestro helps the owner define a spec, then coordinates implementation and independent verification.',
             'Ask how Maestro works for a short explanation.',
-            context.ui.theme.fg(
-              'accent',
-              `Builder (${config.builder.model} ${config.builder.thinking})`,
-            ),
-            context.ui.theme.fg(
-              'accent',
-              `Verifier (${config.verifier.model} ${config.verifier.thinking})`,
-            ),
-            context.ui.theme.fg(
-              'accent',
-              `Simplifier (${config.simplifier.model} ${config.simplifier.thinking})`,
-            ),
+            ...[
+              { label: 'Builder', settings: config.builder },
+              { label: 'Verifier', settings: config.verifier },
+              { label: 'Simplifier', settings: config.simplifier },
+            ]
+              .filter(({ settings }) => isImplementationEnabled && settings.required)
+              .map(({ label, settings }) =>
+                context.ui.theme.fg('accent', `${label} (${settings.model} ${settings.thinking})`),
+              ),
           ].join('\n'),
           'info',
         );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emiliosp/pi-maestro",
-  "version": "0.13.1",
+  "version": "0.15.0",
   "description": "A spec-driven multiagent development workflow for Pi.",
   "keywords": [
     "orchestration",

package/src/config/assertConfiguration.ts

@@ -39,7 +39,7 @@ const formatError = (error: SchemaValidationError): string => {
   }
 
   if (path.endsWith('model')) {
-    return `Invalid model identifier at "${path}". Must use "provider/model" format.`;
+    return `Invalid model at "${path}": expected a string.`;
   }
 
   if (path === 'builder' || path === 'verifier' || path === 'simplifier') {