pi-subagents 0.59.0 → 0.61.0

package/skills/council-mode/SKILL.md

@@ -5,250 +5,55 @@ description: Run a bounded supervisor-mediated advisor council. Use when the use
 
 # Council Mode
 
-This skill is for the parent supervisor only. Do not inject it into advisors. The
-parent selects the roster, curates all cross-advisor communication, decides which
-feedback is valid, and writes the decision memo. Advisors do not talk directly or
-see peer transcripts by default. This is not free-form agent chat.
-
-Use council mode for a material decision with real tradeoffs. Do not use it for a
-trivial or settled question, or for implementation work. Read
-`skills/pi-subagents/references/execution-controls.md` before you launch advisors.
-
-## Roster and limits
-
-Use advisor profile names directly. A `council-*` profile defines model, tools,
-context, output defaults, and any persistent stance in the profile body. Its
-profile configuration or explicit invocation owns its context choice.
-
-Package advisors can also join the roster only when their package Pi extension is
-installed and their external-job provider is registered. For Surf, `gpt-pro` is
-available only after the `surf-cli` Pi extension loads Surf's `surf-oracle`
-provider. Treat it as a normal advisor name in `runs.all` after that provider is
-visible. It is background-only, so omit `async` unless you explicitly want
-detached receipt semantics; workflow execution will await the terminal provider
-result. External runners can lack repo tools, structured-output support, or
-resumability. For them, include the needed evidence or file excerpts in the task,
-use the text JSON contract below instead of `outputSchema`, and use the
-fresh-context fallback path for cross-exam when the run is not resumable.
-
-Create model-based profiles in your user or project agent directory. Do not add
-them to this package. This is a valid example:
-
-```markdown
----
-name: council-sol
-description: Read-only fresh-context advisor for bounded council decisions
-tools: read, grep, find, ls
-model: openai-codex/gpt-5.6-sol
-thinking: high
-systemPromptMode: replace
-inheritProjectContext: true
-inheritSkills: false
-defaultContext: fresh
-acceptanceRole: read-only
----
+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.
 
-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.
-```
-
-After `subagent({ action: "list" })`, prefer 2–3 executable names that start with
-`council-`. The prefix is a naming convention, not runtime selection. If fewer
-than two profiles are available, fill the roster with `oracle`, then `reviewer`,
-until it has two advisors. Launch fallback `oracle` with `context: "fork"` so
-global defaults cannot remove its parent-chat context. Let fallback `reviewer`
-use its normal profile context. Note the fallback and known context modes in the
-memo. Use the normal single-oracle consultation loop only when a requested roster
-or unavailable builtins leaves fewer than two advisors.
-Label that result as degraded mode. Never use more than four advisors.
-
-Pass 1 is independent reports. Pass 2 is one cross-exam. The default pass cap is
-2. Run pass 3 only when `--max-passes 3` was requested and a material dispute can
-be settled by evidence an advisor can produce. Never run an unbounded loop.
+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. The parent writes a brief with the question, scope, non-goals, evidence targets,
-   roster, known advisor context modes, and pass cap. If the user wants a specific
-   lens, keep it in the question, scope, or profile body instead of inventing a
-   per-advisor label.
-2. Before Pass 1, tell the user the roster, requested or known context modes, and
-   pass cap. Use a stable key, `phase`, and concise `label` for every
-   workflow child. For example, use `advisor-oracle`, `phase: "Council pass 1"`,
-   and `label: "Oracle — intent and consistency"`.
-3. Launch one async `workflowScript` with `runs.all` for independent advisor
-   reports. Set `context` when the selected advisor has a known profile context or
-   a fallback rule requests one, because a global default can otherwise override
-   that profile. Set `context: "fork"` for fallback `oracle`. If no advisor context
-   is known, omit `context` and disclose the unknown runtime default in the memo.
-   Each advisor is read-only and must not spawn children, edit files, run mutating
-   commands, commit, or push. Set `output: false` unless separate advisor artifacts
-   are explicitly requested or useful for the decision. When separate artifacts are
-   useful, give advisors relative output paths so the runtime stores them under its
-   managed artifact directory; do not ask them to write root-level council report
-   files. For installed
-   external-runner advisors such as Surf `gpt-pro` after `surf-oracle` is
-   registered, do not pass `outputSchema`; put the schema request in the task text
-   and accept `result.output` as the report.
-4. Return one aggregate Pass 1 receipt. After it completes, tell the user the
-   completion count, agreement count, dispute count, and whether Pass 2 is needed.
-5. The parent synthesizes a claim matrix in session. It contains agreements,
-   disputed claims, missing proof, owner decisions, and a relay set of at most five
-   high-impact claims per advisor. Do not delegate this synthesis.
-6. Before Pass 2, tell the user how many claims are relayed and why each is
-   material. Launch a second async `workflowScript` with `runs.all` resume calls.
-   Each task is a curated challenge packet, not a peer transcript. A resume requires
-   a retained run id and a non-empty task. It excludes `agent` and rejects `gate`.
-   Record the new run id from every resume. Pass 3 resumes those latest ids. Return
-   one aggregate Pass 2 receipt.
-7. After Pass 2, tell the user whether the council converged or which owner
-   decisions remain. The parent writes the final memo. Do not delegate it.
-
-If an advisor is not resumable, run the same profile in fresh context with its own
-pass-1 report and the challenge packet. Label that response as a fresh-context
-fallback, not a 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.
-
-## Advisor contracts and pass receipts
-
-Pass-1 reports are at most about 600 words. Give native Pi advisors the same
-`outputSchema`, so reports are comparable without heading cleanup. For
-external-runner advisors, do not pass `outputSchema`; ask them to return compact
-JSON text with the same fields. The following shape is a contract template. Use
-the runtime schema syntax supported by the workflow for native advisors and keep
-narrative fields as strings:
-
-```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" } }
-  }
-};
-```
-
-Include this contract in each Pass 1 task: inspect supplied evidence directly; do
-not see or ask about other advisors; stay read-only; do not spawn children; return
-only the structured report. For external-runner advisors, say `Return only JSON
-matching this shape. Do not wrap it in Markdown.` and include any evidence they
-cannot read through tools.
-
-After `runs.all`, return one aggregate receipt rather than making the parent find
-separate artifacts. Preserve the result order or map it by stable key so each row
-contains the advisor identity and report:
-
-```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. It records that
-the launch intentionally omitted context.
-
-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. Use a common Pass 2 contract:
-
-```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 requested or useful. Keep
-any artifact outputs under the managed run artifact directory. Do not pass
-`outputSchema` to external-runner fallback launches; ask for compact JSON text
-instead. The aggregate Pass 2 receipt uses the same row shape as Pass 1, with the
-new `runId` and `structuredOutput ?? output`.
-
-## Stop and memo
-
-Converged means no disputed claim remains that both materially affects the
-recommendation and can plausibly be settled by evidence. Stop at convergence, the
-pass cap, failed fallback, or user interruption. Put unresolved disputes in owner
-decisions. Never add a round for polish or symmetry.
-
-The parent memo states the question and scope, recommendation, rationale, accepted
-and rejected feedback with reasons, owner decisions, evidence and run ids,
-confidence, what would change the decision, and the roster, passes, fallbacks, and
-known advisor context modes. Identify advisors by profile name or model-based
-profile, not by invented role labels. State that fallback `oracle` is context-aware
-and forked.
-
-Council mode is not agent-to-agent chat, a transcript dump, mutation authority,
-auto-escalation to writer lanes, or a council UI. Escalate to a writer only after
-the parent memo and only when the user explicitly requests it.
+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 `workflowScript` 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/skills/council-mode/references/pass-contracts.md

