@tea-agent/loop-agent 0.35.0-beta.2 → 0.35.1-beta.0

package/skills/loop-agent/references/docs-converge.md

@@ -1,126 +1,126 @@
-# Docs Converge（文档收敛）
-
-本 reference 把会话协议中的 **Converge Docs** 落成可执行检查表。
-定位是**收敛 / 同步**，不是「每次重新 invent 文档大纲」。
-
-权威规划：`ai_workspace/loop-agent/exec-plans/completed/2026-07-14-website-docs-ia-and-converge.md`。
-站与治理双树边界：`website/README.md`。
-
-## 何时触发
-
-在以下任一情况**加载本文件并跑检查表**：
-
-- 用户可见行为变更（CLI 输出、默认工作流、init 投影、Observe/Worker 主路径）。
-- 新增 / 修改 / 删除 CLI 命令或关键 flags。
-- runtime / 架构边界变更（`ai_workspace/loop-agent/architecture/*`、executor 角色、Worker 边界）。
-- active plan 创建、blocked、完成或归档。
-- 准备发布或写 `CHANGELOG.md` 版本条目。
-- 用户明确要求「文档收敛」「docs converge」「同步 website docs」。
-- handoff 前需要声明「本轮是否更新了站上文档」。
-
-**不要**在无关的纯内部重构（无用户可见行为、无命令面变化）上强制大改站上正文；此时 handoff 写明豁免理由即可。
-
-## 受众矩阵
-
-| 受众 | 主要入口 | 权威细节 |
-| --- | --- | --- |
-| 新贡献者 | `website/docs/intro.md` → `overview/architecture` → `overview/roadmap` → first-run | 根 `ai_workspace/loop-agent/architecture/*`、active plans |
-| 使用者 | `overview/feature-map`、`quick-start/*`、`guides/*`、`reference/*` | CLI help、根 `CHANGELOG.md` |
-| 维护者 / agent | 本检查表 + `AGENTS.md` Converge Docs | `ai_workspace/loop-agent/`、`.agents/skills/`、`scripts/check-*.sh` |
-
-## 页面清单（站上活文档）
-
-| 页面 | 职责 |
-| --- | --- |
-| `website/docs/intro.md` | 概念地图 + 30 分钟路径；非能力堆砌 |
-| `website/docs/overview/feature-map.md` | 功能导览 → guide/CLI |
-| `website/docs/overview/architecture.md` | 架构导读；链到 `ai_workspace/loop-agent/architecture/` |
-| `website/docs/overview/roadmap.md` | 当前有效规划短索引 |
-| `website/docs/quick-start/*` | 安装 / init / first-run |
-| `website/docs/guides/*` | 主路径操作说明 |
-| `website/docs/reference/cli.md` | 用户向 CLI 参考 |
-| `website/docs/reference/config.md` | 配置参考 |
-| `website/docs/changelog.md` | 读者摘要；完整版本以根 `CHANGELOG.md` 为准 |
-
-治理全文、exec-plans、reports **不**搬进 Docusaurus。
-
-## 变更 → 文档检查表
-
-按本轮实际 diff 勾选（有则必须处理，无则跳过并记豁免）：
-
-| 若变更了… | 必须检查 / 更新 |
-| --- | --- |
-| 新/改 CLI 命令 | `website/docs/reference/cli.md` + `.agents/skills/loop-agent/references/command-reference.md`（及 agent-worker 相关 reference） |
-| 用户可见行为 | 对应 `guides/*` 或 `quick-start/*`；根 `CHANGELOG.md`；必要时 `overview/feature-map.md` / `intro.md` |
-| runtime / 边界 | 根 `ai_workspace/loop-agent/architecture/*`；站上 `overview/architecture.md` 导语与外链 |
-| 默认工作流 | `intro.md` 流程图 + `guides/agent-dag.md` / `guides/harness-policy.md` |
-| active plan 状态 | `overview/roadmap.md` 短索引 + `ai_workspace/loop-agent/exec-plans/active/README.md` |
-| 发布 | 根 `CHANGELOG.md` 为版本事实源；`website/docs/changelog.md` 只写摘要与链接；roadmap 仅在规划状态变化时更新 |
-| skill / init 投影 | `ai_workspace/loop-agent/init-surface.manifest.json`、相关测试、必要时 `ai_workspace/loop-agent/.agents/skills/*` |
-
-跨树链接规则：
-
-- 站内页面用 Docusaurus 相对文档链接。
-- 链到根目录 `ai_workspace/loop-agent/`、`AGENTS.md`、`CHANGELOG.md` 等时，使用
-  `https://github.com/tea-agent/loop-agent/blob/main/<repo-path>`，
-  正文同时写出 repo-relative path；禁止伪造站内 `/ai_workspace/loop-agent/architecture/...` 作为根目录文档路由。
-
-## 执行步骤（最小闭环）
-
-1. **列出本轮用户可见 diff**（命令、行为、边界、计划状态）。
-2. **对照上表**产出缺口清单（页面路径 + 要改的一句话）。
-3. **最小补丁**：只改清单内页面；禁止顺手重写 practices 或迁移整个 `ai_workspace/loop-agent/`。
-4. **验证**（见下节）。
-5. **Handoff** 二选一：
-   - 已更新：列出改动页面与验证命令结果。
-   - 无需站上更新：写明「本轮无需站上更新，原因：…」。
-
-## 验证命令
-
-站上正文、侧栏或 `docusaurus.config.ts` 有改动时：
-
-```bash
-npm run docs:build
-```
-
-涉及治理文档、脚本、skill、init surface 时再跑：
-
-```bash
-bash scripts/check-repo.sh
-# 或定向：
-bash scripts/check-skill-entry.sh
-bash scripts/check-command-registry-drift.sh
-bash scripts/check-init-surface.sh
-node bin/loop-agent.js docs audit --repo-root .
-```
-
-skill / package 投影相关：
-
-```bash
-npx vitest run test/init-command.test.ts test/package-surface.test.ts
-```
-
-## 禁止事项
-
-- 每次会话从头撰写全新文档大纲或「重新规划整个 docs 树」。
-- 把 `ai_workspace/loop-agent/design/`、exec-plans、reports 全文复制进 `website/docs/`。
-- 在站上建立第二套与 `ai_workspace/loop-agent/architecture/*` 冲突的架构真源。
-- 未读 `website/README.md` 与相关 exec-plan 就扩大 scope。
-- 用删测试、降 `onBrokenMarkdownLinks` 或忽略 `docs:build` 失败制造「完成」。
-- 新增独立公共 skill 目录承载本检查表（应留在 `.agents/skills/loop-agent/references/`）。
-
-## 与现有能力的关系
-
-| 能力 | 关系 |
-| --- | --- |
-| `loop-agent docs audit` | L0 腐化检查（断链、计划状态等）；**不**替代本表内容审计 |
-| `npm run docs:build` | 站上改动硬门禁（含 Markdown 断链 fail-fast） |
-| `grill-with-docs` | ADR / 术语；不替代本 reference |
-| 历史 2026-07-05 docs governance dogfood | 仅经验输入；新 workflow 必须 Pi-only，不复用已退役原生 Cursor DAG |
-
-## 快速自检（handoff 前 30 秒）
-
-- [ ] 用户可见变更是否对照检查表处理或已豁免？
-- [ ] intro 是否仍是概念地图（而非能力 bullet 堆砌）？
-- [ ] roadmap 是否只含当前有效 active 项？
-- [ ] 需要时 `docs:build` / `check-repo` 是否有新鲜输出？
+# Docs Converge（文档收敛）
+
+本 reference 把会话协议中的 **Converge Docs** 落成可执行检查表。
+定位是**收敛 / 同步**，不是「每次重新 invent 文档大纲」。
+
+权威规划：`ai_workspace/loop-agent/exec-plans/completed/2026-07-14-website-docs-ia-and-converge.md`。
+站与治理双树边界：`website/README.md`。
+
+## 何时触发
+
+在以下任一情况**加载本文件并跑检查表**：
+
+- 用户可见行为变更（CLI 输出、默认工作流、init 投影、Observe/Worker 主路径）。
+- 新增 / 修改 / 删除 CLI 命令或关键 flags。
+- runtime / 架构边界变更（`ai_workspace/loop-agent/architecture/*`、executor 角色、Worker 边界）。
+- active plan 创建、blocked、完成或归档。
+- 准备发布或写 `CHANGELOG.md` 版本条目。
+- 用户明确要求「文档收敛」「docs converge」「同步 website docs」。
+- handoff 前需要声明「本轮是否更新了站上文档」。
+
+**不要**在无关的纯内部重构（无用户可见行为、无命令面变化）上强制大改站上正文；此时 handoff 写明豁免理由即可。
+
+## 受众矩阵
+
+| 受众 | 主要入口 | 权威细节 |
+| --- | --- | --- |
+| 新贡献者 | `website/docs/intro.md` → `overview/architecture` → `overview/roadmap` → first-run | 根 `ai_workspace/loop-agent/architecture/*`、active plans |
+| 使用者 | `overview/feature-map`、`quick-start/*`、`guides/*`、`reference/*` | CLI help、根 `CHANGELOG.md` |
+| 维护者 / agent | 本检查表 + `AGENTS.md` Converge Docs | `ai_workspace/loop-agent/`、`.agents/skills/`、`scripts/check-*.sh` |
+
+## 页面清单（站上活文档）
+
+| 页面 | 职责 |
+| --- | --- |
+| `website/docs/intro.md` | 概念地图 + 30 分钟路径；非能力堆砌 |
+| `website/docs/overview/feature-map.md` | 功能导览 → guide/CLI |
+| `website/docs/overview/architecture.md` | 架构导读；链到 `ai_workspace/loop-agent/architecture/` |
+| `website/docs/overview/roadmap.md` | 当前有效规划短索引 |
+| `website/docs/quick-start/*` | 安装 / init / first-run |
+| `website/docs/guides/*` | 主路径操作说明 |
+| `website/docs/reference/cli.md` | 用户向 CLI 参考 |
+| `website/docs/reference/config.md` | 配置参考 |
+| `website/docs/changelog.md` | 读者摘要；完整版本以根 `CHANGELOG.md` 为准 |
+
+治理全文、exec-plans、reports **不**搬进 Docusaurus。
+
+## 变更 → 文档检查表
+
+按本轮实际 diff 勾选（有则必须处理，无则跳过并记豁免）：
+
+| 若变更了… | 必须检查 / 更新 |
+| --- | --- |
+| 新/改 CLI 命令 | `website/docs/reference/cli.md` + `.agents/skills/loop-agent/references/command-reference.md`（及 agent-worker 相关 reference） |
+| 用户可见行为 | 对应 `guides/*` 或 `quick-start/*`；根 `CHANGELOG.md`；必要时 `overview/feature-map.md` / `intro.md` |
+| runtime / 边界 | 根 `ai_workspace/loop-agent/architecture/*`；站上 `overview/architecture.md` 导语与外链 |
+| 默认工作流 | `intro.md` 流程图 + `guides/agent-dag.md` / `guides/harness-policy.md` |
+| active plan 状态 | `overview/roadmap.md` 短索引 + `ai_workspace/loop-agent/exec-plans/active/README.md` |
+| 发布 | 根 `CHANGELOG.md` 为版本事实源；`website/docs/changelog.md` 只写摘要与链接；roadmap 仅在规划状态变化时更新 |
+| skill / init 投影 | `ai_workspace/loop-agent/init-surface.manifest.json`、相关测试、必要时 `ai_workspace/loop-agent/.agents/skills/*` |
+
+跨树链接规则：
+
+- 站内页面用 Docusaurus 相对文档链接。
+- 链到根目录 `ai_workspace/loop-agent/`、`AGENTS.md`、`CHANGELOG.md` 等时，使用
+  `https://github.com/tea-agent/loop-agent/blob/main/<repo-path>`，
+  正文同时写出 repo-relative path；禁止伪造站内 `/ai_workspace/loop-agent/architecture/...` 作为根目录文档路由。
+
+## 执行步骤（最小闭环）
+
+1. **列出本轮用户可见 diff**（命令、行为、边界、计划状态）。
+2. **对照上表**产出缺口清单（页面路径 + 要改的一句话）。
+3. **最小补丁**：只改清单内页面；禁止顺手重写 practices 或迁移整个 `ai_workspace/loop-agent/`。
+4. **验证**（见下节）。
+5. **Handoff** 二选一：
+   - 已更新：列出改动页面与验证命令结果。
+   - 无需站上更新：写明「本轮无需站上更新，原因：…」。
+
+## 验证命令
+
+站上正文、侧栏或 `docusaurus.config.ts` 有改动时：
+
+```bash
+npm run docs:build
+```
+
+涉及治理文档、脚本、skill、init surface 时再跑：
+
+```bash
+bash scripts/check-repo.sh
+# 或定向：
+bash scripts/check-skill-entry.sh
+bash scripts/check-command-registry-drift.sh
+bash scripts/check-init-surface.sh
+node bin/loop-agent.js docs audit --repo-root .
+```
+
+skill / package 投影相关：
+
+```bash
+npx vitest run test/init-command.test.ts test/package-surface.test.ts
+```
+
+## 禁止事项
+
+- 每次会话从头撰写全新文档大纲或「重新规划整个 docs 树」。
+- 把 `ai_workspace/loop-agent/design/`、exec-plans、reports 全文复制进 `website/docs/`。
+- 在站上建立第二套与 `ai_workspace/loop-agent/architecture/*` 冲突的架构真源。
+- 未读 `website/README.md` 与相关 exec-plan 就扩大 scope。
+- 用删测试、降 `onBrokenMarkdownLinks` 或忽略 `docs:build` 失败制造「完成」。
+- 新增独立公共 skill 目录承载本检查表（应留在 `.agents/skills/loop-agent/references/`）。
+
+## 与现有能力的关系
+
+| 能力 | 关系 |
+| --- | --- |
+| `loop-agent docs audit` | L0 腐化检查（断链、计划状态等）；**不**替代本表内容审计 |
+| `npm run docs:build` | 站上改动硬门禁（含 Markdown 断链 fail-fast） |
+| `grill-with-docs` | ADR / 术语；不替代本 reference |
+| 历史 2026-07-05 docs governance dogfood | 仅经验输入；新 workflow 必须 Pi-only，不复用已退役原生 Cursor DAG |
+
+## 快速自检（handoff 前 30 秒）
+
+- [ ] 用户可见变更是否对照检查表处理或已豁免？
+- [ ] intro 是否仍是概念地图（而非能力 bullet 堆砌）？
+- [ ] roadmap 是否只含当前有效 active 项？
+- [ ] 需要时 `docs:build` / `check-repo` 是否有新鲜输出？

