pi-squad 0.1.0

package/src/skills/collaboration/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: collaboration
+description: Multi-agent collaboration patterns — how to build on others' work, ask questions, share knowledge, and work as a team.
+---
+
+# Collaboration
+
+## Build on others' work
+Read what your dependencies produced. Reference their output explicitly.
+"Based on the schema from the db-schema task, the users table has id, email, password_hash, created_at.
+I'll add the JWT validation column and refresh_token table..."
+
+## Ask real questions
+When you @mention someone, ask something specific that needs an answer.
+Don't send FYI messages that waste their context window.
+
+Good: "@backend what's the token expiry? I need it for the refresh logic"
+Good: "@frontend are you using React Router or Next.js routing? Affects how I set up the auth middleware"
+Bad: "@backend FYI I'm working on the frontend" (no question, wastes their time)
+
+## Share your reasoning
+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
+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?"
+
+Better to ask than to silently introduce a breaking change.
+
+## Respond when asked
+If another agent @mentions you, always respond — even briefly.
+The requesting agent may be blocked waiting for your answer.
+"Got it, the payload is {sub, email, role}. Using 1h expiry."
+
+## Share discoveries
+If you learn something about the project that other agents should know, state it clearly.
+"The project uses Drizzle ORM with PostgreSQL, not Prisma as I initially assumed."
+The squad system captures these as shared knowledge.

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

@@ -0,0 +1,65 @@
+---
+name: squad-protocol
+description: Core communication protocol for multi-agent squad collaboration. Defines how agents talk to each other, signal status, and coordinate work.
+---
+
+# Squad Protocol
+
+You are part of a multi-agent squad. Other agents are working on related tasks in parallel.
+
+## Communication
+
+### Talking to other agents
+Write @agentname followed by your message in your regular output.
+The squad system parses @mentions and routes messages to the target agent in real-time.
+
+Examples:
+- "@frontend what token format do you need for the login endpoint?"
+- "@backend the schema needs a `role` column on the users table"
+- "@qa the API is ready at /api/auth — here are the test endpoints..."
+
+### Receiving messages
+Messages from other agents and the human arrive as interruptions in your conversation.
+They are prefixed with `[squad]`. Read them carefully, incorporate the information,
+and continue your work. Don't ignore incoming messages.
+
+### 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.
+This output gets passed to dependent tasks as context — vague summaries waste their time.
+
+Good: "Created JWT middleware in src/middleware/auth.ts. Validates RS256 tokens,
+extracts user from payload, attaches to req.user. Test: curl -H 'Authorization: Bearer ...' localhost:3000/api/me"
+
+Bad: "Done with the auth middleware."
+
+### Blocking
+If you cannot proceed, clearly explain:
+1. What you need
+2. Who might have it (use @mention)
+3. Why you can't continue without it
+
+The squad system will detect this and route help to you.
+
+## Rules
+
+### Stay in scope
+Your task description defines your scope. If you discover work that's outside
+your task, mention it but don't do it. The squad system will create a new task if needed.
+
+### Don't duplicate work
+Your system prompt includes outputs from completed dependency tasks.
+Read them before starting. Don't redo work that's already done.
+
+### Coordinate on shared files
+Your system prompt lists files modified by other agents.
+If you need to edit a file another agent owns, message them first with @mention.
+Don't silently overwrite their changes.
+
+### Ask for help
+If you're stuck for more than a few minutes, say so clearly.
+The squad system monitors your activity and will intervene, but being explicit is faster.
+
+### Read before writing
+Before modifying any file, read it first. Another agent may have changed it
+since the last time you saw it.