@@ -0,0 +1,150 @@
+# 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/skills/pi-subagents/SKILL.md

@@ -1,51 +1,103 @@
 ---
 name: pi-subagents
 description: |
-  Delegate work to builtin or custom subagents with single-agent, parallel,
-  scripted-chaining, async, forked-context, and coordinated workflows. Use
-  for advisory review, implementation handoffs, and multi-step tasks where a
-  single agent should stay in control while other agents contribute context,
-  planning, or execution.
+  Delegate to builtin or custom subagents for single-agent handoffs, parallel
+  review, scripted chaining, async work, forked context, and coordinated
+  workflows. Use when one parent agent should stay in control while children
+  supply focused context, planning, review, or execution.
 ---
 
 # Pi Subagents
 
-This skill is for the main parent orchestrator only. Do not inject or follow it inside spawned child subagents. The parent session owns delegation, orchestration, review fanout, and final fix-worker launches. Ordinary children should not run their own subagent workflows; the explicit exception is a delegated fanout child whose resolved builtin `tools` includes `subagent`, and that child may use `subagent` only for the fanout work the parent assigned.
+Choose a mode:
 
-Use this skill when the parent orchestrator needs one specialized child or composed orchestration. Use `workflowScript` for all execution, including one isolated child. Chaining is still supported, but it is code-driven: use `await runs.run(...)` for sequential steps, `runs.all([...])` for parallel fanout, and ordinary JavaScript for branching, retries, gate monitors, and aggregation. Keep workflow helpers portable: use plain helper functions or explicit Promise chains, not nested `async function` helpers, async arrows, or async methods. Do not use legacy top-level `chain` / `tasks` inputs or durable `.chain.md` execution. Scripted workflows normally start asynchronously unless config sets `asyncByDefault:false`; set `async:true` explicitly when async behavior matters. Pass `async:false` only when the parent must block until completion. Async mode still shows progress. Do not use `async:false` for final reviews, backlog gates, run-to-completion convenience, or because no other work is available.
+- **Direct mode:** For tiny or focused work, the parent handles the task
+  directly; a single bounded child handoff is fine. Skip workflow ceremony.
+- **Orchestrator mode:** For substantial or delegated work, the parent is the
+  supervisor, arbiter, and authority holder—not the routine primary doer.
+  Subagents may own planning/design, scouting, implementation,
+  simplification/challenge, validation, and review as useful. The parent keeps
+  user intent, constraints, authority, routing, arbitration, final acceptance,
+  and publication.
+- A useful loop for substantial work is **writer → challenge/simplify → review**;
+  the parent arbitrates between steps, and tiny tasks can skip it.
+- Direct parent edits during orchestrator mode should be intentional, small
+  interventions with a brief reason.
 
