pi-squad 0.1.0 → 0.4.14

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:
+Or be explicit with predefined tasks:
 
 ```
 > Use squad: goal="Build task API", tasks=[
@@ -34,33 +34,41 @@ Or be explicit:
 
 ### What Happens
 
-1. Extension creates tasks, starts the scheduler
+1. Extension creates tasks and starts the scheduler
 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 with costs
 
 ## User Interface
 
 ### Widget (above editor)
 
-Always visible when a squad is active. Updates every 2 seconds.
+Always visible when a squad is active. Component-based, event-driven rendering — updates on every scheduler event with no polling.
 
 ```
-⏳ 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 based on terminal height
+- 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. Press `Ctrl+Q` to open/close.
 
 **Task list:**
 ```
@@ -72,9 +80,9 @@ 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  │
 ╰──────────────────────────────────────────────╯
 ```
 
@@ -88,7 +96,7 @@ Side panel on wide screens, centered overlay on narrow screens. Press `Ctrl+Q` t
 │ 10:05 YOU                                    │
 │   Also test edge cases for empty input       │
 ├──────────────────────────────────────────────┤
-│ ↑↓ scroll  m send  esc back  ^q switch      │
+│ ↑↓ scroll  m send  esc back  ^q close       │
 ╰──────────────────────────────────────────────╯
 ```
 
@@ -99,6 +107,8 @@ 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 panel` | Toggle overlay panel |
@@ -109,27 +119,81 @@ Side panel on wide screens, centered overlay on narrow screens. Press `Ctrl+Q` t
 
 | 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.
+
+## 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
+
+### QA verdict format
+
+QA agents should end their output with a structured verdict:
+
+```markdown
+## Verdict: PASS
+All 42 tests passing. No issues found.
+```
 
-The main pi agent sees squad state in its system prompt automatically and can relay messages, add tasks, or check status on your behalf.
+```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
+  maxRetries: 2,      // rework attempts before escalation (default: 2)
+}
+```
 
 ## Sending Messages to Agents
 
@@ -141,30 +205,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 +262,160 @@ 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.
+- `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)
 
-## Data
+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.
 
-All state lives in `~/.pi/squad/` (global). No database, no daemon, no external services.
+### 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.
+
+### Sibling Awareness
+
+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.
 ```
 
-Each squad stores its project `cwd` in `squad.json`. The `/squad list` command filters by current project. `/squad all` shows everything.
+### @Mention Routing
+
+Agents can message each other in real-time:
 
-Project-local agent overrides: `{project}/.pi/squad/agents/`
+```
+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
+```
 
-## Multi-Project Support
+### Block Detection
 
-Squads are stored globally but scoped to projects by their `cwd` field. Multiple pi sessions can run squads for different projects simultaneously.
+If an agent says "I'm blocked" or "cannot proceed", the router detects it and escalates to the main agent.
+
+## Session Resilience
+
+### Crash Recovery
+
+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
+
+### 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. Restarts suspended tasks
 
-Any pi session can browse and view any squad with `/squad select` or `/squad all`.
+All state lives on disk — squads are fully reconstructable.
 
 ## 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`) |
+| **File tracking** | Warns agents about files modified by other agents |
+| **@mention routing** | Parsed from output, delivered via RPC `steer()` |
+| **Escalation** | Blocked agents, stuck agents, and retry limit → notify main agent |
+
+## Data Layout
+
+All state lives in `~/.pi/squad/`. No database, no daemon, no external services. Writes are atomic (temp file + rename).
+
+```
+~/.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
+        └── 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
+├── scheduler.ts          — dependency DAG, concurrency, rework loop, task lifecycle
+├── agent-pool.ts         — pi RPC process spawn/steer/kill
+├── protocol.ts           — system prompt builder (7 sections)
+├── 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   — component-based widget (setWidget factory)
+│   ├── task-list.ts      — task tree with status icons, elapsed time
+│   └── message-view.ts   — scrollable message log per task
+├── skills/
+│   ├── supervisor/       — teaches main agent to supervise squads
+│   ├── squad-protocol/   — communication rules for child agents
+│   ├── collaboration/    — team interaction patterns
+│   └── verification/     — verify-before-done + structured verdicts
+└── agents/_defaults/     — 11 bundled agent definitions
+```
+
+## Test Results
+
+### Simple (3 tasks, linear chain)
+- URL shortener API: 3 tasks, $0.83, 4.5 minutes
+- Backend → QA → Docs, all passing
+
+### Medium (6 tasks, diamond dependency)
+- Static blog engine: 6 tasks, $4.56, 24 minutes
+- Markdown parser → HTML converter → site generator → Express server → QA + Docs
+- 87+ tests passing
+
+### Complex (5 original + 4 auto-rework = 9 tasks)
+- Chat API with auth + rooms: 9 tasks, $4.60, 26 minutes
+- QA found 2 bugs → 2 automatic rework cycles → both fixed and verified
+- 176 turns across 5 specialist agents
 
 ## Requirements
 
 - [pi](https://github.com/badlogic/pi-mono) coding agent
 - 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.4.14",
   "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",