@cleocode/cleo 2026.4.18 → 2026.4.19

package/dist/cli/index.js

@@ -11114,13 +11114,54 @@ function reconcileJournal(nativeDb, migrationsFolder, existenceTable, logSubsyst
       }
     }
   }
+  if (tableExists(nativeDb, "__drizzle_migrations") && tableExists(nativeDb, existenceTable)) {
+    const localMigrations = readMigrationFiles({ migrationsFolder });
+    const journalEntries = nativeDb.prepare('SELECT hash FROM "__drizzle_migrations"').all();
+    const journaledHashes = new Set(journalEntries.map((e) => e.hash));
+    for (const migration of localMigrations) {
+      if (journaledHashes.has(migration.hash)) continue;
+      const alterColumnRegex = /ALTER\s+TABLE\s+[`"]?(\w+)[`"]?\s+ADD\s+COLUMN\s+[`"]?(\w+)[`"]?/gi;
+      const alterMatches = [];
+      const sqlStatements = Array.isArray(migration.sql) ? migration.sql : [migration.sql ?? ""];
+      const fullSql = sqlStatements.join("\n");
+      for (const m2 of fullSql.matchAll(alterColumnRegex)) {
+        alterMatches.push({ table: m2[1], column: m2[2] });
+      }
+      if (alterMatches.length === 0) continue;
+      const allColumnsExist = alterMatches.every(({ table, column }) => {
+        if (!tableExists(nativeDb, table)) return false;
+        const cols = nativeDb.prepare(`PRAGMA table_info(${table})`).all();
+        return cols.some((c) => c.name === column);
+      });
+      if (allColumnsExist) {
+        const log11 = getLogger(logSubsystem);
+        log11.warn(
+          { migration: migration.name, columns: alterMatches },
+          `Detected partially-applied migration ${migration.name} \u2014 columns exist but journal entry missing. Auto-reconciling.`
+        );
+        nativeDb.exec(
+          `INSERT INTO "__drizzle_migrations" ("hash", "created_at") VALUES ('${migration.hash}', ${migration.folderMillis})`
+        );
+      }
+    }
+  }
+}
+function isDuplicateColumnError(err) {
+  if (!(err instanceof Error)) return false;
+  return /duplicate column name/i.test(err.message);
 }
-function migrateWithRetry(db, migrationsFolder) {
+function migrateWithRetry(db, migrationsFolder, nativeDb, existenceTable, logSubsystem) {
+  let duplicateColumnReconciled = false;
   for (let attempt = 1; attempt <= MAX_MIGRATION_RETRIES; attempt++) {
     try {
       migrate(db, { migrationsFolder });
       return;
     } catch (err) {
+      if (isDuplicateColumnError(err) && !duplicateColumnReconciled && nativeDb !== void 0 && existenceTable !== void 0 && logSubsystem !== void 0) {
+        duplicateColumnReconciled = true;
+        reconcileJournal(nativeDb, migrationsFolder, existenceTable, logSubsystem);
+        continue;
+      }
       if (!isSqliteBusy(err) || attempt === MAX_MIGRATION_RETRIES) {
         throw err;
       }
@@ -13478,7 +13519,7 @@ function runMigrations(nativeDb, db) {
   }
   reconcileJournal(nativeDb, migrationsFolder, "tasks", "sqlite");
   ensureColumns(nativeDb, "sessions", REQUIRED_SESSION_COLUMNS, "sqlite");
-  migrateWithRetry(db, migrationsFolder);
+  migrateWithRetry(db, migrationsFolder, nativeDb, "tasks", "sqlite");
   ensureColumns(nativeDb, "tasks", REQUIRED_TASK_COLUMNS, "sqlite");
 }
 function closeDb() {
@@ -13604,7 +13645,7 @@ function runBrainMigrations(nativeDb, db) {
     createSafetyBackup(_dbPath2);
   }
   reconcileJournal(nativeDb, migrationsFolder, "brain_decisions", "brain");
-  migrateWithRetry(db, migrationsFolder);
+  migrateWithRetry(db, migrationsFolder, nativeDb, "brain_decisions", "brain");
 }
 function loadBrainVecExtension(nativeDb) {
   try {
@@ -34416,9 +34457,15 @@ async function addTask(options, cwd, accessor) {
     if (lifecycleMode === "strict") {
       throw new CleoError(
         6 /* VALIDATION_ERROR */,
-        'Tasks must have a parent (epic or task) in strict mode. Use --parent <epicId> or set lifecycle.mode to "advisory".',
+        'Tasks must have a parent (epic or task) in strict mode. Use --parent <epicId>, --type epic for a root-level epic, or set lifecycle.mode to "advisory".',
         {
-          fix: 'cleo add "Task title" --parent T### --acceptance "AC1|AC2|AC3"'
+          fix: 'cleo add "Task title" --parent T### --acceptance "AC1|AC2|AC3"',
+          alternatives: [
+            {
+              action: "Create as epic",
+              command: 'cleo add "Epic title" --type epic --priority high'
+            }
+          ]
         }
       );
     }
@@ -74007,6 +74054,57 @@ async function initProject(opts = {}) {
       ".cleo/ was found in root .gitignore and has been removed. CLEO uses .cleo/.gitignore for selective tracking."
     );
   }
+  try {
+    const cantDir = join105(cleoDir, "cant");
+    const cantAgentsDir = join105(cantDir, "agents");
+    const hasCantFiles = existsSync106(cantDir) && readdirSync36(cantDir, { recursive: true }).some(
+      (f2) => typeof f2 === "string" && f2.endsWith(".cant")
+    );
+    if (!hasCantFiles) {
+      let starterBundleSrc = null;
+      try {
+        const { createRequire: createRequire13 } = await import("node:module");
+        const req = createRequire13(import.meta.url);
+        const cleoOsPkgMain = req.resolve("@cleocode/cleo-os/package.json");
+        const cleoOsPkgRoot = dirname21(cleoOsPkgMain);
+        const candidate = join105(cleoOsPkgRoot, "starter-bundle");
+        if (existsSync106(candidate)) {
+          starterBundleSrc = candidate;
+        }
+      } catch {
+      }
+      if (!starterBundleSrc) {
+        const packageRoot = getPackageRoot();
+        const fallbacks = [
+          join105(packageRoot, "..", "cleo-os", "starter-bundle"),
+          join105(packageRoot, "..", "..", "packages", "cleo-os", "starter-bundle")
+        ];
+        starterBundleSrc = fallbacks.find((p2) => existsSync106(p2)) ?? null;
+      }
+      if (starterBundleSrc) {
+        await mkdir16(cantDir, { recursive: true });
+        await mkdir16(cantAgentsDir, { recursive: true });
+        const teamSrc = join105(starterBundleSrc, "team.cant");
+        const teamDst = join105(cantDir, "team.cant");
+        if (existsSync106(teamSrc) && !existsSync106(teamDst)) {
+          await copyFile4(teamSrc, teamDst);
+        }
+        const agentsSrc = join105(starterBundleSrc, "agents");
+        if (existsSync106(agentsSrc)) {
+          const agentFiles = readdirSync36(agentsSrc).filter((f2) => f2.endsWith(".cant"));
+          for (const agentFile of agentFiles) {
+            const dst = join105(cantAgentsDir, agentFile);
+            if (!existsSync106(dst)) {
+              await copyFile4(join105(agentsSrc, agentFile), dst);
+            }
+          }
+        }
+        created.push("starter-bundle: team + agent .cant files deployed to .cleo/cant/");
+      }
+    }
+  } catch (err) {
+    warnings.push(`Starter bundle deploy: ${err instanceof Error ? err.message : String(err)}`);
+  }
   if (opts.installSeedAgents) {
     try {
       const seedDir = await resolveSeedAgentsDir();
@@ -75307,7 +75405,6 @@ __export(src_exports, {
 });
 var init_src2 = __esm({
   "packages/core/src/index.ts"() {
-    "use strict";
     init_src();
     init_adapters();
     init_admin();
@@ -111594,6 +111691,12 @@ async function orchestrateClassify(request, context, projectRoot) {
     };
   }
 }
+function evictFanoutManifest() {
+  while (fanoutManifestStore.size > FANOUT_MANIFEST_MAX_SIZE) {
+    const oldest = fanoutManifestStore.keys().next().value;
+    if (oldest !== void 0) fanoutManifestStore.delete(oldest);
+  }
+}
 async function orchestrateFanout(items, projectRoot) {
   const manifestEntryId = `fanout-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
   try {
@@ -111638,6 +111741,7 @@ async function orchestrateFanout(items, projectRoot) {
       results,
       completedAt: (/* @__PURE__ */ new Date()).toISOString()
     });
+    evictFanoutManifest();
     return {
       success: true,
       data: {
@@ -111739,7 +111843,7 @@ async function orchestrateAnalyzeParallelSafety(taskIds, projectRoot) {
     };
   }
 }
-var OrchestrateHandler, fanoutManifestStore;
+var OrchestrateHandler, FANOUT_MANIFEST_MAX_SIZE, fanoutManifestStore;
 var init_orchestrate2 = __esm({
   "packages/cleo/src/dispatch/domains/orchestrate.ts"() {
     "use strict";
@@ -112223,6 +112327,7 @@ var init_orchestrate2 = __esm({
         };
       }
     };
+    FANOUT_MANIFEST_MAX_SIZE = 64;
     fanoutManifestStore = /* @__PURE__ */ new Map();
   }
 });
@@ -118452,6 +118557,786 @@ Task ${taskId} reassigned to you by ${active.agentId}. Run: cleo show ${taskId}
       { command: "agent health" }
     );
   });
