pi-teams 0.9.5 → 0.9.6

package/README.md

@@ -45,6 +45,7 @@ pi install npm:pi-teams
 - **Beautiful UI**: Optimized vertical splits in `tmux` with clear labels so you always know who is doing what.
 
 ### Advanced Features
+- **Predefined Teams**: Define team templates in `teams.yaml` and spawn entire teams with a single command.
 - **Isolated OS Windows**: Launch teammates in true separate OS windows instead of panes.
 - **Persistent Window Titles**: Windows are automatically titled `[team-name]: [agent-name]` for easy identification in your window manager.
 - **Plan Approval Mode**: Require teammates to submit their implementation plans for your approval before they touch any code.
@@ -108,6 +109,95 @@ Teammates in `planning` mode will use `task_submit_plan`. As the lead, review th
 
 ---
 
+## 🏗️ Predefined Teams
+
+Predefined teams let you define reusable team templates in a `teams.yaml` file. This is perfect for common workflows where you always want the same set of specialists.
+
+### Define Team Templates
+
+Create `~/.pi/teams.yaml` (global) or `.pi/teams.yaml` in your project:
+
+```yaml
+# Full development team
+full:
+  - scout
+  - planner
+  - builder
+  - reviewer
+  - documenter
+
+# Quick plan-build cycle
+plan-build:
+  - planner
+  - builder
+  - reviewer
+
+# Research and documentation
+research:
+  - scout
+  - documenter
+
+# Frontend specialists
+frontend:
+  - planner
+  - builder
+  - bowser
+```
+
+### Define Agent Definitions
+
+Create agent definitions in `~/.pi/agent/agents/` (global) or `.pi/agents/` (project-local):
+
+**scout.md:**
+```markdown
+---
+name: scout
+description: Fast recon and codebase exploration
+tools: read,grep,find,ls
+---
+You are a scout agent. Investigate the codebase quickly and report findings concisely. Do NOT modify any files. Focus on structure, patterns, and key entry points.
+```
+
+**builder.md:**
+```markdown
+---
+name: builder
+description: Implementation specialist
+tools: read,write,edit,bash
+model: claude-sonnet-4
+thinking: medium
+---
+You are a builder agent. Implement code following the plan provided. Write clean, tested code.
+```
+
+**Agent Definition Fields:**
+- `name` (required): The agent's name
+- `description` (required): What the agent does
+- `tools` (optional): Comma or space-separated list of allowed tools
+- `model` (optional): Model to use (e.g., `claude-sonnet-4`, `gpt-4o`)
+- `thinking` (optional): Thinking level (`off`, `minimal`, `low`, `medium`, `high`)
+
+### Use Predefined Teams
+
+**List available team templates:**
+> **You:** "List all predefined teams I can use."
+
+**List available agent definitions:**
+> **You:** "Show me all predefined agents."
+
+**Create a team from a template:**
+> **You:** "Create a team named 'my-project' from the 'plan-build' predefined team in the current directory."
+
+This single command:
+1. Creates the team
+2. Spawns all agents defined in the template
+3. Each agent gets its predefined prompt, tools, model, and thinking settings
+
+**With options:**
+> **You:** "Create a team named 'big-team' from 'full' predefined team using 'gpt-4o' as default model and separate windows."
+
+---
+
 ## 📚 Learn More
 
 - **[Full Usage Guide](docs/guide.md)** - Detailed examples, hook system, best practices, and troubleshooting

package/extensions/index.ts

@@ -9,6 +9,7 @@ import * as runtime from "../src/utils/runtime";
 import { Member } from "../src/utils/models";
 import { getTerminalAdapter } from "../src/adapters/terminal-registry";
 import { Iterm2Adapter } from "../src/adapters/iterm2-adapter";
+import * as predefined from "../src/utils/predefined-teams";
 import * as path from "node:path";
 import * as fs from "node:fs";
 import { spawnSync } from "node:child_process";
@@ -897,4 +898,216 @@ export default function (pi: ExtensionAPI) {
       };
     },
   });
