kindflow 0.1.0

package/sqlite-HPBUYY7A.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../database/src/drivers/sqlite.ts"],"sourcesContent":["import Database from 'better-sqlite3';\nimport type { DatabaseClient, DatabaseClientConfig, ExecuteResult } from '../client.js';\n\n/**\n * Create a SQLite database client using `better-sqlite3`.\n *\n * @param config - connection configuration (database = file path)\n * @returns a DatabaseClient backed by SQLite\n */\nexport const createSqliteClient = (config: DatabaseClientConfig): DatabaseClient => {\n  const db = new Database(config.database);\n\n  /* Enable WAL mode for better concurrent read performance. */\n  db.pragma('journal_mode = WAL');\n\n  return {\n    async query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]> {\n      const stmt = db.prepare(sql);\n      return (params ? stmt.all(...params) : stmt.all()) as T[];\n    },\n\n    async execute(sql: string, params?: unknown[]): Promise<ExecuteResult> {\n      const stmt = db.prepare(sql);\n      const result = params ? stmt.run(...params) : stmt.run();\n      return { rowsAffected: result.changes };\n    },\n\n    async transaction<T>(fn: (client: DatabaseClient) => Promise<T>): Promise<T> {\n      /**\n       * WARNING: better-sqlite3 is fully synchronous. This manual\n       * BEGIN / COMMIT / ROLLBACK wrapper exposes the transaction to\n       * async interleaving: if the callback `fn` awaits an async\n       * operation, other code on the event loop can execute SQL on\n       * this same connection between `BEGIN` and `COMMIT`, which\n       * means those statements will silently run inside this\n       * transaction. For safety, keep `fn` CPU-bound (only call\n       * the synchronous `query` / `execute` helpers provided here).\n       * If you need true async transactional safety, use the\n       * PostgreSQL driver instead.\n       */\n      /** Scoped client that blocks nested transactions. */\n      const txClient: DatabaseClient = {\n        query: this.query,\n        execute: this.execute,\n        transaction: () => { throw new Error('Nested transactions not supported'); },\n        verify: this.verify,\n        close: this.close,\n      };\n\n      db.exec('BEGIN');\n      try {\n        const result = await fn(txClient);\n        db.exec('COMMIT');\n        return result;\n      } catch (err) {\n        db.exec('ROLLBACK');\n        throw err;\n      }\n    },\n\n    async verify(): Promise<string | null> {\n      try {\n        db.prepare('SELECT 1').get();\n        return null;\n      } catch (err) {\n        return err instanceof Error ? err.message : String(err);\n      }\n    },\n\n    async close(): Promise<void> {\n      db.close();\n    },\n  };\n};\n"],"mappings":";AAAA,OAAO,cAAc;AASd,IAAM,qBAAqB,CAAC,WAAiD;AAClF,QAAM,KAAK,IAAI,SAAS,OAAO,QAAQ;AAGvC,KAAG,OAAO,oBAAoB;AAE9B,SAAO;AAAA,IACL,MAAM,MAAmC,KAAa,QAAkC;AACtF,YAAM,OAAO,GAAG,QAAQ,GAAG;AAC3B,aAAQ,SAAS,KAAK,IAAI,GAAG,MAAM,IAAI,KAAK,IAAI;AAAA,IAClD;AAAA,IAEA,MAAM,QAAQ,KAAa,QAA4C;AACrE,YAAM,OAAO,GAAG,QAAQ,GAAG;AAC3B,YAAM,SAAS,SAAS,KAAK,IAAI,GAAG,MAAM,IAAI,KAAK,IAAI;AACvD,aAAO,EAAE,cAAc,OAAO,QAAQ;AAAA,IACxC;AAAA,IAEA,MAAM,YAAe,IAAwD;AAc3E,YAAM,WAA2B;AAAA,QAC/B,OAAO,KAAK;AAAA,QACZ,SAAS,KAAK;AAAA,QACd,aAAa,MAAM;AAAE,gBAAM,IAAI,MAAM,mCAAmC;AAAA,QAAG;AAAA,QAC3E,QAAQ,KAAK;AAAA,QACb,OAAO,KAAK;AAAA,MACd;AAEA,SAAG,KAAK,OAAO;AACf,UAAI;AACF,cAAM,SAAS,MAAM,GAAG,QAAQ;AAChC,WAAG,KAAK,QAAQ;AAChB,eAAO;AAAA,MACT,SAAS,KAAK;AACZ,WAAG,KAAK,UAAU;AAClB,cAAM;AAAA,MACR;AAAA,IACF;AAAA,IAEA,MAAM,SAAiC;AACrC,UAAI;AACF,WAAG,QAAQ,UAAU,EAAE,IAAI;AAC3B,eAAO;AAAA,MACT,SAAS,KAAK;AACZ,eAAO,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAAA,MACxD;AAAA,IACF;AAAA,IAEA,MAAM,QAAuB;AAC3B,SAAG,MAAM;AAAA,IACX;AAAA,EACF;AACF;","names":[]}

