@selesai/code 0.9.10 → 0.9.12

package/dist/skills/pi-subagents/references/prompting-and-roles.md

@@ -1,69 +1,64 @@
-# Selesai Subagents: Prompting And Roles
+# Pi Subagents: Prompting And Roles
 
 This file is a detailed reference loaded from `skills/pi-subagents/SKILL.md`.
 
 ## Capability ceilings
 
-Parent extensions may register a session-scoped, out-of-band ceiling through `pi-subagents/capability-ceiling`. Child tools and eligible canonical agent names are intersected with every active registration and inherited snapshot; `denyExtensions` removes ambient/provider extension loading while retaining package protocol runtime. `{ action: "list" }` marks non-allowlisted agents as restricted, and launch rejects them before spawn. Do not add a model-visible ceiling field or rely on unrestricted role selection for enforcement. Removed schedule actions are unsupported.
+Parent extensions may register a session-scoped, out-of-band ceiling through `pi-subagents/capability-ceiling`. Child tools and eligible canonical agent names are intersected with every active registration and inherited snapshot; `denyExtensions` removes ambient/provider extension loading while retaining package protocol runtime. `{ action: "list" }` marks non-allowlisted agents as restricted, and launch rejects them before spawn. Do not add a model-visible ceiling field or rely on unrestricted role selection for enforcement. Restricted schedules are rejected until their ceiling can be persisted safely.
 
 ## When to Use
 
 - **Complex work orchestration**: use Fable mode as the default parent-agent loop for complex work. Complex means the task has multiple moving parts, unclear acceptance, cross-cutting code, meaningful user-visible impact, expensive or irreversible validation, broad review surface, or the user asks for orchestration. Lightweight one-off delegation can stay lightweight.
-- **Advisory review**: use fresh-context `reviewer` (or the Selesai-native `commentator`) agents for adversarial code review, or fork to `oracle` when inherited decisions and drift matter
-- **Implementation handoff**: have `oracle` advise, then `worker` (or the Selesai-native `builder`) implement only after an approved direction
-- **Recon and planning**: use `scout` (or `explorer`) for recon, then `architect` when a written plan is useful
-- **Current-state handoff**: use `recapper` to produce a self-contained handoff of the current state before another session or agent picks work up
+- **Advisory review**: use fresh-context `reviewer` agents for adversarial code review, or fork to `oracle` when inherited decisions and drift matter
+- **Implementation handoff**: have `oracle` advise, then `worker` implement only after an approved direction
+- **Recon and planning**: use `scout`, then write a plan when needed
 - **Parallel exploration**: run multiple non-conflicting tasks concurrently
 - **Regular skill specialists**: when discovery shows proactive skill subagent suggestions and the current work is broad enough, launch a small fresh-context fanout that asks one subagent per relevant regularly used skill to apply that skill's perspective to the task
 - **Long-running work**: launch async/background runs and inspect them later. For mutation-capable work, bound the delivery slice and elapsed runtime, then request checkpoints after active tool work returns. Reserve hard turn and tool-call caps for explicitly read-only children.
 - **Subagent control**: watch needs-attention signals and soft-interrupt only when a delegated run is genuinely blocked
-- **Agent authoring**: create, update, or override agents and chains for a project
+- **Agent authoring**: create, update, or override project agents. Treat saved chain records as legacy inspection or migration inputs, not as a current authoring target.
 
 ## Tool vs Slash Commands
 
-Agents use the `subagent(...)` tool directly for execution, management, status, and control. The tool has four first-class execution modes — `SINGLE` (`{ agent, task }`), `CHAIN` (`{ chain: [...] }`), `PARALLEL` (`{ tasks: [...] }`), and `SCRIPTED WORKFLOW` (`{ workflowScript }`) — plus `action` for management. Humans often use the slash-command layer instead:
+Agents use the `subagent(...)` tool with `workflowScript` for execution, and `action` for management, status, and control. Humans often use the slash-command layer instead:
 
 - `/run` — launch a single agent
-- `/chain` — launch a chain of steps: `/chain <agent> <task> | <agent> <task> [--bg] [--fork] [--fresh]`
-- `/parallel` — launch top-level parallel tasks: `/parallel <agent> <task> | <agent> <task> [--bg]`
-- `/run-chain` — run a saved `.chain.md` / `.chain.json` workflow: `/run-chain <name> [--bg]`; `/run-chain list` lists saved chains
+- `workflowScript` — the sole public surface for sequence, parallelism, branching, retries, and aggregation
 - `/subagents` — interactive admin for inspecting agents and editing model, thinking, or system prompt
 - `/subagents-stop [run-id]` — stop a current-session top-level async run; opens a selector when no id is given
 - `/subagents-detach [run-id]` — detach an active foreground single-subagent run without terminating its child
 - `/subagent-cost` — show parent plus child token usage and cost for the session