+
+  pi.registerTool({
+    name: "list_predefined_teams",
+    label: "List Predefined Teams",
+    description: "List all available predefined team configurations from teams.yaml files. These are team templates that can be instantiated with create_predefined_team.",
+    parameters: Type.Object({}),
+    async execute(toolCallId, params: any, signal, onUpdate, ctx) {
+      const projectDir = ctx.cwd;
+      const predefinedTeams = predefined.getAllPredefinedTeams(projectDir);
+      const agents = predefined.getAllAgentDefinitions(projectDir);
+      
+      const result = predefinedTeams.map(team => {
+        const teamAgents = team.agents.map(agentName => {
+          const agentDef = agents.find(a => a.name === agentName);
+          return {
+            name: agentName,
+            description: agentDef?.description || "(agent definition not found)",
+            found: !!agentDef,
+          };
+        });
+        
+        return {
+          name: team.name,
+          agents: teamAgents,
+        };
+      });
+
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        details: { teams: result },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "list_predefined_agents",
+    label: "List Predefined Agents",
+    description: "List all available predefined agent definitions from .md files. These can be used individually or as part of predefined teams.",
+    parameters: Type.Object({}),
+    async execute(toolCallId, params: any, signal, onUpdate, ctx) {
+      const projectDir = ctx.cwd;
+      const agents = predefined.getAllAgentDefinitions(projectDir);
+      
+      const result = agents.map(agent => ({
+        name: agent.name,
+        description: agent.description,
+        tools: agent.tools,
+        model: agent.model,
+        thinking: agent.thinking,
+      }));
+
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        details: { agents: result },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "create_predefined_team",
+    label: "Create Predefined Team",
+    description: "Create a team from a predefined team configuration. Spawns all agents defined in the team template from teams.yaml. Each agent is spawned with its predefined prompt, tools, and settings.",
+    parameters: Type.Object({
+      team_name: Type.String({ description: "Name for the new team instance" }),
+      predefined_team: Type.String({ description: "Name of the predefined team template from teams.yaml" }),
+      cwd: Type.String({ description: "Working directory for spawned agents" }),
+      default_model: Type.Optional(Type.String({ description: "Default model for agents without a specified model" })),
+      separate_windows: Type.Optional(Type.Boolean({ default: false, description: "Open teammates in separate OS windows instead of panes" })),
+    }),
+    async execute(toolCallId, params: any, signal, onUpdate, ctx) {
+      const projectDir = ctx.cwd;
+      const predefinedTeam = predefined.getPredefinedTeam(params.predefined_team, projectDir);
+      
+      if (!predefinedTeam) {
+        const available = predefined.getAllPredefinedTeams(projectDir).map(t => t.name);
+        throw new Error(`Predefined team "${params.predefined_team}" not found. Available teams: ${available.join(", ") || "none"}`);
+      }
+
+      if (!terminal) {
+        throw new Error("No terminal adapter detected.");
+      }
+
+      // Create the team
+      const config = teams.createTeam(params.team_name, "local-session", "lead-agent", `Predefined team: ${params.predefined_team}`, params.default_model, params.separate_windows);
+      registerLeadSession(params.team_name);
+
+      const agentDefinitions = predefined.getAllAgentDefinitions(projectDir);
+      const spawnResults: Array<{ name: string; status: string; error?: string }> = [];
+
+      // Spawn each agent in the predefined team
+      for (const agentName of predefinedTeam.agents) {
+        const agentDef = agentDefinitions.find(a => a.name === agentName);
+        
+        if (!agentDef) {
+          spawnResults.push({ name: agentName, status: "skipped", error: "Agent definition not found" });
+          continue;
+        }
+
+        try {
+          const safeName = paths.sanitizeName(agentName);
+          const safeTeamName = paths.sanitizeName(params.team_name);
+          
+          let chosenModel = agentDef.model || params.default_model || config.defaultModel;
+          
+          if (chosenModel && !chosenModel.includes('/')) {
+            const resolved = resolveModelWithProvider(chosenModel);
+            if (resolved) {
+              chosenModel = resolved;
+            } else if (config.defaultModel && config.defaultModel.includes('/')) {
+              const [provider] = config.defaultModel.split('/');
+              chosenModel = `${provider}/${chosenModel}`;
+            }
+          }
+
+          const useSeparateWindow = params.separate_windows ?? config.separateWindows ?? false;
+          if (useSeparateWindow && !terminal.supportsWindows()) {
+            throw new Error(`Separate windows mode is not supported in ${terminal.name}.`);
+          }
+
+          const member: Member = {
+            agentId: `${safeName}@${safeTeamName}`,
+            name: safeName,
+            agentType: "teammate",
+            model: chosenModel,
+            joinedAt: Date.now(),
+            tmuxPaneId: "",
+            cwd: params.cwd,
+            subscriptions: [],
+            prompt: agentDef.prompt,
+            color: "blue",
+            thinking: agentDef.thinking,
+          };
+
+          await teams.addMember(safeTeamName, member);
+          await messaging.sendPlainMessage(safeTeamName, "team-lead", safeName, agentDef.prompt, "Initial prompt from predefined team");
+
+          const piBinary = process.argv[1] ? `node ${process.argv[1]}` : "pi";
+          let piCmd = piBinary;
+
+          if (chosenModel) {
+            if (agentDef.thinking) {
+              piCmd = `${piBinary} --model ${chosenModel}:${agentDef.thinking}`;
+            } else {
+              piCmd = `${piBinary} --model ${chosenModel}`;
+            }
+          } else if (agentDef.thinking) {
+            piCmd = `${piBinary} --thinking ${agentDef.thinking}`;
+          }
+
+          const env: Record<string, string> = {
+            ...process.env,
+            PI_TEAM_NAME: safeTeamName,
+            PI_AGENT_NAME: safeName,
+          };
+
+          let terminalId = "";
+          let isWindow = false;
+
+          try {
+            if (useSeparateWindow) {
+              isWindow = true;
+              terminalId = terminal.spawnWindow({
+                name: safeName,
+                cwd: params.cwd,
+                command: piCmd,
+                env: env,
+                teamName: safeTeamName,
+              });
+              await teams.updateMember(safeTeamName, safeName, { windowId: terminalId });
+            } else {
+              if (terminal instanceof Iterm2Adapter) {
+                const teammates = (await teams.readConfig(safeTeamName)).members.filter(m => m.agentType === "teammate" && m.tmuxPaneId.startsWith("iterm_"));
+                const lastTeammate = teammates.length > 0 ? teammates[teammates.length - 1] : null;
+                if (lastTeammate?.tmuxPaneId) {
+                  terminal.setSpawnContext({ lastSessionId: lastTeammate.tmuxPaneId.replace("iterm_", "") });
+                } else {
+                  terminal.setSpawnContext({});
+                }
+              }
+
+              const leadMember = (await teams.readConfig(safeTeamName)).members.find(m => m.name === "team-lead");
+              const anchorPaneId = terminal.name === "tmux"
+                ? leadMember?.tmuxPaneId || process.env.TMUX_PANE || undefined
+                : undefined;
+
+              terminalId = terminal.spawn({
+                name: safeName,
+                cwd: params.cwd,
+                command: piCmd,
+                env: env,
+                anchorPaneId,
+              });
+              await teams.updateMember(safeTeamName, safeName, { tmuxPaneId: terminalId });
+            }
+
+            spawnResults.push({ name: agentName, status: "spawned", error: undefined });
+          } catch (e) {
+            spawnResults.push({ name: agentName, status: "error", error: `Failed to spawn: ${e}` });
+          }
+        } catch (e) {
+          spawnResults.push({ name: agentName, status: "error", error: String(e) });
+        }
+      }
+
+      const summary = spawnResults.map(r => `${r.name}: ${r.status}${r.error ? ` (${r.error})` : ""}`).join("\n");
+      
+      return {
+        content: [{ type: "text", text: `Team "${params.team_name}" created from predefined team "${params.predefined_team}".\n\nAgent spawn results:\n${summary}` }],
+        details: { teamName: params.team_name, predefinedTeam: params.predefined_team, results: spawnResults },
+      };
+    },
+  });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-teams",
-  "version": "0.9.5",
+  "version": "0.9.6",
   "description": "Agent teams for pi, ported from claude-code-teams-mcp",
   "repository": {
     "type": "git",
@@ -9,7 +9,18 @@
   "author": "Mark Burggraf",
   "license": "MIT",
   "keywords": [
-    "pi-package"
+    "pi-package",
+    "ai-agent",
+    "multi-agent",
+    "agent-teams",
+    "agent-coordination",
+    "autonomous-agents",
+    "task-management",
+    "team-collaboration",
+    "agent-orchestration",
+    "coding-assistant",
+    "terminal",
+    "tmux"
   ],
   "scripts": {
     "test": "vitest run"

package/src/utils/predefined-teams.test.ts

@@ -0,0 +1,389 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import {
+  parseAgentFrontmatter,
+  parseTeamsYaml,
+  discoverAgents,
+  discoverTeams,
+  getAllAgentDefinitions,
+  getAllPredefinedTeams,
+  getAgentDefinition,
+  getPredefinedTeam,
+} from "./predefined-teams";
+
+describe("parseAgentFrontmatter", () => {
+  it("parses a valid agent definition with all fields", () => {
+    const content = `---
+name: scout
+description: Fast recon and codebase exploration
+tools: read,grep,find,ls
+model: claude-sonnet-4
+thinking: high
+---
+You are a scout agent. Investigate the codebase quickly.`;
+
+    const result = parseAgentFrontmatter(content, "/test/scout.md");
+    
+    expect(result).not.toBeNull();
+    expect(result?.name).toBe("scout");
+    expect(result?.description).toBe("Fast recon and codebase exploration");
+    expect(result?.tools).toEqual(["read", "grep", "find", "ls"]);
+    expect(result?.model).toBe("claude-sonnet-4");
+    expect(result?.thinking).toBe("high");
+    expect(result?.prompt).toBe("You are a scout agent. Investigate the codebase quickly.");
+    expect(result?.filePath).toBe("/test/scout.md");
+  });
+
+  it("parses an agent definition with space-separated tools", () => {
+    const content = `---
+name: builder
+description: Code builder
+tools: read write edit bash
+---
+You build things.`;
+
+    const result = parseAgentFrontmatter(content, "/test/builder.md");
+    
+    expect(result).not.toBeNull();
+    expect(result?.tools).toEqual(["read", "write", "edit", "bash"]);
+  });
+
+  it("parses an agent definition without optional fields", () => {
+    const content = `---
+name: simple
+description: Simple agent
+---
+You are simple.`;
+
+    const result = parseAgentFrontmatter(content, "/test/simple.md");
+    
+    expect(result).not.toBeNull();
+    expect(result?.name).toBe("simple");
+    expect(result?.description).toBe("Simple agent");
+    expect(result?.tools).toBeUndefined();
+    expect(result?.model).toBeUndefined();
+    expect(result?.thinking).toBeUndefined();
+    expect(result?.prompt).toBe("You are simple.");
+  });
+
+  it("returns null for content without frontmatter", () => {
+    const content = "This is just regular markdown without frontmatter.";
+    const result = parseAgentFrontmatter(content, "/test/no-frontmatter.md");
+    expect(result).toBeNull();
+  });
+
+  it("returns null for frontmatter without name", () => {
+    const content = `---
+description: Missing name field
+---
+Some prompt`;
+    const result = parseAgentFrontmatter(content, "/test/no-name.md");
+    expect(result).toBeNull();
+  });
+});
+
+describe("parseTeamsYaml", () => {
+  it("parses a valid teams.yaml content", () => {
+    const content = `
+full:
+  - scout
+  - planner
+  - builder
+
+plan-build:
+  - planner
+  - builder
+  - reviewer
+`;
+
+    const result = parseTeamsYaml(content);
+    
+    expect(result).toHaveLength(2);
+    expect(result[0].name).toBe("full");
+    expect(result[0].agents).toEqual(["scout", "planner", "builder"]);
+    expect(result[1].name).toBe("plan-build");
+    expect(result[1].agents).toEqual(["planner", "builder", "reviewer"]);
+  });
+
+  it("handles comments and empty lines", () => {
+    const content = `
+# This is a comment
+full:
+  - scout
+  # Another comment
+  - planner
+
+# Empty line above
+minimal:
+  - scout
+`;
+
+    const result = parseTeamsYaml(content);
+    
+    expect(result).toHaveLength(2);
+    expect(result[0].agents).toEqual(["scout", "planner"]);
+    expect(result[1].agents).toEqual(["scout"]);
+  });
+
+  it("returns empty array for empty content", () => {
+    expect(parseTeamsYaml("")).toEqual([]);
+    expect(parseTeamsYaml("# Just comments\n\n")).toEqual([]);
+  });
+
+  it("handles tab indentation", () => {
+    const content = `
+full:
+\t- scout
+\t- planner
+`;
+
+    const result = parseTeamsYaml(content);
+    
+    expect(result).toHaveLength(1);
+    expect(result[0].agents).toEqual(["scout", "planner"]);
+  });
+});
+
+describe("discoverAgents", () => {
+  const testDir = path.join(os.tmpdir(), "pi-teams-test-agents-" + Date.now());
+
+  beforeEach(() => {
+    if (fs.existsSync(testDir)) {
+      fs.rmSync(testDir, { recursive: true });
+    }
+    fs.mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(testDir)) {
+      fs.rmSync(testDir, { recursive: true });
+    }
+  });
+
+  it("discovers agent definitions from markdown files", () => {
+    fs.writeFileSync(path.join(testDir, "scout.md"), `---
+name: scout
+description: Scout agent
+---
+Scout prompt`);
+
+    fs.writeFileSync(path.join(testDir, "builder.md"), `---
+name: builder
+description: Builder agent
+---
+Builder prompt`);
+
+    const result = discoverAgents(testDir);
+    
+    expect(result).toHaveLength(2);
+    expect(result.find(a => a.name === "scout")).toBeDefined();
+    expect(result.find(a => a.name === "builder")).toBeDefined();
+  });
+
+  it("discovers agents from SKILL.md in subdirectories", () => {
+    const subDir = path.join(testDir, "special-agent");
+    fs.mkdirSync(subDir, { recursive: true });
+    
+    fs.writeFileSync(path.join(subDir, "SKILL.md"), `---
+name: special
+description: Special agent
+---
+Special prompt`);
+
+    const result = discoverAgents(testDir);
+    
+    expect(result).toHaveLength(1);
+    expect(result[0].name).toBe("special");
+  });
+
+  it("returns empty array for non-existent directory", () => {
+    const result = discoverAgents("/non/existent/path");
+    expect(result).toEqual([]);
+  });
+
+  it("ignores files without valid frontmatter", () => {
+    fs.writeFileSync(path.join(testDir, "invalid.md"), "No frontmatter here");
+    fs.writeFileSync(path.join(testDir, "valid.md"), `---
+name: valid
+description: Valid agent
+---
+Valid prompt`);
+
+    const result = discoverAgents(testDir);
+    
+    expect(result).toHaveLength(1);
+    expect(result[0].name).toBe("valid");
+  });
+});
+
+describe("discoverTeams", () => {
+  const testDir = path.join(os.tmpdir(), "pi-teams-test-teams-" + Date.now());
+
+  beforeEach(() => {
+    if (fs.existsSync(testDir)) {
+      fs.rmSync(testDir, { recursive: true });
+    }
+    fs.mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(testDir)) {
+      fs.rmSync(testDir, { recursive: true });
+    }
+  });
+
+  it("discovers teams from teams.yaml", () => {
+    fs.writeFileSync(path.join(testDir, "teams.yaml"), `
+full:
+  - scout
+  - planner
+`);
+
+    const result = discoverTeams(testDir);
+    
+    expect(result).toHaveLength(1);
+    expect(result[0].name).toBe("full");
+    expect(result[0].agents).toEqual(["scout", "planner"]);
+  });
+
+  it("returns empty array when teams.yaml does not exist", () => {
+    const result = discoverTeams(testDir);
+    expect(result).toEqual([]);
+  });
+});
+
+describe("getAllAgentDefinitions and getAllPredefinedTeams", () => {
+  const globalDir = path.join(os.homedir(), ".pi", "agent", "agents");
+  const globalTeamsDir = path.join(os.homedir(), ".pi", "agent");
+  const projectDir = path.join(os.tmpdir(), "pi-teams-test-project-" + Date.now());
+  const projectAgentsDir = path.join(projectDir, ".pi", "agents");
+  const projectTeamsDir = path.join(projectDir, ".pi");
+
+  // Store original files to restore later
+  let originalGlobalAgents: string[] = [];
+  let originalGlobalTeams: string | null = null;
+
+  beforeEach(() => {
+    // Create project directory
+    if (fs.existsSync(projectDir)) {
+      fs.rmSync(projectDir, { recursive: true });
+    }
+    fs.mkdirSync(projectAgentsDir, { recursive: true });
+
+    // Backup global files if they exist
+    if (fs.existsSync(globalDir)) {
+      originalGlobalAgents = fs.readdirSync(globalDir);
+    }
+    if (fs.existsSync(path.join(globalTeamsDir, "teams.yaml"))) {
+      originalGlobalTeams = fs.readFileSync(path.join(globalTeamsDir, "teams.yaml"), "utf-8");
+    }
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(projectDir)) {
+      fs.rmSync(projectDir, { recursive: true });
+    }
+  });
+
+  it("combines global and project-local agents", () => {
+    // Create project-local agent
+    fs.writeFileSync(path.join(projectAgentsDir, "project-agent.md"), `---
+name: project-agent
+description: Project local agent
+---
+Project prompt`);
+
+    const result = getAllAgentDefinitions(projectDir);
+    
+    // Should include project-local agent
+    expect(result.find(a => a.name === "project-agent")).toBeDefined();
+  });
+
+  it("project-local agents override global agents", () => {
+    // Create project-local agent with same name as global
+    fs.writeFileSync(path.join(projectAgentsDir, "scout.md"), `---
+name: scout
+description: Project override scout
+---
+Project scout prompt`);
+
+    const result = getAllAgentDefinitions(projectDir);
+    const scout = result.find(a => a.name === "scout");
+    
+    expect(scout).toBeDefined();
+    expect(scout?.description).toBe("Project override scout");
+  });
+
+  it("combines global and project-local teams", () => {
+    // Create project-local teams.yaml
+    fs.writeFileSync(path.join(projectTeamsDir, "teams.yaml"), `
+custom:
+  - agent1
+  - agent2
+`);
+
+    const result = getAllPredefinedTeams(projectDir);
+    
+    // Should include project-local team
+    expect(result.find(t => t.name === "custom")).toBeDefined();
+    expect(result.find(t => t.name === "custom")?.agents).toEqual(["agent1", "agent2"]);
+  });
+});
+
+describe("getAgentDefinition and getPredefinedTeam", () => {
+  const projectDir = path.join(os.tmpdir(), "pi-teams-test-get-" + Date.now());
+  const projectAgentsDir = path.join(projectDir, ".pi", "agents");
+  const projectTeamsDir = path.join(projectDir, ".pi");
+
+  beforeEach(() => {
+    if (fs.existsSync(projectDir)) {
+      fs.rmSync(projectDir, { recursive: true });
+    }
+    fs.mkdirSync(projectAgentsDir, { recursive: true });
+
+    fs.writeFileSync(path.join(projectAgentsDir, "test-agent.md"), `---
+name: test-agent
+description: Test agent
+---
+Test prompt`);
+
+    fs.writeFileSync(path.join(projectTeamsDir, "teams.yaml"), `
+test-team:
+  - test-agent
+`);
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(projectDir)) {
+      fs.rmSync(projectDir, { recursive: true });
+    }
+  });
+
+  it("gets a specific agent definition by name", () => {
+    const result = getAgentDefinition("test-agent", projectDir);
+    
+    expect(result).toBeDefined();
+    expect(result?.name).toBe("test-agent");
+    expect(result?.description).toBe("Test agent");
+  });
+
+  it("returns undefined for non-existent agent", () => {
+    const result = getAgentDefinition("non-existent", projectDir);
+    expect(result).toBeUndefined();
+  });
+
+  it("gets a specific predefined team by name", () => {
+    const result = getPredefinedTeam("test-team", projectDir);
+    
+    expect(result).toBeDefined();
+    expect(result?.name).toBe("test-team");
+    expect(result?.agents).toEqual(["test-agent"]);
+  });
+
+  it("returns undefined for non-existent team", () => {
+    const result = getPredefinedTeam("non-existent", projectDir);
+    expect(result).toBeUndefined();
+  });
+});

