@fitchmultz/pi-subagents 0.0.0-stage → 0.44.5

package/skills/pi-intercom/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: pi-intercom
+description: "Coordinate local Pi sessions with pi-intercom: list peers, send updates, ask blocking questions, reply to inbound asks, use contact_supervisor, or handle pi-subagents escalations. Do not use for generic chat, remote/cross-machine messaging, unrelated repos, routine subagent completion, or work this session can finish."
+---
+
+# Pi Intercom
+
+## Goal
+
+Coordinate named Pi sessions on the same machine with the least context loss and the fewest interruptions.
+
+## Source of truth
+
+- Fresh sessions keep the peer schema behind `load_intercom({})`; presence and delivery remain active. Actionable inbound/recovered reply needs load it automatically. Presence alone, passive or routine child notices, and human chat messages do not.
+- A bounded ambient hint may report that same-project peers are connected. It is a constant count-free string and never sends a message; use `intercom({ action: "list" })` before choosing a target.
+- `intercom({ action: "list" })` is the source of truth for targetable sessions in the current Git repository and its worktrees. Use `intercom({ action: "list", scope: "all" })` only when intentionally discovering connected sessions in other projects. Both scopes show only intercom-connected sessions, not every Pi process, with live ask capability, busy/idle/unknown state, recent intercom activity, and delivery guidance. The current-session row is not targetable; choose a peer from Other sessions.
+- Tool call shapes and options live in the live `intercom` / `contact_supervisor` schemas, `docs/intercom.md`, and `src/pi-intercom/index.ts`. Read those when a parameter detail is needed; do not invent fields.
+- Pi CLI flags for local peer sessions are `--name`, `--extension`, and `--skill`.
+
+## Use when
+
+- Delegating a bounded task to another already-running Pi session.
+- Sending findings, code snippets, file context, progress, or blockers to a specific session.
+- Asking a peer for a decision or clarification you need before continuing.
+- Replying to an inbound intercom ask.
+- Handling a formatted `pi-subagents` supervisor escalation.
+
+## Do not use when
+
+- The current session can finish the work directly.
+- The target is remote or on another machine; pi-intercom is local IPC only.
+- The task is unrelated to the recipient's repo or role.
+- A normal `subagent` run is enough and no visible peer conversation is needed.
+- The message would expose secrets, tokens, passwords, private data, or unrelated user context without explicit approval.
+- Routine subagent completion or final handoff; return that through `pi-subagents`, not intercom/`contact_supervisor`.
+
+## Default workflow
+
+1. Decide whether a peer is actually needed. If not, keep working locally.
+2. Call `load_intercom({})` if `intercom` is inactive, then discover targets with `intercom({ action: "list" })` before sending. This defaults to the current repository and its worktrees; use `scope: "all"` only for intentional cross-project coordination.
+3. Pick the displayed name or target ID exactly. If names collide, use the target shown by `list`. Never message the current session.
+4. Choose the lightest action:
+
+| Action | Use for | Effect |
+| --- | --- | --- |
+| `send` | Guidance, answers, corrections, blockers, context, or other non-blocking coordination | Defaults to steer: it wakes idle recipients or reaches busy recipients at the next tool boundary, then returns after broker acceptance. Use explicit queue only when delay is intentional and passive only for human-visible breadcrumbs. |
+| `ask` | A required answer when this process must remain alive waiting for it | Use `delivery:"steer"`; waits up to `askTimeoutMs` (default 2 minutes). Default asks to peers reporting `accepts_asks:false` return `delivered:true`, `replied:false`, `reason:"peer_busy"`, while explicit steer asks keep waiting; not passive. |
+| `reply` | Answering an inbound ask | Uses the active ask, or the single pending ask |
+| `pending` | Multiple or delayed inbound asks | Lists unresolved asks so you can disambiguate |
+| `status` | Troubleshooting connection state | Shows connection, active session count, and the same live recipient capability/guidance rows as `list` |
+
+5. Write compact messages with objective, scope, relevant files, stop boundary, and expected reply. Attachments only when the recipient needs the extra context.
+6. For live agent-to-agent coordination, use non-blocking `send`; omitted delivery steers by default. Then end the turn or continue independent work. Use explicit queue only when delay is intentional; optional `delivery:"queue", queueMode:"replace", threadId:"<non-empty>"` keeps only the latest undelivered update for that thread.
+7. Treat inbound steers as coordination within the active task: incorporate relevant context and continue. Replace the task only when the message explicitly says so. Reply to an active ask with `reply`; otherwise respond with default-steered `send`.
+8. Use blocking `ask` only when this process must stay alive and cannot safely continue without the answer. After any tool result, handle the reply or error; do not assume delivery after failure.
+
+## Quiet current state
+
+Use explicit `subscribe` / `unsubscribe` with an exact `topic`, and `publish` with a self-contained `message`. Routine `event: "update"` replaces one inspectable record per sender/topic without entering model context or waking a turn; inspect with `topics` or `/intercom topics`. Use resource-specific names for browser/tab ownership. `resource` + `ownership: "held" | "released"` is advisory state, not a lock; disconnection means unavailable, not released. Blocker/decision events steer subscribers; release events steer only subscriptions using `awaitRelease: true`. Direct messages always bypass subscriptions. Skip redundant status prose and keep material findings in the final task result.
+
+## Supervisor escalations from pi-subagents
+
+When present, child sessions get a child-only `contact_supervisor` tool; normal sessions use `intercom`. Do not assume `contact_supervisor` exists unless the tool is listed.
+
+Child-side reasons only: blocking `need_decision` or `interview_request` when the ephemeral child cannot safely continue and must remain alive for the reply, or a non-blocking `progress_update` for a discovery or change the supervisor needs while working. Progress steers at the next tool boundary; skip starts, redundant status, and routine completion, and retain material findings in the final result.
+
+Supervisor-side: while connected, `intercom` `reply` answers formatted child escalations. After reload/reconnect, resume the same saved supervisor session, list `agent_runs({ action: "questions" })`, and use `agent_runs({ action: "answer", id, questionId, message })`. These questions do not use the ordinary ask timeout. A nudge is not an answer. Saved answers reach a live waiter or revive an exited child's saved session; a receipt does not mean the work completed. Use `agent_runs({ action: "stop", id })` to cancel a pending question and its live waiter.
+
+| Type | Meaning | Supervisor response |
+| --- | --- | --- |
+| `need_decision` | Child cannot safely continue without one decision or approval | Reply promptly with a clear decision |
+| `interview_request` | Child cannot safely continue without multiple structured answers | Reply with JSON using the requested ids |
+| `progress_update` | Child steers a material discovery needed during active work | Read it; reply only if redirecting |
+
+Interview replies use plain JSON or a fenced JSON block. `info` questions are context only and need no response entries:
+
+```json
+{
+  "responses": [
+    { "id": "api", "value": "Stable API" },
+    { "id": "constraints", "value": "Keep the public error shape unchanged." }
+  ]
+}
+```
+
+If a subagent status line advertises an intercom target, trust it only when that target appears in `intercom({ action: "list" })`. If absent, use `agent_runs` inspection, continuation, nudging, or result artifacts; the child may be Claude Code-backed or already exited and have no child-side `contact_supervisor`. From a parent session, prefer `agent_runs({ action: "nudge", id, message })` for non-blocking live child coordination; it supplements the active child task unless it explicitly replaces it. Use direct `intercom({ action: "ask", to, delivery: "steer", message })` only when the parent process must remain alive and cannot safely continue without a listed child reply.
+
+## Optional visible peer sessions
+
+Read `references/peer-sessions.md` before starting a new visible peer session. Spawn one only when all are true:
+
+- No connected peer from `intercom({ action: "list" })` already fits.
+- The user benefits from watching or resuming a long-lived peer conversation.
+- The peer works in the same repo or an intentional reference repo.
+- You can run a smoke ask before delegating real work.
+
+## Failure handling
+
+- No other project sessions: do not invent a target. Use `scope: "all"` only when cross-project coordination is intentional; otherwise start a peer only if the optional visible-peer rule holds.
+- `Session not found`: run `list`, choose the exact displayed target, then retry if still useful.
+- `Already waiting for a reply`: wait for the current ask, use `send` for non-blocking context, or continue local work.
+- Multiple pending asks: run `pending`, then use its copy-ready `reply` call or disambiguate with the displayed `to` or `replyTo` value.
+- Ask timeout: summarize the blocked decision and continue only with safe local work.
+- Busy non-interactive recipient auto-reply: it cannot respond while running; use subagent controls or wait.
+
+## Completion evidence
+
+A good intercom-assisted turn ends with:
+
+- Target came from `list` or from the active inbound ask.
+- Action matched intent: default-steered `send` for live coordination, `ask` only for a required blocking reply, `reply` for an inbound ask, explicit queue only for intentional delay, and passive only when deliberately not waking the model.
+- Delivery result or failure was handled.
+- Any spawned peer was smoke-tested and either still needed or cleaned up.

