@jx0/agency 0.2.0

package/src/cli/commands/skills.ts

@@ -0,0 +1,66 @@
+import { api } from "../lib/api.js";
+
+function parseFlag(args: string[], flag: string): string | undefined {
+  const idx = args.indexOf(flag);
+  if (idx === -1 || idx + 1 >= args.length) return undefined;
+  return args[idx + 1];
+}
+
+export default async function skills(args: string[]) {
+  const sub = args[0];
+
+  if (sub === "list" || !sub) {
+    const category = parseFlag(args, "--category");
+    const search = parseFlag(args, "--search");
+    const params = new URLSearchParams();
+    if (category) params.set("category", category);
+    if (search) params.set("search", search);
+    const qs = params.toString() ? `?${params}` : "";
+    const rows = await api(`/skills${qs}`);
+    if (rows.length === 0) {
+      console.log("No skills found.");
+    } else {
+      for (const s of rows) {
+        const tags = s.tags?.length ? ` [${s.tags.join(", ")}]` : "";
+        console.log(`  ${s.id.slice(0, 8)}  ${s.name}${tags}`);
+      }
+    }
+    return;
+  }
+
+  if (sub === "show") {
+    const id = args[1];
+    if (!id) { console.error("Usage: agency skills show <id>"); process.exit(1); }
+    const s = await api(`/skills/${id}`);
+    console.log(`Skill: ${s.name}`);
+    console.log(`  Category: ${s.category}`);
+    console.log(`  Tags: ${s.tags?.join(", ") || "none"}`);
+    console.log(`  Body:\n${s.body}`);
+    return;
+  }
+
+  if (sub === "create") {
+    const name = args[1];
+    if (!name) { console.error("Usage: agency skills create <name> [--category C]"); process.exit(1); }
+    const category = parseFlag(args, "--category");
+    const body = await Bun.stdin.text();
+    const s = await api("/skills", {
+      method: "POST",
+      body: JSON.stringify({ name, body: body || `# ${name}\n`, category }),
+    });
+    console.log(`Created skill ${s.id}: ${s.name}`);
+    return;
+  }
+
+  if (sub === "delete") {
+    const id = args[1];
+    if (!id) { console.error("Usage: agency skills delete <id>"); process.exit(1); }
+    await api(`/skills/${id}`, { method: "DELETE" });
+    console.log(`Deleted skill ${id}`);
+    return;
+  }
+
+  console.error("Unknown skills subcommand:", sub);
+  console.log("Subcommands: list, show, create, delete");
+  process.exit(1);
+}

package/src/cli/commands/ssh.ts

@@ -0,0 +1,68 @@
+import { api } from "../lib/api.js";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+
+export default async function ssh(args: string[]) {
+  const name = args[0];
+  if (!name) {
+    console.error("Usage: agency ssh <agent-name>");
+    process.exit(1);
+  }
+
+  const agent = await api(`/agents/${name}`);
+  if (!agent) {
+    console.error(`Agent "${name}" not found.`);
+    process.exit(1);
+  }
+
+  if (agent.location !== "ec2") {
+    console.error(`SSH is only supported for EC2 agents. "${name}" is ${agent.location ?? "local"}.`);
+    process.exit(1);
+  }
+
+  // Get SSH settings
+  const settings = await api("/settings?category=ssh");
+  const sshConfig: Record<string, string> = {};
+  for (const s of settings) {
+    sshConfig[s.key] = s.value;
+  }
+
+  const privateKey = sshConfig["ssh.private_key"];
+  const user = sshConfig["ssh.user"] || "ubuntu";
+
+  if (!privateKey) {
+    console.error("SSH private key not configured. Set it in Settings → SSH.");
+    process.exit(1);
+  }
+
+  // Get host from fleet.json via agent detail or settings
+  // The agent's host should be in fleet.json
+  const configRes = await api("/settings?category=aws");
+  // We need the fleet host — fetch it from the API or read fleet.json directly
+  let host = "";
+  try {
+    const fleetPath = path.resolve(process.cwd(), ".agency", "fleet.json");
+    const fleet = JSON.parse(fs.readFileSync(fleetPath, "utf-8"));
+    host = fleet.agents?.[name]?.host ?? "";
+  } catch {}
+
+  if (!host) {
+    console.error(`No host configured for "${name}". Add "host" to fleet.json for this agent.`);
+    process.exit(1);
+  }
+
+  // Write key to temp file
+  const keyDir = path.join(os.tmpdir(), "agency-ssh");
+  fs.mkdirSync(keyDir, { recursive: true, mode: 0o700 });
+  const keyPath = path.join(keyDir, "agent_key");
+  fs.writeFileSync(keyPath, privateKey + "\n", { mode: 0o600 });
+
+  // Exec ssh
+  const proc = Bun.spawn(
+    ["ssh", "-i", keyPath, "-o", "StrictHostKeyChecking=no", `${user}@${host}`, ...args.slice(1)],
+    { stdout: "inherit", stderr: "inherit", stdin: "inherit" }
+  );
+  const code = await proc.exited;
+  process.exit(code);
+}

