@zhushanwen/pi-cw-tool 0.4.0 → 0.4.1

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 (2) hide show
  1. package/package.json +1 -1
  2. package/skills/pi-cw/SKILL.md +18 -15
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zhushanwen/pi-cw-tool",
3
- "version": "0.4.0",
3
+ "version": "0.4.1",
4
4
  "description": "Pi extension wrapping the `cw` CLI as role-restricted tools (cw_planning / cw_wave / cw_dev / cw_review) with per-tool action whitelists — hard-guarantees no self-review by layer-owner agents.",
5
5
  "type": "module",
6
6
  "main": "index.ts",
package/skills/pi-cw/SKILL.md CHANGED
@@ -5,16 +5,16 @@ description: "cw 递归编排大型多 agent 并行开发任务,适用于需多
5
5
 
6
6
  # pi-cw
7
7
 
8
- 主 agent 发起递归编排:用 cw 建一棵 epic->feature->slice->wave 的任务树,派第一个 planning-agent 自递归展开整棵树,主 agent 空闲等 steer 唤醒,全树完成后报告用户。
8
+ 主 agent 发起递归编排:用 cw 建一棵 <顶层>->...->wave 的任务树(<顶层> 通常 epic,也可 feature/slice),派第一个 planning-agent 自递归展开整棵树,主 agent 空闲等 steer 唤醒,全树完成后报告用户。
9
9
 
10
- > **编排机制**:子 agent 完成时 pi 自动 steer 唤醒父 agent(事件驱动,无轮询)。主 agent 只派第一个 epic planning-agent,**不自己 descend 到子层**。设计依据见 `design-v4.md`（同目录）。
10
+ > **编排机制**:子 agent 完成时 pi 自动 steer 唤醒父 agent(事件驱动,无轮询)。主 agent 只派第一个(根层) planning-agent,**不自己 descend 到子层**。设计依据见 `design-v4.md`（同目录）。
11
11
 
12
12
  ## 何时用
13
13
 
14
- 满足任一:
15
- - 任务需要 epic/feature/slice/wave 多层拆解(单层 wave 装不下)
16
- - 多个 wave 可并行,各自 worktree 隔离开发
17
- - 单 agent 从头做到尾会撑爆上下文(设计 + 实现 + 审查 + 合并全栈)
14
+ 核心判据:**任务需要多 subagent 并行推进 + 上下文隔离**(不是树深——一棵 epic 树也能单 agent 线性走,见 cw-cli)。满足以下场景之一才用 pi-cw:
15
+ - 多个 wave 要 worktree 隔离并行开发
16
+ - 多个 slice/feature 子树要并行展开
17
+ - 单 agent 线性走完整棵树会撑爆上下文(设计 + 实现 + 审查 + 合并全栈),需按层隔离上下文
18
18
 
19
19
  > 单 agent 模式或小任务（改 typo / 单文件 / 明确小 bug）走 `cw-cli` skill,不必建树。
20
20
 
@@ -22,6 +22,7 @@ description: "cw 递归编排大型多 agent 并行开发任务,适用于需多
22
22
 
23
23
  - 单文件小改、明确的小 bug:直接 edit,或派单个 worker subagent;或走 `cw-cli` skill 单 agent 模式
24
24
  - 线性任务、无需多 agent 并行:走 cw 单层 wave 即可,不必建树
25
+ - 能单 agent 线性走完的任务(哪怕要建 epic 树):走 `cw-cli` skill 单 agent 模式,不必上递归编排
25
26
  - 纯分析 / 调研 / 设计文档:不写代码不该进 cw 编排
26
27
 
27
28
  ## 前置：cw-tool
@@ -40,26 +41,28 @@ description: "cw 递归编排大型多 agent 并行开发任务,适用于需多
40
41
  ### 1. 建树根
41
42
 
42
43
  ```bash
43
- cw create epic --slug <kebab-slug> --objective "<一句话目标,含可验收的完成标准>"
44
+ cw create <顶层> --slug <kebab-slug> --objective "<一句话目标,含可验收的完成标准>"
44
45
  ```
45
46
 
46
- 拿到 epic 的 unitId(下文记作 `<epicId>`)。
47
+ `<顶层>` 通常 epic,但 feature/slice 也能做根——选能覆盖全貌的最小层(选层标准复用 cw-cli skill 的「规模 × 性质」表)。递归编排的额外门槛:**顶层必须会拆出 ≥2 个可并行的下层 unit**;只拆 1 个(无并行价值)或整棵树线性串行即可,走 cw-cli 单 agent 模式更省。
48
+
49
+ 拿到根 unit 的 unitId(下文记作 `<根Id>`)。
47
50
 
48
51
  ### 2. 派第一个 planning-agent