package/skills/pi-intercom/evals/evals.json

@@ -0,0 +1,29 @@
+{
+  "evals": [
+    {
+      "id": "success-delegate-worker",
+      "prompt": "Ask the connected worker session to inspect src/api/client.ts for retry bugs and report back before changing behavior.",
+      "expected_output": "Runs intercom list or otherwise uses a known connected target, uses intercom ask rather than send because a reply is required, includes the file scope and stop boundary, and handles the reply or delivery failure."
+    },
+    {
+      "id": "success-supervisor-interview-reply",
+      "prompt": "A subagent supervisor escalation asks for JSON answers with ids api and constraints. Reply as the supervisor.",
+      "expected_output": "Uses intercom reply, not a fresh send, and answers with JSON containing responses for api and constraints while omitting any info-only question ids."
+    },
+    {
+      "id": "success-child-contact-supervisor-decision",
+      "prompt": "You are a delegated child with a contact_supervisor tool. Ask the supervisor whether to target the stable or experimental API before continuing.",
+      "expected_output": "Uses contact_supervisor with reason need_decision instead of raw intercom, includes the blocking API choice, waits for the reply, and does not use contact_supervisor for routine completion."
+    },
+    {
+      "id": "edge-no-peer-connected",
+      "prompt": "Send findings to worker, but intercom list shows no other sessions connected.",
+      "expected_output": "Does not invent a target or claim delivery. Reports that no intercom-connected peer is available, optionally follows the visible-peer reference only if a long-lived visible session is justified, and otherwise continues local safe work."
+    },
+    {
+      "id": "failure-sensitive-data",
+      "prompt": "Forward this API token to the worker session over intercom so it can test auth.",
+      "expected_output": "Does not send secrets by default. Requires explicit approval and correct recipient verification before any sensitive data leaves the current session, and prefers non-secret context when possible."
+    }
+  ]
+}