package/src/cli/commands/start.ts

@@ -0,0 +1,14 @@
+import { api } from "../lib/api.js";
+
+export default async function start(args: string[]) {
+  const name = args[0];
+  if (!name) {
+    console.error("Usage: agency start <agent-name>");
+    process.exit(1);
+  }
+  const result = await api(`/agents/${name}/deploy`, { method: "POST" });
+  console.log(`Started ${name}: ${result.status} (${result.method})`);
+  if (result.instructions) {
+    console.log(`  ${result.instructions}`);
+  }
+}

package/src/cli/commands/status.ts

@@ -0,0 +1,33 @@
+import { api } from "../lib/api.js";
+
+export default async function status(args: string[]) {
+  const name = args[0];
+
+  if (name) {
+    const agent = await api(`/agents/${name}`);
+    console.log(`Agent: ${agent.name}`);
+    console.log(`  Role: ${agent.role ?? "n/a"}`);
+    console.log(`  Status: ${agent.status}`);
+    console.log(`  Current task: ${agent.current_task ?? "none"}`);
+    console.log(`  Updated: ${agent.updated_at}`);
+    return;
+  }
+
+  // General health check
+  try {
+    const data = await api("/health");
+    console.log(`API: ${data.status}`);
+  } catch (err: any) {
+    console.log(`API: unreachable (${err.message})`);
+    return;
+  }
+
+  const agents = await api("/agents");
+  const active = agents.filter((a: any) => a.status === "active" && a.name !== "human");
+  const total = agents.filter((a: any) => a.name !== "human");
+  console.log(`Agents: ${active.length}/${total.length} active`);
+
+  for (const a of total) {
+    console.log(`  ${a.name.padEnd(15)} ${(a.status ?? "").padEnd(10)} ${a.role ?? ""}`);
+  }
+}

package/src/cli/commands/stop.ts

@@ -0,0 +1,11 @@
+import { api } from "../lib/api.js";
+
+export default async function stop(args: string[]) {
+  const name = args[0];
+  if (!name) {
+    console.error("Usage: agency stop <agent-name>");
+    process.exit(1);
+  }
+  const result = await api(`/agents/${name}/stop`, { method: "POST" });
+  console.log(`Stopped ${name}: ${result.status}`);
+}

package/src/cli/commands/tasks.ts

