emilioSp/pi-maestro

Pi extension to manage a spec driven multiagent development workflow

Summary

pi-maestro is a TypeScript extension for Pi that turns one change into an approved specification and, optionally, carries it through a sequential multiagent implementation workflow. It separates requirements, implementation, independent verification, and optional refactoring while keeping the owner in control of approvals and the final review.

What it is useful for

Maestro is useful when a change needs a clear contract before code is written. The owner describes one reversible change, then works with Maestro to prepare and approve a spec. Each acceptance criterion uses a GIVEN, WHEN, THEN, and a concrete example, making the expected behavior easier to review. Requirements also include a Verified by field that points to acceptance criteria, existing tests, or both.

The implementation stage is optional. When enabled, a builder implements the approved spec, an independent verifier checks it against the project files, and a simplifier refactors accepted code without changing behavior. Each phase can be disabled separately—for example, a team might stop after producing an approved spec and implement it elsewhere.

The workflow also separates responsibilities: an agent does not approve its own work, the verifier reports technical findings, and the owner decides requirements, scope, escalations, and findings. This is useful when engineers want traceability from approved behavior to implementation and verification rather than a single unstructured agent run.

How engineers can use it

The documented prerequisites are macOS, Node.js 26 or later, Pi 1.5.0 or later, access to models used by enabled agents, and a project directory trusted by Pi.

Install the extension:

pi install npm:@emiliosp/pi-maestro

Start Pi from the project directory and activate Maestro:

cd /path/to/project
pi

/maestro

After describing the change, review the spec and its acceptance criteria. Reply GREEN FLAG when ready to approve it. Answer builder escalations and verifier findings through Maestro, then review the final summary at candidate-ready.

Configuration can be placed in .pi/maestro.json; documented settings include spec paths, models, thinking levels, and selected phases. If the builder is disabled, the workflow ends with only an approved spec.

Important limitations: the owner must not edit product files while the workflow runs. Simplification requires Git and may be skipped if Git readiness cannot be confirmed; it selects all uncommitted changes, including pre-existing staged, unstaged, and untracked files. Session state is not automatically restored, so incomplete workflows must be resumed manually. Commits, pull requests, and merges remain the owner’s responsibility.