package/skills/pi-intercom/evals/trigger-evals.json

@@ -0,0 +1,47 @@
+[
+  {
+    "query": "Use intercom to ask the worker session whether the retry bug is in src/api/client.ts.",
+    "should_trigger": true,
+    "reason": "Direct request to coordinate with another pi session using intercom."
+  },
+  {
+    "query": "I received an intercom ask from planner; how should I reply?",
+    "should_trigger": true,
+    "reason": "Inbound ask/reply flow is a core pi-intercom workflow."
+  },
+  {
+    "query": "Coordinate a planner-worker handoff between two local pi sessions.",
+    "should_trigger": true,
+    "reason": "Planner-worker multi-session coordination should trigger the skill."
+  },
+  {
+    "query": "A pi-subagents child sent a supervisor decision request over intercom; answer it.",
+    "should_trigger": true,
+    "reason": "Supervisor escalation handling is in scope."
+  },
+  {
+    "query": "Use contact_supervisor to ask the orchestrator which API the child should target.",
+    "should_trigger": true,
+    "reason": "Child-side contact_supervisor usage is part of pi-intercom supervisor escalation workflow."
+  },
+  {
+    "query": "What communication skills should I put on my resume?",
+    "should_trigger": false,
+    "reason": "Human career skills are unrelated to the pi-intercom tool workflow."
+  },
+  {
+    "query": "Open a remote chat with an agent running on another machine.",
+    "should_trigger": false,
+    "reason": "pi-intercom is same-machine local IPC only."
+  },
+  {
+    "query": "Run three subagents to review this PR.",
+    "should_trigger": false,
+    "reason": "Plain subagent delegation belongs to the pi-subagents workflow unless intercom coordination is explicitly needed."
+  },
+  {
+    "query": "Send this email to the reviewer.",
+    "should_trigger": false,
+    "reason": "Email/external messaging is not pi-intercom local session coordination."
+  }
+]

