@emiliosp/pi-maestro 0.10.1 → 0.12.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 +94 -18
- package/CHANGELOG.md +87 -33
- package/MISSION.md +4 -4
- package/README.md +66 -22
- package/ROADMAP.md +141 -112
- package/TECH_STACK.md +12 -11
- package/agents/builder.md +53 -57
- package/agents/simplifier.md +232 -0
- package/agents/verifier.md +52 -79
- package/docs/configuration.md +27 -16
- package/docs/glossary.md +47 -39
- package/docs/subagent-integration.md +22 -13
- package/docs/workflow.md +207 -103
- package/extensions/maestro-subagent.ts +4 -1
- package/extensions/maestro.ts +15 -26
- package/package.json +38 -39
- package/src/MaestroPaths.ts +26 -35
- package/src/artifacts/builder-handoff/assertBuilderHandoff.ts +6 -15
- package/src/artifacts/builder-handoff/schema.ts +3 -6
- 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 +27 -0
- package/src/artifacts/verifier-handoff/assertVerifierHandoff.ts +4 -10
- package/src/artifacts/verifier-handoff/schema.ts +3 -6
- package/src/artifacts/verifier-handoff/writeVerifierHandoff.ts +1 -3
- package/src/config/assertConfiguration.ts +4 -7
- package/src/config/defaults.ts +8 -5
- package/src/config/loadConfiguration.ts +5 -11
- package/src/config/schema.ts +4 -2
- package/src/ids/createSpecId.ts +1 -2
- package/src/ids/isValidSpecId.ts +1 -2
- package/src/maestro/checks/assertEnvironment.ts +21 -48
- package/src/maestro/instructions/getMaestroInstructions.ts +59 -30
- package/src/maestro/status/formatMaestroStatus.ts +7 -13
- package/src/maestro/status/refreshMaestroStatus.ts +3 -7
- package/src/specs/create.ts +14 -4
- package/src/specs/template.ts +10 -14
- package/src/tools/child/record-builder-handoff.ts +1 -0
- package/src/tools/child/record-simplifier-handoff.ts +73 -0
- package/src/tools/child/record-verifier-handoff.ts +2 -3
- package/src/tools/child/utils/resolveWorkflowContext.ts +1 -4
- package/src/tools/main/create-spec.ts +3 -2
- package/src/tools/main/mark-spec-ready.ts +2 -1
- package/src/tools/main/resolve-escalations.ts +1 -0
- package/src/tools/main/resolve-findings.ts +7 -21
- package/src/tools/main/run-builder.ts +37 -57
- package/src/tools/main/run-simplifier.ts +172 -0
- package/src/tools/main/run-verifier.ts +34 -58
- package/src/tools/utils/pi-subagent-delegation.ts +13 -22
- package/src/tools/utils/resolveToolRunContext.ts +2 -3
- package/src/utils/is-errno-exception.ts +1 -3
- package/src/utils/path-exists.ts +1 -0
- package/src/utils/path-strictly-within.ts +3 -6
- package/src/utils/path-within-or-equal.ts +1 -4
- package/src/utils/read-json.ts +1 -4
- package/src/utils/write-json.ts +1 -4
- package/src/workflow/builder/completeBuilderPass.ts +3 -2
- package/src/workflow/builder/prepareBuilderRun.ts +3 -8
- package/src/workflow/builder/resolveEscalations.ts +2 -6
- package/src/workflow/builder/utils/getWorkflowEventByBuilderHandoff.ts +1 -3
- package/src/workflow/roles.ts +2 -1
- package/src/workflow/simplifier/completeSimplifierPass.ts +56 -0
- package/src/workflow/spec/markSpecReady.ts +10 -4
- package/src/workflow/state/readWorkflowState.ts +2 -7
- package/src/workflow/state/schema.ts +9 -10
- package/src/workflow/state/writeWorkflowState.ts +1 -4
- package/src/workflow/transitions.ts +12 -12
- package/src/workflow/utils/assertSpecAcceptanceCriteria.ts +2 -1
- package/src/workflow/utils/getAgentRole.ts +6 -4
- package/src/workflow/verifier/completeVerifierPass.ts +1 -0
- package/src/workflow/verifier/resolveFindings.ts +9 -29
- package/src/workflow/verifier/utils/getWorkflowEventByVerifierHandoff.ts +5 -20
- package/templates/design.md +20 -0
- package/templates/proposal.md +23 -0
- package/templates/spec.md +21 -50
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,49 +2,55 @@
|
|
|
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` for one change: `proposal.md` for motivation and scope, `spec.md` for behavior and `acceptance criteria`, and optional `design.md` for technical decisions. The present documents are approved and frozen together. |
|
|
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
|
-
| `
|
|
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
|
+
| `REQ1`, `REQ2` | Requirement 1, requirement 2. | Requirements in `spec.md`, each with a `Verified by` field. |
|
|
42
|
+
| `AC1`, `AC2` | `Acceptance criterion` 1, `acceptance criterion` 2. | Criteria in `spec.md` and the matching `acceptanceCriteria` entries in reports. |
|
|
43
|
+
| `B1/E1` | `Escalation` 1 in `builder` `handoff` 1. | The question with `id: "E1"` inside `handoffs/builder/B1.json`. |
|
|
44
|
+
| `V1/F2` | `Finding` 2 in `verifier` `handoff` 1. | The `finding` with `id: "F2"` inside `handoffs/verifier/V1.json`. |
|
|
42
45
|
|
|
43
|
-
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
|
+
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
|
|
47
|
+
contains `specs`.
|
|
44
48
|
|
|
45
|
-
|
|
49
|
+
Requirement IDs use the `REQ` prefix. They are unique within the `spec` and remain stable during revisions. Each requirement links to its verification through
|
|
50
|
+
`Verified by`. See [Requirement coverage](workflow.md#requirement-coverage).
|
|
46
51
|
|
|
47
|
-
`
|
|
52
|
+
The `AC` prefix is the template's naming convention. Criterion IDs must be unique within the `spec`. Reports use the exact IDs from the `spec`, including standalone
|
|
53
|
+
regression criteria without a requirement association. `Builder` and `verifier` numbers count saved `handoffs` in separate sequences.
|
|
48
54
|
|
|
49
55
|
## Escalation references
|
|
50
56
|
|
|
@@ -52,7 +58,8 @@ Read `B1/E1` as "escalation 1 in builder report 1". `B1` selects `handoffs/build
|
|
|
52
58
|
|
|
53
59
|
`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
60
|
|
|
55
|
-
The `owner` discusses every current question with `Maestro`. `Maestro` records all answers and reasons together in that same `builder` report. See
|
|
61
|
+
The `owner` discusses every current question with `Maestro`. `Maestro` records all answers and reasons together in that same `builder` report. See
|
|
62
|
+
[Escalations](workflow.md#escalations) for the available choices and their effects.
|
|
56
63
|
|
|
57
64
|
## Finding references
|
|
58
65
|
|
|
@@ -62,9 +69,10 @@ Read `V1/F2` as "finding 2 in verifier report 1". `V1` selects `handoffs/verifie
|
|
|
62
69
|
|
|
63
70
|
For example, a `finding` about a saved title can appear in a `Maestro` message like this:
|
|
64
71
|
|
|
65
|
-
> Verifier report 1, finding 2 (`V1/F2`): the title returns to "Draft" after saving "Ready" and reopening the item.
|
|
66
|
-
>
|
|
72
|
+
> Verifier report 1, finding 2 (`V1/F2`): the title returns to "Draft" after saving "Ready" and reopening the item. Acceptance criterion 1 (`AC1`) requires the saved
|
|
73
|
+
> title to remain "Ready".
|
|
67
74
|
|
|
68
75
|
In this example, the finding's `acceptanceCriterion: "AC1"` connects the issue to criterion `AC1` in `spec.md`.
|
|
69
76
|
|
|
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
|
|
77
|
+
The `owner` discusses the issue with `Maestro`. `Maestro` records the decision in the same `verifier` report. See [Findings](workflow.md#findings) for the available
|
|
78
|
+
choices and their effects.
|
|
@@ -1,34 +1,43 @@
|
|
|
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
|
|
19
|
+
`Maestro` supplies the `spec` ID, project directory, model, thinking level, and timeout. The agents read all approved documents (`proposal.md`, `spec.md`, and `design.md`
|
|
20
|
+
when present) and saved `artifacts` to understand the work. 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 from
|
|
40
|
+
[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`. If readiness cannot be confirmed, it warns and completes without
|
|
43
|
+
delegation. The `simplifier` uses Git to select all uncommitted code changes. `Maestro` does not change the Git index or create commits or checkpoints.
|