@teammates/cli 0.4.1 → 0.5.1

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,15 +60,29 @@ 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.
  */
 export declare function syncRecallIndex(teammatesDir: string, teammate?: string): Promise<void>;
+/**
+ * Context budget allocation:
+ * - Days 2-7 get up to DAILY_LOG_BUDGET tokens (whole entries)
+ * - Recall gets at least RECALL_MIN_BUDGET, plus whatever daily logs didn't use
+ * - Last recall entry can push total up to budget + RECALL_OVERFLOW (4k grace)
+ * - Weekly summaries are excluded (already indexed by recall)
+ */
+export declare const DAILY_LOG_BUDGET_TOKENS = 24000;
 /**
  * Build the full prompt for a teammate session.
  * Includes identity, memory, roster, output protocol, and the task.

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 { buildQueryVariations, Indexer, 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 };
     }
@@ -40,23 +58,16 @@ export async function syncRecallIndex(teammatesDir, teammate) {
         await indexer.syncAll();
     }
 }
-/**
- * Default token budget for the prompt wrapper (everything except the task).
- * ~64k tokens ≈ 256k chars at ~4 chars/token.
- * The task prompt itself is excluded from this budget — if a user pastes
- * a large input, that's intentional and we don't trim it.
- */
-const DEFAULT_TOKEN_BUDGET = 64_000;
+/** Approximate chars per token for budget estimation. */
 const CHARS_PER_TOKEN = 4;
 /**
  * Context budget allocation:
  * - Days 2-7 get up to DAILY_LOG_BUDGET tokens (whole entries)
  * - Recall gets at least RECALL_MIN_BUDGET, plus whatever daily logs didn't use
- * - Last recall entry can push total up to CONTEXT_BUDGET + RECALL_OVERFLOW (36k)
+ * - Last recall entry can push total up to budget + RECALL_OVERFLOW (4k grace)
  * - Weekly summaries are excluded (already indexed by recall)
  */
-const CONTEXT_BUDGET_TOKENS = 32_000;
-const DAILY_LOG_BUDGET_TOKENS = 24_000;
+export const DAILY_LOG_BUDGET_TOKENS = 24_000;
 const RECALL_MIN_BUDGET_TOKENS = 8_000;
 const RECALL_OVERFLOW_TOKENS = 4_000;
 /** Estimate tokens from character count. */
