clearclaw 0.6.1 → 0.7.0

package/dist/orchestrator.js

@@ -4,6 +4,7 @@ import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
 import { z } from "zod";
 import log from "./logger.js";
 import { saveFile } from "./files.js";
+import { assemblePrompt } from "./prompt.js";
 import { formatToolStatusLine, formatToolCallSummary, formatPermissionPrompt, formatTodoList, timeAgo } from "./format.js";
 import { permissionHandlers, displayHandledTools } from "./tool-handlers.js";
 function isTask(ctx) {
@@ -17,13 +18,13 @@ const MODE_OPTIONS = [
 ];
 export class Orchestrator {
     channel;
-    engine;
+    engines;
     config;
     chats = new Map();
     tasks = new Map();
     constructor(opts) {
         this.channel = opts.channel;
-        this.engine = opts.engine;
+        this.engines = opts.engines;
         this.config = opts.config;
     }
     chat(chatId) {
@@ -31,13 +32,22 @@ export class Orchestrator {
         if (!s) {
             s = {
                 busy: false, abort: null, permissionMode: null, stats: null, lastStatusText: null,
-                toolCallHandle: null, todoHandle: null,
+                toolCallHandle: null, todoHandle: null, textHandle: null, textBuffer: "",
+                engineName: null,
                 messageQueue: [], debounceTimer: null,
             };
             this.chats.set(chatId, s);
         }
         return s;
     }
+    engineFor(ws) {
+        const name = ws.engine ?? this.config.defaultEngine;
+        const engine = this.engines.get(name);
+        if (!engine) {
+            throw new Error(`Unknown engine "${name}" configured for workspace "${ws.name}". Available: ${[...this.engines.keys()].join(", ")}`);
+        }
+        return engine;
+    }
     async start() {
         this.channel.on("message", (msg) => {
             this.routeMessage(msg).catch((err) => {
@@ -62,7 +72,7 @@ export class Orchestrator {
             return "assistant";
         if (ctx.behavior !== undefined)
             return ctx.behavior;
-        return ctx.cwd === path.dirname(this.config.defaultPromptPath) ? "assistant" : "relay";
+        return ctx.cwd === this.config.homeWorkspacePath ? "assistant" : "relay";
     }
     /** Enqueue a message and drain — immediately for relay, debounced for assistant/task. */
     enqueueMessage(msg, ctx, state) {
@@ -131,10 +141,10 @@ export class Orchestrator {
         const logPrefix = task ? "[task-turn]" : "[turn]";
         log.info("%s start session=%s msgs=%d cwd=%s", logPrefix, sessionId ?? "new", messages.length, cwd);
         await this.channel.setTyping(chatId, true);
-        const isHomeWorkspace = ws && ws.cwd === path.dirname(this.config.defaultPromptPath);
+        const assembledPrompt = assemblePrompt(this.config.frameworkPromptDir, this.config.instructionsDir);
         const appendSystemPrompt = task
-            ? task.prompt
-            : (isHomeWorkspace ? undefined : this.readDefaultPrompt());
+            ? (assembledPrompt ? `${assembledPrompt}\n\n${task.prompt}` : task.prompt)
+            : assembledPrompt;
         const prompt = buildPrompt(messages);
         // Save attachments for workspace turns
         const allAttachments = messages.flatMap((m) => m.attachments ?? []);
@@ -152,8 +162,10 @@ export class Orchestrator {
             name: "clearclaw",
             tools: this.buildMcpTools(chatId, behavior, turnState),
         });
+        const engine = ws ? this.engineFor(ws) : this.engines.get(this.config.defaultEngine);
+        state.engineName = engine.name;
         try {
-            for await (const event of this.engine.runTurn({
+            for await (const event of engine.runTurn({
                 sessionId,
                 cwd,
                 prompt,
@@ -188,6 +200,15 @@ export class Orchestrator {
                     }
                     state.toolCallHandle = null;
                     state.todoHandle = null;
+                    // Final formatted edit for any pending streaming text
+                    if (state.textHandle && state.textBuffer) {
+                        try {
+                            await this.channel.editMessage(chatId, state.textHandle, state.textBuffer);
+                        }
+                        catch { /* best effort */ }
+                    }
+                    state.textHandle = null;
+                    state.textBuffer = "";
                     await this.updateStatusMessage(chatId, state);
                     break;
                 }
@@ -283,7 +304,7 @@ export class Orchestrator {
                     await this.channel.sendMessage(msg.chatId, "No workspace linked to this group.");
                     return;
                 }
-                const sessions = await this.engine.listSessions(ws.cwd);
+                const sessions = await this.engineFor(ws).listSessions(ws.cwd);
                 if (sessions.length === 0) {
                     await this.channel.sendMessage(msg.chatId, "No sessions found for this workspace.");
                     return;
@@ -339,13 +360,15 @@ export class Orchestrator {
             }
             if (!ws) {
                 if (this.config.isAuthorized(msg.user.id)) {
+                    const chatType = msg.chatType === "dm" ? "DM" : "group";
                     const newTask = {
                         sessionId: null,
-                        cwd: path.dirname(this.config.defaultPromptPath),
+                        cwd: this.config.homeWorkspacePath,
                         prompt: [
                             "THIS IS A TASK SESSION — not a regular conversation.",
                             "Do NOT follow the 'Every Session' startup routine. Do NOT read MEMORY.md or daily notes. Do NOT greet the user.",
-                            "Your only job: help set up a workspace for this chat. Use the onboarding skill.",
+                            `This is a ${chatType} chat. Home workspace path: ${this.config.homeWorkspacePath}`,
+                            "Follow the Workspace Onboarding instructions in the system prompt.",
                         ].join("\n"),
                     };
                     this.tasks.set(msg.chatId, newTask);
@@ -376,13 +399,49 @@ export class Orchestrator {
                         replyToMessageId: turnState.replyToMessageId ?? undefined,
                     });
                     break;
+                case "text_chunk": {
+                    if (turnState.staySilent)
+                        break;
+                    state.textBuffer += event.text;
+                    const plainOpts = { format: "plain" };
+                    if (state.textHandle) {
+                        try {
+                            await this.channel.editMessage(chatId, state.textHandle, state.textBuffer, plainOpts);
+                        }
+                        catch {
+                            const handles = await this.channel.sendMessage(chatId, state.textBuffer, {
+                                ...plainOpts,
+                                replyToMessageId: turnState.replyToMessageId ?? undefined,
+                            });
+                            state.textHandle = handles[0];
+                        }
+                    }
+                    else {
+                        const handles = await this.channel.sendMessage(chatId, state.textBuffer, {
+                            ...plainOpts,
+                            replyToMessageId: turnState.replyToMessageId ?? undefined,
+                        });
+                        state.textHandle = handles[0];
+                    }
+                    break;
+                }
                 case "tool_use": {
+                    // Flush streaming text — final edit with markdown formatting
+                    if (state.textHandle && state.textBuffer) {
+                        try {
+                            await this.channel.editMessage(chatId, state.textHandle, state.textBuffer);
+                        }
+                        catch { /* best effort */ }
+                    }
+                    state.textHandle = null;
+                    state.textBuffer = "";
                     // In assistant behavior, all tool status is suppressed (no rolling status, no plan mode notifications)
                     if (behavior === "assistant")
                         break;
                     // Relay behavior: existing display logic
-                    if (event.toolName === "TodoWrite") {
-                        const text = formatTodoList(event.input);
+                    const { tool } = event;
+                    if (tool.toolName === "TodoWrite") {
+                        const text = formatTodoList(tool);
                         if (state.todoHandle) {
                             try {
                                 await this.channel.editMessage(chatId, state.todoHandle, text);
@@ -398,13 +457,13 @@ export class Orchestrator {
                         }
                         break;
                     }
-                    if (event.toolName === "EnterPlanMode") {
+                    if (tool.toolName === "EnterPlanMode") {
                         await this.channel.sendMessage(chatId, "📋 Planning");
                         break;
                     }
-                    if (displayHandledTools.has(event.toolName))
+                    if (displayHandledTools.has(tool.toolName))
                         break;
-                    const line = formatToolStatusLine(event.toolName, event.input);
+                    const line = formatToolStatusLine(tool);
                     if (state.toolCallHandle) {
                         try {
                             await this.channel.editMessage(chatId, state.toolCallHandle, line);
@@ -470,10 +529,15 @@ export class Orchestrator {
                 cwd: z.string().describe("Absolute path to the workspace directory"),
                 behavior: z.enum(["assistant", "relay"]).optional()
                     .describe("Workspace behavior mode"),
+                engine: z.string().optional()
+                    .describe("Engine to use (e.g. 'claude-code', 'kiro'). Defaults to the server's configured default engine."),
             }, async (args) => {
                 if (this.config.workspaceByName(args.name)) {
                     throw new Error(`Workspace "${args.name}" already exists. Choose a different name.`);
                 }
+                if (args.engine && !this.engines.has(args.engine)) {
+                    throw new Error(`Unknown engine "${args.engine}". Available: ${[...this.engines.keys()].join(", ")}`);
+                }
                 fs.mkdirSync(args.cwd, { recursive: true });
                 this.config.upsertWorkspace({
                     name: args.name,
@@ -481,8 +545,9 @@ export class Orchestrator {
                     chat_id: chatId,
                     current_session_id: null,
                     behavior: args.behavior,
+                    engine: args.engine,
                 });
-                log.info("[tool] workspace_create: %s → %s (chat %s)", args.name, args.cwd, chatId);
+                log.info("[tool] workspace_create: %s → %s engine=%s (chat %s)", args.name, args.cwd, args.engine ?? "default", chatId);
                 return { content: [{ type: "text", text: `Workspace "${args.name}" created at ${args.cwd}, linked to this chat.` }] };
             }), tool("task_complete", "Signal that the current task is complete", {
                 message: z.string().optional().describe("Summary of what was accomplished"),
@@ -512,42 +577,42 @@ export class Orchestrator {
         }
         return tools;
     }
-    async handlePermission(req, chatId) {
+    async handlePermission(tool, chatId) {
         // Always auto-allow ClearClaw's own MCP tools
-        if (req.toolName.startsWith("mcp__clearclaw__")) {
-            log.info(`[perm] ${req.toolName} → auto-allow`);
+        if (tool.toolName.startsWith("mcp__clearclaw__")) {
+            log.info(`[perm] ${tool.toolName} → auto-allow`);
             return { decision: "allow" };
         }
-        log.info(`[perm] ${req.toolName}`);
-        // Custom tool handler
-        const handler = permissionHandlers.get(req.toolName);
+        log.info(`[perm] ${tool.toolName}`);
+        // Custom tool handler (Claude Code specific tools like EnterPlanMode)
+        const handler = permissionHandlers.get(tool.toolName);
         if (handler) {
-            const result = handler(req.input, req.description);
+            const result = handler(tool);
             if (result === null) {
-                log.info(`[perm] ${req.toolName} → auto-allow (handler)`);
+                log.info(`[perm] ${tool.toolName} → auto-allow (handler)`);
                 await this.channel.sendMessage(chatId, "📋 Entering plan mode");
                 return { decision: "allow" };
             }
             try {
                 const resp = await this.channel.sendInteractive(chatId, result.text, result.buttons);
-                log.info(`[perm] ${req.toolName} → ${resp.value || "timeout"}${resp.text ? ` "${resp.text}"` : ""}`);
+                log.info(`[perm] ${tool.toolName} → ${resp.value || "timeout"}${resp.text ? ` "${resp.text}"` : ""}`);
                 return result.mapResponse(resp);
             }
             catch (err) {
-                log.warn({ err }, "[perm] failed to send prompt for %s, auto-denying", req.toolName);
+                log.warn({ err }, "[perm] failed to send prompt for %s, auto-denying", tool.toolName);
                 return { decision: "deny", message: "Permission prompt could not be delivered to chat — denied automatically." };
             }
         }
         try {
-            const resp = await this.channel.sendInteractive(chatId, formatPermissionPrompt(req.toolName, req.input, req.description), [
+            const resp = await this.channel.sendInteractive(chatId, formatPermissionPrompt(tool), [
                 [{ label: "👍 Allow", value: "allow" }, { label: "👎 Deny", value: "deny" }],
                 [{ label: "📝 Deny + Note", value: "deny", requestText: true }],
             ]);
-            log.info(`[perm] ${req.toolName} → ${resp.value || "timeout"}${resp.text ? ` "${resp.text}"` : ""}`);
+            log.info(`[perm] ${tool.toolName} → ${resp.value || "timeout"}${resp.text ? ` "${resp.text}"` : ""}`);
             return { decision: resp.value === "allow" ? "allow" : "deny", message: resp.text };
         }
         catch (err) {
-            log.warn({ err }, "[perm] failed to send prompt for %s, auto-denying", req.toolName);
+            log.warn({ err }, "[perm] failed to send prompt for %s, auto-denying", tool.toolName);
             return { decision: "deny", message: "Permission prompt could not be delivered to chat — denied automatically." };
         }
     }
@@ -559,7 +624,10 @@ export class Orchestrator {
             const pct = state.stats.contextWindow > 0
                 ? Math.round((state.stats.contextUsed / state.stats.contextWindow) * 100)
                 : 0;
-            text = `🤖 ${formatModelName(state.stats.model)} ${pct}% | 🔒 ${modeLabel}`;
+            const displayName = state.stats.model
+                ? formatModelName(state.stats.model)
+                : state.engineName ?? "agent";
+            text = `🤖 ${displayName} ${pct}% | 🔒 ${modeLabel}`;
         }
         else {
             text = `🔒 ${modeLabel}`;
@@ -569,16 +637,6 @@ export class Orchestrator {
         await this.channel.updateStatus(chatId, text);
         state.lastStatusText = text;
     }
-    /** Read default workspace CLAUDE.md to append to non-default workspace sessions. */
-    readDefaultPrompt() {
-        try {
-            const content = fs.readFileSync(this.config.defaultPromptPath, "utf-8").trim();
-            return content || undefined;
-        }
-        catch {
-            return undefined;
-        }
-    }
 }
 /** Strip "claude-" prefix and date suffix from model ID. e.g. "claude-opus-4-6-20250514" → "opus-4-6" */
 function formatModelName(modelId) {

package/dist/prompt.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Assemble the system prompt from framework and user instruction files.
+ * Framework content comes first, user content appended after.
+ * Returns undefined if no content found in either directory.
+ */
+export declare function assemblePrompt(frameworkDir: string, instructionsDir: string): string | undefined;

package/dist/prompt.js

@@ -0,0 +1,35 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Read all .md files from a directory, sorted alphabetically.
+ * Returns empty array if directory doesn't exist.
+ */
+function readMarkdownFiles(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    return fs.readdirSync(dir)
+        .filter((f) => f.endsWith(".md"))
+        .sort()
+        .map((f) => fs.readFileSync(path.join(dir, f), "utf-8").trim())
+        .filter(Boolean);
+}
+/**
+ * Assemble the system prompt from framework and user instruction files.
+ * Framework content comes first, user content appended after.
+ * Returns undefined if no content found in either directory.
+ */
+export function assemblePrompt(frameworkDir, instructionsDir) {
+    const framework = readMarkdownFiles(frameworkDir);
+    const user = readMarkdownFiles(instructionsDir);
+    if (framework.length === 0 && user.length === 0)
+        return undefined;
+    const parts = [];
+    if (framework.length > 0) {
+        parts.push(framework.join("\n\n---\n\n"));
+    }
+    if (user.length > 0) {
+        parts.push(user.join("\n\n---\n\n"));
+    }
+    return parts.join("\n\n");
+}
+//# sourceMappingURL=prompt.js.map

package/dist/tool-handlers.d.ts

@@ -13,7 +13,7 @@ export interface ToolPromptResult {
     buttons: Button[][];
     mapResponse: (resp: ButtonResponse) => PermissionResponse;
 }
-export type ToolPromptHandler = (input: Record<string, unknown>, description: string) => ToolPromptResult | null;
+export type ToolPromptHandler = (input: Record<string, unknown>) => ToolPromptResult | null;
 export declare const permissionHandlers: Map<string, ToolPromptHandler>;
 /** Tools that suppress the default rolling status line in routeEngineEvent. */
 export declare const displayHandledTools: Set<string>;

package/dist/tool-handlers.js

@@ -34,8 +34,8 @@ function handleAskUserQuestion(input) {
         },
     };
 }
-function handleExitPlanMode(input, description) {
-    const text = formatExitPlanMode(input, description);
+function handleExitPlanMode(input) {
+    const text = formatExitPlanMode(input);
     return {
         text,
         buttons: [

package/dist/types.d.ts

@@ -7,9 +7,9 @@ export interface Channel {
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     ownsId(chatId: string): boolean;
-    sendMessage(chatId: string, text: string, opts?: SendMessageOpts): Promise<string[]>;
+    sendMessage(chatId: string, text: string, opts?: MessageOpts): Promise<string[]>;
     sendInteractive(chatId: string, text: string, buttons: Button[][]): Promise<ButtonResponse>;
-    editMessage(chatId: string, handle: string, text: string): Promise<void>;
+    editMessage(chatId: string, handle: string, text: string, opts?: MessageOpts): Promise<void>;
     deleteMessage(chatId: string, handle: string): Promise<void>;
     pinMessage(chatId: string, handle: string): Promise<void>;
     unpinAllMessages(chatId: string): Promise<void>;
@@ -30,11 +30,14 @@ export interface ButtonResponse {
     value: string;
     text?: string;
 }
-export interface SendMessageOpts {
+export type TextFormat = "markdown" | "plain";
+export interface MessageOpts {
     /** When false, skip consuming the typing placeholder (e.g. for tool status messages). */
     consumeTyping?: boolean;
     /** Reply/thread to a specific platform message ID (Telegram reply, Slack thread). */
     replyToMessageId?: string;
+    /** Text format hint. Defaults to "markdown". */
+    format?: TextFormat;
 }
 export interface SendFileOpts {
     caption?: string;
@@ -57,25 +60,59 @@ export interface RunTurnOpts {
     prompt: string;
     attachments?: Attachment[];
     permissionMode: PermissionMode;
-    onPermissionRequest: (req: PermissionRequest) => Promise<PermissionResponse>;
+    onPermissionRequest: (req: ToolCall) => Promise<PermissionResponse>;
     appendSystemPrompt?: string;
     mcpServers?: Record<string, McpServerConfig>;
     signal?: AbortSignal;
 }
-export interface PermissionRequest {
+interface ToolCallBase {
     toolName: string;
-    input: Record<string, unknown>;
-    description: string;
-    reason?: string;
     toolUseId: string;
 }
+declare const ACTIONS: {
+    readonly edit: "edit";
+    readonly write: "write";
+    readonly execute: "execute";
+    readonly read: "read";
+    readonly search: "search";
+    readonly fetch: "fetch";
+};
+export type KnownToolCall = (ToolCallBase & {
+    action: typeof ACTIONS.edit;
+    path: string;
+    before: string;
+    after: string;
+}) | (ToolCallBase & {
+    action: typeof ACTIONS.write;
+    path: string;
+    content: string;
+}) | (ToolCallBase & {
+    action: typeof ACTIONS.execute;
+    command: string;
+}) | (ToolCallBase & {
+    action: typeof ACTIONS.read;
+    paths: string[];
+}) | (ToolCallBase & {
+    action: typeof ACTIONS.search;
+    pattern: string;
+    paths?: string[];
+}) | (ToolCallBase & {
+    action: typeof ACTIONS.fetch;
+    url: string;
+});
+export interface UnknownToolCall extends ToolCallBase {
+    action: string;
+    [key: string]: unknown;
+}
+export type ToolCall = KnownToolCall | UnknownToolCall;
+export declare function isKnownToolCall(tool: ToolCall): tool is KnownToolCall;
 export interface PermissionResponse {
     decision: "allow" | "deny";
     message?: string;
     updatedInput?: Record<string, unknown>;
 }
 export interface TurnStats {
-    model: string;
+    model: string | null;
     contextUsed: number;
     contextWindow: number;
     toolCalls: Record<string, number>;
@@ -83,11 +120,12 @@ export interface TurnStats {
 export type EngineEvent = {
     type: "text";
     text: string;
+} | {
+    type: "text_chunk";
+    text: string;
 } | {
     type: "tool_use";
-    toolName: string;
-    input: Record<string, unknown>;
-    toolUseId: string;
+    tool: ToolCall;
 } | {
     type: "tool_result";
     toolName: string;
@@ -110,6 +148,7 @@ export interface Workspace {
     chat_id: string;
     current_session_id: string | null;
     behavior?: "assistant" | "relay";
+    engine?: string;
 }
 export interface UserInfo {
     id: string;

package/dist/types.js

@@ -1,2 +1,13 @@
-export {};
+const ACTIONS = {
+    edit: "edit",
+    write: "write",
+    execute: "execute",
+    read: "read",
+    search: "search",
+    fetch: "fetch",
+};
+const knownActions = new Set(Object.values(ACTIONS));
+export function isKnownToolCall(tool) {
+    return knownActions.has(tool.action);
+}
 //# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clearclaw",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Your coding agent, from your phone — personal assistant + project workspaces on your machine, built on the CLI's permissions, config, and memory instead of replacing them.",
   "type": "module",
   "license": "MIT",
@@ -26,7 +26,8 @@
   },
   "files": [
     "dist/**/*.js",
-    "dist/**/*.d.ts"
+    "dist/**/*.d.ts",
+    "prompts/**/*.md"
   ],
   "scripts": {
     "start": "tsx src/index.ts daemon",
@@ -36,6 +37,7 @@
     "check": "tsc --noEmit"
   },
   "dependencies": {
+    "@agentclientprotocol/sdk": "^0.16.1",
     "@anthropic-ai/claude-agent-sdk": "^0.2.89",
     "@slack/bolt": "^4.6.0",
     "diff": "^8.0.3",

package/prompts/ONBOARDING.md

@@ -0,0 +1,56 @@
+# Workspace Onboarding
+
+When a task session tells you to follow the Workspace Onboarding instructions, you're guiding an authorized user through setting up a new workspace for this chat.
+
+The task prompt tells you the chat type: DM or group. Use this to adapt the flow.
+
+## Steps
+
+### Group chats
+
+1. **Ask what they want to work on.** A specific project? A git repo? Or a general-purpose assistant chat?
+
+2. **Find the project.** If they mention a project or repo:
+   - Ask for the path, or offer to look in common locations (`~/`, `~/projects/`, `~/src/`, `~/repos/`, `~/workspaces/`, `~/workplace/`)
+   - Use `ls` or `find` to locate git repos if they're not sure where it is
+
+3. **Offer a git worktree** (if it's a git repo). Explain the benefit: an isolated copy on its own branch, so the main working tree isn't disturbed. If they want one, run `git worktree add <target_path> -b <branch_name>` from the repo. Use the worktree path as the workspace cwd.
+
+4. **Ask about the engine.** ClearClaw supports multiple AI engines. Ask which engine they want for this workspace (e.g. `claude-code`, `kiro`). Default to `claude-code` if they don't have a preference.
+
+5. **Create the workspace.** Once you have a name, path, and engine:
+   - Call `workspace_create` with a short, descriptive name, the absolute path, and the chosen engine
+   - For project repos: suggest relay behavior (default)
+   - For general-purpose chats: suggest assistant behavior
+   - Then call `task_complete` to finish setup
+
+## Guidelines
+
+- Be conversational. Don't dump all questions at once.
+- Keep workspace names short: `clearclaw`, `myapp`, `notes` — not `my-awesome-project-workspace`.
+- If the user just wants a quick assistant chat (no specific project), create a workspace pointing at the home workspace path (provided in the task prompt) with assistant behavior.
+- If something goes wrong (bad path, name conflict), explain and ask them to try again.
+
+### DM chats (home workspace)
+
+For DMs, this is the user's personal assistant setup. Create the home workspace, then run the "Get to Know You" bootstrap.
+
+1. **Create the home workspace.** Call `workspace_create` with name `default`, cwd set to the home workspace path (provided in the task prompt), and behavior `assistant`. Don't ask -- DMs are always the home workspace.
+
+2. **Get to know them.** Ask structured questions, one at a time:
+   - What should I call you?
+   - What timezone are you in?
+   - What personality/vibe do you want from me? (warm, professional, playful, direct, etc.)
+   - Would you like to name me, or should I suggest something?
+
+3. **Discover tools.** Scan PATH for common CLI tools the user might want you to use (package managers, dev tools, productivity CLIs). Present what you find: "I see you have brew, git, node installed. Any other tools you use regularly that I should know about?" Note preferred package manager and whether they want you to install tools proactively.
+
+4. **Open up.** Ask: "Anything else I should know about you, your work, or how you like to communicate?" Let the user go wherever they want. Don't constrain or redirect. If they share context that belongs in memory rather than instructions, capture it there without interrupting the conversation.
+
+5. **Write the files.** Sort everything you learned into the right place:
+   - Agent personality, voice, vibe -> `instructions/IDENTITY.md`
+   - User profile, preferences, communication style -> `instructions/USER.md`
+   - Tools, configurations, CLI preferences -> `instructions/TOOLS.md`
+   - Facts, context, decisions -> `memory/MEMORY.md`
+
+6. **Finish.** Call `task_complete`. The instruction files are now part of the assembled system prompt for all future sessions.