@emiliosp/pi-maestro 0.17.0 → 0.18.0

package/node_modules/pi-subagents/prompts/parallel-review.md

@@ -1,58 +0,0 @@
----
-description: Parallel subagents review
----
-
-Launch parallel reviewers for an adversarial review of the current work.
-
-Use fresh context, not forked context, unless I explicitly ask for forked context. Reviewers should inspect the repository, relevant instructions, and current diff directly from files and commands. Do not rely on the main conversation history.
-
-Give each reviewer a distinct angle. Generate the angles dynamically from the user's intent, the plan, the implemented code, and the current diff. If I specify angles, use mine. Otherwise, choose the highest-value review angles for this specific work.
-
-These are examples, not fixed defaults:
-
-1. Correctness and regressions
-   Check whether the change satisfies the request, preserves existing behavior, handles edge cases, and avoids hidden runtime failures.
-
-2. Tests and validation
-   Check whether tests or validation were added at the right layer, whether assertions are meaningful, and whether the chosen verification commands are enough.
-
-3. Simplicity and maintainability
-   Check for unnecessary complexity, duplicate structure, single-use wrappers, brittle abstractions, confusing names, verbosity, and cleanup that is clearly worth doing.
-
-Choose or adapt angles when the work calls for it:
-- TypeScript-heavy changes: include type safety, source-of-truth types, casts, and error-boundary discipline.
-- UI-heavy changes: include UX, accessibility, copy, and visual quality.
-- Security-sensitive changes: include unsafe input/output handling, auth boundaries, privacy, and data exposure.
-- Docs-heavy changes: include clarity, accuracy, completeness, reader flow, and non-robotic prose.
-- Large multi-file changes: consider a fourth reviewer for structural friction, module boundaries, and testability.
-
-Prefer three strong reviewers over many vague reviewers.
-
-Give every reviewer a specific task prompt naming its angle. Ask reviewers to return concise, evidence-backed findings with file/line references and suggested fixes. Filter on evidence, not severity: a finding must be concrete and current within the named review target, and supported by source proof, a test or repro, or a contract contradiction. For a diff review, require that the issue is caused or made reachable by that diff. Label findings P0/P1/P2. P0 blocks merge. P1 should be fixed before release. P2 is report-only. End each review with `Merge verdict: BLOCK`, `Merge verdict: OK`, or `Merge verdict: OK with notes`. If nothing qualifies, ask the reviewer to say exactly `No issues found.` The response should be review feedback, not a context summary. Reviewers must not edit files unless I explicitly ask for a writer pass.
-
-Do not default first-pass reviews to `blockers only`. That phrase is valid only for final pre-merge re-checks after P1/P2 findings are already inventoried, or for explicit emergency hotfix lanes where non-blocking findings are intentionally deferred.
-
-For a targeted follow-up review, ask only whether the named finding was resolved, whether the fix introduced a new defect in the fix blast radius, and whether prior P1/P2 notes still stand. For bot or PR-comment triage, classify each comment as VALID, STALE, INVALID, or OUT-OF-POLICY against current HEAD, then assign P0/P1/P2 only to VALID comments.
-
-While reviewers run, do your own narrow inspection if useful. After they return, synthesize the feedback into:
-- fixes worth doing now
-- optional improvements
-- feedback to ignore or defer, with a short reason
-
-Do not blindly apply every reviewer suggestion.
-
-Autofix mode: if the invocation contains the exact word `autofix`, treat it as workflow control, not review scope. Remove it before deciding the review target. After synthesis, apply only fixes worth doing now, validate, and summarize. Do not apply optional improvements unless explicitly requested. If there are no fixes worth doing now, do not edit.
-
-Without autofix mode, ask before applying fixes unless I already told you to address review feedback. When you ask, end with a compact numbered menu so I can respond with a number. Use wording suited to the findings, but include these choices when applicable:
-
-```text
-Reply with [1], [2], or further instructions:
-[1] Apply only the fixes worth doing now.
-[2] Apply the fixes worth doing now plus optional improvements.
-```
-
-Additional review target or focus from the slash command invocation:
-
-$@
-
-If the invocation provides a URL, issue link, file path, plan path, or freeform focus, treat it as the primary review scope. Read or fetch that target before assigning reviewer angles, and pass the target explicitly into each reviewer task.

package/node_modules/pi-subagents/prompts/review-loop.md

