pi-squad 0.7.2 → 0.14.0

package/src/skills/squad-code-review/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: squad-code-review
+description: >
+  Code review methodology — two-pass review (correctness/scope, then
+  over-engineering), surgical-change discipline, complexity findings with
+  delete/stdlib/native/yagni/shrink tags, machine-parsed verdicts. Use when
+  reviewing diffs, implementations, or pull requests.
+version: 1.0.0
+---
+
+# Code Review
+
+Two passes, in order. Findings from pass 1 gate the verdict; pass 2 findings
+are usually non-blocking. Derived from the karpathy-guidelines and ponytail
+review disciplines.
+
+## Pass 1 — Correctness & Scope
+
+**Every changed line must trace to the task.**
+- Flag unrequested refactors, drive-by "improvements", formatting churn in
+  untouched code, and deleted code the task didn't ask to remove
+- Orphan check: did the change leave now-unused imports/variables/functions
+  it created? (Pre-existing dead code is a mention, not a finding)
+
+**Verify with evidence, not by reading.**
+- Run the task's Verify criterion yourself (tests, build, curl). Your review
+  is only as strong as the commands you ran
+- Reproduce at least one happy path and one failure path where practical
+- If you can't run something, say so explicitly — don't imply you did
+
+**Assumptions and interpretations.**
+- If the implementation silently picked one of several readings of the task,
+  name the choice and whether it matches the task's Goal/Boundaries
+- Check the task's Boundaries were respected (unchanged APIs, schemas, configs)
+
+**Error handling in the right places.**
+- Trust boundaries (user input, network, file I/O) must handle failure
+- Impossible-scenario handling is noise — flag it in pass 2 as yagni
+
+## Pass 2 — Complexity Hunt
+
+Climb the ladder for each addition; stop at the first rung that holds:
+need to exist? → already in codebase? → stdlib? → native platform? →
+installed dep? → one line? → minimum that works.
+
+One line per finding — location, what to cut, what replaces it:
+
+- `delete:` dead code, unused flexibility, speculative feature → nothing
+- `stdlib:` hand-rolled thing the standard library ships → name the function
+- `native:` dep/code doing what the platform does → name the feature
+- `yagni:` abstraction with one implementation, config nobody sets, layer with one caller
+- `shrink:` same logic, fewer lines → show the shorter form
+
+Example: `api.ts:L88: yagni: RepositoryFactory with one product. Inline it until a second exists.`
+
+**Never flag as bloat**: trust-boundary validation, data-loss handling,
+security, accessibility, or a minimal test. Lean is not careless.
+
+If nothing to cut: `Lean already.` — don't invent findings to look thorough.
+
+## Verdict (machine-parsed — REQUIRED)
+
+End your final message with exactly:
+
+```
+## Verdict: PASS | FAIL | PASS WITH ISSUES
+
+## Issues
+1. **[file:line]** (Critical/High/Medium/Low) description
+   - Expected: X
+   - Got: Y
+   - Fix: specific change
+
+## Evidence
+[commands run + output]
+```
+
+- **FAIL**: pass-1 problems (correctness, scope violations, broken Verify).
+  Creates a rework task — the fixer only sees your Issues section
+- **PASS WITH ISSUES**: works and in-scope, but pass-2 cuts are worth making
+- **PASS**: correct, in scope, lean. Say what you verified
+- Severity: correctness/security → Critical/High; complexity → Medium/Low
+- Do not rename the sections — `## Issues` is extracted verbatim as fix feedback
+
+## You Don't Fix
+
+You report; the squad routes fixes to the original agent. Applying fixes
+yourself would bypass the rework loop and confuse file ownership. If a fix
+is truly one character, still report it — with the exact edit in the Fix line.

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

@@ -22,10 +22,14 @@ Bad: "@backend FYI I'm working on the frontend" (no question, wastes their time)
 Don't just post conclusions. Explain why you made a choice, so others can course-correct early.
 "I chose RS256 over HS256 because the frontend needs to verify tokens without the signing secret"
 
-## Admit uncertainty
+## Admit uncertainty — flag gaps, never guess
 If you're not sure about something, say so and ask.
 "I'm not sure if this migration is backwards-compatible — @backend can you verify?"
 
+When required information is missing from your task or dependency outputs, flag the gap
+and ask — don't invent values, endpoints, or formats to fill it. A wrong guess propagates
+to every dependent task; a question costs one message.
+
 Better to ask than to silently introduce a breaking change.
 
 ## Respond when asked

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

