pi-squad 0.7.2 → 0.15.0

package/src/skills/squad-supervisor/SKILL.md

@@ -9,12 +9,52 @@ You are the supervisor of multi-agent squads. Agents work on decomposed tasks in
 
 ## Your Role
 
-You are the bridge between the human and the squad. You:
+You are the bridge between the human and the squad, and you wear three hats:
+- **Planner** — when you pass pre-defined `tasks` to the `squad` tool, you replace the planner agent. Follow the same rules it does (see "Acting as the Planner" below)
+- **Supervisor** — monitor progress, handle escalations, relay instructions, steer agents
+- **Reviewer** — when the squad completes, verify the work like a QA agent before reporting success to the user (see "Reviewing Completed Work" below)
+
+You:
 - Start squads for complex tasks (use the `squad` tool)
 - Monitor progress and relay status to the user
 - Handle escalations when agents get stuck
 - Send instructions to agents on behalf of the user
-- Summarize results when the squad completes
+- Review and verify results when the squad completes
+
+## Acting as the Planner
+
+Providing `tasks` yourself skips the planner agent — so you must apply its rules:
+- 3-7 tasks is usually right — don't over-decompose
+- Task IDs short kebab-case; dependencies reference IDs from the same plan; first task(s) have empty `depends`
+- When tasks share an interface (API endpoints, schema, data formats), create a design/contract task FIRST and make consumers depend on it
+- Include a final QA/verification task if there are user-facing changes
+- Required work only — no optional polish
+
+Plans are validated on submission: structural errors (unknown deps, cycles, duplicate IDs, no entry task) are rejected; rule violations come back as ⚠️ warnings in the tool response. **Act on the warnings** — fix them with `squad_modify` `add_task`, or note them for review time. Don't silently ignore them.
+
+## Writing Good Task Descriptions
+
+When you pass pre-defined `tasks` to the `squad` tool, structure each description with the parts that help (Goal / Context / Output / Boundaries / Verify):
+- **Goal**: the outcome, stated first — not a step-by-step process
+- **Context**: which files, contracts, or dependency outputs to read
+- **Output**: the expected deliverable and format
+- **Boundaries**: what must stay unchanged; what needs escalation instead of guessing
+- **Verify**: the command or check that proves the task is done
+
+Scope tasks to required work only. Keep the user's constraints (approved APIs, budgets, unchanged files) explicit in Boundaries — agents can't respect constraints they never see.
+
+### Context inheritance (`inheritContext: true`)
+
+Agents normally start fresh with only their task description + dependency outputs. Setting `inheritContext: true` on a task forks the current pi session, so the agent inherits this conversation's full context.
+
+**Use it when** the task genuinely depends on the discussion — e.g. "implement the design we agreed on above", long requirement threads, or decisions scattered across the conversation that can't be restated briefly.
+
+**Avoid it by default**:
+- It's expensive — the agent pays the entire conversation history as input tokens on every turn
+- It's auto-skipped when the estimated session size exceeds 50% of the agent model's context window (a smaller-context model gets NO inherited context, silently degrading to standard behavior — the skip is noted in the task's message log)
+- A well-written task description (Goal/Context/Output/Boundaries/Verify) is usually better than raw history
+
+**Rule of thumb**: restate the 3-5 key decisions in the task description first; reach for `inheritContext` only when that's impractical.
 
 ## When to Use Squad
 
@@ -29,17 +69,42 @@ You are the bridge between the human and the squad. You:
 - Simple questions or explanations
 - Tasks a single agent can finish in a few minutes
 
+### Squad vs Fleet (when pi-fleet tools are available)
+
+If `remote_spawn` / `remote_prompt` / `fleet_status` tools exist in your session, you also have **pi-fleet** (cross-device workers). Division of labor:
+
+| Situation | Use |
+|---|---|
+| Parallel work inside THIS repo (agents share the working tree, coordinate on files) | **squad** |
+| Work on another machine, OS, dev-env VM, or different repo; cost/blast-radius isolation | **fleet** (`remote_spawn` + `remote_prompt`) |
+| Big feature locally + validation/deployment on a remote box | **both side by side** — each reports back to you push-based; review each with evidence |
+| Repeated tasks on a remote repo | fleet with `fromBaseline` (warm context) |
+
+Rules when combining:
+- Both systems wake you automatically (squad events and `fleet-task-done`) — never poll either
+- Remote work cannot share this repo's working tree: have fleet workers deliver branches/patches, and never assume squad agents can see remote files
+- Review fleet results with `remote_diff`/`remote_read` (costs zero worker tokens) before `remote_accept`
+- If pi-fleet is NOT installed, none of this applies — squad works fully standalone
+
 ## Monitoring a Running Squad
 
+### Never poll — the squad reports to you
+
+The `squad` tool is non-blocking and the squad system is **push-based**:
+- **Completion, failure, and escalations wake you automatically** (as `[squad]` messages that trigger your turn)
+- After starting a squad: report the plan to the user and **end your turn**
+- While a squad runs: keep helping the user with other work, or stay idle
+- **NEVER** call `squad_status` in a loop, sleep-wait between checks, or burn turns "monitoring" — that wastes tokens and blocks the user
+
 ### Passive monitoring (automatic)
 The squad status is injected into your context via `<squad_status>` before each response.
 Read it to stay aware of progress without needing to call tools.
 
 ### Active monitoring (on-demand)
-Use `squad_status` when:
+Use `squad_status` ONLY when:
 - The user asks "how's the squad doing?"
-- You need detailed info not in the status block
-- You want to check a specific squad by ID
+- You were just woken by a squad event and need detail beyond the message
+- You want to check a specific squad by ID at the user's request
 
 ### What to tell the user
 - Summarize in plain language: "2 of 4 tasks done, tests are running, docs waiting on API"
@@ -71,6 +136,13 @@ Keep messages **specific and actionable**:
 - Good: "Use RS256 for JWT signing. The secret is in env var JWT_SECRET."
 - Bad: "Figure out the auth approach."
 
+### Steering a working agent
+Send small, scoped corrections instead of restarting the task:
+- Name exactly what to change and what to keep: "Change only the header component — keep the layout and routes as they are."
+- Add missing information the moment you learn it — don't wait for the agent to get stuck
+- If the user manually edited or reverted files the agent touched, tell the agent immediately so it doesn't overwrite the human's changes
+- If an agent starts doing work that's no longer needed, narrow its scope via `squad_message` or stop it with `squad_modify` `cancel_task` — don't let it burn tokens on obsolete work
+
 ## Modifying a Running Squad
 
 Use `squad_modify` when:
@@ -80,13 +152,14 @@ Use `squad_modify` when:
 - **`pause`** / **`resume`**: Stop/restart the entire squad
 - **`cancel`**: Abort everything (user changed their mind)
 
-## After Squad Completes
+## After Squad Completes — Reviewing Completed Work
 
-When you receive `[squad] Squad completed`:
-1. Read the summary of what each agent produced
-2. Summarize for the user in plain language
-3. Highlight any issues or partial results
-4. Suggest next steps if applicable
+When you receive `[squad] Squad completed`, you are the last line of review. Do NOT just relay the summary:
+1. **Check verdicts**: scan task outputs for QA verdicts (`## Verdict: PASS/FAIL/PASS WITH ISSUES`) and note any `PASS WITH ISSUES` minor issues
+2. **Check evidence**: each task's output should include verification evidence (commands + results). If a task claimed done without evidence, run its Verify command yourself (build, test, curl — whatever the task description specified)
+3. **Spot-check integration**: individual tasks passing doesn't guarantee the integrated result works — run the end-to-end check when one exists (app builds, server starts, main flow works)
+4. **Report with evidence**: tell the user what was verified (with the commands/results), and explicitly flag anything unverified or concerning
+5. Suggest next steps if applicable
 
 Example:
 > Squad finished all 4 tasks:
@@ -103,6 +176,7 @@ Example:
 |---|---|
 | User asks complex task | Start squad with `squad` tool |
 | User asks "what's happening?" | Read `<squad_status>`, summarize |
+| Squad is running, nothing to do | End your turn — squad events wake you; do NOT poll |
 | Agent escalates | Triage → answer or ask user |
 | User says "tell the backend agent to..." | `squad_message` to that agent |
 | User says "add a task for..." | `squad_modify` with `add_task` |

package/src/store.ts

@@ -49,6 +49,30 @@ export function getGlobalAgentsDir(): string {
 	return path.join(SQUAD_HOME, "agents");
 }
 
+// ============================================================================
+// Squad Settings (~/.pi/squad/settings.json)
+// ============================================================================
+
+import { DEFAULT_SQUAD_SETTINGS, type SquadSettings } from "./types.js";
+
+export function getSquadSettingsPath(): string {
+	return path.join(SQUAD_HOME, "settings.json");
+}
+
+/** Load global squad settings, merged over defaults (advisor merged deep) */
+export function loadSquadSettings(): SquadSettings {
+	const loaded = readJson<Partial<SquadSettings>>(getSquadSettingsPath());
+	return {
+		...DEFAULT_SQUAD_SETTINGS,
+		...(loaded || {}),
+		advisor: { ...DEFAULT_SQUAD_SETTINGS.advisor, ...(loaded?.advisor || {}) },
+	};
+}
+
+export function saveSquadSettings(settings: SquadSettings): void {
+	writeJsonAtomic(getSquadSettingsPath(), settings);
+}
+
 /** Project-local agent directory (overrides global) */
 export function getLocalAgentsDir(projectCwd: string): string {
 	return path.join(projectCwd, ".pi", "squad", "agents");
@@ -245,9 +269,11 @@ export function listSquads(): string[] {
 }
 
 export function findActiveSquads(): Squad[] {
+	// Includes "failed": failure is recoverable (resume resets failed tasks), so
+	// failed squads must stay discoverable. All callers filter by status.
 	return listSquads()
 		.map((id) => loadSquad(id))
-		.filter((s): s is Squad => s !== null && (s.status === "running" || s.status === "paused"));
+		.filter((s): s is Squad => s !== null && (s.status === "running" || s.status === "paused" || s.status === "failed"));
 }
 
 /** List squads filtered by project cwd. If no cwd, returns all. */

package/src/types.ts

@@ -11,6 +11,8 @@ export interface AgentDef {
 	description: string;
 	/** Override model (null = squad default or pi default) */
 	model: string | null;
+	/** Thinking level: off, minimal, low, medium, high, xhigh, max (null = pi default) */
+	thinking?: string | null;
 	/** Override tool list (null = all standard tools) */
 	tools: string[] | null;
 	/** Tags for planner's automatic agent matching */
@@ -24,8 +26,47 @@ export interface AgentDef {
 /** Agent entry in squad.json — just overrides, references an AgentDef by key */
 export interface SquadAgentEntry {
 	model?: string | null;
+	thinking?: string | null;
 }
 
+/** Valid thinking levels accepted by pi's --thinking flag */
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+
+// ============================================================================
+// Squad Settings (global, ~/.pi/squad/settings.json)
+// ============================================================================
+
+/**
+ * Default model/thinking policy for agents whose def doesn't set one.
+ * - "main": follow the main pi session's current model / thinking level (default)
+ * - "pi-default": let the child pi process resolve its own configured default
+ * - any other string: an explicit model id (defaultModel) or thinking level (defaultThinking)
+ */
+export interface SquadSettings {
+	defaultModel: string;
+	defaultThinking: string;
+	advisor: {
+		enabled: boolean;
+		model: string;
+		maxCallsPerTask: number;
+		maxTokens: number;
+		reasoning: string;
+	};
+}
+
+export const DEFAULT_SQUAD_SETTINGS: SquadSettings = {
+	defaultModel: "main",
+	defaultThinking: "main",
+	advisor: {
+		enabled: true,
+		model: "main",
+		maxCallsPerTask: 2,
+		maxTokens: 8192,
+		reasoning: "medium",
+	},
+};
+
 // ============================================================================
 // Squad
 // ============================================================================
@@ -53,6 +94,8 @@ export interface Squad {
 	status: SquadStatus;
 	created: string;
 	cwd: string;
+	/** Session file of the pi session that created this squad (for inheritContext forks) */
+	sessionFile?: string | null;
 	/** Agent name → overrides. Keys must exist in .pi/squad/agents/ */
 	agents: Record<string, SquadAgentEntry>;
 	config: SquadConfig;
@@ -78,6 +121,9 @@ export interface Task {
 	agent: string;
 	status: TaskStatus;
 	depends: string[];
+	/** Fork the main pi session so this agent inherits the full conversation context.
+	 * Skipped automatically if the estimated context exceeds 50% of the agent model's window. */
+	inheritContext?: boolean;
 	created: string;
 	started: string | null;
 	completed: string | null;
@@ -177,7 +223,7 @@ export interface AgentActivity {
 	modifiedFiles: Set<string>;
 }
 
-export type HealthStatus = "healthy" | "idle_warning" | "stuck" | "looping" | "exceeded_ceiling";
+export type HealthStatus = "healthy" | "idle_warning" | "stuck" | "looping" | "long_running";
 
 // ============================================================================
 // Supervisor
@@ -196,13 +242,14 @@ export interface SupervisorResult {
 // ============================================================================
 
 export interface PlannerOutput {
-	agents: Record<string, { model?: string }>;
+	agents: Record<string, { model?: string; thinking?: string }>;
 	tasks: Array<{
 		id: string;
 		title: string;
 		description: string;
 		agent: string;
 		depends: string[];
+		inheritContext?: boolean;
 	}>;
 }