pi-squad 0.7.2 → 0.15.0

package/README.md

@@ -8,6 +8,9 @@ Multi-agent collaboration extension for [pi](https://github.com/badlogic/pi-mono
 # From npm
 pi install npm:pi-squad
 
+# From git
+pi install git:github.com/picassio/pi-squad
+
 # Or symlink for development
 ln -sf /path/to/pi-squad/src ~/.pi/agent/extensions/squad
 ```
@@ -22,11 +25,11 @@ Ask pi to do something complex. It calls the `squad` tool automatically:
 > Build a REST API with authentication, tests, and documentation
 ```
 
-The planner agent reads your codebase and creates a task breakdown automatically. Or be explicit:
+The planner agent reads your codebase and creates a task breakdown automatically. Or define tasks explicitly:
 
 ```
 > Use squad: goal="Build task API", tasks=[
-    {id: "api", title: "Build CRUD endpoints with express", agent: "backend"},
+    {id: "api", title: "Build CRUD endpoints", agent: "backend"},
     {id: "tests", title: "Write tests", agent: "qa", depends: ["api"]},
     {id: "docs", title: "Write README", agent: "docs", depends: ["api"]}
   ]
@@ -34,421 +37,303 @@ The planner agent reads your codebase and creates a task breakdown automatically
 
 ### What Happens
 
-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 dependencies allow
+1. **Planner** analyzes the codebase and creates tasks with dependencies
+2. A **live widget** appears above the editor showing task progress
+3. **Specialist agents** spawn as separate pi processes, working 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
+5. On completion, pi receives a summary with each task's output
 6. Multiple squads can run concurrently across different projects
 
-## User Interface
+## Features
 
-### Widget (above editor)
+### Dependency-Aware Scheduling
 
-Always visible when a squad is active. Debounced updates with cache key to avoid flicker.
+Tasks define dependencies. The scheduler resolves the DAG, spawns ready tasks up to `maxConcurrency`, and auto-unblocks dependents when tasks complete.
 
 ```
-⏳ 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
+architect → backend ──→ qa
+              ↑
+architect → frontend ─┘
 ```
 
-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)
+Architect runs first. Backend and frontend run in parallel after architect completes. QA waits for both.
 
-```
-⏳ squad 2/3 $0.58
-```
+### QA Rework Loop
 
-### Panel (Ctrl+Q)
+When a QA agent outputs `## Verdict: FAIL`, the scheduler automatically:
 
-Centered overlay panel with proper lifecycle management. Press `Ctrl+Q` to open/close.
+1. Creates a **fix task** for the original agent with QA feedback
+2. Creates a **retest task** for QA, blocked until the fix completes
+3. Loops up to `maxRetries` (default: 2), then escalates
 
-**Task list** with sticky summary at bottom:
 ```
-╭─ squad: Build task API ─────────────────────╮
-│ ▸ ✓ api (backend) 2m12s                     │
-│   ⏳ tests (qa) 45s                         │
-│   ◻ docs (docs) blocked                     │
-│                                              │
-│ ── tests (live) ─────────────────────        │
-│ → bash npm test                              │
-│                                              │
-│ 2/3 · $0.58 · 3m                            │
-├──────────────────────────────────────────────┤
-│ ↑↓ nav  ⏎ msgs  m send  p pause  ^q close  │
-╰──────────────────────────────────────────────╯
+api (backend) ✓ → qa (qa) ✗ found bug
+  → api-fix-1 (backend) ✓ → qa-retest-1 (qa) ✓ all passing
 ```
 
-**Message view** (Enter on a task) — long text wraps instead of truncating:
-```
-╭─ tests · qa ⏳ ─────────────────────────────╮
-│ 10:03 qa                                     │
-│   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 close       │
-╰──────────────────────────────────────────────╯
-```
+### Built-in Engineering Skills
 
-## Commands
+9 skills ship with the extension. Every squad agent automatically loads them:
 
-| Command | Description |
+| Skill | Purpose |
 |---|---|
-| `/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 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 |
+| `squad-architecture` | API contract definition, shared types, project structure, decision documentation |
+| `squad-backend-dev` | REST conventions, database patterns, auth implementation, error handling, security |
+| `squad-frontend-dev` | React patterns, state management, Tailwind CSS, accessibility, API integration |
+| `squad-qa-testing` | Test strategy, checklist, evidence requirements, verdict format, rework flow |
+| `squad-security-audit` | Vulnerability checklist, common patterns, reporting format |
+| `squad-verification` | Verify before claiming done, evidence-based completion |
+| `squad-collaboration` | Building on others' work, asking questions, sharing knowledge |
+| `squad-protocol` | Communication rules, @mention syntax, completion format |
+| `squad-supervisor` | Squad management guidance for the main pi agent |
 
-## Keyboard Shortcuts
+Skills are prefixed with `squad-` to avoid conflicts with user or project skills. Squad agents also inherit all skills from the main pi session (user skills, package skills, project skills).
 
-| Key | Context | Action |
-|---|---|---|
-| `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 | Close panel |
+### 11 Specialist Agents
 
-## Tools (LLM-callable)
+Bundled agent definitions are copied to `~/.pi/squad/agents/` on first run. Edit them freely — the extension never overwrites existing files.
 
-| Tool | Description |
-|---|---|
-| `squad` | Start a squad (non-blocking, returns immediately) |
-| `squad_status` | Check progress, costs, task states |
-| `squad_message` | Send message to a running agent via `steer()` |
-| `squad_modify` | Add/cancel/pause/resume tasks, or cancel/resume entire squad |
+| Agent | Role | Tags |
+|---|---|---|
+| `architect` | Software Architect | architecture, design, patterns |
+| `backend` | Backend Engineer | api, server, database, auth |
+| `frontend` | Frontend Engineer | react, ui, css, tailwind, accessibility |
+| `fullstack` | Fullstack Developer | general, coding, implementation |
+| `qa` | QA Engineer | testing, verification, e2e |
+| `reviewer` | Code Reviewer (read-only) | review, code-quality, over-engineering |
+| `security` | Security Engineer | audit, vulnerability, threat-modeling |
+| `debugger` | Debugger & Root Cause Analyst | debugging, investigation, bugs |
+| `devops` | DevOps Engineer | ci-cd, docker, deployment |
+| `docs` | Technical Writer | documentation, readme, api-docs |
+| `researcher` | Research Analyst | research, analysis, exploration |
+| `planner` | Project Planner | planning, architecture, coordination |
 
-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.
+### Agent Collaboration
 
-## Multiple Concurrent Squads
+**Chain context**: When task A completes, its output is injected into task B's system prompt. Downstream agents know what was built.
 
-Multiple squads can run in parallel from the same pi session. Each squad has its own scheduler, agent pool, and disk state.
+**Shared filesystem**: All agents work in the same project directory. Upstream agents create files, downstream agents read and modify them.
 
-```
-> Build the auth API          → starts squad-1
-> Build the dashboard UI      → starts squad-2 (runs in parallel)
+**Sibling awareness**: Parallel agents see each other's status and modified files, with warnings about shared file edits.
 
-/squad list                   → see both, select which to view
-/squad select                 → switch widget/panel focus
-```
+**@mention routing**: Agents write `@frontend what token format?` in their output. The router delivers it in real-time via RPC `steer()`.
 
-All squads run independently in the background. The widget/panel shows whichever squad you're focused on.
+### Smart Planner
 
-## QA Rework Loop
+The planner creates task breakdowns with proper dependency ordering:
+- Frontend tasks depend on backend API tasks (so frontend can test against real endpoints)
+- Parallel tasks that share interfaces get a design/architecture task first
+- Task descriptions include specific API paths, schemas, and conventions
 
-When a QA agent outputs `## Verdict: FAIL`, the scheduler automatically:
+When the main agent provides tasks directly (via the `tasks` parameter), unknown agent names are automatically remapped to `fullstack` instead of failing.
 
-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
+## User Interface
+
+### Widget (above editor)
 
-### Example flow
+Shows live squad progress. Truncated to terminal width — no wrapping, deterministic height.
 
 ```
-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 ✓
+⏳ 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
 ```
 
-### 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:
+### Status Bar
 
-```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
+⏳ squad 2/3 $0.58
 ```
 
-### Configuration
+### Panel (Ctrl+Q)
 
-```
-config: {
-  maxConcurrency: 3,  // parallel agents (default: 2)
-  maxRetries: 2,      // rework attempts before escalation (default: 2)
-}
-```
+Full overlay with task list, live activity preview, and scrollable message view.
 
-## Sending Messages to Agents
+| Key | Action |
+|---|---|
+| `↑↓` / `jk` | Navigate tasks / scroll messages |
+| `Enter` | View task messages |
+| `Esc` | Back to task list |
+| `m` | Send message to agent |
+| `p` | Pause/resume task |
+| `x` | Cancel task |
+| `Ctrl+Q` / `q` | Close panel |
 
-Three ways:
+### Slash Commands
 
-1. **`/squad msg`** — type in the main editor
-   ```
-   /squad msg Use postgres instead of SQLite
-   /squad msg backend Use postgres instead of SQLite
-   ```
+| Command | Description |
+|---|---|
+| `/squad select` | Pick a squad to view |
+| `/squad list` | List project squads |
+| `/squad all` | List all squads |
+| `/squad agents` | Manage agent definitions |
+| `/squad msg [agent] text` | Send message to agent |
+| `/squad widget` | Toggle widget |
+| `/squad panel` | Toggle panel |
+| `/squad cancel` | Cancel running squad |
+| `/squad clear` | Dismiss widget |
+| `/squad cleanup` | Delete squad data |
+| `/squad enable/disable` | Enable/disable the extension |
 
-2. **`m` key** — press in the panel, opens input dialog
+## Tools (LLM-callable)
 
-3. **Natural chat** — tell pi, it relays automatically
-   ```
-   > Tell the backend agent to use argon2 for password hashing
-   ```
+| Tool | Description |
+|---|---|
+| `squad` | Start a squad with goal + optional tasks/config |
+| `squad_status` | Check progress, costs, task states |
+| `squad_message` | Send message to a running agent |
+| `squad_modify` | Add/cancel/complete/pause/resume tasks or squads |
 
-Messages are delivered in real-time via RPC `steer()` if the agent is running, or queued for delivery when the agent spawns.
+The main agent sees available agents in its system prompt and squad state when a squad is active.
 
-## Agents
+## Configuration
 
-### 11 Bundled Agents
+```javascript
+squad({
+  goal: "Build the app",
+  config: {
+    maxConcurrency: 3,  // parallel agents (default: 2)
+    maxRetries: 2,      // QA rework attempts before escalation (default: 2)
+  },
+  agents: {
+    backend: { model: "claude-sonnet-4-20250514" },   // per-agent model override
+    architect: { thinking: "high" },                   // per-agent thinking level
+  },
+})
+```
 
-On first run, copied to `~/.pi/squad/agents/` for editing.
+### Context Inheritance
 
-| 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:
+Agents normally start fresh with only their task description, dependency outputs, and squad protocol. Set `inheritContext: true` on a task to fork the main pi session (via `pi --fork`) so that agent inherits the full conversation context:
 
-```
-/squad agents              — list all, select to view/edit
-/squad agents backend      — quick view of specific agent
+```js
+squad({
+  goal: "Implement the design we discussed",
+  tasks: [
+    { id: "impl", title: "Implement agreed design", agent: "backend",
+      description: "Goal: implement the API design agreed in this conversation. Verify: npm test",
+      inheritContext: true },
+  ],
+})
 ```
 
-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
+**Caveats:**
+- **Cost**: the agent pays the entire conversation history as input tokens on every turn — use sparingly
+- **Context-window guard**: the fork is skipped automatically when the estimated session size exceeds 50% of the agent model's context window (agents on smaller-context models silently degrade to standard squad context; the skip is recorded in the task's message log and `debug.log`)
+- Requires the main session to have a session file (skipped under `--no-session`)
+- Forked child sessions are stored under `~/.pi/squad/<squad-id>/sessions/`, not in your project's session list
+- Prefer restating the 3-5 key decisions in the task description — reach for `inheritContext` only when that's impractical
 
 ### Custom Agents
 
-Create a JSON file in `~/.pi/squad/agents/` (global) or `{project}/.pi/squad/agents/` (project override):
+Create `~/.pi/squad/agents/my-agent.json` (global) or `{project}/.pi/squad/agents/my-agent.json` (project override):
 
 ```json
 {
-  "name": "ml-engineer",
+  "name": "my-agent",
   "role": "ML Engineer",
   "description": "Machine learning, PyTorch, data pipelines",
-  "model": "anthropic/claude-sonnet-4-20250514",
+  "model": null,
+  "thinking": null,
   "tools": null,
   "tags": ["ml", "pytorch", "data"],
-  "prompt": "You are an ML engineer specializing in PyTorch...",
-  "disabled": false
+  "prompt": "You are an ML engineer specializing in PyTorch..."
 }
 ```
 
-- `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
+- `model`: `null` = squad default (see below). Override per agent or per squad.
+- `thinking`: `null` = squad default. One of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` (passed via pi's `--thinking` flag). Override per agent or per squad. Also editable via `/squad agents` → "Change thinking".
 
-### Chain Context (primary)
+### Default Model & Thinking (`/squad defaults`)
 
-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.
+Agents without an explicit `model`/`thinking` follow the squad default policy (stored in `~/.pi/squad/settings.json`):
 
-### 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:
-
-```
-# 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
+| Policy | Behavior |
+|---|---|
+| `main` *(default)* | **Follow the main pi session's current model and thinking level** — switch models mid-session and new agents follow |
+| `pi-default` | Legacy behavior: the child pi process resolves its own configured default |
+| explicit value | A fixed model id (e.g. `openai-codex/gpt-5.6-terra`) or thinking level |
 
-If an agent says "I'm blocked" or "cannot proceed", the router detects it and escalates to the main agent.
+Change interactively with `/squad defaults`. The planner agent follows the same policy. Resolution order: agent def → per-squad override → squad default policy.
+- `tools`: `null` = all tools. Restrict with `["bash", "read", "write", "edit"]`.
+- `tags`: Used by the planner to match agents to tasks automatically.
+- Project-local agents override global agents with the same name.
 
-## Session Resilience
+### Advisor — Self-Healing Squads (`/squad advisor`)
 
-### Crash Recovery
+Modeled on the advisor tool pattern ([pi-advisor](https://github.com/RimuruW/pi-advisor) / Anthropic's advisor strategy): when the health monitor flags an agent as stuck, the squad consults a **stronger advisor model in-process** (via pi-ai, no subprocess) with a curated digest — task, recent messages, recent tool activity — before interrupting you.
 
-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)
+The advisor returns a verdict (`Course-correct` / `Push through` / `Needs human input`) plus ≤5 action items:
+- **Course-correct / Push through** → advice is steered directly into the stuck agent's conversation; escalation suppressed
+- **Needs human input** → escalates immediately with the advisor's assessment attached
+- Advisor disabled, exhausted (`maxCallsPerTask`), or failed → normal escalation to you
 
-### Resume
+Configure with `/squad advisor` (on/off, model, max calls per task, reasoning effort). Defaults: **enabled**, model = main session's model, 2 calls/task, medium reasoning. Settings persist in `~/.pi/squad/settings.json` under `advisor`. All consultations are recorded in the task's message log (`from: "advisor"`).
 
-Resume a paused squad across sessions:
+## Reliability
 
-```
-> Resume the squad
-```
+### Meaningful Work Check
 
-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
+Agents must complete at least 1 LLM turn AND make at least 1 tool call to be marked as "done". Agents that exit cleanly but did no work (rate limit, API error, model not found) are retried once, then failed — never silently marked successful.
 
-All state lives on disk — squads are fully reconstructable from JSON files.
+### Session Resilience
 
-### Spawn Resilience
+- In-progress tasks are **suspended** on session crash, **resumed** on next startup
+- Failure is never terminal: `resume` recovers failed squads (failed tasks reset to pending), `complete_task` marks recovered work done and schedules dependents, and a 60s reconcile loop re-derives scheduling from persisted state so out-of-band store edits can't strand ready tasks
+- Squads are fully reconstructable from JSON files on disk
+- Spawn failures are retried once with a 2-second delay
+- All errors logged to `~/.pi/squad/debug.log` (always for errors, `PI_SQUAD_DEBUG=1` for verbose)
 
-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.
+### Health Monitoring
 
-## Governance
+The monitor never kills or blocks work on its own — its strongest action is notifying the main Pi session so you (or the main agent) can decide.
 
-| 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 |
+| Check | Threshold | Action |
+|---|---|---|
+| Idle warning | 3 minutes no output | Steer agent with nudge |
+| Stuck detection | 5 minutes no output | Steer, then escalate to main session |
+| Loop detection | Same tool call 5x | Steer with warning |
+| Long-running check-in | Every 30 minutes total (`PI_SQUAD_CEILING_MS`) | Notify main session — work continues |
 
 ## 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).
+All state in `~/.pi/squad/`. No database, no daemon. Writes are atomic. JSONL reads skip corrupt lines.
 
 ```
 ~/.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
+├── agents/              — agent definitions (user-editable)
+├── debug.log            — error and debug logging
+└── {squad-id}/
+    ├── squad.json       — goal, status, config, cwd
+    ├── context.json     — live state snapshot
+    └── {task-id}/
+        ├── task.json    — status, output, usage, retryOf, qaFeedback
+        └── messages.jsonl  — 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
+├── index.ts          — extension entry: tools, commands, widget, panel, lifecycle
+├── types.ts          — type definitions
+├── store.ts          — JSON/JSONL file I/O, atomic writes
+├── scheduler.ts      — dependency DAG, concurrency, rework loop, task lifecycle
+├── agent-pool.ts     — pi RPC process management, activity tracking
+├── protocol.ts       — system prompt builder (chain context, sibling awareness, knowledge)
+├── router.ts         — @mention parsing, cross-agent messaging
+├── monitor.ts        — health checks (idle, stuck, loop, long-run notify)
+├── planner.ts        — one-shot goal decomposition via LLM
+├── logger.ts         — file-based logging (never writes to stderr)
+├── panel/            — TUI overlay panel and widget
+├── skills/           — 9 bundled skills for agents
+└── 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 (v0.63.0+, recommended v0.64.0+)
+- [pi](https://github.com/badlogic/pi-mono) v0.63.0+ (recommended v0.64.0+)
 - An API key configured in pi (Anthropic, OpenRouter, etc.)
 - Node.js 18+