@@ -0,0 +1,61 @@
+---
+name: squad-debugging
+description: >
+  Debugging and rework discipline — reproduce-first workflow, hypothesis testing,
+  minimal fixes, regression tests. Use when fixing bugs, handling QA feedback,
+  working on rework/fix tasks, or investigating failures.
+version: 1.0.0
+---
+
+# Debugging & Rework
+
+## The Iron Rule: Reproduce First
+
+Never change code before you've seen the failure with your own eyes.
+
+1. **REPRODUCE**: Run the failing test, repro steps, or command from the QA
+   feedback. Confirm you see the same failure. If you can't reproduce it,
+   say so explicitly — don't "fix" what you can't observe.
+2. **LOCALIZE**: Read the error, stack trace, or diff. Form ONE hypothesis
+   about the cause. State it before changing anything.
+3. **FIX**: Make the smallest change that addresses the hypothesized cause.
+4. **VERIFY**: Re-run the exact reproduction from step 1 — it must now pass.
+   Then run the surrounding test suite to catch regressions.
+5. **PROTECT**: Add a regression test if none exists for this failure mode.
+
+## Hypothesis Discipline
+
+- One hypothesis at a time. If the fix doesn't work, REVERT it before trying
+  the next hypothesis — never stack speculative changes
+- If two hypotheses fail, stop and gather more evidence (add logging, isolate
+  with a minimal test case) instead of guessing a third time
+- Distinguish "the symptom moved" from "the cause is fixed" — re-run the
+  ORIGINAL repro, not just your new test
+
+## Rework Tasks (QA sent your work back)
+
+- Fix ONLY the issues listed in the QA feedback — no rewrites, no opportunistic
+  refactoring, no unrelated improvements
+- Reproduce each reported issue before touching code (the feedback includes
+  Expected/Got/Repro for each — use them)
+- If a reported issue looks wrong or is not reproducible, say so explicitly
+  with evidence instead of silently skipping it
+- Your completion message must show each issue → what changed → re-run evidence
+
+## Common Traps
+
+- **Fixing the test instead of the code** — only adjust a test when you can
+  argue the test itself was wrong, and say so
+- **Shotgun debugging** — many small changes at once; you won't know which
+  one mattered and you'll introduce new breakage
+- **Environment blame** — "works on my machine" requires evidence: show the
+  environment difference, don't assume it
+- **Silent scope creep** — noticing other bugs is good; fixing them inside a
+  rework task is not. Mention them so the squad can create tasks
+
+## Output Checklist
+
+Your completion message must include:
+1. Each issue: root cause (one sentence) + the fix (file:line)
+2. Evidence: the original failing command now passing (actual output)
+3. Regression scope: which suites you ran and their results

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

@@ -23,6 +23,17 @@ Messages from other agents and the human arrive as interruptions in your convers
 They are prefixed with `[squad]`. Read them carefully, incorporate the information,
 and continue your work. Don't ignore incoming messages.
 
+### Advisor messages
+If you appear stuck, a senior advisor model may review your situation. Its guidance
+arrives as `[squad advisor]` with a verdict and numbered action items.
+Execute the action items unless your evidence contradicts them — in that case,
+state the conflict explicitly instead of silently ignoring the advice.
+
+### Reading your task
+Task descriptions are structured as: Goal (the outcome), Context (where to look),
+Output (deliverable), Boundaries (what must NOT change), Verify (the command that
+proves you're done). Honor the Boundaries; run the Verify command before claiming done.
+
 ### Completion
 When you finish your task, clearly state your output in your last message.
 Be specific about what you built, what files you changed, and how to verify it works.
@@ -63,3 +74,11 @@ The squad system monitors your activity and will intervene, but being explicit i
 ### Read before writing
 Before modifying any file, read it first. Another agent may have changed it
 since the last time you saw it.
+
+### Boundaries
+- If required information is missing or ambiguous, ask (@mention or escalate) —
+  flag gaps instead of guessing or inventing
+- Keep changes minimal and within your task's scope — no unrequested refactors or polish
+- Keep public APIs, schemas, and configs unchanged unless your task says otherwise
+- Never take externally visible actions (git push, deploy, publish, send messages)
+  unless your task explicitly instructs it — prepare, don't ship

package/src/skills/squad-qa-testing/SKILL.md

@@ -40,19 +40,30 @@ Every claim must have evidence. Don't just say "it works" — show it:
 - **UI tests**: Describe what you see, or use screenshots
 - **Error tests**: Show the error response for invalid input
 
-## Verdict Format
+## Verdict Format (machine-parsed — use EXACTLY this structure)
+
+Your final message MUST end with this structure. The squad system parses the
+`## Verdict:` line to decide pass/fail, and extracts the `## Issues` section
+(exactly `## Issues`, two hashes) as feedback for the fixing agent:
+
 ```
-## Verdict: PASS | FAIL
+## Verdict: PASS | FAIL | PASS WITH ISSUES
 
-### Issues Found
-| # | Issue | Severity | Details |
-|---|-------|----------|---------|
-| 1 | ...   | Critical/High/Medium/Low | ... |
+## Issues
+1. **[file:line or endpoint]** (Critical/High/Medium/Low) Description
+   - Expected: X
+   - Got: Y
+   - Repro: exact command or steps
 
-### Evidence
-[test output, curl commands, screenshots]
+## Evidence
+[test output, curl commands and responses, build output]
 ```
 
+- `FAIL` automatically creates a rework task for the original agent — it only
+  sees your `## Issues` section, so make every issue specific and reproducible
+- `PASS WITH ISSUES` = working but with non-blocking concerns (listed under `## Issues`)
+- Do NOT rename the sections (`### Issues Found` etc. breaks feedback extraction)
+
 ## Rework Flow
 If issues are found:
 1. Document each issue with severity, location, and reproduction steps

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");

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;
@@ -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;
 	}>;
 }