@emiliosp/pi-maestro 0.11.0 → 0.12.0

package/docs/workflow.md

@@ -2,19 +2,20 @@
 
 `Maestro` manages one spec-driven workflow in the current Pi session. The `owner` works directly with `Maestro`.
 
-The approved `spec.md` defines behavior, scope, constraints, technical decisions, and `acceptance criteria` for the change.
+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 coverage label, a `probe`, an `expected result`, and an example. A `probe` is a scenario used to test behavior.
+An `acceptance criterion` contains a `probe`, an `expected result`, and an example. A `probe` is a scenario used to test behavior.
 
 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.
 
-A `builder` `handoff` can contain `escalations`, which are questions that need `owner` decisions.
-A `verifier` `handoff` can contain `findings`, which are technical issues.
+A `builder` `handoff` can contain `escalations`, which are questions that need `owner` decisions. A `verifier` `handoff` can contain `findings`, which are technical
+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. |
@@ -31,11 +32,9 @@ Maestro's Pi status shows the current phase.
 
 `pi-subagents` FleetView and `/subagents-fleet` show live agent activity and transcripts.
 
-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 and issues were resolved. Earlier numbered reports remain available for inspection.
+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
+and issues were resolved. Earlier numbered reports remain available for inspection.
 
 For example, the `owner` can read `B1.json` to see what the `builder` reports implementing and which `probes` it ran. `V1.json` shows what the `verifier` reports checking
 independently and which issues it found.
@@ -52,7 +51,7 @@ flowchart TD
     buildOutcome{Builder outcome}
     verify[Verifier checks live project files]
     findings{Findings?}
-    simplify[Simplifier refactors accepted code or skips if Git is unavailable]
+    simplify[Simplifier refactors accepted code]
     candidate[Candidate ready]
     summary[Maestro summarizes results]
     review[Owner performs the final review]
