Multi-Agent Collaboration for Team and Friends
TypeScript agent-automationagent-orchestrationagent-workflowai-agentsai-collaborationai-memoryai-workforceautonomous-agentsclaude-codeclaude-code-skillscodexcoding-agentmulti-agentmultiple-agentone-person-businessone-person-companyone-person-teamopencodesolopreneur
feat: use unified agents.md
Gus6bf23b7105fc
diff --git a/src/cli/daemon/daemon.ts b/src/cli/daemon/daemon.tsindex 8adbcda92..5732c8d8e 100644--- a/src/cli/daemon/daemon.ts+++ b/src/cli/daemon/daemon.ts@@ -234,7 +234,6 @@ async function runTask(const { workDir, logFile, timelineDir, env } = prepare({ workspacesRoot: config.workspacesRoot },task,- provider,);const session = backend.execute(prompt, {diff --git a/src/cli/daemon/execenv/__tests__/context.test.ts b/src/cli/daemon/execenv/__tests__/context.test.tsindex 0f2c02624..65bd1771b 100644--- a/src/cli/daemon/execenv/__tests__/context.test.ts+++ b/src/cli/daemon/execenv/__tests__/context.test.ts@@ -1,8 +1,25 @@-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";-import { mkdirSync, writeFileSync, readFileSync, unlinkSync, existsSync, rmSync } from "fs";+import { describe, it, expect, beforeEach, afterEach } from "vitest";+import {+ mkdirSync,+ writeFileSync,+ readFileSync,+ existsSync,+ rmSync,+ lstatSync,+ readlinkSync,+ symlinkSync,+} from "fs";import { join } from "path";import { tmpdir } from "os";-import { buildInstructionContent, writeInstructionFile, cleanStaleProviderFiles } from "../context.js";+import {+ buildInstructionContent,+ contentHash,+ hasContentChanged,+ ensureSymlinks,+ writeInstructionFileIfChanged,+ CANONICAL_FILE,+ SYMLINK_ALIASES,+} from "../context.js";import type { Task } from "../../types.js";function makeTask(overrides: Partial<Task> = {}): Task {@@ -22,31 +39,29 @@ function makeTask(overrides: Partial<Task> = {}): Task {}describe("buildInstructionContent", () => {- it("assembles system section + agent instructions section", () => {+ it("assembles header + agent instructions + context timeline", () => {const task = makeTask();const content = buildInstructionContent(task);- expect(content).toContain("# Alook Agent Instructions");- expect(content).toContain("## System");- expect(content).toContain("SYSPROMPT TODO FOR ALOOK");+ expect(content).toContain("# Alook Agent");expect(content).toContain("## Agent Instructions");expect(content).toContain("Be helpful and concise.");+ expect(content).toContain("## Context Timeline");});- it("with task.agent undefined — omits agent instructions section, keeps system section", () => {+ it("with task.agent undefined — omits agent instructions section", () => {const task = makeTask({ agent: undefined });const content = buildInstructionContent(task);- expect(content).toContain("## System");- expect(content).toContain("SYSPROMPT TODO FOR ALOOK");+ expect(content).toContain("# Alook Agent");expect(content).not.toContain("## Agent Instructions");});- it("with empty instructions string — omits agent instructions section, keeps system section", () => {+ it("with empty instructions string — omits agent instructions section", () => {const task = makeTask({ agent: { name: "test", instructions: "" } });const content = buildInstructionContent(task);- expect(content).toContain("## System");+ expect(content).toContain("# Alook Agent");expect(content).not.toContain("## Agent Instructions");});@@ -69,7 +84,22 @@ describe("buildInstructionContent", () => {});});-describe("writeInstructionFile", () => {+describe("contentHash", () => {+ it("returns consistent hex string for same input", () => {+ const h1 = contentHash("hello world");+ const h2 = contentHash("hello world");+ expect(h1).toBe(h2);+ expect(h1).toMatch(/^[0-9a-f]{64}$/);+ });++ it("returns different hex strings for different inputs", () => {+ const h1 = contentHash("hello");+ const h2 = contentHash("world");+ expect(h1).not.toBe(h2);+ });+});++describe("hasContentChanged", () => {let workDir: string;beforeEach(() => {@@ -81,47 +111,87 @@ describe("writeInstructionFile", () => {rmSync(workDir, { recursive: true, force: true });});- it("for Claude — writes CLAUDE.md with assembled content", () => {- const task = makeTask();- writeInstructionFile(workDir, task, "claude");+ it("returns true when file does not exist", () => {+ expect(hasContentChanged(join(workDir, "missing.md"), "content")).toBe(true);+ });- const content = readFileSync(join(workDir, "CLAUDE.md"), "utf-8");- expect(content).toContain("# Alook Agent Instructions");- expect(content).toContain("Be helpful and concise.");+ it("returns false when file exists with identical content", () => {+ const filePath = join(workDir, "test.md");+ writeFileSync(filePath, "same content", "utf-8");+ expect(hasContentChanged(filePath, "same content")).toBe(false);});- it("for OpenCode — writes AGENTS.md with assembled content", () => {- const task = makeTask();- writeInstructionFile(workDir, task, "opencode");+ it("returns true when file exists with different content", () => {+ const filePath = join(workDir, "test.md");+ writeFileSync(filePath, "old content", "utf-8");+ expect(hasContentChanged(filePath, "new content")).toBe(true);+ });+});- const content = readFileSync(join(workDir, "AGENTS.md"), "utf-8");- expect(content).toContain("# Alook Agent Instructions");- expect(content).toContain("Be helpful and concise.");+describe("ensureSymlinks", () => {+ let workDir: string;++ beforeEach(() => {+ workDir = join(tmpdir(), `execenv-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);+ mkdirSync(workDir, { recursive: true });});- it("for Codex — writes AGENTS.md with assembled content", () => {- const task = makeTask();- writeInstructionFile(workDir, task, "codex");+ afterEach(() => {+ rmSync(workDir, { recursive: true, force: true });+ });- const content = readFileSync(join(workDir, "AGENTS.md"), "utf-8");- expect(content).toContain("# Alook Agent Instructions");- expect(content).toContain("Be helpful and concise.");+ it("creates CLAUDE.md symlink pointing to AGENTS.md", () => {+ writeFileSync(join(workDir, CANONICAL_FILE), "content", "utf-8");+ ensureSymlinks(workDir);++ const aliasPath = join(workDir, "CLAUDE.md");+ expect(lstatSync(aliasPath).isSymbolicLink()).toBe(true);+ expect(readlinkSync(aliasPath)).toBe(CANONICAL_FILE);+ });++ it("does not create symlink when canonical file doesn't exist", () => {+ ensureSymlinks(workDir);++ expect(existsSync(join(workDir, "CLAUDE.md"))).toBe(false);});- it("overwrites existing file on re-run with new instructions", () => {- const task1 = makeTask({ agent: { name: "a", instructions: "Old instructions" } });- writeInstructionFile(workDir, task1, "claude");+ it("replaces a regular file at alias path with a symlink", () => {+ writeFileSync(join(workDir, CANONICAL_FILE), "content", "utf-8");+ writeFileSync(join(workDir, "CLAUDE.md"), "old regular file", "utf-8");- const task2 = makeTask({ agent: { name: "a", instructions: "New instructions" } });- writeInstructionFile(workDir, task2, "claude");+ ensureSymlinks(workDir);- const content = readFileSync(join(workDir, "CLAUDE.md"), "utf-8");- expect(content).toContain("New instructions");- expect(content).not.toContain("Old instructions");+ const aliasPath = join(workDir, "CLAUDE.md");+ expect(lstatSync(aliasPath).isSymbolicLink()).toBe(true);+ expect(readlinkSync(aliasPath)).toBe(CANONICAL_FILE);+ });++ it("replaces a symlink pointing to wrong target", () => {+ writeFileSync(join(workDir, CANONICAL_FILE), "content", "utf-8");+ writeFileSync(join(workDir, "WRONG.md"), "wrong", "utf-8");+ symlinkSync("WRONG.md", join(workDir, "CLAUDE.md"));++ ensureSymlinks(workDir);++ const aliasPath = join(workDir, "CLAUDE.md");+ expect(lstatSync(aliasPath).isSymbolicLink()).toBe(true);+ expect(readlinkSync(aliasPath)).toBe(CANONICAL_FILE);+ });++ it("is no-op when correct symlink already exists", () => {+ writeFileSync(join(workDir, CANONICAL_FILE), "content", "utf-8");+ symlinkSync(CANONICAL_FILE, join(workDir, "CLAUDE.md"));++ // Should not throw+ ensureSymlinks(workDir);++ const aliasPath = join(workDir, "CLAUDE.md");+ expect(lstatSync(aliasPath).isSymbolicLink()).toBe(true);+ expect(readlinkSync(aliasPath)).toBe(CANONICAL_FILE);});});-describe("cleanStaleProviderFiles", () => {+describe("writeInstructionFileIfChanged", () => {let workDir: string;beforeEach(() => {@@ -133,28 +203,64 @@ describe("cleanStaleProviderFiles", () => {rmSync(workDir, { recursive: true, force: true });});- it("for Claude — removes AGENTS.md if present", () => {- writeFileSync(join(workDir, "AGENTS.md"), "old");- cleanStaleProviderFiles(workDir, "claude");+ it("writes AGENTS.md on first call (no prior file), returns true", () => {+ const task = makeTask();+ const result = writeInstructionFileIfChanged(workDir, task);++ expect(result).toBe(true);+ expect(existsSync(join(workDir, CANONICAL_FILE))).toBe(true);+ const content = readFileSync(join(workDir, CANONICAL_FILE), "utf-8");+ expect(content).toContain("# Alook Agent");+ expect(content).toContain("Be helpful and concise.");+ });++ it("creates CLAUDE.md symlink on first call", () => {+ const task = makeTask();+ writeInstructionFileIfChanged(workDir, task);- expect(existsSync(join(workDir, "AGENTS.md"))).toBe(false);+ const aliasPath = join(workDir, "CLAUDE.md");+ expect(lstatSync(aliasPath).isSymbolicLink()).toBe(true);+ expect(readlinkSync(aliasPath)).toBe(CANONICAL_FILE);});- it("for OpenCode — removes CLAUDE.md if present", () => {- writeFileSync(join(workDir, "CLAUDE.md"), "old");- cleanStaleProviderFiles(workDir, "opencode");+ it("returns false on second call with same task (no write)", () => {+ const task = makeTask();+ writeInstructionFileIfChanged(workDir, task);+ const result = writeInstructionFileIfChanged(workDir, task);- expect(existsSync(join(workDir, "CLAUDE.md"))).toBe(false);+ expect(result).toBe(false);});- it("for Codex — removes CLAUDE.md if present", () => {- writeFileSync(join(workDir, "CLAUDE.md"), "old");- cleanStaleProviderFiles(workDir, "codex");+ it("returns true when instructions change between calls", () => {+ const task1 = makeTask({ agent: { name: "a", instructions: "Old" } });+ writeInstructionFileIfChanged(workDir, task1);- expect(existsSync(join(workDir, "CLAUDE.md"))).toBe(false);+ const task2 = makeTask({ agent: { name: "a", instructions: "New" } });+ const result = writeInstructionFileIfChanged(workDir, task2);++ expect(result).toBe(true);+ const content = readFileSync(join(workDir, CANONICAL_FILE), "utf-8");+ expect(content).toContain("New");+ expect(content).not.toContain("Old");});- it("does not throw when file does not exist", () => {- expect(() => cleanStaleProviderFiles(workDir, "claude")).not.toThrow();+ it("preserves symlinks on subsequent no-change calls", () => {+ const task = makeTask();+ writeInstructionFileIfChanged(workDir, task);+ writeInstructionFileIfChanged(workDir, task);++ const aliasPath = join(workDir, "CLAUDE.md");+ expect(lstatSync(aliasPath).isSymbolicLink()).toBe(true);+ expect(readlinkSync(aliasPath)).toBe(CANONICAL_FILE);+ });++ it("replaces a stale regular CLAUDE.md file with a symlink", () => {+ writeFileSync(join(workDir, "CLAUDE.md"), "stale regular file", "utf-8");+ const task = makeTask();+ writeInstructionFileIfChanged(workDir, task);++ const aliasPath = join(workDir, "CLAUDE.md");+ expect(lstatSync(aliasPath).isSymbolicLink()).toBe(true);+ expect(readlinkSync(aliasPath)).toBe(CANONICAL_FILE);});});diff --git a/src/cli/daemon/execenv/__tests__/index.test.ts b/src/cli/daemon/execenv/__tests__/index.test.tsindex bc981fe74..b00f49fdd 100644--- a/src/cli/daemon/execenv/__tests__/index.test.ts+++ b/src/cli/daemon/execenv/__tests__/index.test.ts@@ -1,8 +1,9 @@import { describe, it, expect, beforeEach, afterEach } from "vitest";-import { mkdirSync, existsSync, readFileSync, rmSync } from "fs";+import { mkdirSync, existsSync, readFileSync, rmSync, lstatSync, readlinkSync, statSync } from "fs";import { join } from "path";import { tmpdir } from "os";import { prepare } from "../index.js";+import { CANONICAL_FILE } from "../context.js";import type { Task } from "../../types.js";function makeTask(overrides: Partial<Task> = {}): Task {@@ -35,40 +36,60 @@ describe("prepare", () => {it("creates workdir directory", () => {const task = makeTask();- const result = prepare({ workspacesRoot: root }, task, "claude");+ const result = prepare({ workspacesRoot: root }, task);expect(existsSync(result.workDir)).toBe(true);});it("always constructs {root}/{wsId}/{agentId}/workdir", () => {const task = makeTask();- const result = prepare({ workspacesRoot: root }, task, "claude");+ const result = prepare({ workspacesRoot: root }, task);expect(result.workDir).toBe(join(root, "ws1", "a1", "workdir"));});- it("on existing workdir overwrites instruction file with fresh data", () => {- const task1 = makeTask({ agent: { name: "a", instructions: "Old" } });- prepare({ workspacesRoot: root }, task1, "claude");+ it("creates AGENTS.md and CLAUDE.md symlink", () => {+ const task = makeTask();+ const result = prepare({ workspacesRoot: root }, task);++ const agentsPath = join(result.workDir, CANONICAL_FILE);+ expect(existsSync(agentsPath)).toBe(true);+ const content = readFileSync(agentsPath, "utf-8");+ expect(content).toContain("# Alook Agent");+ expect(content).toContain("Be helpful.");++ const claudePath = join(result.workDir, "CLAUDE.md");+ expect(lstatSync(claudePath).isSymbolicLink()).toBe(true);+ expect(readlinkSync(claudePath)).toBe(CANONICAL_FILE);+ });++ it("called twice with same content — AGENTS.md mtime unchanged", () => {+ const task = makeTask();+ const result = prepare({ workspacesRoot: root }, task);++ const agentsPath = join(result.workDir, CANONICAL_FILE);+ const mtime1 = statSync(agentsPath).mtimeMs;++ // Small delay to ensure mtime would differ if file were rewritten+ const start = Date.now();+ while (Date.now() - start < 50) { /* busy wait */ }- const task2 = makeTask({ agent: { name: "a", instructions: "New" } });- const result = prepare({ workspacesRoot: root }, task2, "claude");+ prepare({ workspacesRoot: root }, task);+ const mtime2 = statSync(agentsPath).mtimeMs;- const content = readFileSync(join(result.workDir, "CLAUDE.md"), "utf-8");- expect(content).toContain("New");- expect(content).not.toContain("Old");+ expect(mtime2).toBe(mtime1);});it("returns logFile path at {root}/{wsId}/{agentId}/agent.log", () => {const task = makeTask();- const result = prepare({ workspacesRoot: root }, task, "claude");+ const result = prepare({ workspacesRoot: root }, task);expect(result.logFile).toBe(join(root, "ws1", "a1", "agent.log"));});it("creates .context_timeline/ directory inside workdir", () => {const task = makeTask();- const result = prepare({ workspacesRoot: root }, task, "claude");+ const result = prepare({ workspacesRoot: root }, task);const timelineDir = join(result.workDir, ".context_timeline");expect(existsSync(timelineDir)).toBe(true);@@ -76,14 +97,14 @@ describe("prepare", () => {it("returns timelineDir in result", () => {const task = makeTask();- const result = prepare({ workspacesRoot: root }, task, "claude");+ const result = prepare({ workspacesRoot: root }, task);expect(result.timelineDir).toBe(join(result.workDir, ".context_timeline"));});it("returns env with all expected keys", () => {const task = makeTask();- const result = prepare({ workspacesRoot: root }, task, "claude");+ const result = prepare({ workspacesRoot: root }, task);expect(result.env).toEqual({ALOOK_WORKSPACE_ID: "ws1",diff --git a/src/cli/daemon/execenv/context.ts b/src/cli/daemon/execenv/context.tsindex ddd0fc06c..55993d417 100644--- a/src/cli/daemon/execenv/context.ts+++ b/src/cli/daemon/execenv/context.ts@@ -1,76 +1,127 @@-import { writeFileSync, unlinkSync } from "fs";+import { createHash } from "crypto";+import {+ writeFileSync,+ readFileSync,+ lstatSync,+ symlinkSync,+ unlinkSync,+ existsSync,+ readlinkSync,+} from "fs";import { join } from "path";import type { Task } from "../types.js";-const INSTRUCTION_FILES = {- claude: "CLAUDE.md",- opencode: "AGENTS.md",- codex: "AGENTS.md",-} as const;+export const CANONICAL_FILE = "AGENTS.md";+export const SYMLINK_ALIASES = ["CLAUDE.md"];-export function buildInstructionContent(task: Task): string {- let content = `# Alook Agent Instructions+const SYSTEM_PROMPT = `+## Memory Management+- Your memory directory is ./, don't write any external memory file+- Write ESSENTIAL yet SHORT memory to ./memory.md+- For SPECIFIC yet LONG rules or pattern, write to experiences/[NAME].md, and add index to ./memory.md for later recall.+### whats is ESSENTIAL and SHORT Memory?+- basic user profile, e.g.:+ - "user name is gus"+ - "user is working on alook"+- certain local project mapping, e.g.:+ - "alook means the project under /user/home/alook/"+- when to read certain stuff, e.g.:+ - "read ./experiences/alook_dev_workflow.md when start a new pr in alook"+Essential means you think you generally need to read it every time, short means a short sentence can describe this memory+### whats is SPECIFIC and LONG Memory?+- specific workflow that trigger at certain cases, e.g.:+ - user ask your to summarize the before workflow with certain skills usage as the common workflow when write a new slide about agent. Write it to experiences/slide-for-agent.md.+SPECIFIC means you think you just need to use it conditionally, long means you need to detailed, more than 140 chars text to describe it.++## Context Timeline+You're a working branch of a powerful personal agent in Alook platform.+Your current context is only a fraction of the full picture, the full picture is inside .context_timeline/YYYY-MM-DD.jsonl+Each line is a JSON object with these fields:+- "task_id" — unique task identifier+- "session_id" — agent session identifier (null until completion)+- "pid" — daemon process ID (present while running, null when done)+- "status" — "running", "completed", or "failed"+- "datetime" — when the task started (local timezone)+- "type" — always "user_dm_message"+- "prompt" — what the user asked+- "steps" — assistant text outputs during execution+- "response" — final response (null if running or failed)+- "errmsg" — error message (null unless status is "failed")-## System-SYSPROMPT TODO FOR ALOOK`;+## RULES+- Read @memory.md(if exists) before your action.+- When you start a new task, read the last ~20 lines of today's timeline to understand what has been asked and done recently.+ - if you don't know the current datetime, obtain the current datetime first.+- You may also check the historical timeline when user ask you to recall+`;++export function buildInstructionContent(task: Task): string {+ let content = SYSTEM_PROMPT;if (task.agent?.instructions) {- content += `+ content += `\n\n## Agent Instructions\n${task.agent.instructions}`;+ }-## Agent Instructions-${task.agent.instructions}`;+ return content;+}++export function contentHash(content: string): string {+ return createHash("sha256").update(content, "utf-8").digest("hex");+}++export function hasContentChanged(+ filePath: string,+ newContent: string,+): boolean {+ try {+ const existing = readFileSync(filePath, "utf-8");+ return contentHash(existing) !== contentHash(newContent);+ } catch (err: unknown) {+ if ((err as NodeJS.ErrnoException)?.code === "ENOENT") return true;+ throw err;}+}- content += `+export function ensureSymlinks(workDir: string): void {+ const canonicalPath = join(workDir, CANONICAL_FILE);+ if (!existsSync(canonicalPath)) return;-## Context Timeline+ for (const alias of SYMLINK_ALIASES) {+ if (alias === CANONICAL_FILE) continue;-Your conversation history is stored in \`.context_timeline/YYYY-MM-DD.jsonl\` (today's date).-Each line is a JSON object with these fields:+ const aliasPath = join(workDir, alias);-- \`task_id\` — unique task identifier-- \`session_id\` — agent session identifier (null until completion)-- \`pid\` — daemon process ID (present while running, null when done)-- \`status\` — "running", "completed", or "failed"-- \`datetime\` — when the task started (local timezone)-- \`type\` — always "user_dm_message"-- \`prompt\` — what the user asked-- \`steps\` — assistant text outputs during execution-- \`response\` — final response (null if running or failed)-- \`errmsg\` — error message (null unless status is "failed")--When you start a new task, read the last ~20 lines of today's file to understand-what has been asked and done recently. You may also check yesterday's file if-today's is empty or very short.`;+ try {+ const stat = lstatSync(aliasPath);+ if (stat.isSymbolicLink()) {+ const target = readlinkSync(aliasPath);+ if (target === CANONICAL_FILE) continue; // already correct+ unlinkSync(aliasPath);+ } else {+ // regular file — remove it+ unlinkSync(aliasPath);+ }+ } catch (err: unknown) {+ if ((err as NodeJS.ErrnoException)?.code !== "ENOENT") throw err;+ // doesn't exist — will create below+ }- return content;+ symlinkSync(CANONICAL_FILE, aliasPath);+ }}-export function writeInstructionFile(+export function writeInstructionFileIfChanged(workDir: string,task: Task,- provider: string,-): void {- const fileName = INSTRUCTION_FILES[provider as keyof typeof INSTRUCTION_FILES];- if (!fileName) return;-+): boolean {const content = buildInstructionContent(task);- writeFileSync(join(workDir, fileName), content, "utf-8");-}--export function cleanStaleProviderFiles(- workDir: string,- provider: string,-): void {- if (!(provider in INSTRUCTION_FILES)) return;+ const filePath = join(workDir, CANONICAL_FILE);- try {- if (provider === "claude") {- unlinkSync(join(workDir, "AGENTS.md"));- } else {- unlinkSync(join(workDir, "CLAUDE.md"));- }- } catch (err: unknown) {- if ((err as NodeJS.ErrnoException)?.code !== "ENOENT") throw err;+ const changed = hasContentChanged(filePath, content);+ if (changed) {+ writeFileSync(filePath, content, "utf-8");}++ ensureSymlinks(workDir);+ return changed;}diff --git a/src/cli/daemon/execenv/index.ts b/src/cli/daemon/execenv/index.tsindex b6c9697c0..08d93e96c 100644--- a/src/cli/daemon/execenv/index.ts+++ b/src/cli/daemon/execenv/index.ts@@ -1,6 +1,6 @@import { mkdirSync } from "fs";import { join, dirname } from "path";-import { writeInstructionFile, cleanStaleProviderFiles } from "./context.js";+import { writeInstructionFileIfChanged } from "./context.js";import type { Task } from "../types.js";export interface ExecEnvConfig {@@ -17,7 +17,6 @@ export interface ExecEnvResult {export function prepare(config: ExecEnvConfig,task: Task,- provider: string,): ExecEnvResult {const workDir = join(config.workspacesRoot, task.workspaceId, task.agentId, "workdir");@@ -26,8 +25,7 @@ export function prepare(const timelineDir = join(workDir, ".context_timeline");mkdirSync(timelineDir, { recursive: true });- writeInstructionFile(workDir, task, provider);- cleanStaleProviderFiles(workDir, provider);+ writeInstructionFileIfChanged(workDir, task);const logFile = join(config.workspacesRoot,@@ -48,4 +46,4 @@ export function prepare(return { workDir, logFile, timelineDir, env };}-export { buildInstructionContent, writeInstructionFile, cleanStaleProviderFiles } from "./context.js";+export { buildInstructionContent, writeInstructionFileIfChanged, ensureSymlinks, CANONICAL_FILE } from "./context.js";