pi-herdr-subagents 0.1.0

package/pi-extension/subagents/plan-skill.md

@@ -0,0 +1,203 @@
+---
+name: plan
+description: >
+  Planning workflow. Runs a pre-flight scout, then spawns the planner agent
+  which clarifies WHAT to build and figures out HOW, with the ability to
+  spawn its own scouts/researchers mid-session. Use when asked to "plan",
+  "brainstorm", "I want to build X", or "let's design". Requires the
+  subagents extension running inside herdr.
+---
+
+# Plan
+
+A planning workflow. A scout maps the relevant codebase, then an interactive planner clarifies intent + requirements and designs the technical approach, producing a `plan.md` and todos.
+
+**Announce at start:** "Let me take a quick look, then I'll send a scout to map the codebase before we start the planning session."
+
+---
+
+## The Flow
+
+```
+Phase 1: Quick Assessment (main session — 30s orientation)
+    ↓
+Phase 2: Scout (autonomous — codebase context)
+    ↓
+Phase 3: Spawn Planner Agent (interactive — clarifies WHAT, plans HOW, creates todos)
+    ↓
+    (Planner may spawn its own scouts/researchers mid-session as needed)
+    ↓
+Phase 4: Review Plan & Todos (main session)
+    ↓
+Phase 5: Execute Todos (workers — receive plan + scout context)
+    ↓
+Phase 6: Review
+```
+
+---
+
+## Phase 1: Quick Assessment
+
+Quick orientation — just enough to give the scout a focused mission:
+
+```bash
+ls -la
+find . -type f -name "*.ts" | head -20  # or relevant extension
+cat package.json 2>/dev/null | head -30
+```
+
+Spend ~30 seconds. Tech stack, project shape, and the area relevant to the user's request. This tells you what to ask the scout to focus on.
+
+---
+
+## Artifact Paths
+
+For a planning run, pick a short `<name>` (e.g. `auth-redesign`) and use a shared directory under `.pi/plans/YYYY-MM-DD-<name>/` for every deliverable. Pass explicit paths in each subagent's task and read them back with the plain `read` tool when a subagent finishes.
+
+Standard filenames:
+
+- `.pi/plans/YYYY-MM-DD-<name>/scout-context.md`
+- `.pi/plans/YYYY-MM-DD-<name>/plan.md`
+- `.pi/plans/YYYY-MM-DD-<name>/review.md` (optional, for reviewer output)
+
+---
+
+## Phase 2: Scout
+
+**Always spawn a scout before the planner.** The scout's context feeds into the planning session — it lets the planner skip re-asking questions whose answers live in the code, and gives it a solid base to design from.
+
+```typescript
+subagent({
+  name: "🔍 Scout",
+  agent: "scout",
+  task: `Analyze the codebase for [user's request area]. Map file structure, key modules, patterns, conventions, and existing code related to [feature area]. Focus on what a planner would need to understand before designing this feature.
+
+Save your findings to: .pi/plans/YYYY-MM-DD-<name>/scout-context.md`,
+});
+```
+
+**Wait for the scout to finish.** Read the scout's context file with the `read` tool — you'll pass it to the planner.
+
+The planner can spawn **additional** scouts or researchers mid-session if it hits a factual gap. That's expected — don't try to pre-scout every possible area.
+
+---
+
+## Phase 3: Spawn Planner Agent
+
+Spawn the interactive planner with the scout's context and the user's request. The planner handles everything from here: clarifying intent, compact requirements engineering, ISC, approach exploration, design validation, premortem, plan artifact, and todos.
+
+```typescript
+subagent({
+  name: "💬 Planner",
+  agent: "planner",
+  interactive: true,
+  task: `Plan: [what the user wants to build]
+
+Scout context:
+[paste scout findings here — file structure, conventions, patterns, relevant code]
+
+Save the final plan to: .pi/plans/YYYY-MM-DD-<name>/plan.md
+Create todos tagged with: <name>`,
+});
+```
+
+**The user works with the planner.** It will clarify requirements lightly (1-2 rounds of questions, not a deep spec session), propose approaches, validate the design, run a premortem, write the plan, and create todos with mandatory code examples.
+
+When done, the user presses Ctrl+D and the plan + todos are returned to the main session.
+
+### The planner may spawn its own specialists
+
+During the session, the planner can spawn:
+- **`scout`** — when a design decision depends on existing code it hasn't read
+- **`researcher`** — when a decision depends on external facts (library tradeoffs, best practices, API behaviors)
+
+These are internal to the planning session. You'll see them in herdr but don't need to intervene.
+
+### Optional: extra scout after planning
+
+If the planner significantly changed scope (new subsystems, areas the original scout didn't cover), spawn another scout targeting the new areas before workers start:
+
+```typescript
+subagent({
+  name: "🔍 Scout (updated scope)",
+  agent: "scout",
+  task: "The plan changed scope. Gather context for [new areas]. Read the plan at [plan path]. Focus on [specific files/modules the planner identified that weren't in the original scout].",
+});
+```
+
+Fold the new context into the worker tasks.
+
+---
+
+## Phase 4: Review Plan & Todos
+
+Once the planner closes, read the plan and list todos:
+
+```typescript
+todo({ action: "list" });
+```
+
+Review with the user:
+
+> "Here's what the planner produced: [brief summary]. Ready to execute, or anything to adjust?"
+
+---
+
+## Phase 5: Execute Todos
+
+Spawn workers sequentially. Each worker gets the plan path and scout context:
+
+```typescript
+// Workers execute todos sequentially — one at a time
+subagent({
+  name: "🔨 Worker 1/N",
+  agent: "worker",
+  task: "Implement TODO-xxxx. Mark the todo as done. Plan: [plan path]\n\nScout context: [paste scout summary from Phase 2, plus any re-scout from Phase 3]",
+});
+
+// Check result, then next todo
+subagent({
+  name: "🔨 Worker 2/N",
+  agent: "worker",
+  task: "Implement TODO-yyyy. Mark the todo as done. Plan: [plan path]\n\nScout context: [paste scout summary]",
+});
+```
+
+**Always run workers sequentially in the same git repo** — parallel workers will conflict on commits.
+
+---
+
+## Phase 6: Review
+
+After all todos are complete:
+
+```typescript
+subagent({
+  name: "Reviewer",
+  agent: "reviewer",
+  interactive: false,
+  task: "Review the recent changes. Plan: [plan path]",
+});
+```
+
+Triage findings:
+
+- **P0** — Real bugs, security issues → fix now
+- **P1** — Genuine traps, maintenance dangers → fix before merging
+- **P2** — Minor issues → fix if quick, note otherwise
+- **P3** — Nits → skip
+
+Create todos for P0/P1, run workers to fix, re-review only if fixes were substantial.
+
+---
+
+## ⚠️ Completion Checklist
+
+Before reporting done:
+
+1. ✅ Scout ran before the planner?
+2. ✅ Scout context was passed to the planner?
+3. ✅ All worker todos closed?
+4. ✅ Every todo has a polished commit (using the `commit` skill)?
+5. ✅ Reviewer has run?
+6. ✅ Reviewer findings triaged and addressed?

package/pi-extension/subagents/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "pi-auto-exit",
+  "version": "1.0.0",
+  "description": "Auto-exit plugin for pi-spawned Claude sessions"
+}

package/pi-extension/subagents/plugin/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/on-stop.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/pi-extension/subagents/plugin/hooks/on-stop.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# Stop hook for pi-spawned Claude sessions.
+# Writes a sentinel file when Claude completes autonomously (no user interjection).
+
+set -euo pipefail
+
+# Read JSON input from stdin
+input=$(cat)
+
+# Guard: if stop_hook_active is true, we're in a loop — bail out
+stop_hook_active=$(echo "$input" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('stop_hook_active', False))" 2>/dev/null || echo "False")
+if [ "$stop_hook_active" = "True" ]; then
+  exit 0
+fi
+
+# Guard: only act for pi-spawned sessions
+if [ -z "${PI_CLAUDE_SENTINEL:-}" ]; then
+  exit 0
+fi
+
+# Get transcript path
+transcript_path=$(echo "$input" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('transcript_path', ''))" 2>/dev/null || echo "")
+if [ -z "$transcript_path" ] || [ ! -f "$transcript_path" ]; then
+  exit 0
+fi
+
+# Count real human messages in transcript (not tool results)
+# Claude's transcript format:
+#   Human message: {"type": "user", "message": {"role": "user", "content": "..."}}
+#   Tool result:   {"type": "user", "message": {"role": "user", "content": [{"type": "tool_result", ...}]}}
+# We only count entries where content is a string (real human input)
+user_msg_count=$(python3 - "$transcript_path" <<'EOF'
+import sys, json
+
+transcript_path = sys.argv[1]
+count = 0
+with open(transcript_path, 'r') as f:
+    for line in f:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            entry = json.loads(line)
+            if entry.get('type') != 'user':
+                continue
+            content = entry.get('message', {}).get('content', '')
+            # Real human messages have string content
+            # Tool results have array content with tool_result blocks
+            if isinstance(content, str):
+                count += 1
+        except (json.JSONDecodeError, AttributeError):
+            pass
+print(count)
+EOF
+)
+
+# Always write transcript path so the watcher can copy the session file
+if [ -n "$transcript_path" ]; then
+  echo "$transcript_path" > "${PI_CLAUDE_SENTINEL}.transcript" 2>/dev/null || true
+fi
+
+# If exactly 1 user message (the initial prompt), this was autonomous — signal completion
+if [ "$user_msg_count" -eq 1 ]; then
+  # Write last_assistant_message to sentinel so the watcher gets a clean result
+  echo "$input" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('last_assistant_message', ''))" > "$PI_CLAUDE_SENTINEL" 2>/dev/null || touch "$PI_CLAUDE_SENTINEL"
+fi
+
+exit 0

