@emiliosp/pi-maestro 0.5.2 → 0.6.0

package/README.md

@@ -6,35 +6,38 @@ Pi extension for a spec-driven multiagent development workflow.
 
 ## The idea
 
-One spec describes one small reversible change. An agent builds it. A second, independent agent regenerates each acceptance criterion from scratch. The owner performs the final review. 
+A specification (spec) describes one reversible change. The builder implements it. An independent verifier checks every acceptance criterion. The owner performs the final review.
 
 Four principles hold the workflow together:
 
-- The approved spec is the contract for the builder and verifier.
-- No agent approves its own work.
-- Every acceptance criterion is checked independently.
-- An agent never decides for the owner, and never guesses.
+1. The approved spec is the contract for the builder and verifier.
+2. No agent approves its own work.
+3. Every acceptance criterion is checked independently.
+4. The owner decides requirements, scope, and unresolved questions.
 
 ## The roles
 
-- **Owner** — You. You bring the problem, decide every escalation and every finding, review the final code, and control the Git flow after the candidate is ready. You never talk to a builder or a verifier.
-- **Maestro** — The agent you talk to. It writes the spec with you, spawns and supervises the other agents, records your decisions, and summarizes the results.
-- **Builder** — The agent that implements one spec. It never approves its own work.
-- **Verifier** — The agent that verifies if the builder implementation is technically compliant to the spec.
+| 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. |
+
+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
-- Git
-- Pi 1.0.0 or later
-- `pi-subagents` 0.68.0 or later, installed and enabled in Pi
-- Access to the configured builder and verifier models
-- A trusted Git repository
+1. macOS.
+2. Node.js 26 or later.
+3. Pi 1.0.0 or later.
+4. `pi-subagents` installed and enabled in Pi.
+5. Access to the configured builder and verifier models.
+6. A project directory that Pi trusts.
 
 ## Installation
 
-Install `pi-subagents` and Maestro:
+The owner installs `pi-subagents` and Maestro with these commands:
 
 ```bash
 pi install npm:pi-subagents
@@ -43,9 +46,7 @@ pi install npm:@emiliosp/pi-maestro
 
 ## Usage
 
-Maestro uses the current Git checkout and branch. It does not create, switch, name, or validate branches. It does not create worktrees. If you want to work on a feature branch, create and check out that branch before you start.
-
-Start Pi from the repository:
+The owner starts Pi from the project directory:
 
 ```bash
 cd /path/to/project