@@ -1,47 +0,0 @@
----
-description: Review/fix loop until clean
----
-
-Run a parent-orchestrated review loop for the requested work.
-
-Use the `subagent` tool. Keep the parent session as the loop controller and final decision-maker. Child subagents must receive concrete role-specific tasks; they must not run subagents or manage the loop themselves unless the parent intentionally selected an explicit fanout agent whose builtin `tools` includes `subagent` for that assigned fanout.
-
-Default to a maximum of 3 review rounds unless I specify a different cap. Count a review round each time fresh-context reviewers inspect the current diff after a worker pass. Stop early when reviewers find no P0 findings, no P1 fixes worth doing now, and no approved P2 notes that should be handled in this loop.
-
-If the invocation includes an implementation request, first launch one async `worker` to implement the approved scope. If the current diff is already the target, start with review. The sequence can be launched up front as a workflow script (a ```` ```js workflow ```` block plus `subagent({ workflow: true })`) when it is already clear, or continued as follow-up single-agent runs after each async completion. For an initial workflow script, pass `async: true` so the main chat is unblocked; do not set `clarify: true` unless I explicitly want the foreground clarify UI. Use only one writer against the active worktree at a time unless I explicitly ask for isolated worktrees.
-
-As a conservative orchestration policy, do not set a hard `toolBudget` or tight `usageBudget` on implementation or fix workers. A default tool budget blocks read/search tools rather than mutation tools, and reported usage has no reservation model, so count or usage limits still do not measure delivery safety. Give each writer a narrow delivery slice and an outer elapsed deadline with enough margin. Before that deadline, request a checkpoint after the current tool returns with changed files, build/test state, remaining work, and commit or PR state. An elapsed timeout is not a mutation-safe boundary and must not be the checkpoint trigger.
-
-For each review round, launch fresh-context `reviewer` agents in parallel. Reviewers must inspect the repository, relevant instructions, and current diff directly from files and commands. They must not rely on the main conversation history and must not edit files.
-
-Tell reviewers to filter on evidence, not severity. They should report only concrete current issues caused or made reachable by the target diff, with source proof, a test or repro, or a contract contradiction. Ask them to label findings P0/P1/P2 and end with `Merge verdict: BLOCK`, `Merge verdict: OK`, or `Merge verdict: OK with notes`. P0 blocks merge. P1 should be fixed before release. P2 is report-only. Use `blockers only` only for final pre-merge re-checks after P1/P2 findings are already captured, or for explicit emergency hotfix lanes.
-
-Choose review angles from the actual change. Common angles are correctness/regressions, tests/validation, and simplicity/maintainability. Add security, performance, docs/API contracts, or user-flow validation when the work calls for it. Prefer three strong reviewers over many vague reviewers.
-
-After reviewers return, synthesize their feedback into:
-- P0 blockers or scope/product/architecture decisions that need user approval;
-- P1 fixes worth doing now;
-- P2 report-only notes or optional improvements;
-- feedback to ignore or defer, with a short reason.
-
-Do not blindly apply every reviewer suggestion. If reviewers surface an unapproved product, scope, or architecture decision, pause and ask me before launching a fix worker.
-
-When an async implementation worker completes, treat its handoff as the transition into review, not as final completion, unless I explicitly asked for worker-only work, review-only output, or to stop after implementation.
-
-When there are fixes worth doing now and the workflow is implementation-authorized, launch one async forked `worker` without hard tool-call caps to apply only those synthesized fixes. Ask it to preserve the approved scope, run focused validation, and report changed files, commands run with exit codes, validation evidence, surprises, and anything left undone.
-
-After a fix worker returns, run another review round only when it made material changes or addressed non-trivial findings. Do not keep looping for optional polish, speculative improvements, or findings already deferred by the parent.
-
-For a targeted follow-up review, ask only three questions: whether the named finding was resolved, whether the fix introduced a new concrete defect in the fix blast radius, and whether prior P1/P2 notes still stand. End with a fix verdict and the merge verdict.
-
-Stop and summarize when one of these is true:
-- reviewers find no P0 blockers or P1 fixes worth doing now;
-- remaining feedback is optional, speculative, or intentionally deferred;
-- reviewers surface an unapproved decision that needs me;
-- the max review-round cap is reached.
-
-On completion, inspect the final diff yourself, run or confirm focused validation where appropriate, and summarize the loop: rounds run, fixes applied, validation, remaining deferred items, and why the loop stopped.
-
-Additional target, implementation request, max-iteration cap, or review focus from the slash command invocation:
-
-$@

package/node_modules/pi-subagents/runner-peer-loader.mjs

@@ -1,21 +0,0 @@
-import { pathToFileURL } from "node:url";
-
-let aliases = {};
-let nativeRunner = false;
-const redirected = new Set([
-	"@earendil-works/pi-tui",
-]);
-
-export function initialize(data) {
-	aliases = data?.aliases ?? {};
-	nativeRunner = data?.nativeRunner === true;
-}
-
-export function resolve(specifier, context, nextResolve) {
-	const alias = nativeRunner ? aliases[specifier] : redirected.has(specifier) && aliases[specifier];
-	if (alias) {
-		const target = pathToFileURL(alias).href;
-		return nativeRunner ? { url: target, shortCircuit: true } : nextResolve(target, context);
-	}
-	return nextResolve(specifier, context);
-}

package/node_modules/pi-subagents/runner-peer-preload.mjs

@@ -1,30 +0,0 @@
-import * as nodeModule from "node:module";
-import { pathToFileURL } from "node:url";
-
-const aliases = JSON.parse(process.env.JITI_ALIAS ?? "{}");
-const nativeRunner = process.env.PI_ASYNC_NATIVE_RUNNER === "1";
-const redirected = new Set([
-	"@earendil-works/pi-tui",
-]);
-
-if (typeof nodeModule.registerHooks === "function") {
-	nodeModule.registerHooks({
-		resolve(specifier, context, nextResolve) {
-			const alias = nativeRunner ? aliases[specifier] : redirected.has(specifier) && aliases[specifier];
-			if (alias) {
-				const target = pathToFileURL(alias).href;
-				return nativeRunner ? { url: target, shortCircuit: true } : nextResolve(target, context);
-			}
-			try {
-				return nextResolve(specifier, context);
-			} catch (error) {
-				if (nativeRunner && specifier.endsWith(".js")) return nextResolve(`${specifier.slice(0, -3)}.ts`, context);
-				throw error;
-			}
-		},
-	});
-} else {
-	nodeModule.register(new URL("./runner-peer-loader.mjs", import.meta.url), {
-		data: { aliases, nativeRunner },
-	});
-}

package/node_modules/pi-subagents/skills/council-mode/SKILL.md

@@ -1,59 +0,0 @@
----
-name: council-mode
-description: Run a bounded supervisor-mediated advisor council. Use when the user asks for council mode, asks to convene advisors, debate a decision, cross-examine recommendations, or run /council.
----
-
-# Council Mode
-
-Council mode is parent-supervised advice for a material decision with real tradeoffs. It is not free-form agent chat, implementation work, a transcript dump, mutation authority, or a council UI.
-
-The parent selects the roster, relays only curated claims, decides validity, and writes the memo. Advisors stay read-only and do not see peer transcripts by default.
-
-Before launch, read:
-
-- `skills/pi-subagents/references/execution-controls.md`
-- `skills/council-mode/references/pass-contracts.md`
-
-## Roster
-
-Run `subagent({ action: "list" })`, then choose 2-3 executable advisor names that start with `council-`. The prefix is convention only. Never use more than four advisors.
-
-If fewer than two council profiles are available, fill with `oracle`, then `reviewer`. Launch fallback `oracle` with `context: "fork"`; let fallback `reviewer` use its normal profile context. Note fallbacks and known context modes in the memo. If fewer than two advisors remain, use the normal one-oracle consultation loop and label it degraded mode.
-
-`council-*` profiles live in user or project agent directories, not this package. A profile defines model, tools, context, output defaults, and persistent stance. Keep advisors read-only, disable inherited skills unless needed, and put stance in the profile body instead of inventing per-run role labels.
-
-External-job/package advisors may join only when their provider is registered. Treat them as ordinary advisor names in `runs.all`, but honor their runner limits: they may lack repo tools, structured output, or resumability. Include evidence they cannot read, request JSON text instead of `outputSchema`, and use a fresh-context fallback when they cannot resume for cross-exam.
-
-## Passes
-
-Pass 1 is independent reports. Pass 2 is one cross-exam. Run Pass 3 only when `--max-passes 3` was requested and a material dispute can still be settled by evidence. Never run an unbounded loop.
-
-## Protocol
-
-1. Write the council brief: question, scope, non-goals, evidence targets, roster, known advisor context modes, and pass cap.
-2. Tell the user the roster, context modes, and pass cap.
-3. Launch one async workflow script (a ```` ```js workflow ```` block plus `subagent({ workflow: true, async: true })`) with `runs.all` for Pass 1. Use stable keys, `phase: "Council pass 1"`, concise labels, and `output: false` unless separate artifacts are useful. Set `context` only when the profile context is known or a fallback rule requires it.
-4. Return one aggregate Pass 1 receipt. On completion, tell the user completion count, agreement count, dispute count, and whether Pass 2 is needed.
-5. Synthesize the claim matrix in the parent: agreements, disputed claims, missing proof, owner decisions, and at most five material relay claims per advisor.
-6. For Pass 2, tell the user which claims are relayed and why they matter. Resume each advisor with a curated challenge packet. A resume needs a retained run id and task; it excludes `agent` and rejects `gate`. Record each new run id; Pass 3 resumes those latest ids with new stable keys.
-7. Stop at convergence, pass cap, failed fallback, or user interruption. The parent writes the final memo.
-
-If an advisor is not resumable, run the same profile fresh with its Pass 1 report and challenge packet. Label it a fresh-context fallback, not true cross-exam.
-
-Do not set `clarify`, `worktree`, `gate`, tool budgets, or tight usage budgets on advisors. Bound work through the roster, pass cap, and report length.
-
-## Memo
-
-Converged means no disputed claim remains that both affects the recommendation and can plausibly be settled by advisor evidence. Put unresolved disputes in owner decisions. Do not add a round for polish or symmetry.
-
-The memo states:
-
-- question and scope
-- recommendation and rationale
-- accepted and rejected feedback with reasons
-- owner decisions
-- evidence and run ids
-- confidence and what would change the decision
-- roster, passes, fallbacks, and known advisor context modes
-
-Identify advisors by profile name. State when fallback `oracle` was forked and context-aware. Escalate to a writer only after the memo and only when the user requests it.

