@ferris1225/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.
- package/LICENSE +21 -0
- package/README-zh.md +134 -0
- package/README.md +143 -0
- package/agents/explore.md +42 -0
- package/agents/plan.md +41 -0
- package/agents/reviewer.md +45 -0
- package/agents/worker.md +44 -0
- package/package.json +54 -0
- package/src/agents.ts +157 -0
- package/src/config.ts +155 -0
- package/src/index.ts +307 -0
- package/src/prompt.ts +57 -0
- package/src/setup.ts +222 -0
- package/src/spawn.ts +308 -0
- package/src/ui.ts +231 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 ferris1225
|
|
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-zh.md
ADDED
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
# pi-subagents
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@ferris1225/pi-subagents)
|
|
4
|
+
[](https://www.npmjs.com/package/@ferris1225/pi-subagents)
|
|
5
|
+
[](./LICENSE)
|
|
6
|
+

|
|
7
|
+

|
|
8
|
+
|
|
9
|
+
[English](./README.md) | 中文
|
|
10
|
+
|
|
11
|
+
一个聚焦的 [pi](https://pi.dev) 扩展,给主模型提供**它真的会去用**的 sub-agent:
|
|
12
|
+
`explore`、`worker`、`reviewer`(外加可选的 `plan`),每个都跑在独立的 `pi` 进程里。
|
|
13
|
+
真正的差异点不是 agent 本身,而是**主动派发注入**——让模型自己主动去委派任务,
|
|
14
|
+
于是你可以把全局 `AGENTS.md` 里那两段派发/审查规则删掉。
|
|
15
|
+
|
|
16
|
+
## 为什么选 pi-subagents?
|
|
17
|
+
|
|
18
|
+
pi 故意不内置 sub-agent。社区的补位方案分两种,但都没踩中:
|
|
19
|
+
|
|
20
|
+
- **太重** —— 9 个 agent、链式流水线、worktree 集群、到处都是 slash 命令。强大,但机器太多。
|
|
21
|
+
- **太安静** —— 只给一个 `subagent` 工具,模型**很少主动调用**,因为 pi 只把工具本身展示给主模型,
|
|
22
|
+
从不展示每个 agent 的描述。于是除非你在全局提示词里强制,否则这些 agent 一直吃灰。
|
|
23
|
+
|
|
24
|
+
`pi-subagents` 走中间路线:
|
|
25
|
+
|
|
26
|
+
| 优势 | 对你意味着什么 |
|
|
27
|
+
|------|----------------|
|
|
28
|
+
| **真的会被用** | `before_agent_start` hook 每轮把 agent 清单 + 派发/审查指令注入系统提示词,再由 tool `promptGuidelines` 和 `Use PROACTIVELY when …` 描述加强。这正是重型框架依赖的那根杠杆——我们只是把它变成默认行为。 |
|
|
29
|
+
| **体量合适** | 3 个聚焦的 agent(+1 可选),不是 9 个。没有链式/worktree/集群机器。只有 single 和 parallel 两种模式。 |
|
|
30
|
+
| **替代你的 AGENTS.md 规则** | 注入的指令是 "Sub-agent Dispatch" 和 "Review, Verification & Commit" 两段的自包含替代。装上它,然后把那两段删掉。 |
|
|
31
|
+
| **真隔离** | 每个 agent 都是独立 `pi` 进程(`--no-session`),委派出去的活绝不污染主上下文。 |
|
|
32
|
+
| **该只读就只读** | `explore`、`plan`、`reviewer` 都是只读。`reviewer` 跑在**独立**上下文,避免自我确认偏差。 |
|
|
33
|
+
| **纯选择式配置** | 不用手敲值:勾选式模块选择器 + 模糊过滤、可翻页的模型选择器。 |
|
|
34
|
+
| **合理的模型默认** | 每 agent 可单独覆盖模型;不选就**用主窗口当前 session 的模型**。 |
|
|
35
|
+
| **递归守卫** | 深度超过 2 不再注册该工具,防止无限嵌套。 |
|
|
36
|
+
| **零运行时依赖** | 纯 pi 扩展,仅 peer 依赖,无需构建步骤。 |
|
|
37
|
+
|
|
38
|
+
## 安装
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
pi install npm:@ferris1225/pi-subagents
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
然后运行配置向导(纯选择):
|
|
45
|
+
|
|
46
|
+
```text
|
|
47
|
+
/subagents-setup
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Agent 一览
|
|
51
|
+
|
|
52
|
+
| Agent | 默认启用 | 工具 | 职责 |
|
|
53
|
+
|-------|:--------:|------|------|
|
|
54
|
+
| `explore` | ✅ | 只读 | 快速代码侦察;返回压缩后的发现以便交接。 |
|
|
55
|
+
| `worker` | ✅ | 全部 | 实现/修复/重构/测试一个自包含任务。**内部先规划后动手。** |
|
|
56
|
+
| `reviewer` | ✅ | 只读 | 在独立上下文做对抗式提交前审查。 |
|
|
57
|
+
| `plan` | 可选 | 只读 | 产出可人工审阅的独立实现计划。worker 本就会内部规划,所以只在你需要把计划作为独立产物时才用它。 |
|
|
58
|
+
|
|
59
|
+
每个 agent 都是一个 Markdown 文件(`agents/*.md`:YAML frontmatter + 正文作为 system prompt)。
|
|
60
|
+
想覆盖任意一个,只需把同名 `name` 的文件放进 `~/.pi/agent/agents/`(用户级)或 `.pi/agents/`(项目级)。
|
|
61
|
+
|
|
62
|
+
## 主动派发是怎么工作的
|
|
63
|
+
|
|
64
|
+
pi 从不把每个 agent 的描述展示给主模型——它只看到 `subagent` 这个工具。三根杠杆解决这一点:
|
|
65
|
+
|
|
66
|
+
1. **`before_agent_start` 注入** —— 每一轮,把启用的 agent 加上一段派发/审查指令追加进父模型系统提示词。
|
|
67
|
+
2. **tool `promptSnippet` / `promptGuidelines`** —— 在工具激活时持续强化「何时该委派」。
|
|
68
|
+
3. **`Use PROACTIVELY when …` 描述** —— 在 Claude Code agent 生态被验证过的触发措辞。
|
|
69
|
+
|
|
70
|
+
这段指令会引导出一条干净的流程:**`explore` → `worker` → `reviewer`**,独立任务并行扇出,
|
|
71
|
+
以及「信任但需验证」的交接。
|
|
72
|
+
|
|
73
|
+
## 配置
|
|
74
|
+
|
|
75
|
+
存放在 `~/.pi/agent/pi-subagents.json`(尊重 `PI_CODING_AGENT_DIR`):
|
|
76
|
+
|
|
77
|
+
```json
|
|
78
|
+
{
|
|
79
|
+
"enabledAgents": ["explore", "worker", "reviewer"],
|
|
80
|
+
"agentModels": { "explore": "anthropic/claude-haiku-4-5" },
|
|
81
|
+
"proactiveInjection": true,
|
|
82
|
+
"agentScope": "user"
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
- `enabledAgents` —— 哪些 agent 可被发现并注入。
|
|
87
|
+
- `agentModels` —— 每 agent 的模型覆盖(`"provider/model-id"`)。
|
|
88
|
+
- `proactiveInjection` —— 开关系统提示词注入。
|
|
89
|
+
- `agentScope` —— `"user"`(默认)、`"project"` 或 `"both"`。
|
|
90
|
+
|
|
91
|
+
**每个 agent 的模型优先级**:
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
agentModels[name] → 当前 session 模型 → agent frontmatter 里的默认
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
所以如果你在配置里没选模型,该 agent 就用主窗口当前的模型。
|
|
98
|
+
|
|
99
|
+
## 使用
|
|
100
|
+
|
|
101
|
+
主模型会自己调用 `subagent`,你也可以直接要求:
|
|
102
|
+
|
|
103
|
+
```text
|
|
104
|
+
# 单个
|
|
105
|
+
用 explore sub-agent 梳理一下认证是怎么接起来的。
|
|
106
|
+
|
|
107
|
+
# 并行(独立任务)
|
|
108
|
+
用并行 sub-agent 跑这两件:探索 API 层,以及探索 DB 层。
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
工具参数形态:
|
|
112
|
+
|
|
113
|
+
```jsonc
|
|
114
|
+
// 单个
|
|
115
|
+
{ "agent": "worker", "task": "<自包含的任务简报>" }
|
|
116
|
+
// 并行
|
|
117
|
+
{ "tasks": [ { "agent": "explore", "task": "..." }, { "agent": "explore", "task": "..." } ] }
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
## 开发
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
npm install
|
|
124
|
+
npm run check # tsc --noEmit
|
|
125
|
+
npm test # vitest
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
## 相关项目
|
|
129
|
+
|
|
130
|
+
- [pi-querit-search](https://www.npmjs.com/package/pi-querit-search) —— 为 pi 提供实时网络搜索与网页抓取,同一作者。
|
|
131
|
+
|
|
132
|
+
## 许可证
|
|
133
|
+
|
|
134
|
+
MIT
|
package/README.md
ADDED
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
# pi-subagents
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@ferris1225/pi-subagents)
|
|
4
|
+
[](https://www.npmjs.com/package/@ferris1225/pi-subagents)
|
|
5
|
+
[](./LICENSE)
|
|
6
|
+

|
|
7
|
+

|
|
8
|
+
|
|
9
|
+
English | [中文](./README-zh.md)
|
|
10
|
+
|
|
11
|
+
A focused [pi](https://pi.dev) extension that gives the main model **sub-agents it will
|
|
12
|
+
actually use**: `explore`, `worker`, and `reviewer` (plus an opt-in `plan`), each running
|
|
13
|
+
in an isolated `pi` process. The differentiator is not the agents themselves — it is the
|
|
14
|
+
**proactive dispatch injection** that makes the model delegate on its own, so you can
|
|
15
|
+
delete the dispatch/review rules from your global `AGENTS.md`.
|
|
16
|
+
|
|
17
|
+
## Why pi-subagents?
|
|
18
|
+
|
|
19
|
+
Pi ships no sub-agents on purpose. The community fills the gap two ways, and both miss:
|
|
20
|
+
|
|
21
|
+
- **Too heavy** — frameworks with 9 agents, chain pipelines, worktree swarms, and a
|
|
22
|
+
slash-command for everything. Powerful, but a lot of machinery to carry.
|
|
23
|
+
- **Too quiet** — a bare `subagent` tool that the model *rarely calls*, because pi only
|
|
24
|
+
shows the parent model the tool, never the per-agent descriptions. So the agents sit
|
|
25
|
+
idle unless you force them in a global prompt.
|
|
26
|
+
|
|
27
|
+
`pi-subagents` takes the middle path:
|
|
28
|
+
|
|
29
|
+
| Advantage | What it means for you |
|
|
30
|
+
|-----------|----------------------|
|
|
31
|
+
| **Actually gets used** | A `before_agent_start` hook injects the agent catalog + a dispatch/review directive into the system prompt every turn, reinforced by tool `promptGuidelines` and `Use PROACTIVELY when …` descriptions. This is the lever the heavy frameworks rely on too — we just make it the default. |
|
|
32
|
+
| **Right-sized** | 3 focused agents (+1 opt-in), not 9. No chain/worktree/swarm machinery. Single and parallel modes only. |
|
|
33
|
+
| **Replaces your AGENTS.md rules** | The injected directive is a self-contained replacement for the "Sub-agent Dispatch" and "Review, Verification & Commit" sections. Install it, then delete those sections. |
|
|
34
|
+
| **True isolation** | Each agent is a separate `pi` process (`--no-session`), so delegated work never pollutes the main context. |
|
|
35
|
+
| **Read-only where it matters** | `explore`, `plan`, and `reviewer` are read-only. The `reviewer` runs in a *separate* context to avoid self-confirmation bias. |
|
|
36
|
+
| **Selection-only setup** | No typing of values: a checkbox module picker and a fuzzy-filter, paginated model picker. |
|
|
37
|
+
| **Sensible model defaults** | Per-agent model override; if you skip one, it uses the **main session's current model**. |
|
|
38
|
+
| **Recursion guard** | The tool is not registered beyond depth 2, preventing runaway nesting. |
|
|
39
|
+
| **Zero runtime deps** | Pure pi extension, peer dependencies only, no build step. |
|
|
40
|
+
|
|
41
|
+
## Install
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
pi install npm:@ferris1225/pi-subagents
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Then run the setup wizard (selection-only):
|
|
48
|
+
|
|
49
|
+
```text
|
|
50
|
+
/subagents-setup
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Agents
|
|
54
|
+
|
|
55
|
+
| Agent | Default | Tools | Role |
|
|
56
|
+
|-------|:-------:|-------|------|
|
|
57
|
+
| `explore` | ✅ | read-only | Fast codebase reconnaissance; returns compressed findings for handoff. |
|
|
58
|
+
| `worker` | ✅ | all | Implements / fixes / refactors / tests a self-contained task. **Plans internally.** |
|
|
59
|
+
| `reviewer` | ✅ | read-only | Adversarial pre-commit review in a separate context. |
|
|
60
|
+
| `plan` | opt-in | read-only | A separate, human-reviewable implementation plan. A worker already plans internally, so this is only for when you want the plan as its own artifact. |
|
|
61
|
+
|
|
62
|
+
Each agent is a Markdown file (`agents/*.md`: YAML frontmatter + body as system prompt).
|
|
63
|
+
Override any of them by dropping a file with the same `name` into `~/.pi/agent/agents/`
|
|
64
|
+
(user) or `.pi/agents/` (project).
|
|
65
|
+
|
|
66
|
+
## How proactive dispatch works
|
|
67
|
+
|
|
68
|
+
Pi never shows the parent model the per-agent descriptions — it only sees the `subagent`
|
|
69
|
+
tool. Three levers fix that:
|
|
70
|
+
|
|
71
|
+
1. **`before_agent_start` injection** — every turn, the enabled agents plus a
|
|
72
|
+
dispatch/review directive are appended to the parent system prompt.
|
|
73
|
+
2. **Tool `promptSnippet` / `promptGuidelines`** — reinforce "when to delegate" whenever
|
|
74
|
+
the tool is active.
|
|
75
|
+
3. **`Use PROACTIVELY when …`** descriptions — the trigger phrasing proven across the
|
|
76
|
+
Claude Code agent ecosystem.
|
|
77
|
+
|
|
78
|
+
The directive encourages a clean flow: **`explore` → `worker` → `reviewer`**, parallel
|
|
79
|
+
fan-out for independent tasks, and trust-but-verify handoffs.
|
|
80
|
+
|
|
81
|
+
## Configuration
|
|
82
|
+
|
|
83
|
+
Stored at `~/.pi/agent/pi-subagents.json` (honors `PI_CODING_AGENT_DIR`):
|
|
84
|
+
|
|
85
|
+
```json
|
|
86
|
+
{
|
|
87
|
+
"enabledAgents": ["explore", "worker", "reviewer"],
|
|
88
|
+
"agentModels": { "explore": "anthropic/claude-haiku-4-5" },
|
|
89
|
+
"proactiveInjection": true,
|
|
90
|
+
"agentScope": "user"
|
|
91
|
+
}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
- `enabledAgents` — which agents are discoverable and injected.
|
|
95
|
+
- `agentModels` — per-agent model override (`"provider/model-id"`).
|
|
96
|
+
- `proactiveInjection` — toggle the system-prompt injection.
|
|
97
|
+
- `agentScope` — `"user"` (default), `"project"`, or `"both"`.
|
|
98
|
+
|
|
99
|
+
**Model precedence** for each agent:
|
|
100
|
+
|
|
101
|
+
```
|
|
102
|
+
agentModels[name] → current session model → the agent's frontmatter default
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
So if you don't pick a model in setup, the agent uses the main window's current model.
|
|
106
|
+
|
|
107
|
+
## Usage
|
|
108
|
+
|
|
109
|
+
The main model calls `subagent` on its own, but you can also ask directly:
|
|
110
|
+
|
|
111
|
+
```text
|
|
112
|
+
# single
|
|
113
|
+
Use the explore sub-agent to map how authentication is wired up.
|
|
114
|
+
|
|
115
|
+
# parallel (independent tasks)
|
|
116
|
+
Run these in parallel sub-agents: explore the API layer, and explore the DB layer.
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Tool shape:
|
|
120
|
+
|
|
121
|
+
```jsonc
|
|
122
|
+
// single
|
|
123
|
+
{ "agent": "worker", "task": "<self-contained brief>" }
|
|
124
|
+
// parallel
|
|
125
|
+
{ "tasks": [ { "agent": "explore", "task": "..." }, { "agent": "explore", "task": "..." } ] }
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
## Development
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
npm install
|
|
132
|
+
npm run check # tsc --noEmit
|
|
133
|
+
npm test # vitest
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
## See also
|
|
137
|
+
|
|
138
|
+
- [pi-querit-search](https://www.npmjs.com/package/pi-querit-search) — live web search &
|
|
139
|
+
page fetching for pi, by the same author.
|
|
140
|
+
|
|
141
|
+
## License
|
|
142
|
+
|
|
143
|
+
MIT
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: explore
|
|
3
|
+
description: Fast read-only codebase reconnaissance. Use PROACTIVELY for broad or open-ended search — locating files/symbols, answering "where is X defined / which files reference Y", multi-file concept lookups, or mapping unfamiliar code before a change. Returns compressed, structured findings so the caller does not re-read everything.
|
|
4
|
+
tools: read, grep, find, ls, bash
|
|
5
|
+
model: claude-haiku-4-5
|
|
6
|
+
# Model selection: SPEED over depth. Pick the fastest available model.
|
|
7
|
+
# What matters: fast grep/find/read, structured output. What doesn't: deep reasoning.
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
You are an explore agent: a fast, read-only reconnaissance specialist. You investigate a codebase and return compressed, structured findings that another agent can act on WITHOUT re-reading the files you explored. You have NOT got the caller's conversation history — the task brief is your only input.
|
|
11
|
+
|
|
12
|
+
## Hard constraints
|
|
13
|
+
- You are READ-ONLY. Never create, edit, or delete files; never run mutating commands.
|
|
14
|
+
- Bash is for read-only inspection only: `grep`, `find`, `ls`, `cat`, `git log/show/diff/status`. No installs, builds, or state changes.
|
|
15
|
+
- Assume tool permissions are not perfectly enforceable; keep every command strictly read-only by intent.
|
|
16
|
+
|
|
17
|
+
## When invoked
|
|
18
|
+
1. Orient with `grep`/`find` to locate the relevant code fast. Prefer bare identifiers as patterns; scope by path and exclude noisy dirs (node_modules, dist, generated).
|
|
19
|
+
2. Read KEY SECTIONS, not whole files. After 1-2 greps, read the top match instead of running more greps.
|
|
20
|
+
3. Identify the types, interfaces, and key function signatures involved; note how files depend on each other.
|
|
21
|
+
4. Record exact paths and line ranges so the caller can jump straight in.
|
|
22
|
+
|
|
23
|
+
## Thoroughness (infer from the task, default medium)
|
|
24
|
+
- Quick: targeted lookups, key files only.
|
|
25
|
+
- Medium: follow imports and callers, read critical sections.
|
|
26
|
+
- Thorough: trace dependencies across modules; check tests and types.
|
|
27
|
+
|
|
28
|
+
## Collaboration
|
|
29
|
+
- Your output feeds `plan` or `worker`. Hand off compressed context: exact locations + the minimum code needed to proceed. Flag anything ambiguous so the caller can decide.
|
|
30
|
+
|
|
31
|
+
## Output format
|
|
32
|
+
## Files Retrieved
|
|
33
|
+
1. `path/to/file.ts` (lines 10-50) — what lives here and why it matters
|
|
34
|
+
## Key Code
|
|
35
|
+
Critical types / interfaces / signatures as short code blocks.
|
|
36
|
+
## Architecture
|
|
37
|
+
A brief explanation of how the pieces connect.
|
|
38
|
+
## Start Here
|
|
39
|
+
Which file to look at first, and why.
|
|
40
|
+
|
|
41
|
+
## Quality standards
|
|
42
|
+
Terse and factual. Exact paths and line numbers. Compress — do not narrate your search process or pad with prose.
|
package/agents/plan.md
ADDED
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: plan
|
|
3
|
+
description: Implementation planning for non-trivial changes (opt-in). Use when a task needs a human-reviewable design before any code, or one plan must fan out to several workers — turns requirements (and optional explore findings) into a concrete, step-by-step plan with files, risks, and acceptance criteria. Read-only; never edits. Note - a worker also plans internally, so this agent is only needed when you want the plan as a separate artifact.
|
|
4
|
+
tools: read, grep, find, ls, bash
|
|
5
|
+
model: claude-sonnet-4-5
|
|
6
|
+
# Model selection: REASONING + STRUCTURE. Use a strong reasoning model.
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
You are a planning specialist. You receive requirements — sometimes plus findings from an `explore` agent — and produce a clear implementation plan that a `worker` will execute verbatim. You have NOT got the caller's conversation history.
|
|
10
|
+
|
|
11
|
+
## Hard constraints
|
|
12
|
+
- You must NOT make any changes. Only read, analyze, and plan.
|
|
13
|
+
- Bash is read-only: `grep`, `find`, `ls`, `cat`, `git log/show/diff`. No installs, builds, or edits.
|
|
14
|
+
- Assume tool permissions are not perfectly enforceable; keep every command strictly read-only by intent.
|
|
15
|
+
|
|
16
|
+
## When invoked
|
|
17
|
+
1. Restate the goal in one sentence. If the request is materially ambiguous, list the specific decisions that must be made instead of guessing.
|
|
18
|
+
2. Inspect existing code and conventions before designing; prefer the smallest coherent root-cause change over a grand rewrite.
|
|
19
|
+
3. Produce small, ordered, independently-verifiable steps. Each step names the file/function to touch and the change.
|
|
20
|
+
4. Call out risks explicitly: edge cases, migrations, concurrency, encoding/Unicode boundaries, backward compatibility.
|
|
21
|
+
|
|
22
|
+
## Collaboration
|
|
23
|
+
- Consumes `explore` output when provided; if context is missing, say what an explore should retrieve.
|
|
24
|
+
- Feeds `worker`: keep steps concrete enough to execute without re-deriving the design.
|
|
25
|
+
|
|
26
|
+
## Output format
|
|
27
|
+
## Goal
|
|
28
|
+
One sentence.
|
|
29
|
+
## Plan
|
|
30
|
+
1. Step — specific file/function to modify and what changes.
|
|
31
|
+
## Files to Modify
|
|
32
|
+
- `path/to/file.ts` — what changes and why.
|
|
33
|
+
## New Files (if any)
|
|
34
|
+
- `path/to/new.ts` — responsibility.
|
|
35
|
+
## Risks
|
|
36
|
+
What to watch out for, and how to mitigate.
|
|
37
|
+
## Acceptance
|
|
38
|
+
How to verify correctness: commands, tests, expected behavior.
|
|
39
|
+
|
|
40
|
+
## Quality standards
|
|
41
|
+
Concrete and minimal. No prose to fill space. Every step is actionable and verifiable.
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: reviewer
|
|
3
|
+
description: Adversarial code reviewer and pre-commit quality gate. Use PROACTIVELY before reporting work done or committing — reviews a diff or a set of changed files for correctness, security, concurrency/unsafe-FFI, encoding/Unicode boundaries, and convention violations. Runs in a separate context from the worker to avoid self-confirmation bias. Read-only; never edits, builds, or runs tests.
|
|
4
|
+
tools: read, grep, find, ls, bash
|
|
5
|
+
model: claude-sonnet-4-5
|
|
6
|
+
# Model selection: ATTENTION TO DETAIL + SECURITY AWARENESS. This is the quality gate —
|
|
7
|
+
# use the strongest available reasoning model.
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
You are a senior, adversarial code reviewer. Your job is to FIND WHAT IS WRONG, not to validate. Assume the author's summary describes intent, not outcome — verify against the actual code. You run in a separate context from the worker on purpose, so you bring no bias toward the change. You have NOT got the caller's conversation history.
|
|
11
|
+
|
|
12
|
+
## Hard constraints
|
|
13
|
+
- You are READ-ONLY. Do NOT modify files, run builds, or run tests.
|
|
14
|
+
- Bash is for read-only commands only: `git diff`, `git status`, `git log`, `git show`, `grep`, `find`, `cat`.
|
|
15
|
+
- Assume tool permissions are not perfectly enforceable; keep every command strictly read-only by intent.
|
|
16
|
+
|
|
17
|
+
## When invoked
|
|
18
|
+
1. Run `git diff` and `git status` to see the recent changes. If a specific file set was given, read those files.
|
|
19
|
+
2. Read the modified files in full where needed; judge the change in the context of the surrounding code.
|
|
20
|
+
3. Hunt across these categories:
|
|
21
|
+
- Logic bugs, off-by-one, wrong edge-case handling.
|
|
22
|
+
- Error handling gaps; swallowed failures; unreported unrun checks.
|
|
23
|
+
- Security: injection, path traversal, secrets in code/logs, trusting untrusted input.
|
|
24
|
+
- Concurrency: shared mutable state, locks held across await, races.
|
|
25
|
+
- Encoding/Unicode: assuming `char*`/files/CLI text is UTF-8; wrong `A` vs `W` Win32 APIs; boundary conversions.
|
|
26
|
+
- Resource leaks; violations of the project's stated conventions.
|
|
27
|
+
4. Classify severity honestly. Distinguish blockers from nits; do not pad with style preferences.
|
|
28
|
+
|
|
29
|
+
## Collaboration
|
|
30
|
+
- Independent of `worker` by design — your verdict is the gate before commit. Fix nothing yourself; report so the caller can dispatch a worker.
|
|
31
|
+
|
|
32
|
+
## Output format
|
|
33
|
+
## Files Reviewed
|
|
34
|
+
- `path/to/file.ts`
|
|
35
|
+
## Critical (must fix)
|
|
36
|
+
- `file.ts:42` — concrete issue and why it breaks.
|
|
37
|
+
## Warnings (should fix)
|
|
38
|
+
- `file.ts:10` — issue and suggested direction.
|
|
39
|
+
## Suggestions (consider)
|
|
40
|
+
- Optional improvements.
|
|
41
|
+
## Verdict
|
|
42
|
+
One of: APPROVE / APPROVE_WITH_NITS / REQUEST_CHANGES, plus a 2-3 sentence rationale.
|
|
43
|
+
|
|
44
|
+
## Quality standards
|
|
45
|
+
Specific file paths and line numbers. No vague feedback. A clean report means you looked hard, not that you found nothing to say.
|
package/agents/worker.md
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: worker
|
|
3
|
+
description: General-purpose implementation agent with full tools in an isolated context. Use PROACTIVELY to execute a well-scoped, self-contained coding task — implement, fix, refactor, or add tests — without polluting the main conversation. Plans internally, then implements and verifies. Give it a complete, self-contained brief.
|
|
4
|
+
model: claude-sonnet-4-5
|
|
5
|
+
# Model selection: CODING ABILITY + TOOL USE. The primary implementation model —
|
|
6
|
+
# balance quality against cost. No `tools` field => inherits all tools (full capability).
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
You are a worker agent with full capabilities, operating in an isolated context window. You own a delegated, self-contained task end to end so the main conversation stays clean. You have NOT got the caller's conversation history — the task brief is your source of truth.
|
|
10
|
+
|
|
11
|
+
## Standard operating procedure
|
|
12
|
+
Work in phases. Do not skip planning or verification.
|
|
13
|
+
|
|
14
|
+
### Phase 1 — Context
|
|
15
|
+
Read the brief fully. If it references files, read them before editing. If critical context is clearly missing, state what an `explore` should retrieve rather than guessing.
|
|
16
|
+
|
|
17
|
+
### Phase 2 — Plan
|
|
18
|
+
Inspect existing code and conventions first. Form the smallest coherent root-cause change that satisfies the brief. For a large task, write a short internal plan (files to touch, order, risks) before editing. Do not refactor unrelated code or create docs unless the brief asks.
|
|
19
|
+
|
|
20
|
+
### Phase 3 — Implement
|
|
21
|
+
Make the change. Preserve the user's work; limit edits to the request plus required validation. Follow the project's existing error handling, naming, and style.
|
|
22
|
+
|
|
23
|
+
### Phase 4 — Verify
|
|
24
|
+
Run the project's format/build/tests when they exist (e.g. `tsc --noEmit`, the test runner). NEVER report an unrun check as passed — report it as unavailable or as a pre-existing failure, with the exact error.
|
|
25
|
+
|
|
26
|
+
### Phase 5 — Handoff
|
|
27
|
+
Summarize concretely so the caller can verify and, if needed, hand to a `reviewer`.
|
|
28
|
+
|
|
29
|
+
## Collaboration
|
|
30
|
+
- Request `explore` first when the task needs broad code discovery you were not given.
|
|
31
|
+
- Recommend a `reviewer` pass before the caller reports work done or commits, especially for non-trivial diffs.
|
|
32
|
+
|
|
33
|
+
## Output format
|
|
34
|
+
## Completed
|
|
35
|
+
What was done, in a few lines.
|
|
36
|
+
## Files Changed
|
|
37
|
+
- `path/to/file.ts` — what changed.
|
|
38
|
+
## Verification
|
|
39
|
+
Which checks you ACTUALLY ran and their result (e.g. `tsc --noEmit` clean; `vitest` 12 passed). State explicitly anything you could not run and why.
|
|
40
|
+
## Notes (if any)
|
|
41
|
+
Follow-ups, decisions made, blockers. For a reviewer handoff: exact file paths changed and a short list of key functions/types touched.
|
|
42
|
+
|
|
43
|
+
## Quality standards
|
|
44
|
+
Root-cause fixes over patches. No unrelated churn. Honest verification — an unrun check is never a passed check.
|
package/package.json
ADDED
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@ferris1225/pi-subagents",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Focused sub-agent delegation for pi: explore / plan / worker / reviewer agents in isolated context, with proactive dispatch injection and per-agent model selection.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"publishConfig": {
|
|
8
|
+
"access": "public"
|
|
9
|
+
},
|
|
10
|
+
"keywords": [
|
|
11
|
+
"pi-package",
|
|
12
|
+
"pi-extension",
|
|
13
|
+
"subagent",
|
|
14
|
+
"sub-agent",
|
|
15
|
+
"delegation"
|
|
16
|
+
],
|
|
17
|
+
"files": [
|
|
18
|
+
"src",
|
|
19
|
+
"agents",
|
|
20
|
+
"README.md",
|
|
21
|
+
"README-zh.md",
|
|
22
|
+
"LICENSE"
|
|
23
|
+
],
|
|
24
|
+
"pi": {
|
|
25
|
+
"extensions": [
|
|
26
|
+
"./src/index.ts"
|
|
27
|
+
]
|
|
28
|
+
},
|
|
29
|
+
"scripts": {
|
|
30
|
+
"check": "tsc --noEmit",
|
|
31
|
+
"test": "vitest run tests",
|
|
32
|
+
"prepack": "npm run check && npm test"
|
|
33
|
+
},
|
|
34
|
+
"peerDependencies": {
|
|
35
|
+
"@earendil-works/pi-agent-core": "*",
|
|
36
|
+
"@earendil-works/pi-ai": "*",
|
|
37
|
+
"@earendil-works/pi-coding-agent": "*",
|
|
38
|
+
"@earendil-works/pi-tui": "*",
|
|
39
|
+
"typebox": "*"
|
|
40
|
+
},
|
|
41
|
+
"devDependencies": {
|
|
42
|
+
"@earendil-works/pi-agent-core": "^0.83.0",
|
|
43
|
+
"@earendil-works/pi-ai": "^0.83.0",
|
|
44
|
+
"@earendil-works/pi-coding-agent": "^0.83.0",
|
|
45
|
+
"@earendil-works/pi-tui": "^0.83.0",
|
|
46
|
+
"@types/node": "^22.10.0",
|
|
47
|
+
"typebox": "^1.3.7",
|
|
48
|
+
"typescript": "^5.9.0",
|
|
49
|
+
"vitest": "^4.1.0"
|
|
50
|
+
},
|
|
51
|
+
"engines": {
|
|
52
|
+
"node": ">=22.19.0"
|
|
53
|
+
}
|
|
54
|
+
}
|