@teammates/cli 0.4.1 → 0.5.1

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export type { AgentAdapter, InstalledService, RecallContext, RosterEntry, } from "./adapter.js";
-export { buildTeammatePrompt, formatHandoffContext, queryRecallContext, syncRecallIndex, } from "./adapter.js";
+export { buildTeammatePrompt, DAILY_LOG_BUDGET_TOKENS, formatHandoffContext, queryRecallContext, syncRecallIndex, } from "./adapter.js";
+export { autoCompactForBudget } from "./compact.js";
 export { type AgentPreset, CliProxyAdapter, type CliProxyOptions, PRESETS, } from "./adapters/cli-proxy.js";
 export { EchoAdapter } from "./adapters/echo.js";
 export type { BannerInfo, ServiceInfo, ServiceStatus } from "./banner.js";
@@ -7,6 +8,8 @@ export { AnimatedBanner } from "./banner.js";
 export type { CliArgs } from "./cli-args.js";
 export { findTeammatesDir, PKG_VERSION, parseCliArgs } from "./cli-args.js";
 export { Orchestrator, type OrchestratorConfig, type TeammateStatus, } from "./orchestrator.js";
+export type { Persona } from "./personas.js";
+export { loadPersonas, scaffoldFromPersona } from "./personas.js";
 export { Registry } from "./registry.js";
 export { tp } from "./theme.js";
 export type { DailyLog, HandoffEnvelope, OrchestratorEvent, OwnershipRules, PresenceState, QueueEntry, SandboxLevel, SlashCommand, TaskAssignment, TaskResult, TeammateConfig, TeammateType, } from "./types.js";

package/dist/index.js

@@ -1,9 +1,11 @@
 // Public API for @teammates/cli
-export { buildTeammatePrompt, formatHandoffContext, queryRecallContext, syncRecallIndex, } from "./adapter.js";
+export { buildTeammatePrompt, DAILY_LOG_BUDGET_TOKENS, formatHandoffContext, queryRecallContext, syncRecallIndex, } from "./adapter.js";
+export { autoCompactForBudget } from "./compact.js";
 export { CliProxyAdapter, PRESETS, } from "./adapters/cli-proxy.js";
 export { EchoAdapter } from "./adapters/echo.js";
 export { AnimatedBanner } from "./banner.js";
 export { findTeammatesDir, PKG_VERSION, parseCliArgs } from "./cli-args.js";
 export { Orchestrator, } from "./orchestrator.js";
+export { loadPersonas, scaffoldFromPersona } from "./personas.js";
 export { Registry } from "./registry.js";
 export { tp } from "./theme.js";

package/dist/onboard.js

@@ -225,82 +225,82 @@ export async function buildImportAdaptationPrompt(teammatesDir, teammateNames, s
         teammateSections.push(`### @${name}\n${soulBlock}${wisdomBlock}`);
     }
     const projectDir = dirname(teammatesDir);
