@teammates/cli 0.1.0 → 0.2.0

package/README.md

@@ -1,5 +1,7 @@
 # @teammates/cli
 
+> Part of the [teammates](https://github.com/Stevenic/teammates) monorepo.
+
 Agent-agnostic CLI orchestrator for teammates. Routes tasks to teammates, manages handoffs, and plugs into any coding agent backend.
 
 ## Quick Start
@@ -53,16 +55,17 @@ Once inside the REPL, you can interact with teammates using `@mentions`, `/comma
 
 | Command | Aliases | Description |
 |---|---|---|
-| `/route <task>` | `/r` | Auto-route a task to the best teammate |
-| `/status` | `/s` | Show teammate roster and session status |
-| `/teammates` | `/team`, `/t` | List all teammates and their roles |
+| `/status` | `/s`, `/queue`, `/qu` | Show teammates, active tasks, and queue |
 | `/log [teammate]` | `/l` | Show the last task result (optionally for a specific teammate) |
 | `/debug [teammate]` | `/raw` | Show raw agent output from the last task |
-| `/queue @teammate <task>` | `/qu` | Add a task to the background queue |
-| `/queue` | `/qu` | Show the current queue |
 | `/cancel <n>` | | Cancel a queued task by number |
-| `/install <service>` | | Install an optional service (e.g. `recall`) |
-| `/clear` | `/cls`, `/reset` | Clear conversation history, reset all sessions, and reprint banner |
+| `/init` | `/onboard`, `/setup` | Run onboarding to set up teammates for this project |
+| `/install <service>` | | Install a teammates service (e.g. `recall`) |
+| `/compact [teammate]` | | Compact daily logs into weekly/monthly summaries |
+| `/retro [teammate]` | | Run a structured self-retrospective for a teammate |
+| `/copy` | `/cp` | Copy the last response to clipboard |
+| `/theme` | | Show current theme colors |
+| `/clear` | `/cls`, `/reset` | Clear history and reset the session |
 | `/help` | `/h`, `/?` | Show available commands |
 | `/exit` | `/q`, `/quit` | Exit the session |
 
@@ -87,7 +90,16 @@ Queued tasks drain one at a time. If a handoff requires approval, the queue paus
 
 ## Handoffs
 
-When a teammate finishes a task, it may propose a handoff to another teammate. The CLI presents a menu:
+Teammates propose handoffs by including fenced handoff blocks in their response:
+
+````
+```handoff
+@beacon
+Update the search index to support the new memory format
+```
+````
+
+Multiple handoff blocks can appear anywhere in a single response. The CLI detects them automatically and presents each one with an approval menu:
 
 ```
   1) Approve          — execute the handoff
@@ -95,7 +107,7 @@ When a teammate finishes a task, it may propose a handoff to another teammate. T
   3) Reject           — decline the handoff
 ```
 
-Handoff details (task, changed files, acceptance criteria, open questions) are displayed before you choose.
+Each handoff is approved individually — there is no automatic chaining.
 
 ## Conversation History
 
@@ -120,7 +132,7 @@ The CLI uses a generic adapter interface to support any coding agent. Each adapt
 2. The prompt is written to a temp file
 3. The agent CLI is spawned with the prompt
 4. stdout/stderr are captured for result parsing
-5. The output is parsed for structured JSON result/handoff blocks
+5. The output is parsed for embedded handoff blocks
 6. Temp files are cleaned up
 
 ### Writing a Custom Adapter
@@ -155,7 +167,7 @@ Or add a preset to `cli-proxy.ts` for any CLI agent that accepts a prompt and ru
 ```
 cli/src/
   cli.ts            # Entry point, REPL, slash commands, wordwheel UI
-  orchestrator.ts   # Task routing, handoff chains, session management
+  orchestrator.ts   # Task routing, session management
   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)
@@ -167,19 +179,16 @@ cli/src/
 
 ### Output Protocol
 
-Agents are instructed to end their response with a structured JSON block:
-
-```json
-{ "result": { "summary": "...", "changedFiles": ["..."] } }
-```
-
-Or for handoffs:
+Agents format their response as a markdown message with a `# Subject` line. Handoffs are embedded as fenced code blocks:
 