package/src/utils/predefined-teams.ts

@@ -0,0 +1,261 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+/**
+ * Represents an agent definition from a .md file
+ */
+export interface AgentDefinition {
+  name: string;
+  description: string;
+  tools?: string[];
+  model?: string;
+  thinking?: "off" | "minimal" | "low" | "medium" | "high";
+  prompt: string;
+  filePath: string;
+}
+
+/**
+ * Represents a predefined team from teams.yaml
+ */
+export interface PredefinedTeam {
+  name: string;
+  agents: string[];
+  description?: string;
+}
+
+/**
+ * Parse frontmatter from a markdown file
+ */
+export function parseAgentFrontmatter(content: string, filePath: string): AgentDefinition | null {
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!frontmatterMatch) {
+    return null;
+  }
+
+  const frontmatterStr = frontmatterMatch[1];
+  const prompt = frontmatterMatch[2].trim();
+  const frontmatter: Record<string, string> = {};
+
+  // Parse YAML-like frontmatter (simple key: value format)
+  for (const line of frontmatterStr.split("\n")) {
+    const colonIndex = line.indexOf(":");
+    if (colonIndex > 0) {
+      const key = line.slice(0, colonIndex).trim();
+      const value = line.slice(colonIndex + 1).trim();
+      frontmatter[key] = value;
+    }
+  }
+
+  const name = frontmatter.name;
+  if (!name) {
+    return null;
+  }
+
+  const description = frontmatter.description || "";
+  
+  // Parse tools (comma-separated or space-separated)
+  let tools: string[] | undefined;
+  if (frontmatter.tools) {
+    tools = frontmatter.tools.split(/[,\s]+/).map(t => t.trim()).filter(t => t);
+  }
+
+  const thinking = frontmatter.thinking as AgentDefinition["thinking"];
+  const model = frontmatter.model;
+
+  return {
+    name,
+    description,
+    tools,
+    model,
+    thinking,
+    prompt,
+    filePath,
+  };
+}
+
+/**
+ * Discover agent definitions from a directory
+ */
+export function discoverAgents(dir: string): AgentDefinition[] {
+  const agents: AgentDefinition[] = [];
+
+  if (!fs.existsSync(dir)) {
+    return agents;
+  }
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+
+    if (entry.isFile() && entry.name.endsWith(".md")) {
+      const content = fs.readFileSync(fullPath, "utf-8");
+      const agent = parseAgentFrontmatter(content, fullPath);
+      if (agent) {
+        agents.push(agent);
+      }
+    } else if (entry.isDirectory()) {
+      // Check for SKILL.md style (agent-name/SKILL.md)
+      const skillPath = path.join(fullPath, "SKILL.md");
+      if (fs.existsSync(skillPath)) {
+        const content = fs.readFileSync(skillPath, "utf-8");
+        const agent = parseAgentFrontmatter(content, skillPath);
+        if (agent) {
+          agents.push(agent);
+        }
+      }
+    }
+  }
+
+  return agents;
+}
+
+/**
+ * Parse teams.yaml content into PredefinedTeam array
+ */
+export function parseTeamsYaml(content: string): PredefinedTeam[] {
+  const teams: PredefinedTeam[] = [];
+  const lines = content.split("\n");
+  let currentTeam: PredefinedTeam | null = null;
+
+  for (const line of lines) {
+    // Skip empty lines and comments
+    if (!line.trim() || line.trim().startsWith("#")) {
+      continue;
+    }
+
+    // Check for team definition (no leading spaces, ends with colon)
+    if (!line.startsWith(" ") && !line.startsWith("\t") && line.endsWith(":")) {
+      // Save previous team
+      if (currentTeam && currentTeam.agents.length > 0) {
+        teams.push(currentTeam);
+      }
+      currentTeam = {
+        name: line.slice(0, -1).trim(),
+        agents: [],
+      };
+    } else if (currentTeam && (line.startsWith("  ") || line.startsWith("\t"))) {
+      // Agent entry (indented line starting with -)
+      const agentMatch = line.match(/^\s*-\s*(.+)$/);
+      if (agentMatch) {
+        currentTeam.agents.push(agentMatch[1].trim());
+      }
+    }
+  }
+
+  // Save last team
+  if (currentTeam && currentTeam.agents.length > 0) {
+    teams.push(currentTeam);
+  }
+
+  return teams;
+}
+
+/**
+ * Discover predefined teams from teams.yaml files
+ */
+export function discoverTeams(dir: string): PredefinedTeam[] {
+  const teamsPath = path.join(dir, "teams.yaml");
+  
+  if (!fs.existsSync(teamsPath)) {
+    return [];
+  }
+
+  try {
+    const content = fs.readFileSync(teamsPath, "utf-8");
+    return parseTeamsYaml(content);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Get all agent definitions from all locations
+ * Priority: project-local > global
+ */
+export function getAllAgentDefinitions(projectDir?: string): AgentDefinition[] {
+  const agents: AgentDefinition[] = [];
+  const seenNames = new Set<string>();
+
+  // Global agent definitions
+  const globalDir = path.join(os.homedir(), ".pi", "agent", "agents");
+  for (const agent of discoverAgents(globalDir)) {
+    if (!seenNames.has(agent.name)) {
+      seenNames.add(agent.name);
+      agents.push(agent);
+    }
+  }
+
+  // Project-local agent definitions
+  if (projectDir) {
+    const projectAgentsDir = path.join(projectDir, ".pi", "agents");
+    for (const agent of discoverAgents(projectAgentsDir)) {
+      if (!seenNames.has(agent.name)) {
+        seenNames.add(agent.name);
+        agents.push(agent);
+      } else {
+        // Override global with project-local
+        const idx = agents.findIndex(a => a.name === agent.name);
+        if (idx >= 0) {
+          agents[idx] = agent;
+        }
+      }
+    }
+  }
+
+  return agents;
+}
+
+/**
+ * Get all predefined teams from all locations
+ * Priority: project-local > global
+ */
+export function getAllPredefinedTeams(projectDir?: string): PredefinedTeam[] {
+  const teams: PredefinedTeam[] = [];
+  const seenNames = new Set<string>();
+
+  // Global teams
+  const globalDir = path.join(os.homedir(), ".pi", "agent");
+  for (const team of discoverTeams(globalDir)) {
+    if (!seenNames.has(team.name)) {
+      seenNames.add(team.name);
+      teams.push(team);
+    }
+  }
+
+  // Project-local teams
+  if (projectDir) {
+    const projectDirPath = path.join(projectDir, ".pi");
+    for (const team of discoverTeams(projectDirPath)) {
+      if (!seenNames.has(team.name)) {
+        seenNames.add(team.name);
+        teams.push(team);
+      } else {
+        // Override global with project-local
+        const idx = teams.findIndex(t => t.name === team.name);
+        if (idx >= 0) {
+          teams[idx] = team;
+        }
+      }
+    }
+  }
+
+  return teams;
+}
+
+/**
+ * Get a specific agent definition by name
+ */
+export function getAgentDefinition(name: string, projectDir?: string): AgentDefinition | undefined {
+  const agents = getAllAgentDefinitions(projectDir);
+  return agents.find(a => a.name === name);
+}
+
+/**
+ * Get a specific predefined team by name
+ */
+export function getPredefinedTeam(name: string, projectDir?: string): PredefinedTeam | undefined {
+  const teams = getAllPredefinedTeams(projectDir);
+  return teams.find(t => t.name === name);
+}