-- `subagent({ action: "status" })` — open the live run status view with per-child controls; `Ctrl+Alt+F` opens it during an active foreground turn, `↑↓`/`jk` selects children, `PgUp`/`PgDn` scrolls transcript detail, `s` steers the selected live async child, and `D` stops its top-level async run after confirmation
-- `/subagents-watchdog` — inspect the opt-in adversarial change watchdog (status, on/off, check)
+- `/subagents-fleet` — open the live fleet inspector with per-child controls; `Ctrl+Alt+F` opens it during an active foreground turn, `↑↓`/`jk` selects children, `PgUp`/`PgDn` scrolls transcript detail, `s` steers the selected live async child, and `D` stops its top-level async run after confirmation
+- `/subagents-watchdog` — inspect or configure the opt-in adversarial change watchdog (model, on/off, recommend-model, check)
 - `/subagents-doctor` — diagnose setup, discovery, async paths, and intercom bridge state
 - `/subagents-models [agent]` — show the live runtime-loaded builtin model mapping
 - `/subagents-profiles`, `/subagents-load-profile`, `/subagents-refresh-provider-models`, `/subagents-generate-profiles`, `/subagents-check-profile` — manage model profiles and provider catalogs
 - `/prompt-workflow` — run a prompt template through native workflowScript execution
-- `/chain-prompts` — run a prompt template whose frontmatter declares a chain, as a native chain
 
 Prefer the tool when you are writing agent logic. Prefer the slash commands when
 you are guiding a human through an interactive flow.
 
-Sending a message that contains `#agent-name` (anywhere in the text) invokes that
-agent inline — `#commentator review the current diff` — with autocomplete offered
-as you type. A `#mention` that does not resolve only consumes the input when it is
-an explicit invocation at the start of the message; mid-message mentions such as
-"issue #42" never swallow the user's text.
-
 Packaged prompt shortcuts are also available for repeatable workflows. Treat them as reusable orchestration recipes, not just human slash commands. When the user asks for one of these shapes, or when the workflow clearly fits, apply the same pattern directly with `subagent(...)` and other tools:
-- `/parallel-review` — fresh-context reviewers (or commentators) with distinct review angles, then synthesis
-- `/review-loop` — parent-orchestrated worker (or builder), fresh-reviewer, and fix-worker cycles until clean or capped
-- `/parallel-research` — combine `researcher` and `scout` (or `explorer`) for external evidence plus local code context
-- `/parallel-context-build` — parallel `explorer` passes that produce planning handoff context and meta-prompts
-- `/parallel-handoff-plan` — external-reference research plus local `explorer` passes, followed by a synthesis handoff plan and implementation-ready meta-prompt
-- `/gather-context-and-clarify` — scout/explorer/research first, then ask the user clarifying questions with `interview`
+- `/parallel-review` — fresh-context reviewers with distinct review angles, then synthesis
+- `/review-loop` — parent-orchestrated worker, fresh-reviewer, and fix-worker cycles until clean or capped
+- `/parallel-research` — combine `researcher` and `scout` for external evidence plus local code context
+- `/gather-context-and-clarify` — scout/research first, then ask the user clarifying questions with `interview`
 - `/parallel-cleanup` — two fresh-context reviewers (deslop + verbosity passes) for an adversarial cleanup review of the current diff
+- `/council` — bounded advisor council for material decisions, plan critique, cross-exam, and parent-written decision memos
 
 ## Applying Prompt Techniques Without Slash Commands
 
 The prompt templates in `prompts/` encode workflows the parent agent can run on demand. If the user provides a URL, issue, PR, plan, local file, screenshot, or freeform target, treat that target as the primary scope: read or fetch it before launching children, then include it explicitly in every child task. For targets outside the parent cwd, include the exact repository, explicit `cwd`, authority boundary, and expected output path in each child task. Do not depend on the parent conversation history when the recipe calls for fresh context.
 
+### Council Mode technique
+
+Use Council Mode when the user asks to convene advisors, debate a material decision, cross-examine recommendations, or critique and improve a plan with several model perspectives. This includes requests such as “run a council on this architecture,” “have Sol, Fable, and Kimi critique this plan,” or “get multiple oracles to debate the tradeoffs.” Read `../council-mode/SKILL.md` and follow its bounded parent-supervised protocol instead of launching ad hoc parallel oracle calls.
+
+Council advisors are read-only. User or project `council-*` profiles can pin models such as GPT 5.6 Sol, Fable, or Kimi and define any persistent stance in the profile body. Package advisors such as Surf's `gpt-pro` can join the roster only when the `surf-cli` Pi extension is installed and its `surf-oracle` provider is registered; treat them as external runners, omit child `async` for attached results, and do not pass `outputSchema` to them. The council question and scope provide the decision frame; do not invent per-advisor role labels. The parent collects independent reports, optionally sends curated cross-exam packets, and writes the final memo. Do not treat the council as agent-to-agent chat, implementation authority, or a writer swarm.
+
 ### Parallel review technique
 
