@teammates/cli 0.4.1 → 0.5.0

package/README.md

@@ -164,19 +164,51 @@ class MyAdapter implements AgentAdapter {
 
 Or add a preset to `cli-proxy.ts` for any CLI agent that accepts a prompt and runs to completion.
 
+## Startup Lifecycle
+
+The CLI startup runs in two phases:
+
+**Phase 1 — Pre-TUI (console I/O)**
+1. **User profile setup** — Prompts for alias (required), name, role, experience, preferences, context. Creates `USER.md` and a user avatar folder at `.teammates/<alias>/` with `SOUL.md` (`**Type:** human`).
+2. **Team onboarding** (if no `.teammates/` exists) — Offers New team / Import / Solo / Exit. Onboarding agents run non-interactively to completion.
+3. **Orchestrator init** — Loads existing teammates from `.teammates/`, registers user avatar with `type: "human"` and `presence: "online"`.
+
+**Phase 2 — TUI (Consolonia)**
+4. Animated startup banner with roster
+5. REPL starts — routing, slash commands, handoff approval
+
+All user interaction during Phase 1 uses plain console I/O (readline + ora spinners), avoiding mouse tracking issues that would occur inside the TUI.
+
+## Personas
+
+The CLI ships with 15 built-in persona templates that serve as starting points when creating new teammates. Each persona file (`personas/*.md`) contains YAML frontmatter (name, default alias, tier, description) and a complete SOUL.md scaffold pre-filled with the role's identity, principles, quality bar, and ownership structure.
+
+### Tiers
+
+| Tier | Personas |
+|---|---|
+| **1 — Core** | PM (`scribe`), SWE (`beacon`), DevOps (`pipeline`), QA (`sentinel`) |
+| **2 — Specialist** | Security (`shield`), Designer (`canvas`), Tech Writer (`quill`), Data Engineer (`forge`), SRE (`watchtower`), Architect (`blueprint`) |
+| **3 — Niche** | Frontend (`pixel`), Backend (`engine`), Mobile (`orbit`), ML/AI (`neuron`), Performance (`tempo`) |
+
+During onboarding, the CLI uses these personas to scaffold teammates. The user picks roles, optionally renames them, and the persona's SOUL.md body becomes the starting template — project-specific sections (commands, file patterns, technologies) are filled in by the onboarding agent.
+
 ## Architecture
 
 ```
 cli/src/
-  cli.ts            # Entry point, REPL, slash commands, wordwheel UI
-  orchestrator.ts   # Task routing, session management
+  cli.ts            # Entry point, startup lifecycle, REPL, slash commands, wordwheel UI
+  orchestrator.ts   # Task routing, session management, presence tracking
   adapter.ts        # AgentAdapter interface, prompt builder, handoff formatting
-  registry.ts       # Discovers teammates from .teammates/, loads SOUL.md + memory
-  types.ts          # Core types (TeammateConfig, TaskResult, HandoffEnvelope)
+  registry.ts       # Discovers teammates from .teammates/, loads SOUL.md + memory, type detection
+  personas.ts       # Persona loader — reads and parses bundled persona templates
+  types.ts          # Core types (TeammateConfig, TaskResult, HandoffEnvelope, TeammateType, PresenceState)
+  onboard.ts        # Template copying, team import, onboarding/adaptation prompts
   dropdown.ts       # Terminal dropdown/wordwheel widget
   adapters/
     cli-proxy.ts    # Generic subprocess adapter with agent presets
     echo.ts         # Test adapter (no-op)
+cli/personas/       # 15 persona template files (pm.md, swe.md, devops.md, etc.)
 ```
 
 ### Output Protocol

package/dist/adapter.d.ts

@@ -19,7 +19,9 @@ export interface AgentAdapter {
      * Send a task prompt to a teammate's session.
      * The adapter hydrates the prompt with identity, memory, and handoff context.
      */
-    executeTask(sessionId: string, teammate: TeammateConfig, prompt: string): Promise<TaskResult>;
+    executeTask(sessionId: string, teammate: TeammateConfig, prompt: string, options?: {
+        raw?: boolean;
+    }): Promise<TaskResult>;
     /**
      * Resume an existing session (for agents that support continuity).
      * Falls back to startSession if not implemented.
@@ -58,10 +60,16 @@ export interface RecallContext {
 }
 /**
  * Query the recall index for context relevant to the task prompt.
- * Returns search results that should be injected into the teammate prompt.
+ *
+ * Uses a multi-query strategy (Pass 1 from the recall query architecture):
+ * 1. Keyword extraction — generates focused queries from the task prompt
+ * 2. Conversation-aware queries — extracts recent topic from conversation history
+ * 3. Memory index scanning — text-matches frontmatter against the task prompt
+ * 4. Multi-query fusion — fires 2-3 queries and deduplicates by URI
+ *
  * Skips auto-sync (sync happens after tasks, not before — keeps pre-task fast).
  */
-export declare function queryRecallContext(teammatesDir: string, teammateName: string, taskPrompt: string): Promise<RecallContext>;
+export declare function queryRecallContext(teammatesDir: string, teammateName: string, taskPrompt: string, conversationContext?: string): Promise<RecallContext>;
 /**
  * Sync the recall index for a teammate (or all teammates).
  * Wrapper around the recall library's Indexer.

package/dist/adapter.js

@@ -5,21 +5,39 @@
  * Each adapter wraps a specific agent backend (Codex, Claude Code, Cursor, etc.)
  * and translates between the orchestrator's protocol and the agent's native API.
  */
-import { Indexer, search } from "@teammates/recall";
+import { platform } from "node:os";
+import { Indexer, buildQueryVariations, matchMemoryCatalog, multiSearch, } from "@teammates/recall";
 /**
  * Query the recall index for context relevant to the task prompt.
- * Returns search results that should be injected into the teammate prompt.
+ *
+ * Uses a multi-query strategy (Pass 1 from the recall query architecture):
+ * 1. Keyword extraction — generates focused queries from the task prompt
+ * 2. Conversation-aware queries — extracts recent topic from conversation history
+ * 3. Memory index scanning — text-matches frontmatter against the task prompt
+ * 4. Multi-query fusion — fires 2-3 queries and deduplicates by URI
+ *
  * Skips auto-sync (sync happens after tasks, not before — keeps pre-task fast).
  */
-export async function queryRecallContext(teammatesDir, teammateName, taskPrompt) {
+export async function queryRecallContext(teammatesDir, teammateName, taskPrompt, conversationContext) {
     try {
-        const results = await search(taskPrompt, {
+        // Build query variations: original + keywords + conversation topic
+        // If no separate conversation context provided, use the task prompt itself
+        // (which may contain prepended conversation history from the orchestrator)
+        const queries = buildQueryVariations(taskPrompt, conversationContext ?? taskPrompt);
+        const primaryQuery = queries[0];
+        const additionalQueries = queries.slice(1);
+        // Scan memory frontmatter for text-matched results (no embeddings needed)
+        const catalogMatches = await matchMemoryCatalog(teammatesDir, teammateName, taskPrompt);
+        // Fire multi-query search with deduplication
+        const results = await multiSearch(primaryQuery, {
             teammatesDir,
             teammate: teammateName,
             maxResults: 5,
             maxChunks: 3,
             maxTokens: 500,
             skipSync: true,
+            additionalQueries,
+            catalogMatches,
         });
         return { results, ok: true };
     }
@@ -182,28 +200,43 @@ export function buildTeammatePrompt(teammate, taskPrompt, options) {
         lines.push("\n---\n");
         parts.push(lines.join("\n"));
     }
+    // ── Recall tool (Pass 2 — agent-driven search) ─────────────────
+    // Tell the agent it can search memories mid-task via the CLI tool
+    parts.push(`## Recall — Memory Search Tool\n\nYou can search your own memories mid-task for additional context. This is useful when the pre-loaded memories don't cover what you need.\n\n**Usage:** Run this command via your shell/terminal tool:\n\`\`\`\nteammates-recall search "<your query>" --dir .teammates --teammate ${teammate.name} --no-sync --json\n\`\`\`\n\n**Tips:**\n- Use specific, descriptive queries ("hooks lifecycle event naming decision" not "hooks")\n- Search iteratively: query → read result → refine query\n- The \`--json\` flag returns structured results for easier parsing\n- Results include a \`score\` field (0-1) — higher is more relevant\n- You can omit \`--teammate\` to search across all teammates' memories\n\n---\n`);
     // ── Handoff context (required when present) ─────────────────────
     if (options?.handoffContext) {
         parts.push(`## Handoff Context\n\n${options.handoffContext}\n\n---\n`);
     }
+    // ── Output protocol (required — BEFORE session/memory updates) ──
+    // Placed first so agents produce text response before doing housekeeping.
+    // When output protocol is after memory updates, agents often end their turn
+    // with file edits and produce no visible text output.
+    parts.push(`## Output Protocol (CRITICAL)\n\n**Your #1 job is to produce a visible text response.** Session updates and memory writes are secondary — they support continuity but are not the deliverable. The user sees ONLY your text output. If you update files but return no text, the user sees an empty message and your work is invisible.\n\nFormat your response as:\n\n\`\`\`\nTO: user\n# <Subject line>\n\n<Body — full markdown response>\n\`\`\`\n\n**Handoffs:** To hand off work to a teammate, include a fenced handoff block anywhere in your response:\n\n\`\`\`\n\`\`\`handoff\n@<teammate>\n<task description — what you need them to do, with full context>\n\`\`\`\n\`\`\`\n\n**Rules:**\n- **You MUST end your turn with visible text output.** A turn that ends with only tool calls and no text is a failed turn.\n- The \`# Subject\` line is REQUIRED — it becomes the message title.\n- Always write a substantive body. Never return just the subject.\n- Use markdown: headings, lists, code blocks, bold, etc.\n- Do as much work as you can before handing off.\n- Only hand off to teammates listed in "Your Team" above.\n- The handoff block can appear anywhere in your response — it will be detected automatically.\n- **Write your text response FIRST, then update session/memory files.** This ensures visible output even if the agent turn ends early.\n\n---\n`);
     // ── Session state (required) ────────────────────────────────────
     if (options?.sessionFile) {
-        parts.push(`## Session State\n\nYour session file is at: \`${options.sessionFile}\`\n\n**Before returning your result**, append a brief entry to this file with:\n- What you did\n- Key decisions made\n- Files changed\n- Anything the next task should know\n\nThis is how you maintain continuity across tasks. Always read it, always update it.\n\n---\n`);
+        parts.push(`## Session State\n\nYour session file is at: \`${options.sessionFile}\`\n\n**After writing your text response**, append a brief entry to this file with:\n- What you did\n- Key decisions made\n- Files changed\n- Anything the next task should know\n\nThis is how you maintain continuity across tasks. Always read it, always update it.\n\n---\n`);
     }
     // ── Memory updates (required) ───────────────────────────────────
     const today = new Date().toISOString().slice(0, 10);
-    parts.push(`## Memory Updates\n\n**Before returning your result**, update your memory files:\n\n1. **Daily log** — Read \`.teammates/${teammate.name}/memory/${today}.md\` first (it may have entries from earlier tasks today), then write it back with your entry added. Create the file if it doesn't exist.\n   - What you did\n   - Key decisions made\n   - Files changed\n   - Anything the next task should know\n\n2. **Typed memories** — If you learned something durable (a decision, pattern, feedback, or reference), create a typed memory file at \`.teammates/${teammate.name}/memory/<type>_<topic>.md\` with frontmatter (\`name\`, \`description\`, \`type\`). Update existing memory files if the topic already has one.\n\n3. **WISDOM.md** — Do not edit directly. Wisdom entries are distilled from typed memories during compaction.\n\nThese files are your persistent memory. Without them, your next session starts from scratch.\n\n---\n`);
-    // ── Output protocol (required) ──────────────────────────────────
-    parts.push(`## Output Protocol (CRITICAL)\n\n**Your #1 job is to produce a visible text response.** Session updates and memory writes are secondary — they support continuity but are not the deliverable. The user sees ONLY your text output. If you update files but return no text, the user sees an empty message and your work is invisible.\n\nFormat your response as:\n\n\`\`\`\nTO: user\n# <Subject line>\n\n<Body — full markdown response>\n\`\`\`\n\n**Handoffs:** To hand off work to a teammate, include a fenced handoff block anywhere in your response:\n\n\`\`\`\n\`\`\`handoff\n@<teammate>\n<task description — what you need them to do, with full context>\n\`\`\`\n\`\`\`\n\n**Rules:**\n- **You MUST end your turn with visible text output.** A turn that ends with only tool calls and no text is a failed turn.\n- The \`# Subject\` line is REQUIRED — it becomes the message title.\n- Always write a substantive body. Never return just the subject.\n- Use markdown: headings, lists, code blocks, bold, etc.\n- Do as much work as you can before handing off.\n- Only hand off to teammates listed in "Your Team" above.\n- The handoff block can appear anywhere in your response — it will be detected automatically.\n\n---\n`);
-    // ── Current date/time (required, small) ─────────────────────────
+    parts.push(`## Memory Updates\n\n**After writing your text response**, update your memory files:\n\n1. **Daily log** — Read \`.teammates/${teammate.name}/memory/${today}.md\` first (it may have entries from earlier tasks today), then write it back with your entry added. Create the file if it doesn't exist.\n   - What you did\n   - Key decisions made\n   - Files changed\n   - Anything the next task should know\n\n2. **Typed memories** — If you learned something durable (a decision, pattern, feedback, or reference), create a typed memory file at \`.teammates/${teammate.name}/memory/<type>_<topic>.md\` with frontmatter (\`name\`, \`description\`, \`type\`). Update existing memory files if the topic already has one.\n\n3. **WISDOM.md** — Do not edit directly. Wisdom entries are distilled from typed memories during compaction.\n\nThese files are your persistent memory. Without them, your next session starts from scratch.\n\n---\n`);
+    // ── Current date/time + environment (required, small) ───────────
     const now = new Date();
-    parts.push(`**Current date:** ${now.toLocaleDateString("en-US", { weekday: "long", year: "numeric", month: "long", day: "numeric" })} (${today})\n**Current time:** ${now.toLocaleTimeString("en-US", { hour: "2-digit", minute: "2-digit" })}\n\n---\n`);
+    const os = platform();
+    const osLabel = os === "win32" ? "Windows" : os === "darwin" ? "macOS" : "Linux";
+    const slashNote = os === "win32"
+        ? "Use backslashes (`\\`) in file paths."
+        : "Use forward slashes (`/`) in file paths.";
+    // Extract timezone from USER.md if available
+    const tzMatch = options?.userProfile?.match(/\*\*Primary Timezone:\*\*\s*(.+)/);
+    const userTimezone = tzMatch?.[1]?.trim();
+    const tzLine = userTimezone ? `\n**Timezone:** ${userTimezone}` : "";
+    parts.push(`**Current date:** ${now.toLocaleDateString("en-US", { weekday: "long", year: "numeric", month: "long", day: "numeric" })} (${today})\n**Current time:** ${now.toLocaleTimeString("en-US", { hour: "2-digit", minute: "2-digit" })}${tzLine}\n**Environment:** ${osLabel} — ${slashNote}\n\n---\n`);
     // ── User profile (always included when present) ────────────────
     if (options?.userProfile?.trim()) {
         parts.push(`## User Profile\n\n${options.userProfile.trim()}\n\n---\n`);
     }
     // ── Task (always included, excluded from budget) ────────────────
-    parts.push(`## Task\n\n${taskPrompt}\n\n---\n\n**REMINDER: After completing the task and updating session/memory files, you MUST produce a text response starting with \`TO: user\`. An empty response is a bug.**`);
+    parts.push(`## Task\n\n${taskPrompt}\n\n---\n\n**REMINDER: Write your text response (TO: user) FIRST, then update session/memory files. A turn with only file edits and no text output is a failed turn.**`);
     return parts.join("\n");
 }
 /**

package/dist/adapters/cli-proxy.d.ts

@@ -88,7 +88,9 @@ export declare class CliProxyAdapter implements AgentAdapter {
     private pendingTempFiles;
     constructor(options: CliProxyOptions);
     startSession(teammate: TeammateConfig): Promise<string>;
-    executeTask(_sessionId: string, teammate: TeammateConfig, prompt: string): Promise<TaskResult>;
+    executeTask(_sessionId: string, teammate: TeammateConfig, prompt: string, options?: {
+        raw?: boolean;
+    }): Promise<TaskResult>;
     routeTask(task: string, roster: RosterEntry[]): Promise<string | null>;
     getSessionFile(teammateName: string): string | undefined;
     destroySession(_sessionId: string): Promise<void>;

package/dist/adapters/cli-proxy.js

@@ -136,12 +136,15 @@ export class CliProxyAdapter {
         this.sessionFiles.set(teammate.name, sessionFile);
         return id;
     }
-    async executeTask(_sessionId, teammate, prompt) {
-        // If the teammate has no soul (e.g. the raw agent), skip identity/memory
-        // wrapping but include handoff instructions so it can delegate to teammates
+    async executeTask(_sessionId, teammate, prompt, options) {
+        // If raw mode is set, skip all prompt wrapping — send prompt as-is
+        // Used for defensive retries where the full prompt template is counterproductive
         const sessionFile = this.sessionFiles.get(teammate.name);
         let fullPrompt;
-        if (teammate.soul) {
+        if (options?.raw) {
+            fullPrompt = prompt;
+        }
+        else if (teammate.soul) {
             // Query recall for relevant memories before building prompt
             const teammatesDir = teammate.cwd
                 ? join(teammate.cwd, ".teammates")

package/dist/adapters/copilot.d.ts

@@ -40,7 +40,9 @@ export declare class CopilotAdapter implements AgentAdapter {
     private sessionsDir;
     constructor(options?: CopilotAdapterOptions);
     startSession(teammate: TeammateConfig): Promise<string>;
-    executeTask(_sessionId: string, teammate: TeammateConfig, prompt: string): Promise<TaskResult>;
+    executeTask(_sessionId: string, teammate: TeammateConfig, prompt: string, options?: {
+        raw?: boolean;
+    }): Promise<TaskResult>;
     routeTask(task: string, roster: RosterEntry[]): Promise<string | null>;
     getSessionFile(teammateName: string): string | undefined;
     destroySession(_sessionId: string): Promise<void>;

package/dist/adapters/copilot.js

@@ -56,12 +56,15 @@ export class CopilotAdapter {
         this.sessionFiles.set(teammate.name, sessionFile);
         return id;
     }
-    async executeTask(_sessionId, teammate, prompt) {
+    async executeTask(_sessionId, teammate, prompt, options) {
         await this.ensureClient(teammate.cwd);
         const sessionFile = this.sessionFiles.get(teammate.name);
         // Build the full teammate prompt (identity + memory + task)
         let fullPrompt;
-        if (teammate.soul) {
+        if (options?.raw) {
+            fullPrompt = prompt;
+        }
+        else if (teammate.soul) {
             // Query recall for relevant memories before building prompt
             const teammatesDir = teammate.cwd
                 ? join(teammate.cwd, ".teammates")

package/dist/adapters/echo.d.ts

@@ -9,5 +9,7 @@ import type { TaskResult, TeammateConfig } from "../types.js";
 export declare class EchoAdapter implements AgentAdapter {
     readonly name = "echo";
     startSession(teammate: TeammateConfig): Promise<string>;
-    executeTask(_sessionId: string, teammate: TeammateConfig, prompt: string): Promise<TaskResult>;
+    executeTask(_sessionId: string, teammate: TeammateConfig, prompt: string, options?: {
+        raw?: boolean;
+    }): Promise<TaskResult>;
 }

package/dist/adapters/echo.js

@@ -11,8 +11,8 @@ export class EchoAdapter {
     async startSession(teammate) {
         return `echo-${teammate.name}-${nextId++}`;
     }
-    async executeTask(_sessionId, teammate, prompt) {
-        const fullPrompt = buildTeammatePrompt(teammate, prompt);
+    async executeTask(_sessionId, teammate, prompt, options) {
+        const fullPrompt = options?.raw ? prompt : buildTeammatePrompt(teammate, prompt);
         return {
             teammate: teammate.name,
             success: true,