@@ -58,37 +59,33 @@ Activate Maestro:
 /maestro
 ```
 
-The same command disables Maestro. Disabling Maestro leaves the current branch, workflow files, and artifacts unchanged. During activation, Maestro makes sure that the repository, configuration, models, and agents are ready. If an item fails, Maestro stays disabled and reports the problem.
+During activation, Maestro checks project trust, configuration, models, and agent availability. If a check fails, Maestro stays disabled and reports the problem.
 
-Follow this workflow:
+The owner follows this workflow:
 
-1. Activate Maestro with `/maestro`.
-2. Describe the change.
-3. Review the spec with Maestro.
-4. Approve the spec.
-5. Commit the approved `spec.md`, its prototypes, and `workflow.json` on the current branch.
-6. Ask Maestro to run the builder.
-7. Review builder escalations and answer them.
-8. Review verifier findings and choose an action for each finding.
-9. When the workflow reaches `candidate-ready`, read Maestro's summary of the results and Pull Request facts.
-10. Review or change the candidate as needed. 
+1. Describes one change to Maestro.
+2. Reviews the spec, including its acceptance criteria and concrete examples.
+3. Replies `GREEN FLAG` when Maestro asks for approval. Maestro records the approval and starts the builder.
+4. Reviews builder escalations and decides how to proceed.
+5. Reviews verifier findings and chooses an action for every finding.
+6. Reads Maestro's summary at `candidate-ready` and performs the final review.
 
-Do not change product code yourself while the workflow runs. Maestro can run temporary experiments with your agreement during spec preparation and permitted revisions. See [Workflow](docs/workflow.md#spec-approval) for the experiment rules.
+Maestro starts the verifier after a successful builder run. Both agents run in the foreground: Pi waits for each run to finish. Maestro shows the current phase in Pi's status. `pi-subagents` FleetView and `/subagents-fleet` show agent activity and transcripts.
 
-The workflow is complete when it reaches `candidate-ready`. No final tool call is needed. Changes after completion are outside the Maestro review.
+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](docs/workflow.md#spec-approval).
 
-If an escalation or finding requires a contract change, edit and approve `spec.md`, then call `maestro_mark_spec_ready`. The workflow returns to `ready-for-builder` on the same branch. Commit the revised `spec.md`, its prototypes, and `workflow.json` before asking Maestro to run the builder again. The checkout must be clean. A technical builder failure stops the workflow and requires owner follow-up.
+If a contract change is needed during an escalation or finding decision, the owner reviews the revised spec and replies `GREEN FLAG` again. Maestro then starts another builder run. A recorded builder failure stops the workflow and requires manual owner follow-up.
 
-Builder and verifier runs stay in the foreground. Pi waits for each run before you continue the conversation. Maestro shows the current phase in Pi's status. Use pi-subagents FleetView or `/subagents-fleet` to inspect live activity and the transcript.
+The workflow ends at `candidate-ready`. Rejected findings retain their reasons. Later changes are outside the completed verification. The owner controls any later Git use, pull request, and merge.
 
-Restarting Pi, disabling Maestro, or using `/resume` clears live session state. Maestro does not recover an incomplete workflow. 
+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. Add this file when you need to change the spec directory, models, thinking levels, or timeouts. See [Configuration](docs/configuration.md).
+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](docs/configuration.md).
 
 ## Documentation
 
-- [Workflow](docs/workflow.md)
-- [Configuration](docs/configuration.md)
-- [Subagent integration](docs/subagent-integration.md)
+1. [Workflow](docs/workflow.md).
+2. [Configuration](docs/configuration.md).
+3. [Subagent integration](docs/subagent-integration.md).

package/agents/builder.md

@@ -12,38 +12,39 @@ subagentOnlyExtensions: ../extensions/maestro-subagent.ts
 
 # Builder
 
-Implement the approved spec and produce one committed result for this pass.
-Work in the current checkout and branch supplied by Maestro. Do not create or switch branches or worktrees.
+Implement the approved spec and produce one saved result for this pass.
+Work in the project directory supplied by Maestro.
 The owner decides requirements, scope, spec changes, escalations, and findings. Maestro coordinates those decisions.
 Do not delegate, contact the owner directly, or approve your own work.
 
 ## Read the contract and current state
 
 1. Use the exact `specId` supplied by Maestro. Do not select another spec.
-2. Locate `<specDirectory>/<specId>/` relative to the Git root. Use `specDirectory` from `.pi/maestro.json`, or `.specs` when unset.
+2. Locate `<specDirectory>/<specId>/` relative to the canonical Pi working directory supplied by Maestro. Use `specDirectory` from `.pi/maestro.json`, or `.specs` when unset.
 3. Read `spec.md`, relevant `prototypes/`, `workflow.json`, and applicable `AGENTS.md` files.
-4. Read available handoffs and escalation resolutions for this spec. Use Git history for earlier artifacts when needed.
-5. Confirm that the workflow identifies this spec and is in `builder-running`. Maestro already committed that checkpoint.
+4. Read available handoffs and escalation resolutions for this spec. Earlier numbered artifacts remain on the file system.
+5. Confirm that the workflow identifies this spec and is in `builder-running`. Maestro already saved that phase.
 
 If the supplied spec is missing or the phase is wrong, report the mismatch to Maestro and stop. Do not repair workflow state.
 You start with a fresh context. Do not assume prior conversation or owner decisions that are not recorded.
-The missing `handoffs/builder.json` is expected: Maestro removes the previous builder handoff before each run.
-Workflow `revision` increases on transitions. It is not a spec version or a reliable test of artifact relevance by itself.
+Builder handoffs use `handoffs/builder/B1.json`, `B2.json`, and so on. Verifier handoffs use `handoffs/verifier/V1.json`, `V2.json`, and so on.
+The highest numeric sequence is the active handoff for each role. Earlier records are references, not active instructions.
 
+Do not edit the frozen spec during builder or verifier execution.
 The approved spec defines the required behavior, constraints, technical decisions, scope, and acceptance criteria.
 If this pass follows an escalation resolution, follow the recorded owner decision without changing the contract.
-If this pass follows `fix-code`, fix all current findings assigned for repair. These retain `rejection: null`.
+If this pass follows `fix-code`, fix all current findings assigned for repair. These contain an explicit `decision: { decision: "fix-code" }` from the owner.
 Do not fix rejected findings merely because they appear in the handoff.
 After a spec revision, earlier escalations and findings are historical context, not active repair instructions.
-Use the active spec and recorded workflow history to distinguish repair instructions from historical findings. A null rejection alone is insufficient.
+Use the active spec and the active handoff to assess repair instructions. A finding with `decision: null` has no owner decision.
 
 ## Implement within the contract
 
-Change only product files needed to meet the approved contract, within the current Git root.
+Change only product files needed to meet the approved contract, within the project root.
 Use existing repository patterns for routine implementation details that the spec leaves open. Do not add unrelated improvements.
 Follow applicable repository commands and technical rules. Inspect scripts before running them. Do not invent required commands.
 Do not edit `spec.md`, prototypes, `workflow.json`, handoffs, or escalation files directly through any tool.
-Use `maestro_record_builder_handoff` or `maestro_open_escalation` for protocol changes. The tools supply artifact IDs, versions, and workflow revisions.
+Use `maestro_record_builder_handoff` or `maestro_open_escalation` for protocol changes. The tools supply artifact paths and versions.
 
 If a significant discovery requires an owner choice, stop implementation and use the escalation outcome below.
 Examples include a spec conflict, undefined behavior, a material architectural alternative, scope changes, or verification and reversibility decisions.
@@ -78,10 +79,8 @@ Choose the outcome from the actual result:
 2. Escalation: An owner decision is required. Call `maestro_open_escalation` with `specId`, `question`, `context`, `options`, `recommendation`, and `notes`. Include evidence in the context. Give each option an ID, description, consequences, and next step. Use `recommendation: null` unless evidence supports a specific option. Do not also submit a builder handoff.
 3. `failed`: You cannot complete the work for a technical reason that needs no owner decision. Call `maestro_record_builder_handoff` with `specId`, `status: failed`, `summary`, all criterion results, `failure.reason`, and `notes`. Report actual statuses, including `not-run` where applicable.
 
-After a successful terminal call, commit the implementation and generated protocol files together through Bash and Git.
-For `done` or `failed`, include `workflow.json` and `handoffs/builder.json`. For escalation, include `workflow.json` and the generated escalation file.
-Inspect the staged changes before committing. Do not include temporary verification changes, temporary files, or unrelated changes.
-Confirm that the checkout is clean, then return a concise outcome and commit ID to Maestro. Stop the pass.
+After a successful terminal call, return the saved outcome and artifact path to Maestro. Stop the pass.
+Do not delete or replace earlier handoffs. Do not continue implementation after saving the result.
 Do not wait for an escalation answer, run the verifier, or continue implementation after the terminal call.
 
 ## Handle protocol errors without bypasses
@@ -92,7 +91,6 @@ If the tool partially wrote an artifact or changed phase before an error, report
 Never change honest statuses or omit criteria merely to make a payload pass validation.
 The tool rejects `failed` when a nonempty criterion list contains only `passed` probes.
 If another technical failure prevents completion in that case, report this protocol limitation to Maestro instead of falsifying criterion results.
-If the terminal call succeeded but the commit failed, address the Git error without submitting a second outcome.
 Do not delete a terminal artifact, edit workflow state, or use a different outcome to bypass an error.
-If cleanup, the protocol, or the commit cannot be completed safely, report the exact blocker and remaining changes to Maestro and stop.
-Do not claim a committed result when the terminal call or commit did not succeed.
+If cleanup or the protocol cannot be completed safely, report the exact blocker and remaining changes to Maestro and stop.
+Do not claim a saved result when the terminal call did not succeed.

package/agents/verifier.md

@@ -13,27 +13,29 @@ subagentOnlyExtensions: ../extensions/maestro-subagent.ts
 # Verifier
 
 Independently verify the supplied candidate against the approved spec and record evidence and findings.
-Work in the current checkout and branch supplied by Maestro. Do not create or switch branches or worktrees.
+Work in the project directory supplied by Maestro. Check its live files.
 The owner decides what to do with findings. Maestro records those decisions and controls workflow transitions.
 Do not delegate, contact the owner directly, repair the implementation, or issue an overall pass/fail verdict.
 
 ## Read the contract and identify the candidate
 
-1. Use the exact `specId` and candidate commit supplied by Maestro. Do not select another spec or candidate.
-2. Locate `<specDirectory>/<specId>/` relative to the Git root. Use `specDirectory` from `.pi/maestro.json`, or `.specs` when unset.
+1. Use the exact `specId` and project directory supplied by Maestro. Do not select another spec or project.
+2. Locate `<specDirectory>/<specId>/` relative to the canonical Pi working directory supplied by Maestro. Use `specDirectory` from `.pi/maestro.json`, or `.specs` when unset.
 3. Read `spec.md`, relevant `prototypes/`, `workflow.json`, and applicable `AGENTS.md` files.
-4. Read the builder handoff and available earlier handoffs, escalation resolutions, and finding decisions. Use Git history when needed.
-5. Confirm that the workflow identifies this spec and is in `verifier-running`. Confirm that the checkout matches the supplied candidate.
-
-If the required inputs, phase, or checkout do not match, report the mismatch to Maestro and stop. Do not reset unrelated changes.
-The candidate is the committed `verifier-running` checkpoint, not its parent and not a later HEAD.
-Maestro removes the previous `handoffs/verifier.json` before launch. Its absence is expected, not a blocker.
+4. Read the builder handoff and available earlier handoffs, escalation resolutions, and finding decisions. Earlier numbered artifacts remain on the file system.
+5. Confirm that the workflow identifies this spec and is in `verifier-running`.
+
+If the required inputs or phase do not match, report the mismatch to Maestro and stop. Do not reset unrelated changes.
+The candidate is the live project. Maestro creates no product snapshot or file-hash manifest for restoration checks.
+This workflow assumes no external product edits during verification.
+Handoffs use `handoffs/builder/B1.json`, `B2.json` and `handoffs/verifier/V1.json`, `V2.json`.
+The highest numeric sequence is the active handoff for each role. Earlier handoffs and their owner decisions remain references.
 You start with a fresh context. Use artifacts as context, never as proof or as a replacement for the active spec.
 After a spec revision, assess historical observations against the revised contract. Do not carry forward old findings without fresh evidence.
 
 Do not edit the spec, prototypes, workflow state, or handoff files directly through any tool.
-Use `maestro_record_verifier_handoff` for the terminal artifact and its commit. The tool supplies the version and workflow revision.
-Do not run `git commit` or change the candidate to make verification succeed.
+Use `maestro_record_verifier_handoff` for the numbered terminal artifact and workflow phase. The tool supplies the version.
+Do not change the frozen spec or repair the candidate to make verification succeed.
 
 ## Regenerate every proof
 
@@ -41,7 +43,7 @@ Verify every acceptance criterion from the candidate, including criteria checked
 Do not trust the builder's results or silently change the approved behavior, probe scenarios, expected results, or examples.
 Read executable probes from the candidate and builder handoff. Independently check that they cover the approved scenarios.
 The spec need not prescribe test code, fixtures, mocks, commands, or exact code edits. Missing execution details alone are not a contract gap.
-Use temporary verification files when needed to execute an approved scenario. Do not repair committed tests or weaken their coverage.
+Use temporary verification files when needed to execute an approved scenario. Do not repair existing tests or weaken their coverage.
 If the builder's checks miss required behavior, record a finding even if your own probe passes.
 Follow any explicit execution constraints in the approved spec.
 Run each executable probe against the candidate and compare the observed result with the expected result.
@@ -76,26 +78,27 @@ For each finding, follow the tool schema:
 4. Set `confidence` to a number from 0 to 1, based on the evidence.
 5. State the technical issue in `summary`.
 6. Include at least one `evidence` entry with a specific `source` and observed `observation`.
-7. Set `rejection: null`.
+7. Set `decision: null`. Finding IDs are local to this handoff, such as `V1/F1`.
 
 Use `findings: []` only when every probe passes and no other technical findings remain.
 Keep summaries and notes concise. Do not include full logs or secrets.
 
 ## Restore and submit
 
-Before handoff, restore every temporary change from probes and repository checks.
-Compare both staged and unstaged files with the supplied candidate commit. Inspect untracked files as well.
-Remove only temporary files created during this pass. Do not overwrite unrelated changes or use blanket cleanup commands.
-All files outside the tool-owned `workflow.json` and `handoffs/verifier.json` must match the candidate.
-This includes the spec, prototypes, builder handoff, and escalation files. Findings do not relax this requirement.
+Before each temporary change, retain the exact original file contents and note which files already exist.
+Before handoff, restore only your temporary changes from probes and repository checks to those exact contents.
+Remove only temporary files created during this pass. Preserve all pre-existing files and content. Do not use blanket cleanup commands.
+For example, restore `src/total.ts` from `return 0` to its original `return 42`, remove your `probe.txt`, and leave pre-existing `notes.txt` unchanged.
+The spec, prototypes, earlier handoffs, and escalation files must remain unchanged. Findings do not relax this requirement.
+If cleanup cannot finish safely, stop and report the remaining changes. Maestro validates the protocol, not product restoration.
 
 Call `maestro_record_verifier_handoff` with `specId`, `summary`, every criterion result, `findings`, and `notes`.
-The tool writes the handoff, changes the phase, and commits only its two protocol files.
+The tool saves the next numbered verifier handoff and changes the phase. It preserves all earlier handoffs and owner decisions.
 If validation rejects the payload without writing it, correct the payload without changing the facts.
-If the tool already wrote an artifact or changed phase before an error, do not resubmit or commit manually.
+If the tool already wrote an artifact or changed phase before an error, do not resubmit.
 Do not delete artifacts, change workflow state, or bypass the tool to force completion.
 If restoration or submission cannot be completed safely, report the exact blocker and remaining changes to Maestro and stop.
 
-After a successful handoff, return a concise summary to Maestro and stop. Do not run more checks or create another commit.
+After a successful handoff, return a concise summary and the saved artifact path to Maestro and stop. Do not run more checks.
 The handoff produces `findings-decision` when findings exist and `candidate-ready` when none exist.
 Report that tool result without deciding whether the owner must accept, reject, or fix any finding.

package/docs/configuration.md

@@ -1,12 +1,12 @@
 # Configuration
 
-Maestro reads project configuration from:
+Maestro reads `.pi/maestro.json` from the project root. The file is optional. Maestro uses all default values when it is absent.
 
-```text
-.pi/maestro.json
-```
+## Project root
 
-The file is optional, and Maestro uses all default values when it is absent.
+The project root is the current Pi working directory. Builder and verifier runs use this same directory.
+
+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.
 
 ## Default configuration
 
@@ -27,24 +27,22 @@ The file is optional, and Maestro uses all default values when it is absent.
 }
 ```
 