package/telegram-client.js

@@ -0,0 +1,7 @@
+import {
+  createTelegramClient
+} from "./chunk-2YT53FBK.js";
+export {
+  createTelegramClient
+};
+//# sourceMappingURL=telegram-client.js.map

package/telegram-client.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/telegram-runner.js

@@ -0,0 +1,156 @@
+import {
+  createTelegramClient
+} from "./chunk-2YT53FBK.js";
+import {
+  createIpcClient,
+  createMessage
+} from "./chunk-2UX7Z5TH.js";
+
+// ../telegram-runner/src/process.ts
+var startTelegramProcess = () => {
+  const processId = process.env["KINDFLOW_PROCESS_ID"];
+  const hubId = process.env["KINDFLOW_HUB_ID"];
+  if (!processId || !hubId) {
+    console.error("[telegram-runner] Missing KINDFLOW_PROCESS_ID or KINDFLOW_HUB_ID env vars");
+    process.exit(1);
+  }
+  const clients = /* @__PURE__ */ new Map();
+  let connections = [];
+  let ipcClient = null;
+  process.on("message", async (msg) => {
+    try {
+      switch (msg.type) {
+        case "config":
+          await handleConfig(msg.config);
+          break;
+        case "telegram:update-bots":
+          await handleBotsUpdate(msg.bots);
+          break;
+        case "telegram:update-connections":
+          connections = msg.connections;
+          console.log(`[telegram-runner] Updated ${connections.length} connection(s)`);
+          break;
+        case "ping":
+          process.send?.({ type: "pong" });
+          break;
+        case "stop":
+          console.log("[telegram-runner] Received stop signal, shutting down");
+          await stopAllClients();
+          process.exit(0);
+          break;
+      }
+    } catch (err) {
+      console.error(
+        "[telegram-runner] Error handling message:",
+        err instanceof Error ? err.message : err
+      );
+      process.send?.({
+        type: "log",
+        level: "error",
+        message: `Message handler error: ${err instanceof Error ? err.message : String(err)}`
+      });
+    }
+  });
+  const handleConfig = async (config) => {
+    console.log(`[telegram-runner] Received config: ${config.name}`);
+    const rawConfig = config.config;
+    if (typeof rawConfig !== "object" || rawConfig === null || !("bots" in rawConfig) || !("connections" in rawConfig)) {
+      console.error(
+        '[telegram-runner] Malformed config: expected "bots" and "connections" properties, got:',
+        JSON.stringify(rawConfig)
+      );
+      process.exit(1);
+    }
+    const telegramConfig = rawConfig;
+    ipcClient = createIpcClient({
+      clientId: processId,
+      hubId,
+      onConnect: () => console.log("[telegram-runner] Connected to IPC hub"),
+      onDisconnect: () => console.log("[telegram-runner] Disconnected from IPC hub, will retry...")
+    });
+    await ipcClient.connect();
+    connections = telegramConfig.connections;
+    await startBotClients(telegramConfig.bots);
+    process.send?.({ type: "ready" });
+    console.log("[telegram-runner] Ready");
+  };
+  const startBotClients = async (bots) => {
+    for (const bot of bots) {
+      if (clients.has(bot.id)) continue;
+      if (!bot.verified) {
+        console.log(`[telegram-runner] Skipping unverified bot: ${bot.name}`);
+        continue;
+      }
+      const client = createTelegramClient({
+        token: bot.token,
+        polling: true
+      });
+      client.onMessage((msg) => {
+        if (!ipcClient || !msg.text) return;
+        const telegramMsg = {
+          messageId: msg.message_id,
+          chatId: msg.chat.id,
+          userId: msg.from?.id ?? 0,
+          username: msg.from?.username ?? "",
+          firstName: msg.from?.first_name ?? "",
+          text: msg.text,
+          date: msg.date,
+          chatType: msg.chat.type
+        };
+        const matching = connections.filter(
+          (c) => c.botId === bot.id && c.enabled && (c.chatId === "*" || c.chatId === String(telegramMsg.chatId))
+        );
+        for (const conn of matching) {
+          const senderLabel = telegramMsg.username ? `@${telegramMsg.username}` : telegramMsg.firstName;
+          const payload = {
+            text: `Telegram message from ${senderLabel}: ${telegramMsg.text}`,
+            metadata: {
+              source: "telegram",
+              botId: bot.id,
+              botUsername: bot.botUsername,
+              chatId: telegramMsg.chatId,
+              userId: telegramMsg.userId,
+              username: telegramMsg.username,
+              firstName: telegramMsg.firstName,
+              messageId: telegramMsg.messageId,
+              connectionId: conn.id
+            }
+          };
+          const ipcMsg = createMessage(processId, conn.targetAgent, "prompt", payload);
+          ipcClient.send(ipcMsg);
+        }
+        if (matching.length > 0) {
+          process.send?.({
+            type: "log",
+            level: "info",
+            message: `Telegram from ${telegramMsg.username || telegramMsg.firstName}: "${telegramMsg.text}" -> ${matching.length} agent(s)`
+          });
+        }
+      });
+      clients.set(bot.id, client);
+      console.log(`[telegram-runner] Starting polling for bot: ${bot.name} (@${bot.botUsername})`);
+    }
+  };
+  const handleBotsUpdate = async (bots) => {
+    const newIds = new Set(bots.map((b) => b.id));
+    for (const [id, client] of clients) {
+      if (!newIds.has(id)) {
+        await client.stop();
+        clients.delete(id);
+        console.log(`[telegram-runner] Stopped client for removed bot: ${id}`);
+      }
+    }
+    await startBotClients(bots);
+    console.log(`[telegram-runner] Updated to ${bots.length} bot(s)`);
+  };
+  const stopAllClients = async () => {
+    const stops = [...clients.values()].map((c) => c.stop());
+    await Promise.all(stops);
+    clients.clear();
+  };
+  console.log(`[telegram-runner:${processId}] Waiting for config from daemon...`);
+};
+
+// ../telegram-runner/src/entry.ts
+startTelegramProcess();
+//# sourceMappingURL=telegram-runner.js.map