package/skills/loop-agent/references/learned/README.md

@@ -1,21 +1,21 @@
-# Learned loop-agent Patterns
-
-本目录是 SePO-lite prompt evolution 的 human-gated target。
-
-Rules:
-
-- Files 仅为 Markdown guidance。
-- `retrospective` 可 propose `.harness/tasks/<task-id>/source/prompt-delta.md`；不得自动 merge 到此。
-- 不要添加 shell commands、credential handling、tool permission expansion 或 completion-authority bypass rules。
-- DAG implementer prompts 在 node 已 request `loop-agent` skill 时，可将 repo-specific 文件 `<repo>.md` 或 `default.md` 作为 bounded inline guidance 加载。
-- 保持条目 short 且 pattern-oriented：failure class、fix scope shape、invariant、verification evidence。
-
-Acceptance checklist before merging a prompt delta:
-
-- Proposal 仅为 Markdown-only process guidance。
-- 不含 shell/runtime command lines 或 fenced command blocks。
-- Credential material、tokens、passwords、secrets 与 API keys 保持不可触达。
-- Tool permissions、path allowlists、`allowedPaths`、`forbiddenPaths` 与 `writeSet` 保持既有边界。
-- Shell verification、tests、write guards、decision gates、human gates 与 completion evidence 均为保留门禁。
-- Completed DAG 与 one-shot run facts 保持只读。
-- Learned file 编辑后 `loop-agent docs audit` 须 pass。
+# Learned loop-agent Patterns
+
+本目录是 SePO-lite prompt evolution 的 human-gated target。
+
+Rules:
+
+- Files 仅为 Markdown guidance。
+- `retrospective` 可 propose `.harness/tasks/<task-id>/source/prompt-delta.md`；不得自动 merge 到此。
+- 不要添加 shell commands、credential handling、tool permission expansion 或 completion-authority bypass rules。
+- DAG implementer prompts 在 node 已 request `loop-agent` skill 时，可将 repo-specific 文件 `<repo>.md` 或 `default.md` 作为 bounded inline guidance 加载。
+- 保持条目 short 且 pattern-oriented：failure class、fix scope shape、invariant、verification evidence。
+
+Acceptance checklist before merging a prompt delta:
+
+- Proposal 仅为 Markdown-only process guidance。
+- 不含 shell/runtime command lines 或 fenced command blocks。
+- Credential material、tokens、passwords、secrets 与 API keys 保持不可触达。
+- Tool permissions、path allowlists、`allowedPaths`、`forbiddenPaths` 与 `writeSet` 保持既有边界。
+- Shell verification、tests、write guards、decision gates、human gates 与 completion evidence 均为保留门禁。
+- Completed DAG 与 one-shot run facts 保持只读。
+- Learned file 编辑后 `loop-agent docs audit` 须 pass。