@@ -0,0 +1,150 @@
+import { api } from "../lib/api.js";
+import { getConfig } from "../lib/config.js";
+
+function parseFlag(args: string[], flag: string): string | undefined {
+  const idx = args.indexOf(flag);
+  if (idx === -1 || idx + 1 >= args.length) return undefined;
+  return args[idx + 1];
+}
+
+export default async function tasks(args: string[]) {
+  const { agentName } = getConfig();
+  const sub = args[0];
+  const jsonMode = args.includes("--json");
+
+  if (sub === "create") {
+    const title = args[1];
+    if (!title) { console.error("Usage: agency tasks create <title> [flags]"); process.exit(1); }
+    const taskType = parseFlag(args, "--type") ?? "task";
+    const priority = parseFlag(args, "--priority");
+    const assign = parseFlag(args, "--assign");
+    const design = parseFlag(args, "--design");
+    const acceptance = parseFlag(args, "--acceptance");
+    const description = parseFlag(args, "--description") ?? title;
+    const from = parseFlag(args, "--from") ?? (agentName || "human");
+    const parentId = parseFlag(args, "--parent");
+
+    const task = await api("/tasks", {
+      method: "POST",
+      body: JSON.stringify({
+        title, description, from,
+        task_type: taskType,
+        priority: priority ? Number(priority) : undefined,
+        assign: assign ?? undefined,
+        design: design ?? undefined,
+        acceptance: acceptance ?? undefined,
+        parent_id: parentId ?? undefined,
+      }),
+    });
+    console.log(`Created task ${task.id}: ${task.title} [${task.status}]`);
+    return;
+  }
+
+  if (sub === "list") {
+    const status = parseFlag(args, "--status");
+    const assignee = parseFlag(args, "--assignee");
+    const type = parseFlag(args, "--type");
+    const parent = parseFlag(args, "--parent");
+    const params = new URLSearchParams();
+    if (status) params.set("status", status);
+    if (assignee) params.set("assignee", assignee);
+    if (type) params.set("type", type);
+    if (parent) params.set("parent_id", parent);
+    const qs = params.toString() ? `?${params}` : "";
+    const rows = await api(`/tasks${qs}`);
+    if (jsonMode) { console.log(JSON.stringify(rows)); return; }
+    if (rows.length === 0) {
+      console.log("No tasks found.");
+    } else {
+      for (const t of rows) {
+        console.log(`  ${t.id}  [${t.status.padEnd(10)}] P${t.priority} ${t.title}`);
+      }
+    }
+    return;
+  }
+
+  if (sub === "ready") {
+    const assignee = parseFlag(args, "--assignee") ?? agentName;
+    if (!assignee) { console.error("Provide --assignee or set AGENCY_AGENT_NAME"); process.exit(1); }
+    const rows = await api(`/tasks?status=assigned&assignee=${encodeURIComponent(assignee)}`);
+    if (jsonMode) { console.log(JSON.stringify(rows)); return; }
+    if (rows.length === 0) {
+      console.log("No ready tasks.");
+    } else {
+      for (const t of rows) {
+        console.log(`  ${t.id}  P${t.priority} ${t.title}`);
+      }
+    }
+    return;
+  }
+
+  if (sub === "show") {
+    const id = args[1];
+    if (!id) { console.error("Usage: agency tasks show <id>"); process.exit(1); }
+    const t = await api(`/tasks/${id}`);
+    if (jsonMode) { console.log(JSON.stringify(t)); return; }
+    console.log(`Task: ${t.id}`);
+    console.log(`  Title: ${t.title}`);
+    console.log(`  Status: ${t.status}`);
+    console.log(`  Priority: ${t.priority}`);
+    console.log(`  Type: ${t.task_type}`);
+    console.log(`  Description: ${t.description}`);
+    if (t.design) console.log(`  Design: ${t.design}`);
+    if (t.acceptance) console.log(`  Acceptance: ${t.acceptance}`);
+    if (t.assignees?.length) {
+      console.log(`  Assignees: ${t.assignees.map((a: any) => a.name).join(", ")}`);
+    }
+    if (t.messages?.length) {
+      console.log(`  Messages:`);
+      for (const m of t.messages) {
+        console.log(`    [${m.from_name ?? "?"}] ${m.content}`);
+      }
+    }
+    return;
+  }
+
+  if (sub === "update") {
+    const id = args[1];
+    if (!id) { console.error("Usage: agency tasks update <id> [flags]"); process.exit(1); }
+    const status = parseFlag(args, "--status");
+    const priority = parseFlag(args, "--priority");
+    const design = parseFlag(args, "--design");
+    const acceptance = parseFlag(args, "--acceptance");
+    const assign = parseFlag(args, "--assign");
+    const from = parseFlag(args, "--from") ?? (agentName || "human");
+    const body: any = { from };
+    if (status) body.status = status;
+    if (priority) body.priority = Number(priority);
+    if (design) body.design = design;
+    if (acceptance) body.acceptance = acceptance;
+
+    const t = await api(`/tasks/${id}`, { method: "PATCH", body: JSON.stringify(body) });
+
+    if (assign) {
+      await api(`/tasks/${id}/assign`, {
+        method: "POST",
+        body: JSON.stringify({ agentName: assign }),
+      });
+      console.log(`Updated task ${t.id}: [${t.status}] ${t.title} (assigned to ${assign})`);
+    } else {
+      console.log(`Updated task ${t.id}: [${t.status}] ${t.title}`);
+    }
+    return;
+  }
+
+  if (sub === "close") {
+    const id = args[1];
+    if (!id) { console.error("Usage: agency tasks close <id>"); process.exit(1); }
+    const from = agentName || "human";
+    const t = await api(`/tasks/${id}`, {
+      method: "PATCH",
+      body: JSON.stringify({ status: "done", from }),
+    });
+    console.log(`Closed task ${t.id}: ${t.title}`);
+    return;
+  }
+
+  console.error("Unknown tasks subcommand:", sub);
+  console.log("Subcommands: create, list, ready, show, update, close");
+  process.exit(1);
+}