-Use this when the user wants adversarial review of a diff, plan, issue, file, or implemented work. Launch fresh-context `reviewer` (or `commentator`) agents with distinct angles generated from the actual target. Common angles are correctness/regressions, tests/validation, and simplicity/maintainability; adapt for TypeScript, UI, security, docs, or large structural changes. Reviewers should inspect files and diffs directly, return concise evidence-backed findings with file/line references, and avoid edits unless the user explicitly asks for a writer pass. The parent synthesizes fixes worth doing now, optional improvements, and feedback to ignore/defer before applying anything.
+Use this when the user wants adversarial review of a diff, plan, issue, file, or implemented work. Launch fresh-context `reviewer` agents with distinct angles generated from the actual target. Common angles are correctness/regressions, tests/validation, and simplicity/maintainability; adapt for TypeScript, UI, security, docs, or large structural changes. Reviewers should inspect files and diffs directly, return concise evidence-backed findings with file/line references, and avoid edits unless the user explicitly asks for a writer pass. Filter on evidence, not severity: report only concrete current issues caused or made reachable by the target diff, with source proof, a test or repro, or a contract contradiction. Label findings P0/P1/P2 and end with `Merge verdict: BLOCK`, `Merge verdict: OK`, or `Merge verdict: OK with notes`. Use `blockers only` only for final pre-merge re-checks after P1/P2 findings are already captured, or for explicit emergency hotfix lanes where non-blocking findings are intentionally deferred. For targeted follow-up, ask only whether the named finding was resolved, whether the fix introduced a new defect in the fix blast radius, and whether prior P1/P2 notes still stand. For bot or PR-comment triage, classify each comment as VALID, STALE, INVALID, or OUT-OF-POLICY against current HEAD, then assign P0/P1/P2 only to VALID comments. The parent synthesizes fixes worth doing now, optional improvements, and feedback to ignore/defer before applying anything.
 
 ### Proactive skill-specialist technique
 
