@emiliosp/pi-maestro 0.18.3 → 0.18.5
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/CHANGELOG.md +4 -0
- package/MANIFESTO.md +37 -0
- package/README.md +4 -0
- package/docs/configuration.md +22 -22
- package/package.json +2 -1
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,10 @@
|
|
|
3
3
|
This file summarizes meaningful changes to the codebase, including behavior, data formats, architecture, and development tools. Git tags identify version boundaries;
|
|
4
4
|
GitHub Releases are not required.
|
|
5
5
|
|
|
6
|
+
## 0.18.5
|
|
7
|
+
|
|
8
|
+
1. Added [The Pi Maestro Manifesto](MANIFESTO.md), linked from the README, explaining the project's motivation and approach to spec-driven development.
|
|
9
|
+
|
|
6
10
|
## 0.18.2
|
|
7
11
|
|
|
8
12
|
1. The `run` progress for `builder`, `verifier`, and `simplifier` now shows only elapsed time and the latest assistant text. The role name and the active tool no longer
|
package/MANIFESTO.md
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# The Pi Maestro Manifesto
|
|
2
|
+
|
|
3
|
+
Pi Maestro started from the need to use an engineering method when working with agents. With simple prompts or the "let’s write a plan" approach, I would sometimes reach
|
|
4
|
+
dead ends and have to start over. Agents would say the work was complete too early, without checking the result enough.
|
|
5
|
+
|
|
6
|
+
Spec-driven development seemed suitable for this problem. So I tried to turn it into a workflow that worked in practice: define the expected behavior, ask one agent to
|
|
7
|
+
implement it, and ask another to check it independently.
|
|
8
|
+
|
|
9
|
+
At first, I tried to do everything through skills. However, I noticed that agents would skip steps in the protocol described in the Markdown files. My impression was that
|
|
10
|
+
following the workflow required too much attention compared to the assigned task.
|
|
11
|
+
|
|
12
|
+
The workflow must be enforced by code, not by the prompt.
|
|
13
|
+
|
|
14
|
+
So I introduced deterministic tools that control transitions and check the reports produced by agents. Basically, I built a finite state machine where each step requires
|
|
15
|
+
a structured handoff. This handoff also becomes the starting point for the next agent.
|
|
16
|
+
|
|
17
|
+
Taking inspiration from OpenSpec and GitHub Spec Kit, I adopted the concepts that suited the way I work:
|
|
18
|
+
|
|
19
|
+
- `proposal.md` for the context, goal, and scope of the change.
|
|
20
|
+
- `spec.md` for requirements in the form "actor MUST…" and acceptance criteria using `GIVEN`, `WHEN`, `THEN` and concrete examples.
|
|
21
|
+
- `design.md` when important technical decisions are needed.
|
|
22
|
+
|
|
23
|
+
Once the spec is written and approved, the Maestro (orchestrator) starts coordinating a sequence of agents:
|
|
24
|
+
|
|
25
|
+
- Builder, responsible for implementation.
|
|
26
|
+
- Verifier, responsible for checking that everything works as specified.
|
|
27
|
+
- Simplifier, responsible for simplifying the code to make it clearer.
|
|
28
|
+
|
|
29
|
+
Only writing the spec is required. Builder, Verifier, and Simplifier are enabled through configuration. I believe the amount of work done by agents should match the
|
|
30
|
+
difficulty of the change. In some cases, I use Maestro only to prepare the spec, which I then divide into smaller specs.
|
|
31
|
+
|
|
32
|
+
I have chosen Pi because it provides events to control the runtime. This made it easy to add the maestro without going through an MCP server. Pi also works with different
|
|
33
|
+
LLM models. Using different models for each role allows for a more critical view of the spec: a builder and a verifier from the same "family" will approach the problem in
|
|
34
|
+
similar ways.
|
|
35
|
+
|
|
36
|
+
Of course, Maestro alone is not enough. You need clear project rules, clear requirements, tests, and human review of the result. You still need to understand what you are
|
|
37
|
+
building and where you want to go.
|
package/README.md
CHANGED
|
@@ -8,6 +8,8 @@ Pi extension for writing a `spec` and optionally implementing it through a spec-
|
|
|
8
8
|
|
|
9
9
|
## The idea
|
|
10
10
|
|
|
11
|
+
Read [The Pi Maestro Manifesto](MANIFESTO.md) for the motivation behind the project.
|
|
12
|
+
|
|
11
13
|
`Maestro` has two goals:
|
|
12
14
|
|
|
13
15
|
1. Help the `owner` write and approve a `specification` (`spec`) for one reversible change.
|
|
@@ -33,6 +35,8 @@ Five principles hold the workflow together:
|
|
|
33
35
|
4. The `owner` decides requirements, scope, and unresolved questions.
|
|
34
36
|
5. Each agent has one and only one role. Specific and with clear instruction.
|
|
35
37
|
|
|
38
|
+
https://github.com/user-attachments/assets/dffa8bc7-6c79-491f-95df-2ee95b6447aa
|
|
39
|
+
|
|
36
40
|
## Inspirations
|
|
37
41
|
|
|
38
42
|
Pi Maestro is inspired by concepts from [OpenSpec](https://github.com/Fission-AI/OpenSpec) and [GitHub Spec Kit](https://github.com/github/spec-kit). It adapts those
|
package/docs/configuration.md
CHANGED
|
@@ -15,16 +15,16 @@ For example, if Pi starts in `/work/app/src`, `Maestro` reads `/work/app/src/.pi
|
|
|
15
15
|
"version": "1.0.0",
|
|
16
16
|
"specDirectory": ".specs",
|
|
17
17
|
"builder": {
|
|
18
|
-
"required": true,
|
|
19
|
-
"model": "openai-codex/gpt-5.6-luna",
|
|
20
|
-
"thinking": "max"
|
|
21
|
-
},
|
|
22
|
-
"simplifier": {
|
|
23
18
|
"required": true,
|
|
24
19
|
"model": "openai-codex/gpt-6.1-sol",
|
|
25
20
|
"thinking": "high"
|
|
26
21
|
},
|
|
27
22
|
"verifier": {
|
|
23
|
+
"required": true,
|
|
24
|
+
"model": "openai-codex/gpt-6-astra",
|
|
25
|
+
"thinking": "medium"
|
|
26
|
+
},
|
|
27
|
+
"simplifier": {
|
|
28
28
|
"required": true,
|
|
29
29
|
"model": "openai-codex/gpt-6.1-sol",
|
|
30
30
|
"thinking": "high"
|
|
@@ -34,22 +34,22 @@ For example, if Pi starts in `/work/app/src`, `Maestro` reads `/work/app/src/.pi
|
|
|
34
34
|
|
|
35
35
|
## Fields
|
|
36
36
|
|
|
37
|
-
| Field | Required | Default
|
|
38
|
-
| --------------------- | ------------------------: |
|
|
39
|
-
| `version` | Yes, when the file exists | `1.0.0`
|
|
40
|
-
| `specDirectory` | No | `.specs`
|
|
41
|
-
| `builder` | No | `Builder` defaults
|
|
42
|
-
| `builder.required` | No | `true`
|
|
43
|
-
| `builder.model` | No | `openai-codex/gpt-
|
|
44
|
-
| `builder.thinking` | No | `
|
|
45
|
-
| `verifier` | No | `Verifier` defaults
|
|
46
|
-
| `verifier.required` | No | `true`
|
|
47
|
-
| `verifier.model` | No | `openai-codex/gpt-6
|
|
48
|
-
| `verifier.thinking` | No | `
|
|
49
|
-
| `simplifier` | No | `Simplifier` defaults
|
|
50
|
-
| `simplifier.required` | No | `true`
|
|
51
|
-
| `simplifier.model` | No | `openai-codex/gpt-6.1-sol`
|
|
52
|
-
| `simplifier.thinking` | No | `high`
|
|
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.required` | No | `true` | Boolean selecting the `builder` phase. |
|
|
43
|
+
| `builder.model` | No | `openai-codex/gpt-6.1-sol` | Model string passed unchanged to Pi. |
|
|
44
|
+
| `builder.thinking` | No | `high` | One supported thinking level. |
|
|
45
|
+
| `verifier` | No | `Verifier` defaults | Overrides supported `verifier` fields. |
|
|
46
|
+
| `verifier.required` | No | `true` | Boolean selecting the `verifier` phase. |
|
|
47
|
+
| `verifier.model` | No | `openai-codex/gpt-6-astra` | Model string passed unchanged to Pi. |
|
|
48
|
+
| `verifier.thinking` | No | `medium` | One supported thinking level. |
|
|
49
|
+
| `simplifier` | No | `Simplifier` defaults | Overrides supported `simplifier` fields. |
|
|
50
|
+
| `simplifier.required` | No | `true` | Boolean selecting the `simplifier` phase. |
|
|
51
|
+
| `simplifier.model` | No | `openai-codex/gpt-6.1-sol` | Model string passed unchanged to Pi. |
|
|
52
|
+
| `simplifier.thinking` | No | `high` | One supported thinking level. |
|
|
53
53
|
|
|
54
54
|
Model values use the full `provider/model` identifier supplied by Pi's model registry, such as `openrouter/~openai/gpt-mini-latest`. Model IDs may contain additional
|
|
55
55
|
slashes. `Maestro` does not apply a separate format rule; it matches the complete identifier against Pi's available models and uses it unchanged for SDK execution.
|
|
@@ -74,7 +74,7 @@ Only `version` is required when the file exists. Each other field overrides its
|
|
|
74
74
|
{
|
|
75
75
|
"version": "1.0.0",
|
|
76
76
|
"builder": {
|
|
77
|
-
"thinking": "
|
|
77
|
+
"thinking": "medium"
|
|
78
78
|
}
|
|
79
79
|
}
|
|
80
80
|
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@emiliosp/pi-maestro",
|
|
3
|
-
"version": "0.18.
|
|
3
|
+
"version": "0.18.5",
|
|
4
4
|
"description": "A spec-driven multiagent development workflow for Pi.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"orchestration",
|
|
@@ -31,6 +31,7 @@
|
|
|
31
31
|
"TECH_STACK.md",
|
|
32
32
|
"ROADMAP.md",
|
|
33
33
|
"CHANGELOG.md",
|
|
34
|
+
"MANIFESTO.md",
|
|
34
35
|
"ADR.md",
|
|
35
36
|
"README.md",
|
|
36
37
|
"LICENSE"
|