pi-squad 0.6.5 → 0.14.0

package/src/skills/squad-frontend-dev/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: squad-frontend-dev
+description: >
+  Frontend engineering practices — React patterns, CSS/Tailwind, accessibility,
+  state management, API integration, and responsive design. Use when building
+  UIs, web apps, or frontend components.
+version: 1.0.0
+---
+
+# Frontend Development
+
+## React Patterns
+- Use functional components with hooks (no class components)
+- Extract reusable logic into custom hooks (useAuth, useFetch, useDebounce)
+- Handle all UI states explicitly: loading, error, empty, success
+- Use React.memo only for measured performance bottlenecks
+- Prefer composition over prop drilling — use context for cross-cutting concerns
+- Use controlled components for forms, validate before submit
+
+## State Management
+- Server state: use React Query / TanStack Query (caching, refetching, optimistic updates)
+- Client state: use useState for local, useContext for shared, useReducer for complex
+- URL state: use router params/search params for bookmarkable state
+- Never duplicate server state in client state — let the query cache be the source of truth
+
+## API Integration
+- Create a typed API client module (don't scatter fetch calls across components)
+- Handle 401 responses globally (refresh token, redirect to login)
+- Show loading indicators for any request > 200ms
+- Handle network errors gracefully (offline banner, retry button)
+- Use optimistic updates for snappy UX (revert on error)
+
+## CSS / Tailwind
+- Use utility classes, avoid custom CSS when possible
+- Follow the project's design tokens (colors, spacing, typography)
+- Use responsive prefixes: sm:, md:, lg:, xl:
+- Implement dark mode with dark: prefix when required
+- Ensure consistent spacing scale (don't mix arbitrary values)
+
+## Accessibility
+- All interactive elements must be keyboard-navigable (tab, enter, escape)
+- Use semantic HTML elements (button, nav, main, section, header, footer)
+- Add aria-labels to icon-only buttons and non-text interactive elements
+- Ensure color contrast meets WCAG AA (4.5:1 for normal text, 3:1 for large)
+- Support screen readers: announce dynamic content changes with aria-live
+
+## Build & Performance
+- Verify the build completes without errors before claiming done
+- Code-split routes (React.lazy + Suspense)
+- Optimize images (lazy loading, proper sizing)
+- Minimize bundle size (check for unnecessary dependencies)

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

@@ -0,0 +1,72 @@
+---
+name: squad-qa-testing
+description: >
+  QA and testing practices — test strategy, checklist, evidence requirements,
+  verdict format, and rework flow. Use when verifying, testing, or reviewing
+  implementations.
+version: 1.0.0
+---
+
+# QA & Testing
+
+## Test Strategy
+1. **Build verification**: Does the code compile/build without errors?
+2. **Smoke test**: Does the app start and respond to basic requests?
+3. **Functional tests**: Do all features work as specified?
+4. **Edge cases**: Invalid inputs, empty states, boundary values
+5. **Integration**: Do components work together (API ↔ frontend, auth flow)?
+
+## Before You Start
+- Read the task description and dependency outputs carefully
+- Understand what was built before testing it
+- Start the server/app and verify it's actually running
+- Don't assume anything works — verify everything
+
+## Testing Checklist
+- [ ] App builds without errors (tsc, vite build, etc.)
+- [ ] Server starts and responds to health check
+- [ ] All CRUD operations work (create, read, update, delete)
+- [ ] Authentication flow works (register, login, protected routes)
+- [ ] Input validation rejects bad data (missing fields, wrong types)
+- [ ] Error responses have correct HTTP status codes
+- [ ] Frontend renders without console errors
+- [ ] Navigation between pages works
+- [ ] Forms submit correctly and show feedback
+
+## Evidence Requirements
+Every claim must have evidence. Don't just say "it works" — show it:
+- **API tests**: Show curl commands and their responses
+- **Build tests**: Show the build command output (exit code 0)
+- **UI tests**: Describe what you see, or use screenshots
+- **Error tests**: Show the error response for invalid input
+
+## 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 | PASS WITH ISSUES
+
+## 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 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
+2. The squad system will create fix tasks automatically
+3. You will re-test after fixes are applied
+4. On re-test: verify ALL previous issues are fixed, not just the latest

package/src/skills/squad-security-audit/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: squad-security-audit
+description: >
+  Security audit checklist, vulnerability patterns, and remediation guidance.
+  Use when reviewing code for security issues, hardening an application,
+  or performing security verification.
+version: 1.0.0
+---
+
+# Security Audit
+
+## Checklist
+- [ ] No secrets in source code (API keys, passwords, tokens, connection strings)
+- [ ] All user inputs validated and sanitized
+- [ ] SQL injection prevention (parameterized queries, no string interpolation)
+- [ ] XSS prevention (output encoding, CSP headers, no innerHTML with user data)
+- [ ] Authentication on all protected endpoints
+- [ ] Authorization checks (can THIS user perform THIS action on THIS resource?)
+- [ ] Rate limiting on public endpoints (login, register, password reset)
+- [ ] Secure headers configured (CORS, HSTS, X-Frame-Options, X-Content-Type-Options)
+- [ ] File upload validation (type whitelist, size limits)
+- [ ] Error messages don't leak internal details (stack traces, SQL errors, file paths)
+- [ ] Passwords hashed with bcrypt (not MD5, SHA1, or plain text)
+- [ ] JWT tokens validated on every request (signature, expiry, issuer)
+- [ ] Sensitive data not logged (passwords, tokens, credit cards)
+- [ ] Dependencies checked for known vulnerabilities (npm audit)
+
+## Common Vulnerabilities
+- **Broken Access Control**: Missing auth checks, IDOR (accessing other users' data by changing IDs)
+- **Injection**: SQL, NoSQL, command injection via unsanitized inputs
+- **Broken Auth**: Weak passwords allowed, no rate limiting on login, tokens never expire
+- **Security Misconfiguration**: Default credentials, verbose error pages, unnecessary features enabled
+- **Sensitive Data Exposure**: Secrets in client-side code, PII in logs, HTTP instead of HTTPS
+
+## Reporting Format
+```
+## Security Finding: [Title]
+**Severity**: Critical | High | Medium | Low
+**Location**: [file:line or endpoint]
+**Description**: What's wrong
+**Impact**: What could happen if exploited
+**Remediation**: How to fix it (specific code change)
+```

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/skills/{verification → squad-verification}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: verification
+name: squad-verification
 description: Verify work before claiming completion — evidence-based discipline for multi-agent handoffs.
 ---
 

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");
@@ -405,32 +429,6 @@ export function loadAllKnowledge(squadId: string): KnowledgeEntry[] {
 	].sort((a, b) => a.ts.localeCompare(b.ts));
 }
 
-// ============================================================================
-// Overview Document (shared squad summary)
-// ============================================================================
-
-export function getOverviewPath(squadId: string): string {
-	return path.join(getSquadDir(squadId), "OVERVIEW.md");
-}
-
-export function loadOverview(squadId: string): string {
-	try {
-		return fs.readFileSync(getOverviewPath(squadId), "utf-8");
-	} catch {
-		return "";
-	}
-}
-
-export function appendOverview(squadId: string, section: string): void {
-	const filePath = getOverviewPath(squadId);
-	ensureDir(path.dirname(filePath));
-	const existing = loadOverview(squadId);
-	const content = existing
-		? existing.trimEnd() + "\n\n---\n\n" + section.trim() + "\n"
-		: section.trim() + "\n";
-	fs.writeFileSync(filePath, content, "utf-8");
-}
-
 // ============================================================================
 // Rework Helpers
 // ============================================================================

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