-    return `You are adapting an imported team to a new project. This is a non-interactive session — complete ALL work without pausing. Do not ask for confirmation or wait for user input.
-
-**Source project:** \`${sourceProjectPath}\`
-**Target project:** \`${projectDir}\`
-**Target .teammates/ directory:** \`${teammatesDir}\`
-**Imported teammates:** ${teammateNames.map((n) => `@${n}`).join(", ")}
-
-> **IMPORTANT:** The \`example/\` directory inside \`.teammates/\` is a **template reference**, NOT a teammate. Do not adapt it, rename it, or treat it as a teammate. When creating new teammates, never use "example" as a folder name.
-
-## Imported Teammates (from source project)
-
-${teammateSections.join("\n\n---\n\n")}
-
-## Instructions
-
-Complete these steps in order. Do NOT pause, ask questions, or wait for approval. Make all changes directly.
-
-### Step 1: Scan This Project
-
-Read the project root to understand its structure:
-- Package manifest, README, config files
-- Major subsystems, languages, frameworks, file patterns
-- Dependency flow and architecture
-
-### Step 2: Adapt EVERY Imported Teammate
-
-This is the most important step. For EACH imported teammate listed above, you MUST edit their SOUL.md and WISDOM.md to reflect THIS project, not the source project.
-
-For each teammate's **SOUL.md**:
-
-1. **Add a "Previous Projects" section** (place it after Ethics). Compress what the teammate did in the source project:
-   \`\`\`markdown
-   ## Previous Projects
-
-   ### <source-project-name>
-   - **Role**: <one-line summary of what they did>
-   - **Stack**: <key technologies they worked with>
-   - **Domains**: <what they owned — file patterns or subsystem names>
-   - **Key learnings**: <1-3 bullets of notable patterns, decisions, or lessons>
-   \`\`\`
-
-2. **Rewrite project-specific sections** for THIS project:
-   - **Preserve**: Identity (name, personality), Core Principles, Ethics
-   - **Rewrite completely**: Ownership (primary/secondary file globs for THIS project's actual files), Boundaries, Capabilities (commands, file patterns, technologies for THIS project), Routing keywords, Quality Bar
-   - **Update**: All codebase-specific references — paths, package names, tools, teammate names must reference THIS project
-
-For each teammate's **WISDOM.md**:
-- Add a "Previous Projects" note at the top
-- Keep universal wisdom entries (general principles, patterns)
-- Remove entries that reference source project paths, architecture, or tools not used here
-- Adapt entries with transferable knowledge but old-project-specific details
-
-### Step 3: Evaluate Gaps and Create New Teammates
-
-After adapting all existing teammates, check if THIS project has major subsystems that no teammate covers. If so, create new teammates:
-- Create \`${teammatesDir}/<name>/\` with SOUL.md, WISDOM.md, and \`memory/\`
-- Use the template at \`${teammatesDir}/TEMPLATE.md\` for structure
-- WISDOM.md starts with one creation entry
-
-If a teammate's domain doesn't exist at all in this project and their skills aren't transferable, delete their directory under \`${teammatesDir}\`.
-
-### Step 4: Update Framework Files
-
-- Update \`${teammatesDir}/README.md\` with the final roster
-- Update \`${teammatesDir}/CROSS-TEAM.md\` ownership table
-
-### Step 5: Verify
-
-- Every teammate has SOUL.md and WISDOM.md adapted to THIS project
-- Ownership globs reference actual files in THIS project
-- Boundaries reference correct teammate names
-- Previous Projects sections are present for all imported teammates
-- CROSS-TEAM.md has one row per teammate
-
-## Critical Reminder
-
+    return `You are adapting an imported team to a new project. This is a non-interactive session — complete ALL work without pausing. Do not ask for confirmation or wait for user input.
+
+**Source project:** \`${sourceProjectPath}\`
+**Target project:** \`${projectDir}\`
+**Target .teammates/ directory:** \`${teammatesDir}\`
+**Imported teammates:** ${teammateNames.map((n) => `@${n}`).join(", ")}
+
+> **IMPORTANT:** The \`example/\` directory inside \`.teammates/\` is a **template reference**, NOT a teammate. Do not adapt it, rename it, or treat it as a teammate. When creating new teammates, never use "example" as a folder name.
+
+## Imported Teammates (from source project)
+
+${teammateSections.join("\n\n---\n\n")}
+
+## Instructions
+
+Complete these steps in order. Do NOT pause, ask questions, or wait for approval. Make all changes directly.
+
+### Step 1: Scan This Project
+
+Read the project root to understand its structure:
+- Package manifest, README, config files
+- Major subsystems, languages, frameworks, file patterns
+- Dependency flow and architecture
+
+### Step 2: Adapt EVERY Imported Teammate
+
+This is the most important step. For EACH imported teammate listed above, you MUST edit their SOUL.md and WISDOM.md to reflect THIS project, not the source project.
+
+For each teammate's **SOUL.md**:
+
+1. **Add a "Previous Projects" section** (place it after Ethics). Compress what the teammate did in the source project:
+   \`\`\`markdown
+   ## Previous Projects
+
+   ### <source-project-name>
+   - **Role**: <one-line summary of what they did>
+   - **Stack**: <key technologies they worked with>
+   - **Domains**: <what they owned — file patterns or subsystem names>
+   - **Key learnings**: <1-3 bullets of notable patterns, decisions, or lessons>
+   \`\`\`
+
+2. **Rewrite project-specific sections** for THIS project:
+   - **Preserve**: Identity (name, personality), Core Principles, Ethics
+   - **Rewrite completely**: Ownership (primary/secondary file globs for THIS project's actual files), Boundaries, Capabilities (commands, file patterns, technologies for THIS project), Routing keywords, Quality Bar
+   - **Update**: All codebase-specific references — paths, package names, tools, teammate names must reference THIS project
+
+For each teammate's **WISDOM.md**:
+- Add a "Previous Projects" note at the top
+- Keep universal wisdom entries (general principles, patterns)
+- Remove entries that reference source project paths, architecture, or tools not used here
+- Adapt entries with transferable knowledge but old-project-specific details
+
+### Step 3: Evaluate Gaps and Create New Teammates
+
+After adapting all existing teammates, check if THIS project has major subsystems that no teammate covers. If so, create new teammates:
+- Create \`${teammatesDir}/<name>/\` with SOUL.md, WISDOM.md, and \`memory/\`
+- Use the template at \`${teammatesDir}/TEMPLATE.md\` for structure
+- WISDOM.md starts with one creation entry
+
+If a teammate's domain doesn't exist at all in this project and their skills aren't transferable, delete their directory under \`${teammatesDir}\`.
+
+### Step 4: Update Framework Files
+
+- Update \`${teammatesDir}/README.md\` with the final roster
+- Update \`${teammatesDir}/CROSS-TEAM.md\` ownership table
+
+### Step 5: Verify
+
+- Every teammate has SOUL.md and WISDOM.md adapted to THIS project
+- Ownership globs reference actual files in THIS project
+- Boundaries reference correct teammate names
+- Previous Projects sections are present for all imported teammates
+- CROSS-TEAM.md has one row per teammate
+
+## Critical Reminder
+
 The PRIMARY goal is adapting the imported teammates. Every SOUL.md must be rewritten so the teammate understands THIS project's codebase, not the source project's. If you only have time for one thing, adapt the existing teammates — that is more important than creating new ones.`;
 }
 /**
@@ -326,95 +326,95 @@ export async function getOnboardingPrompt(projectDir) {
     return wrapPrompt(BUILTIN_ONBOARDING, projectDir);
 }
 function wrapPrompt(onboardingContent, projectDir) {
-    return `You are setting up the teammates framework for a project.
-
-**Target project directory:** ${projectDir}
-
-**Framework files have already been copied** into \`${projectDir}/.teammates/\` from the template. The following files are already in place:
-- CROSS-TEAM.md — fill in the Ownership Scopes table as you create teammates
-- PROTOCOL.md — team protocol (ready to use)
-- TEMPLATE.md — reference for creating teammate SOUL.md and WISDOM.md files
-- USER.md — user profile (gitignored, user fills in later)
-- README.md — update with project-specific roster and info
-- .gitignore — configured for USER.md and .index/
-- example/ — example SOUL.md and WISDOM.md for reference
-
-**Your job is to:**
-1. Analyze the codebase (Step 1)
-2. Design the team roster (Step 2)
-3. Create teammate folders with SOUL.md and WISDOM.md (Step 3) — use TEMPLATE.md for the structure
-4. Update README.md and CROSS-TEAM.md with the roster info (Step 3)
-5. Verify everything is in place (Step 4)
-
-You do NOT need to create the framework files listed above — they're already there.
-
-> **IMPORTANT:** The \`example/\` directory is a **template reference**, NOT a teammate. Do not modify it or treat it as a teammate. Never name a new teammate "example".
-
-Follow the onboarding instructions below. This is a non-interactive session — complete ALL work without pausing. Do not ask for confirmation or wait for user input. Work through each step and make all changes directly.
-
----
-
+    return `You are setting up the teammates framework for a project.
+
+**Target project directory:** ${projectDir}
+
+**Framework files have already been copied** into \`${projectDir}/.teammates/\` from the template. The following files are already in place:
+- CROSS-TEAM.md — fill in the Ownership Scopes table as you create teammates
+- PROTOCOL.md — team protocol (ready to use)
+- TEMPLATE.md — reference for creating teammate SOUL.md and WISDOM.md files
+- USER.md — user profile (gitignored, user fills in later)
+- README.md — update with project-specific roster and info
+- .gitignore — configured for USER.md and .index/
+- example/ — example SOUL.md and WISDOM.md for reference
+
+**Your job is to:**
+1. Analyze the codebase (Step 1)
+2. Design the team roster (Step 2)
+3. Create teammate folders with SOUL.md and WISDOM.md (Step 3) — use TEMPLATE.md for the structure
+4. Update README.md and CROSS-TEAM.md with the roster info (Step 3)
+5. Verify everything is in place (Step 4)
+
+You do NOT need to create the framework files listed above — they're already there.
+
+> **IMPORTANT:** The \`example/\` directory is a **template reference**, NOT a teammate. Do not modify it or treat it as a teammate. Never name a new teammate "example".
+
+Follow the onboarding instructions below. This is a non-interactive session — complete ALL work without pausing. Do not ask for confirmation or wait for user input. Work through each step and make all changes directly.
+
+---
+
 ${onboardingContent}`;
 }
-const BUILTIN_ONBOARDING = `# Teammates Onboarding
-
-You are going to analyze a codebase and create a set of AI teammates — persistent personas that each own a slice of the project. Follow these steps in order.
-
-## Step 1: Analyze the Codebase
-
-Read the project's entry points to understand its structure:
-- README, CONTRIBUTING, or similar docs
-- Package manifest (package.json, Cargo.toml, pyproject.toml, go.mod, etc.)
-- Top-level directory structure
-- Key configuration files
-
-Identify:
-1. **Major domains/subsystems** — distinct areas of the codebase
-2. **Dependency flow** — which layers depend on which
-3. **Key technologies** — languages, frameworks, tools per area
-4. **File patterns** — glob patterns for each domain
-
-## Step 2: Design the Team
-
-Based on your analysis, design a roster of teammates:
-- **Aim for 3–7 teammates.** Fewer for small projects, more for monorepos.
-- **Each teammate owns a distinct domain** with minimal overlap.
-- **Pick short, memorable names** — one word, evocative of the domain.
-
-For each teammate, define:
-- Name and one-line persona
-- Primary ownership (file patterns)
-- Key technologies
-- Boundaries (what they do NOT own)
-
-## Step 3: Create the Directory Structure
-
-Create teammate folders under \`.teammates/\`:
-
-### Teammate folders
-For each teammate, create \`.teammates/<name>/\` with:
-
-**SOUL.md** — Use the template from \`.teammates/TEMPLATE.md\`. Fill in identity, core principles, boundaries, capabilities, ownership, ethics.
-
-**WISDOM.md** — Start with one entry recording creation and key decisions.
-
-**memory/** — Empty directory for daily logs.
-
-### Update framework files
-- Update \`.teammates/README.md\` with the roster table, dependency flow, and routing guide
-- Update \`.teammates/CROSS-TEAM.md\` Ownership Scopes table with one row per teammate
-
-## Step 4: Verify
-
-Check:
-- Every roster teammate has a folder with SOUL.md and WISDOM.md
-- Ownership globs cover the codebase without major gaps
-- Boundaries reference the correct owning teammate
-- CROSS-TEAM.md Ownership Scopes table has one row per teammate with correct paths
-- .gitignore is in place (USER.md not committed)
-
-## Tips
-- Small projects are fine with 2–3 teammates
-- WISDOM.md starts light — just one creation entry
-- Prompt the user to fill in USER.md after setup
+const BUILTIN_ONBOARDING = `# Teammates Onboarding
+
+You are going to analyze a codebase and create a set of AI teammates — persistent personas that each own a slice of the project. Follow these steps in order.
+
+## Step 1: Analyze the Codebase
+
+Read the project's entry points to understand its structure:
+- README, CONTRIBUTING, or similar docs
+- Package manifest (package.json, Cargo.toml, pyproject.toml, go.mod, etc.)
+- Top-level directory structure
+- Key configuration files
+
+Identify:
+1. **Major domains/subsystems** — distinct areas of the codebase
+2. **Dependency flow** — which layers depend on which
+3. **Key technologies** — languages, frameworks, tools per area
+4. **File patterns** — glob patterns for each domain
+
+## Step 2: Design the Team
+
+Based on your analysis, design a roster of teammates:
+- **Aim for 3–7 teammates.** Fewer for small projects, more for monorepos.
+- **Each teammate owns a distinct domain** with minimal overlap.
+- **Pick short, memorable names** — one word, evocative of the domain.
+
+For each teammate, define:
+- Name and one-line persona
+- Primary ownership (file patterns)
+- Key technologies
+- Boundaries (what they do NOT own)
+
+## Step 3: Create the Directory Structure
+
+Create teammate folders under \`.teammates/\`:
+
+### Teammate folders
+For each teammate, create \`.teammates/<name>/\` with:
+
+**SOUL.md** — Use the template from \`.teammates/TEMPLATE.md\`. Fill in identity, core principles, boundaries, capabilities, ownership, ethics.
+
+**WISDOM.md** — Start with one entry recording creation and key decisions.
+
+**memory/** — Empty directory for daily logs.
+
+### Update framework files
+- Update \`.teammates/README.md\` with the roster table, dependency flow, and routing guide
+- Update \`.teammates/CROSS-TEAM.md\` Ownership Scopes table with one row per teammate
+
+## Step 4: Verify
+
+Check:
+- Every roster teammate has a folder with SOUL.md and WISDOM.md
+- Ownership globs cover the codebase without major gaps
+- Boundaries reference the correct owning teammate
+- CROSS-TEAM.md Ownership Scopes table has one row per teammate with correct paths
+- .gitignore is in place (USER.md not committed)
+
+## Tips
+- Small projects are fine with 2–3 teammates
+- WISDOM.md starts light — just one creation entry
+- Prompt the user to fill in USER.md after setup
 `;

package/dist/orchestrator.js

@@ -63,7 +63,10 @@ export class Orchestrator {
         }
         this.onEvent({ type: "task_assigned", assignment });
         const prevPresence = this.statuses.get(assignment.teammate)?.presence ?? "online";
-        this.statuses.set(assignment.teammate, { state: "working", presence: prevPresence });
+        this.statuses.set(assignment.teammate, {
+            state: "working",
+            presence: prevPresence,
+        });
         // Get or create session
         let sessionId = this.sessions.get(assignment.teammate);
         if (!sessionId) {
@@ -76,7 +79,9 @@ export class Orchestrator {
             prompt = `${assignment.extraContext}\n\n---\n\n${prompt}`;
         }
         // Execute
-        const result = await this.adapter.executeTask(sessionId, teammate, prompt);
+        const result = await this.adapter.executeTask(sessionId, teammate, prompt, {
+            raw: assignment.raw,
+        });
         this.onEvent({ type: "task_completed", result });
         // Update status (preserve presence)
         const postPresence = this.statuses.get(assignment.teammate)?.presence ?? "online";

package/dist/personas.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Persona loader — reads bundled persona templates from the personas/ directory.
+ *
+ * Each persona file is a markdown file with YAML frontmatter:
+ *   ---
+ *   persona: Software Engineer
+ *   alias: beacon
+ *   tier: 1
+ *   description: Architecture, implementation, and code quality
+ *   ---
+ *   # <Name> — Software Engineer
+ *   ...body (SOUL.md scaffold)...
+ *
+ * The `<Name>` placeholder in the body is replaced with the user's chosen
+ * teammate name during scaffolding.
+ */
+export interface Persona {
+    /** Display name, e.g. "Software Engineer" */
+    persona: string;
+    /** Suggested alias, e.g. "beacon" */
+    alias: string;
+    /** Tier for ordering: 1 = core, 2 = specialized */
+    tier: number;
+    /** One-line description shown in selection UI */
+    description: string;
+    /** Raw SOUL.md body (everything after the closing ---) */
+    body: string;
+}
+/**
+ * Load all personas from the bundled personas/ directory.
+ * Returns sorted by tier (ascending), then alphabetically.
+ */
+export declare function loadPersonas(): Promise<Persona[]>;
+/**
+ * Scaffold a teammate folder from a persona template.
+ *
+ * @param teammatesDir - The .teammates/ directory
+ * @param name - The teammate name (used as folder name and replaces <Name>)
+ * @param persona - The persona to scaffold from
+ * @returns The path to the created teammate folder
+ */
+export declare function scaffoldFromPersona(teammatesDir: string, name: string, persona: Persona): Promise<string>;