package/src/skills/verification/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: verification
+description: Verify work before claiming completion — evidence-based discipline for multi-agent handoffs.
+---
+
+# Verification
+
+Before claiming your task is done, verify that your work actually works.
+Your output gets passed to dependent tasks. If it's wrong, the entire chain fails.
+
+## The Protocol
+
+1. **IDENTIFY**: What command or test proves the work is correct?
+2. **RUN**: Execute it fresh — don't rely on earlier results
+3. **READ**: Check the full output, not just the exit code
+4. **VERIFY**: Does the output confirm your claim?
+   - If NO: fix it, then re-verify
+   - If YES: include the evidence in your output
+
+## Red Flags — Stop If You Catch Yourself
+
+- Using "should work", "probably correct", "looks right"
+- Claiming done without running the code
+- Assuming tests pass without executing them
+- Expressing satisfaction before verification
+- Saying "just this one time" about skipping verification
+
+## Output Checklist
+
+When completing a task, your final message must include:
+
+1. **What you built/changed** — specific file paths
+2. **How to verify** — exact command or steps
+3. **Evidence** — actual output from running the verification
+
+Example:
+```
+Created JWT middleware:
+- src/lib/jwt.ts — token generation (RS256, 1h expiry)
+- src/middleware/auth.ts — validation middleware
+- test/auth.test.ts — 8 tests
+
+Verification:
+$ npm test -- test/auth.test.ts
+✓ generates valid JWT (12ms)
+✓ validates token signature (3ms)
+✓ rejects expired tokens (5ms)
+...
+8 tests passed, 0 failed
+```
+
+## For Implementation Tasks
+
+- Run the code, don't just write it
+- Check for TypeScript/lint errors
+- Run related tests if they exist
+- Verify the feature works end-to-end, not just that it compiles
+
+## For Research/Analysis Tasks
+
+- Cite specific files and line numbers
+- Include relevant code snippets as evidence
+- State confidence level on uncertain findings
+- List what you checked AND what you didn't check

package/src/store.ts