@@ -86,7 +85,7 @@ 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.                                                                                                   |
@@ -97,48 +96,124 @@ The default path is `.specs/<spec-id>/workflow.json`. The `spec` directory is [c
 | `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.                                                                            |
 
+## Specification documents
+
+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. |
+
 ## Spec approval
 
 For the initial `spec`:
 
-1. `Maestro` creates `spec.md` and `workflow.json` in `drafting-spec` and prepares the `spec` with the `owner`.
-2. The `owner` reviews the requirements, scope, technical decisions, and `acceptance criteria`.
-3. `Maestro` asks the `owner` to inspect the current `spec.md` and reply `GREEN FLAG` to approve it and start the `builder`.
+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.
 
-Approval freezes the `spec`. The `spec` and its visual prototypes remain unchanged during `builder`, `verifier`, and `simplifier` execution.
-See [Spec revision](#spec-revision) for permitted revisions.
+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.
+
+## Requirement deltas
+
+Each requirement has exactly one `Delta` field. It describes the impact of the requirement against the current system's behavior.
+
+| Value      | Meaning                                                                   |
+| ---------- | ------------------------------------------------------------------------- |
+| `added`    | Introduces behavior or a constraint that did not exist before the change. |
+| `modified` | Changes existing behavior or a constraint.                                |
+| `removed`  | Removes behavior that must no longer be available.                        |
+
+The `spec` describes only requirements added, modified, or removed by the change. Existing behavior must continue working unless explicitly changed or removed. Unchanged
+behavior is implicit, not an inventory of requirements to repeat in every `spec`.
+
+For `modified` or `removed` requirements, a short `Before` description is included only when it helps explain the change. For example,
+`Before: Tokens expire 30 minutes after issuance.`
+
+## Requirement coverage
+
+Each requirement has its own section and a unique, stable ID, such as `REQ1`. Its `Verified by` field links to the `acceptance criteria` or existing tests that verify it.
+The mapping appears only under the requirement, not again inside each `acceptance criterion`. Requirements use `### REQ<number>:` headings; their criteria immediately
+follow as `#### AC<number>:` subsections. Each requirement-associated AC is defined once under its primary requirement; other requirements can link to it. AC numbering is
+continuous across the whole document, including standalone regression criteria, not restarted for each requirement or section.
+
+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
+
+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".
+```
+
+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.
+
+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`
+revisions.
 
 ## Acceptance criteria
 
-Each `acceptance criterion` has a unique ID and describes one observable result.
+Each `acceptance criterion` has a unique ID and describes one observable result. A criterion can verify a changed requirement or check a relevant regression in existing
+behavior without an associated requirement.
+
+Standalone regression criteria belong in an optional `## Regression checks` section, with `### AC<number>:` headings. They do not need a `REQ` heading, `Delta`, or an
+artificial requirement association. Only regressions relevant to the change belong here; unchanged requirements are not listed. The section is omitted when unnecessary.
+
+For example, if saving item descriptions already works, adding title persistence may warrant this regression check without a new requirement for descriptions:
+
+```markdown
+## Regression checks
+
+### 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".
+```
 
-Each criterion contains these parts:
+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                                                                             |
-|-------------------|-------------------------------------------------------------------------------------|
-| Coverage          | One label that states the scenario's purpose: `success`, `failure`, or `unchanged`. |
-| `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                                                                            |
+| ----------------- | ---------------------------------------------------------------------------------- |
+| `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`. |
 
 ## Escalations
 
-An `escalation` returns an implementation decision or a technical problem to the `owner`.
-For instance a technical failure, an undefined behavior, a conflict with the `spec`, or a possible scope change.
+An `escalation` returns an implementation decision or a technical problem to the `owner`. For instance a technical failure, an undefined behavior, a conflict with the
+`spec`, or a possible scope change.
 
 The `builder` saves all questions from one `pass` in the `escalations` list of its numbered `handoff`. `Maestro` identifies each question with both report and
 `escalation` IDs, such as `B1/E1`. See [Escalation references](glossary.md#escalation-references) for their scope.
 
 `Maestro` presents each question, evidence, options, consequences, and next steps. The workflow pauses in `escalation-decisions` while the `owner` decides how to proceed.
 
-The `owner` gives `Maestro` an answer and reason for every current question, whether or not the `spec` must change.
-The `owner` can select a listed option or give a different decision.
+The `owner` gives `Maestro` an answer and reason for every current question, whether or not the `spec` must change. The `owner` can select a listed option or give a
+different decision.
 
 `Maestro` saves all answers in the current `builder` `handoff` before the workflow continues.
 
 | `Owner` choice          | Result                                                                                                                            |
-|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
 | Keep the current `spec` | `Maestro` starts another `builder` `run` without renewed approval.                                                                |
 | Change the `spec`       | The `owner` and `Maestro` revise the same `spec`. The `owner` reviews it and replies `GREEN FLAG` before another `builder` `run`. |
 
@@ -149,36 +224,34 @@ The `owner` can select a listed option or give a different decision.
 Every current `finding` requires an `owner` decision, regardless of severity. `Maestro` explains the issue, evidence, practical effect, and available choices.
 
 `Maestro` identifies each `finding` with its report and `finding` IDs. For example, `V1/F2` means `finding` 2 in `verifier` report `V1.json`. The `finding` is an entry in
-that file's `findings` list, not a separate `F2.json` file. `Finding` numbers restart at `F1` in each `verifier` report.
-See [Finding references](glossary.md#finding-references) for a worked example.
+that file's `findings` list, not a separate `F2.json` file. `Finding` numbers restart at `F1` in each `verifier` report. See
+[Finding references](glossary.md#finding-references) for a worked example.
 
 `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`.                     |
 
-`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).
+`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).
 
-Without revision, any `fix-code` decision requires another `builder` `run`, including when other `findings` are rejected.
-After the `builder` completes the fixes, the `verifier` checks the work again.
+Without revision, any `fix-code` decision requires another `builder` `run`, including when other `findings` are rejected. After the `builder` completes the fixes, the
+`verifier` checks the work again.
 
 ## Spec revision
 
-For either `escalation` answers or `finding` decisions, `Maestro` records the complete batch before the workflow returns to `drafting-spec`.
-This decision does not approve the `spec` or start an agent.
-The `owner` and `Maestro` then revise the same `spec` together in `drafting-spec`.
+For either `escalation` answers or `finding` decisions, `Maestro` records the complete batch before the workflow returns to `drafting-spec`. This decision does not
+approve the `spec` or start an agent. The `owner` and `Maestro` then revise the same `spec` together in `drafting-spec`.
 
-The `owner` reviews the changes and replies `GREEN FLAG` again.
-`Maestro` records that renewed approval separately, moves to `ready-for-builder`, and starts another `builder` `run`.
-Approval is permitted only in `drafting-spec`, not directly from either decision phase.
+The `owner` reviews the complete revised set of `proposal.md`, `spec.md`, and `design.md` when present and replies `GREEN FLAG` once again. `Maestro` records that renewed
+approval separately, moves to `ready-for-builder`, and starts another `builder` `run`. Approval is permitted only in `drafting-spec`, not directly from either decision
+phase.
 
-The revised `spec` controls subsequent work.
-Earlier `escalations`, `findings`, and their decisions remain historical context.
+The revised `spec` controls subsequent work. Earlier `escalations`, `findings`, and their decisions remain historical context.
 
 ## Verification boundary
 
@@ -189,25 +262,23 @@ 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.`
+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.`
 
 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.
+check failures. If no code needs refactoring, the `simplifier` does not make any change.
 
 ## 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
+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
 
 The `owner` performs the final review and controls any later Git use, pull request, or merge. Changes after completion are outside the completed verification.
 
 ## Stored artifacts
 
-An `artifact` is a saved workflow file. `Maestro` creates the `spec` directory with `spec.md`, `workflow.json`, and an empty `prototypes/` directory. `Builder`,
-`verifier`, and `simplifier` `handoff` directories appear when those results are saved.
+An `artifact` is a saved workflow file. `Maestro` creates the `spec` directory with `proposal.md`, `spec.md`, `workflow.json`, and an empty `prototypes/` directory.
+`design.md` is created during drafting only when needed. `Builder`, `verifier`, and `simplifier` `handoff` directories appear when those results are saved.
 
 The agents submit results through `Maestro` tools instead of writing the reports directly. A successful submission saves the result and updates the phase in
 `workflow.json` before the agent returns.
@@ -220,7 +291,7 @@ outcome, including `escalation`, creates the next `B` report. Revising the same
 For example, a repair cycle with successful `builder` results produces these files:
 
 | Step | Action                                                                  | Report saved or updated                                                         |
-|------|-------------------------------------------------------------------------|---------------------------------------------------------------------------------|
+| ---- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
 | 1    | The `builder` completes the implementation.                             | Creates `handoffs/builder/B1.json`.                                             |
 | 2    | The `verifier` checks it and reports `findings`.                        | Creates `handoffs/verifier/V1.json`.                                            |
 | 3    | The `owner` decides every `finding` and requests a code fix.            | Updates decisions in the existing `V1.json`.                                    |
@@ -230,8 +301,8 @@ For example, a repair cycle with successful `builder` results produces these fil
 
 If the first `builder` `run` escalates, it creates `B1.json` with its questions. `Owner` answers update `B1.json`. The next saved `builder` result creates `B2.json`.
 
-A `builder` report has `status: done` or `status: escalation`. A `done` report requires every recorded `probe` to pass and an empty `escalations` list.
-An `escalation` retains actual `probe` results: `passed`, `failed`, or `not-run`.
+A `builder` report has `status: done` or `status: escalation`. A `done` report requires every recorded `probe` to pass and an empty `escalations` list. An `escalation`
+retains actual `probe` results: `passed`, `failed`, or `not-run`.
 
 Execution errors or missing or invalid saved results stop the workflow. See [Limitations](#limitations).
 
@@ -239,7 +310,9 @@ The default layout after multiple `runs` is:
 
 ```text
 .specs/<spec-id>/