package/dist/personas.js

@@ -0,0 +1,108 @@
+/**
+ * Persona loader — reads bundled persona templates from the personas/ directory.
+ *
+ * Each persona file is a markdown file with YAML frontmatter:
+ *   ---
+ *   persona: Software Engineer
+ *   alias: beacon
+ *   tier: 1
+ *   description: Architecture, implementation, and code quality
+ *   ---
+ *   # <Name> — Software Engineer
+ *   ...body (SOUL.md scaffold)...
+ *
+ * The `<Name>` placeholder in the body is replaced with the user's chosen
+ * teammate name during scaffolding.
+ */
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * Resolve the bundled personas/ directory.
+ * Works from both dist/ (compiled) and src/ (dev).
+ */
+function getPersonasDir() {
+    const candidates = [
+        resolve(__dirname, "../personas"), // dist/ → cli/personas
+        resolve(__dirname, "../../personas"), // src/ → cli/personas (dev)
+    ];
+    return candidates[0]; // both resolve to cli/personas
+}
+/**
+ * Parse a persona file's frontmatter and body.
+ */
+function parsePersonaFile(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+    if (!match)
+        return null;
+    const frontmatter = match[1];
+    const body = match[2].trim();
+    const persona = extractField(frontmatter, "persona");
+    const alias = extractField(frontmatter, "alias");
+    const tierStr = extractField(frontmatter, "tier");
+    const description = extractField(frontmatter, "description");
+    if (!persona || !alias || !description)
+        return null;
+    return {
+        persona,
+        alias,
+        tier: tierStr ? parseInt(tierStr, 10) : 2,
+        description,
+        body,
+    };
+}
+function extractField(frontmatter, field) {
+    const re = new RegExp(`^${field}:\\s*(.+)$`, "m");
+    const m = frontmatter.match(re);
+    return m?.[1]?.trim();
+}
+/**
+ * Load all personas from the bundled personas/ directory.
+ * Returns sorted by tier (ascending), then alphabetically.
+ */
+export async function loadPersonas() {
+    const dir = getPersonasDir();
+    const personas = [];
+    try {
+        const files = await readdir(dir);
+        for (const file of files) {
+            if (!file.endsWith(".md"))
+                continue;
+            try {
+                const content = await readFile(join(dir, file), "utf-8");
+                const persona = parsePersonaFile(content);
+                if (persona)
+                    personas.push(persona);
+            }
+            catch {
+                /* skip unreadable files */
+            }
+        }
+    }
+    catch {
+        /* personas dir missing — return empty */
+    }
+    personas.sort((a, b) => a.tier - b.tier || a.persona.localeCompare(b.persona));
+    return personas;
+}
+/**
+ * Scaffold a teammate folder from a persona template.
+ *
+ * @param teammatesDir - The .teammates/ directory
+ * @param name - The teammate name (used as folder name and replaces <Name>)
+ * @param persona - The persona to scaffold from
+ * @returns The path to the created teammate folder
+ */
+export async function scaffoldFromPersona(teammatesDir, name, persona) {
+    const folderName = name.toLowerCase().replace(/[^a-z0-9_-]/g, "");
+    const teamDir = join(teammatesDir, folderName);
+    await mkdir(teamDir, { recursive: true });
+    await mkdir(join(teamDir, "memory"), { recursive: true });
+    // Replace <Name> placeholder with the chosen name (capitalize first letter)
+    const displayName = name.charAt(0).toUpperCase() + name.slice(1);
+    const soulContent = persona.body.replace(/<Name>/g, displayName);
+    await writeFile(join(teamDir, "SOUL.md"), soulContent, "utf-8");
+    await writeFile(join(teamDir, "WISDOM.md"), `# ${displayName} — Wisdom\n\nDistilled principles. Read this first every session (after SOUL.md).\n\nLast compacted: never\n\n---\n\n*No entries yet — wisdom is distilled from experience.*\n`, "utf-8");
+    return teamDir;
+}

