@teammates/cli 0.1.0

package/dist/dropdown.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Dropdown — renders lines below the readline prompt.
+ *
+ * Hooks _refreshLine:
+ *   1. origRefresh runs: clears screen, writes prompt, positions cursor
+ *   2. We append dropdown lines with \n
+ *   3. We adjust prevRows so the NEXT _refreshLine's moveCursor(0, -prevRows)
+ *      moves the cursor back up past the dropdown lines to the prompt
+ */
+import type { Interface as ReadlineInterface } from "node:readline";
+export declare class Dropdown {
+    private rl;
+    private lines;
+    private out;
+    private refreshing;
+    constructor(rl: ReadlineInterface);
+    get rendered(): number;
+    /** Set dropdown content. Triggers _refreshLine to display. */
+    render(newLines: string[]): void;
+    /** Clear dropdown. Next _refreshLine won't append anything. */
+    clear(): void;
+    private installHook;
+}

package/dist/dropdown.js

@@ -0,0 +1,80 @@
+/**
+ * Dropdown — renders lines below the readline prompt.
+ *
+ * Hooks _refreshLine:
+ *   1. origRefresh runs: clears screen, writes prompt, positions cursor
+ *   2. We append dropdown lines with \n
+ *   3. We adjust prevRows so the NEXT _refreshLine's moveCursor(0, -prevRows)
+ *      moves the cursor back up past the dropdown lines to the prompt
+ */
+/** Truncate a string with ANSI codes to `max` visible characters. */
+function truncateAnsi(str, max) {
+    let visible = 0;
+    let i = 0;
+    while (i < str.length && visible < max) {
+        if (str[i] === "\x1b") {
+            // Skip ANSI sequence
+            const end = str.indexOf("m", i);
+            if (end !== -1) {
+                i = end + 1;
+                continue;
+            }
+        }
+        visible++;
+        i++;
+    }
+    return str.slice(0, i);
+}
+export class Dropdown {
+    rl;
+    lines = [];
+    out = process.stdout;
+    refreshing = false; // guard against recursion
+    constructor(rl) {
+        this.rl = rl;
+        this.installHook();
+    }
+    get rendered() {
+        return this.lines.length;
+    }
+    /** Set dropdown content. Triggers _refreshLine to display. */
+    render(newLines) {
+        this.lines = newLines;
+        this.rl._refreshLine();
+    }
+    /** Clear dropdown. Next _refreshLine won't append anything. */
+    clear() {
+        this.lines = [];
+    }
+    installHook() {
+        const origRefresh = this.rl._refreshLine.bind(this.rl);
+        this.rl._refreshLine = () => {
+            // Guard: render() calls _refreshLine, which must not recurse
+            if (this.refreshing) {
+                origRefresh();
+                return;
+            }
+            this.refreshing = true;
+            // 1. Run the original: clears below, writes prompt, positions cursor
+            origRefresh();
+            // 2. Append dropdown lines below the prompt (truncated to prevent wrapping)
+            if (this.lines.length > 0) {
+                const cols = this.out.columns || 120;
+                let buf = "";
+                for (const line of this.lines) {
+                    buf += "\n" + truncateAnsi(line, cols - 1);
+                }
+                this.out.write(buf);
+                // 3. Move cursor back up to the prompt line and restore column.
+                //    Don't touch prevRows — cursor IS on the prompt line after this.
+                const n = this.lines.length;
+                this.out.write(`\x1b[${n}A`);
+                const promptText = this.rl._prompt ?? "";
+                const promptLen = promptText.replace(/\x1b\[[0-9;]*m/g, "").length;
+                const cursor = this.rl.cursor ?? 0;
+                this.out.write(`\x1b[${promptLen + cursor + 1}G`);
+            }
+            this.refreshing = false;
+        };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { TeammateConfig, DailyLog, OwnershipRules, SandboxLevel, HandoffEnvelope, TaskResult, TaskAssignment, OrchestratorEvent, } from "./types.js";
+export type { AgentAdapter, RosterEntry, InstalledService } from "./adapter.js";
+export { buildTeammatePrompt, formatHandoffContext } from "./adapter.js";
+export { Registry } from "./registry.js";
+export { Orchestrator, type OrchestratorConfig, type TeammateStatus, } from "./orchestrator.js";
+export { EchoAdapter } from "./adapters/echo.js";
+export { CliProxyAdapter, PRESETS, type AgentPreset, type CliProxyOptions, } from "./adapters/cli-proxy.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+// Public API for @teammates/cli
+export { buildTeammatePrompt, formatHandoffContext } from "./adapter.js";
+export { Registry } from "./registry.js";
+export { Orchestrator, } from "./orchestrator.js";
+export { EchoAdapter } from "./adapters/echo.js";
+export { CliProxyAdapter, PRESETS, } from "./adapters/cli-proxy.js";

package/dist/onboard.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Onboarding flow — guides users through setting up .teammates/ when none exists.
+ *
+ * Ships with a copy of the template/ folder. Framework files (CROSS-TEAM.md,
+ * PROTOCOL.md, TEMPLATE.md, USER.md, .gitignore, example/) are copied into the
+ * target .teammates/ directory before the agent runs, so the agent only needs to
+ * analyze the codebase and create teammate-specific folders.
+ */
+/**
+ * Copy framework files from the bundled template into the target .teammates/ dir.
+ * Skips files that already exist (idempotent).
+ * Returns the list of files that were copied.
+ */
+export declare function copyTemplateFiles(teammatesDir: string): Promise<string[]>;
+/**
+ * Load ONBOARDING.md from the project dir, package root, or built-in fallback.
+ */
+export declare function getOnboardingPrompt(projectDir: string): Promise<string>;

package/dist/onboard.js

@@ -0,0 +1,199 @@
+/**
+ * Onboarding flow — guides users through setting up .teammates/ when none exists.
+ *
+ * Ships with a copy of the template/ folder. Framework files (CROSS-TEAM.md,
+ * PROTOCOL.md, TEMPLATE.md, USER.md, .gitignore, example/) are copied into the
+ * target .teammates/ directory before the agent runs, so the agent only needs to
+ * analyze the codebase and create teammate-specific folders.
+ */
+import { readFile, readdir, copyFile, mkdir, stat } from "node:fs/promises";
+import { resolve, join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * Resolve the bundled template/ directory.
+ * Works from both dist/ (compiled) and src/ (dev).
+ */
+function getTemplateDir() {
+    const candidates = [
+        resolve(__dirname, "../template"), // dist/ → cli/template
+        resolve(__dirname, "../../template"), // src/ → cli/template (dev)
+    ];
+    return candidates[0]; // both resolve to the same cli/template
+}
+/**
+ * Copy framework files from the bundled template into the target .teammates/ dir.
+ * Skips files that already exist (idempotent).
+ * Returns the list of files that were copied.
+ */
+export async function copyTemplateFiles(teammatesDir) {
+    const templateDir = getTemplateDir();
+    const copied = [];
+    // Framework files to copy at the top level
+    const frameworkFiles = [
+        "CROSS-TEAM.md",
+        "PROTOCOL.md",
+        "TEMPLATE.md",
+        "USER.md",
+        "README.md",
+    ];
+    for (const file of frameworkFiles) {
+        const src = join(templateDir, file);
+        const dest = join(teammatesDir, file);
+        try {
+            await stat(dest);
+            // Already exists, skip
+        }
+        catch {
+            try {
+                await copyFile(src, dest);
+                copied.push(file);
+            }
+            catch { /* template file missing, skip */ }
+        }
+    }
+    // Create .gitignore if it doesn't exist
+    const gitignoreDest = join(teammatesDir, ".gitignore");
+    try {
+        await stat(gitignoreDest);
+    }
+    catch {
+        const gitignoreContent = "USER.md\n.index/\n";
+        const { writeFile } = await import("node:fs/promises");
+        await writeFile(gitignoreDest, gitignoreContent, "utf-8");
+        copied.push(".gitignore");
+    }
+    // Copy example/ directory if it doesn't exist
+    const exampleDir = join(teammatesDir, "example");
+    try {
+        await stat(exampleDir);
+    }
+    catch {
+        const templateExampleDir = join(templateDir, "example");
+        try {
+            await mkdir(exampleDir, { recursive: true });
+            const exampleFiles = await readdir(templateExampleDir);
+            for (const file of exampleFiles) {
+                await copyFile(join(templateExampleDir, file), join(exampleDir, file));
+                copied.push(`example/${file}`);
+            }
+        }
+        catch { /* template example dir missing, skip */ }
+    }
+    return copied;
+}
+/**
+ * Load ONBOARDING.md from the project dir, package root, or built-in fallback.
+ */
+export async function getOnboardingPrompt(projectDir) {
+    const candidates = [
+        join(projectDir, "ONBOARDING.md"), // user's project
+        resolve(__dirname, "../../ONBOARDING.md"), // monorepo: cli/dist/ → root
+        resolve(__dirname, "../../../ONBOARDING.md"), // extra nesting fallback
+    ];
+    for (const path of candidates) {
+        try {
+            const content = await readFile(path, "utf-8");
+            if (content.includes("## Step 1")) {
+                return wrapPrompt(content, projectDir);
+            }
+        }
+        catch { /* not found, try next */ }
+    }
+    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 MEMORIES.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 MEMORIES.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 MEMORIES.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.
+
+Follow the onboarding instructions below. Work through each step, pausing after Step 1 and Step 2 to present your analysis and proposed roster to the user for approval before proceeding.
+
+---
+
+${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
+
+**Present your analysis to the user and get confirmation before proceeding.**
+
+## Step 2: Design the Team
+
+Propose 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 proposed teammate, define:
+- Name and one-line persona
+- Primary ownership (file patterns)
+- Key technologies
+- Boundaries (what they do NOT own)
+
+**Present the proposed roster to the user for approval.**
+
+## Step 3: Create the Directory Structure
+
+Once approved, 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.
+
+**MEMORIES.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 MEMORIES.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
+- MEMORIES.md starts light — just one creation entry
+- Prompt the user to fill in USER.md after setup
+`;

package/dist/orchestrator.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Orchestrator — the core of @teammates/cli.
+ *
+ * Routes tasks to teammates, manages handoff chains,
+ * and delegates execution to the plugged-in agent adapter.
+ */
+import type { TaskAssignment, TaskResult, HandoffEnvelope, OrchestratorEvent } from "./types.js";
+import type { AgentAdapter } from "./adapter.js";
+import { Registry } from "./registry.js";
+export interface OrchestratorConfig {
+    /** Path to .teammates/ directory */
+    teammatesDir: string;
+    /** The agent adapter to use for execution */
+    adapter: AgentAdapter;
+    /** Max handoff chain depth before stopping (default: 5) */
+    maxHandoffDepth?: number;
+    /** Event listener for logging/UI */
+    onEvent?: (event: OrchestratorEvent) => void;
+}
+export interface TeammateStatus {
+    state: "idle" | "working" | "pending-handoff";
+    lastSummary?: string;
+    lastChangedFiles?: string[];
+    lastTimestamp?: Date;
+    pendingHandoff?: HandoffEnvelope;
+}
+export declare class Orchestrator {
+    private registry;
+    private adapter;
+    private sessions;
+    private statuses;
+    private maxHandoffDepth;
+    private onEvent;
+    /** When true, handoffs require explicit /approve */
+    requireApproval: boolean;
+    constructor(config: OrchestratorConfig);
+    /** Initialize: load all teammates from disk */
+    init(): Promise<void>;
+    /** Get status for a teammate */
+    getStatus(name: string): TeammateStatus | undefined;
+    /** Get all statuses */
+    getAllStatuses(): Map<string, TeammateStatus>;
+    /** Get the pending handoff if any teammate has one */
+    getPendingHandoff(): HandoffEnvelope | null;
+    /** Clear a pending handoff (on reject) */
+    clearPendingHandoff(teammate: string): void;
+    /** List available teammates */
+    listTeammates(): string[];
+    /** Get the registry for direct access */
+    getRegistry(): Registry;
+    /**
+     * Assign a task to a specific teammate and execute it.
+     * If the result contains a handoff, follows the chain automatically.
+     */
+    assign(assignment: TaskAssignment, depth?: number, visited?: Set<string>): Promise<TaskResult>;
+    /**
+     * Route a task to the best teammate based on keyword matching.
+     * Uses the routing guide from .teammates/README.md ownership patterns.
+     */
+    route(task: string): string | null;
+    /**
+     * Ask the agent to pick the best teammate for a task.
+     * Used as a fallback when keyword routing doesn't find a strong match.
+     */
+    agentRoute(task: string): Promise<string | null>;
+    /** Reset all teammate statuses to idle and clear sessions */
+    reset(): Promise<void>;
+    /** Destroy all sessions */
+    shutdown(): Promise<void>;
+}

package/dist/orchestrator.js

@@ -0,0 +1,240 @@
+/**
+ * Orchestrator — the core of @teammates/cli.
+ *
+ * Routes tasks to teammates, manages handoff chains,
+ * and delegates execution to the plugged-in agent adapter.
+ */
+import { formatHandoffContext } from "./adapter.js";
+import { Registry } from "./registry.js";
+export class Orchestrator {
+    registry;
+    adapter;
+    sessions = new Map(); // teammate -> sessionId
+    statuses = new Map();
+    maxHandoffDepth;
+    onEvent;
+    /** When true, handoffs require explicit /approve */
+    requireApproval = true;
+    constructor(config) {
+        this.registry = new Registry(config.teammatesDir);
+        this.adapter = config.adapter;
+        this.maxHandoffDepth = config.maxHandoffDepth ?? 5;
+        this.onEvent = config.onEvent ?? (() => { });
+    }
+    /** Initialize: load all teammates from disk */
+    async init() {
+        await this.registry.loadAll();
+        for (const name of this.registry.list()) {
+            this.statuses.set(name, { state: "idle" });
+        }
+    }
+    /** Get status for a teammate */
+    getStatus(name) {
+        return this.statuses.get(name);
+    }
+    /** Get all statuses */
+    getAllStatuses() {
+        return this.statuses;
+    }
+    /** Get the pending handoff if any teammate has one */
+    getPendingHandoff() {
+        for (const [, status] of this.statuses) {
+            if (status.state === "pending-handoff" && status.pendingHandoff) {
+                return status.pendingHandoff;
+            }
+        }
+        return null;
+    }
+    /** Clear a pending handoff (on reject) */
+    clearPendingHandoff(teammate) {
+        const status = this.statuses.get(teammate);
+        if (status && status.state === "pending-handoff") {
+            status.state = "idle";
+            status.pendingHandoff = undefined;
+        }
+    }
+    /** List available teammates */
+    listTeammates() {
+        return this.registry.list();
+    }
+    /** Get the registry for direct access */
+    getRegistry() {
+        return this.registry;
+    }
+    /**
+     * Assign a task to a specific teammate and execute it.
+     * If the result contains a handoff, follows the chain automatically.
+     */
+    async assign(assignment, depth = 0, visited) {
+        // Normalize: strip leading @ from teammate names (agents may use @mentions)
+        assignment.teammate = assignment.teammate.replace(/^@/, "");
+        if (assignment.handoff) {
+            assignment.handoff.to = assignment.handoff.to.replace(/^@/, "");
+            assignment.handoff.from = assignment.handoff.from.replace(/^@/, "");
+        }
+        const teammate = this.registry.get(assignment.teammate);
+        if (!teammate) {
+            const error = `Unknown teammate: ${assignment.teammate}`;
+            this.onEvent({ type: "error", teammate: assignment.teammate, error });
+            return {
+                teammate: assignment.teammate,
+                success: false,
+                summary: error,
+                changedFiles: [],
+            };
+        }
+        // ── Handoff cycle detection ──────────────────────────────────
+        const chain = visited ?? new Set();
+        if (chain.has(assignment.teammate)) {
+            const cycle = [...chain, assignment.teammate].join(" → ");
+            const error = `Handoff cycle detected: ${cycle}`;
+            this.onEvent({ type: "error", teammate: assignment.teammate, error });
+            return {
+                teammate: assignment.teammate,
+                success: false,
+                summary: error,
+                changedFiles: [],
+            };
+        }
+        chain.add(assignment.teammate);
+        this.onEvent({ type: "task_assigned", assignment });
+        // Update status
+        this.statuses.set(assignment.teammate, { state: "working" });
+        // Get or create session
+        let sessionId = this.sessions.get(assignment.teammate);
+        if (!sessionId) {
+            sessionId = await this.adapter.startSession(teammate);
+            this.sessions.set(assignment.teammate, sessionId);
+        }
+        // Build prompt with handoff context if present
+        let prompt = assignment.task;
+        if (assignment.handoff) {
+            const handoffCtx = formatHandoffContext(assignment.handoff);
+            prompt = `${handoffCtx}\n\n---\n\n${prompt}`;
+        }
+        if (assignment.extraContext) {
+            prompt = `${assignment.extraContext}\n\n---\n\n${prompt}`;
+        }
+        // Execute
+        const result = await this.adapter.executeTask(sessionId, teammate, prompt);
+        this.onEvent({ type: "task_completed", result });
+        // Update status with result
+        const newStatus = {
+            state: "idle",
+            lastSummary: result.summary,
+            lastChangedFiles: result.changedFiles,
+            lastTimestamp: new Date(),
+        };
+        // Handle handoff
+        if (result.handoff && depth < this.maxHandoffDepth) {
+            this.onEvent({ type: "handoff_initiated", envelope: result.handoff });
+            if (this.requireApproval) {
+                // Park the handoff — user must /approve
+                newStatus.state = "pending-handoff";
+                newStatus.pendingHandoff = result.handoff;
+                this.statuses.set(assignment.teammate, newStatus);
+                return result;
+            }
+            // Auto-follow handoff
+            this.statuses.set(assignment.teammate, newStatus);
+            const nextAssignment = {
+                teammate: result.handoff.to,
+                task: result.handoff.task,
+                handoff: result.handoff,
+            };
+            const handoffResult = await this.assign(nextAssignment, depth + 1, chain);
+            this.onEvent({
+                type: "handoff_completed",
+                envelope: result.handoff,
+                result: handoffResult,
+            });
+            return handoffResult;
+        }
+        this.statuses.set(assignment.teammate, newStatus);
+        return result;
+    }
+    /**
+     * Route a task to the best teammate based on keyword matching.
+     * Uses the routing guide from .teammates/README.md ownership patterns.
+     */
+    route(task) {
+        const taskLower = task.toLowerCase();
+        let bestMatch = null;
+        let bestScore = 0;
+        for (const [name, config] of this.registry.all()) {
+            let score = 0;
+            // Check ownership patterns against task text
+            for (const pattern of [
+                ...config.ownership.primary,
+                ...config.ownership.secondary,
+            ]) {
+                // Extract meaningful keywords from glob patterns
+                const keywords = pattern
+                    .replace(/[*\/{}]/g, " ")
+                    .split(/\s+/)
+                    .filter((w) => w.length > 2);
+                for (const kw of keywords) {
+                    if (taskLower.includes(kw.toLowerCase())) {
+                        score += config.ownership.primary.includes(pattern) ? 2 : 1;
+                    }
+                }
+            }
+            // Check role keywords
+            const roleWords = config.role.toLowerCase().split(/\s+/);
+            for (const word of roleWords) {
+                if (word.length > 3 && taskLower.includes(word)) {
+                    score++;
+                }
+            }
+            if (score > bestScore) {
+                bestScore = score;
+                bestMatch = name;
+            }
+        }
+        // Require a meaningful match — weak/ambiguous scores fall through
+        // so the caller can default to the base coding agent
+        if (bestScore < 2)
+            return null;
+        return bestMatch;
+    }
+    /**
+     * Ask the agent to pick the best teammate for a task.
+     * Used as a fallback when keyword routing doesn't find a strong match.
+     */
+    async agentRoute(task) {
+        if (!this.adapter.routeTask)
+            return null;
+        const roster = [];
+        for (const [name, config] of this.registry.all()) {
+            roster.push({ name, role: config.role, ownership: config.ownership });
+        }
+        // Include the base agent as an option
+        roster.push({
+            name: this.adapter.name,
+            role: "General-purpose coding agent",
+            ownership: { primary: [], secondary: [] },
+        });
+        return this.adapter.routeTask(task, roster);
+    }
+    /** Reset all teammate statuses to idle and clear sessions */
+    async reset() {
+        for (const [name, sessionId] of this.sessions) {
+            if (this.adapter.destroySession) {
+                await this.adapter.destroySession(sessionId);
+            }
+        }
+        this.sessions.clear();
+        for (const name of this.registry.list()) {
+            this.statuses.set(name, { state: "idle" });
+        }
+    }
+    /** Destroy all sessions */
+    async shutdown() {
+        for (const [name, sessionId] of this.sessions) {
+            if (this.adapter.destroySession) {
+                await this.adapter.destroySession(sessionId);
+            }
+        }
+        this.sessions.clear();
+    }
+}

package/dist/orchestrator.test.d.ts

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