+├── proposal.md
 ├── spec.md
+├── design.md             # only when needed
 ├── workflow.json
 ├── handoffs/
 │   ├── builder/
@@ -260,17 +333,17 @@ available as context, not as proof for the current `run`. `Owner` decisions upda
 
 ### No small models
 
-The `owner` must not use small models with a `low` thinking level for this workflow. These combinations cannot reliably follow the workflow rules.
-One example is `gpt-luna-6` with `thinking: "low"`.
+The `owner` must not use small models with a `low` thinking level for this workflow. These combinations cannot reliably follow the workflow rules. One example is
+`gpt-luna-6` with `thinking: "low"`.
 
 Moreover, the workflow works well with a defined harness: tests, lint for code rules, anti-slop checks for unwanted patterns, and `AGENTS.md`. `Maestro` does not supply
 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.
+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.
 
 ### No reconciliation
 

package/extensions/maestro-subagent.ts

@@ -4,6 +4,7 @@
  */
 
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+
 import { registerRecordBuilderHandoffTool } from '#tools/child/record-builder-handoff.ts';
 import { registerRecordSimplifierHandoffTool } from '#tools/child/record-simplifier-handoff.ts';
 import { registerRecordVerifierHandoffTool } from '#tools/child/record-verifier-handoff.ts';