package/node_modules/pi-subagents/skills/council-mode/references/pass-contracts.md

@@ -1,150 +0,0 @@
-# Council Mode Pass Contracts
-
-Load this before launching council advisors.
-
-## Pass 1 report
-
-Native Pi advisors should receive this `outputSchema`. External runners should receive the same shape as plain JSON text and no `outputSchema`.
-
-```js
-const pass1OutputSchema = {
-  type: "object",
-  required: [
-    "recommendation",
-    "evidence",
-    "assumptions",
-    "risks",
-    "confidence",
-    "challengeClaims",
-    "ownerDecisions",
-    "changeMyMind"
-  ],
-  properties: {
-    recommendation: { type: "string" },
-    evidence: {
-      type: "array",
-      items: {
-        type: "object",
-        required: ["claim", "sources"],
-        properties: {
-          claim: { type: "string" },
-          sources: { type: "array", items: { type: "string" } }
-        }
-      }
-    },
-    assumptions: {
-      type: "array",
-      items: {
-        type: "object",
-        required: ["assumption", "status"],
-        properties: {
-          assumption: { type: "string" },
-          status: { enum: ["verified", "unverified"] }
-        }
-      }
-    },
-    risks: { type: "array", items: { type: "string" } },
-    confidence: {
-      type: "object",
-      required: ["level", "reason"],
-      properties: {
-        level: { enum: ["high", "medium", "low"] },
-        reason: { type: "string" }
-      }
-    },
-    challengeClaims: { type: "array", items: { type: "string" }, maxItems: 3 },
-    ownerDecisions: { type: "array", items: { type: "string" } },
-    changeMyMind: { type: "array", items: { type: "string" } }
-  }
-};
-```
-
-Task text:
-
-- inspect supplied evidence directly
-- do not ask other advisors or read peer reports
-- stay read-only
-- do not spawn children
-- return only the structured report
-- keep the report under about 600 words
-
-For external runners, say: `Return only JSON matching this shape. Do not wrap it in Markdown.` Include any evidence they cannot read with tools.
-
-## Pass 1 aggregate receipt
-
-Return one aggregate receipt. Preserve result order or map it by stable key.
-
-```js
-return {
-  pass: 1,
-  advisors: results.map((result, index) => ({
-    key: result.key,
-    agent: result.agent,
-    requestedContext: roster[index].context ?? "runtime-default-unknown",
-    runId: result.runId,
-    report: result.structuredOutput ?? result.output
-  }))
-};
-```
-
-Do not replace `runtime-default-unknown` with a guessed context.
-
-## Pass 2 challenge
-
-A challenge packet contains only disputed claims, strong conflicting evidence, missing proof, owner decisions, and high-impact risks. Attribute peer content as "another advisor". Do not include full peer reports.
-
-Native Pi advisors receive `pass2OutputSchema`. External runners and fresh external fallbacks receive the same shape as JSON-only task text and no `outputSchema`.
-
-```js
-const pass2OutputSchema = {
-  type: "object",
-  required: ["responses", "recommendationChanged", "outOfScopeFindings"],
-  properties: {
-    responses: {
-      type: "array",
-      items: {
-        type: "object",
-        required: ["claimId", "disposition", "reason", "sources"],
-        properties: {
-          claimId: { type: "string" },
-          disposition: { enum: ["accept", "reject", "refine", "owner-decision"] },
-          reason: { type: "string" },
-          sources: { type: "array", items: { type: "string" } }
-        }
-      }
-    },
-    recommendationChanged: {
-      type: "object",
-      required: ["changed", "reason"],
-      properties: {
-        changed: { type: "boolean" },
-        reason: { type: "string" }
-      }
-    },
-    outOfScopeFindings: { type: "array", items: { type: "string" } }
-  }
-};
-```
-
-Use stable resume keys such as `cross-oracle`, `phase: "Council pass 2"`, concise labels, and `output: false` unless separate artifacts are useful. The aggregate Pass 2 receipt uses the Pass 1 row shape with the new `runId` and `structuredOutput ?? output`. Pass 3 resumes those latest ids with new stable keys.
-
-## Advisor profile template
-
-Create model-based advisors in the user or project agent directory, not in this package:
-
-```markdown
----
-name: council-sol
-description: Read-only fresh-context advisor for bounded council decisions
-tools: read, grep, find, ls
-model: provider/top-reasoning-model
-thinking: high
-systemPromptMode: replace
-inheritProjectContext: true
-inheritSkills: false
-defaultContext: fresh
-acceptanceRole: read-only
----
-
-Analyze the council question independently. Inspect evidence directly. Do not edit, run mutating commands, commit, push, contact peers, or spawn subagents. Return concise, cited advice using the report contract in the council task.
-```

