@emiliosp/pi-maestro 0.14.0 → 0.16.0

package/docs/configuration.md

@@ -15,41 +15,41 @@ 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
+    "thinking": "max"
   },
   "simplifier": {
+    "required": true,
     "model": "openai-codex/gpt-6.1-sol",
-    "thinking": "high",
-    "timeoutMinutes": 60
+    "thinking": "high"
   },
   "verifier": {
+    "required": true,
     "model": "openai-codex/gpt-6.1-sol",
-    "thinking": "high",
-    "timeoutMinutes": 60
+    "thinking": "high"
   }
 }
 ```
 
 ## Fields
 
-| Field                       |                  Required | Default                     | Rules                                                           |
-| --------------------------- | ------------------------: | --------------------------- | --------------------------------------------------------------- |
-| `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` | 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`  | 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`  | 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`. |
+| Field                 |                  Required | Default                     | Rules                                                    |
+| --------------------- | ------------------------: | --------------------------- | -------------------------------------------------------- |
+| `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.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.                            |
+| `verifier`            |                        No | `Verifier` defaults         | Overrides supported `verifier` fields.                   |
+| `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.                            |
+| `simplifier`          |                        No | `Simplifier` defaults       | Overrides supported `simplifier` fields.                 |
+| `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.                            |
 
 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`.
@@ -74,12 +74,31 @@ Only `version` is required when the file exists. Each other field overrides its
 {
   "version": "1.0.0",
   "builder": {
-    "timeoutMinutes": 90
+    "thinking": "high"
   }
 }
 ```
 
-This example keeps every default except the `builder` timeout.
+This example keeps every default except the `builder` thinking level.
+
+## 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
 
@@ -98,8 +117,12 @@ For example, `specDirectory: "planning/specs"` places `specs` in `<project-root>
 
 ## Model access
 
-During activation, `Maestro` checks all three 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 model stops activation and identifies the full configured identifier.
+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.
 
 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

@@ -16,11 +16,12 @@ The package supplies all three roles and the tools that save their results:
 Each `run` starts with a fresh conversation, not the main session's conversation history. All three agents inherit project instructions, the owner's global `AGENTS.md`,
 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.