package/telegram-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../telegram-runner/src/process.ts","../../telegram-runner/src/entry.ts"],"sourcesContent":["/**\n * Child process lifecycle for the Telegram runner.\n *\n * Forked by the daemon as a singleton helper (kind: \"telegram\").\n * Manages long-polling Telegram bot clients for all configured bots\n * and routes incoming messages to target agents via the IPC hub.\n *\n * Lifecycle:\n * 1. Reads KINDFLOW_PROCESS_ID and KINDFLOW_HUB_ID from env\n * 2. Waits for `config` from daemon (bots + connections)\n * 3. Connects to IPC hub\n * 4. Starts a polling TelegramClient per bot\n * 5. Sends `ready` to daemon\n * 6. Handles hot-reload messages for bots/connections\n * 7. Responds to `ping` with `pong`, `stop` with graceful shutdown\n */\n\nimport type {\n  DaemonToChild,\n  HelperConfig,\n  TelegramBotProfile,\n  TelegramConnection,\n  TelegramMessage,\n  PromptPayload,\n} from '@repo/types';\nimport { createIpcClient } from '@repo/ipc';\nimport { createMessage } from '@repo/ipc';\nimport { createTelegramClient } from '@repo/telegram';\nimport type { TelegramClient } from '@repo/telegram';\n\n/**\n * Shape of the config.config JSON blob the daemon sends to this helper.\n * Contains everything needed to start watching bots.\n */\ninterface TelegramRunnerConfig {\n  /** Telegram bots to start polling. */\n  bots: TelegramBotProfile[];\n\n  /** Bot-to-agent routing rules. */\n  connections: TelegramConnection[];\n}\n\n/**\n * Start the Telegram runner child process.\n */\nexport const startTelegramProcess = (): void => {\n  const processId = process.env['KINDFLOW_PROCESS_ID'];\n  const hubId = process.env['KINDFLOW_HUB_ID'];\n\n  if (!processId || !hubId) {\n    console.error('[telegram-runner] Missing KINDFLOW_PROCESS_ID or KINDFLOW_HUB_ID env vars');\n    process.exit(1);\n  }\n\n  const clients = new Map<string, TelegramClient>();\n  let connections: TelegramConnection[] = [];\n  let ipcClient: ReturnType<typeof createIpcClient> | null = null;\n\n  /** Listen for control plane messages from the daemon. */\n  process.on('message', async (msg: DaemonToChild) => {\n    try {\n      switch (msg.type) {\n        case 'config':\n          await handleConfig(msg.config as HelperConfig);\n          break;\n\n        case 'telegram:update-bots':\n          await handleBotsUpdate(msg.bots);\n          break;\n\n        case 'telegram:update-connections':\n          connections = msg.connections;\n          console.log(`[telegram-runner] Updated ${connections.length} connection(s)`);\n          break;\n\n        case 'ping':\n          process.send?.({ type: 'pong' });\n          break;\n\n        case 'stop':\n          console.log('[telegram-runner] Received stop signal, shutting down');\n          await stopAllClients();\n          process.exit(0);\n          break;\n      }\n    } catch (err) {\n      console.error(\n        '[telegram-runner] Error handling message:',\n        err instanceof Error ? err.message : err,\n      );\n      process.send?.({\n        type: 'log',\n        level: 'error',\n        message: `Message handler error: ${err instanceof Error ? err.message : String(err)}`,\n      });\n    }\n  });\n\n  /**\n   * Handle the initial config — connect to IPC hub and start bot clients.\n   *\n   * @param config - helper configuration from the daemon\n   */\n  const handleConfig = async (config: HelperConfig): Promise<void> => {\n    console.log(`[telegram-runner] Received config: ${config.name}`);\n\n    const rawConfig: unknown = config.config;\n\n    if (\n      typeof rawConfig !== 'object' ||\n      rawConfig === null ||\n      !('bots' in rawConfig) ||\n      !('connections' in rawConfig)\n    ) {\n      console.error(\n        '[telegram-runner] Malformed config: expected \"bots\" and \"connections\" properties, got:',\n        JSON.stringify(rawConfig),\n      );\n      process.exit(1);\n    }\n\n    const telegramConfig = rawConfig as TelegramRunnerConfig;\n\n    ipcClient = createIpcClient({\n      clientId: processId!,\n      hubId: hubId!,\n      onConnect: () => console.log('[telegram-runner] Connected to IPC hub'),\n      onDisconnect: () => console.log('[telegram-runner] Disconnected from IPC hub, will retry...'),\n    });\n\n    await ipcClient.connect();\n\n    connections = telegramConfig.connections;\n    await startBotClients(telegramConfig.bots);\n\n    process.send?.({ type: 'ready' });\n    console.log('[telegram-runner] Ready');\n  };\n\n  /**\n   * Start polling clients for a set of bots.\n   *\n   * @param bots - Telegram bot profiles to start\n   */\n  const startBotClients = async (bots: TelegramBotProfile[]): Promise<void> => {\n    for (const bot of bots) {\n      if (clients.has(bot.id)) continue;\n      if (!bot.verified) {\n        console.log(`[telegram-runner] Skipping unverified bot: ${bot.name}`);\n        continue;\n      }\n\n      const client = createTelegramClient({\n        token: bot.token,\n        polling: true,\n      });\n\n      client.onMessage((msg) => {\n        if (!ipcClient || !msg.text) return;\n\n        const telegramMsg: TelegramMessage = {\n          messageId: msg.message_id,\n          chatId: msg.chat.id,\n          userId: msg.from?.id ?? 0,\n          username: msg.from?.username ?? '',\n          firstName: msg.from?.first_name ?? '',\n          text: msg.text,\n          date: msg.date,\n          chatType: msg.chat.type,\n        };\n\n        const matching = connections.filter(\n          (c) =>\n            c.botId === bot.id &&\n            c.enabled &&\n            (c.chatId === '*' || c.chatId === String(telegramMsg.chatId)),\n        );\n\n        for (const conn of matching) {\n          const senderLabel = telegramMsg.username\n            ? `@${telegramMsg.username}`\n            : telegramMsg.firstName;\n\n          const payload: PromptPayload = {\n            text: `Telegram message from ${senderLabel}: ${telegramMsg.text}`,\n            metadata: {\n              source: 'telegram',\n              botId: bot.id,\n              botUsername: bot.botUsername,\n              chatId: telegramMsg.chatId,\n              userId: telegramMsg.userId,\n              username: telegramMsg.username,\n              firstName: telegramMsg.firstName,\n              messageId: telegramMsg.messageId,\n              connectionId: conn.id,\n            },\n          };\n\n          const ipcMsg = createMessage(processId!, conn.targetAgent, 'prompt', payload);\n          ipcClient.send(ipcMsg);\n        }\n\n        if (matching.length > 0) {\n          process.send?.({\n            type: 'log',\n            level: 'info',\n            message: `Telegram from ${telegramMsg.username || telegramMsg.firstName}: \"${telegramMsg.text}\" -> ${matching.length} agent(s)`,\n          });\n        }\n      });\n\n      clients.set(bot.id, client);\n      console.log(`[telegram-runner] Starting polling for bot: ${bot.name} (@${bot.botUsername})`);\n    }\n  };\n\n  /**\n   * Handle a bots update: stop removed bots, start new ones.\n   *\n   * @param bots - updated list of bot profiles\n   */\n  const handleBotsUpdate = async (bots: TelegramBotProfile[]): Promise<void> => {\n    const newIds = new Set(bots.map((b) => b.id));\n\n    /* Stop clients for removed bots. */\n    for (const [id, client] of clients) {\n      if (!newIds.has(id)) {\n        await client.stop();\n        clients.delete(id);\n        console.log(`[telegram-runner] Stopped client for removed bot: ${id}`);\n      }\n    }\n\n    await startBotClients(bots);\n    console.log(`[telegram-runner] Updated to ${bots.length} bot(s)`);\n  };\n\n  /**\n   * Gracefully stop all bot polling clients.\n   */\n  const stopAllClients = async (): Promise<void> => {\n    const stops = [...clients.values()].map((c) => c.stop());\n    await Promise.all(stops);\n    clients.clear();\n  };\n\n  console.log(`[telegram-runner:${processId}] Waiting for config from daemon...`);\n};\n","/**\n * Process entry point for the Telegram runner.\n * This file is invoked via `child_process.fork()` from the daemon.\n */\nimport { startTelegramProcess } from './process.js';\n\nstartTelegramProcess();\n"],"mappings":"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","names":[]}