-```json
-{ "handoff": { "to": "teammate", "task": "...", "context": "..." } }
+````
+```handoff
+@<teammate>
+<task description with full context>
 ```
+````
 
-The CLI parses the last JSON fence in the output. If no structured block is found, it falls back to scraping file paths and summaries from freeform output.
+The CLI parses all `` ```handoff `` fences in the output. Multiple handoff blocks are supported in a single response. Each is presented to the user for individual approval.
 
 ## Testing
 
@@ -201,7 +210,7 @@ Tests use [Vitest](https://vitest.dev/) and cover the core modules:
 | File | Covers |
 |---|---|
 | `src/adapter.test.ts` | `buildTeammatePrompt`, `formatHandoffContext` |
-| `src/orchestrator.test.ts` | Task routing, assignment, handoff chains, cycle detection, reset |
+| `src/orchestrator.test.ts` | Task routing, assignment, reset |
 | `src/registry.test.ts` | Teammate discovery, SOUL.md parsing (role, ownership), daily logs |
 | `src/adapters/echo.test.ts` | Echo adapter session and task execution |
 

package/dist/adapter.d.ts

@@ -5,7 +5,7 @@
  * 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 type { TeammateConfig, TaskResult } from "./types.js";
+import type { TaskResult, TeammateConfig } from "./types.js";
 export interface AgentAdapter {
     /** Human-readable name of the agent backend (e.g. "codex", "claude-code") */
     readonly name: string;

package/dist/adapter.js

@@ -15,19 +15,27 @@ export function buildTeammatePrompt(teammate, taskPrompt, options) {
     parts.push(`# You are ${teammate.name}\n`);
     parts.push(teammate.soul);
     parts.push("\n---\n");
-    // ── Memories ──────────────────────────────────────────────────────
-    if (teammate.memories.trim()) {
-        parts.push("## Your Memories\n");
-        parts.push(teammate.memories);
+    // ── Wisdom ───────────────────────────────────────────────────────
+    if (teammate.wisdom.trim()) {
+        parts.push("## Your Wisdom\n");
+        parts.push(teammate.wisdom);
         parts.push("\n---\n");
     }
     if (teammate.dailyLogs.length > 0) {
         parts.push("## Recent Daily Logs\n");
-        for (const log of teammate.dailyLogs.slice(0, 3)) {
+        for (const log of teammate.dailyLogs.slice(0, 7)) {
             parts.push(`### ${log.date}\n${log.content}\n`);
         }
         parts.push("\n---\n");
     }
+    // ── Weekly summaries (recent episodic context) ─────────────────────
+    if (teammate.weeklyLogs.length > 0) {
+        parts.push("## Recent Weekly Summaries\n");
+        for (const log of teammate.weeklyLogs.slice(0, 2)) {
+            parts.push(`### ${log.week}\n${log.content}\n`);
+        }
+        parts.push("\n---\n");
+    }
     // ── Team roster ───────────────────────────────────────────────────
     if (options?.roster && options.roster.length > 0) {
         parts.push("## Your Team\n");
@@ -62,69 +70,73 @@ export function buildTeammatePrompt(teammate, taskPrompt, options) {
     // ── Session state ────────────────────────────────────────────────
     if (options?.sessionFile) {
         parts.push("## Session State\n");
-        parts.push(`Your session file is at: \`${options.sessionFile}\`
-
-**Read this file first** — it contains context from your prior tasks in this session.
-
-**Before returning your result**, 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.
+        parts.push(`Your session file is at: \`${options.sessionFile}\`
+
+**Read this file first** — it contains context from your prior tasks in this session.
+
+**Before returning your result**, 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.
 `);
         parts.push("\n---\n");
     }
     // ── Memory updates ─────────────────────────────────────────────────
     const today = new Date().toISOString().slice(0, 10);
     parts.push("## Memory Updates\n");
-    parts.push(`**Before returning your result**, 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. **MEMORIES.md** — If you learned something durable (a decision, pattern, gotcha, or bug), read \`.teammates/${teammate.name}/MEMORIES.md\`, then write it back with your entry added.
-
-These files are your persistent memory. Without them, your next session starts from scratch.
+    parts.push(`**Before returning your result**, 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.
 `);
     parts.push("\n---\n");
     // ── Output protocol ───────────────────────────────────────────────
     parts.push("## Output Protocol\n");
-    parts.push(`When you finish, you MUST end your response with exactly one of these two blocks:
-
-### Option 1: Direct response
-
-If you can complete the task yourself, do the work and then end with:
-
-\`\`\`json
-{ "result": { "summary": "<one-line summary of what you did>", "changedFiles": ["<file>", ...] } }
-\`\`\`
-
-### Option 2: Handoff
-
-If the task (or part of it) belongs to another teammate, end with:
-
-\`\`\`json
-{ "handoff": { "to": "<teammate>", "task": "<specific request for them>", "changedFiles": ["<files you changed, if any>"], "context": "<any context they need>" } }
-\`\`\`
-
-You may also write a task file (e.g. \`.teammates/tasks/<name>.md\`) with detailed instructions and reference it in the handoff:
-
-\`\`\`json
-{ "handoff": { "to": "<teammate>", "task": "See .teammates/tasks/<name>.md", "changedFiles": [".teammates/tasks/<name>.md"] } }
-\`\`\`
-
-Rules:
-- Always include exactly one JSON block at the end — either \`result\` or \`handoff\`.
-- Only hand off to teammates listed in "Your Team" above.
-- Do as much of the work as you can before handing off.
-- If the task is outside everyone's ownership, do your best and return a result.
+    parts.push(`Your response is a message. Format it as:
+
+\`\`\`
+TO: user
+# <Subject line>
+
+<Body — full markdown response>
+\`\`\`
+
+**Handoffs:** To hand off work to a teammate, include a fenced handoff block anywhere in your response:
+
+\`\`\`
+\`\`\`handoff
+@<teammate>
+<task description — what you need them to do, with full context>
+\`\`\`
+\`\`\`
+
+**Rules:**
+- The \`# Subject\` line is REQUIRED — it becomes the message title.
+- Always write a substantive body. Never return just the subject.
+- **Your final message MUST contain your response text.** Do not end your turn with only tool calls — always finish with a visible message to the user.
+- Use markdown: headings, lists, code blocks, bold, etc.
+- Do as much work as you can before handing off.
+- Only hand off to teammates listed in "Your Team" above.
+- The handoff block can appear anywhere in your response — it will be detected automatically.
 `);
     parts.push("\n---\n");
+    // ── Current date/time ────────────────────────────────────────────
+    const now = new Date();
+    parts.push(`**Current date:** ${now.toLocaleDateString("en-US", { weekday: "long", year: "numeric", month: "long", day: "numeric" })} (${today})`);
+    parts.push(`**Current time:** ${now.toLocaleTimeString("en-US", { hour: "2-digit", minute: "2-digit" })}\n`);
+    parts.push("---\n");
     // ── Task ──────────────────────────────────────────────────────────
     parts.push("## Task\n");
     parts.push(taskPrompt);

package/dist/adapter.test.js

@@ -1,13 +1,15 @@
-import { describe, it, expect } from "vitest";
+import { describe, expect, it } from "vitest";
 import { buildTeammatePrompt, formatHandoffContext } from "./adapter.js";
 function makeConfig(overrides) {
     return {
         name: "beacon",
         role: "Platform engineer.",
         soul: "# Beacon\n\nBeacon owns the recall package.",
-        memories: "",
+        wisdom: "",
         dailyLogs: [],
+        weeklyLogs: [],
         ownership: { primary: ["recall/src/**"], secondary: [] },
+        routingKeywords: [],
         ...overrides,
     };
 }
@@ -28,42 +30,53 @@ describe("buildTeammatePrompt", () => {
     it("includes output protocol", () => {
         const prompt = buildTeammatePrompt(makeConfig(), "task");
         expect(prompt).toContain("## Output Protocol");
-        expect(prompt).toContain('"result"');
-        expect(prompt).toContain('"handoff"');
+        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(".teammates/beacon/memory/");
     });
-    it("skips memories section when empty", () => {
-        const prompt = buildTeammatePrompt(makeConfig({ memories: "" }), "task");
-        expect(prompt).not.toContain("## Your Memories");
+    it("skips wisdom section when empty", () => {
+        const prompt = buildTeammatePrompt(makeConfig({ wisdom: "" }), "task");
+        expect(prompt).not.toContain("## Your Wisdom");
     });
-    it("includes memories when present", () => {
-        const prompt = buildTeammatePrompt(makeConfig({ memories: "Some important memory" }), "task");
-        expect(prompt).toContain("## Your Memories");
-        expect(prompt).toContain("Some important memory");
+    it("includes wisdom when present", () => {
+        const prompt = buildTeammatePrompt(makeConfig({ wisdom: "Some important wisdom" }), "task");
+        expect(prompt).toContain("## Your Wisdom");
+        expect(prompt).toContain("Some important wisdom");
     });
-    it("includes daily logs (up to 3)", () => {
+    it("includes daily logs (up to 7)", () => {
         const logs = [
-            { date: "2026-03-13", content: "Did stuff today" },
-            { date: "2026-03-12", content: "Did stuff yesterday" },
-            { date: "2026-03-11", content: "Day before" },
-            { date: "2026-03-10", content: "Should be excluded" },
+            { date: "2026-03-13", content: "Day 1" },
+            { date: "2026-03-12", content: "Day 2" },
+            { date: "2026-03-11", content: "Day 3" },
+            { date: "2026-03-10", content: "Day 4" },
+            { date: "2026-03-09", content: "Day 5" },
+            { date: "2026-03-08", content: "Day 6" },
+            { date: "2026-03-07", content: "Day 7" },
+            { date: "2026-03-06", content: "Should be excluded" },
         ];
         const prompt = buildTeammatePrompt(makeConfig({ dailyLogs: logs }), "task");
         expect(prompt).toContain("## Recent Daily Logs");
         expect(prompt).toContain("2026-03-13");
-        expect(prompt).toContain("2026-03-12");
-        expect(prompt).toContain("2026-03-11");
-        expect(prompt).not.toContain("2026-03-10");
+        expect(prompt).toContain("2026-03-07");
+        expect(prompt).not.toContain("2026-03-06");
         expect(prompt).not.toContain("Should be excluded");
     });
     it("includes roster excluding self", () => {
         const roster = [
-            { name: "beacon", role: "Platform engineer.", ownership: { primary: [], secondary: [] } },
-            { name: "scribe", role: "Documentation writer.", ownership: { primary: ["docs/**"], secondary: [] } },
+            {
+                name: "beacon",
+                role: "Platform engineer.",
+                ownership: { primary: [], secondary: [] },
+            },
+            {
+                name: "scribe",
+                role: "Documentation writer.",
+                ownership: { primary: ["docs/**"], secondary: [] },
+            },
         ];
         const prompt = buildTeammatePrompt(makeConfig(), "task", { roster });
         expect(prompt).toContain("## Your Team");

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

@@ -14,8 +14,8 @@
  *   3. Tees stdout/stderr to the user's terminal in real time
  *   4. Captures output for result parsing (changed files, handoff envelopes)
  */
-import type { AgentAdapter, RosterEntry, InstalledService } from "../adapter.js";
-import type { TeammateConfig, TaskResult, SandboxLevel } from "../types.js";
+import type { AgentAdapter, InstalledService, RosterEntry } from "../adapter.js";
+import type { SandboxLevel, TaskResult, TeammateConfig } from "../types.js";
 export interface AgentPreset {
     /** Display name */
     name: string;
@@ -32,6 +32,10 @@ export interface AgentPreset {
     interactive?: boolean;
     /** Whether the command needs shell: true to run */
     shell?: boolean;
+    /** Whether to pipe the prompt via stdin instead of as a CLI argument */
+    stdinPrompt?: boolean;
+    /** Optional output parser — transforms raw stdout into clean agent output */
+    parseOutput?(raw: string): string;
 }
 export declare const PRESETS: Record<string, AgentPreset>;
 export interface CliProxyOptions {
@@ -64,11 +68,14 @@ 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): Promise<TaskResult>;
     routeTask(task: string, roster: RosterEntry[]): Promise<string | null>;
-    destroySession(sessionId: string): Promise<void>;
+    destroySession(_sessionId: string): Promise<void>;
     /**
      * Spawn the agent, stream its output live, and capture it.
      */
     private spawnAndProxy;
 }
+export declare function parseResult(teammateName: string, output: string, teammateNames?: string[], _originalTask?: string): TaskResult;
+/** Extract file paths from agent output. */
+export declare function parseChangedFiles(output: string): string[];