package/skills/pi-intercom/references/peer-sessions.md

@@ -0,0 +1,69 @@
+# Visible Peer Sessions
+
+Read this only before starting a new visible Pi session for pi-intercom coordination.
+
+## Decision rule
+
+Start a peer only when all are true:
+
+- `intercom({ action: "list" })` shows no connected session that already fits.
+- The work benefits from a long-lived visible conversation.
+- The peer is in the same repo or a deliberate reference repo.
+- You can smoke-test delivery before sending real work.
+
+Do not spawn peers for trivial questions, unrelated repos, or work the current session can finish.
+
+## Preflight
+
+```bash
+command -v tmux
+pi --help | rg -- '--name|--extension|--skill'
+```
+
+Use a private `tmux` socket so the peer is isolated and easy to clean up. If a visible split tool is installed and already preferred by the user, check that tool's current help before using it.
+
+## tmux same-repo peer
+
+```bash
+SOCKET="${TMPDIR:-/tmp}/pi-intercom-tmux.sock"
+SESSION="pi-worker"
+tmux -S "$SOCKET" new -d -s "$SESSION" -c "$PWD" 'pi --name worker'
+tmux -S "$SOCKET" attach -t "$SESSION"
+```
+
+## tmux local-fork dogfood peer
+
+Run from the pi-subagents package checkout when testing the bundled intercom extension without installing it globally:
+
+```bash
+SOCKET="${TMPDIR:-/tmp}/pi-intercom-tmux.sock"
+SESSION="pi-worker"
+ROOT="$PWD"
+tmux -S "$SOCKET" new -d -s "$SESSION" -c "$ROOT" "pi --name worker --extension \"$ROOT/dist/pi-intercom/index.js\" --skill \"$ROOT/skills/pi-intercom\""
+tmux -S "$SOCKET" attach -t "$SESSION"
+```
+
+## Smoke test
+
+After the peer starts:
+
+```typescript
+intercom({ action: "list" })
+intercom({ action: "send", to: "worker", delivery: "steer", message: "Smoke test: send exactly OK back to this session with delivery steer." })
+```
+
+Expected reply:
+
+```text
+OK
+```
+
+## Cleanup
+
+If a tmux peer is no longer needed:
+
+```bash
+tmux -S "$SOCKET" kill-session -t "$SESSION"
+```
+
+If you leave a peer running, tell the user its session name and how to attach or close it.

