@selesai/code 0.8.3 → 0.8.4

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

@@ -9,9 +9,10 @@ Parent extensions may register a session-scoped, out-of-band ceiling through `pi
 ## 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 `commentator` agents for adversarial code review, or fork to `commentator` when inherited decisions and drift matter
-- **Implementation handoff**: have `commentator` advise, then `builder` implement only after an approved direction
-- **Recon and planning**: use `explorer`, then `architect`
+- **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
 - **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.
@@ -20,13 +21,12 @@ Parent extensions may register a session-scoped, out-of-band ceiling through `pi
 
 ## Tool vs Slash Commands
 
-Agents can use the `subagent(...)` tool directly for execution, management, status, and control.
-Humans often use the slash-command layer instead:
+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:
 
 - `/run` — launch a single agent
-- `/chain` — launch a chain of steps
-- `/parallel` — launch top-level parallel tasks
-- `/run-chain` — launch a saved `.chain.md` or `.chain.json` workflow
+- `/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
 - `/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
@@ -36,27 +36,34 @@ Humans often use the slash-command layer instead:
 - `/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` and `/chain-prompts` — run prompt templates through native subagent single/chain workflows
+- `/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 commentators with distinct review angles, then synthesis
-- `/review-loop` — parent-orchestrated builder, fresh-commentator, and fix-builder cycles until clean or capped
-- `/parallel-research` — combine `researcher` and `explorer` for external evidence plus local code context
+- `/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` — explorer/research first, then ask the user clarifying questions with `interview`
-- `/parallel-cleanup` — two fresh-context commentators (deslop + verbosity passes) for an adversarial cleanup review of the current diff
+- `/gather-context-and-clarify` — scout/explorer/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
 
 ## 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. Do not depend on the parent conversation history when the recipe calls for fresh context.
+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.
 
 ### Parallel review technique
 
-Use this when the user wants adversarial review of a diff, plan, issue, file, or implemented work. Launch fresh-context `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. commentators 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` (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.
 
 ### Proactive skill-specialist technique
 
@@ -84,13 +91,13 @@ subagent({
 
 ### Review-loop technique
 
-Use this when the user wants implementation or current diff review to continue until commentators stop finding fixes worth doing now. Keep the loop in the parent session: one async `builder` implements or fixes, fresh-context `commentator` agents inspect the actual repo and diff, the parent synthesizes accepted fixes, and one async forked `builder` applies them. The parent can express the sequence up front as an async/background chain when the workflow is known, or continue with explicit follow-up subagent runs after each async completion. For an initial chain, pass `async: true` so the main chat is unblocked; do not set `clarify: true` unless the user explicitly wants the foreground clarify UI. Treat an async implementation builder handoff as an intermediate state, not final completion, unless the user explicitly asked for builder-only work, review-only output, or to stop after implementation. Stop when commentators 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` (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.
 
-As a conservative orchestration policy, do not pass `turnBudget` or a hard `toolBudget` to an implementation builder, fix builder, commentator 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.
+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 `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.
+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
 
@@ -113,7 +120,7 @@ subagent({
 
 ### Parallel handoff-plan technique
 
-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.
+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:
 
@@ -133,21 +140,21 @@ subagent({
 
 ### Gather-context-and-clarify technique
 
-Use this at the start of non-trivial work. Launch `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` (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.
 
 ### Parallel cleanup technique
 
-Use this after implementation when the user wants cleanup review or when a final pass would reduce AI-slop. Launch two fresh-context `commentator` tasks with `output: false` and `progress: false`: one deslop pass and one verbosity pass. If the `deslop` or `verbosity-cleaner` skills are available, pass the relevant skill to that commentator; otherwise inline the criteria. Both commentators are review-only and should flag concrete issues with severity, file/line references, and smallest safe fixes. Phrase the constraint as “Do not modify project/source files; returning findings through the configured output artifact is allowed” when you use `output` or `outputMode: "file-only"`. The parent decides what to apply and asks before making changes unless cleanup was already authorized.
+Use this after implementation when the user wants cleanup review or when a final pass would reduce AI-slop. Launch two fresh-context `reviewer` (or `commentator`) tasks with `output: false` and `progress: false`: one deslop pass and one verbosity pass. If the `deslop` or `verbosity-cleaner` skills are available, pass the relevant skill to that reviewer; otherwise inline the criteria. Both reviewers are review-only and should flag concrete issues with severity, file/line references, and smallest safe fixes. Phrase the constraint as "Do not modify project/source files; returning findings through the configured output artifact is allowed" when you use `output` or `outputMode: "file-only"`. The parent decides what to apply and asks before making changes unless cleanup was already authorized.
 
 ### Staged fix orchestration technique
 
-Use this when a broad diff has known commentator findings across several items and the user wants the parent to “orchestrate subagents like a boss.” Keep the active worktree safe with a three-stage chain:
+Use this when a broad diff has known reviewer findings across several items and the user wants the parent to "orchestrate subagents like a boss." Keep the active worktree safe with a three-stage chain:
 
-1. A parallel read-only planning fanout, one architect/commentator per issue cluster. Each child inspects the real diff and returns exact files, line refs, proposed fixes, and focused validation. They must not edit.
-2. One writer builder. It receives the architect summaries through `{previous}`, the parent’s accepted scope, stop rules, and verification contract. It is the only child allowed to edit the active worktree.
-3. A parallel read-only validation fanout. Validators inspect the builder diff from fresh context with distinct angles, report pass/fail, remaining blockers, and missing verification.
+1. A parallel read-only planning fanout, one reviewer (or architect/commentator) per issue cluster. Each child inspects the real diff and returns exact files, line refs, proposed fixes, and focused validation. They must not edit.
+2. One writer worker (or builder). It receives the reviewer summaries through `{previous}`, the parent's accepted scope, stop rules, and verification contract. It is the only child allowed to edit the active worktree.
+3. A parallel read-only validation fanout. Validators inspect the worker diff from fresh context with distinct angles, report pass/fail, remaining blockers, and missing verification.
 
-Prefer `async: true`, `context: "fresh"` for architects/validators, `outputMode: "file-only"` for large summaries, and per-stage output names that will not collide. Add `phase` and `label` to make async status readable, and use `as` plus `{outputs.name}` when a later step needs a specific earlier result instead of the whole `{previous}` blob. Use this pattern instead of launching several writer builders into a dirty worktree. Include non-blocking suggestions in the writer prompt only when they are small, safe, and do not expand product scope; otherwise record them as deferred.
+Prefer `async: true`, `context: "fresh"` for reviewers/validators, `outputMode: "file-only"` for large summaries, and per-stage output names that will not collide. Add `phase` and `label` to make async status readable, and use `as` plus `{outputs.name}` when a later step needs a specific earlier result instead of the whole `{previous}` blob. Use this pattern instead of launching several writer workers into a dirty worktree. Include non-blocking suggestions in the writer prompt only when they are small, safe, and do not expand product scope; otherwise record them as deferred.
 
 When the first step can return a structured target list, prefer dynamic fanout instead of hand-authoring a static parallel group. Use `outputSchema` and `as` on the producer, then an `expand` step with `from: { output, path }`, an explicit `maxItems`, one `parallel` child template, and `collect.as`. Item templates may use `{item}` or a named item such as `{target.path}`. Do not use dynamic fanout for prose outputs, nested fanout, dynamic agent selection, reducers, `when` conditions, or arbitrary expressions; `.chain.md` does not support this syntax, so use direct JSON or a saved `.chain.json`.
 
@@ -180,17 +187,23 @@ 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 |
-| `builder` | Implementation and approved commentator handoffs | inherits default | Single-writer implementation with decision escalation |
-| `commentator` | Review specialist | inherits default | Review-only findings in its final response; no edit/write tools |
-| `explorer` | Fast codebase recon | inherits default | Read-only recon findings 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 |
+| `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 |
 
-Only `architect` and `recapper` resolve to forked context when a launch omits `context`; `builder`, `commentator`, `explorer`, and `researcher` default to fresh context. Read-only builtins return their output in the final response; output files are written only when the caller configures output persistence.
+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.
 
-Explicit `tools` is an allowlist, but ambient extension discovery remains possible unless `extensions`, `subagentOnlyExtensions`, or a capability ceiling constrains it; naming a tool alone does not load its provider. 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`, `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 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.
+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.
 
 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.
 
@@ -205,7 +218,7 @@ Set `subagents.defaultThinking` to apply a shared thinking level to builtin, pac
 For one run, use inline config:
 
 ```text
-/run commentator[model=anthropic/claude-sonnet-4] "Review this diff"
+/run reviewer[model=anthropic/claude-sonnet-4] "Review this diff"
 ```
 
 For persistent tweaks, edit `subagents.agentOverrides` in user or project settings. User overrides apply everywhere. Project overrides apply only in that repo and win over user overrides. Use `/subagents-models` or `subagent({ action: "models" })` to inspect the live mapping after settings and overrides load.
@@ -216,18 +229,20 @@ For model fleets, use the profile commands instead of hand-editing repeated over
 
 ## Prompting role subagents
 
-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.
+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.
 
 A strong subagent prompt usually includes:
 - **Goal**: the concrete outcome the child should produce.
+- **Target**: repository, explicit `cwd`, branch/ref/head, and source seam when the target is not the parent cwd.
+- **Authority boundary**: whether the child may read, edit, commit, push, comment, close, merge, publish, or release. Omit or forbid actions that are not approved.
 - **Context/evidence**: relevant plan paths, files, diffs, decisions, or user constraints already approved.
 - **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.
-- **Stop rules**: when to ask via `intercom`, when to stop after enough evidence, and when not to keep searching.
+- **Output**: the expected summary shape, artifact path, or finding format. Use repo-qualified durable output paths for cross-codebase waves.
+- **Stop rules**: when to ask via `intercom` or `contact_supervisor`, when to stop after enough evidence, and when not to keep searching.
 
-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 commentator 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.
+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.
 
@@ -241,7 +256,7 @@ Direct settings example:
 {
   "subagents": {
     "agentOverrides": {
-      "commentator": {
+      "reviewer": {
         "model": "anthropic/claude-sonnet-4",
         "thinking": "high",
         "fallbackModels": ["openai/gpt-5-mini"],
@@ -264,9 +279,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 `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 `builder` and `commentator`).
-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 `architect` and commentator-style agents).
+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).
 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.

package/docs/plans/workflow-autoloop-reference.md

@@ -0,0 +1,192 @@
+# Workflow auto-loop reference (implement exactly)
+
+> **Superseded:** the 3-round cap was later removed — the loop now runs until
+> clean. See `src/extensions/workflow/modes.ts` for the final implementation.
+
+Convert the four `/workflow-*` modes from static chains to pi-subagents
+`workflowScript` auto-loops. One-shot-and-sleep: the phases run as `runs.run`
+steps and the build↔review phase auto-repeats until the commentator reports
+clean or the cap (3) is hit. A `workflowScript` has no checkpoints, so there are
+no human gates — intentional.
+
+## Files
+
+- Rewrite `src/extensions/workflow/modes.ts` → `build*Script(goal)` builders.
+- Rewrite `src/extensions/workflow/extension.ts` → launch `workflowScript`.
+- Rewrite `src/__tests__/workflow-modes.test.ts` → test the builders.
+- Update docs: `doc-web/src/content/docs/capabilities/delegation/workflow.mdx`
+  (EN), `.../id/capabilities/delegation/workflow.mdx` (ID),
+  `.../pi-subagents.mdx`, `doc-web/src/data/capabilities.ts`,
+  `doc-web/src/data/extension-customization.json`.
+- Update skill `references/execution-controls.md` (3 copies, byte-identical):
+  `src/extensions/pi-subagents/skills/pi-subagents` ↔ `src/skills/pi-subagents`
+  ↔ `~/.selesai/agent/skills`.
+
+## Correctness rules (must hold)
+
+1. Every script template uses `String.raw` so `\n` and the regex `\s` stay
+   literal in the generated JS.
+2. The goal is injected with `JSON.stringify(goal)` (safe JS string literal).
+3. `runs.run` keys are UNIQUE per round (`build-1`, `review-1`, `build-2`, …)
+   because `runs.run` fingerprint-dedupes by key and throws on a reused key with
+   different params.
+4. Clean detection is the marker regex on `review.output` (not line-anchored, so
+   it works in any rendering).
+5. Cap = 3; no `gate` (the commentator's independent review is the gate, matching
+   the old engine). Launch with `async: true`.
+
+## New `src/extensions/workflow/modes.ts`
+
+```ts
+// ponytail: four workflow modes as pi-subagents workflowScript builders.
+// One-shot-and-sleep: phases run as runs.run steps and the loop auto-repeats
+// until clean or the cap. A workflowScript has no checkpoints, so there are no
+// human gates.
+const MAX_ROUNDS = 3;
+
+function js(value: string): string {
+  return JSON.stringify(value);
+}
+
+const AUTO_LOOP = String.raw`
+const autoLoop = async (goal, context) => {
+  const maxRounds = ${MAX_ROUNDS};
+  for (let round = 1; round <= maxRounds; round++) {
+    const build = await runs.run('build-' + round, {
+      agent: 'builder',
+      task: 'Implement the approved work in the workspace and run relevant checks.\n\nSource of truth (handoff/plan):\n' + context + '\n\nGoal:\n' + goal + (round > 1 ? '\n\nAddress the previous review feedback first.' : ''),
+    });
+    const review = await runs.run('review-' + round, {
+      agent: 'commentator',
+      task: 'Independently review the uncommitted diff and report concrete evidence (what you inspected and what you ran). Do not modify the workspace.\n\nAcceptance criteria (source of truth):\n' + context + '\n\nBuilder completion summary:\n' + build.output + '\n\nEnd with exactly one line: WORKFLOW_REVIEW_STATUS: clean OR WORKFLOW_REVIEW_STATUS: blocking.',
+    });
+    if (/WORKFLOW_REVIEW_STATUS\s*:\s*clean/i.test(review.output)) {
+      return { result: 'clean', rounds: round };
+    }
+  }
+  return { result: 'maxed', rounds: maxRounds };
+};`;
+
+export function buildLoopScript(goal: string): string {
+  return String.raw`const goal = ${js(goal)};
+${AUTO_LOOP}
+return await autoLoop(goal, goal);`;
+}
+
+export function buildTaskScript(goal: string): string {
+  return String.raw`const goal = ${js(goal)};
+const plan = await runs.run('plan', { agent: 'architect', task: 'Produce a concrete implementation plan for: ' + goal + '. Cover what to build, how, in what order, which files and components, and the finished result. Return inline.' });
+const reuse = await runs.run('reuse', { agent: 'explorer', task: 'Explore the codebase for reusable patterns relevant to: ' + plan.output + '. Point at relevant areas and dependencies; skip cleanly if wholly new. Return inline.' });
+const handoff = await runs.run('handoff', { agent: 'recapper', task: 'Compile a self-contained handoff from the plan and reuse findings so fresh agents understand the goal, constraints, and acceptance criteria without re-planning.\n\nPlan:\n' + plan.output + '\n\nReuse findings:\n' + reuse.output + '\n\nReturn inline.' });
+${AUTO_LOOP}
+return await autoLoop(goal, handoff.output);`;
+}
+
+export function buildPrototypeScript(goal: string): string {
+  return String.raw`const goal = ${js(goal)};
+const research = await runs.run('research', { agent: 'researcher', task: 'Research the external, fast-changing knowledge this task depends on (libraries, SDKs, APIs, unfamiliar alternatives). Task: ' + goal + '. Synthesize actionable findings with sources. Return inline.' });
+const plan = await runs.run('plan', { agent: 'architect', task: 'Produce a concrete build plan from the research findings.\n\nResearch:\n' + research.output + '\n\nRequest:\n' + goal + '\n\nReturn inline.' });
+const reuse = await runs.run('reuse', { agent: 'explorer', task: 'Explore the codebase for reusable patterns relevant to: ' + plan.output + '. Return inline.' });
+const handoff = await runs.run('handoff', { agent: 'recapper', task: 'Compile a self-contained handoff from the plan and reuse findings.\n\nPlan:\n' + plan.output + '\n\nReuse:\n' + reuse.output + '\n\nReturn inline.' });
+${AUTO_LOOP}
+const loop = await autoLoop(goal, handoff.output);
+const audit = await runs.run('audit', { agent: 'commentator', task: 'Final audit of the uncommitted changes for correctness, plan adherence, and over-engineering (cut bloat, dead flexibility, reinvented stdlib). Plan:\n' + plan.output + '\n\nReport concrete evidence. Do not modify the workspace.' });
+return { ...loop, audited: true };`;
+}
+
+export function buildQuicktypeScript(goal: string): string {
+  return String.raw`const goal = ${js(goal)};
+const plan = await runs.run('plan', { agent: 'architect', task: 'Produce a concrete build plan for: ' + goal + '. Cover what to build, how, in what order, which components, and the finished result. Return inline.' });
+const reuse = await runs.run('reuse', { agent: 'explorer', task: 'Explore the codebase for reusable patterns relevant to: ' + plan.output + '. Return inline.' });
+const handoff = await runs.run('handoff', { agent: 'recapper', task: 'Compile a self-contained handoff from the plan and reuse findings.\n\nPlan:\n' + plan.output + '\n\nReuse:\n' + reuse.output + '\n\nReturn inline.' });
+${AUTO_LOOP}
+const loop = await autoLoop(goal, handoff.output);
+const audit = await runs.run('audit', { agent: 'commentator', task: 'Final audit of the uncommitted changes for correctness, plan adherence, and over-engineering (cut bloat, dead flexibility, reinvented stdlib). Plan:\n' + plan.output + '\n\nReport concrete evidence. Do not modify the workspace.' });
+return { ...loop, audited: true };`;
+}
+```
+
+## New `src/extensions/workflow/extension.ts`
+
+```ts
+// ponytail: thin shell. Registers the four /workflow-* commands and launches
+// each mode's scripted workflow through pi-subagents' launchSlashSubagent.
+
+import type { ExtensionAPI } from "@selesai/code";
+import { launchSlashSubagent } from "../pi-subagents/src/slash/slash-commands.ts";
+import { buildLoopScript, buildPrototypeScript, buildQuicktypeScript, buildTaskScript } from "./modes.ts";
+
+export default function workflowModesExtension(pi: ExtensionAPI): void {
+  const register = (name: string, description: string, build: (goal: string) => string) =>
+    pi.registerCommand(name, {
+      description,
+      handler: async (args, ctx) => {
+        const goal = args.trim();
+        if (!goal) {
+          ctx.ui.notify(`${description}\nUsage: /${name} <goal>`, "info");
+          return;
+        }
+        launchSlashSubagent(pi, ctx, { workflowScript: build(goal), async: true, agentScope: "both" });
+      },
+    });
+
+  register("workflow-task", "Run the task workflow (plan → reuse → handoff → auto build↔review loop) as a scripted workflow.", buildTaskScript);
+  register("workflow-prototype", "Run the full prototype workflow (research → plan → reuse → handoff → auto loop → audit) as a scripted workflow.", buildPrototypeScript);
+  register("workflow-quicktype", "Run the quicker prototype workflow without research (plan → reuse → handoff → auto loop → audit) as a scripted workflow.", buildQuicktypeScript);
+  register("workflow-loop", "Run a direct auto build↔review loop for an already-agreed plan as a scripted workflow.", buildLoopScript);
+}
+```
+
+## Tests (`src/__tests__/workflow-modes.test.ts`)
+
+Replace the chain-shape tests with builder tests (no pi-subagents mocking; only
+the pure builder functions):
+
+- `buildLoopScript(goal)` returns a string containing `'build-'`, `'review-'`,
+  `agent: 'builder'`, `agent: 'commentator'`, `maxRounds = 3`, and the
+  `WORKFLOW_REVIEW_STATUS` marker.
+- Goal injection: `buildLoopScript('it\'s "quoted"')` contains the goal as a
+  valid JS literal (JSON.stringify'd) and does not break on quotes/backslashes.
+- `buildTaskScript` contains `'plan'`, `'reuse'`, `'handoff'` runs and NO
+  `'research'`/`'audit'` keys.
+- `buildPrototypeScript` contains `'research'` AND `'audit'`.
+- `buildQuicktypeScript` contains `'audit'` and NO `'research'`.
+- `buildLoopScript` contains NO `'plan'`/`'handoff'`/`'audit'` keys.
+- Import `extension.ts` with a minimal fake `pi` (capture `registerCommand`) →
+  registers exactly the four names; empty goal → usage notify.
+
+## Docs
+
+- `workflow.mdx` (EN + ID): describe the modes as scripted auto-loop workflows
+  (no checkpoints; loop capped at 3; `async`/background; recover via
+  `mission.list`/`status`; the old `workflow.json` resume note stays as the
+  migration note). Remove chain/checkpoint-specific wording.
+- `pi-subagents.mdx`: update the workflow-modes paragraph (scripted auto-loop,
+  not chains/checkpoints).
+- `capabilities.ts`: benefit string → "scripted auto-loop workflows".
+- `extension-customization.json`: the workflow record already points at
+  `modes.ts` + `extension.ts`; update any wording that says "chain/checkpoint" to
+  "scripted workflow".
+
+## Skill (`references/execution-controls.md`, 3 copies)
+
+Replace the "Workflow modes as saved chains" note with: the bundled workflow
+extension ships the four modes as `workflowScript` auto-loops (`/workflow-*`);
+each mode runs its phases as `runs.run` steps and loops build↔review until clean
+or the 3-round cap; no checkpoints (one-shot-and-sleep); durable state is the
+auto-created mission; recover via `mission.list`/`status`.
+
+## Verification
+
+1. `npx vitest run src/__tests__/workflow-modes.test.ts src/__tests__/bootstrap.test.ts`
+2. `npx tsc --noEmit` (repo root) + `npx tsc --noEmit` (pi-subagents) + `npx tsgo -p tsconfig.build.json --noEmit`
+3. `npx astro check` + `npm run validate:content` (doc-web)
+4. `diff -q` across the 3-way skill sync (byte-identical)
+
+## Constraints
+
+- Do NOT modify `src/extensions/pi-intercom/`, `src/extensions/handoff-new.ts`,
+  `src/extensions/inline-skills.ts`, `src/extensions/inline-skills.test.ts` (the
+  user's parallel work). Leave them exactly as-is.
+- Do NOT commit or push. Leave all changes uncommitted.
+- ponytail: smallest diff; no new deps/abstractions; reuse `launchSlashSubagent`.