@@ -0,0 +1,458 @@
+/**
+ * store.ts — JSON file I/O for squad state.
+ *
+ * All state lives in .pi/squad/ as JSON files.
+ * Writes are atomic (write to temp, rename).
+ * JSONL files are append-only.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import type {
+	AgentDef,
+	KnowledgeEntry,
+	Squad,
+	SquadContext,
+	Task,
+	TaskMessage,
+	TaskUsage,
+	DEFAULT_SQUAD_CONFIG,
+} from "./types.js";
+
+// ============================================================================
+// Paths
+// ============================================================================
+
+/**
+ * Two-tier storage:
+ *
+ * Global: ~/.pi/squad/
+ *   ├── agents/          — default agent definitions
+ *   └── {squad-id}/      — all squad instances (each has cwd in squad.json)
+ *
+ * Local (project override): {project}/.pi/squad/
+ *   └── agents/          — project-specific agent overrides (checked first)
+ *
+ * Squad instances are always global. Agents are merged (local overrides global).
+ * Each squad stores its project cwd in squad.json for agent execution.
+ * Listing/widget filters squads by current project cwd.
+ */
+const SQUAD_HOME = path.join(os.homedir(), ".pi", "squad");
+
+export function getSquadRoot(): string {
+	return SQUAD_HOME;
+}
+
+/** Global agent directory */
+export function getGlobalAgentsDir(): string {
+	return path.join(SQUAD_HOME, "agents");
+}
+
+/** Project-local agent directory (overrides global) */
+export function getLocalAgentsDir(projectCwd: string): string {
+	return path.join(projectCwd, ".pi", "squad", "agents");
+}
+
+/**
+ * Effective agents directory. For writes (bootstrap), always use global.
+ * For reads, merge local over global via loadAllAgentDefs(projectCwd).
+ */
+export function getAgentsDir(): string {
+	return getGlobalAgentsDir();
+}
+
+export function getSquadDir(squadId: string): string {
+	return path.join(getSquadRoot(), squadId);
+}
+
+export function getSquadFilePath(squadId: string): string {
+	return path.join(getSquadDir(squadId), "squad.json");
+}
+
+export function getContextFilePath(squadId: string): string {
+	return path.join(getSquadDir(squadId), "context.json");
+}
+
+export function getKnowledgeDir(squadId: string): string {
+	return path.join(getSquadDir(squadId), "knowledge");
+}
+
+export function getMemoryFilePath(): string {
+	return path.join(getSquadRoot(), "memory.jsonl");
+}
+
+/** Resolve task dir, supporting nested subtasks via parentPath */
+export function getTaskDir(squadId: string, taskId: string, parentPath?: string): string {
+	const base = parentPath
+		? path.join(getSquadDir(squadId), parentPath, taskId)
+		: path.join(getSquadDir(squadId), taskId);
+	return base;
+}
+
+export function getTaskFilePath(squadId: string, taskId: string, parentPath?: string): string {
+	return path.join(getTaskDir(squadId, taskId, parentPath), "task.json");
+}
+
+export function getMessagesFilePath(squadId: string, taskId: string, parentPath?: string): string {
+	return path.join(getTaskDir(squadId, taskId, parentPath), "messages.jsonl");
+}
+
+// ============================================================================
+// Atomic File Operations
+// ============================================================================
+
+function ensureDir(dirPath: string): void {
+	if (!fs.existsSync(dirPath)) {
+		fs.mkdirSync(dirPath, { recursive: true });
+	}
+}
+
+/** Write JSON atomically: write to temp file, then rename */
+function writeJsonAtomic(filePath: string, data: unknown): void {
+	ensureDir(path.dirname(filePath));
+	const tmp = filePath + `.tmp.${process.pid}.${Date.now()}`;
+	fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n", "utf-8");
+	fs.renameSync(tmp, filePath);
+}
+
+function readJson<T>(filePath: string): T | null {
+	try {
+		const content = fs.readFileSync(filePath, "utf-8");
+		return JSON.parse(content) as T;
+	} catch {
+		return null;
+	}
+}
+
+/** Append a JSONL line */
+function appendJsonl(filePath: string, entry: unknown): void {
+	ensureDir(path.dirname(filePath));
+	fs.appendFileSync(filePath, JSON.stringify(entry) + "\n", "utf-8");
+}
+
+/** Read all JSONL lines */
+function readJsonl<T>(filePath: string): T[] {
+	try {
+		const content = fs.readFileSync(filePath, "utf-8").trim();
+		if (!content) return [];
+		return content.split("\n").map((line) => JSON.parse(line) as T);
+	} catch {
+		return [];
+	}
+}
+
+// ============================================================================
+// Agent Definitions (global + local override)
+// ============================================================================
+
+/**
+ * Load agent by name. Checks project-local first, then global.
+ */
+export function loadAgentDef(name: string, projectCwd?: string): AgentDef | null {
+	// Check local override first
+	if (projectCwd) {
+		const localFile = path.join(getLocalAgentsDir(projectCwd), `${name}.json`);
+		const local = readJson<AgentDef>(localFile);
+		if (local) return local;
+	}
+	// Fall back to global
+	return readJson<AgentDef>(path.join(getGlobalAgentsDir(), `${name}.json`));
+}
+
+/**
+ * Load all agents, merging local overrides on top of global.
+ * Local agents with the same name replace global ones.
+ */
+export function loadAllAgentDefs(projectCwd?: string): AgentDef[] {
+	const agents = new Map<string, AgentDef>();
+
+	// Load global first
+	const globalDir = getGlobalAgentsDir();
+	if (fs.existsSync(globalDir)) {
+		for (const f of fs.readdirSync(globalDir).filter((f) => f.endsWith(".json"))) {
+			const agent = readJson<AgentDef>(path.join(globalDir, f));
+			if (agent) agents.set(agent.name, agent);
+		}
+	}
+
+	// Overlay local overrides
+	if (projectCwd) {
+		const localDir = getLocalAgentsDir(projectCwd);
+		if (fs.existsSync(localDir)) {
+			for (const f of fs.readdirSync(localDir).filter((f) => f.endsWith(".json"))) {
+				const agent = readJson<AgentDef>(path.join(localDir, f));
+				if (agent) agents.set(agent.name, agent);
+			}
+		}
+	}
+
+	return Array.from(agents.values());
+}
+
+/** Save agent to global directory */
+export function saveAgentDef(agent: AgentDef): void {
+	writeJsonAtomic(path.join(getGlobalAgentsDir(), `${agent.name}.json`), agent);
+}
+
+/** Save agent to project-local directory (override) */
+export function saveLocalAgentDef(agent: AgentDef, projectCwd: string): void {
+	writeJsonAtomic(path.join(getLocalAgentsDir(projectCwd), `${agent.name}.json`), agent);
+}
+
+export function deleteAgentDef(name: string): boolean {
+	const filePath = path.join(getGlobalAgentsDir(), `${name}.json`);
+	if (fs.existsSync(filePath)) {
+		fs.unlinkSync(filePath);
+		return true;
+	}
+	return false;
+}
+
+// ============================================================================
+// Squad
+// ============================================================================
+
+export function loadSquad(squadId: string): Squad | null {
+	return readJson<Squad>(getSquadFilePath(squadId));
+}
+
+export function saveSquad(squad: Squad): void {
+	writeJsonAtomic(getSquadFilePath(squad.id), squad);
+}
+
+export function listSquads(): string[] {
+	const root = getSquadRoot();
+	if (!fs.existsSync(root)) return [];
+	return fs
+		.readdirSync(root)
+		.filter((entry) => {
+			if (entry === "agents" || entry === "memory.jsonl") return false;
+			const squadFile = path.join(root, entry, "squad.json");
+			return fs.existsSync(squadFile);
+		});
+}
+
+export function findActiveSquads(): Squad[] {
+	return listSquads()
+		.map((id) => loadSquad(id))
+		.filter((s): s is Squad => s !== null && (s.status === "running" || s.status === "paused"));
+}
+
+/** List squads filtered by project cwd. If no cwd, returns all. */
+export function listSquadsForProject(projectCwd?: string): Squad[] {
+	return listSquads()
+		.map((id) => loadSquad(id))
+		.filter((s): s is Squad => {
+			if (!s) return false;
+			if (!projectCwd) return true;
+			return s.cwd === projectCwd;
+		});
+}
+
+/** Find most recent squad for a project (by creation time) */
+export function findLatestSquad(projectCwd?: string): Squad | null {
+	const squads = listSquadsForProject(projectCwd);
+	if (squads.length === 0) return null;
+	return squads.sort((a, b) => b.created.localeCompare(a.created))[0];
+}
+
+// ============================================================================
+// Tasks
+// ============================================================================
+
+export function loadTask(squadId: string, taskId: string, parentPath?: string): Task | null {
+	return readJson<Task>(getTaskFilePath(squadId, taskId, parentPath));
+}
+
+export function saveTask(squadId: string, task: Task, parentPath?: string): void {
+	writeJsonAtomic(getTaskFilePath(squadId, task.id, parentPath), task);
+}
+
+/** Load all tasks for a squad (flat list, scans top-level task folders) */
+export function loadAllTasks(squadId: string): Task[] {
+	const squadDir = getSquadDir(squadId);
+	if (!fs.existsSync(squadDir)) return [];
+
+	const tasks: Task[] = [];
+	const seen = new Set<string>();
+	const entries = fs.readdirSync(squadDir, { withFileTypes: true });
+
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		if (entry.name === "knowledge") continue;
+		const taskFile = path.join(squadDir, entry.name, "task.json");
+		const task = readJson<Task>(taskFile);
+		if (task && !seen.has(task.id)) {
+			seen.add(task.id);
+			tasks.push(task);
+			// Scan for subtasks
+			collectSubtasks(squadDir, entry.name, tasks, seen);
+		}
+	}
+
+	return tasks;
+}
+
+function collectSubtasks(squadDir: string, parentPath: string, tasks: Task[], seen: Set<string>): void {
+	const parentDir = path.join(squadDir, parentPath);
+	let entries;
+	try {
+		entries = fs.readdirSync(parentDir, { withFileTypes: true });
+	} catch {
+		return;
+	}
+
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		const taskFile = path.join(parentDir, entry.name, "task.json");
+		const task = readJson<Task>(taskFile);
+		if (task && !seen.has(task.id)) {
+			seen.add(task.id);
+			tasks.push(task);
+			collectSubtasks(squadDir, path.join(parentPath, entry.name), tasks, seen);
+		}
+	}
+}
+
+export function createTask(squadId: string, task: Task, parentPath?: string): void {
+	ensureDir(getTaskDir(squadId, task.id, parentPath));
+	saveTask(squadId, task, parentPath);
+}
+
+export function updateTaskStatus(
+	squadId: string,
+	taskId: string,
+	status: Task["status"],
+	extra?: Partial<Pick<Task, "output" | "error" | "started" | "completed">>,
+): void {
+	const task = loadTask(squadId, taskId);
+	if (!task) return;
+	task.status = status;
+	if (extra) {
+		if (extra.output !== undefined) task.output = extra.output;
+		if (extra.error !== undefined) task.error = extra.error;
+		if (extra.started !== undefined) task.started = extra.started;
+		if (extra.completed !== undefined) task.completed = extra.completed;
+	}
+	saveTask(squadId, task);
+}
+
+export function updateTaskUsage(squadId: string, taskId: string, usage: Partial<TaskUsage>): void {
+	const task = loadTask(squadId, taskId);
+	if (!task) return;
+	if (usage.inputTokens !== undefined) task.usage.inputTokens += usage.inputTokens;
+	if (usage.outputTokens !== undefined) task.usage.outputTokens += usage.outputTokens;
+	if (usage.cost !== undefined) task.usage.cost += usage.cost;
+	if (usage.turns !== undefined) task.usage.turns += usage.turns;
+	saveTask(squadId, task);
+}
+
+// ============================================================================
+// Messages
+// ============================================================================
+
+export function appendMessage(squadId: string, taskId: string, message: TaskMessage, parentPath?: string): void {
+	appendJsonl(getMessagesFilePath(squadId, taskId, parentPath), message);
+}
+
+export function loadMessages(squadId: string, taskId: string, parentPath?: string): TaskMessage[] {
+	return readJsonl<TaskMessage>(getMessagesFilePath(squadId, taskId, parentPath));
+}
+
+// ============================================================================
+// Context
+// ============================================================================
+
+export function loadContext(squadId: string): SquadContext | null {
+	return readJson<SquadContext>(getContextFilePath(squadId));
+}
+
+export function saveContext(squadId: string, context: SquadContext): void {
+	writeJsonAtomic(getContextFilePath(squadId), context);
+}
+
+// ============================================================================
+// Knowledge
+// ============================================================================
+
+export function appendKnowledge(squadId: string, type: KnowledgeEntry["type"], entry: KnowledgeEntry): void {
+	const file = path.join(getKnowledgeDir(squadId), `${type}s.jsonl`);
+	appendJsonl(file, entry);
+}
+
+export function loadKnowledge(squadId: string, type: KnowledgeEntry["type"]): KnowledgeEntry[] {
+	const file = path.join(getKnowledgeDir(squadId), `${type}s.jsonl`);
+	return readJsonl<KnowledgeEntry>(file);
+}
+
+export function loadAllKnowledge(squadId: string): KnowledgeEntry[] {
+	return [
+		...loadKnowledge(squadId, "decision"),
+		...loadKnowledge(squadId, "convention"),
+		...loadKnowledge(squadId, "finding"),
+	].sort((a, b) => a.ts.localeCompare(b.ts));
+}
+
+// ============================================================================
+// Memory (cross-squad)
+// ============================================================================
+
+export function appendMemory(entry: KnowledgeEntry): void {
+	appendJsonl(getMemoryFilePath(), entry);
+}
+
+export function loadMemory(): KnowledgeEntry[] {
+	return readJsonl<KnowledgeEntry>(getMemoryFilePath());
+}
+
+// ============================================================================
+// Bootstrap — first-run agent initialization
+// ============================================================================
+
+/**
+ * Copy default agents to .pi/squad/agents/ if they don't exist yet.
+ * Never overwrites user's existing files.
+ */
+export function bootstrapAgents(defaultsDir: string): { copied: string[]; skipped: string[] } {
+	const targetDir = getAgentsDir();
+	ensureDir(targetDir);
+
+	const copied: string[] = [];
+	const skipped: string[] = [];
+
+	if (!fs.existsSync(defaultsDir)) return { copied, skipped };
+
+	for (const file of fs.readdirSync(defaultsDir)) {
+		if (!file.endsWith(".json")) continue;
+		const target = path.join(targetDir, file);
+		if (fs.existsSync(target)) {
+			skipped.push(file);
+		} else {
+			fs.copyFileSync(path.join(defaultsDir, file), target);
+			copied.push(file);
+		}
+	}
+
+	return { copied, skipped };
+}
+
+// ============================================================================
+// Utility
+// ============================================================================
+
+export function now(): string {
+	return new Date().toISOString();
+}
+
+export function makeTaskId(title: string): string {
+	return title
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-|-$/g, "")
+		.slice(0, 40);
+}
+
+export function squadExists(squadId: string): boolean {
+	return fs.existsSync(getSquadFilePath(squadId));
+}