package/skills/loop-agent/references/pi-prompt.md

@@ -1,23 +1,23 @@
-# One-shot Pi SDK Prompt Helper（`pi-prompt`）
-
-短时 Pi SDK task、不需要完整 `.harness/tasks/<id>` workflow 时使用本文。替代 ad-hoc 临时代码脚本导入 `executeSingleSdkAttempt` 的做法。
-
-### One-shot Pi SDK prompt helper
-
-短时 Pi SDK task、不需要完整 `.harness/tasks/<id>` workflow 时，用 `loop-agent pi-prompt`，勿创建 ad-hoc 临时代码脚本导入 `executeSingleSdkAttempt`。`pi-prompt` 是一次性 full-capability helper；是否只读由本次调用的 prompt 与 `--tools` 决定。
-
-```bash
-loop-agent pi-prompt "Reply with exactly OK."
-loop-agent pi-prompt --stdin < <temp-dir>/task.md
-loop-agent pi-prompt --file <temp-dir>/task.md
-loop-agent pi-prompt --cwd ~/go/src/loop-agent --tools read,grep,find,ls "Review the current diff. Do not edit files."
-loop-agent pi-prompt --cwd ~/go/src/loop-agent --tools subagent,read --timeout 2400000 "Use subagent exactly once ..."
-loop-agent pi-prompt --model gpt-5.5 --cwd ~/go/src/loop-agent "Deeply diagnose this failure."
-loop-agent pi-prompt "Reply with exactly OK."
-```
-
-`<temp-dir>` 表示平台原生临时目录；实际命令中使用本机路径。
-
-默认：`--provider wizard-local --model glm-5.2`；高复杂度 one-shot 可显式 `--model gpt-5.5`。按需用 `--provider`、`--model`、`--thinking`、`--tools`、`--timeout` 覆盖。
-
-`pi-prompt` 仅用于 quick one-shot SDK call。**不**创建 `.harness/tasks/`、不跑 verification、不写 handoff artifact、不保留 workflow state。须可恢复、可验证的 implementation work 用 DAG 路径；需要隔离写入时使用 bounded Cursor 或 `delegate`。
+# One-shot Pi SDK Prompt Helper（`pi-prompt`）
+
+短时 Pi SDK task、不需要完整 `.harness/tasks/<id>` workflow 时使用本文。替代 ad-hoc 临时代码脚本导入 `executeSingleSdkAttempt` 的做法。
+
+### One-shot Pi SDK prompt helper
+
+短时 Pi SDK task、不需要完整 `.harness/tasks/<id>` workflow 时，用 `loop-agent pi-prompt`，勿创建 ad-hoc 临时代码脚本导入 `executeSingleSdkAttempt`。`pi-prompt` 是一次性 full-capability helper；是否只读由本次调用的 prompt 与 `--tools` 决定。
+
+```bash
+loop-agent pi-prompt "Reply with exactly OK."
+loop-agent pi-prompt --stdin < <temp-dir>/task.md
+loop-agent pi-prompt --file <temp-dir>/task.md
+loop-agent pi-prompt --cwd ~/go/src/loop-agent --tools read,grep,find,ls "Review the current diff. Do not edit files."
+loop-agent pi-prompt --cwd ~/go/src/loop-agent --tools subagent,read --timeout 2400000 "Use subagent exactly once ..."
+loop-agent pi-prompt --model gpt-5.5 --cwd ~/go/src/loop-agent "Deeply diagnose this failure."
+loop-agent pi-prompt "Reply with exactly OK."
+```
+
+`<temp-dir>` 表示平台原生临时目录；实际命令中使用本机路径。
+
+默认：`--provider wizard-local --model glm-5.2`；高复杂度 one-shot 可显式 `--model gpt-5.5`。按需用 `--provider`、`--model`、`--thinking`、`--tools`、`--timeout` 覆盖。
+
+`pi-prompt` 仅用于 quick one-shot SDK call。**不**创建 `.harness/tasks/`、不跑 verification、不写 handoff artifact、不保留 workflow state。须可恢复、可验证的 implementation work 用 DAG 路径；需要隔离写入时使用 bounded Cursor 或 `delegate`。