package/extensions/maestro.ts

@@ -4,19 +4,14 @@
  */
 
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+
 import { loadConfiguration } from '#config/loadConfiguration.ts';
 import { assertEnvironment } from '#maestro/checks/assertEnvironment.ts';
 import { getMaestroInstructions } from '#maestro/instructions/getMaestroInstructions.ts';
 import maestroSessionState from '#maestro/session/MaestroSessionState.ts';
 import { refreshMaestroStatus } from '#maestro/status/refreshMaestroStatus.ts';
-import {
-  CREATE_SPEC_TOOL,
-  registerCreateSpecTool,
-} from '#tools/main/create-spec.ts';
-import {
-  MARK_SPEC_READY_TOOL,
-  registerMarkSpecReadyTool,
-} from '#tools/main/mark-spec-ready.ts';
+import { CREATE_SPEC_TOOL, registerCreateSpecTool } from '#tools/main/create-spec.ts';
+import { MARK_SPEC_READY_TOOL, registerMarkSpecReadyTool } from '#tools/main/mark-spec-ready.ts';
 import {
   RESOLVE_ESCALATIONS_TOOL,
   registerResolveEscalationsTool,
@@ -25,18 +20,9 @@ import {
   RESOLVE_FINDINGS_TOOL,
   registerResolveFindingsTool,
 } from '#tools/main/resolve-findings.ts';
-import {
-  RUN_BUILDER_TOOL,
-  registerRunBuilderTool,
-} from '#tools/main/run-builder.ts';
-import {
-  RUN_SIMPLIFIER_TOOL,
-  registerRunSimplifierTool,
-} from '#tools/main/run-simplifier.ts';
-import {
-  RUN_VERIFIER_TOOL,
-  registerRunVerifierTool,
-} from '#tools/main/run-verifier.ts';
+import { RUN_BUILDER_TOOL, registerRunBuilderTool } from '#tools/main/run-builder.ts';
+import { RUN_SIMPLIFIER_TOOL, registerRunSimplifierTool } from '#tools/main/run-simplifier.ts';
+import { RUN_VERIFIER_TOOL, registerRunVerifierTool } from '#tools/main/run-verifier.ts';
 
 const MAIN_TOOL_NAMES: readonly string[] = [
   CREATE_SPEC_TOOL.NAME,
@@ -58,14 +44,10 @@ export default (pi: ExtensionAPI): void => {
   registerRunSimplifierTool(pi);
 
   const syncMainTools = (): void => {
-    const foreignTools = pi
-      .getActiveTools()
-      .filter((name) => !MAIN_TOOL_NAMES.includes(name));
+    const foreignTools = pi.getActiveTools().filter((name) => !MAIN_TOOL_NAMES.includes(name));
 
     pi.setActiveTools(
-      maestroSessionState.isActive()
-        ? [...foreignTools, ...MAIN_TOOL_NAMES]
-        : foreignTools,
+      maestroSessionState.isActive() ? [...foreignTools, ...MAIN_TOOL_NAMES] : foreignTools,
     );
   };
 
@@ -118,10 +100,7 @@ export default (pi: ExtensionAPI): void => {
           'info',
         );
       } catch (error) {
-        context.ui.notify(
-          error instanceof Error ? error.message : String(error),
-          'error',
-        );
+        context.ui.notify(error instanceof Error ? error.message : String(error), 'error');
 
         return;
       }

package/package.json

@@ -1,30 +1,23 @@
 {
   "name": "@emiliosp/pi-maestro",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "A spec-driven multiagent development workflow for Pi.",
-  "license": "MIT",
-  "type": "module",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/emiliosp/pi-maestro.git"
-  },
-  "homepage": "https://github.com/emiliosp/pi-maestro#readme",
-  "bugs": {
-    "url": "https://github.com/emiliosp/pi-maestro/issues"
-  },
   "keywords": [
-    "pi-package",
+    "orchestration",
     "pi",
     "pi-coding-agent",
-    "workflow",
+    "pi-package",
     "subagents",
-    "orchestration"
-  ],
-  "os": [
-    "darwin"
+    "workflow"
   ],
-  "engines": {
-    "node": ">=26.0.0"
+  "homepage": "https://github.com/emiliosp/pi-maestro#readme",
+  "bugs": {
+    "url": "https://github.com/emiliosp/pi-maestro/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/emiliosp/pi-maestro.git"
   },
   "files": [
     "extensions/",
@@ -41,6 +34,10 @@
     "README.md",
     "LICENSE"
   ],
+  "os": [
+    "darwin"
+  ],
+  "type": "module",
   "imports": {
     "#config/*": "./src/config/*",
     "#specs/*": "./src/specs/*",
@@ -53,41 +50,46 @@
     "#ids/*": "./src/ids/*",
     "#*": "./*"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "vitest run --coverage --config vitest.config.ts",
-    "check": "npm run lint:fix && npm run typecheck && npm test",
+    "check": "npm run fmt && npm run lint && npm run typecheck && npm test",
     "prepublishOnly": "npm run check",
     "publish:npm": "npm publish --access public",
-    "lint": "biome check .",
-    "lint:anti-slop": "oxlint --fix",
-    "lint:fix": "biome check --write . && npm run lint:anti-slop"
+    "fmt": "oxfmt",
+    "lint": "oxlint --fix"
   },
   "dependencies": {
     "pi-subagents": "0.78.0"
   },
-  "bundleDependencies": [
-    "pi-subagents"
-  ],
-  "peerDependencies": {
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "typebox": "*"
-  },
   "devDependencies": {
-    "@biomejs/biome": "2.5.15",
     "@earendil-works/pi-agent-core": "1.0.3",
     "@earendil-works/pi-tui": "1.0.3",
-    "@vitest/coverage-v8": "5.0.3",
     "@types/node": "26.6.4",
+    "@vitest/coverage-v8": "5.0.3",
+    "oxfmt": "0.73.0",
     "oxlint": "1.87.0",
-    "oxlint-anti-slop": "0.3.6",
+    "oxlint-anti-slop": "0.3.8",
     "typebox": "1.3.35",
     "typescript": "7.0.2",
     "vitest": "5.0.3"
   },
-  "publishConfig": {
-    "access": "public"
+  "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
   },
   "pi": {
     "extensions": [
@@ -98,8 +100,5 @@
         "./agents"
       ]
     }
-  },
-  "allowScripts": {
-    "fsevents@2.3.3": true
   }
 }