package/pi-extension/subagents/session.ts

@@ -0,0 +1,180 @@
+import { appendFileSync, copyFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { randomBytes, randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+
+export interface SessionEntry {
+  type: string;
+  id: string;
+  parentId?: string;
+  [key: string]: unknown;
+}
+
+export interface MessageEntry extends SessionEntry {
+  type: "message";
+  message: {
+    role: "user" | "assistant" | "toolResult";
+    content: Array<{ type: string; text?: string; [key: string]: unknown }>;
+  };
+}
+
+export type SeededSubagentSessionMode = "lineage-only" | "fork";
+
+function getForkContentLines(parentSessionFile: string): string[] {
+  const raw = readFileSync(parentSessionFile, "utf8");
+  const lines = raw.split("\n").filter((line) => line.trim());
+
+  let truncateAt = lines.length;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    try {
+      const entry = JSON.parse(lines[i]);
+      if (entry.type === "message" && entry.message?.role === "user") {
+        truncateAt = i;
+        break;
+      }
+    } catch {
+      // ignore malformed lines
+    }
+  }
+
+  return lines.slice(0, truncateAt).filter((line) => {
+    try {
+      return JSON.parse(line).type !== "session";
+    } catch {
+      return true;
+    }
+  });
+}
+
+export function seedSubagentSessionFile(params: {
+  mode: SeededSubagentSessionMode;
+  parentSessionFile: string;
+  childSessionFile: string;
+  childCwd: string;
+}): void {
+  const header = {
+    type: "session",
+    version: 3,
+    id: randomUUID(),
+    timestamp: new Date().toISOString(),
+    cwd: params.childCwd,
+    parentSession: params.parentSessionFile,
+  };
+  const contentLines =
+    params.mode === "fork" ? getForkContentLines(params.parentSessionFile) : [];
+  const lines = [JSON.stringify(header), ...contentLines];
+
+  mkdirSync(dirname(params.childSessionFile), { recursive: true });
+  writeFileSync(params.childSessionFile, lines.join("\n") + "\n", "utf8");
+}
+
+function readEntries(sessionFile: string): SessionEntry[] {
+  const raw = readFileSync(sessionFile, "utf8");
+  return raw
+    .split("\n")
+    .filter((line) => line.trim())
+    .map((line) => JSON.parse(line) as SessionEntry);
+}
+
+/**
+ * Return the id of the last entry in the session file (current branch point / leaf).
+ */
+export function getLeafId(sessionFile: string): string | null {
+  const entries = readEntries(sessionFile);
+  return entries.length > 0 ? entries[entries.length - 1].id : null;
+}
+
+/**
+ * Return entries added after `afterLine` (1-indexed count of existing entries).
+ */
+export function getNewEntries(sessionFile: string, afterLine: number): SessionEntry[] {
+  const raw = readFileSync(sessionFile, "utf8");
+  const lines = raw.split("\n").filter((line) => line.trim());
+  return lines.slice(afterLine).map((line) => JSON.parse(line) as SessionEntry);
+}
+
+/**
+ * Find the last assistant message text in a list of entries.
+ *
+ * Falls back to the `errorMessage` field when the last assistant message has
+ * `stopReason: "error"` and no usable text content — this happens when
+ * auto-retry exhausts on a provider overload / rate limit / server error, and
+ * without this fallback the parent would silently see a stale earlier message.
+ */
+export function findLastAssistantMessage(entries: SessionEntry[]): string | null {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    if (entry.type !== "message") continue;
+    const msg = entry as MessageEntry;
+    if (msg.message.role !== "assistant") continue;
+
+    const texts = msg.message.content
+      .filter(
+        (block) =>
+          block.type === "text" && typeof block.text === "string" && block.text.trim() !== "",
+      )
+      .map((block) => block.text as string);
+
+    if (texts.length > 0 && texts.join("").trim()) return texts.join("\n");
+
+    const stopReason = (msg.message as { stopReason?: unknown }).stopReason;
+    const errorMessage = (msg.message as { errorMessage?: unknown }).errorMessage;
+    if (
+      stopReason === "error" &&
+      typeof errorMessage === "string" &&
+      errorMessage.trim() !== ""
+    ) {
+      return `Subagent error: ${errorMessage.trim()}`;
+    }
+  }
+  return null;
+}
+
+/**
+ * Append a branch_summary entry to the session file.
+ * Returns the new entry's id.
+ */
+export function appendBranchSummary(
+  sessionFile: string,
+  branchPointId: string,
+  fromId: string | null,
+  summary: string,
+): string {
+  const id = randomBytes(4).toString("hex");
+  const entry = {
+    type: "branch_summary",
+    id,
+    parentId: branchPointId,
+    timestamp: new Date().toISOString(),
+    fromId: fromId ?? branchPointId,
+    summary,
+  };
+  appendFileSync(sessionFile, JSON.stringify(entry) + "\n", "utf8");
+  return id;
+}
+
+/**
+ * Copy the session file to destDir for parallel worker isolation.
+ * Returns the path of the copy.
+ */
+export function copySessionFile(sessionFile: string, destDir: string): string {
+  const id = randomBytes(4).toString("hex");
+  const dest = join(destDir, `subagent-${id}.jsonl`);
+  copyFileSync(sessionFile, dest);
+  return dest;
+}
+
+/**
+ * Read new entries from sourceFile (after afterLine), append them to targetFile.
+ * Returns the appended entries.
+ */
+export function mergeNewEntries(
+  sourceFile: string,
+  targetFile: string,
+  afterLine: number,
+): SessionEntry[] {
+  const entries = getNewEntries(sourceFile, afterLine);
+  for (const entry of entries) {
+    appendFileSync(targetFile, JSON.stringify(entry) + "\n", "utf8");
+  }
+  return entries;
+}