package/skills/loop-agent/references/pi-subagent-assisted-mode.md

@@ -1,84 +1,84 @@
-# Pi Subagent Assisted Mode
-
-loop-agent task 启用 `piSubagentMode`、在 analyze/plan/spec/retrospective 内需要 read-only scout/planner/reviewer subagents，或配置 project-local agents/prompts 时使用本文。
-
-`task.json` 支持可选字段 `piSubagentMode`，用于 step 级 `subagent` tool delegation：
-
-| Mode | analyze | plan | spec | implement | retrospective | verify |
-|------|---------|------|------|-----------|----------------|--------|
-| `off`（默认） | read only | read only | read only | +write/edit/bash | read only | read only |
-| `analyze-plan` | **+subagent** | **+subagent** | **+subagent** | 同 off | 同 off | 同 off |
-| `full` | **+subagent** | **+subagent** | **+subagent** | 同 off | **+subagent** | 同 off |
-
-### 何时启用
-
-在 `task.json` 设 `piSubagentMode: "analyze-plan"` 或 `piSubagentMode: "full"` 当：
-- task 涉及大规模 codebase 阅读，适合 parallel scout agents
-- analysis 或 planning 需多角度调查（如跨模块比较实现）
-- retrospective review 适合独立 reviewer subagent（`full` mode）
-
-### step 内使用 `subagent` 的指引
-
-subagent 可用时，**仅用于 read-only task**：
-- **Parallel scout**：dispatch 多个 subagent 同时搜索/阅读不同区域
-- **Chain**：一个 subagent scout，另一个基于发现 planning
-- **Reviewer**：用 subagent 在定稿前 review analysis/plan
-
-**不要**用 subagent 做 writing、editing 或执行命令。subagent 输出仅 advisory；务必 verify 并将发现并入自己的输出。**不要**把 subagent 结果当作权威 state 或 artifact source。
-
-### 前置条件
-
-- Pi runtime 环境须有 `subagent` tool（经 Pi subagent extension 加载）
-- 推荐用 Pi 自带 example 文件安装：
-
-```bash
-mkdir -p ~/.pi/agent/extensions/subagent ~/.pi/agent/agents ~/.pi/agent/prompts
-
-ln -sf /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/index.ts ~/.pi/agent/extensions/subagent/index.ts
-ln -sf /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/agents.ts ~/.pi/agent/extensions/subagent/agents.ts
-
-for f in /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/agents/*.md; do
-  ln -sf "$f" ~/.pi/agent/agents/$(basename "$f")
-done
-
-for f in /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/prompts/*.md; do
-  ln -sf "$f" ~/.pi/agent/prompts/$(basename "$f")
-done
-```
-
-- 最小 smoke check：
-
-```bash
-pi -p --no-session --no-context-files --no-skills --tools subagent "Reply with exactly OK."
-```
-
-  预期输出：`OK`
-- mode 按 task opt-in；默认 `off` 保持向后兼容
-- 任何 mode 下 `implement` 都不给 `subagent`（防止 nested multi-writer）
-
-### 内置 Project-Local Agents 与 Prompts
-
-本 repo 提供 `.pi/agents/` 与 `.pi/prompts/` 模板，供 `piSubagentMode` 使用：
-
-**Agents**（`.pi/agents/`）
-
-| Agent | Role | 对应阶段 |
-|-------|------|----------|
-| `loop-agent-scout` | 只读侦察：code、tests、docs、governance | Scout |
-| `loop-agent-planner` | 最小可执行计划；强调验证与回退 | Plan |
-| `loop-agent-reviewer` | 严格审查：范围漂移、验证缺口、契约破坏 | Verify / Review |
-| `loop-agent-worker` | 有界实现与修补 | Implement |
-
-另有通用 agents：`scout` / `planner` / `worker` / `reviewer`（中文提示，可被通用 prompt 模板调用）。模型以各 agent frontmatter 为准（当前仓库默认对齐 `harness.json` 的 Pi executor）。
-
-**Prompt Templates**（`.pi/prompts/`）：输入 `/loop-agent-*` 或通用模板名调用
-
-| Template | Flow |
-|----------|------|
-| `loop-agent-scout-and-plan` | parallel scout → planner |
-| `loop-agent-analyze-wide` | 3 parallel scouts → 结构化分析 |
-| `loop-agent-review-only` | 独立审查计划/实现/验证 |
-| `loop-agent-implement-and-review` | worker → reviewer → worker |
-| `scout-and-plan` / `implement` / `implement-and-review` | 通用 chain（调用 `scout`/`planner`/`worker`/`reviewer`） |
-
-传 `agentScope: "both"` + `confirmProjectAgents: false` 以访问 repo-local agents。
+# Pi Subagent Assisted Mode
+
+loop-agent task 启用 `piSubagentMode`、在 analyze/plan/spec/retrospective 内需要 read-only scout/planner/reviewer subagents，或配置 project-local agents/prompts 时使用本文。
+
+`task.json` 支持可选字段 `piSubagentMode`，用于 step 级 `subagent` tool delegation：
+
+| Mode | analyze | plan | spec | implement | retrospective | verify |
+|------|---------|------|------|-----------|----------------|--------|
+| `off`（默认） | read only | read only | read only | +write/edit/bash | read only | read only |
+| `analyze-plan` | **+subagent** | **+subagent** | **+subagent** | 同 off | 同 off | 同 off |
+| `full` | **+subagent** | **+subagent** | **+subagent** | 同 off | **+subagent** | 同 off |
+
+### 何时启用
+
+在 `task.json` 设 `piSubagentMode: "analyze-plan"` 或 `piSubagentMode: "full"` 当：
+- task 涉及大规模 codebase 阅读，适合 parallel scout agents
+- analysis 或 planning 需多角度调查（如跨模块比较实现）
+- retrospective review 适合独立 reviewer subagent（`full` mode）
+
+### step 内使用 `subagent` 的指引
+
+subagent 可用时，**仅用于 read-only task**：
+- **Parallel scout**：dispatch 多个 subagent 同时搜索/阅读不同区域
+- **Chain**：一个 subagent scout，另一个基于发现 planning
+- **Reviewer**：用 subagent 在定稿前 review analysis/plan
+
+**不要**用 subagent 做 writing、editing 或执行命令。subagent 输出仅 advisory；务必 verify 并将发现并入自己的输出。**不要**把 subagent 结果当作权威 state 或 artifact source。
+
+### 前置条件
+
+- Pi runtime 环境须有 `subagent` tool（经 Pi subagent extension 加载）
+- 推荐用 Pi 自带 example 文件安装：
+
+```bash
+mkdir -p ~/.pi/agent/extensions/subagent ~/.pi/agent/agents ~/.pi/agent/prompts
+
+ln -sf /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/index.ts ~/.pi/agent/extensions/subagent/index.ts
+ln -sf /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/agents.ts ~/.pi/agent/extensions/subagent/agents.ts
+
+for f in /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/agents/*.md; do
+  ln -sf "$f" ~/.pi/agent/agents/$(basename "$f")
+done
+
+for f in /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/prompts/*.md; do
+  ln -sf "$f" ~/.pi/agent/prompts/$(basename "$f")
+done
+```
+
+- 最小 smoke check：
+
+```bash
+pi -p --no-session --no-context-files --no-skills --tools subagent "Reply with exactly OK."
+```
+
+  预期输出：`OK`
+- mode 按 task opt-in；默认 `off` 保持向后兼容
+- 任何 mode 下 `implement` 都不给 `subagent`（防止 nested multi-writer）
+
+### 内置 Project-Local Agents 与 Prompts
+
+本 repo 提供 `.pi/agents/` 与 `.pi/prompts/` 模板，供 `piSubagentMode` 使用：
+
+**Agents**（`.pi/agents/`）
+
+| Agent | Role | 对应阶段 |
+|-------|------|----------|
+| `loop-agent-scout` | 只读侦察：code、tests、docs、governance | Scout |
+| `loop-agent-planner` | 最小可执行计划；强调验证与回退 | Plan |
+| `loop-agent-reviewer` | 严格审查：范围漂移、验证缺口、契约破坏 | Verify / Review |
+| `loop-agent-worker` | 有界实现与修补 | Implement |
+
+另有通用 agents：`scout` / `planner` / `worker` / `reviewer`（中文提示，可被通用 prompt 模板调用）。模型以各 agent frontmatter 为准（当前仓库默认对齐 `harness.json` 的 Pi executor）。
+
+**Prompt Templates**（`.pi/prompts/`）：输入 `/loop-agent-*` 或通用模板名调用
+
+| Template | Flow |
+|----------|------|
+| `loop-agent-scout-and-plan` | parallel scout → planner |
+| `loop-agent-analyze-wide` | 3 parallel scouts → 结构化分析 |
+| `loop-agent-review-only` | 独立审查计划/实现/验证 |
+| `loop-agent-implement-and-review` | worker → reviewer → worker |
+| `scout-and-plan` / `implement` / `implement-and-review` | 通用 chain（调用 `scout`/`planner`/`worker`/`reviewer`） |
+
+传 `agentScope: "both"` + `confirmProjectAgents: false` 以访问 repo-local agents。