@@ -93,58 +88,19 @@ subagent({
 
 ### Review-loop technique
 
-Use this when the user wants implementation or current diff review to continue until reviewers stop finding fixes worth doing now. Keep the loop in the parent session: one async `worker` (or `builder`) implements or fixes, fresh-context `reviewer` agents inspect the actual repo and diff, the parent synthesizes accepted fixes, and one async forked `worker` applies them. The parent can express the sequence up front as an async/background `workflowScript` or as a chain when the workflow is known, or continue with explicit follow-up subagent runs after each async completion. For an initial workflow, pass `async: true` so the main chat is unblocked. Treat an async implementation worker handoff as an intermediate state, not final completion, unless the user explicitly asked for worker-only work, review-only output, or to stop after implementation. Stop when reviewers find no blockers or fixes worth doing now, remaining feedback is optional or deferred, an unapproved product/scope/architecture decision appears, or the max review-round cap is reached. Default to 3 review rounds unless the user sets a different cap. Do not loop for optional polish, and do not let children launch subagents or decide the loop outcome.
+Use this when the user wants implementation or current diff review to continue until reviewers stop finding fixes worth doing now. Keep the loop in the parent session: one async `worker` implements or fixes, fresh-context `reviewer` agents inspect the actual repo and diff, the parent synthesizes accepted fixes, and one async forked `worker` applies them. The parent can express the sequence up front as an async/background `workflowScript` when the workflow is known, or continue with explicit follow-up workflowScript runs after each async completion. For an initial workflow, pass `async: true` so the main chat is unblocked. Treat an async implementation worker handoff as an intermediate state, not final completion, unless the user explicitly asked for worker-only work, review-only output, or to stop after implementation. Stop when reviewers find no P0 blockers or P1 fixes worth doing now, remaining P2 feedback is optional or deferred, an unapproved product/scope/architecture decision appears, or the max review-round cap is reached. Default to 3 review rounds unless the user sets a different cap. Do not loop for optional polish, and do not let children launch subagents or decide the loop outcome.
 
 As a conservative orchestration policy, do not pass `turnBudget` or a hard `toolBudget` to an implementation worker, fix worker, reviewer with edit authority, or other mutation-capable child. The default tool budget blocks read/search tools rather than mutation tools, but count limits still do not measure delivery safety. Use a narrow task plus an outer elapsed deadline with enough margin, then request a checkpoint after the current tool returns. The checkpoint should report 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 used as the checkpoint trigger.
 
 ### Parallel research technique
 
-Use this when the question needs both external evidence and local implications. Combine `researcher` for official docs, specs, ecosystem behavior, recent changes, benchmarks, and primary sources with `scout` (or `explorer`) for repository files, patterns, constraints, tests, and likely integration points. Give each child a distinct angle: external evidence, local code context, and practical tradeoffs. Ask for source links or file ranges, confidence level, gaps, and decision implications. Do not ask these children to edit unless implementation was explicitly requested.
-
-
-
-### Parallel context-build technique
-
-Use this before planning or implementation when a stronger handoff is needed. Run a chain with one parallel step of `explorer` agents rather than top-level parallel tasks, so relative output files live under the temporary chain directory. Give every task a distinct output path such as `context-build/request-and-scope.md`, `context-build/codebase-and-patterns.md`, and `context-build/validation-and-risks.md`. Choose two or three builders: request/scope, codebase/patterns, and validation/risks. Each builder must read every relevant file needed to understand its slice, follow imports/callers/tests/docs/config, conduct tool-available web research when needed, and include a compact `meta-prompt` section. The parent synthesizes the outputs into important context, recommended next meta-prompt, open questions, assumptions, and artifact paths.
-
-Example shape:
-
-```typescript
-subagent({
-  chain: [{
-    parallel: [
-      { agent: "explorer", task: "Build request/scope context for: ...", output: "context-build/request-and-scope.md" },
-      { agent: "explorer", task: "Build codebase/pattern context for: ...", output: "context-build/codebase-and-patterns.md" },
-      { agent: "explorer", task: "Build validation/risk context for: ...", output: "context-build/validation-and-risks.md" }
-    ]
-  }],
-  context: "fresh"
-})
-```
-
-### Parallel handoff-plan technique
+Use this when the question needs both external evidence and local implications. Combine `researcher` for official docs, specs, ecosystem behavior, recent changes, benchmarks, and primary sources with `scout` for repository files, patterns, constraints, tests, and likely integration points. Give each child a distinct angle: external evidence, local code context, and practical tradeoffs. Ask for source links or file ranges, confidence level, gaps, and decision implications. Do not ask these children to edit unless implementation was explicitly requested.
 
-Use this when the user needs a solution brief or implementation-ready handoff from an external reference plus local code context, such as "study this library behavior, inspect our codebase, then produce a builder prompt." Run a chain with a first parallel group and a second synthesis `explorer` step. The first group usually includes `researcher` for external projects/docs/prompt guidance and `explorer` for local code context; add a second `explorer` for implementation strategy only when the scope is large enough to benefit. Use distinct output paths under `handoff/`, then have the synthesis `explorer` read those outputs and write `handoff/final-handoff-plan.md` with the recommended approach, likely files, constraints, non-goals, validation, risks, unresolved questions, and final compact implementation-ready meta-prompt.
 
-Example shape:
-
-```typescript
-subagent({
-  chain: [
-    { parallel: [
-      { agent: "researcher", task: "Research the external reference and transferable implementation ideas for: ...", output: "handoff/external-reference.md" },
-      { agent: "explorer", task: "Build local codebase context for: ...", output: "handoff/local-context.md" },
-      { agent: "explorer", task: "Compare evidence and propose implementation strategy for: ...", output: "handoff/implementation-strategy.md" }
-    ] },
-    { agent: "explorer", task: "Read {previous} and synthesize the final handoff plan and implementation-ready meta-prompt.", output: "handoff/final-handoff-plan.md" }
-  ],
-  context: "fresh"
-})
-```
 
 ### Gather-context-and-clarify technique
 
-Use this at the start of non-trivial work. Launch `scout` (or `explorer`) for local context and `researcher` only when external docs, recent sources, ecosystem context, or primary evidence would materially improve understanding. Ask children for concise findings plus remaining clarification questions. Then synthesize what is known and use `interview` to ask the unresolved questions needed for shared understanding before planning or implementing.
+Use this at the start of non-trivial work. Launch `scout` for local context and `researcher` only when external docs, recent sources, ecosystem context, or primary evidence would materially improve understanding. Ask children for concise findings plus remaining clarification questions. Then synthesize what is known and use `interview` to ask the unresolved questions needed for shared understanding before planning or implementing.
 
 ### Parallel cleanup technique
 
@@ -178,20 +134,20 @@ subagent({
 
     // Stage 2: single writer — the only child allowed to edit the active worktree.
     // Under outputMode "file-only" the awaited .output is the saved-output
-    // reference, so pass the durable paths declared above to the writer.
+    // reference, so pass those managed artifact references to the writer.
     const worker = await runs.run("apply-fixes", {
       agent: "worker",
       phase: "Implementation",
       label: "Apply accepted fixes",
-      task: "Apply only the accepted fixes from these planning summaries. You are the sole writer for the active worktree. Run focused validation and report changed files, commands, failures, and remaining issues.\\n\\nDeploy plan: plans/deploy.md\\n\\nScheduler plan: plans/scheduler.md\\n\\nSandbox plan: plans/sandbox.md",
+      task: "Apply only the accepted fixes from these planning summaries. You are the sole writer for the active worktree. Run focused validation and report changed files, commands, failures, and remaining issues.\\n\\nDeploy plan: " + plans[0].output + "\\n\\nScheduler plan: " + plans[1].output + "\\n\\nSandbox plan: " + plans[2].output,
       output: "worker/fixes.md",
       outputMode: "file-only"
     });
 
     // Stage 3: parallel read-only validation fanout
     const validations = await runs.all([
-      { key: "validate-deploy-scheduler", agent: "reviewer", phase: "Validation", label: "Deploy/scheduler validation", task: "Validate the post-worker diff for deploy and scheduler fixes. Start from the worker result: " + worker.output + " (also worker/fixes.md). Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "validation/deploy-scheduler.md", outputMode: "file-only" },
-      { key: "validate-sandbox", agent: "reviewer", phase: "Validation", label: "Sandbox validation", task: "Validate the post-worker diff for sandbox/security fixes. Start from the worker result: " + worker.output + " (also worker/fixes.md). Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "validation/sandbox.md", outputMode: "file-only" }
+      { key: "validate-deploy-scheduler", agent: "reviewer", phase: "Validation", label: "Deploy/scheduler validation", task: "Validate the post-worker diff for deploy and scheduler fixes. Start from the worker result: " + worker.output + ". Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "validation/deploy-scheduler.md", outputMode: "file-only" },
+      { key: "validate-sandbox", agent: "reviewer", phase: "Validation", label: "Sandbox validation", task: "Validate the post-worker diff for sandbox/security fixes. Start from the worker result: " + worker.output + ". Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "validation/sandbox.md", outputMode: "file-only" }
     ]);
 
     return { worker: worker.output, validations: validations.map(v => v.output) };
@@ -206,24 +162,17 @@ and user/project agents override builtins with the same name.
 
 | Agent | Purpose | Model | Typical output / role |
 |-------|---------|-------|------------------------|
-| `architect` | Creates implementation plans | inherits default | Read-only planning; returns the complete plan in its final response |
-| `advisor` | Claude Code-compatible alias for `oracle` | inherits default | Same advisory role as `oracle` |
-| `builder` | Selesai-native implementation agent | inherits default | Single-writer implementation with decision escalation (fresh context by default) |
-| `commentator` | Selesai-native review specialist | inherits default | Read-only evidence-backed findings in its final response |
-| `delegate` | Lightweight generic delegate | inherits default | No fixed output; generic delegated work |
-| `explorer` | Selesai-native fast codebase recon | inherits default | Read-only recon findings in its final response |
-| `oracle` | Decision-consistency advisory review | inherits default | Advisory review, intercom coordination |
-| `recapper` | Current-state handoff specialist | inherits default | Fork-context handoff; returns a self-contained handoff in its final response |
-| `researcher` | Sourced research brief generator | inherits default | Read-only brief in its final response (host `grep_app_search` / `grep_app_fetch` / `web_explore` tools) |
-| `reviewer` | Review specialist | inherits default | Default recipes are review-only; tools include edit/write when a fix pass is explicit |
 | `scout` | Fast codebase recon | inherits default | Writes `context.md` handoff material |
 | `worker` | Implementation and approved oracle handoffs | inherits default | Single-writer implementation with decision escalation |
+| `reviewer` | Review specialist | inherits default | Default recipes are review-only; tools include edit/write when a fix pass is explicit |
+| `researcher` | Web research brief generator | inherits default | Writes `research.md` |
+| `delegate` | Lightweight generic delegate | inherits default | No fixed output; generic delegated work |
+| `oracle` | Decision-consistency advisory review | inherits default | Advisory review, intercom coordination |
+| `advisor` | Claude Code-compatible alias for `oracle` | inherits default | Same advisory role as `oracle` |
 
-Selesai-native equivalents: `explorer` ≈ `scout`, `builder` ≈ `worker`, `commentator` ≈ `reviewer`, `architect` ≈ a read-only planner, `recapper` ≈ a current-state handoff. The upstream roster (`scout`, `worker`, `reviewer`, `researcher`, `delegate`, `oracle`) remains fully supported; pick either family per task. Only `architect` and `recapper` resolve to forked context when a launch omits `context`; `builder`, `commentator`, `explorer`, and `researcher` default to fresh context.
-
-Builtin `worker`, `builder`, and `delegate` use strict tool allowlists and do not inherit ambient parent extension tools. To give a child an extension tool, name it in `tools` and load its provider via `extensions`, a path-like `tools` entry, or `subagentOnlyExtensions`. Custom agents without an `extensions` field follow `subagents.defaultExtensions` when set.
+Builtin `worker` and `delegate` use strict tool allowlists and do not inherit ambient parent extension tools. To give a child an extension tool, name it in `tools` and load its provider via `extensions`, a path-like `tools` entry, or `subagentOnlyExtensions`. Custom agents without an `extensions` field follow `subagents.defaultExtensions` when set.
 
-Builtin agents inherit the current Selesai default model unless a run, user setting, project setting, or `subagents.defaultModel` overrides `model`. Set `subagents.defaultModel` when subagents should use a different default model than the parent session. Override builtin defaults before copying full agent files when a small tweak is enough.
+Builtin agents inherit the current Pi default model unless a run, user setting, project setting, or `subagents.defaultModel` overrides `model`. Set `subagents.defaultModel` when subagents should use a different default model than the parent session. Override builtin defaults before copying full agent files when a small tweak is enough.
 
 Set `subagents.defaultThinking` to apply a shared thinking level to builtin, package, user, and project agents whose frontmatter leaves `thinking` unset. Project settings win over user settings; explicit frontmatter (including `thinking: false`), `agentOverrides.<name>.thinking`, and per-run overrides remain more specific. This setting affects child agents only and does not change the parent session's default thinking level.
 
@@ -249,7 +198,7 @@ For model fleets, use the profile commands instead of hand-editing repeated over
 
 ## Prompting role subagents
 
-Builtin role agents inherit the current Selesai default model unless you override them. When launching them, write the task prompt as a compact contract, not a long procedural script. Define the destination and let the role choose the efficient path.
+Builtin role agents inherit the current Pi default model unless you override them. When launching them, write the task prompt as a compact contract, not a long procedural script. Define the destination and let the role choose the efficient path.
 
 A strong subagent prompt usually includes:
 - **Goal**: the concrete outcome the child should produce.
@@ -259,16 +208,18 @@ A strong subagent prompt usually includes:
 - **Success criteria**: what must be true before the child can finish.
 - **Hard constraints**: true invariants only, such as no edits for review-only tasks, one writer thread, child must not run subagents unless it is an explicitly assigned `tools: subagent` fanout child, or escalation for unapproved decisions.
 - **Validation**: targeted checks to run, or the next-best check when validation is impossible.
-- **Output**: the expected summary shape, artifact path, or finding format. Use repo-qualified durable output paths for cross-codebase waves.
+- **Output**: the expected summary shape, artifact path, or finding format. Use managed artifact paths for scratch reports; reserve repo-qualified absolute paths for durable handoffs that the user approved.
 - **Stop rules**: when to ask via `intercom` or `contact_supervisor`, when to stop after enough evidence, and when not to keep searching.
 
+Give each role useful discovery anchors. Name source roots, filenames, symbols, types, methods, and paths for scouts. Give workers context files, plans, task paths, and named source seams before asking them to search. Give reviewers changed files, contracts, and any exhaustive-verification target. Tell oracle whether current source behavior, product/policy documents, plans, or inherited decisions are the evidence that matters.
+
 Avoid carrying over old prompt habits that over-specify every step. Use `must`, `always`, and `never` for real invariants; for judgment calls, give decision rules. For example, tell a reviewer to inspect the staged diff directly and report only evidence-backed findings, rather than prescribing every file or command. Tell a researcher the retrieval budget: start with broad targeted searches, fetch only the strongest sources, search again only when a required fact is missing, then stop.
 
 For implementation handoffs, name the approved scope and success criteria more clearly than the process. Good prompts say what to change, what not to change, where the evidence lives, how to validate, and when to escalate. They should not ask the child to create another subagent plan or continue the parent conversation.
 
 Settings locations:
 - User scope: `~/.selesai/agent/settings.json`
-- Project scope: `.selesai/settings.json`
+- Project scope: `.pi/settings.json`
 
 Direct settings example:
 
@@ -299,9 +250,9 @@ agent with the same name only when you want a substantially different agent.
 
 When several providers are available, route agents by task shape instead of one model for everything:
 
-1. **Fast workhorse** — cheapest capable model at low thinking for recon, lookups, and mechanical edits (for example on `scout` / `explorer`).
-2. **Standard well-scoped** — mid-tier model at medium thinking for most delegations: routine multi-file edits, focused reviews, straightforward implementation (for example on `worker`, `builder`, `reviewer`, `commentator`, `delegate`).
-3. **Deep but bounded** — top reasoning model at high thinking only for hard tasks that arrive with explicit goals and completion criteria; these models loop on vague goals (for example on `oracle`, `architect`, and reviewer-style agents).
+1. **Fast workhorse** — cheapest capable model at low thinking for recon, lookups, and mechanical edits (for example on `scout`).
+2. **Standard well-scoped** — mid-tier model at medium thinking for most delegations: routine multi-file edits, focused reviews, straightforward implementation (for example on `worker`, `reviewer`, `delegate`).
+3. **Deep but bounded** — top reasoning model at high thinking only for hard tasks that arrive with explicit goals and completion criteria; these models loop on vague goals (for example on oracle-style agents).
 4. **Taste and intent** — a model that reads human intent well for ambiguous work: UX/design judgment, product tradeoffs, planning from vague requirements, writing quality.
 
 Routing rule: use tiers 1–3 when the task is well-scoped; use tier 4 when scoping or judging is the task itself. Give tier-4 agents cross-provider `fallbackModels` so subscription usage limits degrade gracefully; fallback triggers automatically on rate-limit and overload errors. Note that forked context over an Anthropic parent transcript with signed thinking blocks forces the child's thinking off, so intent-tier agents work best with fresh context.
@@ -313,4 +264,4 @@ override can opt one builtin back in. Existing custom-agent frontmatter remains
 
 Set `subagents.defaultExtensions` to give agents without an `extensions` field a shared child extension allowlist. Omit it to preserve ambient extension discovery, set it to `[]` to disable ambient extensions by default, or use `agentOverrides.<name>.extensions` for one agent. Explicit custom-agent frontmatter still wins.
 
-Tool description modes live in `~/.selesai/agent/extensions/subagent/config.json`, not `subagents` settings. Set `toolDescriptionMode` to `compact` to reduce tool-description prompt cost while keeping the execution, async/`subagent_wait`, child-safety, one-writer, management/action, and artifact/status guardrails. Set it to `custom` to read `subagent-tool-description.md` from the project config dir or agent dir; invalid custom files fall back to compact mode and the safety guidance is still appended.
+Tool description modes live in `~/.selesai/agent/extensions/subagent/config.json`, not `subagents` settings. The default uses split prompt metadata: a short tool description plus active `promptSnippet` and `promptGuidelines`. Set `toolDescriptionMode` to `full` or `compact` to force one description string, or `custom` to read `subagent-tool-description.md` from the project config dir or agent dir; invalid custom files fall back to full mode and the safety guidance is still appended.

package/dist/skills/planger/SKILL.md

@@ -1,166 +1,166 @@
----
-name: planger
-description: Create decomposed planning for sub agent
-argument-hint: "How i provide a good plan for subagent"
-disable-model-invocation: true
----
-
-# Planning Skill
-
-## Goal
-
-Create implementation plans that can be executed by a small coding model with:
-
-- Limited context window
-- No project knowledge
-- No memory of previous conversation
-- Weak architectural understanding
-- No ability to infer missing steps
-
-Assume the executor only knows what is written in the plan.
-
-# Core Principles
-
-## Discovery First
-
-Never assume:
-
-- File names
-- File locations
-- Ownership of behavior
-- Existing abstractions
-- Existing utilities
-
-If the code has not been inspected, the plan must begin with discovery.
-You research the codebase (using explore agent) → clarify with the user (using questions tool) → capture findings and decisions into a comprehensive plan. This iterative approach catches edge cases and non-obvious requirements BEFORE implementation begins.
-
-## Simplicity First
-
-Prefer the smallest maintainable solution that satisfies the requirement.
-
-Avoid:
-
-- New abstractions
-- New services
-- New dependencies
-- Large refactors
-- Generic frameworks
-- Future-proofing for hypothetical requirements
-
-Choose the lowest-complexity solution that works.
-
-## Reuse Before Build
-
-Before creating anything new (use explorer agent):
-
-- Search for existing implementations
-- Search for existing utilities
-- Search for existing patterns
-- Search for existing tests
-
-Reuse existing code when reasonable.
-
-Do not duplicate behavior unless duplication is clearly preferable.
-
-## Scope Discipline
-
-Only modify code required for the task.
-
-Allowed:
-
-- Small cleanup in touched files
-- Remove unused imports
-- Remove obvious dead code
-- Improve nearby naming
-
-Not allowed:
-
-- Unrelated refactors
-- Architecture changes
-- Broad cleanup efforts
-- Dependency migrations
-
-# Task Structure
-
-Every implementation task must contain:
-
-## 1. Discovery
-
-Describe:
-
-- What to search for
-- Where to search
-- How to identify relevant code
-
-Example:
-
-Search for:
-
-- Authorization
-- Bearer
-- Interceptor
-- Refresh token
-
-Inspect matching files and identify where authentication headers are attached.
-
-## 2. Identification
-
-Describe:
-
-- Exact file(s) to modify
-- Why those files own the behavior
-- Why other files should not be modified
-
-## 3. Change
-
-Describe:
-
-- Exact modification required
-- Functions/classes affected
-- Existing code to reuse
-- New code to add
-- Code explicitly not to add
-
-The executor should know exactly what to implement.
-
-## 4. Verification
-
-Include:
-
-### Success Cases
-
-Expected working behavior.
-
-### Failure Cases
-
-Expected error behavior.
-
-### Regression Checks
-
-Existing behavior that must remain unchanged.
-
-# Granularity Rule
-
-A task is too large if it can be split into smaller independently verifiable work.
-
-Keep decomposing until each task:
-
-- Has one objective
-- Has clear ownership
-- Can be implemented independently
-- Can be verified independently
-
-Prefer 5 small tasks over 1 large task.
-
-# Final Review
-
-Before returning a plan verify:
-
-- Discovery exists
-- Ownership is justified
-- Solution is the simplest acceptable approach
-- Existing code is reused when possible
-- No unnecessary abstractions are introduced
-- Scope remains limited
-- Verification is included
-- Every step is executable without additional assumptions
+---
+name: planger
+description: Create decomposed planning for sub agent
+argument-hint: "How i provide a good plan for subagent"
+disable-model-invocation: true
+---
+
+# Planning Skill
+
+## Goal
+
+Create implementation plans that can be executed by a small coding model with:
+
+- Limited context window
+- No project knowledge
+- No memory of previous conversation
+- Weak architectural understanding
+- No ability to infer missing steps
+
+Assume the executor only knows what is written in the plan.
+
+# Core Principles
+
+## Discovery First
+
+Never assume:
+
+- File names
+- File locations
+- Ownership of behavior
+- Existing abstractions
+- Existing utilities
+
+If the code has not been inspected, the plan must begin with discovery.
+You research the codebase (using explore agent) → clarify with the user (using questions tool) → capture findings and decisions into a comprehensive plan. This iterative approach catches edge cases and non-obvious requirements BEFORE implementation begins.
+
+## Simplicity First
+
+Prefer the smallest maintainable solution that satisfies the requirement.
+
+Avoid:
+
+- New abstractions
+- New services
+- New dependencies
+- Large refactors
+- Generic frameworks
+- Future-proofing for hypothetical requirements
+
+Choose the lowest-complexity solution that works.
+
+## Reuse Before Build
+
+Before creating anything new (use explorer agent):
+
+- Search for existing implementations
+- Search for existing utilities
+- Search for existing patterns
+- Search for existing tests
+
+Reuse existing code when reasonable.
+
+Do not duplicate behavior unless duplication is clearly preferable.
+
+## Scope Discipline
+
+Only modify code required for the task.
+
+Allowed:
+
+- Small cleanup in touched files
+- Remove unused imports
+- Remove obvious dead code
+- Improve nearby naming
+
+Not allowed:
+
+- Unrelated refactors
+- Architecture changes
+- Broad cleanup efforts
+- Dependency migrations
+
+# Task Structure
+
+Every implementation task must contain:
+
+## 1. Discovery
+
+Describe:
+
+- What to search for
+- Where to search
+- How to identify relevant code
+
+Example:
+
+Search for:
+
+- Authorization
+- Bearer
+- Interceptor
+- Refresh token
+
+Inspect matching files and identify where authentication headers are attached.
+
+## 2. Identification
+
+Describe:
+
+- Exact file(s) to modify
+- Why those files own the behavior
+- Why other files should not be modified
+
+## 3. Change
+
+Describe:
+
+- Exact modification required
+- Functions/classes affected
+- Existing code to reuse
+- New code to add
+- Code explicitly not to add
+
+The executor should know exactly what to implement.
+
+## 4. Verification
+
+Include:
+
+### Success Cases
+
+Expected working behavior.
+
+### Failure Cases
+
+Expected error behavior.
+
+### Regression Checks
+
+Existing behavior that must remain unchanged.
+
+# Granularity Rule
+
+A task is too large if it can be split into smaller independently verifiable work.
+
+Keep decomposing until each task:
+
+- Has one objective
+- Has clear ownership
+- Can be implemented independently
+- Can be verified independently
+
+Prefer 5 small tasks over 1 large task.
+
+# Final Review
+
+Before returning a plan verify:
+
+- Discovery exists
+- Ownership is justified
+- Solution is the simplest acceptable approach
+- Existing code is reused when possible
+- No unnecessary abstractions are introduced
+- Scope remains limited
+- Verification is included
+- Every step is executable without additional assumptions