package/templates/agent/agent/.claude/settings.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Read",
+      "Glob",
+      "Grep",
+      "Bash",
+      "Edit",
+      "Write"
+    ]
+  }
+}

package/templates/agent/agent/CLAUDE.md

@@ -0,0 +1,34 @@
+You are an agent. Describe your purpose in one sentence here.
+
+## Directory Structure
+
+```
+scripts/       — Your executable tools. You may create and edit scripts here.
+resources/     — Reference docs. Read-only — do not modify.
+data/          — Your persistent state. You may read and write here (databases, caches, files).
+.claude/       — Your settings and commands. Read-only — do not modify.
+```
+
+**You may write to:** `scripts/` and `data/` only.
+**You may read from:** everything in this directory.
+**Do not modify:** `CLAUDE.md`, `.claude/`, `resources/`. These are your source code — managed by the master agent, not by you.
+
+## Commands
+
+<!-- List your procedures here. Each is a .claude/commands/*.md file. -->
+<!-- Example: /fetch-news — find and save new articles -->
+
+## Scripts
+
+<!-- List your executable tools here. Each is a scripts/*.ts file. -->
+<!-- Scripts accept JSON via stdin and return results via stdout. -->
+<!-- Example: echo '{"url":"..."}' | bun run scripts/save-article.ts -->
+
+## Resources
+
+<!-- List reference docs you can read from resources/. -->
+<!-- Example: resources/schema.md — database table definitions -->
+
+## Important
+
+<!-- Critical rules, constraints, and things to never do. -->

package/templates/agent/agent/config.json

@@ -0,0 +1,7 @@
+{
+  "name": "",
+  "autoStart": false,
+  "model": null,
+  "permissionMode": "bypassPermissions",
+  "env": {}
+}

package/templates/agent/master/.claude/commands/build-commands.md

@@ -0,0 +1,10 @@
+# Build Commands
+
+Create command files in `../agent/.claude/commands/` for each procedure in the design.
+
+Each command should have:
+- When it runs
+- Numbered steps with data source, output, and failure path
+- Rules specific to this procedure
+
+Ask the user about each procedure's details before writing it. Update `checklist.md` when done.

package/templates/agent/master/.claude/commands/build-identity.md

@@ -0,0 +1,7 @@
+# Build Identity
+
+Using the synopsis from `checklist.md`, write `../agent/CLAUDE.md`.
+
+Keep it short — one-line identity, then lists of commands, scripts, and resources with brief descriptions. Write the Important section with hard rules.
+
+Update `checklist.md` when done.

package/templates/agent/master/.claude/commands/build-scripts.md

@@ -0,0 +1,7 @@
+# Build Scripts
+
+Create script files in `../agent/scripts/` for each tool in the design.
+
+Scripts accept JSON via stdin and return results via stdout. Ask the user about input/output shapes and external service details. Create resources in `../agent/resources/` for any API docs or schemas.
+
+Update `checklist.md` when done.

package/templates/agent/master/.claude/commands/discovery.md

@@ -0,0 +1,46 @@
+# Discovery
+
+Get the synopsis first. Let the user explain what the agent should do freely.
+
+Then identify gaps and ask follow-up questions ONE AT A TIME using AskUserQuestion. You need:
+
+- **Purpose** — what does it do?
+- **Trigger** — what starts it? Use AskUserQuestion with options like "Cron schedule", "Manual prompt", "Both"
+- **Process** — what steps does it follow?
+- **Output** — what does it produce? Use AskUserQuestion with options like "Database records", "Files", "API calls", "Notifications"
+- **Services** — what external systems? Use AskUserQuestion with options like "Database (SQLite)", "Cloud storage (S3)", "External API", "None"
+
+IMPORTANT: Every time you present choices, use the AskUserQuestion tool. Do NOT list options as text bullets.
+
+When clear, write the synopsis to `checklist.md`:
+
+```markdown
+# Agent Checklist
+
+## Synopsis
+- Purpose: ...
+- Trigger: ...
+- Process: ...
+- Output: ...
+- Services: ...
+
+## Design
+- [ ] Commands defined
+- [ ] Scripts defined
+- [ ] Resources defined
+
+## Build
+- [ ] CLAUDE.md written
+- [ ] Commands created
+- [ ] Scripts created
+- [ ] Resources created
+- [ ] config.json updated
+
+## Review
+- [ ] All files consistent
+- [ ] All commands have steps
+- [ ] All scripts have stdin/stdout pattern
+- [ ] CLAUDE.md lists everything
+```
+
+Confirm the synopsis with the user (using AskUserQuestion: "Does this look right?" with options "Yes, proceed to design" / "No, let me clarify") before moving on.

package/templates/agent/master/.claude/commands/review-agent.md

@@ -0,0 +1,57 @@
+# Phase 3: Review Agent
+
+Audit the agent's entire structure for completeness and quality.
+
+## Checklist
+
+Read all files in `../agent/` and verify:
+
+### CLAUDE.md
+- [ ] Has a clear one-line identity
+- [ ] Lists all commands with brief descriptions
+- [ ] Lists all scripts with usage examples
+- [ ] Lists all resources
+- [ ] Has an Important section with hard rules
+- [ ] States write boundaries (scripts/ and data/ only)
+
+### Commands (.claude/commands/)
+- [ ] Every workflow mentioned in CLAUDE.md has a command file
+- [ ] Each command has numbered steps
+- [ ] Each step has: data source, output, failure path
+- [ ] No vague steps like "process the data" — every step is specific
+
+### Scripts (scripts/)
+- [ ] Every external operation has a script
+- [ ] Each script has JSDoc with @example
+- [ ] Each script uses the stdin/stdout pattern
+- [ ] Each script handles errors (try/catch, error output)
+
+### Resources (resources/)
+- [ ] API docs exist for any external APIs the scripts call
+- [ ] Schemas exist for any database tables
+- [ ] Reference data exists for any categories, lists, configs
+
+### Consistency
+- [ ] Everything listed in CLAUDE.md actually exists as a file
+- [ ] No orphan files (files that exist but aren't listed in CLAUDE.md)
+- [ ] Command steps reference scripts that actually exist
+- [ ] Scripts reference resources that actually exist
+
+## After review
+
+Report your findings:
+
+> **Review complete.** Here's what I found:
+>
+> **Good:**
+> - [what's well-structured]
+>
+> **Missing:**
+> - [what's missing]
+>
+> **Issues:**
+> - [what needs fixing]
+
+Fix any issues you find. Then confirm with the user:
+
+> Everything looks good. Your agent is ready. You can start it from the Kindflow dashboard.

package/templates/agent/master/.claude/commands/setup-database.md

@@ -0,0 +1,12 @@
+# Setup Database
+
+Configure database access for this agent.
+
+1. Ask what the agent needs a database for. Use AskUserQuestion.
+2. Ask if the user has database profiles configured in Kindflow (Capabilities > Database in the web UI).
+3. If no profiles exist, help them add one via the web UI or set up their database server.
+4. Tell the user to create a **connection** in the web UI (Capabilities > Database > Add Connection) linking the database profile to this agent with a purpose description.
+5. The connection auto-generates a capability file at `../agent/capabilities/database/<connection-id>.md` with connection details and code snippets.
+6. Create scripts using `kindflow/database` for the actual operations.
+
+Read `resources/capabilities.md` for the `kindflow/database` API reference.

package/templates/agent/master/.claude/commands/setup-s3.md

@@ -0,0 +1,12 @@
+# Setup S3
+
+Configure S3 cloud storage for this agent.
+
+1. Ask what the agent needs S3 for. Use AskUserQuestion.
+2. Check if the user has S3 profiles configured in Kindflow (Capabilities > S3 in the web UI). Ask them.
+3. If no profiles exist, help them set up AWS credentials and add a profile via the web UI.
+4. Tell the user to create a **connection** in the web UI (Capabilities > S3 > Add Connection) linking the S3 profile to this agent with a purpose description.
+5. The connection auto-generates a capability file at `../agent/capabilities/s3/<connection-id>.md` with bucket details and code snippets.
+6. Create scripts using `kindflow/s3` for the actual operations.
+
+Read `resources/capabilities.md` for the S3 API reference.

package/templates/agent/master/.claude/commands/setup-telegram.md

@@ -0,0 +1,16 @@
+# Setup Telegram
+
+Configure Telegram bot messaging for this agent.
+
+1. Ask what the agent needs Telegram for (notifications, receiving commands, conversational, etc.). Use AskUserQuestion.
+2. Ask if they already have a Telegram bot configured in Kindflow (Capabilities > Telegram in the web UI). Use AskUserQuestion.
+3. If no bot exists, walk them through setup:
+   - Open Telegram and message @BotFather
+   - Send `/newbot` and follow the prompts
+   - Copy the bot token
+   - Add it via the web UI: Capabilities > Telegram > Add Bot
+4. Tell the user to create a **connection** in the web UI (Capabilities > Telegram > Add Connection) linking the bot to this agent.
+5. The connection auto-generates a capability file at `../agent/capabilities/telegram/<connection-id>.md`.
+6. If the agent needs to proactively send messages, create scripts using `kindflow/telegram`.
+
+Read `resources/capabilities.md` for the Telegram API reference.

package/templates/agent/master/.claude/settings.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "additionalDirectories": ["../agent"],
+    "allow": [
+      "Read",
+      "Glob",
+      "Grep",
+      "Edit",
+      "Write",
+      "Bash"
+    ]
+  }
+}

package/templates/agent/master/CLAUDE.md

@@ -0,0 +1,52 @@
+# Master Agent
+
+You help the user build a Kindflow agent. You drive the conversation — the user answers.
+
+Agent files go in `../agent/`. Track your progress in `checklist.md` in this directory.
+
+## Process
+
+### 1. Synopsis
+
+Understand what the user wants. Ask them to describe the agent in their own words. Listen, then ask follow-up questions ONE AT A TIME to fill gaps:
+
+- What does this agent do? (the big picture)
+- What triggers it? (cron, manual, event)
+- What does it produce? (database records, files, API calls, notifications)
+- What external services does it need? (APIs, databases, storage)
+
+When you have a clear picture, write it to `checklist.md` and confirm with the user.
+
+### 2. Design
+
+Propose the agent's structure — what commands, scripts, and resources it needs. Write the proposed design to `checklist.md`. Confirm with the user before building.
+
+### 3. Build
+
+Create all files in `../agent/`. Update `checklist.md` as you go.
+
+### 4. Review
+
+Run `/review-agent` to audit. Fix any issues. Mark checklist complete.
+
+## Rules
+
+- Start by asking what the agent should do. Don't jump to implementation details.
+- Ask ONE question at a time. Wait for the answer.
+- Be opinionated — propose concrete solutions, ask user to confirm or adjust.
+- Track everything in `checklist.md`.
+- **ALWAYS use the AskUserQuestion tool when presenting choices or asking questions.** Never list options as plain text bullets — use AskUserQuestion with proper options so the user gets the interactive selection UI. This is critical for good UX.
+- Read `resources/capabilities.md` to know what Kindflow can and can't do. If the user asks for something we don't support yet, be honest.
+
+## Agent Structure
+
+```
+../agent/
+  config.json            — Agent config (name, autoStart, etc.)
+  CLAUDE.md              — Identity + overview (short)
+  .claude/commands/*.md  — Procedures (named workflows)
+  scripts/*.ts           — Tools (stdin → stdout)
+  resources/*.md         — Reference docs (read-only for the agent)
+  data/                  — Persistent state (writable by the agent)
+  capabilities/          — Auto-generated by Kindflow when capabilities are connected via web UI
+```

package/templates/agent/master/resources/agent-structure.md

@@ -0,0 +1,24 @@
+# Agent Directory Structure
+
+An agent has these directories:
+
+```
+agent/
+  CLAUDE.md              — Identity + overview. SHORT. Lists commands, scripts, resources.
+  .claude/
+    commands/*.md        — Procedures. Named workflows triggered by situation.
+    settings.json        — Permissions, allowed tools.
+  scripts/*.ts           — Executable tools. stdin JSON in, stdout result out.
+  resources/*.md         — Reference docs. Schemas, API docs, examples.
+  data/                  — Persistent state. Databases, caches, runtime files.
+```
+
+## Rules
+
+- CLAUDE.md is the entry point. Keep it short — delegate details to commands.
+- Each distinct workflow = one command file.
+- Each external operation = one script file.
+- Scripts use `bun run` by default but can use any runtime.
+- Resources are read-only reference material the agent consults.
+- Data is the only directory the agent writes to (besides scripts).
+- The agent should NOT modify CLAUDE.md, .claude/, or resources/ at runtime.