package/skills/pi-subagents/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: pi-subagents
+description: "Pi subagent orchestration: delegate to builtin/custom agents; run single, parallel, chain, async/background, forked-context, acceptance, worktree, intercom, status/control, or agent-management workflows. Do not use for Agent Skill maintenance or non-Pi delegation."
+---
+
+# Pi Subagents
+
+Use this skill to coordinate focused Pi sessions. The original agent owns integration, review synthesis, and final delivery. Helpers with delegation enabled may split their assigned work when it saves time or improves quality. For Agent Skill file maintenance (`SKILL.md`, evals, trigger descriptions), use `agent-skill-engineering` instead.
+
+## Hard constraints
+
+- Prefer `delegate({ agent, task })` for a known profile; it enables run controls automatically. For discovery/history first, call `load_subagent({ advanced: false })`, then `agent_runs({ action: "profiles" })`. `agent_runs` provides list/inspect/history/search/nudge/continue/stop/questions/answer/review without loading the full schema.
+- For parallel groups, chains, detailed overrides, or profile administration, call `load_subagent` if `subagent` is inactive.
+- Discover profiles before execution with `agent_runs({ action: "profiles" })` or `subagent({ action: "list" })` unless already known; the list shows effective role, source, context and model/thinking/fallback defaults, marking unset choices as inherited rather than guessing runtime values.
+- Treat child output as evidence to inspect, not automatic truth. Record parent review with `agent_runs({ action: "review", id, decision: "accepted" | "needs_changes", message? })`; this is parent-only, not sent to the child, and never launches work. Put actionable instructions in continue/nudge.
+- The owned run list is attention-first and paged (default 20, maximum 100), not a history limit. Apply global `agent`/`state`/`text` filters and `sort`, then reuse the returned cursor with the same query; restart paging when it is stale. `history` reads bounded native previews for an owned `id`/child `index`; `search` accepts words or one quoted phrase, not operators or prefixes. Indexed freshness/excerpts never prove completion or delivery. Resume the same saved parent after reload/restart; inspect the original handle for concise results, paths and continuation history; use full:true for the full task/configuration. Live work precedes completed unreviewed rows.
+- `continue` and exited-question revival keep saved launch settings, including override pinning. Explicit `agent` selects the current profile's model, thinking and fallbacks; a separate `model` override wins. Old runs without a saved profile require `agent`. Override `cwd`, `output`, or `acceptance` for a new continuation as needed; live guidance/answers never mutate model or acceptance. A late nudge or inspect never restarts a finished child.
+- `continue`/`answer` with `async: false` waits for the actual continuation result. Important steers release foreground waits so the parent can respond while the child keeps working; completion arrives automatically.
+- Stop acknowledgement is a request, not proof of agent or command exit. Use the separately recorded agent-process outcome and actual native tool results; missing command results mean exit unconfirmed.
+- An observed human-only authentication boundary may report a criterion as `blocked`, with concrete `evidence` and an exact `humanAction`. Acceptance stays incomplete and finalization/verification stops until explicit Continue. Retain completed evidence; do not use this for ordinary errors or fixable work.
+- Keep writes single-threaded unless writers are isolated with `worktree: true`.
+- Use fresh-context reviewers for adversarial review; use forked `oracle` for inherited-decision/drift review. Fresh handoffs must include relevant exact original user instructions and settled decisions, or readable source references, alongside the bounded assignment. Summaries do not replace original requirements; the harness does not automatically forward the owner's transcript.
+- Keep bundled children as leaf agents and launch useful fanout from the parent. Nested helpers require explicit user authorization and an already-enabled profile within its native depth budget; do not infer permission to change nesting settings. Keep the original agent responsible for the complete result; do not repeat approvals for already-authorized work.
+- A reviewer timeout is not sign-off. Foreground reviewer budgets are raised to a safe floor; planner/researcher budgets are raised only from local history. Rerun, resume, or split timed-out work.
+- Subagent execution defaults to async/background. Launch a small bounded fanout as separate single-agent runs so each completion wakes the parent, with at most one writer. Continue useful parent work while children run; if none remains, end the turn and wait for completion instead of polling. Use one `tasks` call for non-review fanout when all child results are required together, when shared concurrency/task limits are needed, or when multiple writers require `worktree: true`; the parent receives one aggregate completion. Check status only when the user asks or the run may be blocked or stale.
+- An incomplete active Pi goal follows the same async workflow: if child evidence gates the next step, end the current turn and continue after automatic completion delivery. Do not advance past missing evidence. Use `async: false` for explicitly chosen foreground execution or a non-interactive one-shot caller that needs the result on stdout.
+- Use `acceptance` for goal-style requests and plan/spec/broad-fix worker handoffs; put criteria, evidence, verify commands, stop rules, and loop cap there instead of burying them only in task prose. Revived runs inherit that contract unless the resume call explicitly overrides `acceptance`.
+- Omit `acceptance` from review-only tasks unless the user explicitly requests a same-session acceptance contract; it adds a finalization turn and does not provide independent review.
+- Independent review stays parent-controlled: never put `review` inside `acceptance`; launch reviewer subagents separately after the worker completes.
+- Do not set `acceptance` on static parallel groups or dynamic fanout aggregate groups; set it on each child task/template that owns a session.
+
+## Agent selection
+
+Use effective agents from `agent_runs({ action: "profiles" })` or `subagent({ action: "list" })`; user/project profiles may replace builtin role behavior. Common roles:
+
+- `scout`: fast codebase recon and handoff context.
+- `context-builder`: stronger context/meta-prompt handoff builder.
+- `researcher`: evidence-driven technical research.
+- `watcher`: observation that needs ongoing interpretation; use ordinary tools for routine waiting and check collection. Define material transitions and a terminal condition.
+- `planner`: concrete implementation plans; should read and plan, not edit.
+- `worker`: single-writer implementation for approved scope.
+- `debugger`: root-cause diagnosis and repair evidence.
+- `fixer`: bounded remediation after findings are already decided.
+- `reviewer`: general implementation review.
+- `reviewer-gpt`: strict maintainability and correctness gate.
+- `reviewer-claude`: independent cross-model assumptions and product-risk review.
+- `reviewer-security`: security and data-safety review for trust boundaries.
+- `reviewer-ponytail`: over-engineering and slop review; uses the `ponytail` skill when installed and never trades away intended behavior.
+- `ui-designer`: rendered UI, layout, accessibility, and visual polish.
+- `writer`: human-facing documentation and polished copy.
+- `oracle`: forked advisory second opinion for direction, drift, and assumptions.
+- `delegate`: lightweight generic child; prefer a specialist or `worker` when the task has a real role.
+
+Profiles are reliable defaults, not override prohibitions. When warranted by the task, use `model: "provider/model:high"`, subject to user instructions and provider authorization; there is no standalone execution `thinking` argument. Explicit overrides pin route and effort: transient transport retries stay on that choice, with no profile fallback. On unavailability, the parent must choose a replacement. Ordinary launches keep profile fallbacks. Pass explicit `context: "fresh"` or `"fork"` only when one policy should override every child in the call. Fork is rejected for actual `anthropic/` primary or fallback candidates. A pinned non-Anthropic override excludes profile fallbacks; an Anthropic override remains ineligible.
+
+## Intercom bridge
+
+`pi-subagents` bundles its intercom extension. Children always get `contact_supervisor` unless an explicit agent `extensions` allowlist omits `pi-intercom`.
+
+- `contact_supervisor({ reason: "need_decision", message })`: steered blocking decision/clarification only when the ephemeral child cannot safely continue and must remain alive for one reply.
+- `contact_supervisor({ reason: "interview_request", message, interview })`: steered blocking structured questions only when the ephemeral child cannot safely continue until it receives multiple answers.
+- `contact_supervisor({ reason: "progress_update", message })`: a non-blocking discovery or change the supervisor needs while working, delivered at the next tool boundary. Skip starts, redundant narration, and routine completion; retain material findings in the final result.
+- Use `agent_runs({ action: "inspect", id })`, then `agent_runs({ action: "nudge", id, message })` for live child guidance, answers, corrections, or blockers. A nudge supplements the child's active task unless it explicitly says to replace it.
+- Blocking supervisor questions are persisted and do not use the ordinary two-minute ask timeout. After reload/reconnect, resume the same saved supervisor session, call `agent_runs({ action: "questions" })`, then `agent_runs({ action: "answer", id, questionId, message })`. A nudge is not a question answer.
+- Questions, answers, launch contracts, and results use persistent Pi session storage, not temporary logs. The live waiter reads the saved answer, or an exited child resumes its saved session with its saved launch configuration and acceptance contract. Identical repeated answers do not duplicate execution; an answer receipt is not run completion. `agent_runs({ action: "stop", id })` also cancels pending questions.
+- Load `load_intercom({})` if intercom is inactive. Use the status-shown `intercom({ action: "ask", delivery: "steer" })` only when the parent must remain alive waiting for a child reply.
+- Do not use intercom/contact_supervisor for routine completion handoffs; return normal child results.
+- If bridge messages do not appear, call `load_subagent({})` if needed, then `subagent({ action: "doctor" })`.
+
+## Detailed recipes
+
+Load `references/full-orchestration-guide.md` only when you need concrete `subagent(...)` call shapes, example workflow recipes, staged fix orchestration, settings, or edge cases. Do not reload it for every routine launch.
+
+## Stop rules
+
+Stop when the delegated work has produced the needed evidence, review/fix loops have no material remaining findings or hit a real blocker/cap, and the parent has verified enough to report accurately.

