@emiliosp/pi-maestro 0.16.0 → 0.18.0

package/TECH_STACK.md

@@ -7,8 +7,7 @@
 | ------------------------------ | ------------------------------------------------------------------------------------------------- |
 | TypeScript                     | Application code and static type checks with `tsc --noEmit`.                                      |
 | Node.js                        | Runtime.                                                                                          |
-| Pi                             | Extension host, agent APIs, and terminal interface.                                               |
-| `pi-subagents`                 | `Builder`, `verifier`, and `simplifier` execution and activity tracking.                          |
+| Pi                             | Extension host, SDK child sessions, native session persistence, and terminal interface.           |
 | TypeBox                        | Schemas and runtime validation for configuration, workflow state, tool inputs, and agent reports. |
 | Vitest with coverage           | Unit tests, integration tests, and code coverage.                                                 |
 | Oxfmt                          | Formatting                                                                                        |

package/agents/builder.md

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

package/agents/simplifier.md

@@ -1,14 +1,3 @@
----
-name: simplifier
-package: maestro
-description: Refactors accepted Maestro code for clarity without changing behavior.
-systemPromptMode: replace
-inheritProjectContext: true
-inheritGlobalContext: true
-inheritSkills: true
-subagentOnlyExtensions: ../extensions/maestro-subagent.ts
----
-
 # Simplifier
 
 Refactor accepted code for clarity. Work only in the canonical project directory supplied by Maestro. Communicate with Maestro, never directly with the owner. Do not

package/agents/verifier.md

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

package/docs/configuration.md

@@ -52,7 +52,7 @@ For example, if Pi starts in `/work/app/src`, `Maestro` reads `/work/app/src/.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`.
+slashes. `Maestro` does not apply a separate format rule; it matches the complete identifier against Pi's available models and uses it unchanged for SDK execution.
 
 `Maestro` accepts these thinking levels:
 
@@ -97,8 +97,8 @@ used for implementation in another workflow. With `builder` enabled, `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.
+Disabled phases do not require 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
 
@@ -117,12 +117,11 @@ For example, `specDirectory: "planning/specs"` places `specs` in `<project-root>
 
 ## Model access
 
-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.
+During activation, `Maestro` checks the configured models for enabled agents against Pi's available model registry. 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.
+With `builder` disabled, activation checks only project trust and configuration, without a model lookup.
 
