@pi-unipi/subagents 2.6.1 → 2.6.2

package/prompts/gather-context-and-clarify.md

@@ -0,0 +1,13 @@
+---
+description: Use subagents to gather context, then ask clarifying questions
+---
+
+Based on our discussion and my intent, launch focused context-gathering subagents before planning or implementing.
+
+Use `scout` to inspect the relevant local files, existing patterns, constraints, tests, and likely integration points. Use `researcher` when external docs, recent sources, ecosystem context, or primary evidence would improve the answer.
+
+Give each subagent a specific meta prompt. Ask them to return concise findings plus the remaining clarification questions that matter for implementation confidence.
+
+After they return, synthesize what we know and use the `interview` tool to ask me the unresolved questions needed to reach a shared understanding.
+
+$@

package/prompts/parallel-cleanup.md

@@ -0,0 +1,59 @@
+---
+description: Parallel cleanup review
+---
+
+Run a fresh-context parallel cleanup review of the current work.
+
+Use the `spawn_helper` tool. First inspect available agents/skills if needed, then launch two reviewer subagents in parallel with `context: "fresh"`. Do not use forked context unless I explicitly ask for it. Reviewers must inspect the repository, relevant instructions, and current diff directly from files and commands. They must not rely on the main conversation history.
+
+Do not write reviewer output files into the repository unless I explicitly ask for artifacts. Prefer `output: false` for each reviewer task.
+
+Reviewer 1: deslop pass.
+
+If the `deslop` skill is available, pass it to this reviewer. If not, inline the guidance below. Ask this reviewer to look for AI-slop patterns in the changed scope:
+- comments that restate code, placeholder text, stale rationale, or debug leftovers;
+- defensive checks that hide useful errors, return vague defaults, or validate trusted internal data after a real boundary was already crossed;
+- type escapes, broad casts, duplicated type definitions, or object-bag typing where a local source-of-truth type exists;
+- style drift from nearby non-slop code and project instructions;
+- generated-sounding docs, changelog text, UI copy, status text, or test names;
+- pass-through wrappers, dead helpers, duplicate helper signatures, duplicated test harness setup, or abstractions that do not enforce an invariant;
+- UI or CLI copy that is noisy, vague, brittle, or makes the user do extra interpretation.
+
+Tell this reviewer to treat tool output and slop-scan-style findings as leads, not verdicts. It should flag only concrete issues in the requested scope with evidence, severity, file/line references, and the smallest safe fix.
+
+Reviewer 2: verbosity pass.
+
+If the `verbosity-cleaner` skill is available, pass it to this reviewer. If not, inline the guidance below. Ask this reviewer to look for needless verbosity in code, tests, docs, status text, grouped messages, receipts, and changelog wording:
+- single-use helpers that merely paraphrase an expression;
+- temporary variables that only name obvious expressions;
+- nested returns or branches that can become direct returns without hiding intent;
+- multi-line cleanup scaffolding that can use a local direct pattern while preserving cleanup semantics;
+- repeated boilerplate that can use an existing local fixture or a small local helper;
+- tests that restate formatter details already covered at a cheaper layer;
+- regression tests where one focused assertion would cover the bug but wrapper/API-adjacent tests only repeat the same claim;
+- prose that says the same thing twice, sounds generic, or buries the important rule.
+
+Tell this reviewer that shorter is only better when it is clearer and preserves behavior, error signals, cleanup semantics, useful invariants, and local style.
+
+Both reviewers are review-only. They must not edit files unless I explicitly ask for a writer pass. Their response should be review feedback, not a context summary. Ask them to return concise, evidence-backed findings with file/line references and suggested fixes.
+
+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 cleanup scope. Remove it before deciding the cleanup 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 scope or focus from the slash command invocation:
+
+$@

package/prompts/parallel-research.md