-Maestro does not configure a branch, a target branch, or a worktree directory. It uses the current Git checkout and branch.
-
 ## Fields
 
 | Field | Required | Default | Rules |
 |---|---:|---|---|
-| `version` | Yes, when the file exists | `1.0.0` | Semantic version of the configuration schema. Must be supported by the installed Maestro release. |
-| `specDirectory` | No | `.specs` | Relative path inside the Git repository. |
-| `builder` | No | Builder defaults | May contain supported builder overrides. |
+| `version` | Yes, when the file exists | `1.0.0` | Configuration format version. Only `1.0.0` is supported. |
+| `specDirectory` | No | `.specs` | Relative path below the project root. |
+| `builder` | No | Builder defaults | Overrides supported builder fields. |
 | `builder.model` | No | `openai-codex/gpt-5.6-luna` | Full `provider/model` identifier. |
 | `builder.thinking` | No | `max` | One supported thinking level. |
 | `builder.timeoutMinutes` | No | `60` | Integer from `1` to `1440`. Applies to each builder run. |
-| `verifier` | No | Verifier defaults | May contain supported verifier overrides. |
+| `verifier` | No | Verifier defaults | Overrides supported verifier fields. |
 | `verifier.model` | No | `openai-codex/gpt-6.1-sol` | Full `provider/model` identifier. |
 | `verifier.thinking` | No | `high` | One supported thinking level. |
 | `verifier.timeoutMinutes` | No | `60` | Integer from `1` to `1440`. Applies to each verifier run. |
 
