@pi-unipi/unipi 2.6.4 → 2.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/unipi",
-  "version": "2.6.4",
+  "version": "2.7.0",
   "description": "All-in-one extension suite for Pi coding agent",
   "type": "module",
   "license": "MIT",
@@ -66,7 +66,11 @@
       "packages/milestone/skills",
       "packages/kanboard/skills",
       "packages/updater/skills",
-      "packages/image/skills"
+      "packages/image/skills",
+      "packages/subagents/skills"
+    ],
+    "prompts": [
+      "packages/subagents/prompts"
     ]
   },
   "peerDependencies": {
@@ -78,30 +82,31 @@
   "dependencies": {
     "@pi-unipi/ask-user": "2.6.1",
     "@pi-unipi/btw": "2.6.1",
-    "@pi-unipi/compactor": "2.6.1",
-    "@pi-unipi/notify": "2.6.1",
     "@pi-unipi/command-enchantment": "2.6.1",
+    "@pi-unipi/compactor": "2.6.1",
     "@pi-unipi/core": "2.6.1",
+    "@pi-unipi/footer": "2.6.1",
+    "@pi-unipi/image": "2.6.1",
     "@pi-unipi/info-screen": "2.6.1",
+    "@pi-unipi/input-shortcuts": "2.6.1",
+    "@pi-unipi/kanboard": "2.6.1",
     "@pi-unipi/mcp": "2.6.1",
     "@pi-unipi/memory": "2.6.1",
+    "@pi-unipi/milestone": "2.6.1",
+    "@pi-unipi/notify": "2.6.1",
     "@pi-unipi/ralph": "2.6.1",
     "@pi-unipi/subagents": "2.6.1",
+    "@pi-unipi/updater": "2.6.1",
     "@pi-unipi/utility": "2.6.1",
-    "@pi-unipi/milestone": "2.6.1",
-    "@pi-unipi/kanboard": "2.6.1",
     "@pi-unipi/web-api": "2.6.1",
-    "@pi-unipi/workflow": "2.6.1",
-    "@pi-unipi/footer": "2.6.1",
-    "@pi-unipi/updater": "2.6.1",
-    "@pi-unipi/input-shortcuts": "2.6.1",
-    "@pi-unipi/image": "2.6.1"
+    "@pi-unipi/workflow": "2.6.1"
   },
   "devDependencies": {
     "@earendil-works/pi-agent-core": "^0.80.0",
     "@earendil-works/pi-ai": "^0.80.0",
     "@earendil-works/pi-coding-agent": "^0.80.0",
     "@earendil-works/pi-tui": "^0.80.0",
+    "@types/better-sqlite3": "^9.6.0",
     "@types/node": "^25.6.0",
     "diff": "^7.0.0",
     "esbuild": "^0.27.7",

package/packages/autocomplete/src/constants.ts

@@ -129,6 +129,11 @@ export const COMMAND_REGISTRY: Record<string, string> = {
   // ask-user (1 command)
   "unipi:ask-user-settings": "ask-user",
 
+  // subagents (3 commands)
+  "unipi:subagents-fleet":  "subagents",
+  "unipi:subagents-doctor": "subagents",
+  "unipi:subagents-guide":  "subagents",
+
   // info (2 commands)
   "unipi:info":          "info",
   "unipi:info-settings": "info",

package/packages/subagents/README.md

@@ -1,110 +1,121 @@
 # @pi-unipi/subagents
 
-Parallel execution with file locking. Spawn background or foreground agents to work on tasks concurrently — research files, fix lint errors, run tests — while the main agent keeps going.
-
-Two built-in agent types: `explore` for read-only research, `work` for file modifications with transparent locking. Define your own types as markdown files.
-
-## Commands
-
-Subagents has no user commands. It's an agent tool package — the agent calls it directly.
-
-## Special Triggers
-
-Workflow skills detect subagents and inject parallel strategies. When `@pi-unipi/subagents` is installed, these skills get enhanced:
-
-| Skill | What Changes |
-|-------|--------------|
-| `brainstorm` | Parallel research for different approaches |
-| `document` | Parallel documentation of different modules |
-| `gather-context` | Parallel codebase exploration |
-| `review-work` | Parallel task verification |
-| `scan-issues` | Parallel scanning by category |
-| `work` | Parallel task execution (with file locking) |
+Delegate work to focused child agents — in parallel, in the background, or as scripted multi-agent workflows. Feature parity with [pi-subagents](https://github.com/nicobailon/pi-subagents), built on unipi conventions: foreground children run in-process (live widget streaming), background/fork/resume/worktree runs use child `pi` processes.
+
+## Agents
+
+Built-in agents (lowest discovery priority — user/project definitions override):
+
+| Agent | Use it for |
+|-------|------------|
+| `explore` | Read-only file research and parallel reads |
+| `work` | File modifications with transparent locking |
+| `scout` | Fast codebase recon: entry points, data flow, risks |
+| `researcher` | Web research with sources (`web_search`, `multi_web_content_read`) |
+| `worker` | Implementation: narrow edits, validation, escalation |
+| `reviewer` | Code review of diffs, plans, solutions |
+| `oracle` | Second opinion; challenges assumptions without editing |
+| `delegate` | Lightweight general delegate close to the parent session |
+
+Custom agents are markdown files with YAML frontmatter:
+
+```markdown
+---
+name: security-reviewer
+description: Security-focused review
+tools: read, grep, find
+thinking: high
+memory: { scope: "project", path: "security-reviewer" }
+---
+
+Review changes for unsafe input handling...
+```
 
-Subagents registers with the info-screen dashboard, showing active agents and their status. The footer displays agent activity in its extension status segment.
+Discovery: project `.unipi/config/agents/` > global `~/.unipi/config/agents/` > builtins. Aliases resolve (`developer` → `worker`, `advisor` → `oracle`). Per-agent overrides live in `subagents.json`.
 
-## Agent Tools
+## Tools
 
 | Tool | Description |
 |------|-------------|
-| `spawn_helper` | Launch a sub-agent for parallel work |
-| `get_helper_result` | Check status and retrieve results from a background agent |
-
-### spawn_helper Parameters
-
-| Parameter | Description |
-|-----------|-------------|
-| `type` | Agent type (`explore`, `work`, or custom) |
-| `prompt` | Task for the agent |
-| `description` | Short description (3-5 words) |
-| `run_in_background` | Return immediately, notify on completion |
-| `max_turns` | Max agentic turns before stopping |
-| `model` | Model override (e.g. `"haiku"`, `"sonnet"`) |
-| `thinking` | Thinking level (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`) |
+| `spawn_helper` | Launch agents: single child, `workflowScript` orchestration, or management `action`s |
+| `get_helper_result` | Wait on / inspect background runs; `nonBlocking` wake subscriptions |
 
-### Foreground (blocks until done)
+### Single child
 
 ```
-spawn_helper(
-  type: "explore",
-  prompt: "Find all auth-related files",
-  description: "Research auth files"
-)
+spawn_helper({ agent: "scout", task: "Analyze the auth flow" })
+spawn_helper({ agent: "worker", task: "Implement it", run_in_background: true })
+spawn_helper({ agent: "reviewer", task: "Review", gate: "npm test" })
 ```
 
-### Background (returns immediately)
+Legacy aliases (`type`, `prompt`, `max_turns`) still work.
 
+### Scripted workflows
+
+```js
+spawn_helper({ workflowScript: `
+  const scan = await runs.run("scan", { agent: "scout", task: "Analyze auth" });
+  const reviews = await runs.all([
+    { key: "correctness", agent: "reviewer", task: "Review correctness: " + scan.output },
+    { key: "tests", agent: "reviewer", task: "Review tests: " + scan.output }
+  ]);
+  return reviews.map(r => r.output);
+`, async: false })
 ```
-spawn_helper(
-  type: "work",
-  prompt: "Fix all lint errors in src/",
-  description: "Fix lint errors",
-  run_in_background: true
-)
-```
 
-### Check Background Result
+`runs.run` / `runs.all` / `runs.steer` inside a sandboxed VM. Budgets (`turnBudget`, `toolBudget`, `usageBudget`), worktree isolation, fork context, and acceptance gates available per child.
+
+### Management actions
 
 ```
-get_helper_result(agent_id: "helper_abc123")
+spawn_helper({ action: "list" | "get" | "status" | "children.list" })
+spawn_helper({ action: "resume", id: "<run>", message: "Reconsider X" })
+spawn_helper({ action: "doctor" | "guide", topic: "workflows" })
+spawn_helper({ action: "mission.create", mission: { title, objective } })
+spawn_helper({ action: "schedule.create", name, agent, task, every: "30m" })
 ```
 
-Foreground and retrieved background results have a hard 64 KiB model-visible ceiling. For raw results up to 16 MiB, larger output includes a bounded head/tail preview and a path to the complete private mode-0600 artifact under a mode-0700 `~/.unipi/tool-results/` directory. Use `read` with offset/limit to inspect only the needed region. Repeated retrieval reuses the same artifact. Results above the safety cap or artifact-write failures still return a preview with an explicit non-retention warning.
-
-## Custom Agent Types
-
-Create markdown files defining agent behavior:
+## Observability
 
-```bash
-# Global agents
-~/.unipi/config/agents/reviewer.md
+- **FleetView** panel: active work from both transports. `↓` to inspect, `j/k` navigate, `enter` opens transcripts, `esc` closes.
+- **`/unipi:subagents-fleet`** · **`/unipi:subagents-doctor`** · **`/unipi:subagents-guide [topic]`**
+- Background completions arrive as `<task-notification>` follow-ups automatically.
+- Supervisor channel: blocked children can `contact_supervisor` for decisions.
 
-# Project agents
-<workspace>/.unipi/config/agents/deployer.md
-```
+## Configuration
 
-## Configurables
+`~/.unipi/config/subagents.json` (global) + `<workspace>/.unipi/config/subagents.json`:
 
 ```json
-// ~/.unipi/config/subagents.json
 {
-  "enabled": true,
-  "maxConcurrent": 3,
-  "types": {
-    "explore": { "enabled": true },
-    "work": { "enabled": true }
+  "subagents": {
+    "defaultModel": "ds/deepseek-v4-flash",
+    "asyncByDefault": true,
+    "maxSubagentSpawnsPerRun": 64,
+    "fleetViewPlacement": "belowEditor"
   }
 }
 ```
 
-| Setting | Default | What It Does |
-|---------|---------|--------------|
-| `enabled` | true | Enable/disable subagents |
-| `maxConcurrent` | 3 | Max agents running at once |
-| `types.{name}.enabled` | true | Disable built-in or custom agent types. Disabled types are omitted from tool guidance and rejected before queueing. |
+Full key reference: `spawn_helper({ action: "guide", topic: "configuration" })`. Env overrides use the `UNIPI_SUBAGENT_*` prefix.
+
+## Storage
+
+| Path | Contents |
+|------|----------|
+| `~/.unipi/missions/<project-hash>/` | Durable mission records |
+| `~/.unipi/schedules/<project-hash>/` | Scheduled runs |
+| `~/.unipi/agent-memory/` | Per-agent persistent memory |
+| temp root (`unipi-subagents-*`) | Run artifacts, results, channels (auto-cleaned) |
+
+## Commands
 
-For custom agents, JSON configuration and Markdown frontmatter are both enforced: the type can run only when neither source sets `enabled: false`. Configuration is loaded when the extension starts, so reload the session after changing enablement.
+| Command | Description |
+|---------|-------------|
+| `/unipi:subagents-fleet` | Show active fleet |
+| `/unipi:subagents-doctor` | Config + capacity diagnosis |
+| `/unipi:subagents-guide [topic]` | Bundled guide |
 
-## License
+## Prompt shortcuts
 
-MIT
+`/council`, `/parallel-review`, `/review-loop`, `/parallel-research`, `/gather-context-and-clarify`, `/parallel-cleanup` — packaged prompt templates for common orchestration patterns.

package/packages/subagents/package.json

@@ -10,7 +10,8 @@
   },
   "dependencies": {
     "@pi-unipi/core": "2.6.1",
-    "@earendil-works/pi-agent-core": "^0.80.0"
+    "@earendil-works/pi-agent-core": "^0.80.0",
+    "acorn": "8.18.0"
   },
   "devDependencies": {
     "typescript": "^5.8.3"
@@ -23,13 +24,18 @@
   "files": [
     "src/**/*.ts",
     "src/global.d.ts",
+    "agents/*.md",
+    "prompts/*.md",
+    "skills/**/*",
     "README.md"
   ],
   "pi": {
     "extensions": [
       "./src/index.ts"
     ],
-    "skills": [],
+    "skills": [
+      "./skills"
+    ],
     "prompts": [],
     "themes": []
   }

package/packages/subagents/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/packages/subagents/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/unipi 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.