+  agent.command("install <path>").description("Install an agent from a .cantz archive or agent directory").option("--global", "Install to global tier (~/.local/share/cleo/cant/agents/)").action(async (sourcePath, opts) => {
+    try {
+      const { existsSync: existsSync131, mkdirSync: mkdirSync31, cpSync, readFileSync: readFileSync101, rmSync: rmSync3, statSync: statSync22 } = await import("node:fs");
+      const { join: join131, basename: basename19, resolve: resolve16 } = await import("node:path");
+      const { homedir: homedir7 } = await import("node:os");
+      const { tmpdir: tmpdir3 } = await import("node:os");
+      const resolvedPath = resolve16(sourcePath);
+      if (!existsSync131(resolvedPath)) {
+        cliOutput(
+          {
+            success: false,
+            error: {
+              code: "E_NOT_FOUND",
+              message: `Path does not exist: ${resolvedPath}`
+            }
+          },
+          { command: "agent install" }
+        );
+        process.exitCode = 4;
+        return;
+      }
+      let agentDir;
+      let agentName;
+      let tempDir = null;
+      const isCantzArchive = resolvedPath.endsWith(".cantz") && statSync22(resolvedPath).isFile();
+      if (isCantzArchive) {
+        const { execFileSync: execFileSync19 } = await import("node:child_process");
+        tempDir = join131(tmpdir3(), `cleo-agent-install-${Date.now()}`);
+        mkdirSync31(tempDir, { recursive: true });
+        try {
+          execFileSync19("unzip", ["-o", "-q", resolvedPath, "-d", tempDir], {
+            encoding: "utf-8",
+            timeout: 3e4
+          });
+        } catch (unzipErr) {
+          if (tempDir) rmSync3(tempDir, { recursive: true, force: true });
+          cliOutput(
+            {
+              success: false,
+              error: {
+                code: "E_VALIDATION",
+                message: `Failed to extract .cantz archive: ${String(unzipErr)}`
+              }
+            },
+            { command: "agent install" }
+          );
+          process.exitCode = 6;
+          return;
+        }
+        const { readdirSync: readdirSync42 } = await import("node:fs");
+        const topLevel = readdirSync42(tempDir).filter((entry) => {
+          const entryPath = join131(tempDir, entry);
+          return statSync22(entryPath).isDirectory();
+        });
+        if (topLevel.length !== 1) {
+          if (tempDir) rmSync3(tempDir, { recursive: true, force: true });
+          cliOutput(
+            {
+              success: false,
+              error: {
+                code: "E_VALIDATION",
+                message: `Archive must contain exactly one top-level directory, found ${topLevel.length}`
+              }
+            },
+            { command: "agent install" }
+          );
+          process.exitCode = 6;
+          return;
+        }
+        agentName = topLevel[0];
+        agentDir = join131(tempDir, agentName);
+      } else if (statSync22(resolvedPath).isDirectory()) {
+        agentDir = resolvedPath;
+        agentName = basename19(resolvedPath);
+      } else {
+        cliOutput(
+          {
+            success: false,
+            error: {
+              code: "E_VALIDATION",
+              message: `Path must be a .cantz file or a directory: ${resolvedPath}`
+            }
+          },
+          { command: "agent install" }
+        );
+        process.exitCode = 6;
+        return;
+      }
+      const personaPath = join131(agentDir, "persona.cant");
+      if (!existsSync131(personaPath)) {
+        if (tempDir) rmSync3(tempDir, { recursive: true, force: true });
+        cliOutput(
+          {
+            success: false,
+            error: {
+              code: "E_VALIDATION",
+              message: `Agent directory must contain persona.cant: ${personaPath}`
+            }
+          },
+          { command: "agent install" }
+        );
+        process.exitCode = 6;
+        return;
+      }
+      const isGlobal = opts["global"] === true;
+      let targetRoot;
+      if (isGlobal) {
+        const home = homedir7();
+        const xdgData = process.env["XDG_DATA_HOME"] ?? join131(home, ".local", "share");
+        targetRoot = join131(xdgData, "cleo", "cant", "agents");
+      } else {
+        targetRoot = join131(process.cwd(), ".cleo", "cant", "agents");
+      }
+      const targetDir = join131(targetRoot, agentName);
+      mkdirSync31(targetRoot, { recursive: true });
+      cpSync(agentDir, targetDir, { recursive: true, force: true });
+      if (tempDir) {
+        rmSync3(tempDir, { recursive: true, force: true });
+      }
+      let registered = false;
+      try {
+        const persona = readFileSync101(join131(targetDir, "persona.cant"), "utf-8");
+        const descMatch = persona.match(/description:\s*"([^"]+)"/);
+        const displayName = descMatch?.[1] ?? agentName;
+        const { AgentRegistryAccessor: AgentRegistryAccessor2, getDb: getDb4 } = await Promise.resolve().then(() => (init_internal(), internal_exports));
+        await getDb4();
+        const registry2 = new AgentRegistryAccessor2(process.cwd());
+        const existing = await registry2.get(agentName);
+        if (!existing) {
+          await registry2.register({
+            agentId: agentName,
+            displayName,
+            apiKey: "local-installed",
+            apiBaseUrl: "local",
+            classification: "specialist",
+            privacyTier: "private",
+            capabilities: [],
+            skills: [],
+            transportType: "http",
+            transportConfig: {},
+            isActive: false
+          });
+          registered = true;
+        }
+      } catch {
+      }
+      cliOutput(
+        {
+          success: true,
+          data: {
+            agent: agentName,
+            tier: isGlobal ? "global" : "project",
+            path: targetDir,
+            registered
+          }
+        },
+        { command: "agent install" }
+      );
+    } catch (err) {
+      cliOutput(
+        { success: false, error: { code: "E_INSTALL", message: String(err) } },
+        { command: "agent install" }
+      );
+      process.exitCode = 1;
+    }
+  });
+  agent.command("pack <dir>").description("Package an agent directory as a .cantz archive").action(async (dir) => {
+    try {
+      const { existsSync: existsSync131, statSync: statSync22 } = await import("node:fs");
+      const { resolve: resolve16, basename: basename19, dirname: dirname29 } = await import("node:path");
+      const { execFileSync: execFileSync19 } = await import("node:child_process");
+      const resolvedDir = resolve16(dir);
+      if (!existsSync131(resolvedDir) || !statSync22(resolvedDir).isDirectory()) {
+        cliOutput(
+          {
+            success: false,
+            error: {
+              code: "E_NOT_FOUND",
+              message: `Directory does not exist: ${resolvedDir}`
+            }
+          },
+          { command: "agent pack" }
+        );
+        process.exitCode = 4;
+        return;
+      }
+      const { join: join131 } = await import("node:path");
+      const personaPath = join131(resolvedDir, "persona.cant");
+      if (!existsSync131(personaPath)) {
+        cliOutput(
+          {
+            success: false,
+            error: {
+              code: "E_VALIDATION",
+              message: `Agent directory must contain persona.cant: ${personaPath}`
+            }
+          },
+          { command: "agent pack" }
+        );
+        process.exitCode = 6;
+        return;
+      }
+      const agentName = basename19(resolvedDir);
+      const archiveName = `${agentName}.cantz`;
+      const archivePath = resolve16(archiveName);
+      const parentDir = dirname29(resolvedDir);
+      try {
+        execFileSync19("zip", ["-r", archivePath, agentName], {
+          cwd: parentDir,
+          encoding: "utf-8",
+          timeout: 3e4
+        });
+      } catch (zipErr) {
+        cliOutput(
+          {
+            success: false,
+            error: {
+              code: "E_PACK",
+              message: `Failed to create archive: ${String(zipErr)}`
+            }
+          },
+          { command: "agent pack" }
+        );
+        process.exitCode = 1;
+        return;
+      }
+      const archiveStats = statSync22(archivePath);
+      const { readdirSync: readdirSync42 } = await import("node:fs");
+      let fileCount = 0;
+      const countFiles2 = (dirPath) => {
+        const entries = readdirSync42(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.isFile()) {
+            fileCount++;
+          } else if (entry.isDirectory()) {
+            countFiles2(join131(dirPath, entry.name));
+          }
+        }
+      };
+      countFiles2(resolvedDir);
+      cliOutput(
+        {
+          success: true,
+          data: {
+            archive: archivePath,
+            agent: agentName,
+            files: fileCount,
+            size: archiveStats.size
+          }
+        },
+        { command: "agent pack" }
+      );
+    } catch (err) {
+      cliOutput(
+        { success: false, error: { code: "E_PACK", message: String(err) } },
+        { command: "agent pack" }
+      );
+      process.exitCode = 1;
+    }
+  });
+  agent.command("create").description("Scaffold a new agent package with persona.cant and manifest.json").requiredOption("--name <name>", "Agent name (kebab-case)").requiredOption("--role <role>", "Agent role: orchestrator, lead, worker, or docs-worker").option("--tier <tier>", "Agent tier: low, mid, or high (defaults based on role)").option("--team <teamName>", "Team this agent belongs to").option("--domain <description>", "Domain description for file permissions and context").option("--global", "Create in global tier (~/.local/share/cleo/cant/agents/)").option("--seed-brain", "Create expertise/mental-model-seed.md and seed a BRAIN observation").option("--parent <parentAgent>", "Parent agent name in the hierarchy").action(async (opts) => {
+    try {
+      const { existsSync: existsSync131, mkdirSync: mkdirSync31, writeFileSync: writeFileSync25 } = await import("node:fs");
+      const { join: join131 } = await import("node:path");
+      const { homedir: homedir7 } = await import("node:os");
+      const name2 = opts["name"];
+      const role = opts["role"];
+      const tier = opts["tier"] ?? inferTierFromRole(role);
+      const team = opts["team"];
+      const domain2 = opts["domain"];
+      const isGlobal = opts["global"] === true;
+      const seedBrain = opts["seedBrain"] === true;
+      const parent = opts["parent"];
+      const validRoles = ["orchestrator", "lead", "worker", "docs-worker"];
+      if (!validRoles.includes(role)) {
+        cliOutput(
+          {
+            success: false,
+            error: {
+              code: "E_VALIDATION",
+              message: `Invalid role "${role}". Must be one of: ${validRoles.join(", ")}`,
+              fix: `cleo agent create --name ${name2} --role worker`
+            }
+          },
+          { command: "agent create" }
+        );
+        process.exitCode = 6;
+        return;
+      }
+      const validTiers = ["low", "mid", "high"];
+      if (!validTiers.includes(tier)) {
+        cliOutput(
+          {
+            success: false,
+            error: {
+              code: "E_VALIDATION",
+              message: `Invalid tier "${tier}". Must be one of: ${validTiers.join(", ")}`,
+              fix: `cleo agent create --name ${name2} --role ${role} --tier mid`
+            }
+          },
+          { command: "agent create" }
+        );
+        process.exitCode = 6;
+        return;
+      }
+      if (!/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(name2)) {
+        cliOutput(
+          {
+            success: false,
+            error: {
+              code: "E_VALIDATION",
+              message: `Agent name must be kebab-case: "${name2}"`,
+              fix: "Use lowercase letters, numbers, and hyphens. Must start with a letter."
+            }
+          },
+          { command: "agent create" }
+        );
+        process.exitCode = 6;
+        return;
+      }
+      let targetRoot;
+      if (isGlobal) {
+        const home = homedir7();
+        const xdgData = process.env["XDG_DATA_HOME"] ?? join131(home, ".local", "share");
+        targetRoot = join131(xdgData, "cleo", "cant", "agents");
+      } else {
+        targetRoot = join131(process.cwd(), ".cleo", "cant", "agents");
+      }
+      const agentDir = join131(targetRoot, name2);
+      if (existsSync131(agentDir)) {
+        cliOutput(
+          {
+            success: false,
+            error: {
+              code: "E_VALIDATION",
+              message: `Agent directory already exists: ${agentDir}`,
+              fix: "Remove the existing directory or choose a different name."
+            }
+          },
+          { command: "agent create" }
+        );
+        process.exitCode = 6;
+        return;
+      }
+      mkdirSync31(agentDir, { recursive: true });
+      const personaContent = generatePersonaCant({
+        name: name2,
+        role,
+        tier,
+        team,
+        domain: domain2,
+        parent
+      });
+      writeFileSync25(join131(agentDir, "persona.cant"), personaContent, "utf-8");
+      const manifest = generateManifest2({ name: name2, role, tier, domain: domain2 });
+      writeFileSync25(
+        join131(agentDir, "manifest.json"),
+        `${JSON.stringify(manifest, null, 2)}
+`,
+        "utf-8"
+      );
+      const createdFiles = [
+        join131(agentDir, "persona.cant"),
+        join131(agentDir, "manifest.json")
+      ];
+      if (team) {
+        const teamConfigContent = generateTeamConfig(name2, role, team);
+        writeFileSync25(join131(agentDir, "team-config.cant"), teamConfigContent, "utf-8");
+        createdFiles.push(join131(agentDir, "team-config.cant"));
+      }
+      if (seedBrain) {
+        const expertiseDir = join131(agentDir, "expertise");
+        mkdirSync31(expertiseDir, { recursive: true });
+        const seedContent = generateMentalModelSeed(name2, role, domain2);
+        writeFileSync25(join131(expertiseDir, "mental-model-seed.md"), seedContent, "utf-8");
+        createdFiles.push(join131(expertiseDir, "mental-model-seed.md"));
+        try {
+          const { execFile: execFile9 } = await import("node:child_process");
+          const { promisify: promisify9 } = await import("node:util");
+          const execFileAsync6 = promisify9(execFile9);
+          await execFileAsync6(
+            "cleo",
+            [
+              "observe",
+              `Agent ${name2} created with role ${role}`,
+              "--title",
+              `Agent creation: ${name2}`
+            ],
+            { encoding: "utf-8", timeout: 1e4 }
+          ).catch(() => {
+          });
+        } catch {
+        }
+      }
+      let registered = false;
+      try {
+        const { AgentRegistryAccessor: AgentRegistryAccessor2, getDb: getDb4 } = await Promise.resolve().then(() => (init_internal(), internal_exports));
+        await getDb4();
+        const registry2 = new AgentRegistryAccessor2(process.cwd());
+        const existing = await registry2.get(name2);
+        if (!existing) {
+          const descMatch = personaContent.match(/description:\s*"([^"]+)"/);
+          const displayName = descMatch?.[1] ?? name2;
+          await registry2.register({
+            agentId: name2,
+            displayName,
+            apiKey: "local-created",
+            apiBaseUrl: "local",
+            classification: role,
+            privacyTier: "private",
+            capabilities: [],
+            skills: [],
+            transportType: "http",
+            transportConfig: {},
+            isActive: false
+          });
+          registered = true;
+        }
+      } catch {
+      }
+      cliOutput(
+        {
+          success: true,
+          data: {
+            agent: name2,
+            role,
+            tier,
+            directory: agentDir,
+            scope: isGlobal ? "global" : "project",
+            files: createdFiles,
+            registered,
+            brainSeeded: seedBrain
+          }
+        },
+        { command: "agent create" }
+      );
+    } catch (err) {
+      cliOutput(
+        { success: false, error: { code: "E_CREATE", message: String(err) } },
+        { command: "agent create" }
+      );
+      process.exitCode = 1;
+    }
+  });
+}
+function inferTierFromRole(role) {
+  if (role === "orchestrator") return "high";
+  return "mid";
+}
+function generatePersonaCant(params) {
+  const { name: name2, role, tier, team, domain: domain2, parent } = params;
+  switch (role) {
+    case "orchestrator":
+      return generateOrchestratorPersona(name2, tier, team, parent);
+    case "lead":
+      return generateLeadPersona(name2, tier, team, domain2, parent);
+    case "worker":
+      return generateWorkerPersona(name2, tier, team, domain2, parent);
+    case "docs-worker":
+      return generateDocsWorkerPersona(name2, tier, team, domain2, parent);
+    default:
+      return generateWorkerPersona(name2, tier, team, domain2, parent);
+  }
+}
+function generateOrchestratorPersona(name2, tier, team, parent) {
+  const parentLine = parent ? `
+  parent: ${parent}` : "";
+  const teamComment = team ? `
+# Team: ${team}` : "";
+  return `---
+kind: agent
+version: "1"
+---
+
+# ${name2} \u2014 orchestrator agent.${teamComment}
+# Coordinates the team, classifies work, dispatches to leads/workers.
+
+agent ${name2}:
+  role: orchestrator${parentLine}
+  tier: ${tier}
+  description: "Orchestrator agent. Reads task context, classifies work, dispatches to leads, and synthesizes results. Does not execute code \u2014 coordinates."
+  consult-when: "Cross-team decisions, scope changes, human-in-the-loop escalation, or when a lead reports a blocking ambiguity"
+
+  context_sources:
+    - source: decisions
+      query: "recent architectural and project decisions"
+      max_entries: 5
+    - source: patterns
+      query: "project conventions and established patterns"
+      max_entries: 3
+  on_overflow: escalate_tier
+
+  mental_model:
+    scope: project
+    max_tokens: 2000
+    on_load:
+      validate: true
+
+  permissions:
+    tasks: read, write
+    session: read, write
+    memory: read, write
+
+  skills:
+    - ct-cleo
+    - ct-task-executor
+
+  tools:
+    core: [Read, Grep, Glob]
+    dispatch: [dispatch_worker, report_to_user]
+
+  on SessionStart:
+    session "Read active tasks and recent decisions to build situational awareness"
+      context: [active-tasks, memory-bridge, recent-decisions]
+
+  on TaskCompleted:
+    if **the completed task unblocks downstream work**:
+      session "Reassess task queue and dispatch next work"
+`;
+}
+function generateLeadPersona(name2, tier, team, domain2, parent) {
+  const parentLine = parent ? `
+  parent: ${parent}` : "\n  parent: cleo-orchestrator";
+  const teamComment = team ? `
+# Team: ${team}` : "";
+  const domainDesc = domain2 ? ` Specializes in ${domain2}.` : "";
+  return `---
+kind: agent
+version: "1"
+---
+
+# ${name2} \u2014 lead agent.${teamComment}
+# Decomposes tasks, reviews worker output, decides technical approach.
+# MUST NOT hold Edit/Write/Bash tools (TEAM-002 / ULTRAPLAN 10.3).
+
+agent ${name2}:
+  role: lead${parentLine}
+  tier: ${tier}
+  description: "Development lead.${domainDesc} Decomposes tasks into concrete implementation steps, reviews worker output, and decides technical approach. Does not write code directly."
+  consult-when: "Implementation strategy, code architecture, refactoring direction, task decomposition, or when workers need clarification"
+
+  context_sources:
+    - source: patterns
+      query: "codebase conventions and architecture patterns"
+      max_entries: 5
+    - source: decisions
+      query: "technical decisions affecting implementation"
+      max_entries: 3
+  on_overflow: escalate_tier
+
+  mental_model:
+    scope: project
+    max_tokens: 1000
+    on_load:
+      validate: true
+
+  permissions:
+    files:
+      read: ["**/*"]
+
+  skills:
+    - ct-cleo
+    - ct-dev-workflow
+    - ct-task-executor
+
+  tools:
+    core: [Read, Grep, Glob]
+    dispatch: [dispatch_worker, report_to_orchestrator]
+
+  on SessionStart:
+    session "Review current task assignments and worker availability"
+      context: [active-tasks, memory-bridge]
+
+  on TaskCompleted:
+    if **the completed task introduced new code**:
+      session "Review worker output for quality and completeness before reporting to orchestrator"
+`;
+}
+function generateWorkerPersona(name2, tier, team, domain2, parent) {
+  const parentLine = parent ? `
+  parent: ${parent}` : "\n  parent: dev-lead";
+  const teamComment = team ? `
+# Team: ${team}` : "";
+  const domainDesc = domain2 ? ` Specializes in ${domain2}.` : "";
+  const writeGlobs = deriveWriteGlobs(domain2);
+  return `---
+kind: agent
+version: "1"
+---
+
+# ${name2} \u2014 worker agent.${teamComment}
+# Executes code changes within declared file globs.
+
+agent ${name2}:
+  role: worker${parentLine}
+  tier: ${tier}
+  description: "Code worker.${domainDesc} Reads requirements, writes code, runs tests, and validates changes. Operates within declared file permission globs."
+  consult-when: "Writing code, fixing bugs, running tests, formatting, or any file modification task"
+
+  context_sources:
+    - source: patterns
+      query: "coding conventions and testing patterns"
+      max_entries: 5
+    - source: learnings
+      query: "past implementation mistakes and fixes"
+      max_entries: 3
+  on_overflow: escalate_tier
+
+  mental_model:
+    scope: project
+    max_tokens: 1000
+    on_load:
+      validate: true
+
+  permissions:
+    files:
+      write: ${JSON.stringify(writeGlobs)}
+      read: ["**/*"]
+      delete: ${JSON.stringify(writeGlobs)}
+
+  skills:
+    - ct-cleo
+    - ct-dev-workflow
+    - ct-task-executor
+
+  tools:
+    core: [Read, Edit, Write, Bash, Glob, Grep]
+
+  on SessionStart:
+    session "Check assigned task and read relevant source files before starting work"
+      context: [active-tasks, memory-bridge]
+
+  on PostToolUse:
+    if tool.name == "Write" or tool.name == "Edit":
+      session "Verify the change compiles and passes lint before proceeding"
+`;
+}
+function generateDocsWorkerPersona(name2, tier, team, domain2, parent) {
+  const parentLine = parent ? `
+  parent: ${parent}` : "\n  parent: dev-lead";
+  const teamComment = team ? `
+# Team: ${team}` : "";
+  const domainDesc = domain2 ? ` Specializes in ${domain2} documentation.` : "";
+  return `---
+kind: agent
+version: "1"
+---
+
+# ${name2} \u2014 documentation worker agent.${teamComment}
+# Writes and maintains documentation within declared globs.
+
+agent ${name2}:
+  role: worker${parentLine}
+  tier: ${tier}
+  description: "Documentation worker.${domainDesc} Writes READMEs, updates guides, adds TSDoc comments, and maintains project documentation. Operates within declared documentation file globs."
+  consult-when: "Writing documentation, updating READMEs, adding TSDoc comments, or improving existing docs"
+
+  context_sources:
+    - source: patterns
+      query: "documentation conventions and style patterns"
+      max_entries: 3
+    - source: decisions
+      query: "architectural decisions needing documentation"
+      max_entries: 3
+  on_overflow: escalate_tier
+
+  mental_model:
+    scope: project
+    max_tokens: 1000
+    on_load:
+      validate: true
+
+  permissions:
+    files:
+      write: ["docs/**", "**/*.md", "**/*.mdx"]
+      read: ["**/*"]
+      delete: ["docs/**"]
+
+  skills:
+    - ct-cleo
+    - ct-documentor
+    - ct-docs-write
+
+  tools:
+    core: [Read, Edit, Write, Bash, Glob, Grep]
+
+  on SessionStart:
+    session "Check assigned documentation task and review existing docs for context"
+      context: [active-tasks, memory-bridge]
+
+  on PostToolUse:
+    if tool.name == "Write" or tool.name == "Edit":
+      session "Verify markdown renders correctly and follows project style conventions"
+`;
+}
+function deriveWriteGlobs(domain2) {
+  const defaults = ["src/**", "packages/**", "lib/**", "test/**", "tests/**"];
+  if (!domain2) return defaults;
+  const lower = domain2.toLowerCase();
+  if (lower.includes("frontend") || lower.includes("ui") || lower.includes("component")) {
+    return ["src/**", "packages/**", "components/**", "styles/**", "public/**", "test/**"];
+  }
+  if (lower.includes("backend") || lower.includes("api") || lower.includes("server")) {
+    return ["src/**", "packages/**", "lib/**", "api/**", "test/**", "tests/**"];
+  }
+  if (lower.includes("infra") || lower.includes("deploy") || lower.includes("ci")) {
+    return [".github/**", "infra/**", "deploy/**", "scripts/**", "Dockerfile*"];
+  }
+  if (lower.includes("test") || lower.includes("qa") || lower.includes("quality")) {
+    return ["test/**", "tests/**", "src/**/*.test.*", "src/**/*.spec.*", "packages/**/*.test.*"];
+  }
+  if (lower.includes("rust") || lower.includes("crate")) {
+    return ["crates/**", "src/**", "Cargo.toml", "test/**"];
+  }
+  if (lower.includes("doc")) {
+    return ["docs/**", "**/*.md", "**/*.mdx"];
+  }
+  return defaults;
+}
+function generateManifest2(params) {
+  return {
+    name: params.name,
+    version: "1.0.0",
+    description: `${capitalizeFirst(params.role)} agent${params.domain ? ` for ${params.domain}` : ""}`,
+    cant: {
+      minVersion: "1",
+      tier: params.tier,
+      role: params.role === "docs-worker" ? "worker" : params.role
+    },
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function generateTeamConfig(name2, role, team) {
+  return `---
+kind: team-config
+version: "1"
+---
+
+# Team membership for ${name2}
+
+team ${team}:
+  member ${name2}:
+    role: ${role}
+    status: active
+`;
+}
+function generateMentalModelSeed(name2, role, domain2) {
+  const domainSection = domain2 ? `## Domain
+
+${domain2}
+` : `## Domain
+
+TODO: Describe the domain this agent specializes in.
+`;
+  return `# Mental Model Seed: ${name2}
+
+> Auto-generated at ${(/* @__PURE__ */ new Date()).toISOString()}
+> Role: ${role}
+
+${domainSection}
+## Key Patterns
+
+TODO: Document recurring patterns this agent should recognize.
+
+## Known Pitfalls
+
+TODO: Document common mistakes or anti-patterns in this domain.
+
+## Decision History
+
+TODO: Track important decisions and their rationale.
+
+## Learning Log
+
+TODO: Record discoveries and insights as the agent operates.
+`;
+}
+function capitalizeFirst(str) {
+  if (str.length === 0) return str;
+  return str.charAt(0).toUpperCase() + str.slice(1);
 }
 
 // packages/cleo/src/cli/commands/agents.ts