@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 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
+ [![npm version](https://img.shields.io/npm/v/@ferris1225/pi-subagents?color=blue)](https://www.npmjs.com/package/@ferris1225/pi-subagents)
4
+ [![downloads](https://img.shields.io/npm/dm/@ferris1225/pi-subagents)](https://www.npmjs.com/package/@ferris1225/pi-subagents)
5
+ [![license](https://img.shields.io/npm/l/@ferris1225/pi-subagents)](./LICENSE)
6
+ ![platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
7
+ ![pi](https://img.shields.io/badge/pi-extension-orange)
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
+ [![npm version](https://img.shields.io/npm/v/@ferris1225/pi-subagents?color=blue)](https://www.npmjs.com/package/@ferris1225/pi-subagents)
4
+ [![downloads](https://img.shields.io/npm/dm/@ferris1225/pi-subagents)](https://www.npmjs.com/package/@ferris1225/pi-subagents)
5
+ [![license](https://img.shields.io/npm/l/@ferris1225/pi-subagents)](./LICENSE)
6
+ ![platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
7
+ ![pi](https://img.shields.io/badge/pi-extension-orange)
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.
@@ -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
+ }