Pi Subagent OrchestrationSAFE

High-performance AI coding agent CLI written in Rust with zero unsafe code

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: pi-subagent-orchestration-git-only
description: Orchestrate subagents in pi with git-based logging and Mission Control. Use when spawning multiple agents that need audit trails, rollback, branching, and real-time monitoring. Covers per-agent git repos, turn-level commits, workspace setup, and the shadow-git extension.
---

# Pi Subagent Orchestration

**YOU ARE AN ORCHESTRATING AGENT.** Your job is to decompose complex tasks, spawn subagents, coordinate their work, and synthesize results. You never execute leaf-level work yourself when subagents are more appropriate.

---

## ⚠️ THE RESOURCE COMMANDMENTS ⚠️

**SUBAGENTS CONSUME REAL RESOURCES. EVERY AGENT YOU SPAWN:**
- Uses CPU and memory on the user's machine
- Costs money (API calls to LLM providers)
- Runs until killed or max-turns reached
- Can accumulate silently if forgotten

### The 7 Commandments

1. **THOU SHALT KILL WHAT THOU SPAWNS**
   - Every spawn must have a corresponding cleanup plan
   - Never assume agents will terminate themselves

2. **THOU SHALT TRACK ALL PROCESSES**
   - Record PIDs or tmux session names
   - Maintain a list of what you spawned

3. **THOU SHALT SET MAX-TURNS**
   - Always use `--max-turns` to prevent runaway agents
   - 20-30 turns for research, 50 max for complex tasks

4. **THOU SHALT CLEAN UP ON EXIT**
   - Before ending your session, kill all spawned agents
   - `tmux kill-server` or `kill $(cat agents/*/pid)`

5. **THOU SHALT CHECK BEFORE SPAWNING**
   - Run `tmux ls` to see existing sessions
   - Run `ps aux | grep pi` to find orphaned agents
   - Kill stale processes before starting new work

6. **THOU SHALT NOT SPAWN OPUS LIGHTLY**
   - `claude-opus-4-5` costs 15x more than haiku
   - Use haiku for research, sonnet for synthesis
   - Opus only for genuinely hard problems

7. **THOU SHALT MONITOR RESOURCE USAGE**
   - Check `top` or Activity Monitor periodically
   - Watch for runaway CPU/memory consumption
   - Kill stuck agents immediately

### Cleanup Commands (Memorize These)

```bash
# See all tmux sessions
tmux ls

# Kill ALL tmux sessions (nuclear option)
tmux kill-server

# Kill specific session
tmux kill-session -t agent-name

# Find orphaned pi processes
ps aux | grep -E "[p]i --model"

# Kill by PID
kill <pid>

# Check system load
uptime
```

### Before You Start ANY Orchestration

```bash
# 1. Check for existing agents
tmux ls 2>/dev/null || echo "No tmux sessions"
ps aux | grep -E "[p]i " | grep -v grep

# 2. Kill any stale agents from previous work
tmux kill-server 2>/dev/null

# 3. Check system resources
uptime  # Load should be < number of CPU cores

# 4. ⚠️ CRITICAL: Force correct model in settings (CLI flags are IGNORED!)
cat > ~/.pi/agent/settings.json << 'EOF'
{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-haiku-4-5",
  "defaultThinkingLevel": "none"
}
EOF
echo "Model set to: $(jq -r .defaultModel ~/.pi/agent/settings.json)"
```

**⚠️ WARNING: `--model` CLI flag is IGNORED! Pi uses `~/.pi/agent/settings.json` instead.**
**If you skip step 4, you WILL spawn Opus agents at 15x the cost of Haiku.**

**IF YOU SPAWN IT, YOU OWN IT. CLEAN UP AFTER YOURSELF.**

---

## Quick Start: Spawn a Single Agent

If you just need to spawn ONE agent quickly, here's the minimum viable setup:

```bash
# 1. Create workspace
WORKSPACE="$HOME/workspaces/$(date +%Y%m%d)-task"
mkdir -p "$WORKSPACE/agents/scout1"/{workspace,output}
cd "$WORKSPACE"

# 2. Write the plan
cat > agents/scout1/plan.md << 'EOF'
# Plan: Research Task

## Objective
Research X and produce findings.

## Steps
1. Read the codebase/docs
2. Document findings in output/findings.md

## Output
- output/findings.md
EOF

# 3. Spawn (using --print for non-interactive mode)
(cd $WORKSPACE/agents/scout1 && \
 pi \
    --model claude-haiku-4-5 \
    --max-turns 20 \
    --print \
    'Read plan.md and execute it.' \
    2>&1 | tee output/run.log) &
echo $! > agents/scout1/pid

# 4. Check status
ps -p $(cat agents/scout1/pid) >/dev/null 2>&1 && echo "Running" || echo "Done"

# 5. View output when done
cat agents/scout1/output/findings.md
```

**Alternative: Use tmux for observability** (can attach to see progress):
```bash
tmux new-session -d -s scout1 \
  "cd $WORKSPACE/agents/scout1 && \
   pi --model claude-haiku-4-5 --max-turns 20 \
   'Read plan.md and execute it.' \
   2>&1 | tee output/run.log"
```

**That's it.** For more complex orchestration (multiple agents, audit trails, coordination), read on.

---

## Table of Contents

0. [THE RESOURCE COMMANDMENTS](#️-the-resource-commandments-️) ← **READ THIS FIRST**
1. [Critical Concepts](#critical-concepts)
2. [Pre-Flight Decisions](#pre-flight-decisions)
3. [Workspace Structure](#workspace-structure)
4. [Spawning Methods](#spawning-methods)
5. [Shadow Git Extension (Audit Trail)](#shadow-git-extension-audit-trail)
6. [Mission Control Dashboard](#mission-control-dashboard)
7. [Output Aggregation Patterns](#output-aggregation-patterns)
8. [Git-Based Coordination](#git-based-coordination)
9. [Logging Protocol](#logging-protocol)
10. [Error Handling and Recovery](#error-handling-and-recovery)
11. [Quick Reference](#quick-reference)
12. [Gotchas and Hard-Won Lessons](#gotchas-and-hard-won-lessons) ← **LEARN FROM THESE**

---

## Critical Concepts

### Why Subagents?

| Problem | Solution |
|---------|----------|
| Task too large for one context window | Decompose into focused subtasks |
| Need parallelism | Spawn multiple agents simultaneously |
| Need isolation | Each agent has clean context |
| Need audit trail | Shadow git tracks everything |
| Task may exceed max turns | Handoff to continuation agent |

### Pi Sessions vs Shadow Git

**Pi has built-in session management** — it stores conversation history in `~/.pi/agent/sessions/`. This is great for single-agent work but has limitations for orchestration:

| Feature | Pi Sessions | Shadow Git |
|---------|-------------|------------|
| Scope | Per-agent, per-cwd | Per-agent repos, unified workspace |
| Branching

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (1)

.beads/beads.jsonl

Gates applied: no_behavioural_pass.