@emiliosp/pi-maestro

A spec-driven multiagent development workflow for Pi.

Packages

Package details

extension

Install @emiliosp/pi-maestro from npm and Pi will load the resources declared by the package manifest.

npm repo home report

$ pi install npm:@emiliosp/pi-maestro

Package: @emiliosp/pi-maestro
Version: 0.11.0
Published: Oct 16, 2026
Downloads: 1,995/mo · 1,798/wk
Author: emiliosp
License: MIT
Types: extension
Size: 22.4 MB
Dependencies: 1 dependency · 3 peers

Pi manifest JSON

{
  "subagents": {
    "agents": [
      "./agents"
    ]
  },
  "extensions": [
    "./extensions/maestro.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-maestro

Pi extension for a spec-driven multiagent development workflow.

Maestro workflow

The idea

A specification (spec) describes one reversible change. The builder implements it. An independent verifier checks every acceptance criterion. A simplifier then refactors accepted code without changing behavior. The owner performs the final review.

Five principles hold the workflow together:

The approved spec defines the required work for the builder and verifier.
No agent approves its own work.
Every acceptance criterion is checked independently.
The owner decides requirements, scope, and unresolved questions.
Each agent has one and only one role. Specific and with clear instruction.

The roles

Role	Responsibility
`Owner`	Brings the problem, approves the `spec`, decides questions and `findings`, and reviews the final code.
`Maestro`	Works directly with the `owner`, prepares the `spec`, runs the other agents, records decisions, and summarizes results.
`Builder`	Implements the approved `spec` and checks each `acceptance criterion`.
`Verifier`	Independently checks the project files against the `spec` and reports technical issues.
`Simplifier`	Refactors accepted code for clarity without changing behavior or introducing check failures.

An escalation asks the owner to decide an implementation question. A finding records a technical issue reported by the verifier. The owner discusses both with Maestro, not directly with the builder or verifier.

Prerequisites

macOS.
Node.js 26 or later.
Pi 1.0.0 or later.
pi-subagents installed and enabled in Pi.
Access to the configured builder, verifier, and simplifier models.
A project directory that Pi trusts.

Installation

The owner installs pi-subagents and Maestro with these commands:

pi install npm:pi-subagents
pi install npm:@emiliosp/pi-maestro

Usage

The owner starts Pi from the project directory:

cd /path/to/project
pi

Activate Maestro:

/maestro

During activation, Maestro checks project trust, configuration, models, and agent availability. If a check fails, Maestro stays disabled and reports the problem.

The owner follows this workflow:

Describes one change to Maestro.
Reviews the spec, including its acceptance criteria and concrete examples.
Replies GREEN FLAG when Maestro asks for approval. Maestro records the approval and starts the builder.
Reviews every current builder escalation and gives Maestro an answer and reason for each question.
Reviews verifier findings and chooses an action for every finding.
Reads Maestro's summary at candidate-ready and performs the final review.

Maestro starts the verifier after a successful builder run. All three agents run in the foreground: Pi waits for each run to finish and Maestro shows the current phase in Pi's status, while pi-subagents FleetView and /subagents-fleet show agent activity and transcripts.

The owner must not edit product files while the workflow runs. Maestro can perform temporary experiments with owner agreement during spec preparation and permitted revisions. See Workflow.

An escalation asks the owner to decide an implementation question, and a finding records a technical issue reported by the verifier. The owner discusses both with Maestro, never directly with the builder or verifier. Maestro records all current escalation answers or finding decisions in the active handoff before changing phase.

If any decision requires a spec change, the workflow returns to drafting-spec before the owner and Maestro revise the same spec. The owner reviews the revised spec and replies GREEN FLAG again. Maestro records renewed approval separately before another builder run.

After successful verification or rejection of all findings, Maestro starts the simplifier. Only this step requires Git. If Git readiness cannot be confirmed, Maestro warns and skips simplification. The simplifier selects all uncommitted code changes, including pre-existing staged, unstaged, and untracked files.

The workflow ends at candidate-ready. Rejected findings retain their reasons and accepted failures can remain. Maestro's summary separates independent verification from the later simplifier's report. The owner controls later review, commits, pull requests, and merging.

The same /maestro command disables Maestro and leaves project files unchanged. Disabling Maestro, restarting Pi, or using /resume clears live session state. Saved files do not automatically restore or resume an incomplete workflow. The owner handles it manually.

Configuration

Maestro uses default values when .pi/maestro.json is absent from the project root. The owner can add this file to change the spec directory, models, thinking levels, or timeouts. See Configuration.

Documentation

The reading order is:

Glossary: terms and identifiers used in specs, reports, and Maestro messages. Read this before the first workflow.
Workflow: approvals, decisions, and how each run produces artifacts.
Configuration: project paths, models, and timeouts.
Subagent integration: agent context, execution, and activity tracking.

Project constitution

Mission: purpose, scope, and owner responsibilities.
Tech stack: runtime technologies and development tools.
Roadmap: completed outcomes and planned priorities.
Changelog: meaningful codebase changes and breaking changes.
Architecture decision records: architectural choices, context, consequences, and evidence.