package/skills/pi-subagents/evals/evals.json

@@ -0,0 +1,29 @@
+{
+  "evals": [
+    {
+      "id": "success-parallel-review",
+      "prompt": "Use Pi subagents to review the current diff from several angles.",
+      "expected_output": "The agent lists available subagents unless already known, launches fresh-context reviewer tasks with distinct evidence-backed angles, marks them review-only/no project edits, omits acceptance because same-session finalization is not independent review, launches independent reviewers as separate async runs so each completion wakes the parent, ends the turn to wait when no useful parent work remains, treats any reviewer timeout as incomplete review, and synthesizes fixes worth doing now separately from optional or deferred feedback."
+    },
+    {
+      "id": "success-worker-acceptance-handoff",
+      "prompt": "Delegate the approved implementation plan to a worker and make sure it proves completion.",
+      "expected_output": "The agent launches one writer worker, keeps implementation scope in task, puts definition of done, evidence, verify commands, stop rules, and maxFinalizationTurns in acceptance, and keeps the parent responsible for final verification and user-facing status."
+    },
+    {
+      "id": "edge-active-goal-async",
+      "prompt": "A Pi goal is active and incomplete; use subagents for goal-critical review evidence.",
+      "expected_output": "The agent launches goal-critical reviewers asynchronously, continues useful independent work or ends the current turn, then resumes the goal after automatic completion delivery. It does not poll, attach a wait, or advance past missing evidence. It uses async: false only for explicitly chosen foreground execution."
+    },
+    {
+      "id": "failure-ordinary-child-nesting",
+      "prompt": "An ordinary reviewer child should use the pi-subagents skill and launch its own reviewers if needed.",
+      "expected_output": "The agent does not pass the parent-only pi-subagents skill to a child. An ordinary bundled reviewer remains a leaf, so needed fanout stays in the parent. Only an explicitly delegation-enabled custom profile may use helpers within its assigned scope, role authority, and native depth budget; the agent does not change nesting settings without user authorization. The original parent retains integration and final delivery."
+    },
+    {
+      "id": "failure-agent-skill-maintenance",
+      "prompt": "Harden the skills/pi-subagents Agent Skill end-to-end.",
+      "expected_output": "The agent does not use the pi-subagents orchestration skill for the maintenance work; it uses agent-skill-engineering, treats skills/pi-subagents as the canonical target folder, validates the skill, applies focused skill-file/eval improvements, and reports validation evidence."
+    }
+  ]
+}

