pi-pier 0.2.3 → 0.2.5

package/README.md

@@ -43,10 +43,9 @@ The installer also verifies node / pi / herdr versions, probes local paths, and
 | Tool | Purpose |
 |---|---|
 | `todo_write` | Full-replacement todo list. Session JSONL is the single source of truth; correct rollback on branch switches. Projected live onto the pane title (`▶i ○p ■b ✓c (N/M) · current task`). `/todos` command to view/edit/unblock |
-| `subagent` | Delegate self-contained subtasks to an isolated pi session in its own herdr pane (separate context window). Foreground / parallel / background modes |
-| `list_agents` | Live state of background subagents (running / idle + panes) |
-| `send_message` | Follow-up work for a subagent (queued if busy, wakes if idle) |
-| `interrupt_agent` | Stop a subagent's current turn; it stays alive for more messages |
+| `subagent` | Delegate self-contained subtasks to an isolated pi session in its own herdr pane. Actions: `spawn` (default; foreground / parallel / background), `list`, `send`, `interrupt`, `resume` |
+| `terminal` | Persistent interactive shells in dedicated herdr panes. Actions: `open`, `send`, `read`, `signal`, `close`, `list` |
+| `ask_user_question` | Human gate: pane shows blocked in herdr while waiting |
 
 ### Behaviors
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-pier",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "pier: pi extension that fuses pi agent sessions with the herdr pane/tab orchestrator — todo_write loop closure + interactive subagents in isolated panes",
   "license": "MIT",
   "type": "module",

package/skills/pi-herdr-workflow/SKILL.md

@@ -2,85 +2,157 @@
 name: pi-herdr-workflow
 description: >-
   How to use the pi-herdr workbench fusion: todo_write discipline, subagent
-  delegation (foreground/parallel/background), list_agents/send_message/
-  interrupt_agent, and how the human watches everything in herdr panes.
+  delegation (foreground/parallel/background via action spawn/list/send/
+  interrupt/resume), terminal persistent shells, and how the human watches
+  everything in herdr panes.
   Load when the user asks about multi-step plans, delegating subtasks,
   background work, or checking on running subagents.
 license: MIT
 ---
 