-Package-installed agents appear in `subagent({ action: "list" })` with builtin, user, and project agents. If `surf-cli` is installed as a Pi package, the Surf browser extension is loaded, and Chrome is logged into a ChatGPT Pro account, Surf can expose `gpt-pro`: a read-only async advisor that reaches ChatGPT web through Surf Oracle. Check it with `subagent({ action: "get", agent: "gpt-pro" })` and run it with `subagent({ agent: "gpt-pro", task: "Review this plan and identify release risks." })`.
+Children do not spawn subagents unless the parent explicitly delegated fanout
+and their resolved `tools` allow `subagent`.
 
-## How to use this router
+## Launch shape
 
-Read the matching reference file before acting. Paths are relative to this `SKILL.md`; resolve them against `skills/pi-subagents/` and load them with the read tool.
+| 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 | `workflowScript` with `runs.run(...)` / `runs.all(...)` |
+| A broad plan split into visible narrow stages per lane | `workflowScript` 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` |
+
+`workflowScript` 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.
+
+Use `runs.lanes(...)` only inside a `workflowScript`, 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.
+
+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.
 
-| Task | Read |
+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
+
+| Branch | Read |
 | --- | --- |
-| Decide whether to delegate, choose agents, compare tool versus slash commands, apply prompt techniques, or understand builtin roles | `references/prompting-and-roles.md` |
-| Use council mode, convene several advisors, debate a decision, cross-examine recommendations, critique or improve a plan with multiple model perspectives, or run `/council` | `../council-mode/SKILL.md` |
-| Run one-child, scripted, async, scheduled, mission-backed, forked, watchdog, oracle, or intercom-coordinated workflows | `references/execution-controls.md` |
-| Coordinate several independent tasks, worktrees, repositories, or writer lanes | `references/multi-lane-orchestration.md` |
-| List/create/update/delete/eject/disable agents, inspect legacy chain records, edit agent files, use prompt-template integration, or expose extension RPC | `references/management-authoring-rpc.md` |
-| Check safety constraints, best practices, standard workflows, or error handling | `references/constraints-and-recipes.md` |
-
-For broad or uncertain requests, read more than one reference. For complex work, start with `references/prompting-and-roles.md` and `references/execution-controls.md`, then consult `references/constraints-and-recipes.md` before launching or reviewing child work.
-
-External CLI agents such as `codex-exec`, `codex-exec-writer`, `claude-code`, and `cursor-agent` use their own runner contract. Do not pass native Pi child options such as model override, structured output, acceptance/agent contract, tool budgets, fast mode, fork context, skills, or native Pi tools unless that runner explicitly implements them.
-
-## Always-on constraints
-
-- Keep the parent as orchestrator and final decision-maker.
-- Before multiple mutation-capable lanes, record a lane board and each lane's isolation path.
-- For plan, design, or architecture advice that asks for council mode, asks to convene several advisors, compare model perspectives, debate a decision, cross-examine recommendations, or critique and improve a plan, read `../council-mode/SKILL.md` and use Council Mode instead of ad hoc parallel oracle calls.
-- For plan, design, or architecture advice that asks to consult, discuss with, or come to agreement with one `oracle`, use a short same-session consultation loop: read the first result, resume once with a targeted challenge when material tradeoffs remain, then synthesize the parent decision. Keep explicit one-shot, trivial, and fully settled consultations one-shot.
-- Use one writer per cwd/worktree unless isolated worktrees are intentional.
-- For cross-codebase work, record the target repo, explicit `cwd`, authority boundary, and expected output before launch. Do not assume the parent session cwd is the child repo.
-- For parallel fanout, compare child prompts before launch. Do not send clone prompts with only issue numbers, titles, or broad file globs swapped; each child needs a lane-specific task, source seam, prior evidence, and decision that remains distinct without the item number. Launch that fanout as one async `workflowScript` with stable keys and aggregate output unless there is truly only one child.
+| 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 complex work, 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`.
+- For mutation work, use an isolated lane/worktree when isolation, overlap, or concurrent juggling matters; keep one writer per cwd/worktree. 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. See `references/execution-controls.md`.
+- 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.
-- Use async/background by default. Final reviews, gate checks, oracle checks, and backlog lanes stay async. Use `async:false` only when the parent must block until completion. Do not poll just to wait. For adaptive gates, branch in `workflowScript`.
-- For Pi extension repos whose canonical checkout is under `~/.pi/agent/extensions`, never create lane worktrees as sibling directories there. Pi auto-loads `~/.pi/agent/extensions/*/index.ts`, so sibling worktrees can register duplicate tools. Put lanes under `~/.pi/agent/worktrees`, another worktree base outside auto-discovery, or a temporary clone. If a lane must run the modified extension itself, use an isolated Pi config home with `PI_CODING_AGENT_DIR=<lane-config> pi --no-extensions -e <lane>/index.ts`. Use full containers only when path and config isolation are insufficient.
-- Preserve capability ceilings, including child tool restrictions and session-scoped allowed-agent restrictions.
-- Escalate unresolved product, architecture, authority, release, merge, or safety decisions upward instead of letting a child decide silently.
-- Treat receipts, CI, review bots, and external-run records as evidence, not authority to merge, close, comment, publish, or release.
-- 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, and reported usage has no reservation model. If a worker is interrupted after a tool call starts, checkpoint after the current tool returns with changed files, build/test state, and commit or PR state.
+- 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.