@@ -0,0 +1,50 @@
+---
+description: Parallel subagents research
+---
+
+Launch parallel research subagents to build a grounded answer to the current question or decision.
+
+Use fresh context, not forked context, unless I explicitly ask for forked context. Researchers and scouts should inspect sources directly instead of relying on the main conversation history.
+
+Use a combination of `researcher` and `scout` subagents:
+- Use `researcher` for web, docs, standards, ecosystem, recent changes, benchmarks, and primary-source evidence.
+- Use `scout` for local codebase context, existing implementation patterns, repo constraints, and files that would be affected.
+
+Give each subagent a distinct angle. Unless I specify angles, use these three:
+
+1. External evidence
+   Use `researcher` to find current, authoritative sources: official docs, specs, release notes, benchmarks, issue threads, or primary explanations.
+
+2. Local code context
+   Use `scout` to inspect the repository for relevant files, existing patterns, constraints, tests, and likely integration points.
+
+3. Practical tradeoffs
+   Use `researcher` or `scout`, whichever fits the question, to compare options, risks, edge cases, maintenance cost, and what would be easiest to validate.
+
+Adapt the angles when the question calls for it:
+- Library/API questions: include official docs and recent examples.
+- Architecture decisions: include local module boundaries, dependency direction, and migration cost.
+- Debugging questions: include likely failure modes, local call paths, and exact error evidence.
+- UI/product questions: include user flow, accessibility, design precedent, and implementation constraints.
+- Time-sensitive topics: include a recent-developments angle and prefer 2026/2025 sources.
+
+Prefer two or three strong subagents over many vague ones. The parent agent should frame the question and assign angles; the child agents should research or scout, not invent broad plans.
+
+Ask each subagent to return concise findings with evidence:
+- file paths and line ranges for local findings
+- source links for external findings
+- confidence level and gaps
+- recommended next step or decision implication
+
+Do not ask subagents to edit files. This is a research pass only unless I explicitly ask for implementation.
+
+After the subagents return, synthesize the answer into:
+- what we know
+- what the local codebase implies
+- tradeoffs and risks
+- gaps or assumptions
+- the recommended next move
+
+If findings disagree, call out the disagreement instead of smoothing it over.
+
+$@

package/prompts/parallel-review.md

@@ -0,0 +1,54 @@
+---
+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. The response should be review feedback, not a context summary. Reviewers must not edit files unless I explicitly ask for a writer pass.
+
+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/prompts/review-loop.md

@@ -0,0 +1,43 @@
+---
+description: Review/fix loop until clean
+---
+
+Run a parent-orchestrated review loop for the requested work.
+
+Use the `spawn_helper` 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 blockers or fixes worth doing now.
+
+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 with `workflowScript` when it is already clear, or continued as follow-up single-agent runs after each async completion. For an initial workflowScript, 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 `turnBudget`, a hard `toolBudget`, or a 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.
+
+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:
+- blockers or scope/product/architecture decisions that need user approval;
+- fixes worth doing now;
+- 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 turn or 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.
+
+Stop and summarize when one of these is true:
+- reviewers find no blockers or 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/skills/council-mode/SKILL.md

@@ -0,0 +1,230 @@
+---
+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
+
+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
+
+Roles such as architect, skeptic, operator, and performance reviewer belong to the
+`/council` request. A `council-*` profile defines only model, tools, context, and
+output defaults. Its profile configuration or explicit invocation owns its context
+choice.
+
+Create model-based profiles in your user or project agent directory. Do not add
+them to this package. This is a valid example; roles still come from `/council`:
+
+```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
+---
+
+Analyze only the assigned council role. 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 `spawn_helper({ 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.
+
+## Protocol
+
+1. The parent writes a brief with the question, scope, non-goals, evidence targets,
+   roster, roles, and pass cap.
+2. Before Pass 1, tell the user the roster, roles, 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.
+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`, turn budgets, 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 each advisor the same
+`outputSchema`, so reports are comparable without heading cleanup. The following
+shape is a contract template. Use the runtime schema syntax supported by the
+workflow 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.
+
+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,
+    role: roster[index].role,
+    requestedContext: roster[index].context ?? "runtime-default-unknown",
+    runId: result.runId,
+    report: result.structuredOutput
+  }))
+};
+```
+
+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. The
+aggregate Pass 2 receipt uses the same row shape as Pass 1, with the new `runId`
+and `structuredOutput`.
+
+## 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, roles, passes,
+fallbacks, and known advisor context modes. 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.

package/skills/subagents/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: unipi-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.
+---
+
+# 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.
+
+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.
+
+Package-installed agents appear in `spawn_helper({ 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 `spawn_helper({ action: "get", agent: "gpt-pro" })` and run it with `subagent({ agent: "gpt-pro", task: "Review this plan and identify release risks." })`.
+
+## How to use this router
+
+Read the matching reference file before acting. Paths are relative to this `SKILL.md`; resolve them against `skills/subagents/` and load them with the read tool.
+
+| Task | 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.
+
+## 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.
+- 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 `turnBudget`, a hard `toolBudget`, or a 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.