@emiliosp/pi-maestro 0.11.0 → 0.13.0

package/docs/glossary.md

@@ -2,52 +2,55 @@
 
 ## Terms
 
-| Term                          | Meaning                                                                                                                                                             |
-|-------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `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`.                                                                                                |
-| `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` that describes one change, its scope, and its `acceptance criteria`. The approved `spec` defines the required behavior. It is saved as `spec.md`. |
-| `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.                                                                                                                  |
-| `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.                                                                                              |
-| `Run` or `pass`               | One agent execution with a fresh conversation.                                                                                                                      |
-| `Candidate`                   | The project files created by agents after a workflow `run`                                                                                                          |
-| `Finding`                     | A technical issue that the `verifier` records for an `owner` decision.                                                                                              |
-| `Escalation`                  | An implementation question or reportable technical problem that the `builder` records in its `handoff` for an `owner` decision.                                     |
-| `GREEN FLAG`                  | The owner's explicit reply that approves the current `spec` and starts the `builder`.                                                                               |
-| `fix-code`                    | An `owner` decision that requests code fixes without changing the approved `spec`.                                                                                  |
-| `revise-spec`                 | An `owner` decision that records a reason and agreed requirement change, then returns to `drafting-spec` for revision and renewed approval.                         |
-| `reject`                      | An `owner` decision that declines a `finding` and records a reason. It does not mean that verification passed.                                                      |
-| `candidate-ready`             | The completed workflow phase. Final review remains with the `owner`.                                                                                                |
+| Term                          | Meaning                                                                                                                                                                                                                               |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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`.                                                                                                                                                                  |
+| `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.                                                                                                                                                                                    |
+| `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.                                                                                                                                                                |
+| `Run` or `pass`               | One agent execution with a fresh conversation.                                                                                                                                                                                        |
+| `Candidate`                   | The project files created by agents after a workflow `run`                                                                                                                                                                            |
+| `Finding`                     | A technical issue that the `verifier` records for an `owner` decision.                                                                                                                                                                |
+| `Escalation`                  | An implementation question or reportable technical problem that the `builder` records in its `handoff` for an `owner` decision.                                                                                                       |
+| `GREEN FLAG`                  | The owner's explicit reply that approves the current `spec` and starts the `builder`.                                                                                                                                                 |
+| `fix-code`                    | An `owner` decision that requests code fixes without changing the approved `spec`.                                                                                                                                                    |
+| `revise-spec`                 | An `owner` decision that records a reason and agreed requirement change, then returns to `drafting-spec` for revision and renewed approval.                                                                                           |
+| `reject`                      | An `owner` decision that declines a `finding` and records a reason. It does not mean that verification passed.                                                                                                                        |
+| `candidate-ready`             | The completed workflow phase. Final review remains with the `owner`.                                                                                                                                                                  |
 
 ## Identifiers and file names
 
 An ID is an identifier that names one record. These labels refer to records within one `spec`, not across all workflows.
 
-| Label        | Meaning                                                           | Location or scope                                                               |
-|--------------|-------------------------------------------------------------------|---------------------------------------------------------------------------------|
-| `<spec-id>`  | The identifier shared by the `spec` and its workflow `artifacts`. | The directory name under `<project-root>/.specs/` by default.                   |
-| `B1`, `B2`   | `Builder` `handoff` 1, `builder` `handoff` 2.                     | `handoffs/builder/B1.json`, `handoffs/builder/B2.json`.                         |
-| `V1`, `V2`   | `Verifier` `handoff` 1, `verifier` `handoff` 2.                   | `handoffs/verifier/V1.json`, `handoffs/verifier/V2.json`.                       |
-| `S.json`     | The fixed, unnumbered `simplifier` `handoff`.                     | `handoffs/simplifier/S.json`.                                                   |
-| `E1`, `E2`   | `Escalation` 1, `escalation` 2 within one `builder` report.       | Entries in that report's `escalations` list.                                    |
-| `F1`, `F2`   | `Finding` 1, `finding` 2 within one `verifier` report.            | Entries in that report's `findings` list.                                       |
-| `AC1`, `AC2` | `Acceptance criterion` 1, `acceptance criterion` 2.               | Criteria in `spec.md` and the matching `acceptanceCriteria` entries in reports. |
-| `B1/E1`      | `Escalation` 1 in `builder` `handoff` 1.                          | The question with `id: "E1"` inside `handoffs/builder/B1.json`.                 |
-| `V1/F2`      | `Finding` 2 in `verifier` `handoff` 1.                            | The `finding` with `id: "F2"` inside `handoffs/verifier/V1.json`.               |
+| Label          | Meaning                                                           | Location or scope                                                               |
+| -------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `<spec-id>`    | The identifier shared by the `spec` and its workflow `artifacts`. | The directory name under `<project-root>/.specs/` by default.                   |
+| `B1`, `B2`     | `Builder` `handoff` 1, `builder` `handoff` 2.                     | `handoffs/builder/B1.json`, `handoffs/builder/B2.json`.                         |
+| `V1`, `V2`     | `Verifier` `handoff` 1, `verifier` `handoff` 2.                   | `handoffs/verifier/V1.json`, `handoffs/verifier/V2.json`.                       |
+| `S.json`       | The fixed, unnumbered `simplifier` `handoff`.                     | `handoffs/simplifier/S.json`.                                                   |
+| `E1`, `E2`     | `Escalation` 1, `escalation` 2 within one `builder` report.       | Entries in that report's `escalations` list.                                    |
+| `F1`, `F2`     | `Finding` 1, `finding` 2 within one `verifier` report.            | Entries in that report's `findings` list.                                       |
+| `REQ1`, `REQ2` | Requirement 1, requirement 2.                                     | Requirements in `spec.md`, each with a `Verified by` field.                     |
+| `AC1`, `AC2`   | `Acceptance criterion` 1, `acceptance criterion` 2.               | Criteria in `spec.md` and the matching `acceptanceCriteria` entries in reports. |
+| `B1/E1`        | `Escalation` 1 in `builder` `handoff` 1.                          | The question with `id: "E1"` inside `handoffs/builder/B1.json`.                 |
+| `V1/F2`        | `Finding` 2 in `verifier` `handoff` 1.                            | The `finding` with `id: "F2"` inside `handoffs/verifier/V1.json`.               |
 
 All paths in this table are relative to the `spec` directory unless stated otherwise. The [configuration](configuration.md#path-rules) can change the directory that
 contains `specs`.
 
-The `AC` prefix is the template's naming convention. Criterion IDs must be unique within the `spec`. Reports use the exact IDs from the `spec`.
+Requirement IDs use the `REQ` prefix. They are unique within the `spec` and remain stable during revisions. Each requirement links to its verification through
+`Verified by`. See [Requirement coverage](workflow.md#requirement-coverage).
 
-`Builder` and `verifier` numbers count saved `handoffs` in separate sequences.
+The `AC` prefix is the template's naming convention. Criterion IDs must be unique within the `spec`. Reports use the exact IDs from the `spec`, including standalone
+regression criteria without a requirement association. `Builder` and `verifier` numbers count saved `handoffs` in separate sequences.
 
 ## Escalation references
 
@@ -55,8 +58,8 @@ Read `B1/E1` as "escalation 1 in builder report 1". `B1` selects `handoffs/build
 
 `Escalation` numbers restart at `E1` in each `builder` report. `B1/E1` and `B2/E1` identify different questions, even if they concern the same topic.
 
