pi-squad 0.1.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-squad
 
-Multi-agent collaboration extension for [pi](https://github.com/badlogic/pi-mono). Decomposes complex tasks into subtasks, assigns specialist agents, manages dependencies, and runs them in parallel — with a live TUI widget, side panel, and full slash command interface.
+Multi-agent collaboration extension for [pi](https://github.com/badlogic/pi-mono). Decomposes complex tasks into subtasks, assigns specialist agents, manages dependencies, runs them in parallel with automatic QA rework loops — all with a live TUI widget, overlay panel, and slash commands.
 
 ## Install
 
@@ -12,7 +12,7 @@ pi install npm:pi-squad
 ln -sf /path/to/pi-squad/src ~/.pi/agent/extensions/squad
 ```
 
-Pi auto-discovers extensions on startup. No build step.
+Pi auto-discovers extensions on startup. No build step required.
 
 ## Quick Start
 
@@ -22,7 +22,7 @@ Ask pi to do something complex. It calls the `squad` tool automatically:
 > Build a REST API with authentication, tests, and documentation
 ```
 
-Or be explicit:
+The planner agent reads your codebase and creates a task breakdown automatically. Or be explicit:
 
 ```
 > Use squad: goal="Build task API", tasks=[
@@ -34,35 +34,44 @@ Or be explicit:
 
 ### What Happens
 
-1. Extension creates tasks, starts the scheduler
+1. Planner analyzes the codebase and creates tasks (or uses your predefined tasks)
 2. A **live widget** appears above the editor showing task status
-3. Agents spawn as separate pi processes, work in parallel where deps allow
-4. When complete, pi reports the summary
+3. Agents spawn as separate pi processes, work in parallel where dependencies allow
+4. QA agents can trigger **automatic rework loops** when they find bugs
+5. When complete, pi reports the summary — notifications don't pollute message history
+6. Multiple squads can run concurrently across different projects
 
 ## User Interface
 
 ### Widget (above editor)
 
-Always visible when a squad is active. Updates every 2 seconds.
+Always visible when a squad is active. Debounced updates with cache key to avoid flicker.
 
 ```
-⏳ squad Build task API 1/3 $0.58 3m12s  ctrl+q panel · /squad
-  ✓ api (backend) Created CRUD REST API with validation
-  ⏳ tests (qa) → bash npm test
+⏳ squad Build task API 2/3 $0.58 3m12s  ^q detail · /squad msg
+  ✓ api (backend) 2m12s Created CRUD REST API with validation
+  ⏳ tests (qa) 45s → bash npm test
   ◻ docs (docs) ← api
 ```
 
+Features:
+- Per-task elapsed time (warning color after 3 minutes)
+- Live tool call preview for running tasks
+- Stale detection — shows `⏳ idle` when agent has no output for 2+ minutes
+- Responsive — caps visible tasks on small terminals, shows `+N more` overflow
+- Completion duration for finished tasks
+
 ### Status Bar (footer)
 
 ```
-⏳ squad 1/3 $0.58
+⏳ squad 2/3 $0.58
 ```
 
 ### Panel (Ctrl+Q)
 
-Side panel on wide screens, centered overlay on narrow screens. Press `Ctrl+Q` to toggle focus between the panel and the editor.
+Centered overlay panel with proper lifecycle management. Press `Ctrl+Q` to open/close.
 
-**Task list:**
+**Task list** with sticky summary at bottom:
 ```
 ╭─ squad: Build task API ─────────────────────╮
 │ ▸ ✓ api (backend) 2m12s                     │
@@ -72,23 +81,26 @@ Side panel on wide screens, centered overlay on narrow screens. Press `Ctrl+Q` t
 │ ── tests (live) ─────────────────────        │
 │ → bash npm test                              │
 │                                              │
-│ 1/3 · $0.58 · 3m                            │
+│ 2/3 · $0.58 · 3m                            │
 ├──────────────────────────────────────────────┤
-│ ↑↓ nav  ⏎ msgs  m send  p pause  ^q switch │
+│ ↑↓ nav  ⏎ msgs  m send  p pause  ^q close  │
 ╰──────────────────────────────────────────────╯
 ```
 
-**Message view** (Enter on a task):
+**Message view** (Enter on a task) — long text wraps instead of truncating:
 ```
 ╭─ tests · qa ⏳ ─────────────────────────────╮
 │ 10:03 qa                                     │
-│   Starting test implementation               │
+│   Starting test implementation. Will cover   │
+│      all CRUD endpoints, validation, and     │
+│      edge cases for empty input.             │
 │ 10:04 qa                                     │
 │   → write src/tasks.test.js                  │
 │ 10:05 YOU                                    │
 │   Also test edge cases for empty input       │
+│ ─ 65% ─ 24 msgs ─ ↑↓ scroll                │
 ├──────────────────────────────────────────────┤
-│ ↑↓ scroll  m send  esc back  ^q switch      │
+│ ↑↓ scroll  m send  esc back  ^q close       │
 ╰──────────────────────────────────────────────╯
 ```
 
@@ -99,37 +111,111 @@ Side panel on wide screens, centered overlay on narrow screens. Press `Ctrl+Q` t
 | `/squad` or `/squad select` | Pick a squad to view (interactive selector) |
 | `/squad list` | List squads for current project |
 | `/squad all` | List all squads across all projects |
+| `/squad agents` | List, view, edit, enable/disable agents |
+| `/squad agents <name>` | Quick view of a specific agent |
 | `/squad msg [agent] text` | Send message to a running agent |
-| `/squad widget` | Toggle live widget |
+| `/squad widget` | Toggle live widget on/off |
 | `/squad panel` | Toggle overlay panel |
 | `/squad cancel` | Cancel running squad |
 | `/squad clear` | Dismiss widget, deactivate view |
+| `/squad cleanup` | Delete squad data (select one or all) |
+| `/squad cleanup all` | Delete all squad data |
+| `/squad enable` | Enable pi-squad (tools, widget, system prompt) |
+| `/squad disable` | Disable pi-squad completely |
 
 ## Keyboard Shortcuts
 
 | Key | Context | Action |
 |---|---|---|
-| `Ctrl+Q` | Main editor | Open/focus squad panel |
-| `Ctrl+Q` | Panel focused (wide) | Return focus to editor (panel stays visible) |
-| `Ctrl+Q` | Panel focused (narrow) | Hide panel |
-| `↑↓` | Panel | Navigate tasks / scroll messages |
+| `Ctrl+Q` | Anywhere | Toggle squad panel overlay |
+| `↑↓` or `jk` | Panel | Navigate tasks / scroll messages |
 | `Enter` | Panel task list | View task messages |
 | `Esc` | Panel message view | Back to task list |
 | `m` | Panel | Send message to selected task's agent |
 | `p` | Panel task list | Pause/resume task |
 | `x` | Panel task list | Cancel task |
-| `q` | Panel task list | Release focus / hide |
+| `q` | Panel task list | Close panel |
 
 ## Tools (LLM-callable)
 
 | Tool | Description |
 |---|---|
 | `squad` | Start a squad (non-blocking, returns immediately) |
-| `squad_status` | Check progress, filtered by project |
+| `squad_status` | Check progress, costs, task states |
 | `squad_message` | Send message to a running agent via `steer()` |
-| `squad_modify` | Add/remove/pause/resume/cancel tasks |
+| `squad_modify` | Add/cancel/pause/resume tasks, or cancel/resume entire squad |
+
+The main pi agent sees squad state in its system prompt automatically (`<squad_status>` block) and can relay messages, add tasks, or check status on your behalf. Squad notifications use `sendMessage({ display: true })` so they don't pollute the LLM's message history.
+
+## Multiple Concurrent Squads
+
+Multiple squads can run in parallel from the same pi session. Each squad has its own scheduler, agent pool, and disk state.
+
+```
+> Build the auth API          → starts squad-1
+> Build the dashboard UI      → starts squad-2 (runs in parallel)
+
+/squad list                   → see both, select which to view
+/squad select                 → switch widget/panel focus
+```
+
+All squads run independently in the background. The widget/panel shows whichever squad you're focused on.
+
+## QA Rework Loop
+
+When a QA agent outputs `## Verdict: FAIL`, the scheduler automatically:
+
+1. **Parses** the failure details from QA output
+2. **Creates a rework task** for the original agent with QA feedback injected into its system prompt
+3. **Creates a retest task** for QA, blocked until the rework completes
+4. After fix, QA re-tests. If still failing, loops up to `maxRetries` (default: 2)
+5. If retry limit exceeded, **escalates** to the main agent for human decision
+
+### Example flow
+
+```
+auth (backend) ✓
+  → qa-auth (qa) ✓ — found race condition bug
+    → auth-fix-1 (backend) ✓ — fixed it [auto-created]
+      → qa-auth-retest-1 (qa) ✓ — retested, found another issue
+        → auth-fix-2 (backend) ✓ — fixed again [auto-created]
+          → qa-auth-retest-2 (qa) ✓ — all tests pass ✓
+```
+
+### What the rework agent sees
+
+The rework agent's system prompt includes:
+- Original task output (what was built)
+- QA feedback (what failed, with specific issues)
+- Instructions to make targeted fixes, not rewrite everything
 
-The main pi agent sees squad state in its system prompt automatically and can relay messages, add tasks, or check status on your behalf.
+### QA verdict format
+
+QA agents should end their output with a structured verdict:
+
+```markdown
+## Verdict: PASS
+All 42 tests passing. No issues found.
+```
+
+```markdown
+## Verdict: FAIL
+
+## Issues
+1. **[src/auth.ts:45]** JWT expiry not enforced
+   - Expected: 401 for expired tokens
+   - Got: 200 (token accepted)
+2. **[src/routes.ts:23]** Missing rate limit on /login
+```
+
+### Configuration
+
+```
+config: {
+  maxConcurrency: 3,  // parallel agents (default: 2)
+  maxRetries: 2,      // rework attempts before escalation (default: 2)
+}
+```
 
 ## Sending Messages to Agents
 
@@ -141,30 +227,50 @@ Three ways:
    /squad msg backend Use postgres instead of SQLite
    ```
 
-2. **`m` key** — press in the panel (task list or message view), opens input dialog
+2. **`m` key** — press in the panel, opens input dialog
 
 3. **Natural chat** — tell pi, it relays automatically
    ```
    > Tell the backend agent to use argon2 for password hashing
    ```
 
+Messages are delivered in real-time via RPC `steer()` if the agent is running, or queued for delivery when the agent spawns.
+
 ## Agents
 
-11 specialist agents are bundled. On first run, they're copied to `~/.pi/squad/agents/` for editing.
+### 11 Bundled Agents
 
-| Agent | Specialty |
-|---|---|
-| **planner** | Task breakdown and planning |
-| **fullstack** | General-purpose coding |
-| **architect** | System design, architecture |
-| **backend** | APIs, databases, server-side |
-| **frontend** | UI/UX, React, CSS |
-| **debugger** | Root cause analysis |
-| **qa** | Testing, verification |
-| **security** | Security audits |
-| **docs** | Technical writing |
-| **researcher** | Code exploration, analysis |
-| **devops** | CI/CD, infrastructure |
+On first run, copied to `~/.pi/squad/agents/` for editing.
+
+| Agent | Specialty | Tags |
+|---|---|---|
+| **planner** | Task breakdown and planning | planning, architecture |
+| **fullstack** | General-purpose coding | general, coding |
+| **architect** | System design, architecture | architecture, design |
+| **backend** | APIs, databases, server-side | api, server, database |
+| **frontend** | UI/UX, React, CSS | react, ui, css |
+| **debugger** | Root cause analysis | debugging, bugs |
+| **qa** | Testing, verification | testing, qa, e2e |
+| **security** | Security audits | security, audit |
+| **docs** | Technical writing | documentation, readme |
+| **researcher** | Code exploration, analysis | research, analysis |
+| **devops** | CI/CD, infrastructure | ci-cd, docker |
+
+### Agent Management
+
+Use `/squad agents` for interactive management:
+
+```
+/squad agents              — list all, select to view/edit
+/squad agents backend      — quick view of specific agent
+```
+
+Actions available per agent:
+- **View details** — name, role, model, tools, tags, prompt, file path
+- **Edit in editor** — opens the agent JSON file
+- **Change model** — set a specific model or use default
+- **Toggle tools** — restrict to specific tools or enable all
+- **Enable/Disable** — disabled agents are hidden from the planner
 
 ### Custom Agents
 
@@ -178,66 +284,173 @@ Create a JSON file in `~/.pi/squad/agents/` (global) or `{project}/.pi/squad/age
   "model": "anthropic/claude-sonnet-4-20250514",
   "tools": null,
   "tags": ["ml", "pytorch", "data"],
-  "prompt": "You are an ML engineer specializing in PyTorch..."
+  "prompt": "You are an ML engineer specializing in PyTorch...",
+  "disabled": false
 }
 ```
 
-Project-local agents override global agents with the same name.
+- `model`: `null` = pi default. Override with any model ID your provider supports.
+- `tools`: `null` = all tools. Array like `["bash", "read", "write", "edit"]` to restrict.
+- `tags`: Used by the planner to match agents to tasks automatically.
+- `disabled`: `true` = hidden from planner, tasks assigned to this agent will fail.
+- Project-local agents override global agents with the same name.
 
 ## How Agents Collaborate
 
-- **Dependencies** — task B waits for task A before starting
-- **Chain context** — task A's output is injected into task B's system prompt
-- **@mentions** — agents write `@agentname message` to talk to each other in real time
-- **Human messages** — sent via panel, `/squad msg`, or the LLM's `squad_message` tool
-- **Shared knowledge** — decisions and findings tracked in `knowledge/*.jsonl`
+### Chain Context (primary)
+
+When task A completes, its **full output** is injected into task B's system prompt as a `# Completed Dependencies` section. Downstream agents read what was built and extend it — no need for explicit communication.
+
+### Shared Filesystem
+
+All agents work in the same project directory. Upstream agents create files, downstream agents read and modify them. Each agent is instructed to read files before writing to avoid conflicts.
 
-## Data
+### Sibling Awareness
 
-All state lives in `~/.pi/squad/` (global). No database, no daemon, no external services.
+When agents run in parallel, each sees the other's status and modified files in their system prompt:
 
 ```
-~/.pi/squad/
-├── agents/*.json              — global agent definitions
-└── {squad-id}/
-    ├── squad.json             — metadata (goal, status, cwd, agents, config)
-    ├── context.json           — live state snapshot
-    └── {task-id}/
-        ├── task.json          — task metadata + output
-        └── messages.jsonl     — conversation log
+# Sibling Tasks
+- template-engine [in_progress] — fullstack — Create HTML templates
+
+## Files Modified by Other Agents
+**fullstack:** src/templateEngine.js, templates/post.html
+⚠️ Coordinate with the owning agent before editing files listed above.
+```
+
+### @Mention Routing
+
+Agents can message each other in real-time:
+
 ```
+Agent output: "@frontend what token format do you need?"
+→ Router parses @mention
+→ Delivers to running agent via steer()
+→ Or queues for delivery when agent spawns
+```
+
+### Block Detection
 
-Each squad stores its project `cwd` in `squad.json`. The `/squad list` command filters by current project. `/squad all` shows everything.
+If an agent says "I'm blocked" or "cannot proceed", the router detects it and escalates to the main agent.
 
-Project-local agent overrides: `{project}/.pi/squad/agents/`
+## Session Resilience
 
-## Multi-Project Support
+### Crash Recovery
 
-Squads are stored globally but scoped to projects by their `cwd` field. Multiple pi sessions can run squads for different projects simultaneously.
+When a pi session crashes (tmux dies, SIGKILL, etc.):
+- In-progress tasks are automatically **suspended** on next startup
+- Squad is marked as **paused**
+- Only squads with completed tasks trigger a notification
+- Squads with zero progress are silently paused (no noise)
+
+### Resume
+
+Resume a paused squad across sessions:
 
 ```
-Session A (cwd: /projects/api)      Session B (cwd: /projects/web)
-  └── squad "build-auth"              └── squad "build-dashboard"
-      both stored in ~/.pi/squad/
-      filtered by cwd when listing
+> Resume the squad
 ```
 
-`/squad list` shows squads for the current project. `/squad all` shows all projects.
+The agent calls `squad_modify({ action: "resume" })`, which:
+1. Finds the latest paused squad for the project
+2. Creates a fresh scheduler from disk state
+3. Wires up event handlers for completion/failure/escalation
+4. Restarts suspended tasks
+
+All state lives on disk — squads are fully reconstructable from JSON files.
+
+### Spawn Resilience
 
-Any pi session can browse and view any squad with `/squad select` or `/squad all`.
+Child agent processes occasionally fail during startup (transient resource pressure). The scheduler automatically retries once after a 2-second delay. If the retry also fails, the task is marked failed with a diagnostic log including PID, exit code, stderr, and stdout line count.
 
 ## Governance
 
-- **Dependency enforcement** — blocked tasks never spawn, auto-unblock when deps complete
-- **Concurrency control** — configurable `maxConcurrency` (default: 2)
-- **Health monitoring** — idle warning (3m), stuck intervention (5m), loop detection, 30m hard ceiling
-- **@mention routing** — parsed from agent output, delivered via RPC `steer()`
-- **File conflict tracking** — warns agents about files modified by others
+| Mechanism | What it does |
+|---|---|
+| **Dependency DAG** | Blocked tasks never spawn. Auto-unblock when deps complete. |
+| **Concurrency control** | `maxConcurrency` limits parallel agents (default: 2) |
+| **Health monitoring** | Idle warning (3m), stuck intervention (5m), loop detection (same tool 5x), 30m hard ceiling |
+| **QA rework loop** | Auto-creates fix + retest tasks when QA fails (up to `maxRetries`) |
+| **Spawn retry** | Retries once on transient startup failures, then fails with diagnostics |
+| **File tracking** | Warns agents about files modified by other agents |
+| **@mention routing** | Parsed from output, delivered via RPC `steer()` |
+| **Escalation** | Blocked agents, stuck agents, retry limit, spawn failure → notify main agent |
+| **Clean notifications** | Uses `sendMessage({ display: true })` — visible to user, not in LLM history |
+
+## Data Layout
+
+All state lives in `~/.pi/squad/`. No database, no daemon, no external services. Writes are atomic (temp file + rename). JSONL reads are fault-tolerant (skip corrupt lines from concurrent writes).
+
+```
+~/.pi/squad/
+├── agents/                    — agent definitions (user-editable)
+│   ├── backend.json
+│   ├── qa.json
+│   └── ...
+└── {squad-id}/                — one directory per squad
+    ├── squad.json             — goal, status, config, cwd
+    ├── context.json           — live state snapshot
+    ├── knowledge/             — shared decisions/findings
+    │   ├── decisions.jsonl
+    │   └── findings.jsonl
+    └── {task-id}/             — one directory per task
+        ├── task.json          — status, agent, output, usage, retryOf, qaFeedback
+        └── messages.jsonl     — full conversation log
+```
+
+## Architecture
+
+```
+src/
+├── index.ts              — extension entry: tools, commands, widget, panel, lifecycle
+├── types.ts              — Squad, Task, Agent, Message types
+├── store.ts              — JSON/JSONL file I/O with atomic writes, fault-tolerant reads
+├── scheduler.ts          — dependency DAG, concurrency, rework loop, spawn retry, task lifecycle
+├── agent-pool.ts         — pi RPC process spawn/steer/kill, diagnostic logging
+├── protocol.ts           — system prompt builder (7 sections + rework context)
+├── router.ts             — @mention parsing, cross-agent messaging
+├── monitor.ts            — health checks: idle/stuck/loop/ceiling
+├── supervisor.ts         — quality review, block analysis
+├── planner.ts            — one-shot goal decomposition via LLM
+├── panel/
+│   ├── squad-panel.ts    — overlay component (ctx.ui.custom with done())
+│   ├── squad-widget.ts   — string[] widget with debounce and cache
+│   ├── task-list.ts      — task tree with status icons, elapsed time, sticky summary
+│   └── message-view.ts   — scrollable message log with word wrap, fixed-height layout
+├── skills/
+│   ├── supervisor/       — teaches main agent to supervise squads
+│   ├── squad-protocol/   — communication rules for child agents
+│   ├── collaboration/    — team interaction patterns
+│   └── verification/     — verify-before-done + structured QA verdicts
+└── agents/_defaults/     — 11 bundled agent definitions
+```
+
+## Test Results
+
+### Simple (3 tasks, linear chain)
+- URL shortener API: 3 tasks, 30 turns, $0.83, 4.5 minutes
+- Backend → QA → Docs, all passing
+
+### Medium (5 tasks, planner-decomposed)
+- Quiz API: 5 tasks, 82 turns, $3.11, 14 minutes
+- Planner auto-created: architect → backend → fullstack → QA + docs
+- 111 vitest tests passing, 3,637 lines of code
+
+### Complex with rework (5 original + 4 auto-rework = 9 tasks)
+- Chat API with auth + rooms: 9 tasks, 176 turns, $4.60, 26 minutes
+- QA found 2 bugs → 2 automatic rework cycles → both fixed and verified
+- Dependency chain with parallel QA and rework loop
+
+### Parallel squads (2 squads running simultaneously)
+- Bookmarks API (2/2, $0.83) + Notes CLI (6/6 with 2 rework cycles, $1.17)
+- Both ran concurrently from the same pi session
+- Combined: 12 tasks, 101 turns, $2.00
 
 ## Requirements
 
-- [pi](https://github.com/badlogic/pi-mono) coding agent
+- [pi](https://github.com/badlogic/pi-mono) coding agent (v0.63.0+, recommended v0.64.0+)
 - An API key configured in pi (Anthropic, OpenRouter, etc.)
+- Node.js 18+
 
 ## License
 

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "pi-squad",
-  "version": "0.1.0",
+  "version": "0.5.0",
   "description": "Multi-agent collaboration extension for pi — task decomposition, dependency management, parallel execution, TUI panel",
   "type": "module",
   "pi": {
-    "extensions": ["src/index.ts"],
-    "skills": ["src/skills/squad-protocol", "src/skills/collaboration", "src/skills/verification"]
+    "extensions": [
+      "src/index.ts"
+    ],
+    "skills": [
+      "src/skills/supervisor"
+    ]
   },
   "files": [
     "src",

package/src/agent-pool.ts

@@ -165,6 +165,7 @@ export class AgentPool {
 
 		// Spawn pi process — set env var to prevent recursive squad extension loading
 		const invocation = getPiInvocation(["--mode", "rpc", ...args]);
+		console.error(`[squad-pool] spawn ${agentDef.name}: ${invocation.command} ${invocation.args.slice(0, 3).join(" ")} ...`);
 		const proc = spawn(invocation.command, invocation.args, {
 			cwd,
 			stdio: ["pipe", "pipe", "pipe"],
@@ -199,6 +200,7 @@ export class AgentPool {
 		});
 
 		attachLineReader(proc.stdout!, (line) => {
+			stdoutLines++;
 			try {
 				const event = JSON.parse(line);
 				this.handleRpcEvent(agentProc, event);
@@ -208,7 +210,14 @@ export class AgentPool {
 		});
 
 		let agentEndEmitted = false;
-		proc.on("exit", (code) => {
+		let stdoutLines = 0;
+		proc.on("exit", (code, signal) => {
+			// Log diagnostic info for debugging spawn failures
+			if (code !== 0 && code !== null) {
+				console.error(`[squad-pool] ${agentDef.name} exited: code=${code} signal=${signal} pid=${proc.pid} stdoutLines=${stdoutLines} stderr=${stderr.slice(0, 300) || "(empty)"}`);
+			}
+			// Clean up agents map so getRunningAgents() doesn't count dead processes
+			this.agents.delete(taskId);
 			// Only emit if we haven't already emitted via RPC agent_end event
 			if (!agentEndEmitted) {
 				agentEndEmitted = true;