package/skills/playwright-cli/references/element-attributes.md

@@ -1,23 +1,23 @@
-# Inspecting Element Attributes
-
-When the snapshot doesn't show an element's `id`, `class`, `data-*` attributes, or other DOM properties, use `eval` to inspect them.
-
-## Examples
-
-```bash
-playwright-cli snapshot
-# snapshot shows a button as e7 but doesn't reveal its id or data attributes
-
-# get the element's id
-playwright-cli eval "el => el.id" e7
-
-# get all CSS classes
-playwright-cli eval "el => el.className" e7
-
-# get a specific attribute
-playwright-cli eval "el => el.getAttribute('data-testid')" e7
-playwright-cli eval "el => el.getAttribute('aria-label')" e7
-
-# get a computed style property
-playwright-cli eval "el => getComputedStyle(el).display" e7
-```
+# Inspecting Element Attributes
+
+When the snapshot doesn't show an element's `id`, `class`, `data-*` attributes, or other DOM properties, use `eval` to inspect them.
+
+## Examples
+
+```bash
+playwright-cli snapshot
+# snapshot shows a button as e7 but doesn't reveal its id or data attributes
+
+# get the element's id
+playwright-cli eval "el => el.id" e7
+
+# get all CSS classes
+playwright-cli eval "el => el.className" e7
+
+# get a specific attribute
+playwright-cli eval "el => el.getAttribute('data-testid')" e7
+playwright-cli eval "el => el.getAttribute('aria-label')" e7
+
+# get a computed style property
+playwright-cli eval "el => getComputedStyle(el).display" e7
+```

