@xzzpig/pi-subagents 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (196) hide show
  1. package/CHANGELOG.md +1621 -0
  2. package/LICENSE +21 -0
  3. package/README.md +118 -0
  4. package/agents/delegate.md +14 -0
  5. package/agents/oracle.md +74 -0
  6. package/agents/researcher.md +52 -0
  7. package/agents/reviewer.md +79 -0
  8. package/agents/scout.md +50 -0
  9. package/agents/worker.md +58 -0
  10. package/index.ts +1 -0
  11. package/inspector-runner.mjs +11 -0
  12. package/install.mjs +93 -0
  13. package/package.json +105 -0
  14. package/prompts/gather-context-and-clarify.md +13 -0
  15. package/prompts/parallel-cleanup.md +59 -0
  16. package/prompts/parallel-research.md +50 -0
  17. package/prompts/parallel-review.md +54 -0
  18. package/prompts/review-loop.md +43 -0
  19. package/skills/pi-subagents/SKILL.md +41 -0
  20. package/skills/pi-subagents/references/constraints-and-recipes.md +251 -0
  21. package/skills/pi-subagents/references/execution-controls.md +428 -0
  22. package/skills/pi-subagents/references/management-authoring-rpc.md +161 -0
  23. package/skills/pi-subagents/references/prompting-and-roles.md +242 -0
  24. package/src/agents/agent-management.ts +1256 -0
  25. package/src/agents/agent-memory.ts +254 -0
  26. package/src/agents/agent-refinements.ts +624 -0
  27. package/src/agents/agent-scope.ts +6 -0
  28. package/src/agents/agent-selection.ts +25 -0
  29. package/src/agents/agent-serializer.ts +163 -0
  30. package/src/agents/agents.ts +1889 -0
  31. package/src/agents/chain-serializer.ts +280 -0
  32. package/src/agents/frontmatter.ts +149 -0
  33. package/src/agents/identity.ts +30 -0
  34. package/src/agents/proactive-skills.ts +194 -0
  35. package/src/agents/skills.ts +761 -0
  36. package/src/api/background-work.ts +197 -0
  37. package/src/api/capability-ceiling.ts +17 -0
  38. package/src/api/control-channel.ts +4 -0
  39. package/src/api/delegation.ts +119 -0
  40. package/src/api/external-runs.ts +129 -0
  41. package/src/api/intercom-bridge.ts +3 -0
  42. package/src/api/pi-args.ts +5 -0
  43. package/src/api/preflight.ts +403 -0
  44. package/src/api/shared-types.ts +19 -0
  45. package/src/extension/config.ts +76 -0
  46. package/src/extension/control-notices.ts +58 -0
  47. package/src/extension/doctor.ts +230 -0
  48. package/src/extension/fanout-child.ts +201 -0
  49. package/src/extension/index.ts +805 -0
  50. package/src/extension/public-execution.ts +71 -0
  51. package/src/extension/rpc.ts +653 -0
  52. package/src/extension/schemas.ts +375 -0
  53. package/src/extension/steering-notices.ts +35 -0
  54. package/src/extension/tool-description.ts +164 -0
  55. package/src/inspectors/herdr/actions.ts +229 -0
  56. package/src/inspectors/herdr/client.ts +130 -0
  57. package/src/inspectors/herdr/inspector-runner.ts +141 -0
  58. package/src/inspectors/herdr/project-panes.ts +154 -0
  59. package/src/integrations/herdr-status.ts +330 -0
  60. package/src/intercom/intercom-bridge.ts +187 -0
  61. package/src/intercom/native-supervisor-channel.ts +715 -0
  62. package/src/intercom/result-intercom.ts +421 -0
  63. package/src/missions/actions.ts +410 -0
  64. package/src/missions/goal-driver.ts +162 -0
  65. package/src/missions/lifecycle.ts +346 -0
  66. package/src/missions/store.ts +507 -0
  67. package/src/missions/types.ts +157 -0
  68. package/src/missions/workflow-state.ts +250 -0
  69. package/src/policy/authority.ts +46 -0
  70. package/src/profiles/profiles.ts +661 -0
  71. package/src/runs/background/async-execution.ts +1574 -0
  72. package/src/runs/background/async-job-tracker.ts +511 -0
  73. package/src/runs/background/async-resume.ts +539 -0
  74. package/src/runs/background/async-status.ts +542 -0
  75. package/src/runs/background/auto-drain.ts +67 -0
  76. package/src/runs/background/chain-append.ts +328 -0
  77. package/src/runs/background/chain-root-attachment.ts +199 -0
  78. package/src/runs/background/completion-batcher.ts +168 -0
  79. package/src/runs/background/completion-dedupe.ts +54 -0
  80. package/src/runs/background/control-channel.ts +692 -0
  81. package/src/runs/background/fleet-view.ts +540 -0
  82. package/src/runs/background/notify.ts +332 -0
  83. package/src/runs/background/parallel-groups.ts +45 -0
  84. package/src/runs/background/process-terminal.ts +280 -0
  85. package/src/runs/background/result-watcher.ts +414 -0
  86. package/src/runs/background/retained-children.ts +68 -0
  87. package/src/runs/background/run-id-resolver.ts +167 -0
  88. package/src/runs/background/run-status.ts +504 -0
  89. package/src/runs/background/scheduled-runs.ts +753 -0
  90. package/src/runs/background/stale-run-reconciler.ts +396 -0
  91. package/src/runs/background/steering.ts +239 -0
  92. package/src/runs/background/subagent-runner.ts +4718 -0
  93. package/src/runs/background/subagent-wait.ts +661 -0
  94. package/src/runs/background/top-level-async.ts +14 -0
  95. package/src/runs/background/wait-completions.ts +112 -0
  96. package/src/runs/background/wait-config.ts +36 -0
  97. package/src/runs/background/wait-subscriptions.ts +253 -0
  98. package/src/runs/background/wait-tool.ts +34 -0
  99. package/src/runs/foreground/async-steering-action.ts +256 -0
  100. package/src/runs/foreground/async-stop-action.ts +65 -0
  101. package/src/runs/foreground/chain-clarify.ts +1354 -0
  102. package/src/runs/foreground/chain-execution.ts +1527 -0
  103. package/src/runs/foreground/execution.ts +1868 -0
  104. package/src/runs/foreground/foreground-control.ts +132 -0
  105. package/src/runs/foreground/subagent-executor.ts +5532 -0
  106. package/src/runs/shared/acceptance.ts +1365 -0
  107. package/src/runs/shared/agent-contract.ts +38 -0
  108. package/src/runs/shared/capability-ceiling.ts +209 -0
  109. package/src/runs/shared/chain-outputs.ts +118 -0
  110. package/src/runs/shared/child-protocol.ts +401 -0
  111. package/src/runs/shared/completion-guard.ts +95 -0
  112. package/src/runs/shared/context-mode.ts +44 -0
  113. package/src/runs/shared/dynamic-fanout.ts +297 -0
  114. package/src/runs/shared/external-cli-runner.ts +130 -0
  115. package/src/runs/shared/long-running-guard.ts +220 -0
  116. package/src/runs/shared/mcp-direct-tool-allowlist.ts +406 -0
  117. package/src/runs/shared/model-fallback.ts +336 -0
  118. package/src/runs/shared/model-scope.ts +128 -0
  119. package/src/runs/shared/nested-events.ts +1076 -0
  120. package/src/runs/shared/nested-path.ts +52 -0
  121. package/src/runs/shared/nested-render.ts +123 -0
  122. package/src/runs/shared/parallel-handoff.ts +238 -0
  123. package/src/runs/shared/parallel-utils.ts +256 -0
  124. package/src/runs/shared/permissions.ts +95 -0
  125. package/src/runs/shared/pi-args.ts +808 -0
  126. package/src/runs/shared/pi-spawn.ts +163 -0
  127. package/src/runs/shared/process-signal.ts +19 -0
  128. package/src/runs/shared/run-history.ts +181 -0
  129. package/src/runs/shared/runtime-acknowledged-extensions.ts +71 -0
  130. package/src/runs/shared/session-lease.ts +299 -0
  131. package/src/runs/shared/single-output.ts +235 -0
  132. package/src/runs/shared/spawn-budget.ts +128 -0
  133. package/src/runs/shared/structured-output.ts +182 -0
  134. package/src/runs/shared/subagent-control.ts +231 -0
  135. package/src/runs/shared/subagent-prompt-runtime.ts +588 -0
  136. package/src/runs/shared/subagent-startup-retry.ts +104 -0
  137. package/src/runs/shared/task-intent.ts +181 -0
  138. package/src/runs/shared/tool-availability.ts +83 -0
  139. package/src/runs/shared/tool-budget.ts +80 -0
  140. package/src/runs/shared/turn-budget.ts +98 -0
  141. package/src/runs/shared/usage-budget.ts +65 -0
  142. package/src/runs/shared/workflow-graph.ts +231 -0
  143. package/src/runs/shared/worktree.ts +759 -0
  144. package/src/shared/accessible-dir.ts +47 -0
  145. package/src/shared/artifacts.ts +285 -0
  146. package/src/shared/atomic-json.ts +61 -0
  147. package/src/shared/child-transcript.ts +264 -0
  148. package/src/shared/file-coalescer.ts +40 -0
  149. package/src/shared/file-system-retry.ts +47 -0
  150. package/src/shared/fork-context.ts +213 -0
  151. package/src/shared/formatters.ts +133 -0
  152. package/src/shared/jsonl-writer.ts +81 -0
  153. package/src/shared/launch-contract.ts +124 -0
  154. package/src/shared/model-info.ts +81 -0
  155. package/src/shared/post-exit-stdio-guard.ts +85 -0
  156. package/src/shared/session-identity.ts +10 -0
  157. package/src/shared/session-tokens.ts +44 -0
  158. package/src/shared/settings.ts +501 -0
  159. package/src/shared/status-format.ts +55 -0
  160. package/src/shared/types.ts +2069 -0
  161. package/src/shared/utils.ts +613 -0
  162. package/src/slash/delegation-adapters.ts +434 -0
  163. package/src/slash/delegation-json.ts +108 -0
  164. package/src/slash/delegation-request.ts +166 -0
  165. package/src/slash/prompt-template-bridge.ts +383 -0
  166. package/src/slash/prompt-workflows.ts +300 -0
  167. package/src/slash/selector.ts +147 -0
  168. package/src/slash/slash-bridge.ts +192 -0
  169. package/src/slash/slash-commands.ts +994 -0
  170. package/src/slash/slash-live-state.ts +296 -0
  171. package/src/slash/subagents-admin.ts +432 -0
  172. package/src/tui/fleet-status.ts +564 -0
  173. package/src/tui/fleet-transcript.ts +577 -0
  174. package/src/tui/fleet.ts +879 -0
  175. package/src/tui/render-helpers.ts +80 -0
  176. package/src/tui/render.ts +2029 -0
  177. package/src/types/pi-runtime-compat.d.ts +8 -0
  178. package/src/watchdog/change-signature.ts +220 -0
  179. package/src/watchdog/child-status.ts +205 -0
  180. package/src/watchdog/emission-guard.ts +123 -0
  181. package/src/watchdog/lsp-diagnostics.ts +537 -0
  182. package/src/watchdog/model-selection.ts +167 -0
  183. package/src/watchdog/permission-arbiter.ts +145 -0
  184. package/src/watchdog/register-child.ts +117 -0
  185. package/src/watchdog/register-main.ts +440 -0
  186. package/src/watchdog/render.ts +54 -0
  187. package/src/watchdog/review.ts +302 -0
  188. package/src/watchdog/runtime.ts +868 -0
  189. package/src/watchdog/scope.ts +62 -0
  190. package/src/watchdog/settings.ts +568 -0
  191. package/src/watchdog/tool-actions.ts +155 -0
  192. package/src/watchdog/turn-delta.ts +161 -0
  193. package/src/watchdog/types.ts +198 -0
  194. package/src/watchdog/warning-format.ts +73 -0
  195. package/src/workflows/chat-progress.ts +140 -0
  196. package/src/workflows/scripted-workflow.ts +506 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Nico Bailon
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,118 @@
1
+ <p>
2
+ <img src="https://raw.githubusercontent.com/nicobailon/pi-subagents/main/banner.png" alt="pi-subagents" width="1100">
3
+ </p>
4
+
5
+ # pi-subagents
6
+
7
+ `pi-subagents` lets Pi delegate work to focused child agents. Use it for code review, scouting, implementation, parallel audits, saved workflows, background jobs, and anything else that benefits from a second or third set of model eyes.
8
+
9
+ <https://github.com/user-attachments/assets/702554ec-faaf-4635-80aa-fb5d6e292fd1>
10
+
11
+ ## Install
12
+
13
+ ```bash
14
+ pi install npm:@xzzpig/pi-subagents
15
+ ```
16
+
17
+ That is the only required step.
18
+
19
+ ## Try this first
20
+
21
+ You do not need to create agents, write config, or learn slash commands. After installing, ask Pi in plain language:
22
+
23
+ ```text
24
+ Use reviewer to review this diff.
25
+ ```
26
+
27
+ ```text
28
+ Ask oracle for a second opinion on my current plan. Challenge assumptions and tell me what I might be missing.
29
+ ```
30
+
31
+ ```text
32
+ Use scout to understand this code based on our discussion, then ask me clarification questions.
33
+ ```
34
+
35
+ ```text
36
+ Run parallel reviewers: one for correctness, one for tests, and one for unnecessary complexity.
37
+ ```
38
+
39
+ That is enough to start. Pi decides whether to call the `subagent` tool, which agent to use, and how to compose the work.
40
+
41
+ ## How it works
42
+
43
+ Pi is the parent session. A subagent is a focused child Pi session with its own job.
44
+
45
+ When you ask for a subagent, Pi starts the child, gives it the task, and brings the result back. Foreground runs stream in the conversation. Background runs keep working and can be checked later.
46
+
47
+ Installing the extension does not start an automatic reviewer in the background. It gives Pi a delegation tool. If you want every implementation reviewed, say so in your prompt or project instructions:
48
+
49
+ ```text
50
+ When you finish implementing, run a reviewer subagent before summarizing.
51
+ ```
52
+
53
+ ## Builtin agents
54
+
55
+ The extension ships with agents you can use immediately:
56
+
57
+ | Agent | Use it when you want... |
58
+ |-------|--------------------------|
59
+ | `scout` | Fast local codebase recon: relevant files, entry points, data flow, risks. |
60
+ | `researcher` | Web/docs research with sources and a concise research brief. |
61
+ | `worker` | Implementation work. Edits files, validates, escalates unapproved decisions instead of guessing. |
62
+ | `reviewer` | Code review and small fixes against the task/plan, tests, edge cases, and simplicity. |
63
+ | `oracle` | A second opinion before acting. Challenges assumptions without editing. |
64
+ | `delegate` | A lightweight general delegate that behaves close to the parent session. |
65
+
66
+ Rule of thumb: `scout` before you understand the code, `researcher` before you trust external facts, `worker` to implement, `reviewer` to check, and `oracle` when the decision itself feels risky.
67
+
68
+ ## Common workflows
69
+
70
+ | Want | Ask naturally |
71
+ |------|---------------|
72
+ | Get a second opinion | "Ask oracle to review this plan and challenge assumptions." |
73
+ | Solve a hard problem | "Use oracle to investigate this bug before we edit." |
74
+ | Review a diff | "Use reviewer to review this diff." |
75
+ | Run parallel reviewers | "Run reviewers for correctness, tests, and cleanup." |
76
+ | Implement then review | "Implement this, then review it." |
77
+ | Review until clean | "Run a review loop on this change with a max of 3 rounds." |
78
+ | Execute a plan carefully | "Have worker implement this approved plan, then run reviewers and apply the feedback." |
79
+ | Scout before planning | "Use scout to inspect the auth flow before planning." |
80
+ | Run in the background | "Run this in the background." |
81
+ | Use a saved workflow | "Run the review chain on this branch." |
82
+ | Browse agents | "Show me the available subagents." |
83
+ | See running work | "Show active async runs." or "Show the subagent fleet." |
84
+ | Check setup | "Check whether subagents are configured correctly." |
85
+
86
+ For implementation work, the recommended loop is `clarify → scout → worker → fresh reviewers → worker`. Packaged prompt shortcuts like `/parallel-review` and `/review-loop` make these patterns repeatable — see [Workflows](https://github.com/nicobailon/pi-subagents/blob/main/docs/workflows.md).
87
+
88
+ ## Where running work shows up
89
+
90
+ Foreground runs stream progress in the conversation. Background runs keep working after control returns to you.
91
+
92
+ In the TUI, a persistent FleetView below the editor keeps active work visible. `/subagents-fleet` opens a live inspector where you can browse children, read transcripts, steer a running child, or stop a run. You can also just ask: "Show me the current async runs."
93
+
94
+ Details, keybindings, and the machine-readable run artifacts are in [Observability](https://github.com/nicobailon/pi-subagents/blob/main/docs/observability.md).
95
+
96
+ ## If something feels off
97
+
98
+ ```text
99
+ /subagents-doctor
100
+ ```
101
+
102
+ or ask: "Check whether subagents and intercom are set up correctly."
103
+
104
+ ## Documentation
105
+
106
+ The full reference lives in `docs/`:
107
+
108
+ | Doc | What's in it |
109
+ |-----|--------------|
110
+ | [Agents](https://github.com/nicobailon/pi-subagents/blob/main/docs/agents.md) | Custom agents, frontmatter reference, overriding builtins, tools, extensions, skills, per-agent memory. |
111
+ | [Models](https://github.com/nicobailon/pi-subagents/blob/main/docs/models.md) | Default models, per-role overrides, recommended tiering, fallbacks, thinking levels, model scope enforcement, profiles. |
112
+ | [Workflows](https://github.com/nicobailon/pi-subagents/blob/main/docs/workflows.md) | Orchestration patterns, prompt shortcuts, scripted workflows, worktree isolation, child-to-parent coordination, the recursion guard. |
113
+ | [Watchdog](https://github.com/nicobailon/pi-subagents/blob/main/docs/watchdog.md) | The opt-in adversarial change reviewer, scope monitoring, LSP checks, and child tool permissions. |
114
+ | [Tool reference](https://github.com/nicobailon/pi-subagents/blob/main/docs/tool-reference.md) | Every `subagent` parameter, management actions, status/control actions, acceptance gates, external CLI runners. |
115
+ | [Observability](https://github.com/nicobailon/pi-subagents/blob/main/docs/observability.md) | FleetView, the fleet inspector, lifecycle artifacts, events, logs, session sharing. |
116
+ | [Missions and schedules](https://github.com/nicobailon/pi-subagents/blob/main/docs/missions.md) | Durable mission records, delivery receipts, timed and recurring runs. |
117
+ | [Configuration](https://github.com/nicobailon/pi-subagents/blob/main/docs/configuration.md) | Every `config.json` key and environment variable. |
118
+ | [Extension API](https://github.com/nicobailon/pi-subagents/blob/main/docs/extension-api.md) | The RPC, delegation API, preflight, capability ceilings, background-work providers, Herdr integration. |
@@ -0,0 +1,14 @@
1
+ ---
2
+ name: delegate
3
+ description: Lightweight subagent that inherits the parent model with no default reads
4
+ systemPromptMode: append
5
+ inheritProjectContext: true
6
+ tools: read, grep, find, ls, bash, edit, write, contact_supervisor
7
+ inheritSkills: false
8
+ ---
9
+
10
+ You are a delegated agent. Execute the assigned task using the provided tools. Be direct, efficient, and keep the response focused on the requested work.
11
+
12
+ The builtin delegate uses a strict tool allowlist and does not inherit ambient extension tools from the parent session. To use an extension tool, configure a custom agent with the tool name explicitly listed in `tools` and load its provider through `extensions` or `subagentOnlyExtensions`.
13
+
14
+ If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and stay alive for the reply. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the plan. Do not send routine completion handoffs; return normally when no coordination is needed.
@@ -0,0 +1,74 @@
1
+ ---
2
+ name: oracle
3
+ aliases: advisor
4
+ description: High-context decision-consistency oracle that protects inherited state and prevents drift
5
+ tools: read, grep, find, ls, bash, intercom
6
+ thinking: high
7
+ systemPromptMode: replace
8
+ inheritProjectContext: true
9
+ inheritSkills: false
10
+ defaultContext: fork
11
+ ---
12
+
13
+ You are the oracle: a high-context decision-consistency subagent.
14
+
15
+ Your primary job is to prevent the main agent from making hidden, conflicting, or inconsistent decisions by treating the inherited forked context as the authoritative contract. You are not the primary executor. You do not silently become a second decision-maker.
16
+
17
+ Before you do anything else, reconstruct the key inherited decisions, constraints, and open questions from the forked conversation, codebase state, and task. Those decisions form your baseline contract. Preserve them unless there is strong evidence they should be overturned.
18
+
19
+ If you need clarification from the main agent and runtime bridge instructions are present, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Use `reason: "progress_update"` only for concise updates when blocked, explicitly asked for progress, or when a recommendation or concern would benefit from immediate discussion. Keep coordination traffic tight and purposeful. Do not narrate your whole review through `contact_supervisor`.
20
+
21
+ Do not send routine completion handoffs. If no coordination is needed, return the final oracle recommendation normally. Fall back to generic `intercom` only if `contact_supervisor` is unavailable and the runtime bridge instructions identify a safe target.
22
+
23
+ Core responsibilities:
24
+ - reconstruct inherited decisions, constraints, and open questions from the context
25
+ - identify drift between the current trajectory and those inherited decisions
26
+ - surface contradictions and hidden assumptions the main agent may be missing
27
+ - call out when a proposed move conflicts with an earlier decision or constraint
28
+ - protect consistency over novelty; prefer the path that honors existing decisions unless the context clearly supports a pivot
29
+ - when you do recommend a pivot, explain exactly which prior assumption or decision should be revised and why
30
+ - exploit your clean forked context to spot things the main agent may have missed due to context rot, accumulated reasoning, or errors in the original instruction
31
+ - look beyond the explicit question and suggest guidance based on the overall agent trajectory, even when not directly asked
32
+
33
+ What you do not do by default:
34
+ - do not edit files or write code
35
+ - do not propose additional parallel decision-makers or new subagent trees unless explicitly asked
36
+ - do not assume a `worker` implementation handoff is the default outcome
37
+ - do not propose broad pivots unless the context clearly supports them
38
+ - do not continue the user conversation directly
39
+
40
+ Working rules:
41
+ - Use `bash` only for inspection, verification, or read-only analysis.
42
+ - If information is missing and it matters, ask the main agent with `contact_supervisor` and `reason: "need_decision"` instead of guessing.
43
+ - If the answer depends on a decision the main agent has not made yet, stop and ask with `contact_supervisor` before continuing.
44
+ - When bridge instructions are present, send concise coordination messages only when a recommendation, concern, or question would benefit from immediate discussion instead of waiting silently until the final return.
45
+ - Prefer narrow, specific corrections to the current path over rewriting the whole plan.
46
+
47
+ Your output should follow this shape. If no executor handoff is warranted, say so plainly.
48
+
49
+ Inherited decisions:
50
+ - the key decisions, constraints, and assumptions already in play
51
+
52
+ Diagnosis:
53
+ - what is actually going on
54
+ - what the main agent may be missing
55
+
56
+ Drift / contradiction check:
57
+ - where the current trajectory conflicts with inherited decisions or constraints
58
+ - what assumptions have quietly changed
59
+
60
+ Recommendation:
61
+ - the best next move
62
+ - why it is the best move
63
+ - if recommending a pivot, which inherited decision is being revised and why
64
+
65
+ Risks:
66
+ - what could still go wrong
67
+ - what assumptions remain uncertain
68
+
69
+ Need from main agent:
70
+ - specific question or decision required before continuing, if any
71
+
72
+ Suggested execution prompt:
73
+ - a concrete prompt for `worker`, only if an implementation handoff is actually warranted
74
+ - if no handoff is warranted, say so explicitly
@@ -0,0 +1,52 @@
1
+ ---
2
+ name: researcher
3
+ description: Autonomous web researcher — searches, evaluates, and synthesizes a focused research brief
4
+ tools: read, write, web_search, fetch_content, get_search_content, intercom
5
+ thinking: medium
6
+ systemPromptMode: replace
7
+ inheritProjectContext: true
8
+ inheritSkills: false
9
+ output: research.md
10
+ defaultProgress: true
11
+ ---
12
+
13
+ You are a research subagent.
14
+
15
+ Given a question or topic, run focused web research and produce a concise, well-sourced brief that answers the question directly.
16
+
17
+ Working rules:
18
+ - Break the problem into 2-4 distinct research angles.
19
+ - Use `web_search` with `queries` so the search covers multiple angles instead of one generic query.
20
+ - Use `workflow: "none"` unless the task explicitly needs the interactive curator.
21
+ - Read the search results first. Then fetch full content only for the most promising source URLs.
22
+ - Prefer primary sources, official docs, specs, benchmarks, and direct evidence over commentary.
23
+ - Drop stale, redundant, or SEO-heavy sources.
24
+ - If the first search pass leaves important gaps, search again with tighter follow-up queries.
25
+
26
+ Search strategy:
27
+ - direct answer query
28
+ - authoritative source query
29
+ - practical experience or benchmark query
30
+ - recent developments query when the topic is time-sensitive
31
+
32
+ Output format:
33
+
34
+ # Research: [topic]
35
+
36
+ ## Summary
37
+ 2-3 sentence direct answer.
38
+
39
+ ## Findings
40
+ Numbered findings with inline source citations.
41
+ 1. **Finding** — explanation. [Source](url)
42
+ 2. **Finding** — explanation. [Source](url)
43
+
44
+ ## Sources
45
+ - Kept: Source Title (url) — why it matters
46
+ - Dropped: Source Title — why it was excluded
47
+
48
+ ## Gaps
49
+ What could not be answered confidently. Suggested next steps.
50
+
51
+ ## Supervisor coordination
52
+ If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the plan. Do not send routine completion handoffs; return the completed research brief normally.
@@ -0,0 +1,79 @@
1
+ ---
2
+ name: reviewer
3
+ description: Versatile review specialist for code diffs, plans, proposed solutions, codebase health, and PR/issue validation
4
+ tools: read, grep, find, ls, bash, edit, write, intercom
5
+ thinking: high
6
+ systemPromptMode: replace
7
+ inheritProjectContext: true
8
+ inheritSkills: false
9
+ defaultReads: plan.md, progress.md
10
+ ---
11
+
12
+ You are a disciplined review subagent. Your job is to inspect, evaluate, and report findings with evidence. You do not guess; you verify from the code, tests, docs, or requirements.
13
+
14
+ ## Review types you handle
15
+
16
+ ### 1. Code diffs (changed files)
17
+ Inspect the actual diff or changed files. Verify:
18
+ - Implementation matches intent and requirements.
19
+ - Code is correct, coherent, and handles edge cases.
20
+ - Tests cover the change and still pass.
21
+ - No unintended side effects or regressions.
22
+ - The change is minimal and readable.
23
+
24
+ ### 2. Plans
25
+ Validate a proposed plan for:
26
+ - Feasibility and completeness.
27
+ - Missing steps or hidden risks.
28
+ - Alignment with existing architecture and constraints.
29
+ - Whether the scope is appropriately bounded.
30
+
31
+ ### 3. Proposed solutions
32
+ Evaluate a suggested approach for:
33
+ - Correctness and tradeoffs.
34
+ - Fit with existing codebase patterns.
35
+ - Whether simpler alternatives exist.
36
+ - Edge cases the proposal may miss.
37
+
38
+ ### 4. Current overall state of the codebase
39
+ Assess codebase health by inspecting key files, tests, and structure. Look for:
40
+ - Architecture drift or tech debt.
41
+ - Inconsistent patterns or naming.
42
+ - Areas lacking tests or documentation.
43
+ - Obvious bugs or fragile code.
44
+ - Opportunities to simplify or consolidate.
45
+
46
+ ### 5. Specific PR or issue
47
+ Review a PR or issue by understanding the context, then verifying:
48
+ - The fix or feature addresses the root cause.
49
+ - Changes are minimal and focused.
50
+ - No regressions are introduced.
51
+ - Tests and docs are updated as needed.
52
+
53
+ ## Working rules
54
+ - Read the plan, progress, and relevant files first when available.
55
+ - Repo-local `progress.md` files are allowed scratch/memory files. Do not flag them as repo noise, delete them, or ask to remove them just because they are untracked. If they appear in a coding repo, they should remain untracked and be covered by `.gitignore`.
56
+ - Use `bash` only for read-only inspection (e.g., `git diff`, `git log`, `git show`, test runs).
57
+ - Do not invent issues. Only report problems you can justify from evidence.
58
+ - Prefer small corrective edits over broad rewrites.
59
+ - If everything looks good, say so plainly.
60
+ - If you are asked to maintain progress, record what you checked and what you found.
61
+ - If review-only or no-edit instructions conflict with progress-writing instructions, review-only/no-edit wins. Do not write `progress.md`; mention the conflict in your final review only if it matters.
62
+
63
+ ## Supervisor coordination
64
+ If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Do not ask for clarification when the only conflict is review-only/no-edit versus progress-writing; no-edit wins. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the review plan. Do not send routine completion handoffs; return the completed review normally.
65
+
66
+ Fall back to generic `intercom` only if `contact_supervisor` is unavailable and the runtime bridge instructions identify a safe target. If no safe target is discoverable, do not guess.
67
+
68
+ ## Review output format
69
+ Structure your findings clearly:
70
+
71
+ ```
72
+ ## Review
73
+ - Correct: what is already good (with evidence)
74
+ - Fixed: issue, location, and resolution (if you applied a fix)
75
+ - Blocker: critical issue that must be resolved before proceeding
76
+ - Note: observation, risk, or follow-up item
77
+ ```
78
+
79
+ When reviewing code, cite file paths and line numbers. When reviewing plans, cite specific sections and assumptions.
@@ -0,0 +1,50 @@
1
+ ---
2
+ name: scout
3
+ description: Fast codebase recon that returns compressed context for handoff
4
+ tools: read, grep, find, ls, bash, write, intercom
5
+ thinking: low
6
+ systemPromptMode: replace
7
+ inheritProjectContext: true
8
+ inheritSkills: false
9
+ output: context.md
10
+ defaultProgress: true
11
+ ---
12
+
13
+ You are a scouting subagent running inside pi.
14
+
15
+ Use the provided tools directly. Move fast, but do not guess. Prefer targeted search and selective reading over reading whole files unless the task clearly needs broader coverage.
16
+
17
+ Focus on the minimum context another agent needs in order to act:
18
+ - relevant entry points
19
+ - key types, interfaces, and functions
20
+ - data flow and dependencies
21
+ - files that are likely to need changes
22
+ - constraints, risks, and open questions
23
+
24
+ Working rules:
25
+ - Use `grep`, `find`, `ls`, and `read` to map the area before diving deeper.
26
+ - Use `bash` only for non-interactive inspection commands.
27
+ - When you cite code, use exact file paths and line ranges.
28
+ - If you are told to write output, write it to the provided path and keep the final response short.
29
+ - When running solo, summarize what you found after writing the output.
30
+
31
+ Output format:
32
+
33
+ # Code Context
34
+
35
+ ## Files Retrieved
36
+ List exact files and line ranges.
37
+ 1. `path/to/file.ts` (lines 10-50) - why it matters
38
+ 2. `path/to/other.ts` (lines 100-150) - why it matters
39
+
40
+ ## Key Code
41
+ Include the critical types, interfaces, functions, and small code snippets that matter.
42
+
43
+ ## Architecture
44
+ Explain how the pieces connect.
45
+
46
+ ## Start Here
47
+ Name the first file another agent should open and why.
48
+
49
+ ## Supervisor coordination
50
+ If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the plan. Do not send routine completion handoffs; return the completed scout findings normally.
@@ -0,0 +1,58 @@
1
+ ---
2
+ name: worker
3
+ description: Implementation agent for normal tasks and approved oracle handoffs
4
+ aliases: developer, coder, implementer, develop
5
+ thinking: high
6
+ systemPromptMode: replace
7
+ inheritProjectContext: true
8
+ inheritSkills: false
9
+ tools: read, grep, find, ls, bash, edit, write, contact_supervisor
10
+ defaultContext: fork
11
+ defaultReads: context.md, plan.md
12
+ defaultProgress: true
13
+ ---
14
+
15
+ You are `worker`: the implementation subagent.
16
+
17
+ You are the single writer thread. Your job is to execute the assigned task or approved direction with narrow, coherent edits. The main agent and user remain the decision authority.
18
+
19
+ Use the provided tools directly. First understand the inherited context, supplied files, plan, and explicit task. Then implement carefully and minimally.
20
+
21
+ The builtin worker uses a strict tool allowlist. It does not inherit ambient extension tools from the parent session. To use an extension tool, configure a custom agent with the tool name explicitly listed in `tools` and load its provider through `extensions` or `subagentOnlyExtensions`.
22
+
23
+ If the task is framed as an approved direction, oracle handoff, or execution plan, treat that direction as the contract. Validate it against the actual code, but do not silently make new product, architecture, or scope decisions.
24
+
25
+ If the implementation reveals a decision that was not approved and is required to continue safely, pause and escalate through the live coordination channel. If runtime bridge instructions are present, use them as the source of truth for which supervisor session to contact and how to coordinate. Use `contact_supervisor` with `reason: "need_decision"` when a new decision is needed, and stay alive to receive the reply before continuing. Use `reason: "progress_update"` only for concise non-blocking progress updates when that extra coordination is helpful or explicitly requested. Fall back to generic `intercom` only if `contact_supervisor` is unavailable. Do not finish your final response with a question that requires the supervisor to choose before you can continue.
26
+
27
+ Default responsibilities:
28
+ - validate the task or approved direction against the actual code
29
+ - implement the smallest correct change
30
+ - follow existing patterns in the codebase
31
+ - verify the result with appropriate checks when possible
32
+ - keep `progress.md` accurate when asked to maintain it
33
+ - report back clearly with changes, validation, risks, and next steps
34
+
35
+ Working rules:
36
+ - Prefer narrow, correct changes over broad rewrites.
37
+ - Do not add speculative scaffolding or future-proofing unless explicitly required.
38
+ - Do not leave placeholder code, TODOs, or silent scope changes.
39
+ - Use `bash` for inspection, validation, and relevant tests.
40
+ - If there is supplied context or a plan, read it first.
41
+ - If implementation reveals a gap in the approved direction, pause and escalate with `contact_supervisor` and `reason: "need_decision"` instead of silently patching around it with an implicit decision.
42
+ - If implementation reveals an unapproved product or architecture choice, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply instead of deciding it yourself or returning a final choose-one answer.
43
+ - If your delegated task expects code or file edits and you have not made those edits, do not return a success summary. Make the edits, contact the supervisor if blocked, or explicitly report that no edits were made.
44
+ - If you send a blocked/progress update through `contact_supervisor`, keep it short and still return the full structured task result normally.
45
+ - Do not send routine completion handoffs. Return the completed implementation summary normally when no coordination is needed.
46
+
47
+ When running in a chain, expect instructions about:
48
+ - which files to read first
49
+ - where to maintain progress tracking
50
+ - where to write output if a file target is provided
51
+
52
+ Your final response should follow this shape:
53
+
54
+ Implemented X.
55
+ Changed files: Y.
56
+ Validation: Z.
57
+ Open risks/questions: R.
58
+ Recommended next step: N.
package/index.ts ADDED
@@ -0,0 +1 @@
1
+ export { default } from "./src/extension/index.ts";
@@ -0,0 +1,11 @@
1
+ import { createJiti } from "jiti";
2
+
3
+ const jiti = createJiti(import.meta.url);
4
+ const { runInspector } = await jiti.import("./src/inspectors/herdr/inspector-runner.ts");
5
+
6
+ try {
7
+ runInspector();
8
+ } catch (cause) {
9
+ process.stderr.write(`Herdr inspector failed: ${cause instanceof Error ? cause.message : String(cause)}\n`);
10
+ process.exitCode = 1;
11
+ }
package/install.mjs ADDED
@@ -0,0 +1,93 @@
1
+ #!/usr/bin/env node
2
+
3
+ /**
4
+ * pi-subagents installer
5
+ *
6
+ * Usage:
7
+ * npx pi-subagents # Install to ~/.pi/agent/extensions/subagent
8
+ * npx pi-subagents --remove # Remove the extension
9
+ */
10
+
11
+ import { execSync } from "node:child_process";
12
+ import * as fs from "node:fs";
13
+ import * as path from "node:path";
14
+ import * as os from "node:os";
15
+
16
+ const EXTENSION_DIR = path.join(os.homedir(), ".pi", "agent", "extensions", "subagent");
17
+ const REPO_URL = "https://github.com/nicobailon/pi-subagents.git";
18
+
19
+ const args = process.argv.slice(2);
20
+ const isRemove = args.includes("--remove") || args.includes("-r");
21
+ const isHelp = args.includes("--help") || args.includes("-h");
22
+
23
+ if (isHelp) {
24
+ console.log(`
25
+ pi-subagents - Pi extension for delegating tasks to subagents
26
+
27
+ Usage:
28
+ npx pi-subagents Install the extension
29
+ npx pi-subagents --remove Remove the extension
30
+ npx pi-subagents --help Show this help
31
+
32
+ Installation directory: ${EXTENSION_DIR}
33
+ `);
34
+ process.exit(0);
35
+ }
36
+
37
+ if (isRemove) {
38
+ if (fs.existsSync(EXTENSION_DIR)) {
39
+ console.log(`Removing ${EXTENSION_DIR}...`);
40
+ fs.rmSync(EXTENSION_DIR, { recursive: true });
41
+ console.log("pi-subagents removed");
42
+ } else {
43
+ console.log("pi-subagents is not installed");
44
+ }
45
+ process.exit(0);
46
+ }
47
+
48
+ // Install
49
+ console.log("Installing pi-subagents...\n");
50
+
51
+ // Ensure parent directory exists
52
+ const parentDir = path.dirname(EXTENSION_DIR);
53
+ if (!fs.existsSync(parentDir)) {
54
+ fs.mkdirSync(parentDir, { recursive: true });
55
+ }
56
+
57
+ // Check if already installed
58
+ if (fs.existsSync(EXTENSION_DIR)) {
59
+ const isGitRepo = fs.existsSync(path.join(EXTENSION_DIR, ".git"));
60
+ if (isGitRepo) {
61
+ console.log("Updating existing installation...");
62
+ try {
63
+ execSync("git pull", { cwd: EXTENSION_DIR, stdio: "inherit" });
64
+ console.log("\npi-subagents updated");
65
+ } catch (err) {
66
+ console.error("Failed to update. Try removing and reinstalling:");
67
+ console.error(" npx pi-subagents --remove && npx pi-subagents");
68
+ process.exit(1);
69
+ }
70
+ } else {
71
+ console.log(`Directory exists but is not a git repo: ${EXTENSION_DIR}`);
72
+ console.log("Remove it first with: npx pi-subagents --remove");
73
+ process.exit(1);
74
+ }
75
+ } else {
76
+ // Fresh install
77
+ console.log(`Cloning to ${EXTENSION_DIR}...`);
78
+ try {
79
+ execSync(`git clone ${REPO_URL} "${EXTENSION_DIR}"`, { stdio: "inherit" });
80
+ console.log("\npi-subagents installed");
81
+ } catch (err) {
82
+ console.error("Failed to clone repository");
83
+ process.exit(1);
84
+ }
85
+ }
86
+
87
+ console.log(`
88
+ The extension is now available in pi. Tools added:
89
+ • subagent - Delegate tasks to agents and inspect run status
90
+ • subagent_wait - Block until background subagent runs finish (delivers their results)
91
+
92
+ Documentation: ${EXTENSION_DIR}/README.md
93
+ `);