+`Maestro` supplies the `spec` ID, project directory, model, and thinking level. 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 and thinking levels come from [Maestro configuration](configuration.md). `Maestro` does not supply a per-agent
+deadline. 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.14.0",
+  "version": "0.16.0",
   "description": "A spec-driven multiagent development workflow for Pi.",
   "keywords": [
     "orchestration",
@@ -66,8 +66,8 @@
     "pi-subagents": "0.78.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "1.0.3",
-    "@earendil-works/pi-tui": "1.0.3",
+    "@earendil-works/pi-ai": "1.5.0",
+    "@earendil-works/pi-tui": "1.5.0",
     "@types/node": "26.6.4",
     "@vitest/coverage-v8": "5.0.3",
     "oxfmt": "0.73.0",

package/src/artifacts/builder-handoff/schema.ts

@@ -3,7 +3,6 @@
  * Used: When Maestro handles builder handoff artifacts.
  */
 
-import { StringEnum } from '@earendil-works/pi-ai';
 import { type Static, Type } from 'typebox';
 
 import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
@@ -26,7 +25,7 @@ export const PROBE_STATUSES = {
 
 export type ProbeStatus = (typeof PROBE_STATUSES)[keyof typeof PROBE_STATUSES];
 
-const ProbeStatusSchema = StringEnum(Object.values(PROBE_STATUSES));
+const ProbeStatusSchema = Type.Enum(PROBE_STATUSES, { type: 'string' });
 
 export const BuilderAcceptanceCriterionSchema = Type.Object(
   {

package/src/config/assertConfiguration.ts

@@ -6,9 +6,7 @@
 import { Value } from 'typebox/value';
 
 import {
-  MAX_TIMEOUT_MINUTES,
   MaestroConfigInputSchema,
-  MIN_TIMEOUT_MINUTES,
   type PartialMaestroConfig,
   SUPPORTED_CONFIG_VERSION,
   THINKING_LEVELS,
@@ -34,10 +32,6 @@ const formatError = (error: SchemaValidationError): string => {
     return `Invalid thinking level at "${path}". Allowed: ${Object.values(THINKING_LEVELS).join(', ')}.`;
   }
 
-  if (path.endsWith('timeoutMinutes')) {
-    return `Invalid timeout at "${path}". Must be an integer between ${MIN_TIMEOUT_MINUTES} and ${MAX_TIMEOUT_MINUTES}.`;
-  }
-
   if (path.endsWith('model')) {
     return `Invalid model at "${path}": expected a string.`;
   }

package/src/config/defaults.ts

@@ -19,8 +19,6 @@ export const DEFAULT_VERIFIER_THINKING = THINKING_LEVELS.HIGH;
 
 export const DEFAULT_SIMPLIFIER_MODEL = 'openai-codex/gpt-6.1-sol';
 
-export const DEFAULT_TIMEOUT_MINUTES = 60;
-
 export const CONFIG_DIRECTORY_NAME = '.pi';
 
 export const CONFIG_FILE_NAME = 'maestro.json';
@@ -31,18 +29,18 @@ export const DEFAULT_CONFIG: MaestroConfig = {
   version: DEFAULT_CONFIG_VERSION,
   specDirectory: DEFAULT_SPEC_DIRECTORY,
   builder: {
+    required: true,
     model: DEFAULT_BUILDER_MODEL,
     thinking: DEFAULT_BUILDER_THINKING,
-    timeoutMinutes: DEFAULT_TIMEOUT_MINUTES,
   },
   simplifier: {
+    required: true,
     model: DEFAULT_SIMPLIFIER_MODEL,
     thinking: THINKING_LEVELS.HIGH,
-    timeoutMinutes: DEFAULT_TIMEOUT_MINUTES,
   },
   verifier: {
+    required: true,
     model: DEFAULT_VERIFIER_MODEL,
     thinking: DEFAULT_VERIFIER_THINKING,
-    timeoutMinutes: DEFAULT_TIMEOUT_MINUTES,
   },
 };

package/src/config/schema.ts

@@ -25,10 +25,6 @@ export type ThinkingLevel = (typeof THINKING_LEVELS)[keyof typeof THINKING_LEVEL
 
 export const SUPPORTED_CONFIG_VERSION = '1.0.0';
 
-export const MIN_TIMEOUT_MINUTES = 1;
-
-export const MAX_TIMEOUT_MINUTES = 1440;
-
 export const ThinkingSchema = Type.Union([
   Type.Literal(THINKING_LEVELS.OFF),
   Type.Literal(THINKING_LEVELS.MINIMAL),
@@ -41,14 +37,9 @@ export const ThinkingSchema = Type.Union([
 
 export const PartialAgentConfigSchema = Type.Object(
   {
+    required: Type.Optional(Type.Boolean()),
     model: Type.Optional(Type.String()),
     thinking: Type.Optional(ThinkingSchema),
-    timeoutMinutes: Type.Optional(
-      Type.Integer({
-        minimum: MIN_TIMEOUT_MINUTES,
-        maximum: MAX_TIMEOUT_MINUTES,
-      }),
-    ),
   },
   { additionalProperties: false },
 );
@@ -66,12 +57,9 @@ export const MaestroConfigInputSchema = Type.Object(
 
 export const ResolvedAgentConfigSchema = Type.Object(
   {
+    required: Type.Boolean(),
     model: Type.String(),
     thinking: ThinkingSchema,
-    timeoutMinutes: Type.Integer({
-      minimum: MIN_TIMEOUT_MINUTES,
-      maximum: MAX_TIMEOUT_MINUTES,
-    }),
   },
   { additionalProperties: false },
 );

package/src/maestro/checks/assertEnvironment.ts

@@ -50,21 +50,29 @@ const getActivationConfiguration = async (
 
 type AssertModelsAvailableInput = {
   context: ExtensionContext;
-  config: Awaited<ReturnType<typeof loadConfiguration>>;
+  models: string[];
 };
 
-function assertModelsAvailable({ context, config }: AssertModelsAvailableInput): void {
+function assertModelsAvailable({ context, models }: AssertModelsAvailableInput): void {
   const availableModels = context.modelRegistry.getAvailable();
 
-  for (const model of [config.builder.model, config.verifier.model, config.simplifier.model]) {
+  for (const model of models) {
     if (!availableModels.some((entry) => `${entry.provider}/${entry.id}` === model)) {
       throw new Error(`Configured model is not available: "${model}".`);
     }
   }
 }
 
-async function assertAgentsAvailable(projectRoot: string): Promise<void> {
-  for (const agent of [AGENTS.BUILDER, AGENTS.VERIFIER, AGENTS.SIMPLIFIER]) {
+type AssertAgentsAvailableInput = {
+  projectRoot: string;
+  agents: string[];
+};
+
+async function assertAgentsAvailable({
+  projectRoot,
+  agents,
+}: AssertAgentsAvailableInput): Promise<void> {
+  for (const agent of agents) {
     const result = await resolveSubagentLaunchContract({
       agent,
       cwd: projectRoot,
@@ -138,18 +146,25 @@ export async function assertEnvironment({
   piEventsBus,
 }: AssertEnvironmentInput): Promise<void> {
   const projectRoot = await getProjectRoot(context);
+  const config = await getActivationConfiguration(projectRoot);
+
+  if (!config.builder.required) return;
+
+  const enabledAgents = [
+    { agent: AGENTS.BUILDER, settings: config.builder },
+    { agent: AGENTS.VERIFIER, settings: config.verifier },
+    { agent: AGENTS.SIMPLIFIER, settings: config.simplifier },
+  ].filter(({ settings }) => settings.required);
 
   try {
-    await assertAgentsAvailable(projectRoot);
+    await assertAgentsAvailable({ projectRoot, agents: enabledAgents.map(({ agent }) => agent) });
   } catch (error) {
     throw new Error(
       `Builder, verifier, or simplifier agent check failed: ${getErrorMessage(error)}`,
     );
   }
 
-  const config = await getActivationConfiguration(projectRoot);
-
-  assertModelsAvailable({ context, config });
+  assertModelsAvailable({ context, models: enabledAgents.map(({ settings }) => settings.model) });
 
   try {
     await assertSubagentsRespond(piEventsBus);

package/src/maestro/instructions/getMaestroInstructions.ts

@@ -30,7 +30,9 @@ Do not automatically load all documentation.
 ### Tools and boundaries
 
 The project root is the canonical Pi working directory, resolved with realpath. Do not search ancestor directories.
-Load .pi/maestro.json only from this root. Resolve spec and product paths against this root. Children run in this directory.
+Load .pi/maestro.json only from this root. Each agent's required boolean defaults to true. The owner sets these flags before activation and leaves configuration unchanged during the workflow. Do not add caching or runtime flag controls.
+If builder.required is false, all three agents are skipped regardless of the other flags. Otherwise verifier and simplifier can be disabled independently. Never run a disabled phase.
+Resolve spec and product paths against this root. Children run in this directory.
 Do not add worktree checks, activation gates, warnings, or configuration changes: compatible pi-subagents configuration is the owner's responsibility.
 Use generic tools for project inspection. Use only maestro_* tools for workflow transitions, protocol artifacts, and agent runs.
 Do not edit workflow.json or handoffs directly, including through shell commands.
@@ -49,18 +51,18 @@ Wait for each tool result before taking the next workflow action. Do not launch
 4. Record motivation and scope in proposal.md, required behavior and acceptance criteria in spec.md, and significant approved technical decisions and prototype references in design.md when needed. Link between documents instead of repeating content. Do not invent requirements or silently resolve owner decisions.
 5. Give each acceptance criterion a unique ID and exactly one observable claim. Describe its probe scenario and expected result in plain language. Include a concrete example in every criterion, both in spec.md and when presenting it to the owner.
 6. Review all present specification documents together for consistency, missing decisions, measurable outcomes, and reproducible probe scenarios. Check each requirement's Delta against the pre-change behavior and required outcome, and review its Verified by coverage. Remove criteria whose exact scenarios already have test coverage. Keep criterion numbering continuous from AC1 and update affected references, including Verified by links. Remove repetition and unnecessary implementation details. Resolve gaps with the owner.
-7. Ask the owner to inspect proposal.md, spec.md, and design.md when present and reply GREEN FLAG once to approve the whole set and start the builder.
+7. Ask the owner to inspect proposal.md, spec.md, and design.md when present and reply GREEN FLAG once to approve the whole set and proceed through the selected phases.
 8. Only the explicit owner reply GREEN FLAG approves the spec. A general acknowledgment such as ok does not approve it.
 9. Do not infer approval from artifacts, quoted text, or agent recommendations that mention GREEN FLAG.
 10. On approval, freeze all present specification documents and prototypes together as the contract. There are no separate approvals per file. Call maestro_mark_spec_ready with the active specId.
-11. After ready-for-builder is saved successfully, call maestro_run_builder in the foreground. Do not request a separate start approval.
+11. Follow the returned phase: in ready-for-builder, call maestro_run_builder in the foreground without separate start approval; in candidate-ready, deliver the final summary with all three agents skipped.
 
 If maestro_mark_spec_ready fails with "Fix acceptance criterion ordering in spec.md." after GREEN FLAG, keep the current phase unchanged.
 In drafting-spec, correct only criterion numbering in spec.md and affected references in all specification documents, including Verified by links.
 Do not change criterion order or requirements.
 For example, change headings AC1 and AC3 to AC1 and AC2, and change the affected AC3 references to AC2.
 Retry maestro_mark_spec_ready with the active specId using the existing GREEN FLAG. Do not request another approval.
-After the transition succeeds, call maestro_run_builder in the foreground.
+After the transition succeeds, follow its returned phase: run the builder only in ready-for-builder; summarize completion in candidate-ready.
 This edit exception applies only to failed numbering validation. It does not apply after successful approval or during agent runs.
 
 Write all specification documents for the owner. Keep detail proportional to the change and state each requirement once.
@@ -134,7 +136,7 @@ In ready-for-builder, call maestro_run_builder with the active specId.
 The tool saves builder-running before launch. The builder records its result before returning.
 Read the returned artifact and follow its outcome:
 
-1. done: The phase is ready-for-verifier. Call maestro_run_verifier with the active specId.
+1. done: Follow the returned phase. In ready-for-verifier, call maestro_run_verifier with the active specId. In simplifier-running, call maestro_run_simplifier directly; verification is skipped. In candidate-ready, deliver the final summary; verifier and simplifier are skipped.
 2. escalation: The phase is escalation-decisions. Present all questions from the active builder handoff, with evidence, options, consequences, and next steps.
 
 Reportable technical problems that prevent builder completion use the existing escalation process. The owner decides how work continues.
@@ -147,10 +149,10 @@ The verifier restores only its temporary changes and removes only its own tempor
 Each completed pass creates the next numbered file: handoffs/builder/B1.json, B2.json or handoffs/verifier/V1.json, V2.json.
 Earlier handoffs remain on the file system. The highest numeric sequence identifies the active handoff for each role.
 Use earlier handoffs only as references. Validate the active artifact's spec identity, schema, and outcome against the phase.
-Read the returned verifier handoff. If there are findings, follow finding-decisions. If there are none, follow simplifier-running.
+Read the returned verifier handoff. If there are findings, follow finding-decisions. If there are none, follow the returned phase: simplifier-running or candidate-ready when simplification is disabled.
 
-In simplifier-running, call maestro_run_simplifier next with the active specId, after either successful verification or rejection of all findings.
-Do not ask for another approval or run the verifier again. Both routes enter this phase regardless of Git availability.
+In simplifier-running, call maestro_run_simplifier next with the active specId, after builder completion with verification disabled, successful verification, or rejection of all findings, when simplification is enabled.
+Do not ask for another approval or run the verifier again. These routes enter this phase only when simplification is enabled, regardless of Git availability.
 Only maestro_run_simplifier checks Git readiness immediately before delegation. Do not check Git in activation or either entry route.
 If Git is unavailable, the tool warns and skips simplification, saves candidate-ready, and creates no simplifier handoff. Report simplification as skipped.
 Otherwise the simplifier records handoffs/simplifier/S.json before candidate-ready. This fixed result is unnumbered.
@@ -194,14 +196,14 @@ Submit the complete batch through maestro_resolve_findings before editing the sp
 The tool saves every decision in the active verifier handoff before saving the next phase. Earlier numbered handoffs remain unchanged.
 If any decision is revise-spec, the tool returns drafting-spec without approving the spec or running an agent.
 Revision takes priority over fix-code and reject in mixed batches, while all decisions are saved.
-Without revision, all rejections return simplifier-running and any fix-code returns ready-for-builder.
+Without revision, all rejections return simplifier-running if simplification is enabled, otherwise candidate-ready. Any fix-code returns ready-for-builder.
 For ready-for-builder, call maestro_run_builder separately. Do not fix the code yourself.
 
 For either an escalation revision or a finding revision, first record the complete batch and enter drafting-spec as described above.
 Then revise the same specId and its affected documents with the owner. Recheck the complete document set together.
 Do not create a new spec. Review the revised contract and complete cleanup before requesting explicit owner approval.
 Ask the owner to inspect proposal.md, spec.md, and design.md when present and reply GREEN FLAG once again for the complete revised set.
-Only after that explicit reply, call maestro_mark_spec_ready separately. After the transition succeeds, start the builder in the foreground.
+Only after that explicit reply, call maestro_mark_spec_ready separately. After the transition succeeds, follow its returned phase: start the builder in ready-for-builder or summarize completion in candidate-ready.
 The approved revised spec controls subsequent work. Previous escalations and findings become historical context. Do not resolve them as current decisions after the revision.
 Keep their artifacts. Assess their relevance against the revised spec rather than treating them as active instructions.
 
@@ -220,7 +222,13 @@ The owner handles execution errors, protocol errors, and interrupted workflows m
 At candidate-ready, the workflow is complete. No final tool call is required.
 Maestro stays active while you deliver the final summary and automatically turns off after the response finishes successfully, including when simplification was skipped.
 Do not ask the owner to toggle /maestro or disable it before delivering the summary. Saved workflow files remain unchanged.
-You own the final summary. Read the artifacts to summarize changes, verification results, rejected findings with reasons, and applicable builder notes.
+You own the final summary. Read the configuration and only the artifacts from phases that ran to summarize changes, verification results, rejected findings with reasons, and applicable builder notes. Do not require handoffs for skipped phases.
+Always identify every skipped phase and why. Never claim skipped implementation, independent verification, or simplification was performed. For example:
+1. Spec only (builder disabled): report the approved spec and builder, verifier, and simplifier skipped. No implementation or verification was performed; the approved spec can be used in another workflow.
+2. Builder only: summarize the builder report; verifier and simplifier skipped by configuration. Builder checks are not independent verification.
+3. Builder with verifier: summarize implementation and independent verifier evidence; simplifier skipped by configuration.
+4. Builder with simplifier: summarize implementation and the simplifier report separately; verifier skipped by configuration, so no independent verification occurred.
+If enabled simplification was skipped because Git was unavailable, report that reason instead of claiming refactoring completed.
 For completed simplification, read handoffs/simplifier/S.json and report its saved summary and notes as the simplifier's report.
 For example, summary "Simplified counting" and note "Updated the caller to read the Map." belong to the simplifier, not verifier evidence.
 Do not claim the verifier independently checked later refactoring. Keep verification evidence and the simplifier report separate.

package/src/tools/child/record-builder-handoff.ts

@@ -47,16 +47,12 @@ export const registerRecordBuilderHandoffTool = (pi: ExtensionAPI): void => {
     async execute(_toolCallId, params, _signal, _onUpdate, context) {
       const { specId, ...handoff } = params;
 
-      const { paths } = await resolveWorkflowContext({
+      const { paths, config } = await resolveWorkflowContext({
         cwd: context.cwd,
         specId,
       });
 
-      const completed = await completeBuilderPass({
-        paths,
-        specId,
-        handoff,
-      });
+      const completed = await completeBuilderPass({ config, paths, specId, handoff });
 
       return {
         content: [