@emiliosp/pi-maestro 0.10.1 → 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 +73 -33
- package/MISSION.md +4 -2
- package/README.md +29 -14
- package/ROADMAP.md +114 -85
- 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 +102 -71
- package/extensions/maestro-subagent.ts +3 -1
- package/extensions/maestro.ts +10 -0
- package/package.json +1 -1
- package/src/MaestroPaths.ts +4 -0
- 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/config/assertConfiguration.ts +1 -1
- package/src/config/defaults.ts +7 -0
- package/src/config/loadConfiguration.ts +1 -0
- package/src/config/schema.ts +3 -0
- package/src/maestro/checks/assertEnvironment.ts +7 -3
- package/src/maestro/instructions/getMaestroInstructions.ts +16 -6
- package/src/maestro/status/formatMaestroStatus.ts +3 -0
- package/src/tools/child/record-simplifier-handoff.ts +73 -0
- package/src/tools/main/resolve-findings.ts +1 -1
- package/src/tools/main/run-simplifier.ts +182 -0
- package/src/tools/main/run-verifier.ts +5 -5
- 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 +9 -1
- package/src/workflow/utils/getAgentRole.ts +5 -1
package/agents/verifier.md
CHANGED
|
@@ -63,21 +63,6 @@ Use `probeStatus: passed` when the observed result matches the expected result.
|
|
|
63
63
|
Use `failed` for an observed probe failure and `not-run` for an unexecuted probe.
|
|
64
64
|
Include every spec criterion once. Never omit unrun criteria or fabricate evidence.
|
|
65
65
|
|
|
66
|
-
## Review code quality
|
|
67
|
-
|
|
68
|
-
If applicable `AGENTS.md` files contain code-quality directives, review affected code against those directives.
|
|
69
|
-
Review only code affected by the approved change. Do not audit unrelated project code.
|
|
70
|
-
This review supplements all existing duties. Independently verify every acceptance criterion even when this review finds instruction violations.
|
|
71
|
-
Do not treat personal style preferences as requirements or report findings based only on those preferences.
|
|
72
|
-
|
|
73
|
-
For each instruction violation, use the existing finding evidence fields:
|
|
74
|
-
|
|
75
|
-
1. Identify the applicable `AGENTS.md` file in `evidence.source` and quote the violated instruction exactly in `evidence.observation`.
|
|
76
|
-
2. Identify the violating code in `evidence.source` and explain how it violates that instruction in `evidence.observation`.
|
|
77
|
-
|
|
78
|
-
If no applicable `AGENTS.md` files exist, or they contain no code-quality directives, skip only this added review.
|
|
79
|
-
Missing files or directives are not errors or findings. Do not invent directives or require those files to be created.
|
|
80
|
-
|
|
81
66
|
## Record findings, not decisions
|
|
82
67
|
|
|
83
68
|
Record technical issues supported by fresh evidence. Do not add requirements, style preferences, or unrelated improvements.
|
|
@@ -115,5 +100,5 @@ Do not delete artifacts, change workflow state, or bypass the tool to force comp
|
|
|
115
100
|
If restoration or submission cannot be completed safely, report the exact blocker and remaining changes to Maestro and stop.
|
|
116
101
|
|
|
117
102
|
After a successful handoff, return a concise summary and the saved artifact path to Maestro and stop. Do not run more checks.
|
|
118
|
-
The handoff produces `finding-decisions` when findings exist and `
|
|
103
|
+
The handoff produces `finding-decisions` when findings exist and `simplifier-running` when none exist.
|
|
119
104
|
Report that tool result without deciding whether the owner must accept, reject, or fix any finding.
|
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
|
@@ -6,36 +6,39 @@ The approved `spec.md` defines behavior, scope, constraints, technical decisions
|
|
|
6
6
|
|
|
7
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,19 +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
|
-
| Coverage
|
|
118
|
-
| `Probe`
|
|
119
|
-
| `Expected result` | The measurable result the `probe` observes.
|
|
120
|
-
| Example
|
|
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`. |
|
|
121
124
|
|
|
122
125
|
## Escalations
|
|
123
126
|
|
|
124
|
-
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`.
|
|
125
128
|
For instance a technical failure, an undefined behavior, a conflict with the `spec`, or a possible scope change.
|
|
126
129
|
|
|
127
|
-
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.
|
|
128
132
|
|
|
129
133
|
`Maestro` presents each question, evidence, options, consequences, and next steps. The workflow pauses in `escalation-decisions` while the `owner` decides how to proceed.
|
|
130
134
|
|
|
@@ -133,10 +137,10 @@ The `owner` can select a listed option or give a different decision.
|
|
|
133
137
|
|
|
134
138
|
`Maestro` saves all answers in the current `builder` `handoff` before the workflow continues.
|
|
135
139
|
|
|
136
|
-
| `Owner` choice
|
|
137
|
-
|
|
138
|
-
| Keep the current `spec` | `Maestro` starts another `builder` `run` without renewed approval.
|
|
139
|
-
| 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`. |
|
|
140
144
|
|
|
141
145
|
`Owner` decisions update only the questions' `resolution` fields. The handoff's other content and earlier `handoffs` remain unchanged.
|
|
142
146
|
|
|
@@ -144,15 +148,18 @@ The `owner` can select a listed option or give a different decision.
|
|
|
144
148
|
|
|
145
149
|
Every current `finding` requires an `owner` decision, regardless of severity. `Maestro` explains the issue, evidence, practical effect, and available choices.
|
|
146
150
|
|
|
147
|
-
`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.
|
|
148
154
|
|
|
149
|
-
`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`).
|
|
150
157
|
|
|
151
|
-
| Decision
|
|
152
|
-
|
|
153
|
-
| `reject`
|
|
154
|
-
| `fix-code`
|
|
155
|
-
| `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`. |
|
|
156
163
|
|
|
157
164
|
`Maestro` saves every current decision together before the phase changes.
|
|
158
165
|
If any `finding` requires revision, revision takes priority over code fixes and rejections. See [Spec revision](#spec-revision).
|
|
@@ -175,40 +182,56 @@ Earlier `escalations`, `findings`, and their decisions remain historical context
|
|
|
175
182
|
|
|
176
183
|
## Verification boundary
|
|
177
184
|
|
|
178
|
-
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.
|
|
179
187
|
|
|
180
188
|
Cleanup relies on the `verifier`. If cleanup cannot finish safely, the `verifier` stops and reports the remaining changes.
|
|
181
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
|
+
|
|
182
199
|
## Workflow completion
|
|
183
200
|
|
|
184
|
-
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
|
|
185
204
|
|
|
186
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.
|
|
187
206
|
|
|
188
207
|
## Stored artifacts
|
|
189
208
|
|
|
190
|
-
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.
|
|
191
211
|
|
|
192
|
-
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.
|
|
193
214
|
|
|
194
|
-
`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.
|
|
195
217
|
|
|
196
218
|
`Escalation` (`E`) numbers identify questions within a `builder` `handoff`. They restart at `E1` in each `handoff`.
|
|
197
219
|
|
|
198
220
|
For example, a repair cycle with successful `builder` results produces these files:
|
|
199
221
|
|
|
200
|
-
| Step | Action
|
|
201
|
-
|
|
202
|
-
| 1
|
|
203
|
-
| 2
|
|
204
|
-
| 3
|
|
205
|
-
| 4
|
|
206
|
-
| 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`. |
|
|
207
230
|
|
|
208
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`.
|
|
209
232
|
|
|
210
233
|
A `builder` report has `status: done` or `status: escalation`. A `done` report requires every recorded `probe` to pass and an empty `escalations` list.
|
|
211
|
-
An `escalation` retains actual `probe` results: `passed`, `failed`, or `not-run`.
|
|
234
|
+
An `escalation` retains actual `probe` results: `passed`, `failed`, or `not-run`.
|
|
212
235
|
|
|
213
236
|
Execution errors or missing or invalid saved results stop the workflow. See [Limitations](#limitations).
|
|
214
237
|
|
|
@@ -222,26 +245,34 @@ The default layout after multiple `runs` is:
|
|
|
222
245
|
│ ├── builder/
|
|
223
246
|
│ │ ├── B1.json
|
|
224
247
|
│ │ └── B2.json
|
|
225
|
-
│
|
|
226
|
-
│
|
|
227
|
-
│
|
|
248
|
+
│ ├── verifier/
|
|
249
|
+
│ │ ├── V1.json
|
|
250
|
+
│ │ └── V2.json
|
|
251
|
+
│ └── simplifier/
|
|
252
|
+
│ └── S.json
|
|
228
253
|
└── prototypes/
|
|
229
254
|
```
|
|
230
255
|
|
|
231
|
-
`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.
|
|
232
258
|
|
|
233
259
|
## Limitations
|
|
234
260
|
|
|
235
261
|
### No small models
|
|
262
|
+
|
|
236
263
|
The `owner` must not use small models with a `low` thinking level for this workflow. These combinations cannot reliably follow the workflow rules.
|
|
237
264
|
One example is `gpt-luna-6` with `thinking: "low"`.
|
|
238
265
|
|
|
239
|
-
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.
|
|
240
268
|
|
|
241
269
|
### No automatic rollback
|
|
270
|
+
|
|
242
271
|
Launch errors, delegation failures, timeouts, interruptions, cancellations, and missing or invalid `handoffs` stop the workflow without a recovery transition.
|
|
243
272
|
If a `run` saves no completed transition, its saved running phase remains unchanged. Partial protocol writes require manual `owner` follow-up.
|
|
244
273
|
`Maestro` provides no automatic rollback, repair, or recovery for these errors. The files that remain are available for `owner` inspection.
|
|
245
274
|
|
|
246
275
|
### No reconciliation
|
|
247
|
-
|
|
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.
|