-The `owner` discusses every current question with `Maestro`. `Maestro` records all answers and reasons together in that same `builder` report.
-See [Escalations](workflow.md#escalations) for the available choices and their effects.
+The `owner` discusses every current question with `Maestro`. `Maestro` records all answers and reasons together in that same `builder` report. See
+[Escalations](workflow.md#escalations) for the available choices and their effects.
 
 ## Finding references
 
@@ -66,8 +69,8 @@ Read `V1/F2` as "finding 2 in verifier report 1". `V1` selects `handoffs/verifie
 
 For example, a `finding` about a saved title can appear in a `Maestro` message like this:
 
-> Verifier report 1, finding 2 (`V1/F2`): the title returns to "Draft" after saving "Ready" and reopening the item.
-> Acceptance criterion 1 (`AC1`) requires the saved title to remain "Ready".
+> Verifier report 1, finding 2 (`V1/F2`): the title returns to "Draft" after saving "Ready" and reopening the item. Acceptance criterion 1 (`AC1`) requires the saved
+> title to remain "Ready".
 
 In this example, the finding's `acceptanceCriterion: "AC1"` connects the issue to criterion `AC1` in `spec.md`.
 

package/docs/subagent-integration.md

@@ -8,7 +8,7 @@ stays in the main `Maestro` conversation.
 The package supplies all three roles and the tools that save their results:
 
 | 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) |
@@ -16,8 +16,8 @@ The package supplies all three roles and the tools that save their results:
 Each `run` starts with a fresh conversation, not the main session's conversation history. All three agents inherit project instructions, the owner's global `AGENTS.md`,
 and available skills. The global file normally lives at `~/.pi/agent/AGENTS.md`.
 
-`Maestro` supplies the `spec` ID, project directory, model, thinking level, and timeout. The agents read the approved `spec` and saved `artifacts` to understand the work.
-Earlier `artifacts` provide context, not proof.
+`Maestro` supplies the `spec` ID, project directory, model, thinking level, and timeout. The agents read all approved documents (`proposal.md`, `spec.md`, and `design.md`
+when present) and saved `artifacts` to understand the work. Earlier `artifacts` provide context, not proof.
 
 The `owner` does not call agent tools directly. `Maestro` starts the `builder` after `GREEN FLAG` approval. The `verifier` starts after successful `builder` completion,
 and the `simplifier` follows successful `verifier` completion.
@@ -36,9 +36,8 @@ If a `run` fails or returns without a valid saved result, `Maestro` reports the
 
 ## External configuration
 
-The `pi-subagents` extension must be installed and enabled in Pi. `Builder`, `verifier`, and `simplifier` model choices, thinking levels, and timeouts come
-from [Maestro configuration](configuration.md). Other `pi-subagents` configuration remains the owner's responsibility.
+The `pi-subagents` extension must be installed and enabled in Pi. `Builder`, `verifier`, and `simplifier` model choices, thinking levels, and timeouts come from
+[Maestro configuration](configuration.md). Other `pi-subagents` configuration remains the owner's responsibility.
 
-Only `maestro_run_simplifier` checks Git readiness, with `git rev-parse --is-inside-work-tree`.
-If readiness cannot be confirmed, it warns and completes without delegation.
-The `simplifier` uses Git to select all uncommitted code changes. `Maestro` does not change the Git index or create commits or checkpoints.
+Only `maestro_run_simplifier` checks Git readiness, with `git rev-parse --is-inside-work-tree`. If readiness cannot be confirmed, it warns and completes without
+delegation. The `simplifier` uses Git to select all uncommitted code changes. `Maestro` does not change the Git index or create commits or checkpoints.

package/docs/workflow.md

@@ -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,24 @@ 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.
+`Maestro` stays active while delivering this final summary, then automatically turns off after successful delivery. The `owner` performs the final review and controls any
+later Git use, pull request, or merge. Changes after completion are outside the completed verification.
 
 ## 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 +292,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 +302,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 +311,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 +334,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';