@emiliosp/pi-maestro 0.13.1 → 0.15.0

package/src/config/defaults.ts

@@ -31,16 +31,19 @@ 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

@@ -23,8 +23,6 @@ export const THINKING_LEVELS = {
 
 export type ThinkingLevel = (typeof THINKING_LEVELS)[keyof typeof THINKING_LEVELS];
 
-export const MODEL_PATTERN = '^[^/\\s]+/[^/\\s]+$';
-
 export const SUPPORTED_CONFIG_VERSION = '1.0.0';
 
 export const MIN_TIMEOUT_MINUTES = 1;
@@ -43,7 +41,8 @@ export const ThinkingSchema = Type.Union([
 
 export const PartialAgentConfigSchema = Type.Object(
   {
-    model: Type.Optional(Type.String({ pattern: MODEL_PATTERN })),
+    required: Type.Optional(Type.Boolean()),
+    model: Type.Optional(Type.String()),
     thinking: Type.Optional(ThinkingSchema),
     timeoutMinutes: Type.Optional(
       Type.Integer({
@@ -68,7 +67,8 @@ export const MaestroConfigInputSchema = Type.Object(
 
 export const ResolvedAgentConfigSchema = Type.Object(
   {
-    model: Type.String({ pattern: MODEL_PATTERN }),
+    required: Type.Boolean(),
+    model: Type.String(),
     thinking: ThinkingSchema,
     timeoutMinutes: Type.Integer({
       minimum: MIN_TIMEOUT_MINUTES,

package/src/maestro/checks/assertEnvironment.ts

@@ -50,23 +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]) {
-    const [provider, id] = model.split('/');
-
-    if (!availableModels.some((entry) => entry.provider === provider && entry.id === id)) {
+  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,
@@ -140,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: [

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

@@ -44,12 +44,13 @@ export const registerRecordSimplifierHandoffTool = (pi: ExtensionAPI): void => {
     async execute(_toolCallId, params, _signal, _onUpdate, context) {
       assertSimplifierSubmission(params);
 
-      const { paths } = await resolveWorkflowContext({
+      const { paths, config } = await resolveWorkflowContext({
         cwd: context.cwd,
         specId: params.specId,
       });
 
       const completed = await completeSimplifierPass({
+        config,
         paths,
         specId: params.specId,
         handoff: { ...params, version: SIMPLIFIER_HANDOFF_VERSION },

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

@@ -53,7 +53,7 @@ export const registerRecordVerifierHandoffTool = (pi: ExtensionAPI): void => {
     async execute(_toolCallId, params, _signal, _onUpdate, context) {
       const { specId, ...submission } = params;
 
-      const { paths } = await resolveWorkflowContext({
+      const { paths, config } = await resolveWorkflowContext({
         cwd: context.cwd,
         specId,
       });
@@ -69,11 +69,7 @@ export const registerRecordVerifierHandoffTool = (pi: ExtensionAPI): void => {
         notes: submission.notes,
       };
 
-      const completed = await completeVerifierPass({
-        paths,
-        specId,
-        handoff,
-      });
+      const completed = await completeVerifierPass({ config, paths, specId, handoff });
 
       return {
         content: [

package/src/tools/child/utils/resolveWorkflowContext.ts

@@ -16,7 +16,7 @@ export const resolveWorkflowContext = async ({ cwd, specId }: ResolveWorkflowCon
     throw new Error(`Invalid spec ID: "${specId}".`);
   }
 
-  const { paths, projectRoot } = await resolveToolRunContext(cwd);
+  const { paths, projectRoot, config } = await resolveToolRunContext(cwd);
 
-  return { paths, specId, projectRoot };
+  return { paths, specId, projectRoot, config };
 };

package/src/tools/main/mark-spec-ready.ts

@@ -10,12 +10,13 @@ import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
 import maestroSessionState from '#maestro/session/MaestroSessionState.ts';
 import { resolveToolRunContext } from '#tools/utils/resolveToolRunContext.ts';
 import { markSpecReady } from '#workflow/spec/markSpecReady.ts';
+import { WORKFLOW_PHASES } from '#workflow/state/schema.ts';
 
 export const MARK_SPEC_READY_TOOL = {
   NAME: 'maestro_mark_spec_ready',
   LABEL: 'Mark Spec Ready',
   DESCRIPTION:
-    'Approve proposal.md and spec.md together with design.md if present, only from drafting-spec after the owner replies GREEN FLAG. Freeze all present documents and move to ready-for-builder. Only the owner reply GREEN FLAG authorizes approval. After this transition succeeds, call maestro_run_builder in the foreground.',
+    'Approve proposal.md and spec.md together with design.md if present, only from drafting-spec after the owner replies GREEN FLAG. Freeze all present documents and move to the configured next phase. Only the owner reply GREEN FLAG authorizes approval. Run the builder only if the returned phase is ready-for-builder; otherwise summarize the approved spec and skipped agents.',
 } as const;
 
 const MarkSpecReadyToolParameters = Type.Object(
@@ -32,9 +33,10 @@ export const registerMarkSpecReadyTool = (pi: ExtensionAPI): void => {
     description: MARK_SPEC_READY_TOOL.DESCRIPTION,
     parameters: MarkSpecReadyToolParameters,
     async execute(_toolCallId, { specId }, _signal, _onUpdate, context) {
-      const { paths } = await resolveToolRunContext(context.cwd);
+      const { paths, config } = await resolveToolRunContext(context.cwd);
 
       const state = await markSpecReady({
+        config,
         paths,
         specId,
         activeWorkflowSpecId: maestroSessionState.getActiveSpecId(),
@@ -44,7 +46,10 @@ export const registerMarkSpecReadyTool = (pi: ExtensionAPI): void => {
         content: [
           {
             type: 'text',
-            text: `Spec ${state.specId} is approved and ready-for-builder. Call maestro_run_builder now. No separate owner start request is needed.`,
+            text:
+              state.phase === WORKFLOW_PHASES.CANDIDATE_READY
+                ? `Spec ${state.specId} is approved. The workflow is candidate-ready. Builder, verifier, and simplifier skipped by configuration. No implementation or verification was performed.`
+                : `Spec ${state.specId} is approved and ready-for-builder. Call maestro_run_builder now. No separate owner start request is needed.`,
           },
         ],
         details: state,

package/src/tools/main/resolve-escalations.ts

@@ -47,9 +47,10 @@ export const registerResolveEscalationsTool = (pi: ExtensionAPI): void => {
     parameters: ResolveEscalationsToolParameters,
     async execute(_toolCallId, params, _signal, _onUpdate, context) {
       const { specId, specChangeRequired, decisions } = params;
-      const { paths } = await resolveToolRunContext(context.cwd);
+      const { paths, config } = await resolveToolRunContext(context.cwd);
 
       const resolved = await resolveEscalations({
+        config,
         paths,
         specId,
         specChangeRequired,

package/src/tools/main/resolve-findings.ts

@@ -96,6 +96,10 @@ const formatResolution = (details: FindingResolutionDetails): string => {
     return `${summary} The workflow is ready-for-builder. Run the builder separately.`;
   }
 
+  if (details.phase === WORKFLOW_PHASES.CANDIDATE_READY) {
+    return `${summary} The workflow is candidate-ready. Simplifier skipped by configuration.`;
+  }
+
   return `${summary} The workflow is simplifier-running. Call maestro_run_simplifier next with this specId, without another approval or verifier pass.`;
 };
 
@@ -106,13 +110,9 @@ export const registerResolveFindingsTool = (pi: ExtensionAPI): void => {
     description: RESOLVE_FINDINGS_TOOL.DESCRIPTION,
     parameters: ResolveFindingsToolParameters,
     async execute(_toolCallId, { specId, decisions }, _signal, _onUpdate, context) {
-      const { paths } = await resolveToolRunContext(context.cwd);
+      const { paths, config } = await resolveToolRunContext(context.cwd);
 
-      const resolved = await resolveFindings({
-        paths,
-        specId,
-        decisions,
-      });
+      const resolved = await resolveFindings({ config, paths, specId, decisions });
 
       const details: FindingResolutionDetails = {
         specId: resolved.state.specId,

package/src/tools/main/run-builder.ts

@@ -14,7 +14,7 @@ import {
   BUILDER_HANDOFF_STATUSES,
   type BuilderHandoff,
 } from '#artifacts/builder-handoff/schema.ts';
-import { AGENTS } from '#config/schema.ts';
+import { AGENTS, type MaestroConfig } from '#config/schema.ts';
 import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
 import { refreshMaestroStatus } from '#maestro/status/refreshMaestroStatus.ts';
 import type { MaestroPaths } from '#MaestroPaths.ts';
@@ -26,7 +26,8 @@ import { resolveToolRunContext } from '#tools/utils/resolveToolRunContext.ts';
 import { prepareBuilderRun } from '#workflow/builder/prepareBuilderRun.ts';
 import { WORKFLOW_ROLES } from '#workflow/roles.ts';
 import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
-import { WORKFLOW_PHASES } from '#workflow/state/schema.ts';
+import { WORKFLOW_PHASES, WORKFLOW_EVENTS, type WorkflowState } from '#workflow/state/schema.ts';
+import { transitionWorkflow } from '#workflow/transitions.ts';
 
 export const RUN_BUILDER_TOOL = {
   NAME: 'maestro_run_builder',
@@ -48,7 +49,10 @@ type BuilderRunResult =
   | {
       outcome: typeof BUILDER_HANDOFF_STATUSES.DONE;
       specId: string;
-      phase: typeof WORKFLOW_PHASES.READY_FOR_VERIFIER;
+      phase:
+        | typeof WORKFLOW_PHASES.READY_FOR_VERIFIER
+        | typeof WORKFLOW_PHASES.SIMPLIFIER_RUNNING
+        | typeof WORKFLOW_PHASES.CANDIDATE_READY;
       handoff: BuilderHandoff;
     }
   | {
@@ -59,11 +63,15 @@ type BuilderRunResult =
     };
 
 type ReadBuilderResultInput = {
+  config: MaestroConfig;
+  builderRunningState: WorkflowState;
   paths: MaestroPaths;
   specId: string;
 };
 
 const readBuilderResult = async ({
+  config,
+  builderRunningState,
   paths,
   specId,
 }: ReadBuilderResultInput): Promise<BuilderRunResult> => {
@@ -74,20 +82,32 @@ const readBuilderResult = async ({
       throw new Error(`Workflow spec ID mismatch: expected "${specId}", found "${state.specId}".`);
     }
 
+    const donePhase = transitionWorkflow({
+      state: builderRunningState,
+      event: WORKFLOW_EVENTS.BUILDER_DONE,
+      config,
+    }).phase;
+
     if (
       state.phase !== WORKFLOW_PHASES.READY_FOR_VERIFIER &&
+      state.phase !== WORKFLOW_PHASES.SIMPLIFIER_RUNNING &&
+      state.phase !== WORKFLOW_PHASES.CANDIDATE_READY &&
       state.phase !== WORKFLOW_PHASES.ESCALATION_DECISIONS
     ) {
       throw new Error(`Builder returned with unexpected workflow phase "${state.phase}".`);
     }
 
+    if (state.phase !== WORKFLOW_PHASES.ESCALATION_DECISIONS && state.phase !== donePhase) {
+      throw new Error(`Builder returned with unexpected workflow phase "${state.phase}".`);
+    }
+
     const handoff = await readBuilderHandoff({
       path: await paths.getActiveBuilderHandoffPath(specId),
       specId,
     });
 
     const expectedStatus =
-      state.phase === WORKFLOW_PHASES.READY_FOR_VERIFIER
+      state.phase !== WORKFLOW_PHASES.ESCALATION_DECISIONS
         ? BUILDER_HANDOFF_STATUSES.DONE
         : BUILDER_HANDOFF_STATUSES.ESCALATION;
 
@@ -95,7 +115,7 @@ const readBuilderResult = async ({
       throw new Error(`Builder handoff status does not match workflow phase "${state.phase}".`);
     }
 
-    if (state.phase === WORKFLOW_PHASES.READY_FOR_VERIFIER) {
+    if (state.phase !== WORKFLOW_PHASES.ESCALATION_DECISIONS) {
       return {
         outcome: BUILDER_HANDOFF_STATUSES.DONE,
         specId,
@@ -122,11 +142,19 @@ const readBuilderResult = async ({
 };
 
 const formatBuilderResult = (result: BuilderRunResult): string => {
-  if (result.outcome === BUILDER_HANDOFF_STATUSES.DONE) {
-    return `Builder completed spec ${result.specId}. The workflow is ready-for-verifier.`;
+  if (result.outcome !== BUILDER_HANDOFF_STATUSES.DONE) {
+    return `Builder submitted escalation questions for spec ${result.specId}. The workflow is waiting for an owner decision.`;
+  }
+
+  if (result.phase === WORKFLOW_PHASES.CANDIDATE_READY) {
+    return `Builder completed spec ${result.specId}. The workflow is candidate-ready. Verifier and simplifier skipped by configuration. No independent verification was performed.`;
+  }
+
+  if (result.phase === WORKFLOW_PHASES.SIMPLIFIER_RUNNING) {
+    return `Builder completed spec ${result.specId}. The workflow is simplifier-running. Verifier skipped by configuration. Call maestro_run_simplifier next.`;
   }
 
-  return `Builder submitted escalation questions for spec ${result.specId}. The workflow is waiting for an owner decision.`;
+  return `Builder completed spec ${result.specId}. The workflow is ${result.phase}.`;
 };
 
 export const registerRunBuilderTool = (pi: ExtensionAPI): void => {
@@ -138,7 +166,12 @@ export const registerRunBuilderTool = (pi: ExtensionAPI): void => {
     async execute(toolCallId, { specId }, _signal, _onUpdate, context) {
       const { paths, config } = await resolveToolRunContext(context.cwd);
 
-      const run = await prepareBuilderRun({ paths, specId });
+      const { projectRoot, state: builderRunningState } = await prepareBuilderRun({
+        config,
+        paths,
+        specId,
+      });
+
       await refreshMaestroStatus(context);
 
       const request: SubagentDelegationRequest = {
@@ -148,9 +181,9 @@ export const registerRunBuilderTool = (pi: ExtensionAPI): void => {
         // pi-subagents loads this name from agents/builder.md through package.json.
         // See docs/subagent-integration.md.
         agent: AGENTS.BUILDER,
-        task: `Implement specId "${specId}" in the project directory "${run.projectRoot}".`,
+        task: `Implement specId "${specId}" in the project directory "${projectRoot}".`,
         context: 'fresh',
-        cwd: run.projectRoot,
+        cwd: projectRoot,
         model: config.builder.model,
         thinking: config.builder.thinking,
         timeoutMs: config.builder.timeoutMinutes * MILLISECONDS_PER_MINUTE,
@@ -163,7 +196,7 @@ export const registerRunBuilderTool = (pi: ExtensionAPI): void => {
       });
 
       assertDelegationResponse(response);
-      const result = await readBuilderResult({ paths, specId });
+      const result = await readBuilderResult({ paths, specId, config, builderRunningState });
 
       return {
         content: [{ type: 'text', text: formatBuilderResult(result) }],

package/src/tools/main/run-simplifier.ts

@@ -118,6 +118,7 @@ export const registerRunSimplifierTool = (pi: ExtensionAPI): void => {
 
       if (!(await isGitReady({ pi, projectRoot }))) {
         const nextState = transitionWorkflow({
+          config,
           state,
           event: WORKFLOW_EVENTS.SIMPLIFIER_SKIPPED,
         });

package/src/tools/main/run-verifier.ts

@@ -11,7 +11,7 @@ import { Type } from 'typebox';
 
 import { readVerifierHandoff } from '#artifacts/verifier-handoff/readVerifierHandoff.ts';
 import type { VerifierHandoff } from '#artifacts/verifier-handoff/schema.ts';
-import { AGENTS } from '#config/schema.ts';
+import { AGENTS, type MaestroConfig } from '#config/schema.ts';
 import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
 import { refreshMaestroStatus } from '#maestro/status/refreshMaestroStatus.ts';
 import type { MaestroPaths } from '#MaestroPaths.ts';
@@ -22,7 +22,8 @@ import {
 import { resolveToolRunContext } from '#tools/utils/resolveToolRunContext.ts';
 import { WORKFLOW_ROLES } from '#workflow/roles.ts';
 import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
-import { WORKFLOW_PHASES } from '#workflow/state/schema.ts';
+import { WORKFLOW_PHASES, WORKFLOW_EVENTS, type WorkflowState } from '#workflow/state/schema.ts';
+import { transitionWorkflow } from '#workflow/transitions.ts';
 import { prepareVerifierRun } from '#workflow/verifier/prepareVerifierRun.ts';
 
 export const RUN_VERIFIER_TOOL = {
@@ -42,6 +43,7 @@ const RunVerifierToolParameters = Type.Object(
 const MILLISECONDS_PER_MINUTE = 60_000;
 
 type VerifierTerminalPhase =
+  | typeof WORKFLOW_PHASES.CANDIDATE_READY
   | typeof WORKFLOW_PHASES.SIMPLIFIER_RUNNING
   | typeof WORKFLOW_PHASES.FINDING_DECISIONS;
 
@@ -53,11 +55,15 @@ type VerifierRunResult = {
 };
 
 type ReadVerifierResultInput = {
+  config: MaestroConfig;
+  runningState: WorkflowState;
   paths: MaestroPaths;
   specId: string;
 };
 
 const readVerifierResult = async ({
+  config,
+  runningState,
   paths,
   specId,
 }: ReadVerifierResultInput): Promise<VerifierRunResult> => {
@@ -74,6 +80,7 @@ const readVerifierResult = async ({
 
     if (
       state.phase !== WORKFLOW_PHASES.SIMPLIFIER_RUNNING &&
+      state.phase !== WORKFLOW_PHASES.CANDIDATE_READY &&
       state.phase !== WORKFLOW_PHASES.FINDING_DECISIONS
     ) {
       throw new Error(`Verifier returned with unexpected workflow phase "${state.phase}".`);
@@ -87,7 +94,8 @@ const readVerifierResult = async ({
     const expectedPhase =
       handoff.findings.length > 0
         ? WORKFLOW_PHASES.FINDING_DECISIONS
-        : WORKFLOW_PHASES.SIMPLIFIER_RUNNING;
+        : transitionWorkflow({ state: runningState, event: WORKFLOW_EVENTS.VERIFIER_DONE, config })
+            .phase;
 
     if (state.phase !== expectedPhase) {
       throw new Error(`Verifier handoff findings do not match workflow phase "${state.phase}".`);
@@ -107,6 +115,10 @@ const readVerifierResult = async ({
 };
 
 const formatVerifierResult = (result: VerifierRunResult): string => {
+  if (result.outcome === WORKFLOW_PHASES.CANDIDATE_READY) {
+    return `Verifier completed spec ${result.specId}. The workflow is candidate-ready. Simplifier skipped by configuration.`;
+  }
+
   if (result.outcome === WORKFLOW_PHASES.SIMPLIFIER_RUNNING) {
     return `Verifier completed spec ${result.specId}. The workflow is simplifier-running. Call maestro_run_simplifier next with this specId, without another approval or verifier pass.`;
   }
@@ -123,7 +135,7 @@ export const registerRunVerifierTool = (pi: ExtensionAPI): void => {
     async execute(toolCallId, { specId }, _signal, _onUpdate, context) {
       const { paths, config } = await resolveToolRunContext(context.cwd);
 
-      const run = await prepareVerifierRun({ paths, specId });
+      const run = await prepareVerifierRun({ config, paths, specId });
       await refreshMaestroStatus(context);
 
       const request: SubagentDelegationRequest = {
@@ -147,7 +159,7 @@ export const registerRunVerifierTool = (pi: ExtensionAPI): void => {
       });
 
       assertDelegationResponse(response);
-      const result = await readVerifierResult({ paths, specId });
+      const result = await readVerifierResult({ paths, specId, config, runningState: run.state });
 
       return {
         content: [{ type: 'text', text: formatVerifierResult(result) }],

package/src/workflow/builder/completeBuilderPass.ts

@@ -15,6 +15,7 @@ import {
   BuilderHandoffSubmissionSchema,
 } from '#artifacts/builder-handoff/schema.ts';
 import { writeBuilderHandoff } from '#artifacts/builder-handoff/writeBuilderHandoff.ts';
+import type { MaestroConfig } from '#config/schema.ts';
 import type { MaestroPaths } from '#MaestroPaths.ts';
 import { getWorkflowEventByBuilderHandoff } from '#workflow/builder/utils/getWorkflowEventByBuilderHandoff.ts';
 import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
@@ -39,12 +40,14 @@ function assertBuilderHandoffSubmission(
 }
 
 type CompleteBuilderPassInput = {
+  config: MaestroConfig;
   paths: MaestroPaths;
   specId: string;
   handoff: BuilderHandoffSubmissionInput;
 };
 
 export const completeBuilderPass = async ({
+  config,
   paths,
   specId,
   handoff: draftHandoff,
@@ -84,6 +87,7 @@ export const completeBuilderPass = async ({
   });
 
   const nextState = transitionWorkflow({
+    config,
     state: currentState,
     event: getWorkflowEventByBuilderHandoff(handoff),
   });