package/node_modules/pi-subagents/skills/pi-subagents/SKILL.md

@@ -1,123 +0,0 @@
----
-name: pi-subagents
-description: |
-  Technical guidance for operator-requested delegation to builtin or custom
-  subagents: bounded handoffs, parallel review, scripted workflows, async work,
-  forked context, isolation, and coordinated execution.
----
-
-# Pi Subagents
-
-The parent works directly by default. Invoke subagents only when the operator
-requested delegation in the current request or through applicable user/project
-instructions. Task size, complexity, risk, tool-call count, recipe fit, or an
-available specialist does not independently authorize delegation.
-
-Once authorized, choose the smallest bounded shape that earns its token and
-elapsed-time overhead through concrete evidence, independent review,
-specialization, useful parallelism, or needed isolation. A single child is
-valid; writer, challenge, and review stages must each earn their overhead rather
-than becoming default ceremony. The parent keeps user intent, constraints,
-routing, arbitration, decisions, final acceptance, and publication authority,
-and may perform the work directly where it is the most efficient owner.
-
-Children do not spawn subagents unless the parent explicitly delegated fanout
-and their resolved `tools` allow `subagent`.
-
-## Launch shape
-
-| Need | Use |
-| --- | --- |
-| One bounded task for one child | direct `{ agent, task }` |
-| JavaScript control flow or data-dependent branching; sequence, fanout, retry, rolling fanout, or aggregation | a workflow script with `runs.run(...)` / `runs.all(...)` |
-| A broad plan split into visible narrow stages per lane | a workflow script with `runs.lanes([{ key, stages: [...] }])` |
-| Independent worktree or repository lanes | `references/multi-lane-orchestration.md` |
-| Council of advisors | `../council-mode/SKILL.md` |
-| Management, status, steering, authoring, or inspection | `action` |
-
-To launch a workflow script, write it as one ```` ```js workflow ```` fenced
-block in your reply, then call `subagent({ workflow: true, ... })` in the same
-reply. Use `workflow: "./path/to/script.js"` for a script file and
-`workflow: "<name>"` for a named resource.
-
-A workflow script is code-driven: `runs.run(...)` for keyed steps,
-`runs.all([...])` for fanout, plain JavaScript for branching and aggregation.
-Keep scripts portable: use top-level `await`, plain helpers, or explicit Promise
-chains, not nested async helpers. Legacy top-level `chain` / `tasks` inputs and
-durable `.chain.md` execution are inspection or migration material only, except
-that `disabledFeatures: ["workflow-scripts"]` replaces scripts with top-level
-`chain` and `tasks` (see [configuration](../../docs/configuration.md#chain-and-tasks-without-workflow-scripts)).
-
-Use `runs.lanes(...)` only inside a workflow script, not as a top-level mode,
-when a broad, predeclared plan benefits from visible per-lane stages; otherwise
-use ordinary `runs.run(...)` / `runs.all(...)`. See the [canonical staged-lane
-example](../../docs/workflows.md#parallel-sequential-lanes). Keep assignments
-bounded, but do not add stages or ceremony just to satisfy this skill.
-
-When composing `runs.run(...)`, `runs.all(...)`, or `runs.lanes(...)`, always
-supply a short verb + behavior display `label` derived from the task, unless
-the user supplied an explicit label; preserve that label. Keep the stable
-machine `key` independent (for example, `issue2011-writer` with
-`label: "Fix workflow steering"`). For `runs.lanes`, put labels on stage
-items, not lane objects. Use stage-appropriate labels for reviews and retained-child
-follow-ups too (for example, `Review workflow steering`). Generate labels in
-the orchestrator while composing the launch—no extra model call, runtime
-generator, or schema change. Native direct `{ agent, task }` calls have no
-top-level `label` parameter; do not invent one or wrap a tiny single task in
-a workflow just to label it.
-
-Use async/background by default. Set `async:false` only when the parent must
-block. Final reviews, validation gates, oracle checks, and publication checks
-stay async.
-
-In an ordinary interactive session, yield after launching or triaging useful
-async lanes and let Pi wake the parent on completion; ordinary async subagents
-already have native completion notifications, so do not call `bg_wait()` merely
-because a child is active. Use blocking `bg_wait()` only for provider,
-detached, or other background work without a native notification when a
-headless/run-to-completion contract or a required same-turn artifact makes the
-result necessary before this turn ends. For
-“continue/orchestrate/work until done,” keep the lane board moving while a safe
-immediate action remains; if only async lanes are running, record the revisit
-trigger and yield.
-
-Package agents appear in `subagent({ action: "list" })`. External CLI/job agents
-use their own runner contract. Do not pass native Pi child options to them unless
-that runner explicitly supports the option.
-
-## Read the reference for the branch
-
-For exact API fields and worked examples, call `subagent({action:"guide",options:{topic:"tool-reference"}})` or `topic:"workflows"`. The compact tool definition is not the recipe catalog; use `topic:"missions"` for mission updates and schedules.
-
-| Branch | Read |
-| --- | --- |
-| Delegate or choose roles, prompts, models, or slash commands | `references/prompting-and-roles.md` |
-| Execute single, scripted, async, scheduled, mission, forked, watchdog, oracle, or intercom workflows | `references/execution-controls.md` |
-| Review, validate, triage gate failures, or prepare delivery | `references/review-and-validation.md` |
-| Coordinate lanes, worktrees, repositories, or writer waves | `references/multi-lane-orchestration.md` |
-| List, create, edit, disable, eject, or expose agents/RPC | `references/management-authoring-rpc.md` |
-| Check safety constraints, recipes, or error handling | `references/constraints-and-recipes.md` |
-
-For an authorized complex delegated workflow, read `prompting-and-roles.md` and
-`execution-controls.md`, then load `review-and-validation.md` and
-`constraints-and-recipes.md` before launch or review.
-
-## Operating rules
-
-- Avoid duplicate scouts, overlapping writers, and vague prompts without a concrete deliverable.
-- Keep the parent on the ordinary strong default model. Route workers/scouts to a fast capable tier, serious reviews to a strong tier, and top reasoning to bounded read-only critique.
-- Exact model names are deployment policy. Put them in user/project settings or profiles, not package guidance.
-- Give every child a compact meta-prompt checklist: objective; repo/cwd/ref; authority/edit boundary; relevant files/contracts and constraints; success/acceptance criteria; validation; expected output/report; and stop/ask conditions. See `references/prompting-and-roles.md`.
-- Before launching a writer for substantial mutation work, classify it as single-seam or multi-seam and partition multi-seam work across exclusive component owners, gates, and durable handoffs before an integration-only owner. See `references/multi-lane-orchestration.md`.
-- For mutation work, use an isolated lane/worktree when isolation, overlap, or concurrent juggling matters; keep one writer per cwd/worktree. `worktree: true` refuses to launch unless the source checkout is clean (untracked files count; `.pi/subagents/` does not), so commit your own changes first or plan the lane without managed isolation. See `references/multi-lane-orchestration.md` for lane mechanics.
-- Keep long/high-output validation out of chat: prefer `interactive_shell` dispatch/background monitors, bounded logs, or subagent-owned reports; return a concise summary plus report path unless same-turn output is required. Do not use `interactive_shell` as an implicit fallback for a failed `subagent` lane; see `references/execution-controls.md`.
-- Treat subagent workflow, child launch, prompt runtime, extension load, and child tooling setup failures as lane infrastructure blockers. Stop, report the exact failure and run/worktree state, verify a clean worktree or capture a partial diff, and use only a clear same-protocol retry or an owner-approved execution-mode fallback.
-- For cross-codebase work, record the repo, explicit `cwd`, authority boundary, and expected output before launch.
-- Make parallel prompts distinct by source seam, evidence, and decision. Do not clone prompts with only item numbers swapped.
-- Prefer fresh-context review/validation fanout, then synthesize and apply fixes in the parent.
-- For Pi extension repos under `~/.pi/agent/extensions`, put lane worktrees outside extension auto-discovery, such as `~/.pi/agent/worktrees`.
-- Preserve capability ceilings, including child tool limits and allowed-agent restrictions.
-- Preserve parent authority and escalate unresolved choices.
-- Treat receipts, CI, review bots, and external-run records as evidence, not authority.
-- For backlog maintenance, releases, merge queues, or other public-repo mutation policy, load the matching user/project skill. This package defines delegation primitives, not private policy.
-- As a conservative orchestration policy, do not pass a hard `toolBudget` or tight `usageBudget` to mutation-capable workers. The default tool budget blocks read/search tools rather than mutation tools. If interrupted after a tool call starts, checkpoint after the current tool returns with changed files, build/test state, and commit or PR state.

package/node_modules/pi-subagents/skills/pi-subagents/references/constraints-and-recipes.md

@@ -1,74 +0,0 @@
-# Pi Subagents: Constraints And Recipes
-
-This file is a detailed reference loaded from `skills/pi-subagents/SKILL.md`.
-
-## Important Constraints
-
-- **Explicit forking requires a persisted parent session.** If the current session
-  does not have a persisted session file or current leaf, explicit `context: "fork"`
-  fails. An agent-level `defaultContext: fork` is a preference: packaged `oracle`
-  and `advisor` fall back to `fresh` when those fork preconditions are not
-  met yet. Use `context: "fresh"` when you do not want a fork even after the parent
-  session exists.
-- **Packaged workers start fresh.** `worker` defaults to fresh context so its brief,
-  not the parent's unfinished agenda, controls the implementation. Pass explicit
-  `context: "fork"` when inherited conversation history is required.
-- **Forked runs inherit parent history.** They are branched threads, not fresh
-  filtered contexts. Use fresh context for adversarial reviewers unless the user explicitly asks for forked context.
-- **Default subagent nesting depth is 2.** Deeper recursive delegation is blocked
-  unless configured otherwise.
-- **Attention signals are not lifecycle state.** `needs_attention` means no activity has been observed past the configured threshold. `paused` means the child turn was intentionally interrupted or is awaiting direction; it is not the same as `failed`.
-- **Intercom asks are blocking.** A session can only maintain one pending outbound
-  ask wait state at a time.
-- **Keep conversational authority clear.** Advisory subagents should not silently
-  become second decision-makers.
-- **Respect the fixed authority policy.** `authorityPolicy` is a small `auto` / `confirm` / `forbid` map for supported operational actions. Worktree discard, destructive cleanup, and spawn-budget grants default to confirmation; stop, steer, and schedule creation remain automatic. Use `worktree.discard` with the durable `handoffPath`; confirm-required actions refuse safely without an interactive UI and retained paths include manual Git recovery commands.
-
-Runtime config can change orchestration behavior. `intercomBridge.resultDelivery: false` disables only external acknowledged grouped-result delivery when native parent notifications own completion; supervisor asks/progress stay active, and enabled transport failures are still reported. `asyncByDefault` and `forceTopLevelAsync` affect whether launches detach; `waitTool` can make direct `bg_wait()` calls return immediately while headless auto-drain remains active, and its effective value is propagated to child runtimes; `globalConcurrencyLimit` bounds concurrent fanout, while a positive `maxSubagentSpawnsPerSession` optionally caps cumulative launches (`0` or unset is unlimited). Status and doctor report the budget; static work preflights declared capacity; only the settled root interactive parent can use `grant-spawn-budget` after native confirmation, with total grants bounded by the original cap. Compaction does not reset usage or grants; `singleRunOutputBaseDir` and `worktreeBaseDir` route outputs and worktrees; `completionBatch` groups async notifications. `artifactDir` is `session` (default), `project`, or `temp` and chooses where subagent artifacts are stored. Set `asyncWidget: false` to hide the above-editor background-run widget when a companion footer or dashboard owns that space (fleet inspector remains available). Per-run `artifacts: false` disables artifact capture for that launch. Async status and result artifacts include `lifecycleArtifactVersion` and fields such as `workflowGraph`, `steps`, `results`, `totalTokens`, `totalCost`, `turnCount`, `toolCount`, and nested `children`. Prefer these artifacts and `status` views over scraping terminal output.
-
-### Keep report artifacts out of the repository root
-
-Treat lane reports, review notes, council pass reports, and gate logs as scratch unless the user explicitly asks to keep them. Prefer `output: false` and the aggregate workflow result for short reports. When a later step needs a file, use the runtime-managed output artifact by setting a stable child key plus a relative `output` path such as `plans/deploy.md`; relative child outputs are saved under the run artifact directory, not the project root. Do not put `reports/...`, `*-report.json`, or similar repo-root paths in child task text.
-
-For durable evidence, copy only the final summary to session memory, a PR body/comment, a mission artifact, or a user-approved docs path outside the repo. After the PR, issue, or gate reaches a terminal state, delete or move scratch reports from the active worktree before reporting completion. Keep a project `.gitignore` entry for ad-hoc report patterns only as a safety net; it is not the cleanup mechanism.
-
-## Best Practices
-
-- Run subagents asynchronously by default; direct one-child execution is enough for one bounded task, while a workflow script (a ```` ```js workflow ```` block plus `subagent({ workflow: true })`) is the composition surface for JavaScript control flow and data-dependent branching. Use `async: false` only when the parent must block. See `references/execution-controls.md` → Async/background for wait semantics.
-- For a predeclared broad plan split into visible narrow stages, use `runs.lanes([...])` inside a workflow script; use raw `runs.run(...)`/`runs.all(...)` for conditional or rolling flows. See [`execution-controls.md`](execution-controls.md#parallel-sequential-lanes).
-- Keep one writer per cwd/worktree. Parallelize reading, review, and validation; concurrent writers need isolated worktrees. Give every child a cold-start packet with its goal, target/ref, authority, context, success criteria, validation, output, and stop rules.
-- Keep tasks narrow and standalone; do not rely on issue numbers, broad globs, or supervisor round-trips to supply missing context.
-- Keep authority with the parent. Escalate unapproved product, scope, architecture, merge, credential, or release decisions; checks, receipts, and review bots are evidence, not authority.
-- Use `fresh` context for adversarial review. `fork` is a persisted, history-inheriting branch; see `references/execution-controls.md` for its preconditions.
-- Use a same-session oracle follow-up only when its first answer leaves a material tradeoff. Treat `needs_attention` as a control signal, not failure, and do not interrupt a child merely because it is quiet during tools, tests, or reasoning.
-- Use `/name` when intercom targeting needs a stable session name.
-
-## Workflow selection
-
-This reference keeps cross-cutting policy and failure handling. Load the matching domain reference for detail:
-
-| Need | Read |
-| --- | --- |
-| Execution syntax, lifecycle, async/wait, missions, controls, watchdog, or worktrees | [`references/execution-controls.md`](execution-controls.md) |
-| Role choice, prompt contracts, review/research/cleanup techniques, or model tiering | [`references/prompting-and-roles.md`](prompting-and-roles.md) |
-| Fresh review, validation, gate failures, finding disposition, and final delivery checks | [`references/review-and-validation.md`](review-and-validation.md) |
-| Independent lanes, repositories, worktrees, and handoffs | [`references/multi-lane-orchestration.md`](multi-lane-orchestration.md) |
-| Agent management, file authoring, prompt integration, or RPC | [`references/management-authoring-rpc.md`](management-authoring-rpc.md) |
-
-After delegation is operator-authorized, choose the smallest recipe that earns
-its overhead. Recipes select a shape; they do not authorize delegation:
-
-- **Recon → plan → implement:** run one focused `scout`, then one `worker` that consumes its findings.
-- **Implementation:** clarify scope and acceptance, record user-owned decisions and seam/validation contracts, and use a bounded scout, writer, or fresh reviewer only where the requested delegation benefits from that stage. Keep one writer, inspect direct evidence, and require every added stage to earn its overhead. Split large work into serial milestones instead of a writer swarm; do not stop at review without disposition.
-- **Parallel analysis:** fan out only independent read/review/validation work, or isolate each writer in its own worktree. Never run concurrent writers in one checkout.
-
-## Error Handling
-
-- **Unknown agent:** the error lists the available agents and the directories searched; check scope/precedence and author new orchestration as a workflow script, not legacy chains.
-- **Setup, discovery, or intercom confusion:** run `subagent({ action: "doctor" })`.
-- **Max subagent depth exceeded:** flatten the workflow or raise `maxSubagentDepth` in config.
-- **Missing session file for a fork:** persist the parent session before using `context: "fork"`.
-- **Intercom already waiting for a reply:** resolve the pending ask before starting another.
-- **Parallel output-path conflict:** give each task a distinct output path, or disable output where no artifact is needed.
-- **Worktree launch failure:** ensure the git tree is clean and task cwd overrides match the shared cwd.
-- **Child fails before starting:** inspect `subagent({ action: "status", id: "..." })`, artifact metadata, output logs, and `doctor`; loader errors usually appear in child logs.