package/dist/personas.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/personas.test.js

@@ -0,0 +1,88 @@
+import { mkdir, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { loadPersonas, scaffoldFromPersona } from "./personas.js";
+// ── scaffoldFromPersona ─────────────────────────────────────────────
+let testDir;
+beforeEach(async () => {
+    testDir = join(tmpdir(), `personas-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(testDir, { recursive: true });
+});
+afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+});
+const samplePersona = {
+    persona: "Software Engineer",
+    alias: "beacon",
+    tier: 1,
+    description: "Architecture and implementation",
+    body: "# <Name> — Software Engineer\n\n## Identity\n<Name> is the team's SWE.",
+};
+describe("scaffoldFromPersona", () => {
+    it("creates teammate folder with SOUL.md and WISDOM.md", async () => {
+        const teamDir = await scaffoldFromPersona(testDir, "beacon", samplePersona);
+        const soul = await readFile(join(teamDir, "SOUL.md"), "utf-8");
+        const wisdom = await readFile(join(teamDir, "WISDOM.md"), "utf-8");
+        expect(soul).toContain("# Beacon — Software Engineer");
+        expect(soul).toContain("Beacon is the team's SWE.");
+        expect(wisdom).toContain("# Beacon — Wisdom");
+        expect(wisdom).toContain("Last compacted: never");
+    });
+    it("normalizes folder name to lowercase with safe chars", async () => {
+        const teamDir = await scaffoldFromPersona(testDir, "My Cool Bot!", samplePersona);
+        // Should strip spaces, uppercase, and special chars
+        expect(teamDir).toContain("mycoolbot");
+    });
+    it("replaces all <Name> placeholders in SOUL.md", async () => {
+        const teamDir = await scaffoldFromPersona(testDir, "atlas", samplePersona);
+        const soul = await readFile(join(teamDir, "SOUL.md"), "utf-8");
+        expect(soul).not.toContain("<Name>");
+        expect(soul).toContain("Atlas");
+    });
+    it("creates memory subdirectory", async () => {
+        const teamDir = await scaffoldFromPersona(testDir, "test", samplePersona);
+        // Should not throw — directory exists
+        const memDir = join(teamDir, "memory");
+        await mkdir(memDir, { recursive: true }); // no-op if exists
+    });
+    it("capitalizes display name in WISDOM.md", async () => {
+        const teamDir = await scaffoldFromPersona(testDir, "forge", samplePersona);
+        const wisdom = await readFile(join(teamDir, "WISDOM.md"), "utf-8");
+        expect(wisdom).toContain("# Forge — Wisdom");
+    });
+});
+// ── loadPersonas ────────────────────────────────────────────────────
+describe("loadPersonas", () => {
+    it("loads persona files from the bundled directory", async () => {
+        const personas = await loadPersonas();
+        // Should find at least the built-in personas
+        expect(personas.length).toBeGreaterThan(0);
+    });
+    it("sorts by tier then alphabetically", async () => {
+        const personas = await loadPersonas();
+        // Verify ordering: all tier 1 before tier 2
+        let lastTier = 0;
+        let lastName = "";
+        for (const p of personas) {
+            if (p.tier > lastTier) {
+                lastTier = p.tier;
+                lastName = "";
+            }
+            if (p.tier === lastTier && lastName) {
+                expect(p.persona.localeCompare(lastName)).toBeGreaterThanOrEqual(0);
+            }
+            lastName = p.persona;
+        }
+    });
+    it("each persona has required fields", async () => {
+        const personas = await loadPersonas();
+        for (const p of personas) {
+            expect(p.persona).toBeTruthy();
+            expect(p.alias).toBeTruthy();
+            expect(p.description).toBeTruthy();
+            expect(typeof p.tier).toBe("number");
+            expect(p.body.length).toBeGreaterThan(0);
+        }
+    });
+});