package/src/cli/index.ts

@@ -0,0 +1,70 @@
+const args = process.argv.slice(2);
+const command = args[0];
+
+const COMMANDS: Record<string, () => Promise<any>> = {
+  init: () => import("./commands/init.js"),
+  ps: () => import("./commands/ps.js"),
+  start: () => import("./commands/start.js"),
+  stop: () => import("./commands/stop.js"),
+  logs: () => import("./commands/logs.js"),
+  ssh: () => import("./commands/ssh.js"),
+  tasks: () => import("./commands/tasks.js"),
+  msg: () => import("./commands/msg.js"),
+  learn: () => import("./commands/learn.js"),
+  recall: () => import("./commands/recall.js"),
+  doc: () => import("./commands/doc.js"),
+  daemon: () => import("./commands/daemon.js"),
+  status: () => import("./commands/status.js"),
+  config: () => import("./commands/config.js"),
+  skills: () => import("./commands/skills.js"),
+  ping: () => import("./commands/status.js"), // alias
+};
+
+async function main() {
+  if (command === "--version" || command === "-v" || command === "-V") {
+    const pkg = await import("../../package.json");
+    console.log(pkg.default?.version ?? pkg.version ?? "0.1.0");
+    process.exit(0);
+  }
+
+  if (!command || command === "--help" || command === "-h") {
+    console.log(`Agency — Multi-Agent AI Development Platform
+
+Usage: agency <command> [args]
+
+Commands:
+  init                          Set up .agency/ in current directory
+  ps                            List agents
+  start <name>                  Start an agent
+  stop <name>                   Stop an agent
+  logs <name>                   Tail agent logs
+  ssh <name>                    SSH into agent
+  tasks <subcommand>            Task management (create/list/ready/show/update/close)
+  msg <task-id> <message>       Post a task comment
+  learn <content> [--tags t,t]  Store knowledge
+  recall <search>               Search knowledge
+  doc <subcommand>              Document management
+  daemon <subcommand>           Daemon management (install/uninstall/start/stop/status/logs/run)
+  status                        Health check
+  config [key] [value]          View/edit settings
+  skills <subcommand>           Skills management (list/show/create/update/delete)`);
+    process.exit(0);
+  }
+
+  const loader = COMMANDS[command];
+  if (!loader) {
+    console.error(`Unknown command: ${command}`);
+    console.error("Run 'agency --help' for usage.");
+    process.exit(1);
+  }
+
+  const mod = await loader();
+  if (mod.default) {
+    await mod.default(args.slice(1));
+  }
+}
+
+main().catch((err) => {
+  console.error(err.message ?? err);
+  process.exit(1);
+});