-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).
+The `owner` can correct the identifier or authenticate the provider in Pi, then retry `/maestro`. Authentication or provider errors during execution still appear as `run`
+failures. Agent context are described in [Subagent integration](subagent-integration.md#roles-and-context).

package/docs/glossary.md

@@ -6,13 +6,15 @@
 | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `Owner`                       | The person who approves the `spec`, decides questions and `findings`, and performs the final review.                                                                                                                                  |
 | `Maestro`                     | The coordinator that prepares the `spec`, runs the agents, and records `owner` decisions.                                                                                                                                             |
-| `Builder`                     | The agent that implements the approved `spec` and runs its `probes`.                                                                                                                                                                  |
+| `Builder`                     | The agent that implements the approved `spec` and runs every `GIVEN`, `WHEN`, and `THEN` scenario.                                                                                                                                    |
 | `Verifier`                    | The independent agent that checks the implementation and reports technical issues.                                                                                                                                                    |
 | `Simplifier`                  | The agent that refactors accepted code for clarity without changing behavior or introducing check failures.                                                                                                                           |
 | `Spec`                        | A `specification` for one change: `proposal.md` for motivation and scope, `spec.md` for behavior and `acceptance criteria`, and optional `design.md` for technical decisions. The present documents are approved and frozen together. |
 | `Acceptance criterion` (`AC`) | One required, observable result defined in the `spec`.                                                                                                                                                                                |
-| `Probe`                       | A scenario used to test an `acceptance criterion`. Reports record the actual command or procedure and its outcome.                                                                                                                    |
-| `Expected result`             | The observable result that a `probe` must produce.                                                                                                                                                                                    |
+| `GIVEN`                       | The starting conditions of an `acceptance criterion`.                                                                                                                                                                                 |
+| `WHEN`                        | The action or observation that checks the behavior of an `acceptance criterion`.                                                                                                                                                      |
+| `THEN`                        | The measurable outcome the `WHEN` must produce.                                                                                                                                                                                       |
+| `Assumption`                  | A detail the request did not specify or a scope boundary taken as given. A false `assumption` during implementation is an `escalation` trigger.                                                                                       |
 | `Artifact`                    | A saved workflow file, such as a `spec`, or a `handoff` between agents.                                                                                                                                                               |
 | `Handoff`                     | A saved agent report. `Builder` and `verifier` reports include `probe` outcomes. A `simplifier` report includes refactored files, a summary, and notes.                                                                               |
 | `Observability`               | The owner's ability to inspect workflow progress and reported results.                                                                                                                                                                |

package/docs/subagent-integration.md

@@ -1,45 +1,46 @@
 # Subagent integration
 
-`Maestro` uses `pi-subagents` to run the `builder`, `verifier`, and `simplifier` as child sessions. A child session is a separate Pi session for one role. The `owner`
-stays in the main `Maestro` conversation.
+`Maestro` runs the `builder`, `verifier`, and `simplifier` through Pi's SDK. Each child session handles one role while the `owner` stays in the main `Maestro`
+conversation.
 
 ## Roles and context
 
-The package supplies all three roles and the tools that save their results:
+The package supplies the three roles:
 
-| Role         | Agent name           | Definition                                        |
-| ------------ | -------------------- | ------------------------------------------------- |
-| `Builder`    | `maestro.builder`    | [`agents/builder.md`](../agents/builder.md)       |
-| `Verifier`   | `maestro.verifier`   | [`agents/verifier.md`](../agents/verifier.md)     |
-| `Simplifier` | `maestro.simplifier` | [`agents/simplifier.md`](../agents/simplifier.md) |
+| Role         | Instructions                                      |
+| ------------ | ------------------------------------------------- |
+| `Builder`    | [`agents/builder.md`](../agents/builder.md)       |
+| `Verifier`   | [`agents/verifier.md`](../agents/verifier.md)     |
+| `Simplifier` | [`agents/simplifier.md`](../agents/simplifier.md) |
 
-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`.
+Each `run` starts a fresh conversation, without the main session's history or automatic resumption of earlier child sessions. The bundled role instructions supplement
+Pi's normal instructions. Global and project instructions, including `AGENTS.md`, and available skills are discovered through Pi. Models and thinking levels come from
+[Maestro configuration](configuration.md).
 
-`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.
+Enabled global and project extensions load in child sessions. Native Pi tools and configured MCP, codemode, and tool search support are available.
 
-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).
+The `owner` approves the `spec` and selected phases through the main conversation. See [Phase selection](configuration.md#phase-selection).
 
 ## Following a run
 
-`Runs` stay in the foreground and occur one at a time. Pi waits for each `run` to finish before `Maestro` continues. `Maestro` does not run agents in parallel or in the
-background.
+`Runs` stay in the foreground and occur one at a time. Pi waits for each `run` to finish before `Maestro` continues. Maestro's Pi status shows the workflow phase.
 
-Maestro's Pi status shows the workflow phase. `pi-subagents` FleetView shows agent activity, and `/subagents-fleet` opens its inspector for details and transcripts.
+Saved `handoffs` contain the structured results. See [Stored artifacts](workflow.md#stored-artifacts) for further details.
 
-Each child saves its result through `Maestro` tools before returning. `Builder` results produce `B1.json`, `B2.json`, and so on. `Verifier` results produce `V1.json`,
-`V2.json`, and so on. The `simplifier` saves the unnumbered `handoffs/simplifier/S.json`. See [Stored artifacts](workflow.md#stored-artifacts) for the creation sequence.
+## Cancellation and errors
 
-If a `run` fails or returns without a valid saved result, `Maestro` reports the error and stops. Manual follow-up is described in [Limitations](workflow.md#limitations).
+The `owner` can interrupt a running agent with Pi's cancel action (`Escape` by default). `Maestro` forwards cancellation to the child and waits for cleanup.
 
-## External configuration
+Execution errors, interruptions, and missing or invalid `handoffs` stop the workflow. Completed file changes remain.
 
-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.
+## Inspecting saved sessions
 
-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.
+When a native child session file exists, `Maestro` displays its exact path on completion or failure, including interruptions and invalid `handoffs`. No path is displayed
+when execution fails before a session file is saved.
+
+Child session files live under `subagents/` in Pi's project session directory, outside the project repository. The `owner` can read the displayed JSONL file directly or
+export it with Pi:
+
+```bash
+pi --export /sessions/weather/subagents/child.jsonl conversation.html
+```

package/docs/workflow.md

@@ -5,7 +5,8 @@
 The approved `spec` is one document set: `proposal.md` explains motivation and scope, `spec.md` defines behavior and `acceptance criteria`, and optional `design.md`
 records significant technical decisions. The set forms one contract for the change.
 
-An `acceptance criterion` contains a `probe`, an `expected result`, and an example. A `probe` is a scenario used to test behavior.
+An `acceptance criterion` contains one `GIVEN`, one `WHEN`, one `THEN`, and an example. `GIVEN` and `WHEN` describe the scenario, and `THEN` states the measurable
+outcome.
 
 A `handoff` is a saved agent report. `Builder` and `verifier` reports contain `probe` outcomes. The simplifier's report records refactored files, a summary, and notes.
 
@@ -14,13 +15,13 @@ issues.
 
 ## Roles
 
-| Role         | Responsibility                                                                                                                                      |
-| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Owner`      | Decides requirements, scope, technical decisions, `spec` approval, `escalation` answers, and `finding` decisions. Performs the final review.        |
-| `Maestro`    | Prepares the `spec` with the `owner`, records workflow progress, runs agents, presents issues, and saves `owner` decisions.                         |
-| `Builder`    | Implements the approved `spec` and runs every `probe`. Reports completion or an `escalation`, including technical problems that prevent completion. |
-| `Verifier`   | Independently runs every `probe` against the live project files. Reports `findings` without repairing product code.                                 |
-| `Simplifier` | Refactors accepted code for clarity without changing behavior or introducing check failures.                                                        |
+| Role         | Responsibility                                                                                                                                                                   |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Owner`      | Decides requirements, scope, technical decisions, `spec` approval, `escalation` answers, and `finding` decisions. Performs the final review.                                     |
+| `Maestro`    | Prepares the `spec` with the `owner`, records workflow progress, runs agents, presents issues, and saves `owner` decisions.                                                      |
+| `Builder`    | Implements the approved `spec` and runs every `GIVEN`, `WHEN`, and `THEN` scenario. Reports completion or an `escalation`, including technical problems that prevent completion. |
+| `Verifier`   | Independently runs every `GIVEN`, `WHEN`, and `THEN` scenario against the live project files. Reports `findings` without repairing product code.                                 |
+| `Simplifier` | Refactors accepted code for clarity without changing behavior or introducing check failures.                                                                                     |
 
 `Builder`, `verifier`, and `simplifier` `runs` are sequential foreground operations. Each starts with a fresh conversation and reads the `spec` and saved `artifacts`.
 
@@ -30,7 +31,8 @@ issues.
 
 Maestro's Pi status shows the current phase.
 
-`pi-subagents` FleetView and `/subagents-fleet` show live agent activity and transcripts.
+`Maestro` displays the saved native child session path when one exists, including after a failed or interrupted `run`. The `owner` can inspect the file or export it with
+Pi. See [Inspecting saved sessions](subagent-integration.md#inspecting-saved-sessions).
 
 Saved `handoffs` provide a structured account of each reported `run`. The `builder` reports its outcome, `probe` results, notes, and any `escalation` questions. The
 `verifier` reports its independent checks, results, and `findings`. The `simplifier` reports its refactoring separately. Recorded `owner` decisions explain how questions
@@ -107,18 +109,18 @@ The default path is `.specs/<spec-id>/workflow.json`. The `spec` directory is [c
 
 Each new `spec` uses these documents in the same directory:
 
-| Document      | Content                                                                                           | Presence                                                       |
-| ------------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
-| `proposal.md` | Problem, goal, scope, and exclusions.                                                             | Always created.                                                |
-| `spec.md`     | Required behavior, constraints, deltas, and `acceptance criteria` next to their requirements.     | Always created.                                                |
-| `design.md`   | Approved technical decisions, brief reasons, relevant contracts, risks, and prototype references. | Only when significant technical decisions need to be recorded. |
+| Document      | Content                                                                                                      | Presence                                                       |
+| ------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
+| `proposal.md` | Problem, goal, scope, and exclusions.                                                                        | Always created.                                                |
+| `spec.md`     | Required behavior, constraints, deltas, `acceptance criteria` next to their requirements, and `assumptions`. | Always created.                                                |
+| `design.md`   | Approved technical decisions, brief reasons, relevant contracts, risks, and prototype references.            | Only when significant technical decisions need to be recorded. |
 
 ## Spec approval
 
 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.
+2. The `owner` reviews the complete document set: motivation, scope, requirements, `acceptance criteria`, `assumptions`, 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 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.
@@ -152,24 +154,23 @@ continuous across the whole document, including standalone regression criteria,
 For example, a change that introduces persistent item titles can describe its requirement and linked `acceptance criterion` in `spec.md` as follows:
 
 ```markdown
-### REQ1: Persist saved titles
+### REQ1: The system MUST persist saved titles
 
 Delta: added
 
-Saving and reopening an item must preserve its title.
-
 Verified by: [AC1](#ac1-saved-title-is-persisted)
 
 #### AC1: Saved title is persisted
 
-1. Probe: Save a change to an item's title, then reopen the item.
-2. Expected result: The saved title is still present.
-3. Example: Change the title from "Draft" to "Ready", save, and reopen the item. The title is "Ready".
+- GIVEN a saved item.
+- WHEN its title is changed and saved, then the item is reopened.
+- THEN the saved title is present.
+- Example: Change the title from "Draft" to "Ready", save, and reopen the item. The title is "Ready".
 ```
 
 A requirement can link to several `acceptance criteria`, and one criterion can verify several requirements (1:N). When an existing test covers the exact starting
-conditions, action, and `expected result`, `Verified by` links to the test file relative to `spec.md` and includes the exact scenario name. No duplicate criterion is
-needed. A requirement can reference both criteria and existing tests.
+conditions, action, and outcome, `Verified by` links to the test file relative to `spec.md` and includes the exact scenario name. No duplicate criterion is needed. A
+requirement can reference both criteria and existing tests.
 
 Before approval, `Maestro` follows the links and checks that their combined scenarios verify the whole requirement. Missing, partial, or uncertain coverage must be
 resolved with an appropriate criterion or a confirmed existing test. References are updated when criterion headings or test locations change, including during `spec`
@@ -190,19 +191,27 @@ For example, if saving item descriptions already works, adding title persistence
 
 ### AC2: Existing descriptions remain saved
 
-1. Probe: Change and save the title of an item with a saved description, then reopen it.
-2. Expected result: The description is unchanged.
-3. Example: An item's saved description is "Buy milk". Change its title from "Draft" to "Shopping", save, and reopen it. Its description is still "Buy milk".
+- GIVEN an item with a saved description.
+- WHEN its title is changed and saved, then the item is reopened.
+- THEN the description is unchanged.
+- Example: An item's saved description is "Buy milk". Change its title from "Draft" to "Shopping", save, and reopen it. Its description is still "Buy milk".
 ```
 
 Both nested and standalone criteria share one continuous AC sequence and are checked by the `builder` and `verifier`. Standalone criteria have the same fields as
 requirement-associated criteria:
 
-| Part              | Content                                                                            |
-| ----------------- | ---------------------------------------------------------------------------------- |
-| `Probe`           | Starting conditions and the action or observation that checks the behavior.        |
-| `Expected result` | The measurable result the `probe` observes.                                        |
-| Example           | Concrete starting conditions, an input or action, and the exact `expected result`. |
+| Part      | Content                                                                  |
+| --------- | ------------------------------------------------------------------------ |
+| `GIVEN`   | Starting conditions.                                                     |
+| `WHEN`    | The action or observation that checks the behavior.                      |
+| `THEN`    | The measurable outcome the `WHEN` must produce.                          |
+| `Example` | Concrete starting conditions, an input or action, and the exact outcome. |
+
+## Assumptions
+
+An `assumption` records a detail the request did not specify or a scope boundary taken as given. `Maestro` writes short `assumptions` in a `## Assumptions` section of
+`spec.md` as a bullet list, without paragraphs. The section is omitted when there are none. An `assumption` that proves false during implementation is an `escalation`
+trigger.
 
 ## Escalations
 
@@ -262,8 +271,8 @@ The revised `spec` controls subsequent work. Earlier `escalations`, `findings`,
 
 ## Verification boundary
 
-The `verifier` can make temporary changes for `probes`. Before submitting its `handoff`, it restores the exact original contents of affected files and removes only files
-it created.
+The `verifier` can make temporary changes to run its checks. Before submitting its `handoff`, it restores the exact original contents of affected files and removes only
+files it created.
 
 Cleanup relies on the `verifier`. If cleanup cannot finish safely, the `verifier` stops and reports the remaining changes.
 
@@ -351,9 +360,12 @@ these project-specific checks.
 
 ### No automatic rollback
 
-Launch errors, delegation failures, timeouts, interruptions, cancellations, and missing or invalid `handoffs` stop the workflow without a recovery transition. If a `run`
-saves no completed transition, its saved running phase remains unchanged. Partial protocol writes require manual `owner` follow-up. `Maestro` provides no automatic
-rollback, repair, or recovery for these errors. The files that remain are available for `owner` inspection.
+The `owner` can stop a running agent through Pi's cancel action (`Escape` by default). There is no automatic `Maestro` execution deadline. Cancellation does not request a
+final agent turn or create a synthetic `handoff`.
+
+Launch errors, execution failures, interruptions, cancellations, and missing or invalid `handoffs` stop the workflow without a recovery transition. If a `run` saves no
+completed transition, its saved running phase remains unchanged. Partial protocol writes require manual `owner` follow-up. `Maestro` provides no automatic rollback,
+repair, or recovery for these errors. The files that remain are available for `owner` inspection.
 
 ### No reconciliation
 

package/extensions/maestro.ts

@@ -85,7 +85,7 @@ export default (pi: ExtensionAPI): void => {
       }
 
       try {
-        await assertEnvironment({ context, piEventsBus: pi.events });
+        await assertEnvironment({ context });
         const config = await loadConfiguration(context.cwd);
         const isImplementationEnabled = config.builder.required;
 

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@emiliosp/pi-maestro",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "A spec-driven multiagent development workflow for Pi.",
   "keywords": [
     "orchestration",
     "pi",
     "pi-coding-agent",
     "pi-package",
+    "sdd",
     "subagents",
     "workflow"
   ],
@@ -62,43 +63,34 @@
     "fmt": "oxfmt",
     "lint": "oxlint --fix"
   },
-  "dependencies": {
-    "pi-subagents": "0.78.0"
-  },
   "devDependencies": {
     "@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",
+    "@vitest/coverage-v8": "5.0.5",
     "oxfmt": "0.73.0",
     "oxlint": "1.87.0",
     "oxlint-anti-slop": "0.3.8",
     "typebox": "1.3.35",
     "typescript": "7.0.2",
-    "vitest": "5.0.3"
+    "vitest": "5.0.5"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "typebox": "*"
   },
-  "bundleDependencies": [
-    "pi-subagents"
-  ],
   "engines": {
     "node": ">=26.0.0"
   },
   "allowScripts": {
-    "fsevents@2.3.3": true
+    "fsevents@2.3.3": true,
+    "@google/genai": false,
+    "protobufjs": false
   },
   "pi": {
     "extensions": [
       "./extensions/maestro.ts"
-    ],
-    "subagents": {
-      "agents": [
-        "./agents"
-      ]
-    }
+    ]
   }
 }

package/src/config/schema.ts

@@ -5,12 +5,6 @@
 
 import { type Static, Type } from 'typebox';
 
-export const AGENTS = {
-  BUILDER: 'maestro.builder',
-  VERIFIER: 'maestro.verifier',
-  SIMPLIFIER: 'maestro.simplifier',
-} as const;
-
 export const THINKING_LEVELS = {
   OFF: 'off',
   MINIMAL: 'minimal',