package/skills/playwright-cli/references/playwright-tests.md

@@ -1,39 +1,39 @@
-# Running Playwright Tests
-
-To run Playwright tests, use the `npx playwright test` command, or a package manager script. To avoid opening the interactive html report, use `PLAYWRIGHT_HTML_OPEN=never` environment variable.
-
-```bash
-# Run all tests
-PLAYWRIGHT_HTML_OPEN=never npx playwright test
-
-# Run all tests through a custom npm script
-PLAYWRIGHT_HTML_OPEN=never npm run special-test-command
-```
-
-# Debugging Playwright Tests
-
-To debug a failing Playwright test, run it with `--debug=cli` option. This command will pause the test at the start and print the debugging instructions.
-
-**IMPORTANT**: run the command in the background and check the output until "Debugging Instructions" is printed. Make sure to stop the command after you have finished.
-
-Once instructions containing a session name are printed, use `playwright-cli` to attach the session and explore the page.
-
-```bash
-# Run the test
-PLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli
-# ...
-# ... debugging instructions for "tw-abcdef" session ...
-# ...
-
-# Attach to the test
-playwright-cli attach tw-abcdef
-```
-
-Keep the test running in the background while you explore and look for a fix.
-The test is paused at the start, so you should step over or pause at a particular location
-where the problem is most likely to be.
-
-Every action you perform with `playwright-cli` generates corresponding Playwright TypeScript code.
-This code appears in the output and can be copied directly into the test. Most of the time, a specific locator or an expectation should be updated, but it could also be a bug in the app. Use your judgement.
-
-After fixing the test, stop the background test run. Rerun to check that test passes.
+# Running Playwright Tests
+
+To run Playwright tests, use the `npx playwright test` command, or a package manager script. To avoid opening the interactive html report, use `PLAYWRIGHT_HTML_OPEN=never` environment variable.
+
+```bash
+# Run all tests
+PLAYWRIGHT_HTML_OPEN=never npx playwright test
+
+# Run all tests through a custom npm script
+PLAYWRIGHT_HTML_OPEN=never npm run special-test-command
+```
+
+# Debugging Playwright Tests
+
+To debug a failing Playwright test, run it with `--debug=cli` option. This command will pause the test at the start and print the debugging instructions.
+
+**IMPORTANT**: run the command in the background and check the output until "Debugging Instructions" is printed. Make sure to stop the command after you have finished.
+
+Once instructions containing a session name are printed, use `playwright-cli` to attach the session and explore the page.
+
+```bash
+# Run the test
+PLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli
+# ...
+# ... debugging instructions for "tw-abcdef" session ...
+# ...
+
+# Attach to the test
+playwright-cli attach tw-abcdef
+```
+
+Keep the test running in the background while you explore and look for a fix.
+The test is paused at the start, so you should step over or pause at a particular location
+where the problem is most likely to be.
+
+Every action you perform with `playwright-cli` generates corresponding Playwright TypeScript code.
+This code appears in the output and can be copied directly into the test. Most of the time, a specific locator or an expectation should be updated, but it could also be a bug in the app. Use your judgement.
+
+After fixing the test, stop the background test run. Rerun to check that test passes.