@emiliosp/pi-maestro 0.7.1 → 0.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/CHANGELOG.md +91 -0
  2. package/MISSION.md +7 -0
  3. package/README.md +35 -35
  4. package/ROADMAP.md +89 -0
  5. package/{tech-stack.md → TECH_STACK.md} +3 -3
  6. package/docs/configuration.md +12 -12
  7. package/docs/glossary.md +35 -36
  8. package/docs/subagent-integration.md +11 -11
  9. package/docs/workflow.md +75 -75
  10. package/package.json +5 -5
  11. package/changelog.md +0 -85
  12. package/mission.md +0 -7
  13. package/roadmap.md +0 -85
package/CHANGELOG.md ADDED
@@ -0,0 +1,91 @@
1
+ # Changelog
2
+
3
+ This file summarizes meaningful changes to the codebase, including behavior, data formats, architecture, and development tools. Git tags identify version boundaries; GitHub Releases are not required. Version-only changes and routine maintenance are omitted.
4
+
5
+ ## 0.7.2
6
+
7
+ 1. Renamed the constitution files to `MISSION.md`, `TECH_STACK.md`, `ROADMAP.md`, and `CHANGELOG.md`. Updated their links, package file list, and audit references.
8
+ 2. Applied consistent inline code formatting to glossary terms across the documentation. Recorded the formatting rule and its exclusions in `AGENTS.md` and the documentation audit skill.
9
+ 3. Used `spec` consistently for the approved change document and removed the redundant glossary entry.
10
+
11
+ ## 0.7.1
12
+
13
+ 1. Documented the project mission, current tech stack, `owner` responsibilities, roadmap, and codebase change history. See [PR #30](https://github.com/emilioSp/pi-maestro/pull/30).
14
+ 2. Replaced `TODO.md` with the roadmap and included the four project constitution documents in the npm package.
15
+ 3. Updated documentation audits to compare all current documentation and the project constitution with the working tree without requesting a comparison baseline.
16
+
17
+ ## 0.7.0
18
+
19
+ 1. Stored multiple `escalation` questions and `owner` resolutions inside numbered `builder` `handoffs`. Earlier `handoffs` remain available as history. See [PR #27](https://github.com/emilioSp/pi-maestro/pull/27).
20
+ 2. Breaking: replaced `maestro_open_escalation` and `maestro_resolve_escalation` with `maestro_record_builder_handoff` and `maestro_resolve_escalations`. Done `handoffs` require `escalations: []`. Standalone `escalation` storage was removed without migration or compatibility readers. `Artifact` versions remain `1.0.0`.
21
+ 3. Added LCOV coverage reports and Codecov uploads from CI. See [PR #28](https://github.com/emilioSp/pi-maestro/pull/28).
22
+
23
+ Reload `Maestro` extensions before starting new workflows so sessions use the updated tools.
24
+
25
+ ## 0.6.2
26
+
27
+ Added phase icons, theme colors, and display-only shortening of long `spec` IDs. Successful activation shows the configured agent settings in a UI-only notice, outside session history and model context. See [PR #26](https://github.com/emilioSp/pi-maestro/pull/26).
28
+
29
+ ## 0.6.0
30
+
31
+ 1. Removed Git requirements, checkpoints, and automatic commits from the workflow. `Maestro` uses Pi's project directory and saved workflow phase. See [PR #25](https://github.com/emilioSp/pi-maestro/pull/25).
32
+ 2. Retained numbered `builder` and `verifier` `handoffs` and explicit `owner` `finding` decisions. Removed workflow revision counters and writer locks.
33
+ 3. Breaking: changed `artifact` formats, `handoff` paths, and tool results without migration or compatibility readers. Removed revision and commit fields. `Artifact` versions remain `1.0.0`. Interrupted and older workflows require manual `owner` handling.
34
+
35
+ ## 0.5.2
36
+
37
+ Reverted the `spec` question-dependency instructions introduced in `0.5.1`. See [commit 13cad11](https://github.com/emilioSp/pi-maestro/commit/13cad11).
38
+
39
+ ## 0.5.1
40
+
41
+ Added instructions to resolve prerequisite decisions before asking dependent `spec` questions and to review unresolved decisions before approval. These instructions were reverted in `0.5.2`.
42
+
43
+ ## 0.5.0
44
+
45
+ Removed breakage checks from `specs`, `handoffs`, validation, and agent instructions. Breakage checks temporarily introduced faults to test error detection. `Acceptance criteria` retain `probes`, `expected results`, and concrete examples. See [PR #24](https://github.com/emilioSp/pi-maestro/pull/24).
46
+
47
+ Breaking: `handoffs` no longer accept `breakageStatus`. Older `handoffs` containing that field must be regenerated. `Artifact` versions remain `1.0.0`.
48
+
49
+ ## 0.4.5
50
+
51
+ Required a concrete example in every `acceptance criterion`, both in the `spec` and when presenting it to the `owner`. Examples identify starting conditions, an action, and the expected observable result.
52
+
53
+ ## 0.4.4
54
+
55
+ Expanded Maestro's explanations of `findings` and `escalations` with code evidence, concrete examples, available choices, and their consequences. The `owner` retains control of each decision.
56
+
57
+ ## 0.4.3
58
+
59
+ Removed explicit `builder` and `verifier` tool allowlists and enabled inherited skills. Workflow boundaries remain defined by agent instructions.
60
+
61
+ ## 0.4.2
62
+
63
+ Made breakage checks optional when the approved `spec` did not require them. Required acceptance `probes` remained mandatory. Breakage checks were later removed in `0.5.0`. See [PR #23](https://github.com/emilioSp/pi-maestro/pull/23).
64
+
65
+ ## 0.4.1
66
+
67
+ Enabled inheritance of global instructions for `builder` and `verifier` agents, alongside project context.
68
+
69
+ ## 0.4.0
70
+
71
+ 1. Fixed delegated `handoffs` that depended on unavailable parent session memory. See [PR #22](https://github.com/emilioSp/pi-maestro/pull/22).
72
+ 2. Removed hash-based `spec` guards and checkpoint-based `verifier` comparisons. `Spec` preservation and restoration rely on agent instructions.
73
+ 3. Refreshed the running status before delegation and required repository investigation before presenting technical decisions during `spec` preparation.
74
+
75
+ ## 0.3.0
76
+
77
+ Clarified `Maestro`, `builder`, and `verifier` responsibilities, `spec` and prototype revisions, permitted experiments, evidence requirements, and cleanup. See [PR #21](https://github.com/emilioSp/pi-maestro/pull/21).
78
+
79
+ ## 0.2.0
80
+
81
+ Moved TypeBox to peer dependencies and loosened Pi peer dependency version constraints. Kept `pi-subagents` bundled with the package.
82
+
83
+ ## 0.1.2
84
+
85
+ Pinned `verifier` comparisons to a fixed `candidate` checkpoint rather than the current HEAD's parent. This checkpoint mechanism was later removed in `0.4.0`. See [PR #20](https://github.com/emilioSp/pi-maestro/pull/20).
86
+
87
+ Breaking: renamed `maestro_launch_builder` and `maestro_launch_verifier` to `maestro_run_builder` and `maestro_run_verifier`. Renamed the corresponding workflow events from `launch-*` to `run-*`.
88
+
89
+ ## 0.1.1
90
+
91
+ First tagged baseline with `/maestro`, `spec` creation and approval, and foreground `builder` and `verifier` `runs`. The `owner` decides `escalation` questions and `verifier` `findings`. The workflow ends at `candidate-ready`, leaving final review to the `owner`. See [PR #14](https://github.com/emilioSp/pi-maestro/pull/14) and [PR #13](https://github.com/emilioSp/pi-maestro/pull/13).
package/MISSION.md ADDED
@@ -0,0 +1,7 @@
1
+ # Mission
2
+
3
+ `Maestro` uses spec-driven development to improve quality when coding with agents. It guides the `owner` to define requirements and think through a feature before writing code.
4
+ It provides a clear path from an approved `spec` to verified code and manages agent coordination for the `owner`.
5
+
6
+ The `owner` remains responsible for final code review, pull requests, and merging. The `owner` also provides and maintains the project's development checks and instructions, including linters, tests, anti-slop checks, and `AGENTS.md`.
7
+ `Maestro` and its agents use these checks and instructions.
package/README.md CHANGED
@@ -8,25 +8,25 @@ Pi extension for a spec-driven multiagent development workflow.
8
8
 
9
9
  ## The idea
10
10
 
11
- A specification (spec) describes one reversible change. The builder implements it. An independent verifier checks every acceptance criterion. The owner performs the final review.
11
+ A `specification` (`spec`) describes one reversible change. The `builder` implements it. An independent `verifier` checks every `acceptance criterion`. The `owner` performs the final review.
12
12
 
13
13
  Four principles hold the workflow together:
14
14
 
15
- 1. The approved spec is the contract for the builder and verifier.
15
+ 1. The approved `spec` defines the required work for the `builder` and `verifier`.
16
16
  2. No agent approves its own work.
17
- 3. Every acceptance criterion is checked independently.
18
- 4. The owner decides requirements, scope, and unresolved questions.
17
+ 3. Every `acceptance criterion` is checked independently.
18
+ 4. The `owner` decides requirements, scope, and unresolved questions.
19
19
 
20
20
  ## The roles
21
21
 
22
22
  | Role | Responsibility |
23
23
  |---|---|
24
- | Owner | Brings the problem, approves the spec, decides questions and findings, and reviews the final code. |
25
- | Maestro | Works directly with the owner, prepares the spec, runs the other agents, records decisions, and summarizes results. |
26
- | Builder | Implements the approved spec and checks each acceptance criterion. |
27
- | Verifier | Independently checks the project files against the spec and reports technical issues. |
24
+ | `Owner` | Brings the problem, approves the `spec`, decides questions and `findings`, and reviews the final code. |
25
+ | `Maestro` | Works directly with the `owner`, prepares the `spec`, runs the other agents, records decisions, and summarizes results. |
26
+ | `Builder` | Implements the approved `spec` and checks each `acceptance criterion`. |
27
+ | `Verifier` | Independently checks the project files against the `spec` and reports technical issues. |
28
28
 
29
- An escalation asks the owner to decide an implementation question. A finding records a technical issue reported by the verifier. The owner discusses both with Maestro, not directly with the builder or verifier.
29
+ An `escalation` asks the `owner` to decide an implementation question. A `finding` records a technical issue reported by the `verifier`. The `owner` discusses both with `Maestro`, not directly with the `builder` or `verifier`.
30
30
 
31
31
  ## Prerequisites
32
32
 
@@ -34,12 +34,12 @@ An escalation asks the owner to decide an implementation question. A finding rec
34
34
  2. Node.js 26 or later.
35
35
  3. Pi 1.0.0 or later.
36
36
  4. `pi-subagents` installed and enabled in Pi.
37
- 5. Access to the configured builder and verifier models.
37
+ 5. Access to the configured `builder` and `verifier` models.
38
38
  6. A project directory that Pi trusts.
39
39
 
40
40
  ## Installation
41
41
 
42
- The owner installs `pi-subagents` and Maestro with these commands:
42
+ The `owner` installs `pi-subagents` and `Maestro` with these commands:
43
43
 
44
44
  ```bash
45
45
  pi install npm:pi-subagents
@@ -48,59 +48,59 @@ pi install npm:@emiliosp/pi-maestro
48
48
 
49
49
  ## Usage
50
50
 
51
- The owner starts Pi from the project directory:
51
+ The `owner` starts Pi from the project directory:
52
52
 
53
53
  ```bash
54
54
  cd /path/to/project
55
55
  pi
56
56
  ```
57
57
 
58
- Activate Maestro:
58
+ Activate `Maestro`:
59
59
 
60
60
  ```text
61
61
  /maestro
62
62
  ```
63
63
 
64
- During activation, Maestro checks project trust, configuration, models, and agent availability. If a check fails, Maestro stays disabled and reports the problem.
64
+ During activation, `Maestro` checks project trust, configuration, models, and agent availability. If a check fails, `Maestro` stays disabled and reports the problem.
65
65
 
66
- The owner follows this workflow:
66
+ The `owner` follows this workflow:
67
67
 
68
- 1. Describes one change to Maestro.
69
- 2. Reviews the spec, including its acceptance criteria and concrete examples.
70
- 3. Replies `GREEN FLAG` when Maestro asks for approval. Maestro records the approval and starts the builder.
71
- 4. Reviews every current builder escalation and gives Maestro an answer and reason for each question.
72
- 5. Reviews verifier findings and chooses an action for every finding.
68
+ 1. Describes one change to `Maestro`.
69
+ 2. Reviews the `spec`, including its `acceptance criteria` and concrete examples.
70
+ 3. Replies `GREEN FLAG` when `Maestro` asks for approval. `Maestro` records the approval and starts the `builder`.
71
+ 4. Reviews every current `builder` `escalation` and gives `Maestro` an answer and reason for each question.
72
+ 5. Reviews `verifier` `findings` and chooses an action for every `finding`.
73
73
  6. Reads Maestro's summary at `candidate-ready` and performs the final review.
74
74
 
75
- Maestro starts the verifier after a successful builder run.
76
- Both agents run in the foreground: Pi waits for each run to finish and Maestro shows the current phase in Pi's status, while `pi-subagents` FleetView and `/subagents-fleet` show agent activity and transcripts.
75
+ `Maestro` starts the `verifier` after a successful `builder` `run`.
76
+ Both agents run in the foreground: Pi waits for each `run` to finish and `Maestro` shows the current phase in Pi's status, while `pi-subagents` FleetView and `/subagents-fleet` show agent activity and transcripts.
77
77
 
78
- The owner must not edit product files while the workflow runs.
79
- Maestro can perform temporary experiments with owner agreement during spec preparation and permitted revisions. See [Workflow](docs/workflow.md#spec-approval).
78
+ The `owner` must not edit product files while the workflow runs.
79
+ `Maestro` can perform temporary experiments with `owner` agreement during `spec` preparation and permitted revisions. See [Workflow](docs/workflow.md#spec-approval).
80
80
 
81
- An escalation asks the owner to decide an implementation question, and a finding records a technical issue reported by the verifier. The owner discusses both with Maestro, never directly with the builder or verifier.
82
- If a contract change is needed during an escalation or finding decision, the owner reviews the revised spec and replies `GREEN FLAG` again. Maestro then starts another builder run.
81
+ An `escalation` asks the `owner` to decide an implementation question, and a `finding` records a technical issue reported by the `verifier`. The `owner` discusses both with `Maestro`, never directly with the `builder` or `verifier`.
82
+ If a `spec` change is needed during an `escalation` or `finding` decision, the `owner` reviews the revised `spec` and replies `GREEN FLAG` again. `Maestro` then starts another `builder` `run`.
83
83
 
84
- The workflow ends at `candidate-ready`. Rejected findings retain their reasons. Later changes are outside the completed verification. The owner controls any later Git use, pull request, and merge.
84
+ The workflow ends at `candidate-ready`. Rejected `findings` retain their reasons. Later changes are outside the completed verification. The `owner` controls any later Git use, pull request, and merge.
85
85
 
86
- The same `/maestro` command disables Maestro and leaves project files unchanged. Disabling Maestro, restarting Pi, or using `/resume` clears live session state. Saved files do not automatically restore or resume an incomplete workflow. The owner handles it manually.
86
+ The same `/maestro` command disables `Maestro` and leaves project files unchanged. Disabling `Maestro`, restarting Pi, or using `/resume` clears live session state. Saved files do not automatically restore or resume an incomplete workflow. The `owner` handles it manually.
87
87
 
88
88
  ## Configuration
89
89
 
90
- Maestro uses default values when `.pi/maestro.json` is absent from the project root. The owner can add this file to change the spec directory, models, thinking levels, or timeouts. See [Configuration](docs/configuration.md).
90
+ `Maestro` uses default values when `.pi/maestro.json` is absent from the project root. The `owner` can add this file to change the `spec` directory, models, thinking levels, or timeouts. See [Configuration](docs/configuration.md).
91
91
 
92
92
  ## Documentation
93
93
 
94
94
  The reading order is:
95
95
 
96
- 1. [Glossary](docs/glossary.md): terms and identifiers used in specs, reports, and Maestro messages. Read this before the first workflow.
97
- 2. [Workflow](docs/workflow.md): approvals, decisions, and how each run produces artifacts.
96
+ 1. [Glossary](docs/glossary.md): terms and identifiers used in `specs`, reports, and `Maestro` messages. Read this before the first workflow.
97
+ 2. [Workflow](docs/workflow.md): approvals, decisions, and how each `run` produces `artifacts`.
98
98
  3. [Configuration](docs/configuration.md): project paths, models, and timeouts.
99
99
  4. [Subagent integration](docs/subagent-integration.md): agent context, execution, and activity tracking.
100
100
 
101
101
  ## Project constitution
102
102
 
103
- 1. [Mission](mission.md): purpose, scope, and owner responsibilities.
104
- 2. [Tech stack](tech-stack.md): runtime technologies and development tools.
105
- 3. [Roadmap](roadmap.md): completed outcomes and planned priorities.
106
- 4. [Changelog](changelog.md): meaningful codebase changes and breaking contracts.
103
+ 1. [Mission](MISSION.md): purpose, scope, and `owner` responsibilities.
104
+ 2. [Tech stack](TECH_STACK.md): runtime technologies and development tools.
105
+ 3. [Roadmap](ROADMAP.md): completed outcomes and planned priorities.
106
+ 4. [Changelog](CHANGELOG.md): meaningful codebase changes and breaking changes.
package/ROADMAP.md ADDED
@@ -0,0 +1,89 @@
1
+ # Roadmap
2
+
3
+ This roadmap records planned outcomes, not permission to implement them. The `owner` selects work and approves its `specification` before implementation starts. Detailed requirements, technical decisions, and `acceptance criteria` belong in that `specification`.
4
+
5
+ "Now" is the current priority. "Next" follows it. “Later” contains uncommitted ideas with no promised order or date.
6
+
7
+ Item identifiers remain stable when priorities change. The `owner` approves changes to priorities and scope.
8
+
9
+ ## Completed
10
+
11
+ ### R-01: Improve status presentation and activation feedback
12
+
13
+ The status bar uses phase icons, theme colors, and shortened `spec` IDs. Successful activation shows the configured `builder` and `verifier` settings without adding the notice to session history or model context. All 12 `acceptance criteria` passed with no `verifier` `findings`; the saved workflow reached `candidate-ready`.
14
+
15
+ Evidence: [Specification](.specs/20261007-170438-update-maestro-status-bar-with-agent-models-theme-colors-and-phase-icons/spec.md), [verifier report](.specs/20261007-170438-update-maestro-status-bar-with-agent-models-theme-colors-and-phase-icons/handoffs/verifier/V1.json), and [merged PR #26](https://github.com/emilioSp/pi-maestro/pull/26).
16
+
17
+ ### R-02: Store escalations and owner decisions in builder handoffs
18
+
19
+ Numbered `builder` `handoffs` contain multiple `escalation` questions and their `owner` resolutions. The `owner` resolves all current questions in one batch, while earlier `handoffs` remain available as history. All 10 `acceptance criteria` passed with no `verifier` `findings`; the saved workflow reached `candidate-ready`.
20
+
21
+ Evidence: [Specification](.specs/20261008-132344-store-escalations-in-builder-handoffs/spec.md), [verifier report](.specs/20261008-132344-store-escalations-in-builder-handoffs/handoffs/verifier/V1.json), and [merged PR #27](https://github.com/emilioSp/pi-maestro/pull/27).
22
+
23
+ ### R-12: Format glossary terms consistently
24
+
25
+ Applied glossary formatting across the documentation and recorded its exclusions in `AGENTS.md` and the documentation audit skill. The approved change document uses the term `spec`. The `owner` confirmed completion.
26
+
27
+ Evidence: [Glossary](docs/glossary.md) and [workflow documentation](docs/workflow.md).
28
+
29
+ ## Now
30
+
31
+ No current priority is selected.
32
+
33
+ ## Next
34
+
35
+ ### R-03: Route builder failures through owner escalations
36
+
37
+ A technical `builder` failure currently ends the workflow in `builder-failed`. Replace the builder's `failed` `handoff` status and the `builder-failed` workflow phase with an `escalation`. The `owner` decides how to proceed through the existing `escalation` process.
38
+
39
+ Complete when `builder` failures produce `owner` `escalations` instead of a terminal failure state. Individual checks retain `failed` as a valid result. Agent instructions, tools, workflow transitions, tests, and documentation must describe the same behavior.
40
+
41
+ Automatic recovery of interrupted `runs` is outside this item. No `specification` is approved yet.
42
+
43
+ ## Later
44
+
45
+ These items need scope review before `specification` approval. Existing behavior must be checked before adding new code. Dependencies between these items are not yet agreed.
46
+
47
+ ### R-04: Rename the npm package
48
+
49
+ Rename `@emiliosp/pi-maestro` to `pi-maestro-sdd`. The `owner` installs the package under the new name. This item changes the package identity, not the development workflow.
50
+
51
+ Complete when package metadata and installation documentation use the new name and the package is available under it. Compatibility with installations under the old name must be decided in the `specification`. No `specification` is approved yet.
52
+
53
+ ### R-05: Keep acceptance criterion numbering continuous
54
+
55
+ When criteria are removed during `spec` preparation or revision, renumber the remaining criteria without gaps. Numbering starts at `AC1` and continues through the final criterion. Complete when the `spec` and its current references use consistent numbering.
56
+
57
+ ### R-06: Check subagent extensions at activation
58
+
59
+ Make extension availability problems visible before a `builder` or `verifier` `run` starts. Activation already checks agent launch requirements, so first identify any missing extension checks. Complete when unavailable required subagent extensions prevent activation and the error identifies the problem.
60
+
61
+ ### R-07: Guide initial configuration
62
+
63
+ Help the `owner` create `Maestro` configuration through an interview. `Maestro` asks questions and writes the agreed configuration. Complete when the `owner` can create a valid project configuration without writing the file manually.
64
+
65
+ ### R-08: Change agent models before a builder run
66
+
67
+ Let the `owner` change the `builder` and `verifier` models during `spec` preparation and the `ready-for-builder` phase. The selected models apply to subsequent `runs`. Complete when the `owner` can select available models in those phases and `Maestro` uses the selections.
68
+
69
+ ### R-09: Define workflow reconciliation
70
+
71
+ Explore how `Maestro` can reconcile saved `artifacts` and workflow state. The recovery scope is not yet defined. The `owner` must define the intended outcome, recovery boundaries, and completion condition before this item can move forward.
72
+
73
+ ### R-10: Match handoff criteria to the approved spec
74
+
75
+ Prevent `builder` and `verifier` reports from omitting or adding `acceptance criteria`. Each report must contain exactly the criterion IDs in the approved `spec`, with no duplicates in either place. Existing duplicate checks in reports do not establish this match.
76
+
77
+ Complete when both `handoff` submissions reject missing, extra, or duplicate criterion IDs before saving a report or changing phase. The `specification` must define the criterion heading format used to extract IDs. For example, a heading can use `### AC1: ...`.
78
+
79
+ ### R-11: Reduce temporary verifier changes
80
+
81
+ Reduce the risk that verification changes the `candidate`. Existing instructions already require exact restoration, cleanup, and reporting of unresolved restoration problems. Refine the remaining guidance rather than duplicate those rules.
82
+
83
+ Prefer checks that leave existing files unchanged and use separate temporary files when possible. Change an existing file only when a criterion requires it, retain its exact contents, and restore it immediately after each `probe`, including failed `probes`. Prefer check-only commands over commands that apply automatic fixes.
84
+
85
+ Complete when `verifier` instructions cover these limits and require restoration and temporary-file cleanup before `handoff`. If restoration fails, the `verifier` must stop and report affected paths and remaining changes. `Maestro` currently has no file-hash restoration check; adding one requires a separate scope decision.
86
+
87
+ ### R-13: Show when Maestro is working
88
+
89
+ Show an activity indicator in Pi's status bar while progress does not require an `owner` decision. A spinner is one option, not an agreed implementation. Complete when the status clearly distinguishes work in progress from a request for `owner` action.
package/{tech-stack.md → TECH_STACK.md} RENAMED
@@ -1,14 +1,14 @@
1
1
  # Tech stack
2
2
 
3
- Maestro is a source-only TypeScript package that uses ECMAScript modules (ESM). Pi loads the TypeScript source directly. The package has no build step or compiled `dist/` directory.
3
+ `Maestro` is a source-only TypeScript package that uses ECMAScript modules (ESM). Pi loads the TypeScript source directly. The package has no build step or compiled `dist/` directory.
4
4
 
5
5
  | Technology | Use |
6
6
  |---|---|
7
7
  | TypeScript | Application code and static type checks with `tsc --noEmit`. |
8
8
  | Node.js | Runtime. |
9
9
  | Pi | Extension host, agent APIs, and terminal interface. |
10
- | `pi-subagents` | Builder and verifier execution and activity tracking. |
10
+ | `pi-subagents` | `Builder` and `verifier` execution and activity tracking. |
11
11
  | TypeBox | Schemas and runtime validation for configuration, workflow state, tool inputs, and agent reports. |
12
- | Vitest with V8 coverage | Unit tests, integration tests, and code coverage. |
12
+ | Vitest with coverage | Unit tests, integration tests, and code coverage. |
13
13
  | Biome | Formatting and lint checks. |
14
14
  | Oxlint with `oxlint-anti-slop` | Additional lint and anti-slop checks. |
package/docs/configuration.md CHANGED
@@ -1,12 +1,12 @@
1
1
  # Configuration
2
2
 
3
- Maestro reads `.pi/maestro.json` from the project root. The file is optional. Maestro uses all default values when it is absent.
3
+ `Maestro` reads `.pi/maestro.json` from the project root. The file is optional. `Maestro` uses all default values when it is absent.
4
4
 
5
5
  ## Project root
6
6
 
7
- The project root is the current Pi working directory. Builder and verifier runs use this same directory.
7
+ The project root is the current Pi working directory. `Builder` and `verifier` `runs` use this same directory.
8
8
 
9
- For example, if Pi starts in `/work/app/src`, Maestro reads `/work/app/src/.pi/maestro.json`. A configuration file in `/work/app/.pi/maestro.json` does not apply.
9
+ For example, if Pi starts in `/work/app/src`, `Maestro` reads `/work/app/src/.pi/maestro.json`. A configuration file in `/work/app/.pi/maestro.json` does not apply.
10
10
 
11
11
  ## Default configuration
12
12
 
@@ -33,16 +33,16 @@ For example, if Pi starts in `/work/app/src`, Maestro reads `/work/app/src/.pi/m
33
33
  |---|---:|---|---|
34
34
  | `version` | Yes, when the file exists | `1.0.0` | Configuration format version. Only `1.0.0` is supported. |
35
35
  | `specDirectory` | No | `.specs` | Relative path below the project root. |
36
- | `builder` | No | Builder defaults | Overrides supported builder fields. |
36
+ | `builder` | No | `Builder` defaults | Overrides supported `builder` fields. |
37
37
  | `builder.model` | No | `openai-codex/gpt-5.6-luna` | Full `provider/model` identifier. |
38
38
  | `builder.thinking` | No | `max` | One supported thinking level. |
39
- | `builder.timeoutMinutes` | No | `60` | Integer from `1` to `1440`. Applies to each builder run. |
40
- | `verifier` | No | Verifier defaults | Overrides supported verifier fields. |
39
+ | `builder.timeoutMinutes` | No | `60` | Integer from `1` to `1440`. Applies to each `builder` `run`. |
40
+ | `verifier` | No | `Verifier` defaults | Overrides supported `verifier` fields. |
41
41
  | `verifier.model` | No | `openai-codex/gpt-6.1-sol` | Full `provider/model` identifier. |
42
42
  | `verifier.thinking` | No | `high` | One supported thinking level. |
43
- | `verifier.timeoutMinutes` | No | `60` | Integer from `1` to `1440`. Applies to each verifier run. |
43
+ | `verifier.timeoutMinutes` | No | `60` | Integer from `1` to `1440`. Applies to each `verifier` `run`. |
44
44
 
45
- Model identifiers use the full `provider/model` form shown in the defaults. Maestro accepts these thinking levels:
45
+ Model identifiers use the full `provider/model` form shown in the defaults. `Maestro` accepts these thinking levels:
46
46
 
47
47
  ```text
48
48
  off
@@ -67,7 +67,7 @@ Only `version` is required when the file exists. Each other field overrides its
67
67
  }
68
68
  ```
69
69
 
70
- This example keeps every default except the builder timeout.
70
+ This example keeps every default except the `builder` timeout.
71
71
 
72
72
  ## Schema version
73
73
 
@@ -81,10 +81,10 @@ This example keeps every default except the builder timeout.
81
81
  2. The path stays below that root after `.` and `..` are resolved.
82
82
  3. The path is not the project root itself.
83
83
 
84
- For example, `specDirectory: "planning/specs"` places specs in `<project-root>/planning/specs/`. Absolute paths and paths outside the project root are rejected. The owner is responsible for directory permissions that allow Maestro to save artifacts.
84
+ For example, `specDirectory: "planning/specs"` places `specs` in `<project-root>/planning/specs/`. Absolute paths and paths outside the project root are rejected. The `owner` is responsible for directory permissions that allow `Maestro` to save `artifacts`.
85
85
 
86
86
  ## Model access
87
87
 
88
- Maestro checks both configured models during activation. Each model must exist and have valid authentication.
88
+ `Maestro` checks both configured models during activation. Each model must exist and have valid authentication.
89
89
 
90
- A model error stops activation and identifies the affected model. The owner can correct the model identifier or authenticate the provider, then run `/maestro` again. Agent names and context are described in [Subagent integration](subagent-integration.md#roles-and-context).
90
+ A model error stops activation and identifies the affected model. The `owner` can correct the model identifier or authenticate the provider, then run `/maestro` again. Agent names and context are described in [Subagent integration](subagent-integration.md#roles-and-context).
package/docs/glossary.md CHANGED
@@ -4,66 +4,65 @@
4
4
 
5
5
  | Term | Meaning |
6
6
  |---|---|
7
- | Owner | The person who approves the spec, decides questions and findings, and performs the final review. |
8
- | Maestro | The coordinator that prepares the spec, runs the agents, and records owner decisions. |
9
- | Builder | The agent that implements the approved spec and runs its probes. |
10
- | Verifier | The independent agent that checks the implementation and reports technical issues. |
11
- | Spec | A specification that describes one change and its acceptance criteria. It is saved as `spec.md`. |
12
- | Contract | The approved spec that defines the required behavior and scope. |
13
- | Acceptance criterion (AC) | One required, observable result defined in the spec. |
14
- | Probe | A scenario used to test an acceptance criterion. Reports record the actual command or procedure and its outcome. |
15
- | Expected result | The observable result that a probe must produce. |
16
- | Artifact | A saved workflow file, such as a spec, or a handoff between agents. |
17
- | Handoff | A saved builder or verifier report with results, probe outcomes, and notes. |
18
- | Run or pass | One execution of the builder or verifier with a fresh conversation. |
19
- | Candidate | The project files created by agents after a workflow run |
20
- | Finding | A technical issue that the verifier records for an owner decision. |
21
- | Escalation | An implementation question that the builder records in its handoff for an owner decision. |
22
- | `GREEN FLAG` | The owner's explicit reply that approves the current spec and starts the builder. |
23
- | `fix-code` | An owner decision that requests code fixes without changing the approved spec. |
24
- | `reject` | An owner decision that declines a finding and records a reason. It does not mean that verification passed. |
25
- | `candidate-ready` | The completed workflow phase. The verifier reported no findings, or the owner rejected every finding with a reason. Final review remains with the owner. |
7
+ | `Owner` | The person who approves the `spec`, decides questions and `findings`, and performs the final review. |
8
+ | `Maestro` | The coordinator that prepares the `spec`, runs the agents, and records `owner` decisions. |
9
+ | `Builder` | The agent that implements the approved `spec` and runs its `probes`. |
10
+ | `Verifier` | The independent agent that checks the implementation and reports technical issues. |
11
+ | `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`. |
12
+ | `Acceptance criterion` (`AC`) | One required, observable result defined in the `spec`. |
13
+ | `Probe` | A scenario used to test an `acceptance criterion`. Reports record the actual command or procedure and its outcome. |
14
+ | `Expected result` | The observable result that a `probe` must produce. |
15
+ | `Artifact` | A saved workflow file, such as a `spec`, or a `handoff` between agents. |
16
+ | `Handoff` | A saved `builder` or `verifier` report with results, `probe` outcomes, and notes. |
17
+ | `Run` or `pass` | One execution of the `builder` or `verifier` with a fresh conversation. |
18
+ | `Candidate` | The project files created by agents after a workflow `run` |
19
+ | `Finding` | A technical issue that the `verifier` records for an `owner` decision. |
20
+ | `Escalation` | An implementation question that the `builder` records in its `handoff` for an `owner` decision. |
21
+ | `GREEN FLAG` | The owner's explicit reply that approves the current `spec` and starts the `builder`. |
22
+ | `fix-code` | An `owner` decision that requests code fixes without changing the approved `spec`. |
23
+ | `reject` | An `owner` decision that declines a `finding` and records a reason. It does not mean that verification passed. |
24
+ | `candidate-ready` | The completed workflow phase. The `verifier` reported no `findings`, or the `owner` rejected every `finding` with a reason. Final review remains with the `owner`. |
26
25
 
27
26
  ## Identifiers and file names
28
27
 
29
- An ID is an identifier that names one record. These labels refer to records within one spec, not across all workflows.
28
+ An ID is an identifier that names one record. These labels refer to records within one `spec`, not across all workflows.
30
29
 
31
30
  | Label | Meaning | Location or scope |
32
31
  |---|---|---|
33
- | `<spec-id>` | The identifier shared by the spec and its workflow artifacts. | The directory name under `<project-root>/.specs/` by default. |
34
- | `B1`, `B2` | Builder handoff 1, builder handoff 2. | `handoffs/builder/B1.json`, `handoffs/builder/B2.json`. |
35
- | `V1`, `V2` | Verifier handoff 1, verifier handoff 2. | `handoffs/verifier/V1.json`, `handoffs/verifier/V2.json`. |
36
- | `E1`, `E2` | Escalation 1, escalation 2 within one builder report. | Entries in that report's `escalations` list. |
37
- | `F1`, `F2` | Finding 1, finding 2 within one verifier report. | Entries in that report's `findings` list. |
38
- | `AC1`, `AC2` | Acceptance criterion 1, acceptance criterion 2. | Criteria in `spec.md` and the matching `acceptanceCriteria` entries in reports. |
39
- | `B1/E1` | Escalation 1 in builder handoff 1. | The question with `id: "E1"` inside `handoffs/builder/B1.json`. |
40
- | `V1/F2` | Finding 2 in verifier handoff 1. | The finding with `id: "F2"` inside `handoffs/verifier/V1.json`. |
32
+ | `<spec-id>` | The identifier shared by the `spec` and its workflow `artifacts`. | The directory name under `<project-root>/.specs/` by default. |
33
+ | `B1`, `B2` | `Builder` `handoff` 1, `builder` `handoff` 2. | `handoffs/builder/B1.json`, `handoffs/builder/B2.json`. |
34
+ | `V1`, `V2` | `Verifier` `handoff` 1, `verifier` `handoff` 2. | `handoffs/verifier/V1.json`, `handoffs/verifier/V2.json`. |
35
+ | `E1`, `E2` | `Escalation` 1, `escalation` 2 within one `builder` report. | Entries in that report's `escalations` list. |
36
+ | `F1`, `F2` | `Finding` 1, `finding` 2 within one `verifier` report. | Entries in that report's `findings` list. |
37
+ | `AC1`, `AC2` | `Acceptance criterion` 1, `acceptance criterion` 2. | Criteria in `spec.md` and the matching `acceptanceCriteria` entries in reports. |
38
+ | `B1/E1` | `Escalation` 1 in `builder` `handoff` 1. | The question with `id: "E1"` inside `handoffs/builder/B1.json`. |
39
+ | `V1/F2` | `Finding` 2 in `verifier` `handoff` 1. | The `finding` with `id: "F2"` inside `handoffs/verifier/V1.json`. |
41
40
 
42
- 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.
41
+ 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`.
43
42
 
44
- 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.
43
+ 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`.
45
44
 
46
- Builder and verifier numbers count saved handoffs in separate sequences.
45
+ `Builder` and `verifier` numbers count saved `handoffs` in separate sequences.
47
46
 
48
47
  ## Escalation references
49
48
 
50
49
  Read `B1/E1` as "escalation 1 in builder report 1". `B1` selects `handoffs/builder/B1.json`. `E1` selects the entry with `id: "E1"` in its `escalations` list.
51
50
 
52
- Escalation numbers restart at `E1` in each builder report. `B1/E1` and `B2/E1` identify different questions, even if they concern the same topic.
51
+ `Escalation` numbers restart at `E1` in each `builder` report. `B1/E1` and `B2/E1` identify different questions, even if they concern the same topic.
53
52
 
54
- 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.
53
+ 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.
55
54
 
56
55
  ## Finding references
57
56
 
58
57
  Read `V1/F2` as "finding 2 in verifier report 1". `V1` selects `handoffs/verifier/V1.json`. `F2` selects the entry with `id: "F2"` in its `findings` list.
59
58
 
60
- Finding numbers restart at `F1` in each verifier report. `V1/F2` and `V2/F2` identify different records, even if they describe a similar issue.
59
+ `Finding` numbers restart at `F1` in each `verifier` report. `V1/F2` and `V2/F2` identify different records, even if they describe a similar issue.
61
60
 
62
- For example, a finding about a saved title can appear in a Maestro message like this:
61
+ For example, a `finding` about a saved title can appear in a `Maestro` message like this:
63
62
 
64
63
  > Verifier report 1, finding 2 (`V1/F2`): the title returns to "Draft" after saving "Ready" and reopening the item.
65
64
  > Acceptance criterion 1 (`AC1`) requires the saved title to remain "Ready".
66
65
 
67
66
  In this example, the finding's `acceptanceCriterion: "AC1"` connects the issue to criterion `AC1` in `spec.md`.
68
67
 
69
- The owner discusses the issue with Maestro. Maestro records the decision in the same verifier report. See [Findings](workflow.md#findings) for the available choices and their effects.
68
+ The `owner` discusses the issue with `Maestro`. `Maestro` records the decision in the same `verifier` report. See [Findings](workflow.md#findings) for the available choices and their effects.
package/docs/subagent-integration.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Subagent integration
2
2
 
3
- Maestro uses `pi-subagents` to run the builder and verifier as child sessions. A child session is a separate Pi session for one role. The owner stays in the main Maestro conversation.
3
+ `Maestro` uses `pi-subagents` to run the `builder` and `verifier` as child sessions. A child session is a separate Pi session for one role. The `owner` stays in the main `Maestro` conversation.
4
4
 
5
5
  ## Roles and context
6
6
 
@@ -8,27 +8,27 @@ The package supplies both roles and the tools that save their results:
8
8
 
9
9
  | Role | Agent name | Definition |
10
10
  |---|---|---|
11
- | Builder | `maestro.builder` | [`agents/builder.md`](../agents/builder.md) |
12
- | Verifier | `maestro.verifier` | [`agents/verifier.md`](../agents/verifier.md) |
11
+ | `Builder` | `maestro.builder` | [`agents/builder.md`](../agents/builder.md) |
12
+ | `Verifier` | `maestro.verifier` | [`agents/verifier.md`](../agents/verifier.md) |
13
13
 
14
- Each run starts with a fresh conversation, not the main session's conversation history. Both agents inherit project instructions, the owner's global `AGENTS.md`, and available skills. The global file normally lives at `~/.pi/agent/AGENTS.md`.
14
+ Each `run` starts with a fresh conversation, not the main session's conversation history. Both agents inherit project instructions, the owner's global `AGENTS.md`, and available skills. The global file normally lives at `~/.pi/agent/AGENTS.md`.
15
15
 
16
- 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.
16
+ `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.
17
17
 
18
- The owner does not call builder or verifier tools directly. Maestro starts the builder after `GREEN FLAG` approval and the verifier after successful builder completion.
18
+ The `owner` does not call `builder` or `verifier` tools directly. `Maestro` starts the `builder` after `GREEN FLAG` approval and the `verifier` after successful `builder` completion.
19
19
 
20
20
  ## Following a run
21
21
 
22
- 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 the builder and verifier in parallel or in the background.
22
+ `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 the `builder` and `verifier` in parallel or in the background.
23
23
 
24
24
  Maestro's Pi status shows the workflow phase. `pi-subagents` FleetView shows agent activity, and `/subagents-fleet` opens its inspector for details and transcripts.
25
25
 
26
- 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. See [Stored artifacts](workflow.md#stored-artifacts) for the creation sequence.
26
+ 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. See [Stored artifacts](workflow.md#stored-artifacts) for the creation sequence.
27
27
 
28
- 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).
28
+ 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).
29
29
 
30
30
  ## External configuration
31
31
 
32
- The `pi-subagents` extension must be installed and enabled in Pi. Builder and verifier model choices, thinking levels, and timeouts come from [Maestro configuration](configuration.md). Other `pi-subagents` configuration remains the owner's responsibility.
32
+ The `pi-subagents` extension must be installed and enabled in Pi. `Builder` and `verifier` model choices, thinking levels, and timeouts come from [Maestro configuration](configuration.md). Other `pi-subagents` configuration remains the owner's responsibility.
33
33
 
34
- Maestro does not invoke Git to manage its workflow. `pi-subagents` can use Git internally.
34
+ `Maestro` does not invoke Git to manage its workflow. `pi-subagents` can use Git internally.
package/docs/workflow.md CHANGED
@@ -1,32 +1,32 @@
1
1
  # Workflow
2
2
 
3
- Maestro manages one spec-driven workflow in the current Pi session. The owner works directly with Maestro.
3
+ `Maestro` manages one spec-driven workflow in the current Pi session. The `owner` works directly with `Maestro`.
4
4
 
5
- The approved `spec.md` is the contract for the change. It defines behavior, scope, constraints, technical decisions, and acceptance criteria.
5
+ The approved `spec.md` defines behavior, scope, constraints, technical decisions, and `acceptance criteria` for the change.
6
6
 
7
- An acceptance criterion contains a probe, an expected result, and an example. A probe is a scenario used to test behavior.
7
+ An `acceptance criterion` contains a `probe`, an `expected result`, and an example. A `probe` is a scenario used to test behavior.
8
8
 
9
- A handoff is a saved report from a builder or verifier run. It records the result, probe outcomes, and notes.
9
+ A `handoff` is a saved report from a `builder` or `verifier` `run`. It records the result, `probe` outcomes, and notes.
10
10
 
11
- A builder handoff can contain escalations, which are questions that need owner decisions.
12
- A verifier handoff can contain findings, which are technical issues.
11
+ A `builder` `handoff` can contain `escalations`, which are questions that need `owner` decisions.
12
+ A `verifier` `handoff` can contain `findings`, which are technical issues.
13
13
 
14
14
  ## Roles
15
15
 
16
16
  | Role | Responsibility |
17
17
  |---|---|
18
- | Owner | Decides requirements, scope, technical decisions, spec approval, escalation answers, and finding decisions. Performs the final review. |
19
- | Maestro | Prepares the spec with the owner, records workflow progress, runs agents, presents issues, and saves owner decisions. |
20
- | Builder | Implements the approved spec and runs every probe. Reports completion, an escalation, or a technical failure. |
21
- | Verifier | Independently runs every probe against the live project files. Reports findings without repairing product code. |
18
+ | `Owner` | Decides requirements, scope, technical decisions, `spec` approval, `escalation` answers, and `finding` decisions. Performs the final review. |
19
+ | `Maestro` | Prepares the `spec` with the `owner`, records workflow progress, runs agents, presents issues, and saves `owner` decisions. |
20
+ | `Builder` | Implements the approved `spec` and runs every `probe`. Reports completion, an `escalation`, or a technical failure. |
21
+ | `Verifier` | Independently runs every `probe` against the live project files. Reports `findings` without repairing product code. |
22
22
 
23
- Builder and verifier runs are sequential foreground operations. Each starts with a fresh conversation and reads the spec and saved artifacts.
23
+ `Builder` and `verifier` `runs` are sequential foreground operations. Each starts with a fresh conversation and reads the `spec` and saved `artifacts`.
24
24
 
25
25
  Maestro's Pi status shows the current phase. `pi-subagents` FleetView and `/subagents-fleet` show live agent activity and transcripts.
26
26
 
27
27
  ## Main flow
28
28
 
29
- The green arrows and lines show the path without escalations or findings.
29
+ The green arrows and lines show the path without `escalations` or `findings`.
30
30
 
31
31
  ```mermaid
32
32
  flowchart TD
@@ -48,9 +48,9 @@ flowchart TD
48
48
  findings -->|None| candidate
49
49
 
50
50
  buildOutcome -->|Escalation| ownerEscalation{Owner decides every question}
51
- ownerEscalation -->|Contract unchanged| recordEscalation[Maestro records all answers]
51
+ ownerEscalation -->|Spec unchanged| recordEscalation[Maestro records all answers]
52
52
  recordEscalation --> build
53
- ownerEscalation -->|Contract changes| reviseSpec[Owner and Maestro revise the spec]
53
+ ownerEscalation -->|Spec changes| reviseSpec[Owner and Maestro revise the spec]
54
54
  reviseSpec --> approval
55
55
 
56
56
  buildOutcome -->|Failed| stopped[Workflow stops for manual owner follow-up]
@@ -69,124 +69,124 @@ flowchart TD
69
69
 
70
70
  ## Workflow phases
71
71
 
72
- Each spec has a `workflow.json` file that records its identity and current phase. The saved phase controls the next permitted workflow action. An agent's final message alone does not establish a completed action.
72
+ Each `spec` has a `workflow.json` file that records its identity and current phase. The saved phase controls the next permitted workflow action. An agent's final message alone does not establish a completed action.
73
73
 
74
- The default path is `.specs/<spec-id>/workflow.json`. The spec directory is [configurable](configuration.md).
74
+ The default path is `.specs/<spec-id>/workflow.json`. The `spec` directory is [configurable](configuration.md).
75
75
 
76
76
  | Phase | Meaning |
77
77
  |---|---|
78
- | `drafting-spec` | The owner and Maestro are preparing the initial spec. |
79
- | `ready-for-builder` | The approved spec or recorded owner decisions permit a builder run. |
80
- | `builder-running` | A builder run is active. |
81
- | `escalation-decision` | The owner must decide how to handle every escalation question. |
82
- | `builder-failed` | The builder recorded a technical failure. The workflow stops. |
83
- | `ready-for-verifier` | The builder completed the work and the verifier can start. |
84
- | `verifier-running` | A verifier run is active. |
85
- | `findings-decision` | The owner must decide how to handle every current finding. |
86
- | `candidate-ready` | The verifier reported no findings, or the owner rejected every finding with a reason. The workflow is complete. |
78
+ | `drafting-spec` | The `owner` and `Maestro` are preparing the initial `spec`. |
79
+ | `ready-for-builder` | The approved `spec` or recorded `owner` decisions permit a `builder` `run`. |
80
+ | `builder-running` | A `builder` `run` is active. |
81
+ | `escalation-decision` | The `owner` must decide how to handle every `escalation` question. |
82
+ | `builder-failed` | The `builder` recorded a technical failure. The workflow stops. |
83
+ | `ready-for-verifier` | The `builder` completed the work and the `verifier` can start. |
84
+ | `verifier-running` | A `verifier` `run` is active. |
85
+ | `findings-decision` | The `owner` must decide how to handle every current `finding`. |
86
+ | `candidate-ready` | The `verifier` reported no `findings`, or the `owner` rejected every `finding` with a reason. The workflow is complete. |
87
87
 
88
88
  ## Spec approval
89
89
 
90
- For the initial spec:
90
+ For the initial `spec`:
91
91
 
92
- 1. Maestro creates `spec.md` and `workflow.json` in `drafting-spec` and prepares the spec with the owner.
93
- 2. The owner reviews the requirements, scope, technical decisions, and acceptance criteria.
94
- 3. Maestro asks the owner to inspect the current `spec.md` and reply `GREEN FLAG` to approve it and start the builder.
95
- 4. After that reply, Maestro saves `ready-for-builder` and starts the builder in the foreground.
92
+ 1. `Maestro` creates `spec.md` and `workflow.json` in `drafting-spec` and prepares the `spec` with the `owner`.
93
+ 2. The `owner` reviews the requirements, scope, technical decisions, and `acceptance criteria`.
94
+ 3. `Maestro` asks the `owner` to inspect the current `spec.md` and reply `GREEN FLAG` to approve it and start the `builder`.
95
+ 4. After that reply, `Maestro` saves `ready-for-builder` and starts the `builder` in the foreground.
96
96
 
97
- Approval freezes the spec as the contract. The spec and its visual prototypes remain unchanged during builder and verifier execution. Contract revisions are limited to the decision phases described in [Spec revision](#spec-revision).
97
+ Approval freezes the `spec`. The `spec` and its visual prototypes remain unchanged during `builder` and `verifier` execution. `Spec` revisions are limited to the decision phases described in [Spec revision](#spec-revision).
98
98
 
99
99
  ## Acceptance criteria
100
100
 
101
- Each acceptance criterion has a unique ID and describes one observable result.
101
+ Each `acceptance criterion` has a unique ID and describes one observable result.
102
102
 
103
103
  Each criterion contains these parts:
104
104
 
105
105
  | Part | Content |
106
106
  |---|---|
107
- | Probe | Starting conditions and the action or observation that checks the behavior. |
108
- | Expected result | The measurable result the probe observes. |
109
- | Example | Concrete starting conditions, an input or action, and the exact expected result. |
107
+ | `Probe` | Starting conditions and the action or observation that checks the behavior. |
108
+ | `Expected result` | The measurable result the `probe` observes. |
109
+ | Example | Concrete starting conditions, an input or action, and the exact `expected result`. |
110
110
 
111
111
  ## Escalations
112
112
 
113
- An escalation returns an implementation decision to the owner. It does not necessarily mean that a technical failure occurred. Examples include undefined behavior, a conflict with the spec, or a possible scope change.
113
+ An `escalation` returns an implementation decision to the `owner`. It does not necessarily mean that a technical failure occurred. Examples include undefined behavior, a conflict with the `spec`, or a possible scope change.
114
114
 
115
- 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.
115
+ 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.
116
116
 
117
- Maestro presents each question, evidence, options, consequences, and next steps. The workflow pauses in `escalation-decision` while the owner decides how to proceed.
117
+ `Maestro` presents each question, evidence, options, consequences, and next steps. The workflow pauses in `escalation-decision` while the `owner` decides how to proceed.
118
118
 
119
- If the contract stays unchanged, the owner gives Maestro an answer and reason for every current question. The owner can select a listed option or give a different decision.
119
+ If the `spec` stays unchanged, the `owner` gives `Maestro` an answer and reason for every current question. The `owner` can select a listed option or give a different decision.
120
120
 
121
- | Owner choice | Result |
121
+ | `Owner` choice | Result |
122
122
  |---|---|
123
- | Keep the current contract | Maestro saves all answers and reasons together in the active builder handoff, returns to `ready-for-builder`, and starts another builder run. |
124
- | Change the contract | The owner and Maestro revise the same spec and obtain renewed approval before another builder run. |
123
+ | Keep the current `spec` | `Maestro` saves all answers and reasons together in the active `builder` `handoff`, returns to `ready-for-builder`, and starts another `builder` `run`. |
124
+ | Change the `spec` | The `owner` and `Maestro` revise the same `spec` and obtain renewed approval before another `builder` `run`. |
125
125
 
126
- Owner decisions update only the questions' `resolution` fields. The handoff's other content and earlier handoffs remain unchanged.
126
+ `Owner` decisions update only the questions' `resolution` fields. The handoff's other content and earlier `handoffs` remain unchanged.
127
127
 
128
128
  ## Findings
129
129
 
130
- Every current finding requires an owner decision, regardless of severity. Maestro explains the issue, evidence, practical effect, and available choices.
130
+ Every current `finding` requires an `owner` decision, regardless of severity. `Maestro` explains the issue, evidence, practical effect, and available choices.
131
131
 
132
- 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.
132
+ `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.
133
133
 
134
- 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`).
134
+ `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`).
135
135
 
136
136
  | Decision | Result |
137
137
  |---|---|
138
- | `reject` | Records the owner's reason. If every finding is rejected, the workflow reaches `candidate-ready`. |
139
- | `fix-code` | Keeps the current spec and returns to `ready-for-builder` for code fixes. |
138
+ | `reject` | Records the owner's reason. If every `finding` is rejected, the workflow reaches `candidate-ready`. |
139
+ | `fix-code` | Keeps the current `spec` and returns to `ready-for-builder` for code fixes. |
140
140
 
141
- 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.
141
+ 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.
142
142
 
143
- If the contract must change, the owner and Maestro use [Spec revision](#spec-revision) instead. Earlier findings then become historical context.
143
+ If the `spec` must change, the `owner` and `Maestro` use [Spec revision](#spec-revision) instead. Earlier `findings` then become historical context.
144
144
 
145
145
  ## Spec revision
146
146
 
147
- Contract revisions are allowed only in `escalation-decision` or `findings-decision`. Maestro revises the same spec with the owner, including its prototypes when needed.
147
+ `Spec` revisions are allowed only in `escalation-decision` or `findings-decision`. `Maestro` revises the same `spec` with the `owner`, including its prototypes when needed.
148
148
 
149
- After review and cleanup, Maestro asks the owner to inspect the revised spec and reply `GREEN FLAG` again. Maestro then records `ready-for-builder` and starts another builder run.
149
+ After review and cleanup, `Maestro` asks the `owner` to inspect the revised `spec` and reply `GREEN FLAG` again. `Maestro` then records `ready-for-builder` and starts another `builder` `run`.
150
150
 
151
- Previous escalations, findings, and handoffs remain as historical context. The new (revised) spec is the contract for subsequent work.
151
+ Previous `escalations`, `findings`, and `handoffs` remain as historical context. The revised `spec` defines the requirements for subsequent work.
152
152
 
153
153
  ## Verification boundary
154
154
 
155
- 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.
155
+ 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.
156
156
 
157
- Cleanup relies on the verifier. If cleanup cannot finish safely, the verifier stops and reports the remaining changes.
157
+ Cleanup relies on the `verifier`. If cleanup cannot finish safely, the `verifier` stops and reports the remaining changes.
158
158
 
159
159
  ## Workflow completion
160
160
 
161
- The workflow ends at `candidate-ready`. Maestro summarizes the changes, verification results, rejected findings and reasons, and relevant builder notes from the saved artifacts.
161
+ The workflow ends at `candidate-ready`. `Maestro` summarizes the changes, verification results, rejected `findings` and reasons, and relevant `builder` notes from the saved `artifacts`.
162
162
 
163
- The owner performs the final review and controls any later Git use, pull request, or merge. Changes after completion are outside the completed verification.
163
+ The `owner` performs the final review and controls any later Git use, pull request, or merge. Changes after completion are outside the completed verification.
164
164
 
165
165
  ## Stored artifacts
166
166
 
167
- An artifact is a saved workflow file. Maestro creates the spec directory with `spec.md`, `workflow.json`, and an empty `prototypes/` directory. Builder and verifier handoff directories appear when those results are saved.
167
+ An `artifact` is a saved workflow file. `Maestro` creates the `spec` directory with `spec.md`, `workflow.json`, and an empty `prototypes/` directory. `Builder` and `verifier` `handoff` directories appear when those results are saved.
168
168
 
169
- 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.
169
+ 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.
170
170
 
171
- Builder (`B`) and verifier (`V`) numbers count saved handoffs within one spec. Each sequence starts at 1 and advances independently. Every saved builder outcome, including escalation, creates the next `B` report. Revising the same spec keeps these sequences. A new spec starts new sequences.
171
+ `Builder` (`B`) and `verifier` (`V`) numbers count saved `handoffs` within one `spec`. Each sequence starts at 1 and advances independently. Every saved `builder` outcome, including `escalation`, creates the next `B` report. Revising the same `spec` keeps these sequences. A new `spec` starts new sequences.
172
172
 
173
- Escalation (`E`) numbers identify questions within a builder handoff. They restart at `E1` in each handoff.
173
+ `Escalation` (`E`) numbers identify questions within a `builder` `handoff`. They restart at `E1` in each `handoff`.
174
174
 
175
- For example, a repair cycle with successful builder results produces these files:
175
+ For example, a repair cycle with successful `builder` results produces these files:
176
176
 
177
177
  | Step | Action | Report saved or updated |
178
178
  |---|---|---|
179
- | 1 | The builder completes the implementation. | Creates `handoffs/builder/B1.json`. |
180
- | 2 | The verifier checks it and reports findings. | Creates `handoffs/verifier/V1.json`. |
181
- | 3 | The owner decides every finding and requests a code fix. | Updates decisions in the existing `V1.json`. |
182
- | 4 | A new builder run completes the fixes. | Creates `handoffs/builder/B2.json`. |
183
- | 5 | A new verifier run checks the work again and reports no findings. | Creates `handoffs/verifier/V2.json`. The workflow reaches `candidate-ready`. |
179
+ | 1 | The `builder` completes the implementation. | Creates `handoffs/builder/B1.json`. |
180
+ | 2 | The `verifier` checks it and reports `findings`. | Creates `handoffs/verifier/V1.json`. |
181
+ | 3 | The `owner` decides every `finding` and requests a code fix. | Updates decisions in the existing `V1.json`. |
182
+ | 4 | A new `builder` `run` completes the fixes. | Creates `handoffs/builder/B2.json`. |
183
+ | 5 | A new `verifier` `run` checks the work again and reports no `findings`. | Creates `handoffs/verifier/V2.json`. The workflow reaches `candidate-ready`. |
184
184
 
185
- 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`.
185
+ 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`.
186
186
 
187
- A builder report with `status: failed` stops the workflow without a verifier run. If an agent returns without a valid saved result, Maestro stops and reports the error. See [Limitations](#limitations).
187
+ A `builder` report with `status: failed` stops the workflow without a `verifier` `run`. If an agent returns without a valid saved result, `Maestro` stops and reports the error. See [Limitations](#limitations).
188
188
 
189
- The default layout after multiple runs is:
189
+ The default layout after multiple `runs` is:
190
190
 
191
191
  ```text
192
192
  .specs/<spec-id>/
@@ -202,18 +202,18 @@ The default layout after multiple runs is:
202
202
  └── prototypes/
203
203
  ```
204
204
 
205
- Maestro uses the latest saved handoff in each role's sequence as the active result. New results do not replace earlier numbered reports. Earlier reports remain available as context, not as proof for the current run. Owner decisions update the active builder or verifier handoff without creating another numbered report.
205
+ `Maestro` uses the latest saved `handoff` in each role's sequence as the active result. New results do not replace earlier numbered reports. Earlier reports remain available as context, not as proof for the current `run`. `Owner` decisions update the active `builder` or `verifier` `handoff` without creating another numbered report.
206
206
 
207
207
  ## Limitations
208
208
 
209
209
  ### No small models
210
- The owner must not use small models with a `low` thinking level for this workflow. These combinations cannot reliably follow the workflow rules.
210
+ The `owner` must not use small models with a `low` thinking level for this workflow. These combinations cannot reliably follow the workflow rules.
211
211
  One example is `gpt-luna-6` with `thinking: "low"`.
212
212
 
213
- 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.
213
+ 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.
214
214
 
215
215
  ### No automatic rollback
216
- Maestro provides no automatic rollback, repair, or recovery for failed or interrupted workflows. The files that remain are available for owner inspection. The owner handles the workflow manually.
216
+ `Maestro` provides no automatic rollback, repair, or recovery for failed or interrupted workflows. The files that remain are available for `owner` inspection. The `owner` handles the workflow manually.
217
217
 
218
218
  ### No reconciliation
219
- Disabling Maestro, restarting Pi, or using `/resume` clears live Maestro session state and leaves project files unchanged. Maestro starts disabled in a new or resumed session. Reactivating it does not reconstruct or resume a saved workflow.
219
+ Disabling `Maestro`, restarting Pi, or using `/resume` clears live `Maestro` session state and leaves project files unchanged. `Maestro` starts disabled in a new or resumed session. Reactivating it does not reconstruct or resume a saved workflow.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@emiliosp/pi-maestro",
3
- "version": "0.7.1",
3
+ "version": "0.7.2",
4
4
  "description": "A spec-driven multiagent development workflow for Pi.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -33,10 +33,10 @@
33
33
  "src/",
34
34
  "!**/*.test.ts",
35
35
  "docs/",
36
- "mission.md",
37
- "tech-stack.md",
38
- "roadmap.md",
39
- "changelog.md",
36
+ "MISSION.md",
37
+ "TECH_STACK.md",
38
+ "ROADMAP.md",
39
+ "CHANGELOG.md",
40
40
  "README.md",
41
41
  "LICENSE"
42
42
  ],
package/changelog.md DELETED
@@ -1,85 +0,0 @@
1
- # Changelog
2
-
3
- This file summarizes meaningful changes to the codebase, including behavior, contracts, architecture, and development tools. Git tags identify version boundaries; GitHub Releases are not required. Version-only changes and routine maintenance are omitted.
4
-
5
- ## 0.7.1
6
-
7
- 1. Documented the project mission, current tech stack, owner responsibilities, roadmap, and codebase change history. See [PR #30](https://github.com/emilioSp/pi-maestro/pull/30).
8
- 2. Replaced `TODO.md` with the roadmap and included the four project constitution documents in the npm package.
9
- 3. Updated documentation audits to compare all current documentation and the project constitution with the working tree without requesting a comparison baseline.
10
-
11
- ## 0.7.0
12
-
13
- 1. Stored multiple escalation questions and owner resolutions inside numbered builder handoffs. Earlier handoffs remain available as history. See [PR #27](https://github.com/emilioSp/pi-maestro/pull/27).
14
- 2. Breaking: replaced `maestro_open_escalation` and `maestro_resolve_escalation` with `maestro_record_builder_handoff` and `maestro_resolve_escalations`. Done handoffs require `escalations: []`. Standalone escalation storage was removed without migration or compatibility readers. Artifact versions remain `1.0.0`.
15
- 3. Added LCOV coverage reports and Codecov uploads from CI. See [PR #28](https://github.com/emilioSp/pi-maestro/pull/28).
16
-
17
- Reload Maestro extensions before starting new workflows so sessions use the new tool contracts.
18
-
19
- ## 0.6.2
20
-
21
- Added phase icons, theme colors, and display-only shortening of long spec IDs. Successful activation shows the configured agent settings in a UI-only notice, outside session history and model context. See [PR #26](https://github.com/emilioSp/pi-maestro/pull/26).
22
-
23
- ## 0.6.0
24
-
25
- 1. Removed Git requirements, checkpoints, and automatic commits from the workflow. Maestro uses Pi's project directory and saved workflow phase. See [PR #25](https://github.com/emilioSp/pi-maestro/pull/25).
26
- 2. Retained numbered builder and verifier handoffs and explicit owner finding decisions. Removed workflow revision counters and writer locks.
27
- 3. Breaking: changed artifact contracts, handoff paths, and tool results without migration or compatibility readers. Removed revision and commit fields. Artifact versions remain `1.0.0`. Interrupted and older workflows require manual owner handling.
28
-
29
- ## 0.5.2
30
-
31
- Reverted the spec question-dependency instructions introduced in `0.5.1`. See [commit 13cad11](https://github.com/emilioSp/pi-maestro/commit/13cad11).
32
-
33
- ## 0.5.1
34
-
35
- Added instructions to resolve prerequisite decisions before asking dependent spec questions and to review unresolved decisions before approval. These instructions were reverted in `0.5.2`.
36
-
37
- ## 0.5.0
38
-
39
- Removed breakage checks from specs, handoffs, validation, and agent instructions. Breakage checks temporarily introduced faults to test error detection. Acceptance criteria retain probes, expected results, and concrete examples. See [PR #24](https://github.com/emilioSp/pi-maestro/pull/24).
40
-
41
- Breaking: handoffs no longer accept `breakageStatus`. Older handoffs containing that field must be regenerated. Artifact versions remain `1.0.0`.
42
-
43
- ## 0.4.5
44
-
45
- Required a concrete example in every acceptance criterion, both in the spec and when presenting it to the owner. Examples identify starting conditions, an action, and the expected observable result.
46
-
47
- ## 0.4.4
48
-
49
- Expanded Maestro's explanations of findings and escalations with code evidence, concrete examples, available choices, and their consequences. The owner retains control of each decision.
50
-
51
- ## 0.4.3
52
-
53
- Removed explicit builder and verifier tool allowlists and enabled inherited skills. Workflow boundaries remain defined by agent instructions.
54
-
55
- ## 0.4.2
56
-
57
- Made breakage checks optional when the approved spec did not require them. Required acceptance probes remained mandatory. Breakage checks were later removed in `0.5.0`. See [PR #23](https://github.com/emilioSp/pi-maestro/pull/23).
58
-
59
- ## 0.4.1
60
-
61
- Enabled inheritance of global instructions for builder and verifier agents, alongside project context.
62
-
63
- ## 0.4.0
64
-
65
- 1. Fixed delegated handoffs that depended on unavailable parent session memory. See [PR #22](https://github.com/emilioSp/pi-maestro/pull/22).
66
- 2. Removed hash-based spec guards and checkpoint-based verifier comparisons. Spec preservation and restoration rely on agent instructions.
67
- 3. Refreshed the running status before delegation and required repository investigation before presenting technical decisions during spec preparation.
68
-
69
- ## 0.3.0
70
-
71
- Clarified Maestro, builder, and verifier responsibilities, spec and prototype revisions, permitted experiments, evidence requirements, and cleanup. See [PR #21](https://github.com/emilioSp/pi-maestro/pull/21).
72
-
73
- ## 0.2.0
74
-
75
- Moved TypeBox to peer dependencies and loosened Pi peer dependency version constraints. Kept `pi-subagents` bundled with the package.
76
-
77
- ## 0.1.2
78
-
79
- Pinned verifier comparisons to a fixed candidate checkpoint rather than the current HEAD's parent. This checkpoint mechanism was later removed in `0.4.0`. See [PR #20](https://github.com/emilioSp/pi-maestro/pull/20).
80
-
81
- Breaking: renamed `maestro_launch_builder` and `maestro_launch_verifier` to `maestro_run_builder` and `maestro_run_verifier`. Renamed the corresponding workflow events from `launch-*` to `run-*`.
82
-
83
- ## 0.1.1
84
-
85
- First tagged baseline with `/maestro`, spec creation and approval, and foreground builder and verifier runs. The owner decides escalation questions and verifier findings. The workflow ends at `candidate-ready`, leaving final review to the owner. See [PR #14](https://github.com/emilioSp/pi-maestro/pull/14) and [PR #13](https://github.com/emilioSp/pi-maestro/pull/13).
package/mission.md DELETED
@@ -1,7 +0,0 @@
1
- # Mission
2
-
3
- Maestro uses spec-driven development to improve quality when coding with agents. It guides the owner to define requirements and think through a feature before writing code.
4
- It provides a clear path from an approved spec to verified code and manages agent coordination for the owner.
5
-
6
- The owner remains responsible for final code review, pull requests, and merging. The owner also provides and maintains the project's development checks and instructions, including linters, tests, anti-slop checks, and `AGENTS.md`.
7
- Maestro and its agents use these checks and instructions.
package/roadmap.md DELETED
@@ -1,85 +0,0 @@
1
- # Roadmap
2
-
3
- This roadmap records planned outcomes, not permission to implement them. The owner selects work and approves its specification before implementation starts. Detailed requirements, technical decisions, and acceptance criteria belong in that specification.
4
-
5
- "Now" is the current priority. "Next" follows it. “Later” contains uncommitted ideas with no promised order or date.
6
-
7
- Item identifiers remain stable when priorities change. The owner approves changes to priorities and scope.
8
-
9
- ## Completed
10
-
11
- ### R-01: Improve status presentation and activation feedback
12
-
13
- The status bar uses phase icons, theme colors, and shortened spec IDs. Successful activation shows the configured builder and verifier settings without adding the notice to session history or model context. All 12 acceptance criteria passed with no verifier findings; the saved workflow reached `candidate-ready`.
14
-
15
- Evidence: [Specification](.specs/20261007-170438-update-maestro-status-bar-with-agent-models-theme-colors-and-phase-icons/spec.md), [verifier report](.specs/20261007-170438-update-maestro-status-bar-with-agent-models-theme-colors-and-phase-icons/handoffs/verifier/V1.json), and [merged PR #26](https://github.com/emilioSp/pi-maestro/pull/26).
16
-
17
- ### R-02: Store escalations and owner decisions in builder handoffs
18
-
19
- Numbered builder handoffs contain multiple escalation questions and their owner resolutions. The owner resolves all current questions in one batch, while earlier handoffs remain available as history. All 10 acceptance criteria passed with no verifier findings; the saved workflow reached `candidate-ready`.
20
-
21
- Evidence: [Specification](.specs/20261008-132344-store-escalations-in-builder-handoffs/spec.md), [verifier report](.specs/20261008-132344-store-escalations-in-builder-handoffs/handoffs/verifier/V1.json), and [merged PR #27](https://github.com/emilioSp/pi-maestro/pull/27).
22
-
23
- ## Now
24
-
25
- ### R-03: Route builder failures through owner escalations
26
-
27
- A technical builder failure currently ends the workflow in `builder-failed`. Replace the builder's `failed` handoff status and the `builder-failed` workflow phase with an escalation. The owner decides how to proceed through the existing escalation process.
28
-
29
- Complete when builder failures produce owner escalations instead of a terminal failure state. Individual checks retain `failed` as a valid result. Agent instructions, tools, workflow transitions, tests, and documentation must describe the same behavior.
30
-
31
- Automatic recovery of interrupted runs is outside this item. No specification is approved yet.
32
-
33
- ## Next
34
-
35
- ### R-04: Rename the npm package
36
-
37
- Rename `@emiliosp/pi-maestro` to `pi-maestro-sdd`. The owner installs the package under the new name. This item changes the package identity, not the development workflow.
38
-
39
- Complete when package metadata and installation documentation use the new name and the package is available under it. Compatibility with installations under the old name must be decided in the specification. No specification is approved yet.
40
-
41
- ## Later
42
-
43
- These items need scope review before specification approval. Existing behavior must be checked before adding new code. Dependencies between these items are not yet agreed.
44
-
45
- ### R-05: Keep acceptance criterion numbering continuous
46
-
47
- When criteria are removed during spec preparation or revision, renumber the remaining criteria without gaps. Numbering starts at `AC1` and continues through the final criterion. Complete when the spec and its current references use consistent numbering.
48
-
49
- ### R-06: Check subagent extensions at activation
50
-
51
- Make extension availability problems visible before a builder or verifier run starts. Activation already checks agent launch contracts, so first identify any missing extension checks. Complete when unavailable required subagent extensions prevent activation and the error identifies the problem.
52
-
53
- ### R-07: Guide initial configuration
54
-
55
- Help the owner create Maestro configuration through an interview. Maestro asks questions and writes the agreed configuration. Complete when the owner can create a valid project configuration without writing the file manually.
56
-
57
- ### R-08: Change agent models before a builder run
58
-
59
- Let the owner change the builder and verifier models during spec preparation and the `ready-for-builder` phase. The selected models apply to subsequent runs. Complete when the owner can select available models in those phases and Maestro uses the selections.
60
-
61
- ### R-09: Define workflow reconciliation
62
-
63
- Explore how Maestro can reconcile saved artifacts and workflow state. The recovery scope is not yet defined. The owner must define the intended outcome, recovery boundaries, and completion condition before this item can move forward.
64
-
65
- ### R-10: Match handoff criteria to the approved spec
66
-
67
- Prevent builder and verifier reports from omitting or adding acceptance criteria. Each report must contain exactly the criterion IDs in the approved spec, with no duplicates in either place. Existing duplicate checks in reports do not establish this match.
68
-
69
- Complete when both handoff submissions reject missing, extra, or duplicate criterion IDs before saving a report or changing phase. The specification must define the criterion heading format used to extract IDs. For example, a heading can use `### AC1: ...`.
70
-
71
- ### R-11: Reduce temporary verifier changes
72
-
73
- Reduce the risk that verification changes the candidate. Existing instructions already require exact restoration, cleanup, and reporting of unresolved restoration problems. Refine the remaining guidance rather than duplicate those rules.
74
-
75
- Prefer checks that leave existing files unchanged and use separate temporary files when possible. Change an existing file only when a criterion requires it, retain its exact contents, and restore it immediately after each probe, including failed probes. Prefer check-only commands over commands that apply automatic fixes.
76
-
77
- Complete when verifier instructions cover these limits and require restoration and temporary-file cleanup before handoff. If restoration fails, the verifier must stop and report affected paths and remaining changes. Maestro currently has no file-hash restoration check; adding one requires a separate scope decision.
78
-
79
- ### R-12: Format glossary terms consistently
80
-
81
- Use inline code formatting for glossary terms throughout the documentation. This lets the owner recognize the same term across documents. Complete when occurrences of glossary terms consistently use formatting such as `candidate-ready`.
82
-
83
- ### R-13: Show when Maestro is working
84
-
85
- Show an activity indicator in Pi's status bar while progress does not require an owner decision. A spinner is one option, not an agreed implementation. Complete when the status clearly distinguishes work in progress from a request for owner action.