@@ -79,57 +90,98 @@ function estimateTokens(text) {
  */
 export function buildTeammatePrompt(teammate, taskPrompt, options) {
     const parts = [];
-    // ── Identity (required) ─────────────────────────────────────────
-    parts.push(`# You are ${teammate.name}\n\n${teammate.soul}\n\n---\n`);
-    // ── Wisdom (required) ───────────────────────────────────────────
+    // ── Top edge (high attention) ─────────────────────────────────────
+    // <IDENTITY> — anchors persona
+    parts.push(`<IDENTITY>\n# You are ${teammate.name}\n\n${teammate.soul}\n`);
+    // <WISDOM> — stable knowledge
     if (teammate.wisdom.trim()) {
-        parts.push(`## Your Wisdom\n\n${teammate.wisdom}\n\n---\n`);
+        parts.push(`<WISDOM>\n${teammate.wisdom}\n`);
+    }
+    // ── Reference data (middle — acceptable for "lost in the middle") ──
+    // <TEAM> — roster for handoffs
+    if (options?.roster && options.roster.length > 0) {
+        const lines = [
+            "<TEAM>",
+            "These are the other teammates you can hand off work to:\n",
+        ];
+        for (const t of options.roster) {
+            if (t.name === teammate.name)
+                continue;
+            const owns = t.ownership.primary.length > 0
+                ? ` — owns: ${t.ownership.primary.join(", ")}`
+                : "";
+            lines.push(`- **@${t.name}**: ${t.role}${owns}`);
+        }
+        parts.push(`${lines.join("\n")}\n`);
     }
-    // ── Budget-allocated context (daily logs → recall) ──────────────
-    // Today's log: always included, outside budget
-    // Days 2-7: up to 24k tokens (whole entries)
-    // Recall: at least 8k + unused daily budget, last entry may overflow by 4k
+    // <SERVICES> — installed services
+    if (options?.services && options.services.length > 0) {
+        const lines = [
+            "<SERVICES>",
+            "These services are installed and available for you to use:\n",
+        ];
+        for (const svc of options.services) {
+            lines.push(`### ${svc.name}\n`);
+            lines.push(svc.description);
+            lines.push(`\n**Usage:** \`${svc.usage}\`\n`);
+        }
+        parts.push(`${lines.join("\n")}\n`);
+    }
+    // <RECALL_TOOL> — Pass 2: agent-driven search
+    parts.push(`<RECALL_TOOL>\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`);
+    // <ENVIRONMENT> — date/time + platform
+    const now = new Date();
+    const today = now.toISOString().slice(0, 10);
+    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(`<ENVIRONMENT>\n**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`);
+    // ── Session context (middle-to-lower) ─────────────────────────────
+    // <DAILY_LOGS> — today's log (never trimmed) + days 2-7 (budget-allocated)
     const todayLog = teammate.dailyLogs.slice(0, 1);
     const pastLogs = teammate.dailyLogs.slice(1, 7); // days 2-7
     let dailyBudget = DAILY_LOG_BUDGET_TOKENS;
-    // Current daily log (today) — never trimmed, always included
-    if (todayLog.length > 0) {
-        const todayLines = ["## Recent Daily Logs\n"];
+    if (todayLog.length > 0 || pastLogs.length > 0) {
+        const logLines = ["<DAILY_LOGS>"];
+        // Current daily log (today) — never trimmed, always included
         for (const log of todayLog) {
-            todayLines.push(`### ${log.date}\n${log.content}\n`);
+            logLines.push(`### ${log.date}\n${log.content}`);
         }
-        parts.push(todayLines.join("\n"));
-    }
-    // Days 2-7 — whole entries, up to 24k tokens
-    if (pastLogs.length > 0) {
-        const lines = [];
+        // Days 2-7 — whole entries, up to 24k tokens
         for (const log of pastLogs) {
-            const entry = `### ${log.date}\n${log.content}\n`;
+            const entry = `### ${log.date}\n${log.content}`;
             const cost = estimateTokens(entry);
             if (cost > dailyBudget)
                 break;
-            lines.push(entry);
+            logLines.push(entry);
             dailyBudget -= cost;
         }
-        if (lines.length > 0)
-            parts.push(lines.join("\n"));
+        parts.push(`${logLines.join("\n")}\n`);
+    }
+    // <USER_PROFILE> — always included when present
+    if (options?.userProfile?.trim()) {
+        parts.push(`<USER_PROFILE>\n${options.userProfile.trim()}\n`);
     }
-    // Recall results — gets at least 8k tokens, plus unused daily budget
-    // Last entry may overflow by up to 4k tokens
+    // ── Task-adjacent context (close to task for maximum relevance) ───
+    // <RECALL_RESULTS> — budget-allocated, adjacent to task
     const recallBudget = Math.max(RECALL_MIN_BUDGET_TOKENS, RECALL_MIN_BUDGET_TOKENS + dailyBudget);
     const recallResults = options?.recallResults ?? [];
     if (recallResults.length > 0) {
         const lines = [
-            "## Relevant Memories (from recall search)\n",
+            "<RECALL_RESULTS>",
             "These memories were retrieved based on relevance to the current task:\n",
         ];
         const headerCost = estimateTokens(lines.join("\n"));
         let recallUsed = headerCost;
         for (const r of recallResults) {
-            const label = r.contentType
-                ? `[${r.contentType}] ${r.uri}`
-                : r.uri;
-            const entry = `### ${label}\n${r.text}\n`;
+            const label = r.contentType ? `[${r.contentType}] ${r.uri}` : r.uri;
+            const entry = `### ${label}\n${r.text}`;
             const cost = estimateTokens(entry);
             if (recallUsed + cost > recallBudget + RECALL_OVERFLOW_TOKENS)
                 break;
@@ -140,70 +192,90 @@ export function buildTeammatePrompt(teammate, taskPrompt, options) {
                 break;
         }
         if (lines.length > 2) {
-            lines.push("\n---\n");
-            parts.push(lines.join("\n"));
+            parts.push(`${lines.join("\n")}\n`);
         }
     }
-    // Close context section with separator if needed
-    if (todayLog.length > 0 || pastLogs.length > 0) {
-        const lastPart = parts[parts.length - 1];
-        if (!lastPart.endsWith("---\n")) {
-            parts.push("\n---\n");
-        }
+    // <HANDOFF_CONTEXT> — directly task-relevant when present
+    if (options?.handoffContext) {
+        parts.push(`<HANDOFF_CONTEXT>\n${options.handoffContext}\n`);
+    }
+    // ── The question ──────────────────────────────────────────────────
+    // <TASK> — always included, excluded from budget
+    parts.push(`<TASK>\n${taskPrompt}\n`);
+    // ── Bottom edge (high attention) — all instructions merged ────────
+    // <INSTRUCTIONS> — output protocol, handoffs, session state, memory updates
+    const instrLines = [
+        "<INSTRUCTIONS>",
+        "",
+        "### Output Protocol (CRITICAL)",
+        "",
+        "**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.",
+        "",
+        "Format your response as:",
+        "",
+        "```",
+        "TO: user",
+        "# <Subject line>",
+        "",
+        "<Body — full markdown response>",
+        "```",
+        "",
+        "**Rules:**",
+        "- **You MUST end your turn with visible text output.** A turn that ends with only tool calls and no text is a failed turn.",
+        "- The `# Subject` line is REQUIRED — it becomes the message title.",
+        "- Always write a substantive body. Never return just the subject.",
+        "- Use markdown: headings, lists, code blocks, bold, etc.",
+        "- **Write your text response FIRST, then update session/memory files.** This ensures visible output even if the agent turn ends early.",
+        "",
+        "### Handoffs",
+        "",
+        "To delegate work to a teammate, you MUST include a fenced code block with the language tag `handoff` in your text output. **This is the ONLY way to trigger a handoff.** Mentioning a handoff in plain English does NOT work — the system parses the fenced block, not your prose.",
+        "",
+        "Exact format (include the triple backticks exactly as shown):",
+        "",
+        "    ```handoff",
+        "    @<teammate-name>",
+        "    <task description with full context>",
+        "    ```",
+        "",
+        "Rules:",
+        `- Only hand off to teammates listed in \`<TEAM>\`.`,
+        "- Do as much work as you can BEFORE handing off.",
+        '- Do NOT just say "I\'ll hand this off" in prose — that does nothing. You MUST use the fenced block.',
+    ];
+    // Session state (conditional)
+    if (options?.sessionFile) {
+        instrLines.push("", "### Session State", "", `Your session file is at: \`${options.sessionFile}\``, "", "**After writing your text response**, append a brief entry to this file with:", "- What you did", "- Key decisions made", "- Files changed", "- Anything the next task should know", "", "This is how you maintain continuity across tasks. Always read it, always update it.");
+    }
+    // Memory updates
+    instrLines.push("", "### Memory Updates", "", "**After writing your text response**, update your memory files:", "", `1. **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.`, "   - What you did", "   - Key decisions made", "   - Files changed", "   - Anything the next task should know", "", `2. **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.`, "", "3. **WISDOM.md** — Do not edit directly. Wisdom entries are distilled from typed memories during compaction.", "", "These files are your persistent memory. Without them, your next session starts from scratch.");
+    // Section Reinforcement — back-references from high-attention bottom edge to each section tag
+    instrLines.push("", "### Section Reinforcement", "");
+    instrLines.push("- Stay in character as defined in `<IDENTITY>` — never break persona or speak as a generic assistant.");
+    if (teammate.wisdom.trim()) {
+        instrLines.push("- Apply lessons from `<WISDOM>` before proposing solutions — do not repeat past mistakes.");
     }
-    // ── Team roster (required, small) ───────────────────────────────
     if (options?.roster && options.roster.length > 0) {
-        const lines = [
-            "## Your Team\n",
-            "These are the other teammates you can hand off work to:\n",
-        ];
-        for (const t of options.roster) {
-            if (t.name === teammate.name)
-                continue;
-            const owns = t.ownership.primary.length > 0
-                ? ` — owns: ${t.ownership.primary.join(", ")}`
-                : "";
-            lines.push(`- **@${t.name}**: ${t.role}${owns}`);
-        }
-        lines.push("\n---\n");
-        parts.push(lines.join("\n"));
+        instrLines.push("- Only hand off to teammates listed in `<TEAM>` using the handoff block format above.");
     }
-    // ── Installed services (required, small) ────────────────────────
     if (options?.services && options.services.length > 0) {
-        const lines = [
-            "## Available Services\n",
-            "These services are installed and available for you to use:\n",
-        ];
-        for (const svc of options.services) {
-            lines.push(`### ${svc.name}\n`);
-            lines.push(svc.description);
-            lines.push(`\n**Usage:** \`${svc.usage}\`\n`);
-        }
-        lines.push("\n---\n");
-        parts.push(lines.join("\n"));
+        instrLines.push("- Use tools and services from `<SERVICES>` when they fit the task — do not reinvent what is already available.");
     }
-    // ── Handoff context (required when present) ─────────────────────
-    if (options?.handoffContext) {
-        parts.push(`## Handoff Context\n\n${options.handoffContext}\n\n---\n`);
+    instrLines.push("- If pre-loaded context is insufficient, use `<RECALL_TOOL>` to search for additional memories before giving up.", "- Respect platform, date, and path conventions from `<ENVIRONMENT>`.");
+    if (todayLog.length > 0 || pastLogs.length > 0) {
+        instrLines.push("- Check `<DAILY_LOGS>` for prior work on this topic before starting — avoid duplicating what was already done today.");
     }
-    // ── 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`);
-    }
-    // ── 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) ─────────────────────────
-    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`);
-    // ── User profile (always included when present) ────────────────
     if (options?.userProfile?.trim()) {
-        parts.push(`## User Profile\n\n${options.userProfile.trim()}\n\n---\n`);
+        instrLines.push("- Honor the user's role, preferences, and communication style from `<USER_PROFILE>`.");
+    }
+    if (recallResults.length > 0) {
+        instrLines.push("- Incorporate relevant context from `<RECALL_RESULTS>` into your response — these memories were retrieved for a reason.");
+    }
+    if (options?.handoffContext) {
+        instrLines.push("- When `<HANDOFF_CONTEXT>` is present, address its requirements and open questions directly.");
     }
-    // ── 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.**`);
+    instrLines.push("- Your response must answer `<TASK>` — everything else is supporting context.", "", "**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.**");
+    parts.push(instrLines.join("\n"));
     return parts.join("\n");
 }
 /**

package/dist/adapter.test.js

@@ -25,27 +25,28 @@ describe("buildTeammatePrompt", () => {
     });
     it("includes the task", () => {
         const prompt = buildTeammatePrompt(makeConfig(), "fix the bug");
-        expect(prompt).toContain("## Task");
+        expect(prompt).toContain("<TASK>");
         expect(prompt).toContain("fix the bug");
     });
     it("includes output protocol", () => {
         const prompt = buildTeammatePrompt(makeConfig(), "task");
-        expect(prompt).toContain("## Output Protocol");
+        expect(prompt).toContain("<INSTRUCTIONS>");
+        expect(prompt).toContain("Output Protocol");
         expect(prompt).toContain("TO: user");
         expect(prompt).toContain("```handoff");
     });
     it("includes memory updates section", () => {
         const prompt = buildTeammatePrompt(makeConfig(), "task");
-        expect(prompt).toContain("## Memory Updates");
+        expect(prompt).toContain("### Memory Updates");
         expect(prompt).toContain(".teammates/beacon/memory/");
     });
     it("skips wisdom section when empty", () => {
         const prompt = buildTeammatePrompt(makeConfig({ wisdom: "" }), "task");
-        expect(prompt).not.toContain("## Your Wisdom");
+        expect(prompt).not.toContain("<WISDOM>");
     });
     it("includes wisdom when present", () => {
         const prompt = buildTeammatePrompt(makeConfig({ wisdom: "Some important wisdom" }), "task");
-        expect(prompt).toContain("## Your Wisdom");
+        expect(prompt).toContain("<WISDOM>");
         expect(prompt).toContain("Some important wisdom");
     });
     it("includes daily logs (up to 7)", () => {
@@ -60,7 +61,7 @@ describe("buildTeammatePrompt", () => {
             { date: "2026-03-06", content: "Should be excluded" },
         ];
         const prompt = buildTeammatePrompt(makeConfig({ dailyLogs: logs }), "task");
-        expect(prompt).toContain("## Recent Daily Logs");
+        expect(prompt).toContain("<DAILY_LOGS>");
         expect(prompt).toContain("2026-03-13");
         expect(prompt).toContain("2026-03-07");
         expect(prompt).not.toContain("2026-03-06");
@@ -80,7 +81,7 @@ describe("buildTeammatePrompt", () => {
             },
         ];
         const prompt = buildTeammatePrompt(makeConfig(), "task", { roster });
-        expect(prompt).toContain("## Your Team");
+        expect(prompt).toContain("<TEAM>");
         expect(prompt).toContain("@scribe");
         expect(prompt).toContain("Documentation writer.");
         // Should not list self in roster
@@ -90,14 +91,14 @@ describe("buildTeammatePrompt", () => {
         const prompt = buildTeammatePrompt(makeConfig(), "task", {
             handoffContext: "Handed off from scribe with files changed",
         });
-        expect(prompt).toContain("## Handoff Context");
+        expect(prompt).toContain("<HANDOFF_CONTEXT>");
         expect(prompt).toContain("Handed off from scribe");
     });
     it("includes session file when provided", () => {
         const prompt = buildTeammatePrompt(makeConfig(), "task", {
             sessionFile: "/tmp/beacon-session.md",
         });
-        expect(prompt).toContain("## Session State");
+        expect(prompt).toContain("### Session State");
         expect(prompt).toContain("/tmp/beacon-session.md");
     });
     it("drops daily logs that exceed the 24k daily budget", () => {
@@ -130,11 +131,17 @@ describe("buildTeammatePrompt", () => {
         const recallText = "R".repeat(20_000); // ~5k tokens — fits in 8k min
         const prompt = buildTeammatePrompt(config, "task", {
             recallResults: [
-                { teammate: "beacon", uri: "memory/decision_foo.md", text: recallText, score: 0.9, contentType: "typed_memory" },
+                {
+                    teammate: "beacon",
+                    uri: "memory/decision_foo.md",
+                    text: recallText,
+                    score: 0.9,
+                    contentType: "typed_memory",
+                },
             ],
         });
         expect(prompt).toContain("2026-03-17");
-        expect(prompt).toContain("## Relevant Memories");
+        expect(prompt).toContain("<RECALL_RESULTS>");
     });
     it("recall gets unused daily log budget", () => {
         // Small daily logs leave most of 24k unused — recall gets the surplus.
@@ -148,10 +155,16 @@ describe("buildTeammatePrompt", () => {
         const recallText = "R".repeat(80_000); // ~20k tokens — fits in (8k + ~24k unused)
         const prompt = buildTeammatePrompt(config, "task", {
             recallResults: [
-                { teammate: "beacon", uri: "memory/big.md", text: recallText, score: 0.9, contentType: "typed_memory" },
+                {
+                    teammate: "beacon",
+                    uri: "memory/big.md",
+                    text: recallText,
+                    score: 0.9,
+                    contentType: "typed_memory",
+                },
             ],
         });
-        expect(prompt).toContain("## Relevant Memories");
+        expect(prompt).toContain("<RECALL_RESULTS>");
         expect(prompt).toContain("memory/big.md");
     });
     it("weekly summaries are excluded (indexed by recall)", () => {
@@ -160,8 +173,8 @@ describe("buildTeammatePrompt", () => {
             weeklyLogs: [{ week: "2026-W11", content: "short summary" }],
         });
         const prompt = buildTeammatePrompt(config, "task");
-        expect(prompt).toContain("## Recent Daily Logs");
-        expect(prompt).not.toContain("## Recent Weekly Summaries");
+        expect(prompt).toContain("<DAILY_LOGS>");
+        expect(prompt).not.toContain("Weekly Summaries");
     });
     it("excludes task prompt from budget calculation", () => {
         // Large task prompt should not trigger trimming of wrapper sections
@@ -171,7 +184,7 @@ describe("buildTeammatePrompt", () => {
         });
         const prompt = buildTeammatePrompt(config, bigTask);
         // Daily logs should still be included despite the huge task
-        expect(prompt).toContain("## Recent Daily Logs");
+        expect(prompt).toContain("<DAILY_LOGS>");
         expect(prompt).toContain("small log");
     });
 });

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>;