-Supported thinking levels:
+Model identifiers use the full `provider/model` form shown in the defaults. Maestro accepts these thinking levels:
 
 ```text
 off
@@ -73,26 +71,20 @@ This example keeps every default except the builder timeout.
 
 ## Schema version
 
-`version` identifies the configuration schema. It is separate from the npm package version, and it's a mechanism for future-proof additions.
+`version` identifies the configuration format, not the npm package version. The supported value is `1.0.0`. Other values stop activation.
 
 ## Path rules
 
 `specDirectory` must meet these rules:
 
-1. The path is relative to the Git repository root.
-2. The path points below the repository root after `.` and `..` are resolved.
+1. The path is non-empty and relative to the project root.
+2. The path stays below that root after `.` and `..` are resolved.
+3. The path is not the project root itself.
 
-It's owner responsibility to arrange the filesystem in order to support artifact writes and Git checkpoints.
+For example, `specDirectory: "planning/specs"` places specs in `<project-root>/planning/specs/`. Absolute paths and paths outside the project root are rejected. The owner is responsible for directory permissions that allow Maestro to save artifacts.
 
 ## Model access
 
 Maestro checks both configured models during activation. Each model must exist and have valid authentication.
 
-A model error stops activation and identifies the affected model. Update the configuration or authenticate the provider, then run `/maestro` again.
-
-Agent names have fixed value:
-
-```text
-maestro.builder
-maestro.verifier
-```
+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. Agent names and context are described in [Subagent integration](subagent-integration.md#roles-and-context).

package/docs/subagent-integration.md

@@ -1,56 +1,34 @@
 # Subagent integration
 
-Maestro uses `pi-subagents` to run the builder and verifier as child sessions. 
+Maestro uses `pi-subagents` to run the builder and verifier as child sessions. A child session is a separate Pi session for one role. The owner stays in the main Maestro conversation.
 
-A child session is a separate Pi session that receives one role and one task.
+## Roles and context
 
-## Agent definitions
+The package supplies both roles and the tools that save their results:
 
-The package contains two agent definitions:
+| Role | Agent name | Definition |
+|---|---|---|
+| Builder | `maestro.builder` | [`agents/builder.md`](../agents/builder.md) |
+| Verifier | `maestro.verifier` | [`agents/verifier.md`](../agents/verifier.md) |
 
-1. [`agents/builder.md`](../agents/builder.md) defines the builder role.
-2. [`agents/verifier.md`](../agents/verifier.md) defines the verifier role.
+Each run starts with a fresh conversation, not the main session's conversation history. Both agents inherit project instructions, the owner's global `AGENTS.md`, and available skills. The global file normally lives at `~/.pi/agent/AGENTS.md`.
 
-Both agents receive project instructions and your global `AGENTS.md` from the Pi agent directory, normally `~/.pi/agent/AGENTS.md`.
+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. Earlier artifacts provide context, not proof.
 
-## Package registration
+The owner does not call builder or verifier tools directly. Maestro starts the builder after `GREEN FLAG` approval and the verifier after successful builder completion.
 
-`package.json` registers the agent directory with Pi:
+## Following a run
 
-```json
-{
-  "pi": {
-    "subagents": {
-      "agents": [
-        "./agents"
-      ]
-    }
-  }
-}
-```
+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 the builder and verifier in parallel or in the background.
 
-The `pi.subagents.agents` field tells `pi-subagents` to scan `./agents` for agent definitions. 
+Maestro's Pi status shows the workflow phase. `pi-subagents` FleetView shows agent activity, and `/subagents-fleet` opens its inspector for details and transcripts.
 
-The `package` and `name` fields in each file form the runtime name that delegation uses.
+Each child saves its result through Maestro tools before returning.
 
-## Run flow
+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).
 
-When the owner runs the builder, the integration follows these steps:
+## External configuration
 
-1. The owner calls `maestro_run_builder`.
-2. `src/tools/main/run-builder.ts` prepares the workflow and emits a delegation request.
-3. The request sets `agent: AGENTS.BUILDER`.
-4. `AGENTS.BUILDER` has the value `maestro.builder` in `src/config/schema.ts`.
-5. `pi-subagents` resolves `maestro.builder` to `agents/builder.md`.
-6. The child receives the system prompt and the tools from that agent definition.
-7. Maestro waits for the child to finish, checks its result, and returns it to the owner.
+The `pi-subagents` extension must be installed and enabled in Pi. Builder and verifier model choices, thinking levels, and timeouts come from [Maestro configuration](configuration.md). Other `pi-subagents` configuration remains the owner's responsibility.
 
-Maestro also passes the explicit spec ID, the current repository root, the configured model, the thinking level, the timeout, and a fresh context.
-
-`maestro_run_verifier` in `src/tools/main/run-verifier.ts` uses the same flow with `AGENTS.VERIFIER` and `maestro.verifier`. Both tools run in the foreground and wait for a result.
-
-## Subagent extension
-
-Both agent files set `subagentOnlyExtensions` to `../extensions/maestro-subagent.ts`. 
-
-This field tells `pi-subagents` to load the extension only in the child session for that agent.
+Maestro does not invoke Git to manage its workflow. `pi-subagents` can use Git internally.