49
52
 
50
53
  用 `subagent` 工具**后台**派发(`planning-agent` 是 cw-tool 内置的 agent 模板):
51
54
 
52
55
  ```
53
- subagent(action="start", agent="planning-agent", slug="<epic-slug>-planning", fork=false,
54
- task="<背景>这是 cw epic <epicId> 的层主 agent,目标:<原 objective>。这是递归编排,你会自递归派 feature/slice/wave 层 planning-agent。<目标>先调 cw handoff --unitId <epicId> 拿上下文与 guidance,按 guidance 的派发指导自递归展开并合并子树。<验收>cw status --unitId <epicId> 显示该 epic 子树全部 closed。")
56
+ subagent(action="start", agent="planning-agent", slug="<根-slug>-planning", fork=false,
57
+ task="<背景>这是 cw <根层> <根Id> 的层主 agent,目标:<原 objective>。这是递归编排,你会自递归派下层 planning-agent(<根层> 是 epic 派 feature,是 feature 派 slice,是 slice 派 wave)。<目标>先调 cw handoff --unitId <根Id> 拿上下文与 guidance,按 guidance 的派发指导自递归展开并合并子树。<验收>cw status --unitId <根Id> 显示该 <根层> 子树全部 closed。")
55
58
  # 不传 model 参数——默认继承主 agent 模型,递归传给所有下层(见「模型派发」)。
56
59
  # 用户特别指定时才传 model="provider/modelId",单个 subagent 生效或作为全树根模型。
57
60
  ```
58
61
 
59
62
  task 三要素:
60
- - **背景**:epic 的 `<epicId>`、目标、说明这是递归编排(planning-agent 会自递归派下层)
61
- - **目标**:入口是 `cw handoff --unitId <epicId>`;自递归的每一步按 cw guidance 的派发指导执行
62
- - **验收**:`cw status --unitId <epicId>` 子树全 `closed`(可查的检查点,禁止"完成""实现该功能"这类不可证伪描述)
63
+ - **背景**:`<根层>` 的 `<根Id>`、目标、说明这是递归编排(planning-agent 会自递归派下层)
64
+ - **目标**:入口是 `cw handoff --unitId <根Id>`;自递归的每一步按 cw guidance 的派发指导执行
65
+ - **验收**:`cw status --unitId <根Id>` 子树全 `closed`(可查的检查点,禁止"完成""实现该功能"这类不可证伪描述)
63
66
 
64
67
  派发后主 agent 结束当前 turn,进空闲态(session 保活)。
65
68
 
@@ -71,7 +74,7 @@ planning-agent 自递归展开(epic->feature->slice->wave),每层 design -> 审
71
74
 
72
75
  ```bash
73
76
  cw status # 全局
74
- cw frontier --root <epicId> # 看 epic 子树 frontier
77
+ cw frontier --root <根Id> # 看根子树 frontier
75
78
  ```
76
79
 
77
80
  - 子树全 `closed` -> 进入第 5 步汇报用户
@@ -86,7 +89,7 @@ cw frontier --root <epicId> # 看 epic 子树 frontier
86
89
 
87
90
  - **只派第一个 planning-agent**:主 agent 不自己 descend 到 feature / slice / wave 层。下层派发是 planning-agent 的职责(它调 cw execute 自动建子 unit,并按 guidance 派子 planning-agent / wave-agent)。
88
91
  - **靠 cw 查进度,不信自报**:agent 汇报"我做完了"不等于 cw 状态 closed。以 `cw status` / `cw frontier` 为唯一真相。
89
- - **worktree 隔离**:wave 层用 `worktree: true` 派出(各 wave 独立工作目录,并行不冲突;worktree 与 fork 正交,fork 默认 false);主 agent 派的 epic planning-agent 不需 worktree(它只编排不写码)。worktree 的合并与清理由 slice 层 planning-agent 派 chain workflow(merge-agent)处理,细节见 planning-agent 模板。
92
+ - **worktree 隔离**:wave 层用 `worktree: true` 派出(各 wave 独立工作目录,并行不冲突;worktree 与 fork 正交,fork 默认 false);主 agent 派的根层 planning-agent 不需 worktree(它只编排不写码)。worktree 的合并与清理由 slice 层 planning-agent 派 chain workflow(merge-agent)处理,细节见 planning-agent 模板。
90
93
  - **失败恢复靠 L0-L3**:cw gate fail / 审查 must-fix / 方案缺陷 / 父层拆错,各有恢复路径(L0 就地改重审 / L1 cw replan / L2 父 replan 级联 / L3 上报人),定义在 planning-agent 模板与 cw guidance,本 skill 不重复。
91
94
 
92
95
  ## 模型派发