@emiliosp/pi-maestro 0.10.0 → 0.11.0
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.
- package/ADR.md +53 -9
- package/CHANGELOG.md +79 -36
- package/MISSION.md +4 -2
- package/README.md +31 -15
- package/ROADMAP.md +150 -61
- package/TECH_STACK.md +12 -11
- package/agents/simplifier.md +214 -0
- package/agents/verifier.md +1 -16
- package/docs/configuration.md +27 -16
- package/docs/glossary.md +41 -36
- package/docs/subagent-integration.md +23 -13
- package/docs/workflow.md +103 -71
- package/extensions/maestro-subagent.ts +3 -1
- package/extensions/maestro.ts +10 -0
- package/package.json +1 -1
- package/src/MaestroPaths.ts +8 -32
- package/src/artifacts/builder-handoff/assertBuilderHandoff.ts +23 -29
- package/src/artifacts/simplifier-handoff/assertSimplifierHandoff.ts +56 -0
- package/src/artifacts/simplifier-handoff/readSimplifierHandoff.ts +29 -0
- package/src/artifacts/simplifier-handoff/schema.ts +26 -0
- package/src/artifacts/verifier-handoff/assertVerifierHandoff.ts +14 -18
- package/src/config/assertConfiguration.ts +1 -1
- package/src/config/defaults.ts +7 -0
- package/src/config/loadConfiguration.ts +21 -50
- package/src/config/schema.ts +3 -0
- package/src/maestro/checks/assertEnvironment.ts +7 -3
- package/src/maestro/instructions/getMaestroInstructions.ts +27 -9
- package/src/maestro/status/formatMaestroStatus.ts +3 -0
- package/src/specs/create.ts +7 -24
- package/src/tools/child/record-simplifier-handoff.ts +73 -0
- package/src/tools/main/resolve-findings.ts +4 -3
- package/src/tools/main/run-builder.ts +38 -48
- package/src/tools/main/run-simplifier.ts +182 -0
- package/src/tools/main/run-verifier.ts +14 -25
- package/src/utils/path-within-or-equal.ts +3 -4
- package/src/workflow/builder/resolveEscalations.ts +43 -27
- package/src/workflow/roles.ts +2 -1
- package/src/workflow/simplifier/completeSimplifierPass.ts +57 -0
- package/src/workflow/state/schema.ts +4 -0
- package/src/workflow/transitions.ts +13 -6
- package/src/workflow/utils/getAgentRole.ts +5 -1
- package/src/workflow/verifier/resolveFindings.ts +53 -87
- package/templates/spec.md +9 -5
package/docs/configuration.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
## Project root
|
|
6
6
|
|
|
7
|
-
The project root is the current Pi working directory. `Builder` and `
|
|
7
|
+
The project root is the current Pi working directory. `Builder`, `verifier`, and `simplifier` `runs` use this same directory.
|
|
8
8
|
|
|
9
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
|
|
|
@@ -19,6 +19,11 @@ For example, if Pi starts in `/work/app/src`, `Maestro` reads `/work/app/src/.pi
|
|
|
19
19
|
"thinking": "max",
|
|
20
20
|
"timeoutMinutes": 60
|
|
21
21
|
},
|
|
22
|
+
"simplifier": {
|
|
23
|
+
"model": "openai-codex/gpt-6.1-sol",
|
|
24
|
+
"thinking": "high",
|
|
25
|
+
"timeoutMinutes": 60
|
|
26
|
+
},
|
|
22
27
|
"verifier": {
|
|
23
28
|
"model": "openai-codex/gpt-6.1-sol",
|
|
24
29
|
"thinking": "high",
|
|
@@ -29,18 +34,22 @@ For example, if Pi starts in `/work/app/src`, `Maestro` reads `/work/app/src/.pi
|
|
|
29
34
|
|
|
30
35
|
## Fields
|
|
31
36
|
|
|
32
|
-
| Field
|
|
33
|
-
|
|
34
|
-
| `version`
|
|
35
|
-
| `specDirectory`
|
|
36
|
-
| `builder`
|
|
37
|
-
| `builder.model`
|
|
38
|
-
| `builder.thinking`
|
|
39
|
-
| `builder.timeoutMinutes`
|
|
40
|
-
| `verifier`
|
|
41
|
-
| `verifier.model`
|
|
42
|
-
| `verifier.thinking`
|
|
43
|
-
| `verifier.timeoutMinutes`
|
|
37
|
+
| Field | Required | Default | Rules |
|
|
38
|
+
|-----------------------------|--------------------------:|-----------------------------|-----------------------------------------------------------------|
|
|
39
|
+
| `version` | Yes, when the file exists | `1.0.0` | Configuration format version. Only `1.0.0` is supported. |
|
|
40
|
+
| `specDirectory` | No | `.specs` | Relative path below the project root. |
|
|
41
|
+
| `builder` | No | `Builder` defaults | Overrides supported `builder` fields. |
|
|
42
|
+
| `builder.model` | No | `openai-codex/gpt-5.6-luna` | Full `provider/model` identifier. |
|
|
43
|
+
| `builder.thinking` | No | `max` | One supported thinking level. |
|
|
44
|
+
| `builder.timeoutMinutes` | No | `60` | Integer from `1` to `1440`. Applies to each `builder` `run`. |
|
|
45
|
+
| `verifier` | No | `Verifier` defaults | Overrides supported `verifier` fields. |
|
|
46
|
+
| `verifier.model` | No | `openai-codex/gpt-6.1-sol` | Full `provider/model` identifier. |
|
|
47
|
+
| `verifier.thinking` | No | `high` | One supported thinking level. |
|
|
48
|
+
| `verifier.timeoutMinutes` | No | `60` | Integer from `1` to `1440`. Applies to each `verifier` `run`. |
|
|
49
|
+
| `simplifier` | No | `Simplifier` defaults | Overrides supported `simplifier` fields. |
|
|
50
|
+
| `simplifier.model` | No | `openai-codex/gpt-6.1-sol` | Full `provider/model` identifier. |
|
|
51
|
+
| `simplifier.thinking` | No | `high` | One supported thinking level. |
|
|
52
|
+
| `simplifier.timeoutMinutes` | No | `60` | Integer from `1` to `1440`. Applies to each `simplifier` `run`. |
|
|
44
53
|
|
|
45
54
|
Model identifiers use the full `provider/model` form shown in the defaults. `Maestro` accepts these thinking levels:
|
|
46
55
|
|
|
@@ -81,10 +90,12 @@ This example keeps every default except the `builder` timeout.
|
|
|
81
90
|
2. The path stays below that root after `.` and `..` are resolved.
|
|
82
91
|
3. The path is not the project root itself.
|
|
83
92
|
|
|
84
|
-
For example, `specDirectory: "planning/specs"` places `specs` in `<project-root>/planning/specs/`. Absolute paths and paths outside the project root are rejected. The
|
|
93
|
+
For example, `specDirectory: "planning/specs"` places `specs` in `<project-root>/planning/specs/`. Absolute paths and paths outside the project root are rejected. The
|
|
94
|
+
`owner` is responsible for directory permissions that allow `Maestro` to save `artifacts`.
|
|
85
95
|
|
|
86
96
|
## Model access
|
|
87
97
|
|
|
88
|
-
`Maestro` checks
|
|
98
|
+
`Maestro` checks all three configured models during activation. Each model must exist and have valid authentication.
|
|
89
99
|
|
|
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.
|
|
100
|
+
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.
|
|
101
|
+
Agent names and context are described in [Subagent integration](subagent-integration.md#roles-and-context).
|
package/docs/glossary.md
CHANGED
|
@@ -2,45 +2,48 @@
|
|
|
2
2
|
|
|
3
3
|
## Terms
|
|
4
4
|
|
|
5
|
-
| Term
|
|
6
|
-
|
|
7
|
-
| `Owner`
|
|
8
|
-
| `Maestro`
|
|
9
|
-
| `Builder`
|
|
10
|
-
| `Verifier`
|
|
11
|
-
| `
|
|
12
|
-
| `
|
|
13
|
-
| `
|
|
14
|
-
| `
|
|
15
|
-
| `
|
|
16
|
-
| `
|
|
17
|
-
| `
|
|
18
|
-
| `
|
|
19
|
-
| `
|
|
20
|
-
| `
|
|
21
|
-
| `
|
|
22
|
-
| `
|
|
23
|
-
| `
|
|
24
|
-
| `
|
|
25
|
-
| `
|
|
26
|
-
| `
|
|
5
|
+
| Term | Meaning |
|
|
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
|
+
| `Simplifier` | The agent that refactors accepted code for clarity without changing behavior or introducing check failures. |
|
|
12
|
+
| `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`. |
|
|
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 agent report. `Builder` and `verifier` reports include `probe` outcomes. A `simplifier` report includes refactored files, a summary, and notes. |
|
|
18
|
+
| `Observability` | The owner's ability to inspect workflow progress and reported results. |
|
|
19
|
+
| `Run` or `pass` | One agent execution with a fresh conversation. |
|
|
20
|
+
| `Candidate` | The project files created by agents after a workflow `run` |
|
|
21
|
+
| `Finding` | A technical issue that the `verifier` records for an `owner` decision. |
|
|
22
|
+
| `Escalation` | An implementation question or reportable technical problem that the `builder` records in its `handoff` for an `owner` decision. |
|
|
23
|
+
| `GREEN FLAG` | The owner's explicit reply that approves the current `spec` and starts the `builder`. |
|
|
24
|
+
| `fix-code` | An `owner` decision that requests code fixes without changing the approved `spec`. |
|
|
25
|
+
| `revise-spec` | An `owner` decision that records a reason and agreed requirement change, then returns to `drafting-spec` for revision and renewed approval. |
|
|
26
|
+
| `reject` | An `owner` decision that declines a `finding` and records a reason. It does not mean that verification passed. |
|
|
27
|
+
| `candidate-ready` | The completed workflow phase. Final review remains with the `owner`. |
|
|
27
28
|
|
|
28
29
|
## Identifiers and file names
|
|
29
30
|
|
|
30
31
|
An ID is an identifier that names one record. These labels refer to records within one `spec`, not across all workflows.
|
|
31
32
|
|
|
32
|
-
| Label
|
|
33
|
-
|
|
34
|
-
| `<spec-id>`
|
|
35
|
-
| `B1`, `B2`
|
|
36
|
-
| `V1`, `V2`
|
|
37
|
-
| `
|
|
38
|
-
| `
|
|
39
|
-
| `
|
|
40
|
-
| `
|
|
41
|
-
| `
|
|
42
|
-
|
|
43
|
-
|
|
33
|
+
| Label | Meaning | Location or scope |
|
|
34
|
+
|--------------|-------------------------------------------------------------------|---------------------------------------------------------------------------------|
|
|
35
|
+
| `<spec-id>` | The identifier shared by the `spec` and its workflow `artifacts`. | The directory name under `<project-root>/.specs/` by default. |
|
|
36
|
+
| `B1`, `B2` | `Builder` `handoff` 1, `builder` `handoff` 2. | `handoffs/builder/B1.json`, `handoffs/builder/B2.json`. |
|
|
37
|
+
| `V1`, `V2` | `Verifier` `handoff` 1, `verifier` `handoff` 2. | `handoffs/verifier/V1.json`, `handoffs/verifier/V2.json`. |
|
|
38
|
+
| `S.json` | The fixed, unnumbered `simplifier` `handoff`. | `handoffs/simplifier/S.json`. |
|
|
39
|
+
| `E1`, `E2` | `Escalation` 1, `escalation` 2 within one `builder` report. | Entries in that report's `escalations` list. |
|
|
40
|
+
| `F1`, `F2` | `Finding` 1, `finding` 2 within one `verifier` report. | Entries in that report's `findings` list. |
|
|
41
|
+
| `AC1`, `AC2` | `Acceptance criterion` 1, `acceptance criterion` 2. | Criteria in `spec.md` and the matching `acceptanceCriteria` entries in reports. |
|
|
42
|
+
| `B1/E1` | `Escalation` 1 in `builder` `handoff` 1. | The question with `id: "E1"` inside `handoffs/builder/B1.json`. |
|
|
43
|
+
| `V1/F2` | `Finding` 2 in `verifier` `handoff` 1. | The `finding` with `id: "F2"` inside `handoffs/verifier/V1.json`. |
|
|
44
|
+
|
|
45
|
+
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
|
|
46
|
+
contains `specs`.
|
|
44
47
|
|
|
45
48
|
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`.
|
|
46
49
|
|
|
@@ -52,7 +55,8 @@ Read `B1/E1` as "escalation 1 in builder report 1". `B1` selects `handoffs/build
|
|
|
52
55
|
|
|
53
56
|
`Escalation` numbers restart at `E1` in each `builder` report. `B1/E1` and `B2/E1` identify different questions, even if they concern the same topic.
|
|
54
57
|
|
|
55
|
-
The `owner` discusses every current question with `Maestro`. `Maestro` records all answers and reasons together in that same `builder` report.
|
|
58
|
+
The `owner` discusses every current question with `Maestro`. `Maestro` records all answers and reasons together in that same `builder` report.
|
|
59
|
+
See [Escalations](workflow.md#escalations) for the available choices and their effects.
|
|
56
60
|
|
|
57
61
|
## Finding references
|
|
58
62
|
|
|
@@ -67,4 +71,5 @@ For example, a `finding` about a saved title can appear in a `Maestro` message l
|
|
|
67
71
|
|
|
68
72
|
In this example, the finding's `acceptanceCriterion: "AC1"` connects the issue to criterion `AC1` in `spec.md`.
|
|
69
73
|
|
|
70
|
-
The `owner` discusses the issue with `Maestro`. `Maestro` records the decision in the same `verifier` report. See [Findings](workflow.md#findings) for the available
|
|
74
|
+
The `owner` discusses the issue with `Maestro`. `Maestro` records the decision in the same `verifier` report. See [Findings](workflow.md#findings) for the available
|
|
75
|
+
choices and their effects.
|
|
@@ -1,34 +1,44 @@
|
|
|
1
1
|
# Subagent integration
|
|
2
2
|
|
|
3
|
-
`Maestro` uses `pi-subagents` to run the `builder` and `
|
|
3
|
+
`Maestro` uses `pi-subagents` to run the `builder`, `verifier`, and `simplifier` as child sessions. A child session is a separate Pi session for one role. The `owner`
|
|
4
|
+
stays in the main `Maestro` conversation.
|
|
4
5
|
|
|
5
6
|
## Roles and context
|
|
6
7
|
|
|
7
|
-
The package supplies
|
|
8
|
+
The package supplies all three roles and the tools that save their results:
|
|
8
9
|
|
|
9
|
-
| Role
|
|
10
|
-
|
|
11
|
-
| `Builder`
|
|
12
|
-
| `Verifier`
|
|
10
|
+
| Role | Agent name | Definition |
|
|
11
|
+
|--------------|----------------------|---------------------------------------------------|
|
|
12
|
+
| `Builder` | `maestro.builder` | [`agents/builder.md`](../agents/builder.md) |
|
|
13
|
+
| `Verifier` | `maestro.verifier` | [`agents/verifier.md`](../agents/verifier.md) |
|
|
14
|
+
| `Simplifier` | `maestro.simplifier` | [`agents/simplifier.md`](../agents/simplifier.md) |
|
|
13
15
|
|
|
14
|
-
Each `run` starts with a fresh conversation, not the main session's conversation history.
|
|
16
|
+
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`,
|
|
17
|
+
and available skills. The global file normally lives at `~/.pi/agent/AGENTS.md`.
|
|
15
18
|
|
|
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.
|
|
19
|
+
`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.
|
|
20
|
+
Earlier `artifacts` provide context, not proof.
|
|
17
21
|
|
|
18
|
-
The `owner` does not call
|
|
22
|
+
The `owner` does not call agent tools directly. `Maestro` starts the `builder` after `GREEN FLAG` approval. The `verifier` starts after successful `builder` completion,
|
|
23
|
+
and the `simplifier` follows successful `verifier` completion.
|
|
19
24
|
|
|
20
25
|
## Following a run
|
|
21
26
|
|
|
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
|
|
27
|
+
`Runs` stay in the foreground and occur one at a time. Pi waits for each `run` to finish before `Maestro` continues. `Maestro` does not run agents in parallel or in the
|
|
28
|
+
background.
|
|
23
29
|
|
|
24
30
|
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
31
|
|
|
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`,
|
|
32
|
+
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`,
|
|
33
|
+
`V2.json`, and so on. The `simplifier` saves the unnumbered `handoffs/simplifier/S.json`. See [Stored artifacts](workflow.md#stored-artifacts) for the creation sequence.
|
|
27
34
|
|
|
28
35
|
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
36
|
|
|
30
37
|
## External configuration
|
|
31
38
|
|
|
32
|
-
The `pi-subagents` extension must be installed and enabled in Pi. `Builder` and `
|
|
39
|
+
The `pi-subagents` extension must be installed and enabled in Pi. `Builder`, `verifier`, and `simplifier` model choices, thinking levels, and timeouts come
|
|
40
|
+
from [Maestro configuration](configuration.md). Other `pi-subagents` configuration remains the owner's responsibility.
|
|
33
41
|
|
|
34
|
-
`
|
|
42
|
+
Only `maestro_run_simplifier` checks Git readiness, with `git rev-parse --is-inside-work-tree`.
|
|
43
|
+
If readiness cannot be confirmed, it warns and completes without delegation.
|
|
44
|
+
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
CHANGED
|
@@ -4,38 +4,41 @@
|
|
|
4
4
|
|
|
5
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 coverage label, 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
|
|
9
|
+
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.
|
|
10
10
|
|
|
11
11
|
A `builder` `handoff` can contain `escalations`, which are questions that need `owner` decisions.
|
|
12
12
|
A `verifier` `handoff` can contain `findings`, which are technical issues.
|
|
13
13
|
|
|
14
14
|
## Roles
|
|
15
15
|
|
|
16
|
-
| Role
|
|
17
|
-
|
|
18
|
-
| `Owner`
|
|
19
|
-
| `Maestro`
|
|
20
|
-
| `Builder`
|
|
21
|
-
| `Verifier`
|
|
16
|
+
| Role | Responsibility |
|
|
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 or an `escalation`, including technical problems that prevent completion. |
|
|
21
|
+
| `Verifier` | Independently runs every `probe` against the live project files. Reports `findings` without repairing product code. |
|
|
22
|
+
| `Simplifier` | Refactors accepted code for clarity without changing behavior or introducing check failures. |
|
|
22
23
|
|
|
23
|
-
`Builder` and `
|
|
24
|
+
`Builder`, `verifier`, and `simplifier` `runs` are sequential foreground operations. Each starts with a fresh conversation and reads the `spec` and saved `artifacts`.
|
|
24
25
|
|
|
25
26
|
## Observability
|
|
26
27
|
|
|
27
|
-
`Observability` is the owner's ability to inspect workflow progress and reported results.
|
|
28
|
+
`Observability` is the owner's ability to inspect workflow progress and reported results.
|
|
28
29
|
|
|
29
|
-
Maestro's Pi status shows the current phase.
|
|
30
|
+
Maestro's Pi status shows the current phase.
|
|
30
31
|
|
|
31
32
|
`pi-subagents` FleetView and `/subagents-fleet` show live agent activity and transcripts.
|
|
32
33
|
|
|
33
34
|
Saved `handoffs` provide a structured account of each reported `run`.
|
|
34
|
-
The `builder` reports its outcome, `probe` results, notes, and any `escalation` questions.
|
|
35
|
-
The `verifier` reports its independent checks, results, and `findings`.
|
|
35
|
+
The `builder` reports its outcome, `probe` results, notes, and any `escalation` questions.
|
|
36
|
+
The `verifier` reports its independent checks, results, and `findings`.
|
|
37
|
+
The `simplifier` reports its refactoring separately.
|
|
36
38
|
Recorded `owner` decisions explain how questions and issues were resolved. Earlier numbered reports remain available for inspection.
|
|
37
39
|
|
|
38
|
-
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
|
|
40
|
+
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
|
|
41
|
+
independently and which issues it found.
|
|
39
42
|
|
|
40
43
|
## Main flow
|
|
41
44
|
|
|
@@ -49,51 +52,50 @@ flowchart TD
|
|
|
49
52
|
buildOutcome{Builder outcome}
|
|
50
53
|
verify[Verifier checks live project files]
|
|
51
54
|
findings{Findings?}
|
|
55
|
+
simplify[Simplifier refactors accepted code or skips if Git is unavailable]
|
|
52
56
|
candidate[Candidate ready]
|
|
53
57
|
summary[Maestro summarizes results]
|
|
54
58
|
review[Owner performs the final review]
|
|
55
|
-
|
|
56
59
|
spec --> approval
|
|
57
60
|
approval --> build
|
|
58
61
|
build --> buildOutcome
|
|
59
62
|
buildOutcome -->|Done| verify
|
|
60
63
|
verify --> findings
|
|
61
|
-
findings -->|None|
|
|
62
|
-
|
|
64
|
+
findings -->|None| simplify
|
|
63
65
|
buildOutcome -->|Escalation| ownerEscalation{Owner decides every question}
|
|
64
66
|
ownerEscalation --> recordEscalation[Maestro records all answers]
|
|
65
67
|
recordEscalation -->|Spec unchanged| build
|
|
66
68
|
recordEscalation -->|Spec changes| reviseSpec[Owner and Maestro revise the spec]
|
|
67
69
|
reviseSpec --> approval
|
|
68
|
-
|
|
69
70
|
findings -->|One or more| ownerFindings[Owner decides every finding]
|
|
70
71
|
ownerFindings --> recordFindings[Maestro records all decisions]
|
|
71
|
-
recordFindings -->|Reject all with reasons|
|
|
72
|
+
recordFindings -->|Reject all with reasons| simplify
|
|
72
73
|
recordFindings -->|Fix code without spec changes| build
|
|
73
74
|
recordFindings -->|Spec changes| reviseSpec
|
|
74
|
-
|
|
75
|
+
simplify --> candidate
|
|
75
76
|
candidate --> summary
|
|
76
77
|
summary --> review
|
|
77
|
-
|
|
78
|
-
linkStyle 0,1,2,3,4,5,16,17 stroke:#2e7d32,stroke-width:3px
|
|
78
|
+
linkStyle 0,1,2,3,4,5,16,17,18 stroke: #2e7d32, stroke-width: 3px
|
|
79
79
|
```
|
|
80
80
|
|
|
81
81
|
## Workflow phases
|
|
82
82
|
|
|
83
|
-
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
|
|
83
|
+
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
|
|
84
|
+
alone does not establish a completed action.
|
|
84
85
|
|
|
85
86
|
The default path is `.specs/<spec-id>/workflow.json`. The `spec` directory is [configurable](configuration.md).
|
|
86
87
|
|
|
87
|
-
| Phase
|
|
88
|
-
|
|
89
|
-
| `drafting-spec`
|
|
90
|
-
| `ready-for-builder`
|
|
91
|
-
| `builder-running`
|
|
92
|
-
| `escalation-decisions` | The `owner` must decide how to handle every `escalation` question.
|
|
93
|
-
| `ready-for-verifier`
|
|
94
|
-
| `verifier-running`
|
|
95
|
-
| `finding-decisions`
|
|
96
|
-
| `
|
|
88
|
+
| Phase | Meaning |
|
|
89
|
+
|------------------------|--------------------------------------------------------------------------------------------------------------------------------|
|
|
90
|
+
| `drafting-spec` | The `owner` and `Maestro` prepare the initial `spec` or revise it after recorded `escalation` answers or `finding` decisions. |
|
|
91
|
+
| `ready-for-builder` | The approved `spec` or recorded `owner` decisions permit a `builder` `run`. |
|
|
92
|
+
| `builder-running` | A `builder` `run` is active. |
|
|
93
|
+
| `escalation-decisions` | The `owner` must decide how to handle every `escalation` question. |
|
|
94
|
+
| `ready-for-verifier` | The `builder` completed the work and the `verifier` can start. |
|
|
95
|
+
| `verifier-running` | A `verifier` `run` is active. |
|
|
96
|
+
| `finding-decisions` | The `owner` must decide how to handle every current `finding`. |
|
|
97
|
+
| `simplifier-running` | Verification succeeded or the `owner` rejected all current `findings`. The `simplifier` can run or skip if Git is unavailable. |
|
|
98
|
+
| `candidate-ready` | Simplification completed. The workflow is complete. |
|
|
97
99
|
|
|
98
100
|
## Spec approval
|
|
99
101
|
|
|
@@ -104,7 +106,8 @@ For the initial `spec`:
|
|
|
104
106
|
3. `Maestro` asks the `owner` to inspect the current `spec.md` and reply `GREEN FLAG` to approve it and start the `builder`.
|
|
105
107
|
4. After that reply, `Maestro` saves `ready-for-builder` and starts the `builder` in the foreground.
|
|
106
108
|
|
|
107
|
-
Approval freezes the `spec`. The `spec` and its visual prototypes remain unchanged during `builder` and `
|
|
109
|
+
Approval freezes the `spec`. The `spec` and its visual prototypes remain unchanged during `builder`, `verifier`, and `simplifier` execution.
|
|
110
|
+
See [Spec revision](#spec-revision) for permitted revisions.
|
|
108
111
|
|
|
109
112
|
## Acceptance criteria
|
|
110
113
|
|
|
@@ -112,18 +115,20 @@ Each `acceptance criterion` has a unique ID and describes one observable result.
|
|
|
112
115
|
|
|
113
116
|
Each criterion contains these parts:
|
|
114
117
|
|
|
115
|
-
| Part
|
|
116
|
-
|
|
117
|
-
|
|
|
118
|
-
| `
|
|
119
|
-
|
|
|
118
|
+
| Part | Content |
|
|
119
|
+
|-------------------|-------------------------------------------------------------------------------------|
|
|
120
|
+
| Coverage | One label that states the scenario's purpose: `success`, `failure`, or `unchanged`. |
|
|
121
|
+
| `Probe` | Starting conditions and the action or observation that checks the behavior. |
|
|
122
|
+
| `Expected result` | The measurable result the `probe` observes. |
|
|
123
|
+
| Example | Concrete starting conditions, an input or action, and the exact `expected result`. |
|
|
120
124
|
|
|
121
125
|
## Escalations
|
|
122
126
|
|
|
123
|
-
An `escalation` returns an implementation decision or a technical problem to the `owner`.
|
|
127
|
+
An `escalation` returns an implementation decision or a technical problem to the `owner`.
|
|
124
128
|
For instance a technical failure, an undefined behavior, a conflict with the `spec`, or a possible scope change.
|
|
125
129
|
|
|
126
|
-
The `builder` saves all questions from one `pass` in the `escalations` list of its numbered `handoff`. `Maestro` identifies each question with both report and
|
|
130
|
+
The `builder` saves all questions from one `pass` in the `escalations` list of its numbered `handoff`. `Maestro` identifies each question with both report and
|
|
131
|
+
`escalation` IDs, such as `B1/E1`. See [Escalation references](glossary.md#escalation-references) for their scope.
|
|
127
132
|
|
|
128
133
|
`Maestro` presents each question, evidence, options, consequences, and next steps. The workflow pauses in `escalation-decisions` while the `owner` decides how to proceed.
|
|
129
134
|
|
|
@@ -132,10 +137,10 @@ The `owner` can select a listed option or give a different decision.
|
|
|
132
137
|
|
|
133
138
|
`Maestro` saves all answers in the current `builder` `handoff` before the workflow continues.
|
|
134
139
|
|
|
135
|
-
| `Owner` choice
|
|
136
|
-
|
|
137
|
-
| Keep the current `spec` | `Maestro` starts another `builder` `run` without renewed approval.
|
|
138
|
-
| Change the `spec`
|
|
140
|
+
| `Owner` choice | Result |
|
|
141
|
+
|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
|
|
142
|
+
| Keep the current `spec` | `Maestro` starts another `builder` `run` without renewed approval. |
|
|
143
|
+
| Change the `spec` | The `owner` and `Maestro` revise the same `spec`. The `owner` reviews it and replies `GREEN FLAG` before another `builder` `run`. |
|
|
139
144
|
|
|
140
145
|
`Owner` decisions update only the questions' `resolution` fields. The handoff's other content and earlier `handoffs` remain unchanged.
|
|
141
146
|
|
|
@@ -143,15 +148,18 @@ The `owner` can select a listed option or give a different decision.
|
|
|
143
148
|
|
|
144
149
|
Every current `finding` requires an `owner` decision, regardless of severity. `Maestro` explains the issue, evidence, practical effect, and available choices.
|
|
145
150
|
|
|
146
|
-
`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
|
|
151
|
+
`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
|
|
152
|
+
that file's `findings` list, not a separate `F2.json` file. `Finding` numbers restart at `F1` in each `verifier` report.
|
|
153
|
+
See [Finding references](glossary.md#finding-references) for a worked example.
|
|
147
154
|
|
|
148
|
-
`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
|
|
155
|
+
`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
|
|
156
|
+
next report (`V2.json`).
|
|
149
157
|
|
|
150
|
-
| Decision
|
|
151
|
-
|
|
152
|
-
| `reject`
|
|
153
|
-
| `fix-code`
|
|
154
|
-
| `revise-spec` | Records the owner's reason and agreed requirement change, then returns to `drafting-spec`.
|
|
158
|
+
| Decision | Result |
|
|
159
|
+
|---------------|----------------------------------------------------------------------------------------------------------------|
|
|
160
|
+
| `reject` | Records the owner's reason. If every `finding` is rejected, the workflow reaches `simplifier-running`. |
|
|
161
|
+
| `fix-code` | Keeps the current `spec` and returns to `ready-for-builder` for code fixes when no decision requires revision. |
|
|
162
|
+
| `revise-spec` | Records the owner's reason and agreed requirement change, then returns to `drafting-spec`. |
|
|
155
163
|
|
|
156
164
|
`Maestro` saves every current decision together before the phase changes.
|
|
157
165
|
If any `finding` requires revision, revision takes priority over code fixes and rejections. See [Spec revision](#spec-revision).
|
|
@@ -174,40 +182,56 @@ Earlier `escalations`, `findings`, and their decisions remain historical context
|
|
|
174
182
|
|
|
175
183
|
## Verification boundary
|
|
176
184
|
|
|
177
|
-
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
|
|
185
|
+
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
|
|
186
|
+
it created.
|
|
178
187
|
|
|
179
188
|
Cleanup relies on the `verifier`. If cleanup cannot finish safely, the `verifier` stops and reports the remaining changes.
|
|
180
189
|
|
|
190
|
+
## Simplification
|
|
191
|
+
|
|
192
|
+
After a successful verification, Maestro starts the `simplifier`.
|
|
193
|
+
The `simplifier` runs only if Git is available, if not, a warning is displayed: `Simplifier skipped: Git repository unavailable.`
|
|
194
|
+
|
|
195
|
+
The `simplifier` starts from all staged, unstaged, and untracked code changes, including pre-existing changes. It preserves observable behavior and introduces no new
|
|
196
|
+
check failures.
|
|
197
|
+
If no code needs refactoring, the `simplifier` does not make any change.
|
|
198
|
+
|
|
181
199
|
## Workflow completion
|
|
182
200
|
|
|
183
|
-
The workflow ends at `candidate-ready`.
|
|
201
|
+
The workflow ends at `candidate-ready`.
|
|
202
|
+
`Maestro` summarizes the changes, verification results, rejected `findings` and reasons, relevant `builder` notes from the saved `artifacts`, and simplifier's summary and
|
|
203
|
+
notes
|
|
184
204
|
|
|
185
205
|
The `owner` performs the final review and controls any later Git use, pull request, or merge. Changes after completion are outside the completed verification.
|
|
186
206
|
|
|
187
207
|
## Stored artifacts
|
|
188
208
|
|
|
189
|
-
An `artifact` is a saved workflow file. `Maestro` creates the `spec` directory with `spec.md`, `workflow.json`, and an empty `prototypes/` directory. `Builder
|
|
209
|
+
An `artifact` is a saved workflow file. `Maestro` creates the `spec` directory with `spec.md`, `workflow.json`, and an empty `prototypes/` directory. `Builder`,
|
|
210
|
+
`verifier`, and `simplifier` `handoff` directories appear when those results are saved.
|
|
190
211
|
|
|
191
|
-
The agents submit results through `Maestro` tools instead of writing the reports directly. A successful submission saves the result and updates the phase in
|
|
212
|
+
The agents submit results through `Maestro` tools instead of writing the reports directly. A successful submission saves the result and updates the phase in
|
|
213
|
+
`workflow.json` before the agent returns.
|
|
192
214
|
|
|
193
|
-
`Builder` (`B`) and `verifier` (`V`) numbers count saved `handoffs` within one `spec`. Each sequence starts at 1 and advances independently. Every saved `builder`
|
|
215
|
+
`Builder` (`B`) and `verifier` (`V`) numbers count saved `handoffs` within one `spec`. Each sequence starts at 1 and advances independently. Every saved `builder`
|
|
216
|
+
outcome, including `escalation`, creates the next `B` report. Revising the same `spec` keeps these sequences. A new `spec` starts new sequences.
|
|
194
217
|
|
|
195
218
|
`Escalation` (`E`) numbers identify questions within a `builder` `handoff`. They restart at `E1` in each `handoff`.
|
|
196
219
|
|
|
197
220
|
For example, a repair cycle with successful `builder` results produces these files:
|
|
198
221
|
|
|
199
|
-
| Step | Action
|
|
200
|
-
|
|
201
|
-
| 1
|
|
202
|
-
| 2
|
|
203
|
-
| 3
|
|
204
|
-
| 4
|
|
205
|
-
| 5
|
|
222
|
+
| Step | Action | Report saved or updated |
|
|
223
|
+
|------|-------------------------------------------------------------------------|---------------------------------------------------------------------------------|
|
|
224
|
+
| 1 | The `builder` completes the implementation. | Creates `handoffs/builder/B1.json`. |
|
|
225
|
+
| 2 | The `verifier` checks it and reports `findings`. | Creates `handoffs/verifier/V1.json`. |
|
|
226
|
+
| 3 | The `owner` decides every `finding` and requests a code fix. | Updates decisions in the existing `V1.json`. |
|
|
227
|
+
| 4 | A new `builder` `run` completes the fixes. | Creates `handoffs/builder/B2.json`. |
|
|
228
|
+
| 5 | A new `verifier` `run` checks the work again and reports no `findings`. | Creates `handoffs/verifier/V2.json`. The workflow reaches `simplifier-running`. |
|
|
229
|
+
| 6 | The `simplifier` completes its refactoring. | Creates `handoffs/simplifier/S.json`, then saves `candidate-ready`. |
|
|
206
230
|
|
|
207
231
|
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`.
|
|
208
232
|
|
|
209
233
|
A `builder` report has `status: done` or `status: escalation`. A `done` report requires every recorded `probe` to pass and an empty `escalations` list.
|
|
210
|
-
An `escalation` retains actual `probe` results: `passed`, `failed`, or `not-run`.
|
|
234
|
+
An `escalation` retains actual `probe` results: `passed`, `failed`, or `not-run`.
|
|
211
235
|
|
|
212
236
|
Execution errors or missing or invalid saved results stop the workflow. See [Limitations](#limitations).
|
|
213
237
|
|
|
@@ -221,26 +245,34 @@ The default layout after multiple `runs` is:
|
|
|
221
245
|
│ ├── builder/
|
|
222
246
|
│ │ ├── B1.json
|
|
223
247
|
│ │ └── B2.json
|
|
224
|
-
│
|
|
225
|
-
│
|
|
226
|
-
│
|
|
248
|
+
│ ├── verifier/
|
|
249
|
+
│ │ ├── V1.json
|
|
250
|
+
│ │ └── V2.json
|
|
251
|
+
│ └── simplifier/
|
|
252
|
+
│ └── S.json
|
|
227
253
|
└── prototypes/
|
|
228
254
|
```
|
|
229
255
|
|
|
230
|
-
`Maestro` uses the latest saved `
|
|
256
|
+
`Maestro` uses the latest saved `builder` and `verifier` `handoffs` as their active results. New results do not replace earlier numbered reports. Earlier reports remain
|
|
257
|
+
available as context, not as proof for the current `run`. `Owner` decisions update the active `builder` or `verifier` `handoff` without creating another numbered report.
|
|
231
258
|
|
|
232
259
|
## Limitations
|
|
233
260
|
|
|
234
261
|
### No small models
|
|
262
|
+
|
|
235
263
|
The `owner` must not use small models with a `low` thinking level for this workflow. These combinations cannot reliably follow the workflow rules.
|
|
236
264
|
One example is `gpt-luna-6` with `thinking: "low"`.
|
|
237
265
|
|
|
238
|
-
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
|
|
266
|
+
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
|
|
267
|
+
these project-specific checks.
|
|
239
268
|
|
|
240
269
|
### No automatic rollback
|
|
270
|
+
|
|
241
271
|
Launch errors, delegation failures, timeouts, interruptions, cancellations, and missing or invalid `handoffs` stop the workflow without a recovery transition.
|
|
242
272
|
If a `run` saves no completed transition, its saved running phase remains unchanged. Partial protocol writes require manual `owner` follow-up.
|
|
243
273
|
`Maestro` provides no automatic rollback, repair, or recovery for these errors. The files that remain are available for `owner` inspection.
|
|
244
274
|
|
|
245
275
|
### No reconciliation
|
|
246
|
-
|
|
276
|
+
|
|
277
|
+
Disabling `Maestro`, restarting Pi, or using `/resume` clears live `Maestro` session state and leaves project files unchanged. `Maestro` starts disabled in a new or
|
|
278
|
+
resumed session. Reactivating it does not reconstruct or resume a saved workflow.
|
|
@@ -1,13 +1,15 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Objective: Compose the Maestro extension for builder and
|
|
2
|
+
* Objective: Compose the Maestro extension for builder, verifier, and simplifier subagent sessions.
|
|
3
3
|
* Used: When Pi starts a Maestro subagent session.
|
|
4
4
|
*/
|
|
5
5
|
|
|
6
6
|
import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
|
|
7
7
|
import { registerRecordBuilderHandoffTool } from '#tools/child/record-builder-handoff.ts';
|
|
8
|
+
import { registerRecordSimplifierHandoffTool } from '#tools/child/record-simplifier-handoff.ts';
|
|
8
9
|
import { registerRecordVerifierHandoffTool } from '#tools/child/record-verifier-handoff.ts';
|
|
9
10
|
|
|
10
11
|
export default (pi: ExtensionAPI): void => {
|
|
11
12
|
registerRecordBuilderHandoffTool(pi);
|
|
12
13
|
registerRecordVerifierHandoffTool(pi);
|
|
14
|
+
registerRecordSimplifierHandoffTool(pi);
|
|
13
15
|
};
|