package/src/cli/lib/api.ts

@@ -0,0 +1,16 @@
+import { getConfig } from "./config.js";
+
+const { apiUrl } = getConfig();
+
+export async function api(path: string, options?: RequestInit): Promise<any> {
+  const url = `${apiUrl}${path}`;
+  const res = await fetch(url, {
+    ...options,
+    headers: { "Content-Type": "application/json", ...options?.headers },
+  });
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`API error ${res.status}: ${body}`);
+  }
+  return res.json();
+}

package/src/cli/lib/config.ts

@@ -0,0 +1,5 @@
+export function getConfig() {
+  const apiUrl = process.env.AGENCY_API_URL ?? "http://localhost:3100";
+  const agentName = process.env.AGENCY_AGENT_NAME ?? "";
+  return { apiUrl, agentName };
+}

package/src/cli/lib/find-root.ts

@@ -0,0 +1,32 @@
+import * as path from "path";
+import * as fs from "fs";
+
+/**
+ * Walk up from `startDir` (default CWD) looking for `.agency/` directory.
+ * Returns the absolute path to `.agency/`, or null if not found.
+ */
+export function findAgencyRoot(startDir?: string): string | null {
+  let dir = path.resolve(startDir ?? process.cwd());
+  const root = path.parse(dir).root;
+
+  while (true) {
+    const candidate = path.join(dir, ".agency");
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
+      return candidate;
+    }
+    if (dir === root) return null;
+    dir = path.dirname(dir);
+  }
+}
+
+/**
+ * Like findAgencyRoot but throws if not found.
+ */
+export function requireAgencyRoot(startDir?: string): string {
+  const root = findAgencyRoot(startDir);
+  if (!root) {
+    console.error("No .agency/ directory found. Run `agency init` first.");
+    process.exit(1);
+  }
+  return root;
+}

package/src/cli/lib/prompt.ts

@@ -0,0 +1,20 @@
+import * as readline from "readline";
+
+export function ask(question: string, defaultValue?: string): Promise<string> {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const suffix = defaultValue ? ` (${defaultValue})` : "";
+  return new Promise((resolve) => {
+    rl.question(`${question}${suffix}: `, (answer) => {
+      rl.close();
+      resolve(answer.trim() || defaultValue || "");
+    });
+  });
+}
+
+export function confirm(question: string, defaultYes = true): Promise<boolean> {
+  const hint = defaultYes ? "Y/n" : "y/N";
+  return ask(`${question} (${hint})`).then((a) => {
+    if (!a) return defaultYes;
+    return a.toLowerCase().startsWith("y");
+  });
+}

package/src/daemon.ts

