easy-coding-harness 0.4.0 → 0.5.1

package/dist/cli.js

@@ -5,12 +5,207 @@ import chalk8 from "chalk";
 import { Command } from "commander";
 
 // src/commands/add-agent.ts
-import path13 from "path";
 import { outro } from "@clack/prompts";
 import chalk2 from "chalk";
 
-// src/configurators/claude.ts
-import path5 from "path";
+// src/constants/version.ts
+import { readFileSync } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+var packageMetadata = readPackageMetadata();
+var PACKAGE_NAME = packageMetadata.name;
+var VERSION = packageMetadata.version;
+function readPackageMetadata() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    path.resolve(here, "../../package.json"),
+    path.resolve(here, "../package.json"),
+    path.resolve(process.cwd(), "package.json")
+  ];
+  for (const candidate of candidates) {
+    try {
+      const parsed = JSON.parse(readFileSync(candidate, "utf8"));
+      if (parsed.name && parsed.version) {
+        return { name: parsed.name, version: parsed.version };
+      }
+    } catch {
+    }
+  }
+  throw new Error(`Unable to locate package metadata. Tried: ${candidates.join(", ")}`);
+}
+
+// src/ui/banner.ts
+import chalk from "chalk";
+import figlet from "figlet";
+var WIDE_TERMINAL_WIDTH = 88;
+var MEDIUM_TERMINAL_WIDTH = 72;
+function renderBanner() {
+  const terminalWidth = process.stdout.columns ?? 120;
+  const art = figlet.textSync("Easy Coding", selectBannerPreset(terminalWidth));
+  console.log(colorizeBanner(art));
+  console.log(chalk.bold.white(`  Easy Coding Harness  ${chalk.cyan(`v${VERSION}`)}
+`));
+}
+function selectBannerPreset(width) {
+  if (width >= WIDE_TERMINAL_WIDTH) {
+    return { font: "ANSI Shadow", horizontalLayout: "full" };
+  }
+  if (width >= MEDIUM_TERMINAL_WIDTH) {
+    return { font: "Small Shadow", horizontalLayout: "full" };
+  }
+  return { font: "Small Slant" };
+}
+function colorizeBanner(art) {
+  const colors = [chalk.cyanBright, chalk.cyan, chalk.blueBright, chalk.blue];
+  return art.split("\n").map((line, index) => colors[index % colors.length](line)).join("\n");
+}
+
+// src/utils/config-yaml.ts
+import { readFile as readFile2 } from "fs/promises";
+import YAML, { isScalar, isSeq, parseDocument } from "yaml";
+
+// src/utils/file-writer.ts
+import { constants } from "fs";
+import { access, cp, writeFile as fsWriteFile, mkdir, readFile, stat } from "fs/promises";
+import path2 from "path";
+async function pathExists(filePath) {
+  try {
+    await access(filePath, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function ensureDir(dir) {
+  await mkdir(dir, { recursive: true });
+}
+async function writeTextFile(filePath, content) {
+  await ensureDir(path2.dirname(filePath));
+  await fsWriteFile(filePath, content.endsWith("\n") ? content : `${content}
+`, "utf8");
+}
+async function readTextFile(filePath) {
+  return readFile(filePath, "utf8");
+}
+async function readTextIfExists(filePath) {
+  if (!await pathExists(filePath)) {
+    return null;
+  }
+  return readTextFile(filePath);
+}
+async function isDirectory(filePath) {
+  try {
+    return (await stat(filePath)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+// src/utils/config-yaml.ts
+function createDefaultConfig(params) {
+  const config = {
+    version: 1,
+    harness_version: params.harnessVersion,
+    agents: params.agents,
+    project: {
+      name: params.projectName
+    },
+    memory: {
+      short_term_max: 10,
+      short_term_keep: 5,
+      schema_version: 2
+    },
+    tasks: {
+      auto_archive_days: 30
+    },
+    behavior: {
+      strict_confirm: true,
+      auto_mode: false
+    }
+  };
+  if (params.supermodule) {
+    config.supermodule = params.supermodule;
+  }
+  return config;
+}
+function stringifyConfig(config) {
+  return YAML.stringify(config);
+}
+async function writeConfigYaml(filePath, config) {
+  await writeTextFile(filePath, stringifyConfig(config));
+}
+async function readConfigYaml(filePath) {
+  const content = await readFile2(filePath, "utf8");
+  return YAML.parse(content);
+}
+async function updateConfigYaml(filePath, updater) {
+  const content = await readFile2(filePath, "utf8");
+  const document = parseDocument(content);
+  const config = document.toJSON();
+  updater(config);
+  for (const [key, value] of Object.entries(config)) {
+    document.set(key, value);
+  }
+  await writeTextFile(filePath, document.toString());
+  return config;
+}
+async function addAgentsToConfig(filePath, agents) {
+  return updateConfigYaml(filePath, (config) => {
+    const merged = /* @__PURE__ */ new Set([...config.agents ?? [], ...agents]);
+    config.agents = [...merged];
+  });
+}
+async function updateHarnessVersion(filePath, version) {
+  return updateConfigYaml(filePath, (config) => {
+    config.harness_version = version;
+  });
+}
+async function updateSupermoduleConfig(filePath, supermodule) {
+  return updateConfigYaml(filePath, (config) => {
+    config.supermodule = supermodule;
+  });
+}
+
+// src/utils/gitignore.ts
+import path3 from "path";
+
+// src/constants/paths.ts
+var EASY_CODING_DIR = ".easy-coding";
+var CONFIG_FILE = "config.yaml";
+var INSTALL_MANIFEST_FILE = "install-manifest.json";
+var SESSIONS_DIR = "sessions";
+var TASKS_DIR = "tasks";
+var PROJECT_INIT_TASK_ID = "project-init";
+var MEMORY_DIR = "memory";
+var SPEC_DIR = "spec";
+var MAIN_SPEC_DIR = "main";
+var DEV_SPEC_DIR = "dev";
+var TEMPLATES_DIR = "templates";
+var SESSIONS_GITIGNORE_ENTRY = ".easy-coding/sessions/";
+var GENERATED_REGION_START = "<!-- \u2550\u2550\u2550 easy-coding-harness generated (DO NOT EDIT BETWEEN MARKERS) \u2550\u2550\u2550 -->";
+var GENERATED_REGION_END = "<!-- \u2550\u2550\u2550 end easy-coding-harness generated \u2550\u2550\u2550 -->";
+
+// src/utils/gitignore.ts
+async function ensureGitignoreEntry(cwd, entry, heading = "# \u2550\u2550\u2550 easy-coding-harness (auto-generated) \u2550\u2550\u2550\n# Personal runtime state; do not commit") {
+  const gitignorePath = path3.join(cwd, ".gitignore");
+  const current = await readTextIfExists(gitignorePath) ?? "";
+  const lines = current.split(/\r?\n/).map((line) => line.trim());
+  if (lines.includes(entry)) {
+    return false;
+  }
+  const prefix = current.trimEnd();
+  const next = [prefix, heading, entry].filter(Boolean).join("\n");
+  await writeTextFile(gitignorePath, next);
+  return true;
+}
+async function ensureEasyCodingSessionsIgnored(cwd) {
+  return ensureGitignoreEntry(cwd, SESSIONS_GITIGNORE_ENTRY);
+}
+
+// src/utils/install-manifest.ts
+import { createHash } from "crypto";
+import { readFile as readFile3 } from "fs/promises";
+import path4 from "path";
 
 // src/types/platform.ts
 var pythonCmd = process.platform === "win32" ? "python" : "python3";
@@ -34,7 +229,8 @@ var PLATFORM_META = {
       workflow_state_path: ".easy-coding/sessions/",
       main_constraint_file: "CLAUDE.md",
       python_cmd: pythonCmd,
-      platform_config_dir: ".claude"
+      platform_config_dir: ".claude",
+      supermodule_boundary: ""
     }
   },
   codex: {
@@ -56,7 +252,8 @@ var PLATFORM_META = {
       workflow_state_path: ".easy-coding/sessions/",
       main_constraint_file: "AGENTS.md",
       python_cmd: pythonCmd,
-      platform_config_dir: ".codex"
+      platform_config_dir: ".codex",
+      supermodule_boundary: ""
     }
   },
   qoder: {
@@ -79,7 +276,8 @@ var PLATFORM_META = {
       workflow_state_path: ".easy-coding/sessions/",
       main_constraint_file: "AGENTS.md",
       python_cmd: pythonCmd,
-      platform_config_dir: ".qoder"
+      platform_config_dir: ".qoder",
+      supermodule_boundary: ""
     }
   }
 };
@@ -88,64 +286,6 @@ function isAgentPlatform(value) {
   return Object.hasOwn(PLATFORM_META, value);
 }
 
-// src/utils/install-manifest.ts
-import { createHash } from "crypto";
-import { readFile as readFile2 } from "fs/promises";
-import path2 from "path";
-
-// src/constants/paths.ts
-var EASY_CODING_DIR = ".easy-coding";
-var CONFIG_FILE = "config.yaml";
-var INSTALL_MANIFEST_FILE = "install-manifest.json";
-var SESSIONS_DIR = "sessions";
-var TASKS_DIR = "tasks";
-var PROJECT_INIT_TASK_ID = "project-init";
-var MEMORY_DIR = "memory";
-var SPEC_DIR = "spec";
-var MAIN_SPEC_DIR = "main";
-var DEV_SPEC_DIR = "dev";
-var TEMPLATES_DIR = "templates";
-var SESSIONS_GITIGNORE_ENTRY = ".easy-coding/sessions/";
-var GENERATED_REGION_START = "<!-- \u2550\u2550\u2550 easy-coding-harness generated (DO NOT EDIT BETWEEN MARKERS) \u2550\u2550\u2550 -->";
-var GENERATED_REGION_END = "<!-- \u2550\u2550\u2550 end easy-coding-harness generated \u2550\u2550\u2550 -->";
-
-// src/utils/file-writer.ts
-import { constants } from "fs";
-import { access, cp, writeFile as fsWriteFile, mkdir, readFile, stat } from "fs/promises";
-import path from "path";
-async function pathExists(filePath) {
-  try {
-    await access(filePath, constants.F_OK);
-    return true;
-  } catch {
-    return false;
-  }
-}
-async function ensureDir(dir) {
-  await mkdir(dir, { recursive: true });
-}
-async function writeTextFile(filePath, content) {
-  await ensureDir(path.dirname(filePath));
-  await fsWriteFile(filePath, content.endsWith("\n") ? content : `${content}
-`, "utf8");
-}
-async function readTextFile(filePath) {
-  return readFile(filePath, "utf8");
-}
-async function readTextIfExists(filePath) {
-  if (!await pathExists(filePath)) {
-    return null;
-  }
-  return readTextFile(filePath);
-}
-async function isDirectory(filePath) {
-  try {
-    return (await stat(filePath)).isDirectory();
-  } catch {
-    return false;
-  }
-}
-
 // src/utils/install-manifest.ts
 function fileArtifact(filePath, kind, platform) {
   return { type: "file", kind, filePath, platform };
@@ -153,8 +293,8 @@ function fileArtifact(filePath, kind, platform) {
 function constraintRegionArtifact(filePath, platform) {
   return { type: "constraint-region", filePath, platform };
 }
-async function hookRegistrationArtifacts(configPath, platform) {
-  const content = await readTextIfExists(configPath);
+async function hookRegistrationArtifacts(configPath2, platform) {
+  const content = await readTextIfExists(configPath2);
   if (content === null) {
     return [];
   }
@@ -166,7 +306,7 @@ async function hookRegistrationArtifacts(configPath, platform) {
   }
   return collectHookCommands(parsed.hooks).map((command) => ({
     type: "hook-registration",
-    configPath,
+    configPath: configPath2,
     command,
     hookPath: extractHookPathFromCommand(command),
     platform
@@ -206,14 +346,14 @@ async function writeInstallManifest(cwd, params) {
       continue;
     }
     if (artifact.type === "hook-registration") {
-      const configPath = toProjectPath(cwd, artifact.configPath);
+      const configPath2 = toProjectPath(cwd, artifact.configPath);
       const registration = {
-        config_path: configPath,
+        config_path: configPath2,
         command: artifact.command,
-        hook_path: artifact.hookPath,
+        hook_path: artifact.hookPath ? normalizeHookPath(cwd, artifact.hookPath) : null,
         platform: artifact.platform
       };
-      hookRegistrations.set(`${configPath}\0${normalizeCommand(artifact.command)}`, registration);
+      hookRegistrations.set(`${configPath2}\0${normalizeCommand(artifact.command)}`, registration);
       continue;
     }
     const relPath = toProjectPath(cwd, artifact.filePath);
@@ -234,12 +374,12 @@ async function writeInstallManifest(cwd, params) {
     constraint_regions: [...constraintRegions.values()].sort(byPath)
   };
   await writeTextFile(
-    path2.join(cwd, EASY_CODING_DIR, INSTALL_MANIFEST_FILE),
+    path4.join(cwd, EASY_CODING_DIR, INSTALL_MANIFEST_FILE),
     JSON.stringify(manifest, null, 2)
   );
 }
 async function readInstallManifest(cwd) {
-  const manifestPath2 = path2.join(cwd, EASY_CODING_DIR, INSTALL_MANIFEST_FILE);
+  const manifestPath2 = path4.join(cwd, EASY_CODING_DIR, INSTALL_MANIFEST_FILE);
   const content = await readTextIfExists(manifestPath2);
   if (content === null) {
     return null;
@@ -265,32 +405,32 @@ function manifestPath(cwd, projectPath) {
   return resolveProjectPath(cwd, projectPath);
 }
 function toProjectPath(cwd, filePath) {
-  const root = path2.resolve(cwd);
-  const resolved = path2.resolve(filePath);
+  const root = path4.resolve(cwd);
+  const resolved = path4.resolve(filePath);
   assertPathInsideProject(root, resolved, filePath);
-  return path2.relative(root, resolved).split(path2.sep).join("/");
+  return path4.relative(root, resolved).split(path4.sep).join("/");
 }
 function normalizeCommand(command) {
   return command.replace(/\\/g, "/").trim().replace(/\s+/g, " ");
 }
 async function sha256File(filePath) {
-  const content = await readFile2(filePath);
+  const content = await readFile3(filePath);
   return createHash("sha256").update(content).digest("hex");
 }
 function resolveProjectPath(cwd, projectPath) {
   const normalized = projectPath.replace(/\\/g, "/");
   const parts = normalized.split("/");
-  if (normalized.trim() === "" || path2.isAbsolute(projectPath) || path2.posix.isAbsolute(normalized) || path2.win32.isAbsolute(projectPath) || /^[A-Za-z]:/.test(projectPath) || parts.some((part) => part === "..")) {
+  if (normalized.trim() === "" || path4.isAbsolute(projectPath) || path4.posix.isAbsolute(normalized) || path4.win32.isAbsolute(projectPath) || /^[A-Za-z]:/.test(projectPath) || parts.some((part) => part === "..")) {
     throw new Error(`Unsafe install manifest path: ${projectPath}`);
   }
-  const root = path2.resolve(cwd);
-  const resolved = path2.resolve(root, normalized);
+  const root = path4.resolve(cwd);
+  const resolved = path4.resolve(root, normalized);
   assertPathInsideProject(root, resolved, projectPath);
   return resolved;
 }
 function assertPathInsideProject(root, resolvedPath, sourcePath) {
-  const relative = path2.relative(root, resolvedPath);
-  if (!relative || relative.startsWith("..") || path2.isAbsolute(relative)) {
+  const relative = path4.relative(root, resolvedPath);
+  if (!relative || relative.startsWith("..") || path4.isAbsolute(relative)) {
     throw new Error(`Unsafe install manifest path: ${sourcePath}`);
   }
 }
@@ -325,20 +465,250 @@ function collectHookCommands(hooks) {
   return commands;
 }
 function extractHookPathFromCommand(command) {
-  const match = normalizeCommand(command).match(/(?:^|\s)(\S+\/hooks\/\S+\.py)(?:\s|$)/);
-  return match?.[1] ?? null;
-}
-function byPath(a, b) {
-  return a.path.localeCompare(b.path);
+  return extractQuotedHookPath(command) ?? extractUnquotedHookPath(command);
 }
-
-// src/configurators/shared.ts
-import { readdir, stat as stat2 } from "fs/promises";
-import path4 from "path";
-
-// src/utils/marked-region.ts
-var MarkedRegionError = class extends Error {
-  constructor(message) {
+function extractQuotedHookPath(command) {
+  for (let index = 0; index < command.length; index += 1) {
+    const quote = command[index];
+    if (quote !== '"' && quote !== "'") {
+      continue;
+    }
+    if (index > 0 && !/\s/.test(command[index - 1])) {
+      continue;
+    }
+    const parsed = parseQuotedToken(command, index, quote);
+    if (!parsed) {
+      continue;
+    }
+    const suffix = readPathSuffix(command, parsed.endIndex);
+    for (const candidate of [parsed.value + suffix, parsed.value]) {
+      if (isHookPythonPath(candidate)) {
+        return candidate;
+      }
+    }
+    index = parsed.endIndex;
+  }
+  return null;
+}
+function parseQuotedToken(command, startIndex, quote) {
+  let value = "";
+  for (let index = startIndex + 1; index < command.length; index += 1) {
+    const char = command[index];
+    if (quote === '"' && char === "\\" && index + 1 < command.length) {
+      value += command[index + 1];
+      index += 1;
+      continue;
+    }
+    if (char === quote) {
+      return { value, endIndex: index + 1 };
+    }
+    value += char;
+  }
+  return null;
+}
+function readPathSuffix(command, startIndex) {
+  if (command[startIndex] !== "/") {
+    return "";
+  }
+  let suffix = "";
+  for (let index = startIndex; index < command.length; index += 1) {
+    const char = command[index];
+    if (/\s/.test(char)) {
+      break;
+    }
+    suffix += char;
+  }
+  return suffix;
+}
+function extractUnquotedHookPath(command) {
+  const match = command.match(/(?:^|\s)(\S+\/hooks\/\S+\.py)(?:\s|$)/);
+  return match?.[1] ?? null;
+}
+function isHookPythonPath(candidate) {
+  return /\/hooks\/\S+\.py$/.test(candidate);
+}
+function normalizeHookPath(cwd, hookPath) {
+  const normalized = hookPath.replace(/\\/g, "/").replace(/^\.\//, "");
+  if (path4.isAbsolute(hookPath) || path4.posix.isAbsolute(normalized) || path4.win32.isAbsolute(hookPath)) {
+    return toProjectPath(cwd, hookPath);
+  }
+  return normalized;
+}
+function byPath(a, b) {
+  return a.path.localeCompare(b.path);
+}
+
+// src/utils/runtime-scaffold.ts
+import path6 from "path";
+
+// src/utils/template-paths.ts
+import { existsSync } from "fs";
+import path5 from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+function getTemplateRoot() {
+  const here = path5.dirname(fileURLToPath2(import.meta.url));
+  const candidates = [
+    path5.resolve(here, "../templates"),
+    path5.resolve(here, "../../templates"),
+    path5.resolve(process.cwd(), "src/templates"),
+    path5.resolve(process.cwd(), "templates")
+  ];
+  const found = candidates.find((candidate) => existsSync(candidate));
+  if (!found) {
+    throw new Error(`Unable to locate templates directory. Tried: ${candidates.join(", ")}`);
+  }
+  return found;
+}
+function getTemplatePath(...segments) {
+  return path5.join(getTemplateRoot(), ...segments);
+}
+
+// src/utils/runtime-scaffold.ts
+async function writeRuntimeScaffold(cwd, agents, opts = {}) {
+  const easyCodingDir = path6.join(cwd, EASY_CODING_DIR);
+  await ensureDir(easyCodingDir);
+  const configPath2 = path6.join(easyCodingDir, CONFIG_FILE);
+  if (!await pathExists(configPath2)) {
+    const projectName = path6.basename(cwd);
+    await writeConfigYaml(
+      configPath2,
+      createDefaultConfig({
+        projectName,
+        harnessVersion: VERSION,
+        agents,
+        supermodule: opts.supermodule
+      })
+    );
+  }
+  await ensureDir(path6.join(easyCodingDir, "tasks"));
+  await ensureDir(path6.join(easyCodingDir, SESSIONS_DIR));
+  await ensureDir(path6.join(easyCodingDir, SPEC_DIR, MAIN_SPEC_DIR));
+  await ensureDir(path6.join(easyCodingDir, SPEC_DIR, DEV_SPEC_DIR));
+  await writeMemoryScaffold(easyCodingDir);
+  await writeTemplatesScaffold(easyCodingDir);
+}
+async function writeTemplatesScaffold(easyCodingDir) {
+  const templatesDir = path6.join(easyCodingDir, TEMPLATES_DIR);
+  await ensureDir(templatesDir);
+  const src = getTemplatePath("runtime", "templates", "dev-spec-skeleton.md");
+  const dest = path6.join(templatesDir, "dev-spec-skeleton.md");
+  await writeTextFile(dest, await readTextFile(src));
+}
+async function writeMemoryScaffold(easyCodingDir) {
+  const memoryDir = path6.join(easyCodingDir, MEMORY_DIR);
+  await ensureDir(path6.join(memoryDir, "short"));
+  await ensureDir(path6.join(memoryDir, "long"));
+  for (const file of ["MEMORY.md", "BUSINESS.md", "TECHNICAL.md"]) {
+    const destination = path6.join(memoryDir, "long", file);
+    if (await pathExists(destination)) {
+      continue;
+    }
+    const templatePath = getTemplatePath("runtime", "memory", "long", file);
+    await writeTextFile(destination, await readTextFile(templatePath));
+  }
+  const shortTemplateDest = path6.join(memoryDir, "SHORT_MEMORY_TEMPLATE.md");
+  if (!await pathExists(shortTemplateDest)) {
+    const templatePath = getTemplatePath("runtime", "memory", "SHORT_MEMORY_TEMPLATE.md");
+    await writeTextFile(shortTemplateDest, await readTextFile(templatePath));
+  }
+}
+
+// src/utils/task-json.ts
+import { readdir } from "fs/promises";
+import path7 from "path";
+function createProjectInitTask(params) {
+  return {
+    type: "project-init",
+    status: "PENDING",
+    created_at: (params.now ?? /* @__PURE__ */ new Date()).toISOString(),
+    created_by: "cli-init",
+    last_agent: "cli",
+    stage_history: [],
+    context: {
+      agents_installed: params.agents,
+      cli_version: VERSION,
+      project_path: params.cwd,
+      init_source: params.initSource ?? "fresh",
+      ...params.legacyAssets ? { legacy_assets: params.legacyAssets } : {},
+      ...params.legacyMissingHarnessFiles ? { legacy_missing_harness_files: params.legacyMissingHarnessFiles } : {}
+    },
+    init_log: []
+  };
+}
+function getTaskJsonPath(cwd, taskId) {
+  return path7.join(cwd, EASY_CODING_DIR, TASKS_DIR, taskId, "task.json");
+}
+async function writeTaskJson(filePath, task) {
+  await writeTextFile(filePath, JSON.stringify(task, null, 2));
+}
+async function readTaskJson(filePath) {
+  return JSON.parse(await readTextFile(filePath));
+}
+async function writeProjectInitTask(cwd, agents, options = {}) {
+  await writeTaskJson(
+    getTaskJsonPath(cwd, PROJECT_INIT_TASK_ID),
+    createProjectInitTask({
+      cwd,
+      agents,
+      initSource: options.initSource,
+      legacyAssets: options.legacyAssets,
+      legacyMissingHarnessFiles: options.legacyMissingHarnessFiles
+    })
+  );
+}
+async function setPendingInitSince(cwd, version) {
+  const filePath = getTaskJsonPath(cwd, PROJECT_INIT_TASK_ID);
+  if (!await pathExists(filePath)) return;
+  const task = await readTaskJson(filePath);
+  if (task.status !== "COMPLETE") return;
+  task.pending_init_since = version;
+  await writeTaskJson(filePath, task);
+}
+async function listTasks(cwd) {
+  const tasksDir = path7.join(cwd, EASY_CODING_DIR, TASKS_DIR);
+  if (!await pathExists(tasksDir)) {
+    return [];
+  }
+  const entries = await readdir(tasksDir, { withFileTypes: true });
+  const tasks = [];
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const taskPath = getTaskJsonPath(cwd, entry.name);
+    if (!await pathExists(taskPath)) {
+      continue;
+    }
+    tasks.push({ id: entry.name, task: await readTaskJson(taskPath) });
+  }
+  return tasks;
+}
+function summarizeTaskStatuses(tasks) {
+  return tasks.reduce(
+    (summary, item) => {
+      summary[item.task.status] = (summary[item.task.status] ?? 0) + 1;
+      return summary;
+    },
+    {}
+  );
+}
+function isActiveTask(task) {
+  return task.status !== "COMPLETE" && task.status !== "CLOSED";
+}
+
+// src/commands/install-harness.ts
+import path13 from "path";
+
+// src/configurators/claude.ts
+import path9 from "path";
+
+// src/configurators/shared.ts
+import { readdir as readdir2, stat as stat2 } from "fs/promises";
+import path8 from "path";
+
+// src/utils/marked-region.ts
+var MarkedRegionError = class extends Error {
+  constructor(message) {
     super(message);
     this.name = "MarkedRegionError";
   }
@@ -373,28 +743,6 @@ function removeMarkedRegion(content) {
 ` : "";
 }
 
-// src/utils/template-paths.ts
-import { existsSync } from "fs";
-import path3 from "path";
-import { fileURLToPath } from "url";
-function getTemplateRoot() {
-  const here = path3.dirname(fileURLToPath(import.meta.url));
-  const candidates = [
-    path3.resolve(here, "../templates"),
-    path3.resolve(here, "../../templates"),
-    path3.resolve(process.cwd(), "src/templates"),
-    path3.resolve(process.cwd(), "templates")
-  ];
-  const found = candidates.find((candidate) => existsSync(candidate));
-  if (!found) {
-    throw new Error(`Unable to locate templates directory. Tried: ${candidates.join(", ")}`);
-  }
-  return found;
-}
-function getTemplatePath(...segments) {
-  return path3.join(getTemplateRoot(), ...segments);
-}
-
 // src/configurators/shared.ts
 var UnresolvedPlaceholderError = class extends Error {
   constructor(contentName, placeholders) {
@@ -414,16 +762,43 @@ function resolvePlaceholders(content, ctx, contentName = "template") {
   }
   return resolved;
 }
+function withInstallPaths(cwd, ctx) {
+  const hooksDir = toPosixPath(path8.resolve(cwd, ctx.platform_config_dir, "hooks"));
+  return {
+    ...ctx,
+    platform_hooks_dir_abs: hooksDir,
+    platform_hooks_dir_shell: jsonStringContent(shellDoubleQuoteArg(hooksDir))
+  };
+}
+function renderHookCommand(cwd, ctx, scriptName, platform = process.platform) {
+  const hooksDir = toPosixPath(path8.resolve(cwd, ctx.platform_config_dir, "hooks"));
+  return `${ctx.python_cmd} ${shellDoubleQuoteArg(hooksDir, platform)}/${scriptName}`;
+}
+function shellDoubleQuoteArg(value, platform = process.platform) {
+  if (platform === "win32") {
+    if (value.includes('"')) {
+      throw new Error("Windows hook paths cannot contain double quotes.");
+    }
+    return `"${value}"`;
+  }
+  return `"${value.replace(/(["\\$`])/g, "\\$1")}"`;
+}
+function toPosixPath(filePath) {
+  return filePath.split(path8.sep).join("/");
+}
+function jsonStringContent(value) {
+  return JSON.stringify(value).slice(1, -1);
+}
 async function resolveSkills(ctx) {
   const skillsRoot = getTemplatePath("common", "skills");
-  const entries = await readdir(skillsRoot);
+  const entries = await readdir2(skillsRoot);
   const skills = [];
   for (const entry of entries.sort()) {
-    const skillDir = path4.join(skillsRoot, entry);
+    const skillDir = path8.join(skillsRoot, entry);
     if (!await isDirectory(skillDir)) {
       continue;
     }
-    const content = await readTextFile(path4.join(skillDir, "SKILL.md"));
+    const content = await readTextFile(path8.join(skillDir, "SKILL.md"));
     skills.push({
       name: entry,
       content: resolvePlaceholders(content, ctx, `common/skills/${entry}/SKILL.md`)
@@ -436,10 +811,10 @@ async function resolveBundledSkills(ctx) {
   if (!await pathExists(bundledRoot)) {
     return [];
   }
-  const entries = await readdir(bundledRoot);
+  const entries = await readdir2(bundledRoot);
   const bundled = [];
   for (const entry of entries.sort()) {
-    const sourceDir = path4.join(bundledRoot, entry);
+    const sourceDir = path8.join(bundledRoot, entry);
     if (await isDirectory(sourceDir)) {
       bundled.push({ name: entry, sourceDir, context: ctx });
     }
@@ -450,13 +825,13 @@ async function writeSkills(dir, skills, bundled) {
   await ensureDir(dir);
   const written = [];
   for (const skill of skills) {
-    const destination = path4.join(dir, skill.name, "SKILL.md");
+    const destination = path8.join(dir, skill.name, "SKILL.md");
     await writeTextFile(destination, skill.content);
     written.push(destination);
   }
   for (const skill of bundled) {
     written.push(
-      ...await copyTemplateDirectory(skill.sourceDir, path4.join(dir, skill.name), skill.context)
+      ...await copyTemplateDirectory(skill.sourceDir, path8.join(dir, skill.name), skill.context)
     );
   }
   return written;
@@ -464,14 +839,14 @@ async function writeSkills(dir, skills, bundled) {
 async function writeSharedHooks(dir, platform, opts = {}) {
   const hooksRoot = getTemplatePath("shared-hooks");
   const ctx = PLATFORM_META[platform].templateContext;
-  const entries = await readdir(hooksRoot);
+  const entries = await readdir2(hooksRoot);
   await ensureDir(dir);
   const written = [];
   for (const entry of entries.sort()) {
     if (opts.skipSubagentContext && entry === "inject-subagent-context.py") {
       continue;
     }
-    const sourcePath = path4.join(hooksRoot, entry);
+    const sourcePath = path8.join(hooksRoot, entry);
     if ((await stat2(sourcePath)).isDirectory()) {
       continue;
     }
@@ -480,7 +855,7 @@ async function writeSharedHooks(dir, platform, opts = {}) {
       ctx,
       `shared-hooks/${entry}`
     );
-    const destination = path4.join(dir, entry);
+    const destination = path8.join(dir, entry);
     await writeTextFile(destination, content);
     await import("fs/promises").then(({ chmod }) => chmod(destination, 493));
     written.push(destination);
@@ -491,16 +866,19 @@ async function copyPlatformTemplates(platformTemplateDir, destination, skipDirs,
   const source = getTemplatePath(platformTemplateDir);
   return copyTemplateDirectory(source, destination, ctx, new Set(skipDirs));
 }
-async function writeMainConstraint(cwd, platform) {
+async function writeMainConstraint(cwd, platform, opts = {}) {
   const meta = PLATFORM_META[platform];
-  const ctx = meta.templateContext;
+  const ctx = {
+    ...meta.templateContext,
+    supermodule_boundary: renderSupermoduleBoundary(opts.supermodule)
+  };
   const templateName = `${meta.mainConstraint}.tpl`;
   const template = await readTextFile(getTemplatePath("main-constraint", templateName));
   const generated = resolvePlaceholders(template, ctx, `main-constraint/${templateName}`);
   if (!generated.includes(GENERATED_REGION_START) || !generated.includes(GENERATED_REGION_END)) {
     throw new Error(`Main constraint template ${templateName} does not contain generated markers.`);
   }
-  const destination = path4.join(cwd, meta.mainConstraint);
+  const destination = path8.join(cwd, meta.mainConstraint);
   const current = await readTextIfExists(destination);
   if (current) {
     const markerContent = extractMarkedRegion(generated);
@@ -513,15 +891,37 @@ async function writeMainConstraint(cwd, platform) {
   }
   return destination;
 }
+function renderSupermoduleBoundary(boundary) {
+  if (!boundary || boundary.submodulePaths.length === 0) {
+    return "";
+  }
+  const submodules = boundary.submodulePaths.map((submodulePath) => `- \`${submodulePath}\``);
+  return [
+    "",
+    "## Supermodule Boundary",
+    "",
+    "This directory is a git supermodule root. The following subdirectories are independent",
+    "submodule harness roots with their own git boundaries and Easy Coding runtime:",
+    "",
+    ...submodules,
+    "",
+    "- Cross-repo work launched from this root uses the parent `.easy-coding` task, session, state, and spec as the source of truth.",
+    "- Child `.easy-coding` directories are not parent workflow state sources.",
+    "- During memory archive, technical memory that belongs to a child repo is written only to that child's `.easy-coding/memory`; do not write child task/session/state files from the parent.",
+    "- Commit submodule changes in two steps: push each child repo first, then commit and push the parent gitlink update.",
+    "- Parent memory should keep cross-repo context; child technical details should follow the owning child repo.",
+    ""
+  ].join("\n");
+}
 async function copyTemplateDirectory(source, destination, ctx, skipDirs = /* @__PURE__ */ new Set()) {
   await ensureDir(destination);
   const written = [];
-  for (const entry of (await readdir(source)).sort()) {
+  for (const entry of (await readdir2(source)).sort()) {
     if (skipDirs.has(entry) || shouldSkipTemplateEntry(entry)) {
       continue;
     }
-    const sourcePath = path4.join(source, entry);
-    const destinationPath = path4.join(destination, stripTemplateExtension(entry));
+    const sourcePath = path8.join(source, entry);
+    const destinationPath = path8.join(destination, stripTemplateExtension(entry));
     const sourceStat = await stat2(sourcePath);
     if (sourceStat.isDirectory()) {
       written.push(...await copyTemplateDirectory(sourcePath, destinationPath, ctx, skipDirs));
@@ -541,63 +941,65 @@ function stripTemplateExtension(fileName) {
 }
 
 // src/configurators/claude.ts
-async function configureClaude(cwd) {
+async function configureClaude(cwd, opts = {}) {
   const platform = "claude-code";
   const meta = PLATFORM_META[platform];
-  const ctx = meta.templateContext;
-  const dest = path5.join(cwd, ".claude");
-  const hookConfigPath = path5.join(cwd, meta.hookConfigFile);
+  const ctx = withInstallPaths(cwd, meta.templateContext);
+  const dest = path9.join(cwd, ".claude");
+  const hookConfigPath = path9.join(cwd, meta.hookConfigFile);
   const artifacts = [];
   const platformFiles = await copyPlatformTemplates("claude", dest, ["hooks"], ctx);
   artifacts.push(
     ...platformFiles.filter((filePath) => filePath !== hookConfigPath).map(
       (filePath) => fileArtifact(
         filePath,
-        filePath.startsWith(path5.join(cwd, meta.agentsDir)) ? "agent" : "platform-config",
+        filePath.startsWith(path9.join(cwd, meta.agentsDir)) ? "agent" : "platform-config",
         platform
       )
     )
   );
   artifacts.push(...await hookRegistrationArtifacts(hookConfigPath, platform));
   artifacts.push(
-    ...(await writeSharedHooks(path5.join(dest, "hooks"), platform)).map(
+    ...(await writeSharedHooks(path9.join(dest, "hooks"), platform)).map(
       (filePath) => fileArtifact(filePath, "hook", platform)
     )
   );
   artifacts.push(
     ...(await writeSkills(
-      path5.join(cwd, meta.skillsDir),
+      path9.join(cwd, meta.skillsDir),
       await resolveSkills(ctx),
       await resolveBundledSkills(ctx)
     )).map((filePath) => fileArtifact(filePath, "skill", platform))
   );
-  artifacts.push(constraintRegionArtifact(await writeMainConstraint(cwd, platform), platform));
+  artifacts.push(
+    constraintRegionArtifact(await writeMainConstraint(cwd, platform, opts), platform)
+  );
   return artifacts;
 }
 
 // src/configurators/codex.ts
-import path6 from "path";
-async function configureCodex(cwd) {
+import path10 from "path";
+async function configureCodex(cwd, opts = {}) {
   const platform = "codex";
   const meta = PLATFORM_META[platform];
-  const ctx = meta.templateContext;
-  const hookConfigPath = path6.join(cwd, meta.hookConfigFile);
+  const ctx = withInstallPaths(cwd, meta.templateContext);
+  const hookConfigPath = path10.join(cwd, meta.hookConfigFile);
   const artifacts = [];
   artifacts.push(
     ...(await writeSkills(
-      path6.join(cwd, meta.skillsDir),
+      path10.join(cwd, meta.skillsDir),
       await resolveSkills(ctx),
       await resolveBundledSkills(ctx)
     )).map((filePath) => fileArtifact(filePath, "skill", platform))
   );
   artifacts.push(
-    ...(await writeSharedHooks(path6.join(cwd, meta.hooksDir), platform, {
+    ...(await writeSharedHooks(path10.join(cwd, meta.hooksDir), platform, {
       skipSubagentContext: true
     })).map((filePath) => fileArtifact(filePath, "hook", platform))
   );
   const platformFiles = await copyPlatformTemplates(
     "codex",
-    path6.join(cwd, ".codex"),
+    path10.join(cwd, ".codex"),
     ["hooks"],
     ctx
   );
@@ -605,28 +1007,30 @@ async function configureCodex(cwd) {
     ...platformFiles.filter((filePath) => filePath !== hookConfigPath).map(
       (filePath) => fileArtifact(
         filePath,
-        filePath.startsWith(path6.join(cwd, meta.agentsDir)) ? "agent" : "platform-config",
+        filePath.startsWith(path10.join(cwd, meta.agentsDir)) ? "agent" : "platform-config",
         platform
       )
     )
   );
   artifacts.push(...await hookRegistrationArtifacts(hookConfigPath, platform));
-  artifacts.push(constraintRegionArtifact(await writeMainConstraint(cwd, platform), platform));
+  artifacts.push(
+    constraintRegionArtifact(await writeMainConstraint(cwd, platform, opts), platform)
+  );
   return artifacts;
 }
 
 // src/configurators/qoder.ts
-import { readdir as readdir2 } from "fs/promises";
-import path8 from "path";
+import { readdir as readdir3 } from "fs/promises";
+import path12 from "path";
 
 // src/utils/platform-paths.ts
 import { existsSync as existsSync2 } from "fs";
-import path7 from "path";
+import path11 from "path";
 function detectQoderCnVariant(cwd) {
   if (process.env.EC_QODER_VARIANT === "cn" || process.env.QODER_VARIANT === "cn") {
     return true;
   }
-  return existsSync2(path7.join(cwd, PLATFORM_META.qoder.cnVariant ?? ".qodercn"));
+  return existsSync2(path11.join(cwd, PLATFORM_META.qoder.cnVariant ?? ".qodercn"));
 }
 function resolvePlatformMeta(cwd, platform) {
   const meta = PLATFORM_META[platform];
@@ -657,12 +1061,12 @@ function resolveQoderMetaForBaseDir(baseDir) {
 
 // src/configurators/qoder.ts
 async function claudeHarnessSkillsExist(cwd) {
-  return pathExists(path8.join(cwd, ".claude", "skills", "ec-workflow", "SKILL.md"));
+  return pathExists(path12.join(cwd, ".claude", "skills", "ec-workflow", "SKILL.md"));
 }
 async function listFilesRecursive(dir) {
   let entries;
   try {
-    entries = await readdir2(dir, { withFileTypes: true });
+    entries = await readdir3(dir, { withFileTypes: true });
   } catch (error) {
     if (error.code === "ENOENT") {
       return [];
@@ -671,7 +1075,7 @@ async function listFilesRecursive(dir) {
   }
   const files = [];
   for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
-    const entryPath = path8.join(dir, entry.name);
+    const entryPath = path12.join(dir, entry.name);
     if (entry.isDirectory()) {
       files.push(...await listFilesRecursive(entryPath));
       continue;
@@ -685,32 +1089,32 @@ async function listFilesRecursive(dir) {
 async function existingManagedSkillArtifacts(skillsDir, skillNames, platform) {
   const artifacts = [];
   for (const skillName of skillNames) {
-    for (const filePath of await listFilesRecursive(path8.join(skillsDir, skillName))) {
+    for (const filePath of await listFilesRecursive(path12.join(skillsDir, skillName))) {
       artifacts.push(fileArtifact(filePath, "skill", platform));
     }
   }
   return artifacts;
 }
-async function configureQoder(cwd) {
+async function configureQoder(cwd, opts = {}) {
   const platform = "qoder";
   const meta = resolvePlatformMeta(cwd, platform);
-  const ctx = meta.templateContext;
-  const dest = path8.join(cwd, ctx.platform_config_dir);
-  const hookConfigPath = path8.join(cwd, meta.hookConfigFile);
+  const ctx = withInstallPaths(cwd, meta.templateContext);
+  const dest = path12.join(cwd, ctx.platform_config_dir);
+  const hookConfigPath = path12.join(cwd, meta.hookConfigFile);
   const artifacts = [];
   const platformFiles = await copyPlatformTemplates("qoder", dest, ["hooks"], ctx);
   artifacts.push(
     ...platformFiles.filter((filePath) => filePath !== hookConfigPath).map(
       (filePath) => fileArtifact(
         filePath,
-        filePath.startsWith(path8.join(cwd, meta.agentsDir)) ? "agent" : "platform-config",
+        filePath.startsWith(path12.join(cwd, meta.agentsDir)) ? "agent" : "platform-config",
         platform
       )
     )
   );
   artifacts.push(...await hookRegistrationArtifacts(hookConfigPath, platform));
   artifacts.push(
-    ...(await writeSharedHooks(path8.join(dest, "hooks"), platform)).map(
+    ...(await writeSharedHooks(path12.join(dest, "hooks"), platform)).map(
       (filePath) => fileArtifact(filePath, "hook", platform)
     )
   );
@@ -718,20 +1122,22 @@ async function configureQoder(cwd) {
   const bundledSkills = await resolveBundledSkills(ctx);
   if (!await claudeHarnessSkillsExist(cwd)) {
     artifacts.push(
-      ...(await writeSkills(path8.join(dest, "skills"), skills, bundledSkills)).map(
+      ...(await writeSkills(path12.join(dest, "skills"), skills, bundledSkills)).map(
         (filePath) => fileArtifact(filePath, "skill", platform)
       )
     );
   } else {
     artifacts.push(
       ...await existingManagedSkillArtifacts(
-        path8.join(dest, "skills"),
+        path12.join(dest, "skills"),
         [...skills.map((skill) => skill.name), ...bundledSkills.map((skill) => skill.name)],
         platform
       )
     );
   }
-  artifacts.push(constraintRegionArtifact(await writeMainConstraint(cwd, platform), platform));
+  artifacts.push(
+    constraintRegionArtifact(await writeMainConstraint(cwd, platform, opts), platform)
+  );
   return artifacts;
 }
 
@@ -742,261 +1148,64 @@ var CONFIGURATORS = {
   qoder: configureQoder
 };
 
-// src/constants/version.ts
-import { readFileSync } from "fs";
-import path9 from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
-var packageMetadata = readPackageMetadata();
-var PACKAGE_NAME = packageMetadata.name;
-var VERSION = packageMetadata.version;
-function readPackageMetadata() {
-  const here = path9.dirname(fileURLToPath2(import.meta.url));
-  const candidates = [
-    path9.resolve(here, "../../package.json"),
-    path9.resolve(here, "../package.json"),
-    path9.resolve(process.cwd(), "package.json")
-  ];
-  for (const candidate of candidates) {
-    try {
-      const parsed = JSON.parse(readFileSync(candidate, "utf8"));
-      if (parsed.name && parsed.version) {
-        return { name: parsed.name, version: parsed.version };
-      }
-    } catch {
-    }
+// src/commands/install-harness.ts
+async function configurePlatformsForDir(targetDir, platforms, boundary) {
+  const artifacts = [];
+  for (const platform of platforms) {
+    artifacts.push(...await CONFIGURATORS[platform](targetDir, { supermodule: boundary }));
   }
-  throw new Error(`Unable to locate package metadata. Tried: ${candidates.join(", ")}`);
+  return artifacts;
 }
-
-// src/ui/banner.ts
-import chalk from "chalk";
-import figlet from "figlet";
-var WIDE_TERMINAL_WIDTH = 88;
-var MEDIUM_TERMINAL_WIDTH = 72;
-function renderBanner() {
-  const terminalWidth = process.stdout.columns ?? 120;
-  const art = figlet.textSync("Easy Coding", selectBannerPreset(terminalWidth));
-  console.log(colorizeBanner(art));
-  console.log(chalk.bold.white(`  Easy Coding Harness  ${chalk.cyan(`v${VERSION}`)}
-`));
+async function installHarnessToDir(targetDir, platforms, ctx) {
+  const artifacts = await configurePlatformsForDir(targetDir, platforms, boundaryFromContext(ctx));
+  await writeRuntimeScaffold(targetDir, platforms, {
+    supermodule: supermoduleConfigFromContext(ctx)
+  });
+  await writeInstallManifest(targetDir, {
+    harnessVersion: VERSION,
+    agents: platforms,
+    artifacts
+  });
+  await writeProjectInitTask(targetDir, platforms, {
+    initSource: ctx.initSource,
+    legacyAssets: ctx.legacyAssets,
+    legacyMissingHarnessFiles: ctx.legacyMissingHarnessFiles
+  });
+  await ensureEasyCodingSessionsIgnored(targetDir);
+  return artifacts;
 }
-function selectBannerPreset(width) {
-  if (width >= WIDE_TERMINAL_WIDTH) {
-    return { font: "ANSI Shadow", horizontalLayout: "full" };
+function supermoduleConfigFromContext(ctx) {
+  if (ctx.role === "super-parent") {
+    return {
+      role: "super-parent",
+      submodules: ctx.submodulePaths ?? []
+    };
+  }
+  if (ctx.role === "submodule-child") {
+    return {
+      role: "submodule-child",
+      parent: ctx.parent
+    };
+  }
+  return { role: "standalone" };
+}
+async function refreshSupermoduleParent(targetDir, platforms, submodulePaths) {
+  const supermodule = {
+    role: "super-parent",
+    submodules: submodulePaths
+  };
+  await updateSupermoduleConfig(path13.join(targetDir, EASY_CODING_DIR, CONFIG_FILE), supermodule);
+  for (const platform of platforms) {
+    await writeMainConstraint(targetDir, platform, {
+      supermodule: { submodulePaths }
+    });
   }
-  if (width >= MEDIUM_TERMINAL_WIDTH) {
-    return { font: "Small Shadow", horizontalLayout: "full" };
+}
+function boundaryFromContext(ctx) {
+  if (ctx.role !== "super-parent") {
+    return void 0;
   }
-  return { font: "Small Slant" };
-}
-function colorizeBanner(art) {
-  const colors = [chalk.cyanBright, chalk.cyan, chalk.blueBright, chalk.blue];
-  return art.split("\n").map((line, index) => colors[index % colors.length](line)).join("\n");
-}
-
-// src/utils/config-yaml.ts
-import { readFile as readFile3 } from "fs/promises";
-import YAML, { isScalar, isSeq, parseDocument } from "yaml";
-function createDefaultConfig(params) {
-  return {
-    version: 1,
-    harness_version: params.harnessVersion,
-    agents: params.agents,
-    project: {
-      name: params.projectName
-    },
-    memory: {
-      short_term_max: 10,
-      short_term_keep: 5,
-      schema_version: 2
-    },
-    tasks: {
-      auto_archive_days: 30
-    },
-    behavior: {
-      strict_confirm: true,
-      auto_mode: false
-    }
-  };
-}
-function stringifyConfig(config) {
-  return YAML.stringify(config);
-}
-async function writeConfigYaml(filePath, config) {
-  await writeTextFile(filePath, stringifyConfig(config));
-}
-async function readConfigYaml(filePath) {
-  const content = await readFile3(filePath, "utf8");
-  return YAML.parse(content);
-}
-async function updateConfigYaml(filePath, updater) {
-  const content = await readFile3(filePath, "utf8");
-  const document = parseDocument(content);
-  const config = document.toJSON();
-  updater(config);
-  for (const [key, value] of Object.entries(config)) {
-    document.set(key, value);
-  }
-  await writeTextFile(filePath, document.toString());
-  return config;
-}
-async function addAgentsToConfig(filePath, agents) {
-  return updateConfigYaml(filePath, (config) => {
-    const merged = /* @__PURE__ */ new Set([...config.agents ?? [], ...agents]);
-    config.agents = [...merged];
-  });
-}
-async function updateHarnessVersion(filePath, version) {
-  return updateConfigYaml(filePath, (config) => {
-    config.harness_version = version;
-  });
-}
-
-// src/utils/gitignore.ts
-import path10 from "path";
-async function ensureGitignoreEntry(cwd, entry, heading = "# \u2550\u2550\u2550 easy-coding-harness (auto-generated) \u2550\u2550\u2550\n# Personal runtime state; do not commit") {
-  const gitignorePath = path10.join(cwd, ".gitignore");
-  const current = await readTextIfExists(gitignorePath) ?? "";
-  const lines = current.split(/\r?\n/).map((line) => line.trim());
-  if (lines.includes(entry)) {
-    return false;
-  }
-  const prefix = current.trimEnd();
-  const next = [prefix, heading, entry].filter(Boolean).join("\n");
-  await writeTextFile(gitignorePath, next);
-  return true;
-}
-async function ensureEasyCodingSessionsIgnored(cwd) {
-  return ensureGitignoreEntry(cwd, SESSIONS_GITIGNORE_ENTRY);
-}
-
-// src/utils/runtime-scaffold.ts
-import path11 from "path";
-async function writeRuntimeScaffold(cwd, agents) {
-  const easyCodingDir = path11.join(cwd, EASY_CODING_DIR);
-  await ensureDir(easyCodingDir);
-  const configPath = path11.join(easyCodingDir, CONFIG_FILE);
-  if (!await pathExists(configPath)) {
-    const projectName = path11.basename(cwd);
-    await writeConfigYaml(
-      configPath,
-      createDefaultConfig({ projectName, harnessVersion: VERSION, agents })
-    );
-  }
-  await ensureDir(path11.join(easyCodingDir, "tasks"));
-  await ensureDir(path11.join(easyCodingDir, SESSIONS_DIR));
-  await ensureDir(path11.join(easyCodingDir, SPEC_DIR, MAIN_SPEC_DIR));
-  await ensureDir(path11.join(easyCodingDir, SPEC_DIR, DEV_SPEC_DIR));
-  await writeMemoryScaffold(easyCodingDir);
-  await writeTemplatesScaffold(easyCodingDir);
-}
-async function writeTemplatesScaffold(easyCodingDir) {
-  const templatesDir = path11.join(easyCodingDir, TEMPLATES_DIR);
-  await ensureDir(templatesDir);
-  const src = getTemplatePath("runtime", "templates", "dev-spec-skeleton.md");
-  const dest = path11.join(templatesDir, "dev-spec-skeleton.md");
-  await writeTextFile(dest, await readTextFile(src));
-}
-async function writeMemoryScaffold(easyCodingDir) {
-  const memoryDir = path11.join(easyCodingDir, MEMORY_DIR);
-  await ensureDir(path11.join(memoryDir, "short"));
-  await ensureDir(path11.join(memoryDir, "long"));
-  for (const file of ["MEMORY.md", "BUSINESS.md", "TECHNICAL.md"]) {
-    const destination = path11.join(memoryDir, "long", file);
-    if (await pathExists(destination)) {
-      continue;
-    }
-    const templatePath = getTemplatePath("runtime", "memory", "long", file);
-    await writeTextFile(destination, await readTextFile(templatePath));
-  }
-  const shortTemplateDest = path11.join(memoryDir, "SHORT_MEMORY_TEMPLATE.md");
-  if (!await pathExists(shortTemplateDest)) {
-    const templatePath = getTemplatePath("runtime", "memory", "SHORT_MEMORY_TEMPLATE.md");
-    await writeTextFile(shortTemplateDest, await readTextFile(templatePath));
-  }
-}
-
-// src/utils/task-json.ts
-import { readdir as readdir3 } from "fs/promises";
-import path12 from "path";
-function createProjectInitTask(params) {
-  return {
-    type: "project-init",
-    status: "PENDING",
-    created_at: (params.now ?? /* @__PURE__ */ new Date()).toISOString(),
-    created_by: "cli-init",
-    last_agent: "cli",
-    stage_history: [],
-    context: {
-      agents_installed: params.agents,
-      cli_version: VERSION,
-      project_path: params.cwd,
-      init_source: params.initSource ?? "fresh",
-      ...params.legacyAssets ? { legacy_assets: params.legacyAssets } : {},
-      ...params.legacyMissingHarnessFiles ? { legacy_missing_harness_files: params.legacyMissingHarnessFiles } : {}
-    },
-    init_log: []
-  };
-}
-function getTaskJsonPath(cwd, taskId) {
-  return path12.join(cwd, EASY_CODING_DIR, TASKS_DIR, taskId, "task.json");
-}
-async function writeTaskJson(filePath, task) {
-  await writeTextFile(filePath, JSON.stringify(task, null, 2));
-}
-async function readTaskJson(filePath) {
-  return JSON.parse(await readTextFile(filePath));
-}
-async function writeProjectInitTask(cwd, agents, options = {}) {
-  await writeTaskJson(
-    getTaskJsonPath(cwd, PROJECT_INIT_TASK_ID),
-    createProjectInitTask({
-      cwd,
-      agents,
-      initSource: options.initSource,
-      legacyAssets: options.legacyAssets,
-      legacyMissingHarnessFiles: options.legacyMissingHarnessFiles
-    })
-  );
-}
-async function setPendingInitSince(cwd, version) {
-  const filePath = getTaskJsonPath(cwd, PROJECT_INIT_TASK_ID);
-  if (!await pathExists(filePath)) return;
-  const task = await readTaskJson(filePath);
-  if (task.status !== "COMPLETE") return;
-  task.pending_init_since = version;
-  await writeTaskJson(filePath, task);
-}
-async function listTasks(cwd) {
-  const tasksDir = path12.join(cwd, EASY_CODING_DIR, TASKS_DIR);
-  if (!await pathExists(tasksDir)) {
-    return [];
-  }
-  const entries = await readdir3(tasksDir, { withFileTypes: true });
-  const tasks = [];
-  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
-    if (!entry.isDirectory()) {
-      continue;
-    }
-    const taskPath = getTaskJsonPath(cwd, entry.name);
-    if (!await pathExists(taskPath)) {
-      continue;
-    }
-    tasks.push({ id: entry.name, task: await readTaskJson(taskPath) });
-  }
-  return tasks;
-}
-function summarizeTaskStatuses(tasks) {
-  return tasks.reduce(
-    (summary, item) => {
-      summary[item.task.status] = (summary[item.task.status] ?? 0) + 1;
-      return summary;
-    },
-    {}
-  );
-}
-function isActiveTask(task) {
-  return task.status !== "COMPLETE" && task.status !== "CLOSED";
+  return { submodulePaths: ctx.submodulePaths ?? [] };
 }
 
 // src/commands/platforms.ts
@@ -1043,49 +1252,453 @@ async function resolvePlatforms(opts, defaults = ["claude-code"]) {
       cancel("Platform selection cancelled.");
       process.exit(1);
     }
-    if (shouldInstall) {
-      return result;
+    if (shouldInstall) {
+      return result;
+    }
+    selectedDefaults = result;
+  }
+}
+function parseSubmoduleList(submoduleList, available) {
+  const requested = submoduleList.split(",").map((value) => value.trim()).filter(Boolean);
+  if (requested.length === 0) {
+    throw new Error("No submodule specified.");
+  }
+  const byPathOrName = /* @__PURE__ */ new Map();
+  for (const submodule of available) {
+    byPathOrName.set(submodule.path, submodule);
+    byPathOrName.set(submodule.name, submodule);
+  }
+  const selected = [];
+  const invalid = [];
+  for (const value of requested) {
+    const submodule = byPathOrName.get(value);
+    if (!submodule) {
+      invalid.push(value);
+      continue;
+    }
+    if (!selected.some((item) => item.path === submodule.path)) {
+      selected.push(submodule);
+    }
+  }
+  if (invalid.length > 0) {
+    throw new Error(`Unknown or unavailable submodule: ${invalid.join(", ")}`);
+  }
+  return selected.sort((a, b) => a.path.localeCompare(b.path));
+}
+async function resolveSubmodules(opts, available, defaultSelection = available) {
+  if (opts.submodules === false) {
+    return [];
+  }
+  if (typeof opts.submodules === "string") {
+    return parseSubmoduleList(opts.submodules, available);
+  }
+  if (available.length === 0) {
+    return [];
+  }
+  if (opts.yes) {
+    return defaultSelection;
+  }
+  const result = await multiselect({
+    message: "Select checked-out submodules to initialize (Space to toggle, Enter to confirm)",
+    options: available.map((submodule) => ({
+      label: `${submodule.path} (${submodule.name})`,
+      value: submodule.path
+    })),
+    initialValues: defaultSelection.map((submodule) => submodule.path),
+    required: false
+  });
+  if (typeof result === "symbol") {
+    cancel("Submodule selection cancelled.");
+    process.exit(1);
+  }
+  const selected = new Set(result);
+  return available.filter((submodule) => selected.has(submodule.path));
+}
+
+// src/commands/supermodule-targets.ts
+import path15 from "path";
+import { cancel as cancel2, multiselect as multiselect2 } from "@clack/prompts";
+
+// src/utils/gitmodules.ts
+import { lstat, realpath } from "fs/promises";
+import path14 from "path";
+async function parseGitmodules(rootDir) {
+  const content = await readTextIfExists(path14.join(rootDir, ".gitmodules"));
+  if (content === null) {
+    return [];
+  }
+  const entries = [];
+  let current = null;
+  const flushCurrent = () => {
+    if (current?.name && current.path) {
+      entries.push({
+        name: current.name,
+        path: current.path,
+        url: current.url ?? ""
+      });
+    }
+  };
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = stripGitConfigInlineComment(rawLine).trim();
+    if (!line || line.startsWith("#") || line.startsWith(";")) {
+      continue;
+    }
+    const section = line.match(/^\[submodule\s+"(.+)"\]$/i);
+    if (section) {
+      flushCurrent();
+      current = { name: section[1] };
+      continue;
+    }
+    if (!current) {
+      continue;
+    }
+    const keyValue = line.match(/^([A-Za-z0-9_.-]+)\s*=\s*(.*)$/);
+    if (!keyValue) {
+      continue;
+    }
+    const key = keyValue[1].toLowerCase();
+    const value = unquote(keyValue[2].trim());
+    if (key === "path") {
+      current.path = normalizeSubmodulePath(value);
+      continue;
+    }
+    if (key === "url") {
+      current.url = value;
+    }
+  }
+  flushCurrent();
+  return entries.sort((a, b) => a.path.localeCompare(b.path));
+}
+async function listInstallableSubmodules(rootDir) {
+  const entries = await parseGitmodules(rootDir);
+  const installable = [];
+  for (const entry of entries) {
+    if (await isSubmoduleWorktree(rootDir, entry.path)) {
+      installable.push(entry);
+    }
+  }
+  return installable;
+}
+function normalizeSubmodulePath(value) {
+  const normalized = value.replace(/\\/g, "/").replace(/^\.\/+/, "").trim();
+  const parts = normalized.split("/").filter(Boolean);
+  if (normalized === "" || path14.posix.isAbsolute(normalized) || path14.win32.isAbsolute(value) || parts.some((part) => part === "..")) {
+    throw new Error(`Unsafe submodule path in .gitmodules: ${value}`);
+  }
+  return parts.join("/");
+}
+function unquote(value) {
+  if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+function stripGitConfigInlineComment(value) {
+  let inQuotes = false;
+  let escaped = false;
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (inQuotes && char === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (char === '"') {
+      inQuotes = !inQuotes;
+      continue;
+    }
+    if (!inQuotes && (char === "#" || char === ";") && isCommentStart(value, index)) {
+      return value.slice(0, index);
+    }
+  }
+  return value;
+}
+function isCommentStart(value, index) {
+  return index === 0 || /\s/.test(value[index - 1]);
+}
+async function isSubmoduleWorktree(rootDir, submodulePath) {
+  const dir = path14.join(rootDir, submodulePath);
+  try {
+    if (!await pathHasNoSymlinkSegments(rootDir, submodulePath)) {
+      return false;
+    }
+    const rootRealPath = await realpath(rootDir);
+    const dirRealPath = await realpath(dir);
+    if (!isInsideDirectory(rootRealPath, dirRealPath)) {
+      return false;
+    }
+    const dirStat = await lstat(dir);
+    if (!dirStat.isDirectory()) {
+      return false;
+    }
+    const gitMarkerStat = await lstat(path14.join(dir, ".git"));
+    return !gitMarkerStat.isSymbolicLink() && (gitMarkerStat.isFile() || gitMarkerStat.isDirectory());
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+async function pathHasNoSymlinkSegments(rootDir, submodulePath) {
+  let current = rootDir;
+  for (const part of submodulePath.split("/")) {
+    current = path14.join(current, part);
+    const partStat = await lstat(current);
+    if (partStat.isSymbolicLink()) {
+      return false;
+    }
+  }
+  return true;
+}
+function isInsideDirectory(parent, child) {
+  const relative = path14.relative(parent, child);
+  return Boolean(relative) && !relative.startsWith("..") && !path14.isAbsolute(relative);
+}
+
+// src/commands/supermodule-targets.ts
+function rejectSubmoduleListWithoutGitmodules(opts) {
+  if (typeof opts.submodules === "string") {
+    throw new Error("--submodules can only be used in a repository with .gitmodules.");
+  }
+}
+async function resolveAddAgentTargets(cwd, opts) {
+  const installedSubmodules = await listInstalledSubmodules(cwd);
+  if ((await parseGitmodules(cwd)).length === 0) {
+    rejectSubmoduleListWithoutGitmodules(opts);
+    return [standaloneTarget(cwd)];
+  }
+  const selected = await resolveSubmodules(opts, installedSubmodules);
+  const parentManagedSubmodulePaths = await listParentManagedSubmodulePaths(cwd);
+  const parentSubmodulePaths = [
+    .../* @__PURE__ */ new Set([...parentManagedSubmodulePaths, ...selected.map((entry) => entry.path)])
+  ].sort();
+  return [
+    parentTargetFromPaths(cwd, parentSubmodulePaths),
+    ...selected.map((entry) => childTarget(cwd, entry))
+  ];
+}
+async function resolveUpgradeTargets(cwd) {
+  const installedSubmodules = await listInstalledSubmodules(cwd);
+  if ((await parseGitmodules(cwd)).length === 0) {
+    return [standaloneTarget(cwd)];
+  }
+  return [
+    parentTarget(cwd, installedSubmodules),
+    ...installedSubmodules.map((entry) => childTarget(cwd, entry))
+  ];
+}
+async function resolveInitSubmoduleSelection(cwd, opts) {
+  const installable = await listInstallableSubmodules(cwd);
+  const installed = await listInstalledSubmodules(cwd);
+  const parentManagedSubmodulePaths = await listParentManagedSubmodulePaths(cwd);
+  const defaultSelection = installable;
+  const selected = await resolveSubmodules(opts, installable, defaultSelection);
+  const parentSubmodulePaths = [
+    .../* @__PURE__ */ new Set([...parentManagedSubmodulePaths, ...selected.map((entry) => entry.path)])
+  ].sort();
+  return { installable, installed, selected, parentSubmodulePaths };
+}
+async function resolveClearTargets(cwd, opts) {
+  if ((await parseGitmodules(cwd)).length === 0) {
+    rejectSubmoduleListWithoutGitmodules(opts);
+    return [standaloneTarget(cwd)];
+  }
+  const installedSubmodules = await listInstalledSubmodules(cwd);
+  const parent = await pathExists(path15.join(cwd, EASY_CODING_DIR)) ? parentTarget(cwd, installedSubmodules) : null;
+  const children = installedSubmodules.map((entry) => childTarget(cwd, entry));
+  if (opts.submodules === false) {
+    return parent ? [parent] : [];
+  }
+  if (typeof opts.submodules === "string") {
+    return [
+      ...parent ? [parent] : [],
+      ...parseSubmoduleSelection(opts.submodules, installedSubmodules).map(
+        (entry) => childTarget(cwd, entry)
+      )
+    ];
+  }
+  if (opts.yes) {
+    return parent ? [parent] : [];
+  }
+  const candidates = [...parent ? [parent] : [], ...children];
+  if (candidates.length === 0) {
+    return [];
+  }
+  const result = await multiselect2({
+    message: "Select Easy Coding harness targets to clear",
+    options: candidates.map((target) => ({
+      label: target.label === "." ? "parent repository" : `submodule: ${target.label}`,
+      value: target.label
+    })),
+    initialValues: parent ? [parent.label] : [],
+    required: true
+  });
+  if (typeof result === "symbol") {
+    cancel2("Clear target selection cancelled.");
+    process.exit(1);
+  }
+  const selected = new Set(result);
+  return candidates.filter((target) => selected.has(target.label));
+}
+async function listInstalledSubmodules(cwd) {
+  const entries = await listInstallableSubmodules(cwd);
+  const installed = [];
+  for (const entry of entries) {
+    if (await pathExists(configPath(path15.join(cwd, entry.path)))) {
+      installed.push(entry);
+    }
+  }
+  return installed;
+}
+async function listParentManagedSubmodulePaths(cwd) {
+  const parentConfigPath = configPath(cwd);
+  if (!await pathExists(parentConfigPath)) {
+    return [];
+  }
+  try {
+    const config = await readConfigYaml(parentConfigPath);
+    if (config.supermodule?.role !== "super-parent" || !Array.isArray(config.supermodule.submodules)) {
+      return [];
+    }
+    return config.supermodule.submodules.filter((submodulePath) => typeof submodulePath === "string").sort();
+  } catch {
+    return [];
+  }
+}
+function standaloneTarget(cwd) {
+  return {
+    dir: cwd,
+    label: ".",
+    configPath: configPath(cwd),
+    supermodule: { role: "standalone" }
+  };
+}
+function parentTarget(cwd, installedSubmodules) {
+  const submodulePaths = installedSubmodules.map((entry) => entry.path);
+  return parentTargetFromPaths(cwd, submodulePaths);
+}
+function parentTargetFromPaths(cwd, submodulePaths) {
+  return {
+    dir: cwd,
+    label: ".",
+    configPath: configPath(cwd),
+    supermodule: { role: "super-parent", submodules: submodulePaths },
+    boundary: { submodulePaths }
+  };
+}
+function childTarget(cwd, entry) {
+  const dir = path15.join(cwd, entry.path);
+  return {
+    dir,
+    label: entry.path,
+    configPath: configPath(dir),
+    supermodule: { role: "submodule-child", parent: toPosixRelative(dir, cwd) }
+  };
+}
+function parseSubmoduleSelection(submoduleList, available) {
+  const requested = submoduleList.split(",").map((value) => value.trim()).filter(Boolean);
+  if (requested.length === 0) {
+    throw new Error("No submodule specified.");
+  }
+  const byPathOrName = /* @__PURE__ */ new Map();
+  for (const submodule of available) {
+    byPathOrName.set(submodule.path, submodule);
+    byPathOrName.set(submodule.name, submodule);
+  }
+  const selected = [];
+  const invalid = [];
+  for (const value of requested) {
+    const submodule = byPathOrName.get(value);
+    if (!submodule) {
+      invalid.push(value);
+      continue;
+    }
+    if (!selected.some((item) => item.path === submodule.path)) {
+      selected.push(submodule);
     }
-    selectedDefaults = result;
   }
+  if (invalid.length > 0) {
+    throw new Error(`Unknown or unavailable initialized submodule: ${invalid.join(", ")}`);
+  }
+  return selected.sort((a, b) => a.path.localeCompare(b.path));
+}
+function configPath(cwd) {
+  return path15.join(cwd, EASY_CODING_DIR, CONFIG_FILE);
+}
+function toPosixRelative(from, to) {
+  const relative = path15.relative(from, to);
+  return relative ? relative.split(path15.sep).join("/") : ".";
 }
 
 // src/commands/add-agent.ts
 async function addAgent(opts) {
   renderBanner();
   const cwd = process.cwd();
-  const configPath = path13.join(cwd, EASY_CODING_DIR, CONFIG_FILE);
-  if (!await pathExists(configPath)) {
+  const targets = await resolveAddAgentTargets(cwd, opts);
+  if (!await pathExists(targets[0].configPath)) {
     throw new Error("No .easy-coding/config.yaml found. Run easy-coding init first.");
   }
-  const config = await readConfigYaml(configPath);
   const platforms = await resolvePlatforms(opts, ["claude-code"]);
-  const toInstall = platforms.filter((platform) => !config.agents.includes(platform));
-  if (toInstall.length === 0) {
+  const installedLabels = [];
+  const refreshedLabels = [];
+  for (const target of targets) {
+    if (!await pathExists(target.configPath)) {
+      continue;
+    }
+    const config = await readConfigYaml(target.configPath);
+    const toInstall = platforms.filter((platform) => !config.agents.includes(platform));
+    const agents = [...config.agents, ...toInstall];
+    if (toInstall.length > 0) {
+      const artifacts = await configurePlatformsForDir(
+        target.dir,
+        toInstall,
+        target.boundary
+      );
+      await writeRuntimeScaffold(target.dir, agents, {
+        supermodule: target.supermodule
+      });
+      await writeInstallManifest(target.dir, {
+        harnessVersion: VERSION,
+        agents: toInstall,
+        artifacts,
+        mode: "merge"
+      });
+      await ensureEasyCodingSessionsIgnored(target.dir);
+      await addAgentsToConfig(target.configPath, toInstall);
+      await setPendingInitSince(target.dir, VERSION);
+      installedLabels.push(`${target.label}: ${toInstall.join(", ")}`);
+    }
+    if (target.supermodule.role === "super-parent") {
+      await refreshSupermoduleParent(target.dir, agents, target.supermodule.submodules ?? []);
+      refreshedLabels.push(target.label);
+      continue;
+    }
+    if (target.supermodule.role === "submodule-child") {
+      await updateSupermoduleConfig(target.configPath, target.supermodule);
+      refreshedLabels.push(target.label);
+    }
+  }
+  if (installedLabels.length === 0) {
+    if (refreshedLabels.length > 0) {
+      outro(chalk2.green(`Supermodule topology refreshed:
+${refreshedLabels.join("\n")}`));
+      return;
+    }
     outro(chalk2.yellow("All selected agent platforms are already installed."));
     return;
   }
-  const artifacts = [];
-  for (const platform of toInstall) {
-    artifacts.push(...await CONFIGURATORS[platform](cwd));
-  }
-  await writeRuntimeScaffold(cwd, [...config.agents, ...toInstall]);
-  await writeInstallManifest(cwd, {
-    harnessVersion: VERSION,
-    agents: toInstall,
-    artifacts,
-    mode: "merge"
-  });
-  await ensureEasyCodingSessionsIgnored(cwd);
-  await addAgentsToConfig(configPath, toInstall);
-  await setPendingInitSince(cwd, VERSION);
-  outro(chalk2.green(`Added agent platforms: ${toInstall.join(", ")}`));
+  outro(chalk2.green(`Added agent platforms:
+${installedLabels.join("\n")}`));
 }
 
 // src/commands/clear.ts
 import { readdir as readdir4, rm, writeFile } from "fs/promises";
-import path14 from "path";
-import { cancel as cancel2, confirm as confirm2, outro as outro2 } from "@clack/prompts";
+import path16 from "path";
+import { cancel as cancel3, confirm as confirm2, outro as outro2 } from "@clack/prompts";
 import chalk3 from "chalk";
 var PLATFORM_TEMPLATE_DIR = {
   "claude-code": "claude",
@@ -1095,13 +1708,12 @@ var PLATFORM_TEMPLATE_DIR = {
 async function clear(opts) {
   renderBanner();
   const cwd = process.cwd();
-  const easyCodingDir = path14.join(cwd, EASY_CODING_DIR);
-  if (!await pathExists(easyCodingDir)) {
+  const targets = await resolveClearTargets(cwd, opts);
+  const targetPlans = await buildTargetClearPlans(targets);
+  if (targetPlans.length === 0) {
     throw new Error("No .easy-coding directory found in this project \u2014 nothing to clear.");
   }
-  const agents = await resolveInstalledAgents(cwd);
-  const plan = await buildClearPlan(cwd, agents);
-  console.log(renderPlan(cwd, agents, plan));
+  console.log(renderTargetPlans(targetPlans));
   if (opts.dryRun) {
     return;
   }
@@ -1111,18 +1723,54 @@ async function clear(opts) {
       initialValue: false
     });
     if (typeof ok === "symbol" || !ok) {
-      cancel2("Clear cancelled.");
+      cancel3("Clear cancelled.");
       return;
     }
   }
-  await executeClearPlan(plan);
+  for (const targetPlan of targetPlans) {
+    await executeClearPlan(targetPlan.plan);
+  }
+  await refreshParentAfterChildClear(cwd, targetPlans);
   outro2(chalk3.green("Easy Coding harness removed. Run easy-coding init to reinstall."));
 }
+async function buildTargetClearPlans(targets) {
+  const plans = [];
+  for (const target of targets) {
+    const easyCodingDir = path16.join(target.dir, EASY_CODING_DIR);
+    if (!await pathExists(easyCodingDir)) {
+      continue;
+    }
+    const agents = await resolveInstalledAgents(target.dir);
+    plans.push({
+      target,
+      agents,
+      plan: await buildClearPlan(target.dir, agents)
+    });
+  }
+  return plans;
+}
+async function refreshParentAfterChildClear(cwd, targetPlans) {
+  if (targetPlans.some((targetPlan) => targetPlan.target.label === ".")) {
+    return;
+  }
+  if (!await pathExists(path16.join(cwd, EASY_CODING_DIR, CONFIG_FILE))) {
+    return;
+  }
+  const [parent] = await resolveUpgradeTargets(cwd);
+  if (!parent || parent.label !== ".") {
+    return;
+  }
+  const config = await readConfigYaml(parent.configPath);
+  if (!Array.isArray(config.agents) || config.agents.length === 0) {
+    return;
+  }
+  await refreshSupermoduleParent(cwd, config.agents, parent.supermodule.submodules ?? []);
+}
 async function resolveInstalledAgents(cwd) {
-  const configPath = path14.join(cwd, EASY_CODING_DIR, CONFIG_FILE);
-  if (await pathExists(configPath)) {
+  const configPath2 = path16.join(cwd, EASY_CODING_DIR, CONFIG_FILE);
+  if (await pathExists(configPath2)) {
     try {
-      const config = await readConfigYaml(configPath);
+      const config = await readConfigYaml(configPath2);
       const listed = Array.isArray(config.agents) ? config.agents.filter(isAgentPlatform) : [];
       if (listed.length > 0) {
         return listed;
@@ -1150,7 +1798,7 @@ async function hasPlatformInstall(cwd, platform) {
 async function hasInstallMarkers(cwd, meta) {
   const markers = [meta.skillsDir, meta.hooksDir, meta.agentsDir, meta.hookConfigFile];
   for (const marker of markers) {
-    if (await pathExists(path14.join(cwd, marker))) {
+    if (await pathExists(path16.join(cwd, marker))) {
       return true;
     }
   }
@@ -1206,7 +1854,7 @@ async function buildManifestClearPlan(cwd, agents, manifest) {
     }
     if (await manifestFileMatches(filePath, file.sha256)) {
       plan.removeFiles.push({ filePath, expectedSha256: file.sha256 });
-      addEmptyDirChain(plan.emptyDirs, path14.dirname(filePath), cwd);
+      addEmptyDirChain(plan.emptyDirs, path16.dirname(filePath), cwd);
     } else {
       plan.skippedModified.push(filePath);
     }
@@ -1215,11 +1863,12 @@ async function buildManifestClearPlan(cwd, agents, manifest) {
     if (!agentSet.has(registration.platform)) {
       continue;
     }
+    const managedHookPaths = registration.hook_path ? managedHookPathsForRegistration(cwd, registration.hook_path) : [];
     addHookConfigPrune(
       plan.pruneHookConfigs,
       plan.pruneHookCommands,
       manifestPath(cwd, registration.config_path),
-      registration.hook_path ? [registration.hook_path] : [],
+      managedHookPaths,
       [registration.command]
     );
   }
@@ -1255,28 +1904,28 @@ async function addTemplateClearEntries(plan, cwd, platform, metas, managedSkills
   );
   for (const meta of metas) {
     for (const name of managedSkills) {
-      plan.remove.add(path14.join(cwd, meta.skillsDir, name));
+      plan.remove.add(path16.join(cwd, meta.skillsDir, name));
     }
     for (const name of hookFileNames) {
-      plan.remove.add(path14.join(cwd, meta.hooksDir, name));
+      plan.remove.add(path16.join(cwd, meta.hooksDir, name));
     }
     for (const name of agentFileNames) {
-      plan.remove.add(path14.join(cwd, meta.agentsDir, name));
+      plan.remove.add(path16.join(cwd, meta.agentsDir, name));
     }
     addHookConfigPrune(
       plan.pruneHookConfigs,
       plan.pruneHookCommands,
-      path14.join(cwd, meta.hookConfigFile),
-      hookFileNames.map((name) => `${meta.templateContext.platform_config_dir}/hooks/${name}`),
+      path16.join(cwd, meta.hookConfigFile),
+      managedHookPathsForTemplate(cwd, meta, hookFileNames),
       []
     );
-    plan.constraints.add(path14.join(cwd, meta.mainConstraint));
+    plan.constraints.add(path16.join(cwd, meta.mainConstraint));
     if (platform === "codex") {
-      plan.remove.add(path14.join(cwd, meta.templateContext.platform_config_dir, "config.toml"));
+      plan.remove.add(path16.join(cwd, meta.templateContext.platform_config_dir, "config.toml"));
     }
-    plan.emptyDirs.add(path14.join(cwd, meta.skillsDir));
-    plan.emptyDirs.add(path14.join(cwd, meta.hooksDir));
-    plan.emptyDirs.add(path14.join(cwd, meta.agentsDir));
+    plan.emptyDirs.add(path16.join(cwd, meta.skillsDir));
+    plan.emptyDirs.add(path16.join(cwd, meta.hooksDir));
+    plan.emptyDirs.add(path16.join(cwd, meta.agentsDir));
   }
 }
 async function resolveManifestUncoveredQoderMetas(cwd, manifest) {
@@ -1318,6 +1967,51 @@ function addHookConfigPrune(pruneHookConfigs, pruneHookCommands, filePath, manag
   }
   pruneHookCommands.set(filePath, existingCommands);
 }
+function managedHookPathsForRegistration(cwd, hookPath) {
+  const paths = [hookPath];
+  try {
+    paths.push(...managedHookPathTokens(manifestPath(cwd, hookPath)));
+  } catch {
+    if (path16.isAbsolute(hookPath)) {
+      paths.push(...managedHookPathTokens(hookPath));
+    }
+  }
+  return paths;
+}
+function managedHookPathsForTemplate(cwd, meta, hookFileNames) {
+  const relativePaths = hookFileNames.map(
+    (name) => `${meta.templateContext.platform_config_dir}/hooks/${name}`
+  );
+  const absolutePaths = hookFileNames.flatMap(
+    (name) => managedHookPathTokens(path16.join(cwd, meta.hooksDir, name))
+  );
+  return [...relativePaths, ...absolutePaths];
+}
+function managedHookPathTokens(filePath) {
+  const tokens = /* @__PURE__ */ new Set();
+  for (const equivalentPath of equivalentAbsolutePaths(filePath)) {
+    const normalized = equivalentPath.replace(/\\/g, "/");
+    const dir = path16.posix.dirname(normalized);
+    const basename = path16.posix.basename(normalized);
+    tokens.add(normalized);
+    tokens.add(shellDoubleQuoteArg2(normalized));
+    tokens.add(`${shellDoubleQuoteArg2(dir)}/${basename}`);
+  }
+  return [...tokens];
+}
+function equivalentAbsolutePaths(filePath) {
+  const normalized = path16.resolve(filePath).replace(/\\/g, "/");
+  const equivalents = [normalized];
+  if (normalized.startsWith("/private/var/")) {
+    equivalents.push(normalized.replace(/^\/private\/var\//, "/var/"));
+  } else if (normalized.startsWith("/var/")) {
+    equivalents.push(normalized.replace(/^\/var\//, "/private/var/"));
+  }
+  return equivalents;
+}
+function shellDoubleQuoteArg2(value) {
+  return `"${value.replace(/(["\\$`])/g, "\\$1")}"`;
+}
 function createClearPlan() {
   return {
     remove: /* @__PURE__ */ new Set(),
@@ -1380,27 +2074,27 @@ function addRuntimeClearEntries(plan, cwd) {
   plan.remove = [
     .../* @__PURE__ */ new Set([
       ...plan.remove,
-      path14.join(cwd, EASY_CODING_DIR, CONFIG_FILE),
-      path14.join(cwd, EASY_CODING_DIR, SESSIONS_DIR),
-      path14.join(cwd, EASY_CODING_DIR, TEMPLATES_DIR),
-      path14.join(cwd, EASY_CODING_DIR, INSTALL_MANIFEST_FILE)
+      path16.join(cwd, EASY_CODING_DIR, CONFIG_FILE),
+      path16.join(cwd, EASY_CODING_DIR, SESSIONS_DIR),
+      path16.join(cwd, EASY_CODING_DIR, TEMPLATES_DIR),
+      path16.join(cwd, EASY_CODING_DIR, INSTALL_MANIFEST_FILE)
     ])
   ];
 }
 function addEmptyDirChain(emptyDirs, startDir, cwd) {
   let current = startDir;
-  while (current !== cwd && isInsideDirectory(cwd, current)) {
+  while (current !== cwd && isInsideDirectory2(cwd, current)) {
     emptyDirs.add(current);
-    const parent = path14.dirname(current);
+    const parent = path16.dirname(current);
     if (parent === current) {
       break;
     }
     current = parent;
   }
 }
-function isInsideDirectory(parent, child) {
-  const relative = path14.relative(parent, child);
-  return Boolean(relative) && !relative.startsWith("..") && !path14.isAbsolute(relative);
+function isInsideDirectory2(parent, child) {
+  const relative = path16.relative(parent, child);
+  return Boolean(relative) && !relative.startsWith("..") && !path16.isAbsolute(relative);
 }
 async function listSharedHookNamesForPlatform(platform) {
   const names = await listFileNames(getTemplatePath("shared-hooks"));
@@ -1502,7 +2196,7 @@ function isManagedHook(hook, managedHookPaths, managedHookCommands) {
   if (normalizedManagedCommands.includes(normalizeCommand(command))) {
     return true;
   }
-  const normalizedCommand = command.replace(/\\/g, "/");
+  const normalizedCommand = command;
   return managedHookPaths.some(
     (hookPath) => commandContainsPathToken(normalizedCommand, hookPath.replace(/\\/g, "/"))
   );
@@ -1537,7 +2231,7 @@ function sortDirsDeepestFirst(dirs) {
   });
 }
 function pathDepth(dir) {
-  return path14.normalize(dir).split(path14.sep).filter(Boolean).length;
+  return path16.normalize(dir).split(path16.sep).filter(Boolean).length;
 }
 async function listDirNames(dir) {
   try {
@@ -1556,7 +2250,7 @@ async function listFileNames(dir) {
   }
 }
 function renderPlan(cwd, agents, plan) {
-  const rel = (target) => path14.relative(cwd, target) || target;
+  const rel = (target) => path16.relative(cwd, target) || target;
   const lines = [];
   lines.push(chalk3.bold("easy-coding clear"));
   lines.push(`Platforms: ${agents.length > 0 ? agents.join(", ") : "(none detected)"}`);
@@ -1594,23 +2288,33 @@ function renderPlan(cwd, agents, plan) {
   );
   return lines.join("\n");
 }
+function renderTargetPlans(targetPlans) {
+  if (targetPlans.length === 1) {
+    const [{ target, agents, plan }] = targetPlans;
+    return [`Target: ${target.label}`, renderPlan(target.dir, agents, plan)].join("\n");
+  }
+  return targetPlans.map(
+    ({ target, agents, plan }) => [`Target: ${target.label}`, renderPlan(target.dir, agents, plan)].join("\n")
+  ).join("\n\n");
+}
 
 // src/commands/init.ts
+import path18 from "path";
 import { note, outro as outro3 } from "@clack/prompts";
 import chalk4 from "chalk";
 
 // src/utils/install-state.ts
 import { readdir as readdir5 } from "fs/promises";
-import path15 from "path";
+import path17 from "path";
 var LEGACY_ROOT_FILES = ["SOUL.md", "RULES.md", "ABSTRACT.md"];
 async function detectEasyCodingInstallState(cwd) {
-  const easyCodingDir = path15.join(cwd, EASY_CODING_DIR);
+  const easyCodingDir = path17.join(cwd, EASY_CODING_DIR);
   if (!await pathExists(easyCodingDir)) {
     return { kind: "fresh", easyCodingDir };
   }
-  const configPath = path15.join(easyCodingDir, CONFIG_FILE);
-  if (await pathExists(configPath)) {
-    return { kind: "installed", easyCodingDir, configPath };
+  const configPath2 = path17.join(easyCodingDir, CONFIG_FILE);
+  if (await pathExists(configPath2)) {
+    return { kind: "installed", easyCodingDir, configPath: configPath2 };
   }
   const legacyAssets = await detectLegacyAssets(easyCodingDir);
   if (legacyAssets.length === 0) {
@@ -1626,17 +2330,17 @@ async function detectEasyCodingInstallState(cwd) {
 async function detectLegacyAssets(easyCodingDir) {
   const assets = [];
   for (const file of LEGACY_ROOT_FILES) {
-    if (await pathExists(path15.join(easyCodingDir, file))) {
+    if (await pathExists(path17.join(easyCodingDir, file))) {
       assets.push(relativeEasyCodingPath(file));
     }
   }
-  if (await pathExists(path15.join(easyCodingDir, "memory", "long", "MEMORY.md"))) {
+  if (await pathExists(path17.join(easyCodingDir, "memory", "long", "MEMORY.md"))) {
     assets.push(relativeEasyCodingPath("memory", "long", "MEMORY.md"));
   }
-  const shortMemoryFiles = await listMarkdownFiles(path15.join(easyCodingDir, "memory", "short"));
+  const shortMemoryFiles = await listMarkdownFiles(path17.join(easyCodingDir, "memory", "short"));
   assets.push(...shortMemoryFiles.map((file) => relativeEasyCodingPath("memory", "short", file)));
   for (const dir of ["spec", "prototype"]) {
-    if (await hasAnyDirectoryEntry(path15.join(easyCodingDir, dir))) {
+    if (await hasAnyDirectoryEntry(path17.join(easyCodingDir, dir))) {
       assets.push(relativeEasyCodingPath(dir));
     }
   }
@@ -1656,19 +2360,54 @@ async function hasAnyDirectoryEntry(dir) {
   return (await readdir5(dir)).length > 0;
 }
 function relativeEasyCodingPath(...segments) {
-  return path15.posix.join(EASY_CODING_DIR, ...segments);
+  return path17.posix.join(EASY_CODING_DIR, ...segments);
 }
 function relativeConfigPath() {
-  return path15.posix.join(EASY_CODING_DIR, CONFIG_FILE);
+  return path17.posix.join(EASY_CODING_DIR, CONFIG_FILE);
 }
 function relativeProjectInitTaskPath() {
-  return path15.posix.join(EASY_CODING_DIR, TASKS_DIR, PROJECT_INIT_TASK_ID, "task.json");
+  return path17.posix.join(EASY_CODING_DIR, TASKS_DIR, PROJECT_INIT_TASK_ID, "task.json");
 }
 
 // src/commands/init.ts
 async function init(opts) {
   renderBanner();
   const cwd = process.cwd();
+  const submodules = await parseGitmodules(cwd);
+  if (submodules.length === 0) {
+    rejectSubmoduleListWithoutGitmodules(opts);
+  }
+  const targets = submodules.length === 0 ? [await standaloneTarget2(cwd)] : await supermoduleTargets(cwd, opts, submodules);
+  const installableTargets = targets.filter((target) => !target.installed);
+  const parentTarget2 = targets.find((target) => target.label === ".");
+  if (installableTargets.length === 0) {
+    await refreshInstalledChildTopologies(targets);
+    if (submodules.length > 0 && parentTarget2) {
+      const platforms2 = await resolveInitPlatforms(cwd, opts, true);
+      await refreshParentTopologyIfNeeded(cwd, parentTarget2, platforms2);
+    }
+    outro3(chalk4.yellow("All selected easy-coding harness targets are already installed."));
+    return;
+  }
+  const platforms = await resolveInitPlatforms(cwd, opts, Boolean(parentTarget2?.installed));
+  for (const target of installableTargets) {
+    await installHarnessToDir(target.dir, platforms, target.context);
+  }
+  await refreshInstalledChildTopologies(targets);
+  if (submodules.length > 0 && parentTarget2) {
+    await refreshParentTopologyIfNeeded(cwd, parentTarget2, platforms);
+  }
+  const triggers = platforms.map(
+    (platform) => `${PLATFORM_META[platform].label}: ${PLATFORM_META[platform].skillTrigger}ec-init`
+  ).join("\n");
+  note(triggers, "Next step");
+  outro3(
+    chalk4.green(
+      `easy-coding harness installed in ${installableTargets.map((target) => target.label).join(", ")}. Open your agent and run ec-init.`
+    )
+  );
+}
+async function standaloneTarget2(cwd) {
   const installState = await detectEasyCodingInstallState(cwd);
   if (installState.kind === "installed") {
     throw new Error(
@@ -1680,36 +2419,121 @@ async function init(opts) {
       ".easy-coding exists but is not recognized as an easy-coding harness or legacy easy-coding skill project. Please inspect it manually before running init."
     );
   }
-  const platforms = await resolvePlatforms(opts, ["claude-code"]);
-  const artifacts = [];
-  for (const platform of platforms) {
-    artifacts.push(...await CONFIGURATORS[platform](cwd));
+  return {
+    dir: cwd,
+    label: ".",
+    context: contextFromState("standalone", installState),
+    installed: false
+  };
+}
+async function supermoduleTargets(cwd, opts, submodules) {
+  const { installable, parentSubmodulePaths } = await resolveInitSubmoduleSelection(cwd, opts);
+  const skipped = submodules.filter(
+    (entry) => !installable.some((installableEntry) => installableEntry.path === entry.path)
+  );
+  if (skipped.length > 0) {
+    note(
+      skipped.map((entry) => `${entry.path} (${entry.name})`).join("\n"),
+      "Skipped unchecked-out submodules"
+    );
   }
-  await writeRuntimeScaffold(cwd, platforms);
-  await writeInstallManifest(cwd, {
-    harnessVersion: VERSION,
-    agents: platforms,
-    artifacts
-  });
-  await writeProjectInitTask(cwd, platforms, {
+  const targets = [
+    await targetFromState(cwd, ".", "super-parent", {
+      submodulePaths: parentSubmodulePaths
+    })
+  ];
+  const targetSubmodulePaths = opts.submodules === false ? /* @__PURE__ */ new Set() : new Set(parentSubmodulePaths);
+  for (const entry of installable) {
+    if (!targetSubmodulePaths.has(entry.path)) {
+      continue;
+    }
+    const dir = path18.join(cwd, entry.path);
+    targets.push(
+      await targetFromState(dir, entry.path, "submodule-child", {
+        parent: toPosixRelative2(dir, cwd)
+      })
+    );
+  }
+  return targets;
+}
+async function targetFromState(targetDir, label, role, extraContext = {}) {
+  const installState = await detectEasyCodingInstallState(targetDir);
+  if (installState.kind === "unknown") {
+    throw new Error(
+      `${targetDir}/.easy-coding exists but is not recognized as an easy-coding harness or legacy easy-coding skill project. Please inspect it manually before running init.`
+    );
+  }
+  if (installState.kind === "installed") {
+    return {
+      dir: targetDir,
+      label,
+      installed: true,
+      context: {
+        role,
+        initSource: "fresh",
+        ...extraContext
+      }
+    };
+  }
+  return {
+    dir: targetDir,
+    label,
+    installed: false,
+    context: {
+      ...contextFromState(role, installState),
+      ...extraContext
+    }
+  };
+}
+function contextFromState(role, installState) {
+  return {
+    role,
     initSource: installState.kind === "legacy" ? "legacy-easy-coding" : "fresh",
     legacyAssets: installState.kind === "legacy" ? installState.legacyAssets : void 0,
     legacyMissingHarnessFiles: installState.kind === "legacy" ? installState.missingHarnessFiles : void 0
-  });
-  await ensureEasyCodingSessionsIgnored(cwd);
-  const triggers = platforms.map(
-    (platform) => `${PLATFORM_META[platform].label}: ${PLATFORM_META[platform].skillTrigger}ec-init`
-  ).join("\n");
-  note(triggers, "Next step");
-  outro3(chalk4.green("easy-coding harness installed. Open your agent and run ec-init."));
+  };
+}
+function toPosixRelative2(from, to) {
+  const relative = path18.relative(from, to);
+  return relative ? relative.split(path18.sep).join("/") : ".";
+}
+async function resolveInitPlatforms(cwd, opts, parentInstalled) {
+  if (opts.agent || !parentInstalled) {
+    return resolvePlatforms(opts, ["claude-code"]);
+  }
+  const config = await readConfigYaml(path18.join(cwd, EASY_CODING_DIR, CONFIG_FILE));
+  if (Array.isArray(config.agents) && config.agents.length > 0) {
+    return config.agents;
+  }
+  return resolvePlatforms(opts, ["claude-code"]);
+}
+async function refreshParentTopologyIfNeeded(cwd, parentTarget2, installPlatforms) {
+  if (!await pathExists(path18.join(cwd, EASY_CODING_DIR, CONFIG_FILE))) {
+    return;
+  }
+  const config = parentTarget2.installed ? await readConfigYaml(path18.join(cwd, EASY_CODING_DIR, CONFIG_FILE)) : { agents: installPlatforms };
+  const platforms = Array.isArray(config.agents) && config.agents.length > 0 ? config.agents : installPlatforms;
+  await refreshSupermoduleParent(cwd, platforms, parentTarget2.context.submodulePaths ?? []);
+}
+async function refreshInstalledChildTopologies(targets) {
+  for (const target of targets) {
+    if (!target.installed || target.context.role !== "submodule-child") {
+      continue;
+    }
+    const configPath2 = path18.join(target.dir, EASY_CODING_DIR, CONFIG_FILE);
+    if (!await pathExists(configPath2)) {
+      continue;
+    }
+    await updateSupermoduleConfig(configPath2, supermoduleConfigFromContext(target.context));
+  }
 }
 
 // src/commands/status.ts
-import path18 from "path";
+import path21 from "path";
 import chalk5 from "chalk";
 
 // src/utils/compare-versions.ts
-import path16 from "path";
+import path19 from "path";
 function normalize(version) {
   const [core] = String(version ?? "").split("-");
   return core.split(".").map((part) => {
@@ -1733,13 +2557,13 @@ function isVersionBehind(installed, current = VERSION) {
   return compareVersions(installed, current) === -1;
 }
 async function checkForUpgrade(cwd) {
-  const configPath = path16.join(cwd, EASY_CODING_DIR, CONFIG_FILE);
-  if (!await pathExists(configPath)) {
+  const configPath2 = path19.join(cwd, EASY_CODING_DIR, CONFIG_FILE);
+  if (!await pathExists(configPath2)) {
     return;
   }
   let config;
   try {
-    config = await readConfigYaml(configPath);
+    config = await readConfigYaml(configPath2);
   } catch {
     return;
   }
@@ -1754,14 +2578,14 @@ async function checkForUpgrade(cwd) {
 
 // src/utils/session.ts
 import { readdir as readdir6 } from "fs/promises";
-import path17 from "path";
+import path20 from "path";
 var STALE_THRESHOLD_MS = 24 * 60 * 60 * 1e3;
 function getSessionDir(cwd) {
-  return path17.join(cwd, EASY_CODING_DIR, SESSIONS_DIR);
+  return path20.join(cwd, EASY_CODING_DIR, SESSIONS_DIR);
 }
 function getSessionFilePath(cwd, ppid) {
   const pid = ppid ?? process.ppid;
-  return path17.join(getSessionDir(cwd), `${pid}.json`);
+  return path20.join(getSessionDir(cwd), `${pid}.json`);
 }
 async function readSessionFile(cwd, ppid) {
   const content = await readTextIfExists(getSessionFilePath(cwd, ppid));
@@ -1775,11 +2599,11 @@ async function readSessionFile(cwd, ppid) {
 async function status() {
   renderBanner();
   const cwd = process.cwd();
-  const configPath = path18.join(cwd, EASY_CODING_DIR, CONFIG_FILE);
-  if (!await pathExists(configPath)) {
+  const configPath2 = path21.join(cwd, EASY_CODING_DIR, CONFIG_FILE);
+  if (!await pathExists(configPath2)) {
     throw new Error("No easy-coding harness found in this project.");
   }
-  const config = await readConfigYaml(configPath);
+  const config = await readConfigYaml(configPath2);
   const tasks = await listTasks(cwd);
   const taskCounts = summarizeTaskStatuses(tasks);
   const activeTasks = tasks.filter((item) => isActiveTask(item.task));
@@ -1829,7 +2653,7 @@ async function status() {
 
 // src/commands/update.ts
 import { execFileSync } from "child_process";
-import { cancel as cancel3, confirm as confirm3, outro as outro4 } from "@clack/prompts";
+import { cancel as cancel4, confirm as confirm3, outro as outro4 } from "@clack/prompts";
 import chalk6 from "chalk";
 async function update(opts) {
   renderBanner();
@@ -1848,7 +2672,7 @@ async function update(opts) {
       initialValue: true
     });
     if (typeof confirmed === "symbol" || !confirmed) {
-      cancel3("Update cancelled.");
+      cancel4("Update cancelled.");
       return;
     }
   }
@@ -1858,37 +2682,62 @@ async function update(opts) {
 }
 
 // src/commands/upgrade.ts
-import path19 from "path";
-import { cancel as cancel4, confirm as confirm4, outro as outro5 } from "@clack/prompts";
+import path22 from "path";
+import { cancel as cancel5, confirm as confirm4, outro as outro5 } from "@clack/prompts";
 import chalk7 from "chalk";
+var EXPECTED_HOOK_REGISTRATION_SCRIPTS = {
+  "claude-code": [
+    { event: "SessionStart", scriptName: "session-start.py" },
+    { event: "UserPromptSubmit", scriptName: "session-start.py" },
+    { event: "UserPromptSubmit", scriptName: "inject-workflow-state.py" },
+    { event: "PreToolUse", scriptName: "inject-subagent-context.py" }
+  ],
+  codex: [
+    { event: "UserPromptSubmit", scriptName: "session-start.py" },
+    { event: "UserPromptSubmit", scriptName: "inject-workflow-state.py" }
+  ],
+  qoder: [
+    { event: "UserPromptSubmit", scriptName: "session-start.py" },
+    { event: "UserPromptSubmit", scriptName: "inject-workflow-state.py" },
+    { event: "PreToolUse", scriptName: "inject-subagent-context.py" }
+  ]
+};
+var MANAGED_HOOK_SCRIPT_NAMES = {
+  "claude-code": [
+    ...new Set(
+      EXPECTED_HOOK_REGISTRATION_SCRIPTS["claude-code"].map(({ scriptName }) => scriptName)
+    )
+  ],
+  codex: [...new Set(EXPECTED_HOOK_REGISTRATION_SCRIPTS.codex.map(({ scriptName }) => scriptName))],
+  qoder: [...new Set(EXPECTED_HOOK_REGISTRATION_SCRIPTS.qoder.map(({ scriptName }) => scriptName))]
+};
 async function upgrade(opts) {
   renderBanner();
   const cwd = process.cwd();
-  const configPath = path19.join(cwd, EASY_CODING_DIR, CONFIG_FILE);
-  if (!await pathExists(configPath)) {
+  const targets = await resolveUpgradeTargets(cwd);
+  if (!await pathExists(targets[0].configPath)) {
     throw new Error("No .easy-coding/config.yaml found. Run easy-coding init first.");
   }
-  const config = await readConfigYaml(configPath);
-  const installedVersion = String(config.harness_version ?? "");
-  const hasAgents = Array.isArray(config.agents) && config.agents.length > 0;
-  if (!installedVersion || !hasAgents) {
-    throw new Error(
-      "config.yaml is missing required harness fields (harness_version / agents). This project predates the current config layout. Run `easy-coding clear` then `easy-coding init` to migrate \u2014 your tasks, spec, and memory are preserved."
-    );
-  }
-  const relation = compareVersions(installedVersion, VERSION);
-  if (relation === 0) {
+  const pending = await resolvePendingUpgradeTargets(targets);
+  const parentTopologyRefresh = await resolveParentTopologyRefresh(targets, pending);
+  const childTopologyRefreshes = await resolveChildTopologyRefreshes(targets, pending);
+  if (pending.length === 0 && !parentTopologyRefresh && childTopologyRefreshes.length === 0) {
     outro5(chalk7.green(`easy-coding harness is already up to date (${VERSION}).`));
     return;
   }
-  if (relation === 1) {
-    throw new Error(
-      `Project harness version ${installedVersion} is newer than CLI ${VERSION}. Update the CLI first.`
-    );
-  }
   const summary = [
-    `Upgrade: ${installedVersion || "unknown"} -> ${VERSION}`,
-    `Installed agents: ${config.agents.join(", ")}`,
+    "Upgrade targets:",
+    ...pending.length > 0 ? pending.map(
+      ({ target, config }) => `- ${target.label}: ${String(config.harness_version ?? "unknown")} -> ${VERSION}; agents: ${config.agents.join(", ")}`
+    ) : ["- (none)"],
+    ...parentTopologyRefresh ? [
+      "Supermodule topology refresh:",
+      `- ${parentTopologyRefresh.target.label}: submodules: ${parentTopologyRefresh.submodulePaths.length > 0 ? parentTopologyRefresh.submodulePaths.join(", ") : "(none)"}`
+    ] : [],
+    ...childTopologyRefreshes.length > 0 ? [
+      parentTopologyRefresh ? "" : "Supermodule topology refresh:",
+      ...childTopologyRefreshes.map(({ target }) => `- ${target.label}: role: submodule-child`)
+    ].filter(Boolean) : [],
     "Will overwrite managed skills, hooks, agents, templates, and generated main-constraint regions.",
     "Will update project-init task to recommend ec-init re-run for version adaptation.",
     "Will not touch memory, state, spec, or project knowledge files."
@@ -1903,24 +2752,256 @@ async function upgrade(opts) {
       initialValue: true
     });
     if (typeof shouldUpgrade === "symbol" || !shouldUpgrade) {
-      cancel4("Upgrade cancelled.");
+      cancel5("Upgrade cancelled.");
       return;
     }
   }
-  const artifacts = [];
-  for (const platform of config.agents) {
-    artifacts.push(...await CONFIGURATORS[platform](cwd));
+  for (const { target, config } of pending) {
+    const artifacts = await configurePlatformsForDir(
+      target.dir,
+      config.agents,
+      target.boundary
+    );
+    await writeRuntimeScaffold(target.dir, config.agents, {
+      supermodule: target.supermodule
+    });
+    await writeInstallManifest(target.dir, {
+      harnessVersion: VERSION,
+      agents: config.agents,
+      artifacts
+    });
+    await ensureEasyCodingSessionsIgnored(target.dir);
+    await updateHarnessVersion(target.configPath, VERSION);
+    await updateSupermoduleConfig(target.configPath, target.supermodule);
+    await setPendingInitSince(target.dir, VERSION);
+  }
+  if (parentTopologyRefresh) {
+    await refreshSupermoduleParent(
+      parentTopologyRefresh.target.dir,
+      parentTopologyRefresh.agents,
+      parentTopologyRefresh.submodulePaths
+    );
   }
-  await writeRuntimeScaffold(cwd, config.agents);
-  await writeInstallManifest(cwd, {
-    harnessVersion: VERSION,
-    agents: config.agents,
-    artifacts
+  for (const { target } of childTopologyRefreshes) {
+    await updateSupermoduleConfig(target.configPath, target.supermodule);
+  }
+  outro5(
+    chalk7.green(
+      pending.length > 0 ? `easy-coding harness upgraded to ${VERSION}.` : "easy-coding supermodule topology refreshed."
+    )
+  );
+}
+async function resolvePendingUpgradeTargets(targets) {
+  const pending = [];
+  for (const target of targets) {
+    if (!await pathExists(target.configPath)) {
+      continue;
+    }
+    const config = await readConfigYaml(target.configPath);
+    const installedVersion = String(config.harness_version ?? "");
+    const hasAgents = Array.isArray(config.agents) && config.agents.length > 0;
+    if (!installedVersion || !hasAgents) {
+      throw new Error(
+        `${target.label} config.yaml is missing required harness fields (harness_version / agents). This project predates the current config layout. Run \`easy-coding clear\` then \`easy-coding init\` to migrate \u2014 your tasks, spec, and memory are preserved.`
+      );
+    }
+    const relation = compareVersions(installedVersion, VERSION);
+    if (relation === 1) {
+      throw new Error(
+        `${target.label} harness version ${installedVersion} is newer than CLI ${VERSION}. Update the CLI first.`
+      );
+    }
+    if (relation === -1 || relation === 0 && await needsHookConfigRefresh(target, config.agents)) {
+      pending.push({ target, config });
+    }
+  }
+  return pending;
+}
+async function needsHookConfigRefresh(target, agents) {
+  const manifest = await readInstallManifest(target.dir);
+  for (const agent of agents) {
+    const meta = resolvePlatformMeta(target.dir, agent);
+    const configPath2 = path22.join(target.dir, meta.hookConfigFile);
+    const content = await readTextIfExists(configPath2);
+    if (content === null) {
+      return true;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(content);
+    } catch {
+      return true;
+    }
+    const commandsByEvent = collectHookCommandsByEvent(parsed.hooks);
+    const commands = [...commandsByEvent.values()].flat();
+    const expectedRegistrations = expectedHookRegistrations(target.dir, meta, agent);
+    const expectedCommandSet = new Set(
+      expectedRegistrations.map((registration) => registration.command)
+    );
+    if (!hasExpectedHookRegistrations(commandsByEvent, expectedRegistrations)) {
+      return true;
+    }
+    const manifestManagedCommands = new Set(
+      manifest?.hook_registrations.filter((registration) => registration.platform === agent).map((registration) => registration.command) ?? []
+    );
+    if (commands.some(
+      (command) => isUnexpectedManagedHookCommand(
+        command,
+        expectedCommandSet,
+        target.dir,
+        meta,
+        agent,
+        manifestManagedCommands
+      )
+    )) {
+      return true;
+    }
+  }
+  return false;
+}
+function expectedHookRegistrations(cwd, meta, platform) {
+  return EXPECTED_HOOK_REGISTRATION_SCRIPTS[platform].map(({ event, scriptName }) => ({
+    event,
+    command: renderHookCommand(cwd, meta.templateContext, scriptName)
+  }));
+}
+function hasExpectedHookRegistrations(commandsByEvent, expectedRegistrations) {
+  const actualCounts = countRegistrations(
+    [...commandsByEvent.entries()].flatMap(
+      ([event, commands]) => commands.map((command) => ({ event, command }))
+    )
+  );
+  const expectedCounts = countRegistrations(expectedRegistrations);
+  return [...expectedCounts.entries()].every(
+    ([registrationKey, expectedCount]) => (actualCounts.get(registrationKey) ?? 0) >= expectedCount
+  );
+}
+function countRegistrations(registrations) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const registration of registrations) {
+    const key = hookRegistrationKey(registration);
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  return counts;
+}
+function hookRegistrationKey(registration) {
+  return `${registration.event}\0${registration.command}`;
+}
+function collectHookCommandsByEvent(hooks) {
+  if (!hooks || typeof hooks !== "object" || Array.isArray(hooks)) {
+    return /* @__PURE__ */ new Map();
+  }
+  const commandsByEvent = /* @__PURE__ */ new Map();
+  for (const [event, value] of Object.entries(hooks)) {
+    if (!Array.isArray(value)) {
+      continue;
+    }
+    for (const group of value) {
+      if (!group || typeof group !== "object") {
+        continue;
+      }
+      const hookItems = group.hooks;
+      if (!Array.isArray(hookItems)) {
+        continue;
+      }
+      for (const hook of hookItems) {
+        if (!hook || typeof hook !== "object") {
+          continue;
+        }
+        const command = hook.command;
+        if (typeof command === "string") {
+          const eventCommands = commandsByEvent.get(event) ?? [];
+          eventCommands.push(command);
+          commandsByEvent.set(event, eventCommands);
+        }
+      }
+    }
+  }
+  return commandsByEvent;
+}
+function isUnexpectedManagedHookCommand(command, expectedCommands, cwd, meta, platform, manifestManagedCommands) {
+  if (expectedCommands.has(command)) {
+    return false;
+  }
+  if (manifestManagedCommands.has(command)) {
+    return true;
+  }
+  const hookPath = extractHookPathFromCommand(command);
+  return hookPath === null ? false : isCurrentProjectManagedHookPath(cwd, hookPath, meta, platform);
+}
+function isCurrentProjectManagedHookPath(cwd, hookPath, meta, platform) {
+  const normalizedHookPath = normalizePathForHookComparison(hookPath);
+  const configDir = normalizePathForHookComparison(meta.templateContext.platform_config_dir);
+  return MANAGED_HOOK_SCRIPT_NAMES[platform].some((scriptName) => {
+    const relativeHookPath = `${configDir}/hooks/${scriptName}`;
+    if (normalizedHookPath === relativeHookPath) {
+      return true;
+    }
+    return pathAliases(
+      normalizePathForHookComparison(path22.resolve(cwd, relativeHookPath))
+    ).includes(normalizedHookPath);
   });
-  await ensureEasyCodingSessionsIgnored(cwd);
-  await updateHarnessVersion(configPath, VERSION);
-  await setPendingInitSince(cwd, VERSION);
-  outro5(chalk7.green(`easy-coding harness upgraded to ${VERSION}.`));
+}
+function normalizePathForHookComparison(value) {
+  return value.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function pathAliases(value) {
+  const aliases = /* @__PURE__ */ new Set([value]);
+  if (value.startsWith("/private/var/")) {
+    aliases.add(value.replace(/^\/private\/var\//, "/var/"));
+  } else if (value.startsWith("/var/")) {
+    aliases.add(`/private${value}`);
+  }
+  return [...aliases];
+}
+async function resolveParentTopologyRefresh(targets, pending) {
+  const parent = targets.find(
+    (target) => target.label === "." && target.supermodule.role === "super-parent"
+  );
+  if (!parent || pending.some(({ target }) => target.label === ".")) {
+    return null;
+  }
+  if (!await pathExists(parent.configPath)) {
+    return null;
+  }
+  const config = await readConfigYaml(parent.configPath);
+  if (!Array.isArray(config.agents) || config.agents.length === 0) {
+    return null;
+  }
+  const submodulePaths = parent.supermodule.submodules ?? [];
+  const configuredSubmodules = Array.isArray(config.supermodule?.submodules) ? config.supermodule.submodules : [];
+  const needsRefresh = config.supermodule?.role !== "super-parent" || !sameStringList(configuredSubmodules, submodulePaths);
+  if (!needsRefresh) {
+    return null;
+  }
+  return {
+    target: parent,
+    agents: config.agents,
+    submodulePaths
+  };
+}
+async function resolveChildTopologyRefreshes(targets, pending) {
+  const pendingLabels = new Set(pending.map(({ target }) => target.label));
+  const refreshes = [];
+  for (const target of targets) {
+    if (target.supermodule.role !== "submodule-child" || pendingLabels.has(target.label) || !await pathExists(target.configPath)) {
+      continue;
+    }
+    const config = await readConfigYaml(target.configPath);
+    if (config.supermodule?.role === "submodule-child" && config.supermodule.parent === target.supermodule.parent) {
+      continue;
+    }
+    refreshes.push({ target });
+  }
+  return refreshes;
+}
+function sameStringList(left, right) {
+  if (left.length !== right.length) {
+    return false;
+  }
+  const sortedLeft = [...left].sort();
+  const sortedRight = [...right].sort();
+  return sortedLeft.every((value, index) => value === sortedRight[index]);
 }
 
 // src/cli.ts
@@ -1940,11 +3021,14 @@ function withErrorHandling(fn) {
 await checkForUpgrade(process.cwd());
 var program = new Command();
 program.name("easy-coding").description(PACKAGE_NAME).version(VERSION, "-v, --version");
-program.command("init").description("Initialize easy-coding harness in current project").option("--agent <list>", "Comma-separated platforms: claude-code,codex,qoder").option("-y, --yes", "Skip prompts, use defaults").action(withErrorHandling(init));
-program.command("add-agent").description("Add agent platform support to an existing project").option("--agent <list>", "Comma-separated platforms to add").action(withErrorHandling(addAgent));
+program.command("init").description("Initialize easy-coding harness in current project").option("--agent <list>", "Comma-separated platforms: claude-code,codex,qoder").option(
+  "--submodules <list>",
+  "Comma-separated checked-out submodule paths or names to initialize"
+).option("--no-submodules", "Initialize only the current directory when .gitmodules exists").option("-y, --yes", "Skip prompts, use defaults").action(withErrorHandling(init));
+program.command("add-agent").description("Add agent platform support to an existing project").option("--agent <list>", "Comma-separated platforms to add").option("--submodules <list>", "Comma-separated initialized submodule paths or names to update").option("--no-submodules", "Add the agent only to the current directory").action(withErrorHandling(addAgent));
 program.command("upgrade").description("Upgrade harness files to current CLI version").option("--dry-run", "Preview changes without applying").option("-y, --yes", "Skip confirmation").action(withErrorHandling(upgrade));
 program.command("update").description("Refresh the global CLI to the latest published version").option("--tag <tag>", "npm dist-tag or version to install", "latest").option("--dry-run", "Preview the install command without running it").option("-y, --yes", "Skip confirmation").action(withErrorHandling(update));
 program.command("status").description("Show installed agents, version, and tasks").action(withErrorHandling(status));
-program.command("clear").description("Remove installed harness files (skills, hooks, config); keep tasks, spec, memory").option("--dry-run", "Preview what would be removed without deleting").option("-y, --yes", "Skip confirmation").action(withErrorHandling(clear));
+program.command("clear").description("Remove installed harness files (skills, hooks, config); keep tasks, spec, memory").option("--submodules <list>", "Comma-separated initialized submodule paths or names to clear").option("--no-submodules", "Clear only the current directory").option("--dry-run", "Preview what would be removed without deleting").option("-y, --yes", "Skip confirmation").action(withErrorHandling(clear));
 program.parse();
 //# sourceMappingURL=cli.js.map