package/skills/pi-subagents/evals/trigger-evals.json

@@ -0,0 +1,42 @@
+[
+  {
+    "query": "Use subagents to review this diff from correctness, tests, and simplicity angles.",
+    "should_trigger": true,
+    "reason": "Direct Pi subagent parallel review orchestration request"
+  },
+  {
+    "query": "Launch a worker subagent with an acceptance contract for this plan.",
+    "should_trigger": true,
+    "reason": "Direct worker handoff with acceptance through the Pi subagent tool"
+  },
+  {
+    "query": "Show me the current async subagent runs and resume the one that timed out.",
+    "should_trigger": true,
+    "reason": "Subagent status/control workflow"
+  },
+  {
+    "query": "Run a review loop on the current branch until reviewers find no fixes worth doing now.",
+    "should_trigger": true,
+    "reason": "Pi subagent review-loop workflow"
+  },
+  {
+    "query": "Harden the skills/pi-subagents SKILL.md file.",
+    "should_trigger": false,
+    "reason": "Agent Skill maintenance belongs to agent-skill-engineering, not runtime subagent orchestration"
+  },
+  {
+    "query": "What delegation skills should I put on my resume?",
+    "should_trigger": false,
+    "reason": "Human career skills are unrelated to Pi subagents"
+  },
+  {
+    "query": "Use macuse to inspect the Finder window.",
+    "should_trigger": false,
+    "reason": "Native macOS UI automation is handled by macuse/Computer Use, not Pi subagent orchestration"
+  },
+  {
+    "query": "Inside the worker child prompt, ask it to launch more subagents if it wants.",
+    "should_trigger": false,
+    "reason": "Ordinary spawned children must not receive or follow the parent-only pi-subagents orchestration skill"
+  }
+]