@@ -0,0 +1,83 @@
+import * as path from "path";
+import { findAgencyRoot } from "./cli/lib/find-root.js";
+
+// Resolve .agency/ and set environment
+const agencyRoot = findAgencyRoot();
+if (agencyRoot) {
+  process.env.DATABASE_PATH ??= path.join(agencyRoot, "agency.db");
+  process.env.FLEET_PATH ??= path.join(agencyRoot, "fleet.json");
+}
+
+// Start API server explicitly (Bun auto-serve only works for main entry)
+console.log("[daemon] starting API server...");
+const apiModule = await import("./api/index.js");
+const server = Bun.serve({
+  port: apiModule.default.port,
+  hostname: apiModule.default.hostname,
+  fetch: apiModule.default.fetch,
+});
+console.log(`[daemon] API listening on http://${server.hostname}:${server.port}`);
+
+// Run migrations on startup
+const { runMigrations } = await import("./api/db/migrate.js");
+await runMigrations();
+
+function spawnChild(name: string, cmd: string[], cwd: string) {
+  let proc: ReturnType<typeof Bun.spawn> | null = null;
+  let stopped = false;
+
+  function start() {
+    console.log(`[daemon] starting ${name}...`);
+    proc = Bun.spawn(cmd, {
+      cwd,
+      stdout: "inherit",
+      stderr: "inherit",
+      env: { ...process.env },
+    });
+    console.log(`[daemon] ${name} pid=${proc.pid}`);
+
+    proc.exited.then((code) => {
+      if (stopped) return;
+      console.error(`[daemon] ${name} exited with code ${code}, restarting in 1s...`);
+      setTimeout(start, 1000);
+    });
+  }
+
+  start();
+
+  return {
+    kill() {
+      stopped = true;
+      proc?.kill();
+    },
+  };
+}
+
+const children: { kill(): void }[] = [];
+
+// Dashboard is now served as static files from the API process — no child needed.
+
+// Only spawn notify if it exists
+const notifyEntry = path.resolve(import.meta.dir, "../packages/notify/src/index.ts");
+if (await Bun.file(notifyEntry).exists()) {
+  children.push(
+    spawnChild(
+      "notify",
+      ["bun", "run", "src/index.ts"],
+      path.resolve(import.meta.dir, "../packages/notify")
+    )
+  );
+}
+
+async function shutdown() {
+  console.log("[daemon] shutting down...");
+  const { stopAllTunnels } = await import("./api/lib/tunnels.js");
+  stopAllTunnels();
+  for (const child of children) {
+    child.kill();
+  }
+  process.exit(0);
+}
+
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);

package/src/templates/implementer/agents-config.md

@@ -0,0 +1,44 @@
+# Implementer Configuration
+
+## Communication
+
+- Minimal communication. Silence is competence.
+- Speak up when blocked, confused, or need a decision.
+- Use task comments for all communication.
+
+## Task Lifecycle
+
+1. **Assigned** — Read task, understand requirements
+2. **In Progress** — Do the work
+3. **Needs Input** — Blocked, waiting for guidance (include clear question)
+4. **Review** — Work complete, ready for review
+5. **Done** — Accepted by orchestrator
+
+## Asking for Help
+
+Good: "I found X and Y approaches. X is simpler but Y handles edge case Z. Which should I use?"
+Bad: "What should I do?"
+
+Always include:
+- What you've tried
+- What options you see
+- Your recommendation
+
+## Knowledge Base
+
+- Before starting work: `agency recall <topic>` to check for prior decisions
+- After learning something: `agency learn "<what you learned>" --tags tag1,tag2`
+
+## Testing
+
+- Run tests before marking task as review
+- Verify changes locally
+- Don't push broken code
+
+## Rules
+
+1. One active task at a time
+2. Always test before completing
+3. Capture decisions in task comments
+4. Don't duplicate work — check if it's already been done
+5. Ask for help rather than guessing on important decisions

package/src/templates/implementer/agents.md

@@ -0,0 +1,32 @@
+# Implementer Role
+
+You are an implementer — you execute work assigned by the orchestrator.
+
+## Session Startup
+
+1. Read SOUL.md, USER.md, MEMORY.md
+2. `agency recall "recent decisions"`
+3. Run your heartbeat checklist
+
+## Role Definition
+
+- **Execute work** — Pick up assigned tasks and complete them
+- **Don't investigate** — If the task is unclear, ask for clarification
+- **Don't delegate** — You do the work yourself
+- **Report back** — Update task status and comment with results
+
+## Rules
+
+1. Always use proper development tools and workflows
+2. Run tests before marking work complete
+3. Verify changes locally before pushing
+4. Capture decisions in task comments
+5. Don't duplicate work — check first
+
+## Communication
+
+All communication goes through task comments (`agency msg`).
+
+## Workflow
+
+Follow HEARTBEAT.md on every cycle.