-# pi-herdr 工作台工作流
-
-你在一个 herdr 终端工作区（pane）里运行。本 skill 教你把 `todo_write` 与
-`subagent` 工具用好；人类在 herdr 的 TUI 里实时观察：每个 pane 的窗格头
-显示 `▶x ○y ■b ✓z · 当前任务`，语义状态（working/blocked/idle）上卷到侧边栏。
-
-## 1. todo 纪律（全量替换语义）
-
-- `todo_write` 每次调用提交**完整列表**（last-wins），没有部分更新。
-- 条目 = `content`（非空、唯一、5–10 词的命令式短语，写"做什么"不写"怎么做"，**不带编号前缀**）+ `status`（pending | in_progress | completed | blocked | abandoned）。
-  - `blocked` = 在等外部条件（信息、人、别的系统），必须带 `blocker` 说明等什么；`abandoned` = 显式放弃（不删条目，保留计划痕迹）。
-  - 多阶段计划用可选 `phase` 分组（≤30 字）；单阶段就不写 phase。
-- 保持列表精简（≤15 条）：一条 = 一个有意义的交付单元，不是微步骤。
-- 正在推进的标 `in_progress`（真正并行时才允许多条）；**完成立即标 completed**。
-- **测试失败/实现不完整/有未解决错误时绝不算 completed**——保持 in_progress，或改成 blocked 并说明 blocker。
-- **绝不把 todo_write 当成一轮里的唯一工具调用**——搭着真实工作一起提交。
-- 记不清某条任务的原文时，从上一轮 todo_write 结果里找，**不许凭记忆编**（防幻影条目）。
-- **不要**把已委派给子代理的工作写进自己的 todo——那是子代理自己的职责；
-  你的列表只跟踪你自己的工作。等子代理结果回流后再验收归档。
-- 多子代理协作时在 content 里写清**文件所有权**（例如 "重构 auth 模块（只碰 src/auth/）"），
-  避免两个 agent 抢同一文件。
-- **你是被委派的工作 pane**（`PI_HERDR_SUBAGENT=1`）时，本插件自动执行严格模式：
-  你的列表任何时候**至多一条 in_progress**（多写会被归一化），全部完成会自动晋升下一条 pending。
-  你是主控 pane 时保持并行语义，纪律由本节承担。
-
-## 2. 子代理委派
-
-子代理 pane 跑的是**交互式 pi TUI**（独立会话）：人类可以随时进入该 pane
-直接与子代理对话；你的委派 prompt 会以消息形式出现在它的对话里。
-
-### 选型
-- **前台**（默认）：调用后等待结果返回。适合"下一步依赖其结果"的委派。
-- **后台**（`run_in_background: true`）：立即返回 `agentId`；子代理在独立
-  pane 常驻运行。适合长任务/并行推进。它会**持续存在**（有自己的持久会话），
-  结算时你会收到一条 "Background subagent <id> finished..." 通知消息。
-- 一条消息里的多个 subagent 调用会并行执行（上限 4 并发）。
-- 可选 `role`（如 `advisor`）只是标签：v1 不改工具面、不改生命周期，与普通 task 一样走 TTL；省略 = `task`。复活走 `resume_subagent`，不要假设 pane 会自动补回来。
-
-### 任务 tab 分组（`tab` 参数）
-- 每个委派默认开一个**以任务命名的新 tab**（名字取自 `description`）。
-- 一组相关的子任务用同一个 `tab` 名字收进同一个 tab（例如网络调研 + 现状
-  摸索都用 `tab: "调研"`），人类在 herdr 里一个 tab 内看完全部相关 pane。
-- 名字要短（≤20 字）、人类一眼能懂；tab 栏就是任务板。
-- 不要为了少开 tab 而把无关任务塞进同一个 tab；一个 tab = 一个任务目标。
-- **任务 tab 是临时的**：tab 内全部子代理结算后（默认宽限约 10 分钟）tab
-  会自动关闭——不要假设它的 pane 长期存在；需要回看/继续时用
-  `resume_subagent(taskId)` 从历史复活，而不是引用已关的 pane。
-
-### prompt 纪律
-- prompt 必须**自包含**：子代理看不到你的对话历史，只有这段 prompt。
-- 明确输入（哪些文件/事实）、明确产出（交什么）、明确边界（不碰什么）。
-- 用文件/工件传递共享上下文，不要把大段内容塞进 prompt。
-- 独立任务才委派；互相依赖的工作拆给同一子代理。
-
-### 后台子代理的后续管理
-- `list_agents`：查看全部后台子代理与状态（running/idle）。
-- `send_message(agentId, message)`：给子代理追加任务（FIFO；已结算的子代理
-  会被唤醒继续干）。
-- `interrupt_agent(agentId)`：打断子代理当前轮次（它仍驻留，可继续 send_message）。
-- 子代理结算后不要重新委派同一个 agentId 之外的新任务时，可再 send_message 唤醒。
-
-## 3. 人类闸门
-
-- 需要人类决策（审批、取舍、方向选择）时，用 `ask_user_question`（本插件提供）——
-  等待回答期间，你的 pane 在 herdr 里呈 **blocked** 状态，人类会看到并介入；
-  答案会作为工具结果回到你的上下文，然后继续工作。
-- 子代理 pane 在 herdr 里可被人类直接进入交互；你的委派描述（pane 标签）
-  要写得人类一眼能懂。
-
-## 4. 多 agent 纪律（工程实践映射）
-
-- 你是仲裁者：验收每个子代理的输出，再合入你的工作；不要把仲裁权下放。
-- 关键结论安排独立复核（换个子代理 reviewer 复核），不盲信单一子代理。
-- 同构的并行子代理会犯同样的错：给不同子代理不同的任务边界与产出格式。
-- 委派后继续做你自己的事，不要干等（前台调用除外）。
+# pi-herdr workbench workflow
+
+You run inside a herdr terminal pane. This skill is how to use `todo_write` and
+`subagent` well. The human watches live in herdr: each pane header shows
+`▶x ○y ■b ✓z · current task`, and semantic state (working / blocked / idle)
+rolls up to the sidebar.
+
+## 1. Todo discipline (full-replace semantics)
+
+- Every `todo_write` submits the **entire list** (last-wins). There is no partial update.
+- An item is `content` (non-empty, unique, 5–10 word imperative phrase: *what*, not *how*, **no numeric prefix**) + `status` (`pending` | `in_progress` | `completed` | `blocked` | `abandoned`).
+  - `blocked` = waiting on an external condition (info, a person, another system) and **must** include `blocker` saying what is missing; `abandoned` = explicit drop (keep the row; do not delete the plan trail).
+  - Multi-phase plans may group with optional `phase` (≤30 chars). Single-phase: omit `phase`.
+- Keep the list small (≤15): one item = one meaningful deliverable, not a micro-step.
+- Mark what you are actually doing `in_progress` (multiple only when truly parallel); **mark `completed` the moment it is done**.
+- **Never mark completed when tests fail, the implementation is incomplete, or errors remain** — stay `in_progress`, or switch to `blocked` with a blocker.
+- **Never make `todo_write` the only tool call in a turn** — batch it with real work.
+- If you forget an item's exact wording, copy it from the previous `todo_write` result. **Do not invent from memory** (phantom items).
+- **Do not** put work you already delegated to a subagent on *your* todo list — that is the subagent's job. Your list tracks *your* work. Accept and archive after the result comes back.
+- When several subagents collaborate, put **file ownership** in `content` (e.g. "refactor auth (only src/auth/)") so two agents do not fight over the same file.
+- When **you** are a delegated worker pane (`PI_HERDR_SUBAGENT=1`), this plugin enforces strict mode: **at most one `in_progress`** at a time (extras are normalized), and finishing the current item auto-promotes the next `pending`. The master pane keeps parallel semantics; this section is the discipline.
+
+## 2. Subagent delegation
+
+A subagent pane is an **interactive pi TUI** (independent session). A human can enter that pane and talk to it at any time. Your delegation prompt appears as a message in its conversation.
+
+The `subagent` tool has 5 operations controlled by the `action` parameter (default: `spawn`):
+
+### spawn (default action)
+
+Create a subagent in a new pane:
+- **Foreground** (default): the call waits for a result. Use when the next step depends on it.
+- **Background** (`run_in_background: true`): returns `agentId` immediately; the subagent keeps running in its own pane. Use for long / parallel work. It **persists** (own session). On settle you get a "Background subagent <id> finished..." notice.
+- Multiple `subagent` calls (with `action: "spawn"`) in one message run in parallel (cap 4).
+- Optional `role` (e.g. `advisor`) matches a profile when found; unknown names are labels only.
+
+**Task-tab grouping** (`tab`):
+- Each delegation defaults to a **new tab named from `description`**.
+- Related subtasks share one `tab` name (e.g. web research + status probe both `tab: "research"`) so the human sees every related pane in one herdr tab.
+- Keep names short (≤20 chars) and obvious; the tab bar *is* the task board.
+- Do not cram unrelated work into one tab to "save tabs". One tab = one goal.
+- **Task tabs are temporary**: after every subagent in the tab has settled (default grace ~10 minutes) the tab closes. Do not assume those panes last. To review or continue, use `action: "resume"` from history — do not cite a closed pane.
+
+**Prompt discipline**:
+- The prompt must be **self-contained**: the subagent cannot see your conversation, only this prompt.
+- State inputs (which files / facts), outputs (what to deliver), and bounds (what not to touch).
+- Share context via files / artifacts. Do not dump large blobs into the prompt.
+- Delegate only independent work; dependent steps go to the same subagent.
+
+### list
+
+Show all background subagents with status (`running` / `idle` / `blocked`), `agentId`, and last activity.
+
+Call: `subagent(action: "list")`
+
+### send
+
+Append follow-up message to background subagent:
+- If working: delivered at next tool-gap (steering, seconds).
+- If idle: wakes for new turn.
+- After settle, `send` to wake it; do not spawn duplicate.
+
+Call: `subagent(action: "send", agentId: "<id>", message: "...")`
+
+### interrupt
+
+Abort subagent's current turn (fire-and-return). Pane stays; can `send` again.
+
+Call: `subagent(action: "interrupt", agentId: "<id>")`
+
+### resume
+
+Revive finished subagent from ledger by `taskId`. Opens saved conversation in new pane; then `send` work.
+
+The ledger is an append-only JSONL file at `~/.pi/agent/herdr-pi/history/<flattened-cwd>/history.jsonl`, one row per status change. Use `list` for live panes from this session; for tasks from earlier sessions or closed panes, read/grep the ledger for the `taskId`.
+
+Call: `subagent(action: "resume", taskId: "<uuid>")`
+
+## 3. Human gate
+
+- For a human decision (approval, tradeoff, direction), use `ask_user_question` (this plugin). While waiting, your pane is **blocked** in herdr so the human can see and intervene. The answer comes back as the tool result, then you continue.
+- A human can enter a subagent pane directly. Write the delegation `description` (pane label) so a human understands it at a glance.
+
+## 4. Multi-agent engineering rules
+
+- You are the arbiter: accept each subagent's output, then merge it. Do not outsource arbitration.
+- Independent review for critical conclusions (a different subagent as reviewer). Do not trust a single worker blindly.
+- Homogeneous parallel workers make the same mistakes: give them different bounds and output shapes.
+- After delegating, keep doing your own work. Do not idle-wait (except a foreground call).
+
+## 5. Terminal management (master only)
+
+The `terminal` tool has 6 operations for persistent shell sessions (dev servers, REPLs, stateful work):
+
+### open
+
+Create a persistent interactive terminal (resident shell in its own herdr pane) and return its `terminal_id`.
+
+The shell keeps its cwd, environment variables, and background processes across `terminal` calls — use it for dev servers, REPLs, or multi-step shell work instead of one-shot bash calls.
+
+Call: `terminal(action: "open", cwd: "<path>")`
+Returns: `terminal_id` and readiness status (prompt detected or busy).
+
+### send
+
+Send a text command (plain text only, no ANSI escapes) to a persistent terminal; Enter is appended automatically.
+
+Returns after the keystrokes are delivered — poll with `action: "read"` for output (long-running commands keep producing output across reads).
+
+Call: `terminal(action: "send", terminal_id: "<id>", text: "npm run dev")`
+
+### read
+
+Read new output from a persistent terminal since your last read (cursor-based increment; the first read returns the recent buffer).
+
+Parameters:
+- `terminal_id`: your terminal from `open`. Alternatively `pane_id`: a pane in this session's own tab (narrow scope by design).
+- `max_chars`: output cap for this read.
+
+Output is ANSI-stripped and bounded; if the buffer scrolled past your last read you get a reset marker plus the current tail. Detecting a fullscreen TUI program (vim/less/top) returns an error with suggestions instead of garbage.
+
+Call: `terminal(action: "read", terminal_id: "<id>")`
+
+### signal
+
+Send a control key to a persistent terminal: ctrl+c (interrupt), ctrl+d (EOF), ctrl+z (suspend), esc, enter.
+
+Use ctrl+c to stop a running command; anything beyond this whitelist is outside the terminal seam.
+
+Call: `terminal(action: "signal", terminal_id: "<id>", key: "ctrl+c")`
+
+### close
+
+Close a persistent terminal (kills its shell process tree and removes the pane).
+
+Terminal state does not survive close — persist anything you need to files first.
+
+Call: `terminal(action: "close", terminal_id: "<id>")`
+
+### list
+
+List this session's persistent terminals with open/closed and pane-liveness status.
+
+Entries whose pane is gone (human closed it, restart) are marked closed — terminal sessions do not survive pane closure or restarts; persist state to files instead of relying on terminal reuse.
+
+Call: `terminal(action: "list")`