codex-potter 0.1.31 → 0.2.0-next.1

package/README.md

@@ -1,24 +1,10 @@
 # CodexPotter
 
-Install:
+Set up CodexPotter for use from Codex:
 
 ```sh
-npm install -g codex-potter
+npx codex-potter@next setup
 ```
 
-Supported platforms:
-
-- macOS: Apple Silicon + Intel
-- Linux: x86_64 + aarch64
-- Windows: x86_64 + aarch64 (ARM64)
-
-Packaging note:
-
-- The `codex-potter` npm package ships a small cross-platform launcher.
-- The native binary payload is delivered via platform-specific optional dependencies.
-  If you see an error like `Missing optional dependency codex-potter-<platform>`, reinstall
-  CodexPotter so your package manager can fetch the correct platform package.
-
----
-
-See https://github.com/breezewish/CodexPotter for full usage.
+The setup command configures the global gitignore, installs the CodexPotter
+subagent profile, and installs the `$loop` skill.

package/bin/codex-potter.js

@@ -1,233 +1,523 @@
 #!/usr/bin/env node
-// Unified entry point for CodexPotter.
 
-import { spawn } from "node:child_process";
-import { existsSync } from "fs";
-import { createRequire } from "node:module";
-import path from "path";
-import { fileURLToPath } from "url";
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+import { fileURLToPath } from "node:url";
 
-// __dirname equivalent in ESM
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-const require = createRequire(import.meta.url);
-
-const PLATFORM_PACKAGE_BY_TARGET = {
-  "x86_64-unknown-linux-musl": "codex-potter-linux-x64",
-  "aarch64-unknown-linux-musl": "codex-potter-linux-arm64",
-  "x86_64-apple-darwin": "codex-potter-darwin-x64",
-  "aarch64-apple-darwin": "codex-potter-darwin-arm64",
-  "x86_64-pc-windows-msvc": "codex-potter-win32-x64",
-  "aarch64-pc-windows-msvc": "codex-potter-win32-arm64",
+
+const CODEXPOTTER_GITIGNORE_ENTRY = "/.codexpotter";
+const LOOP_SKILL_COMMAND = [
+  "skills",
+  "add",
+  "--yes",
+  "-g",
+  "https://github.com/breezewish/CodexPotter/tree/v2",
+  "-a",
+  "codex",
+];
+
+const colorEnabled = shouldUseColor();
+const colors = {
+  bold: "\x1b[1m",
+  cyan: "\x1b[36m",
+  dim: "\x1b[2m",
+  green: "\x1b[32m",
+  red: "\x1b[31m",
+  reset: "\x1b[0m",
+  yellow: "\x1b[33m",
 };
 
-const { platform, arch } = process;
-
-let targetTriple = null;
-switch (platform) {
-  case "linux":
-  case "android":
-    switch (arch) {
-      case "x64":
-        targetTriple = "x86_64-unknown-linux-musl";
-        break;
-      case "arm64":
-        targetTriple = "aarch64-unknown-linux-musl";
-        break;
-      default:
-        break;
-    }
-    break;
-  case "darwin":
-    switch (arch) {
-      case "x64":
-        targetTriple = "x86_64-apple-darwin";
-        break;
-      case "arm64":
-        targetTriple = "aarch64-apple-darwin";
-        break;
-      default:
-        break;
+async function main(args) {
+  const { command, yes, errors } = parseArgs(args);
+  if (errors.length > 0) {
+    printErrors(errors);
+    printAvailableCommands();
+    return 1;
+  }
+
+  if (command !== "setup") {
+    if (command) {
+      printErrors([`Unknown command: ${command}`]);
     }
-    break;
-  case "win32":
-    switch (arch) {
-      case "x64":
-        targetTriple = "x86_64-pc-windows-msvc";
-        break;
-      case "arm64":
-        targetTriple = "aarch64-pc-windows-msvc";
-        break;
-      default:
-        break;
+    printAvailableCommands();
+    return command ? 1 : 0;
+  }
+
+  await runSetup({ yes });
+  return 0;
+}
+
+function parseArgs(args) {
+  const remaining = [];
+  const errors = [];
+  let yes = false;
+
+  for (const arg of args) {
+    if (arg === "--yes" || arg === "-y") {
+      yes = true;
+    } else if (arg === "--help" || arg === "-h") {
+      return { command: null, yes, errors };
+    } else if (arg.startsWith("-")) {
+      errors.push(`Unknown option: ${arg}`);
+    } else {
+      remaining.push(arg);
     }
-    break;
-  default:
-    break;
+  }
+
+  if (remaining.length > 1) {
+    errors.push(`Unexpected argument: ${remaining[1]}`);
+  }
+
+  return { command: remaining[0] ?? null, yes, errors };
 }
 
-if (!targetTriple) {
-  throw new Error(`Unsupported platform: ${platform} (${arch})`);
+function printAvailableCommands() {
+  console.log(format("CodexPotter", "bold"));
+  console.log("");
+  console.log("Usage:");
+  console.log("  codex-potter setup [--yes]");
+  console.log("");
+  console.log("Available commands:");
+  console.log("  setup    Configure CodexPotter for $loop.");
 }
 
-const platformPackage = PLATFORM_PACKAGE_BY_TARGET[targetTriple];
-if (!platformPackage) {
-  throw new Error(`Unsupported target triple: ${targetTriple}`);
+function printErrors(errors) {
+  for (const error of errors) {
+    console.error(`${format("Error:", "red")} ${error}`);
+  }
 }
 
-const codexPotterBinaryName =
-  process.platform === "win32" ? "codex-potter.exe" : "codex-potter";
-const localVendorRoot = path.join(__dirname, "..", "vendor");
-const localBinaryPath = path.join(
-  localVendorRoot,
-  targetTriple,
-  "codex-potter",
-  codexPotterBinaryName,
-);
-const packageManager = detectPackageManager();
+async function runSetup({ yes }) {
+  const home = getHomeDir();
+  const resourcePath = path.join(
+    __dirname,
+    "..",
+    "resources",
+    "potter_worker.toml",
+  );
+  const profilePath = path.join(home, ".codex", "agents", "potter_worker.toml");
+  const profileContent = await fs.promises.readFile(resourcePath, "utf8");
 
-let vendorRoot;
-try {
-  const packageJsonPath = require.resolve(`${platformPackage}/package.json`);
-  vendorRoot = path.join(path.dirname(packageJsonPath), "vendor");
-} catch {
-  if (existsSync(localBinaryPath)) {
-    vendorRoot = localVendorRoot;
+  const globalGitignore = resolveGlobalGitignore(home);
+  const gitignoreContent = await readTextIfExists(globalGitignore.path);
+  const gitignoreNeedsWrite = !gitignoreIgnoresCodexPotter(gitignoreContent);
+
+  const currentProfileContent = await readTextIfExists(profilePath);
+  const profileNeedsWrite = currentProfileContent !== profileContent;
+  const skillInstaller = resolveSkillInstaller();
+
+  printSetupPlan({
+    gitignoreNeedsWrite,
+    profileNeedsWrite,
+    profilePath,
+    skillInstaller,
+  });
+
+  if (!yes && !(await confirm())) {
+    console.log("Setup cancelled.");
+    return;
+  }
+
+  if (gitignoreNeedsWrite) {
+    const gitignoreUpdated = await ensureCodexPotterIgnored(globalGitignore.path);
+    if (gitignoreUpdated) {
+      console.log(
+        `${format("✓ Added", "green")} ${format(
+          CODEXPOTTER_GITIGNORE_ENTRY,
+          "dim",
+        )} to ${format(displayPath(globalGitignore.path), "dim")}`,
+      );
+    }
+  }
+
+  if (profileNeedsWrite) {
+    await fs.promises.mkdir(path.dirname(profilePath), { recursive: true });
+    await fs.promises.writeFile(profilePath, profileContent, "utf8");
+    console.log(
+      `${format("✓ Added", "green")} subagent profile ${format(
+        displayPath(profilePath),
+        "dim",
+      )}`,
+    );
+  }
+
+  await runLoopSkillInstaller(skillInstaller);
+
+  console.log("");
+  console.log(format("✨ CodexPotter setup complete!", "green"));
+  console.log(
+    `${format("Usage in Codex:", "bold")} ${format(
+      "$loop",
+      "cyan",
+    )} <your_instruction>`,
+  );
+}
+
+function printSetupPlan({
+  gitignoreNeedsWrite,
+  profileNeedsWrite,
+  profilePath,
+  skillInstaller,
+}) {
+  console.log(format("CodexPotter setup", "bold"));
+  console.log("");
+  console.log(
+    `${statusLabel(gitignoreNeedsWrite)} Ignore ${format(
+      CODEXPOTTER_GITIGNORE_ENTRY,
+      "dim",
+    )} in global gitignore`,
+  );
+  console.log(
+    `${statusLabel(profileNeedsWrite)} Add subagent profile ${format(
+      displayPath(profilePath),
+      "dim",
+    )}`,
+  );
+  console.log(
+    `${statusLabel(true)} Install / update skill: ${format(
+      skillInstaller.displayCommand,
+      "cyan",
+    )}`,
+  );
+  console.log("");
+}
+
+function statusLabel(needsAction) {
+  return needsAction ? format("□ Todo:", "yellow") : format("✓ Skip:", "green");
+}
+
+async function confirm() {
+  if (process.stdin.isTTY && process.stdout.isTTY) {
+    return confirmInteractively();
   }
+
+  return confirmFromLineInput();
 }
 
-if (!vendorRoot) {
-  throw missingOptionalDependencyError(platformPackage, packageManager);
+async function confirmInteractively() {
+  return await new Promise((resolve) => {
+    let selected = true;
+    let settled = false;
+    const input = process.stdin;
+
+    const render = () => {
+      process.stdout.write(`\r\x1b[2K${confirmPrompt(selected)}`);
+    };
+
+    const settle = (value) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      input.off("keypress", onKeypress);
+      input.off("close", onClose);
+      input.off("end", onClose);
+      if (input.isTTY) {
+        input.setRawMode(false);
+      }
+      process.stdout.write("\n");
+      resolve(value);
+    };
+
+    const onClose = () => {
+      settle(false);
+    };
+
+    const onKeypress = (text, key = {}) => {
+      if (key.ctrl && key.name === "c") {
+        settle(false);
+      } else if (key.name === "return") {
+        settle(selected);
+      } else if (key.name === "escape") {
+        settle(false);
+      } else if (key.name === "left" || key.name === "up") {
+        selected = true;
+        render();
+      } else if (key.name === "right" || key.name === "down") {
+        selected = false;
+        render();
+      } else if (key.name === "tab" || text === " ") {
+        selected = !selected;
+        render();
+      } else if (text && text.toLowerCase() === "y") {
+        settle(true);
+      } else if (text && text.toLowerCase() === "n") {
+        settle(false);
+      }
+    };
+
+    readline.emitKeypressEvents(input);
+    input.on("keypress", onKeypress);
+    input.on("close", onClose);
+    input.on("end", onClose);
+    input.setRawMode(true);
+    input.resume();
+    render();
+  });
 }
 
-const archRoot = path.join(vendorRoot, targetTriple);
-const binaryPath = path.join(archRoot, "codex-potter", codexPotterBinaryName);
+async function confirmFromLineInput() {
+  const answer = await new Promise((resolve) => {
+    let settled = false;
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: false,
+    });
 
-// Use an asynchronous spawn instead of spawnSync so that Node is able to
-// respond to signals (e.g. Ctrl-C / SIGINT) while the native binary is
-// executing. This allows us to forward those signals to the child process
-// and guarantees that when either the child terminates or the parent
-// receives a fatal signal, both processes exit in a predictable manner.
+    const settle = (value) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      rl.close();
+      resolve(value);
+    };
 
-function getUpdatedPath(newDirs) {
-  const pathSep = process.platform === "win32" ? ";" : ":";
-  const existingPath = process.env.PATH || "";
-  const updatedPath = [
-    ...newDirs,
-    ...existingPath.split(pathSep).filter(Boolean),
-  ].join(pathSep);
-  return updatedPath;
+    rl.on("close", () => {
+      settle("");
+    });
+    rl.question(confirmPrompt(true), settle);
+  });
+
+  return /^(y|yes)$/i.test(String(answer).trim());
 }
 
-/**
- * Use heuristics to detect the package manager that was used to install CodexPotter
- * in order to give the user a hint about how to update it.
- */
-function detectPackageManager() {
-  const userAgent = process.env.npm_config_user_agent || "";
-  if (/\bbun\//.test(userAgent)) {
-    return "bun";
+function confirmPrompt(yesSelected) {
+  const yes = yesSelected
+    ? `${format("●", "green")} Yes`
+    : format("○ Yes", "dim");
+  const no = yesSelected
+    ? format(" / ○ No", "dim")
+    : ` ${format("/", "dim")} ${format("●", "green")} No`;
+  return `Continue? ${yes}${no} `;
+}
+
+function resolveGlobalGitignore(home) {
+  const configured = spawnSync(
+    "git",
+    ["config", "--global", "--path", "--get", "core.excludesfile"],
+    { encoding: "utf8" },
+  );
+
+  if (configured.status === 0) {
+    const configuredPath = configured.stdout.trim();
+    if (configuredPath) {
+      const resolvedPath = expandHome(configuredPath, home);
+      return {
+        path: resolvedPath,
+      };
+    }
   }
 
-  const execPath = process.env.npm_execpath || "";
-  if (execPath.includes("bun")) {
-    return "bun";
+  const configHome = process.env.XDG_CONFIG_HOME || path.join(home, ".config");
+  const resolvedPath = path.join(configHome, "git", "ignore");
+  return {
+    path: resolvedPath,
+  };
+}
+
+async function readTextIfExists(filePath) {
+  try {
+    return await fs.promises.readFile(filePath, "utf8");
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      return "";
+    }
+    throw error;
   }
+}
 
-  if (
-    __dirname.includes(".bun/install/global") ||
-    __dirname.includes(".bun\\install\\global")
-  ) {
-    return "bun";
+async function ensureCodexPotterIgnored(filePath) {
+  const currentContent = await readTextIfExists(filePath);
+  if (gitignoreIgnoresCodexPotter(currentContent)) {
+    return false;
   }
 
-  return userAgent ? "npm" : null;
+  let updated = currentContent;
+  if (updated && !updated.endsWith("\n")) {
+    updated += "\n";
+  }
+  updated += `${CODEXPOTTER_GITIGNORE_ENTRY}\n`;
+  await writeTextAtomic(filePath, updated);
+  return true;
 }
 
-function reinstallCommand(packageManager) {
-  return packageManager === "bun"
-    ? "bun install -g codex-potter@latest"
-    : "npm install -g codex-potter@latest";
+async function writeTextAtomic(filePath, content) {
+  const dir = path.dirname(filePath);
+  await fs.promises.mkdir(dir, { recursive: true });
+  const tempPath = path.join(
+    dir,
+    `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`,
+  );
+
+  try {
+    await fs.promises.writeFile(tempPath, content, "utf8");
+    await fs.promises.rename(tempPath, filePath);
+  } catch (error) {
+    await fs.promises.rm(tempPath, { force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+function gitignoreIgnoresCodexPotter(contents) {
+  if (!contents) {
+    return false;
+  }
+
+  return simpleGitignoreIgnoresCodexPotter(contents);
+}
+
+function simpleGitignoreIgnoresCodexPotter(contents) {
+  let ignored = false;
+
+  for (const rawLine of contents.split(/\r?\n/)) {
+    const parsed = parseGitignoreLine(rawLine);
+    if (!parsed) {
+      continue;
+    }
+
+    if (patternMatchesCodexPotter(parsed.pattern)) {
+      ignored = !parsed.negated;
+    }
+  }
+
+  return ignored;
+}
+
+function parseGitignoreLine(rawLine) {
+  const line = rawLine.trim();
+  if (!line || line.startsWith("#")) {
+    return null;
+  }
+
+  if (line.startsWith("!")) {
+    return { negated: true, pattern: line.slice(1) };
+  }
+
+  return { negated: false, pattern: line };
 }
 
-function missingOptionalDependencyError(platformPackage, packageManager) {
-  return new Error(
-    `Missing optional dependency ${platformPackage}. Reinstall CodexPotter: ${reinstallCommand(packageManager)}`,
+function patternMatchesCodexPotter(pattern) {
+  const normalized = pattern.replace(/\\/g, "/").replace(/^\/+/, "");
+  const withoutTrailingSlash = normalized.replace(/\/+$/, "");
+
+  return (
+    withoutTrailingSlash === ".codexpotter" ||
+    withoutTrailingSlash === "**/.codexpotter" ||
+    normalized === ".codexpotter/**" ||
+    normalized === "**/.codexpotter/**"
   );
 }
 
-const additionalDirs = [];
-const pathDir = path.join(archRoot, "path");
-if (existsSync(pathDir)) {
-  additionalDirs.push(pathDir);
-}
-const updatedPath = getUpdatedPath(additionalDirs);
-
-const env = { ...process.env, PATH: updatedPath };
-delete env.CODEX_POTTER_MANAGED_BY_NPM;
-delete env.CODEX_POTTER_MANAGED_BY_BUN;
-const packageManagerEnvVar =
-  packageManager === "bun"
-    ? "CODEX_POTTER_MANAGED_BY_BUN"
-    : "CODEX_POTTER_MANAGED_BY_NPM";
-env[packageManagerEnvVar] = "1";
-
-const child = spawn(binaryPath, process.argv.slice(2), {
-  stdio: "inherit",
-  env,
-});
-
-child.on("error", (err) => {
-  // Typically triggered when the binary is missing or not executable.
-  // Re-throwing here will terminate the parent with a non-zero exit code
-  // while still printing a helpful stack trace.
-  // eslint-disable-next-line no-console
-  console.error(err);
-  process.exit(1);
-});
-
-// Forward common termination signals to the child so that it shuts down
-// gracefully. In the handler we temporarily disable the default behavior of
-// exiting immediately; once the child has been signaled we simply wait for
-// its exit event which will in turn terminate the parent (see below).
-const forwardSignal = (signal) => {
-  if (child.killed) {
-    return;
+function resolveSkillInstaller() {
+  const runner = detectPackageRunner();
+  const args =
+    runner === "npx" ? ["--yes", ...LOOP_SKILL_COMMAND] : LOOP_SKILL_COMMAND;
+  return {
+    command: executableForRunner(runner),
+    args,
+    displayCommand: `${runner} ${args.join(" ")}`,
+  };
+}
+
+function detectPackageRunner() {
+  const userAgent = process.env.npm_config_user_agent || "";
+  const execPath = process.env.npm_execpath || "";
+  const execName = path.basename(execPath).toLowerCase();
+  if (/\bbun\//.test(userAgent) || execName.startsWith("bun")) {
+    return "bunx";
   }
-  try {
-    child.kill(signal);
-  } catch {
-    /* ignore */
+  return "npx";
+}
+
+function executableForRunner(runner) {
+  if (process.platform === "win32") {
+    return `${runner}.cmd`;
   }
-};
+  return runner;
+}
 
-const forwardedSignals = ["SIGINT", "SIGTERM", "SIGHUP"];
-forwardedSignals.forEach((sig) => {
-  process.on(sig, () => forwardSignal(sig));
-});
-
-// When the child exits, mirror its termination reason in the parent so that
-// shell scripts and other tooling observe the correct exit status.
-// Wrap the lifetime of the child process in a Promise so that we can await
-// its termination in a structured way. The Promise resolves with an object
-// describing how the child exited: either via exit code or due to a signal.
-const childResult = await new Promise((resolve) => {
-  child.on("exit", (code, signal) => {
-    if (signal) {
-      resolve({ type: "signal", signal });
-    } else {
-      resolve({ type: "code", exitCode: code ?? 1 });
-    }
+async function runLoopSkillInstaller(skillInstaller) {
+  const child = spawn(skillInstaller.command, skillInstaller.args, {
+    stdio: "inherit",
   });
-});
 
-if (childResult.type === "signal") {
-  forwardedSignals.forEach((sig) => {
-    process.removeAllListeners(sig);
+  const result = await new Promise((resolve, reject) => {
+    child.on("error", reject);
+    child.on("exit", (code, signal) => {
+      resolve({ code, signal });
+    });
   });
-  // Re-emit the same signal so that the parent terminates with the expected
-  // semantics (this also sets the correct exit code of 128 + n).
-  process.kill(process.pid, childResult.signal);
-} else {
-  process.exit(childResult.exitCode);
+
+  if (result.signal) {
+    throw new Error(`Loop skill installer terminated by ${result.signal}.`);
+  }
+
+  if (result.code !== 0) {
+    throw new Error(`Loop skill installer failed with exit code ${result.code}.`);
+  }
+}
+
+function getHomeDir() {
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (!home) {
+    throw new Error("Cannot determine the home directory.");
+  }
+  return home;
+}
+
+function expandHome(value, home) {
+  if (value === "~") {
+    return home;
+  }
+  if (value.startsWith("~/") || value.startsWith("~\\")) {
+    return path.join(home, value.slice(2));
+  }
+  return value;
+}
+
+function displayPath(filePath) {
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (!home) {
+    return filePath;
+  }
+
+  const relative = path.relative(home, filePath);
+  if (relative === "") {
+    return "~";
+  }
+  if (!relative.startsWith("..") && !path.isAbsolute(relative)) {
+    return path.join("~", relative);
+  }
+  return filePath;
+}
+
+function shouldUseColor() {
+  if (process.env.NO_COLOR) {
+    return false;
+  }
+  if (process.env.FORCE_COLOR && process.env.FORCE_COLOR !== "0") {
+    return true;
+  }
+  return Boolean(process.stdout.isTTY);
+}
+
+function format(text, color) {
+  if (!colorEnabled) {
+    return text;
+  }
+  return `${colors[color]}${text}${colors.reset}`;
+}
+
+try {
+  const exitCode = await main(process.argv.slice(2));
+  process.exit(exitCode);
+} catch (error) {
+  console.error(`${format("Error:", "red")} ${error.message}`);
+  process.exit(1);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-potter",
-  "version": "0.1.31",
+  "version": "0.2.0-next.1",
   "license": "Apache-2.0",
   "bin": {
     "codex-potter": "bin/codex-potter.js"
@@ -10,20 +10,16 @@
     "node": ">=16"
   },
   "files": [
-    "bin"
+    "bin",
+    "resources"
   ],
+  "scripts": {
+    "test": "node --test"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/breezewish/CodexPotter",
     "directory": "npm"
   },
-  "packageManager": "pnpm@10.29.3+sha512.498e1fb4cca5aa06c1dcf2611e6fafc50972ffe7189998c409e90de74566444298ffe43e6cd2acdc775ba1aa7cc5e092a8b7054c811ba8c5770f84693d33d2dc",
-  "optionalDependencies": {
-    "codex-potter-linux-x64": "npm:codex-potter@0.1.31-linux-x64",
-    "codex-potter-linux-arm64": "npm:codex-potter@0.1.31-linux-arm64",
-    "codex-potter-darwin-x64": "npm:codex-potter@0.1.31-darwin-x64",
-    "codex-potter-darwin-arm64": "npm:codex-potter@0.1.31-darwin-arm64",
-    "codex-potter-win32-x64": "npm:codex-potter@0.1.31-win32-x64",
-    "codex-potter-win32-arm64": "npm:codex-potter@0.1.31-win32-arm64"
-  }
+  "packageManager": "pnpm@10.29.3+sha512.498e1fb4cca5aa06c1dcf2611e6fafc50972ffe7189998c409e90de74566444298ffe43e6cd2acdc775ba1aa7cc5e092a8b7054c811ba8c5770f84693d33d2dc"
 }

package/resources/potter_worker.toml

@@ -0,0 +1,122 @@
+name = "potter_worker"
+description = "General purpose worker, only used in CodexPotter loop"
+developer_instructions = """
+
+<WORKFLOW_INSTRUCTIONS>
+
+Run the workflow below to implement the overall goal recorded in the handoff file.
+Keep handoff file updated until all listed tasks are complete or handoff file's `status == skip`.
+
+- `.codexpotter/` is intentionally gitignored—never commit anything under it.
+- Sections in handoff file: Overall Goal, In Progress, Todo, Done
+- handoff file's status in front matter: initial / open / skip
+
+# Phase: `status == initial`
+
+1. Resolve and fully understand user's request in `Overall Goal`.
+
+2. For user request that:
+   - requires broken down into smaller tasks:
+     set status to `open` and create smaller tasks in `Todo`.
+   - can be done / answered immediately:
+     do so and record in `Done`, set status to `skip`. No need to create other tasks.
+
+# Phase: `status == open`
+
+1. Always continue tasks in `In Progress` first (if any).
+   - If none are in progress, pick from `Todo` (not necessarily first, choose wisely).
+   - You may start multiple related tasks, but don't start multiple large/complex ones at once.
+
+2. When start tasks, move them from `Todo` -> `In Progress` (keep text unchanged).
+
+3. When complete a task:
+
+   3.1. Append an entry to `Done` including:
+   - what you completed (concise, derived from the original task, keep necessary details)
+   - key decisions + rationale
+   - files changed (if any)
+   - learnings for future iterations (optional)
+
+   Keep it concise (brevity > grammar).
+
+   3.2. Remove task from `Todo`/`In Progress`.
+
+   3.3. Create a git commit for your changes (if any) with a succinct message. No need to commit the handoff file.
+
+4. You may add/remove `Todo` tasks as needed.
+   - Break large tasks into small, concrete steps; adjust tasks as your understanding improves.
+
+5. If all tasks are complete, do strict review and try to enhance:
+
+   5.1 Analyze and understand working dir with `Overall Goal`, then verify and review against what has changed so far. Utilize review skills if available.
+
+   handoff file's front matter recorded git commit before change; use it to learn diffs.
+
+   5.2 Identify issues, missing parts, unaligned areas, or possible improvements, and add them to `Todo`.
+
+   IMPORTANT PRINCIPLE: `Done` TASKS COULD BE MISLEADING, always be critical and skeptical about `Done` tasks,
+   as they could be written by previous low-quality agents, claimed to be done but actually incomplete,
+   incorrect, not well-designed, not respecting project's standard, or not aligned with the overall goal at all.
+   You must find the good path to achieve the overall goal based on the first principle, without being biased by the existing "Done" tasks.
+
+   5.3 Stop only if you are very certain everything is done and no further improvements are possible.
+
+   If the user request was fulfilled by replying directly without any artifact files or code changes, you can stop once all tasks are done — no further improvements are needed.
+
+# Do Improvements
+
+When all tasks are complete AND overall goal is to make changes, consider improvements of various kinds, for example but not limited to:
+
+**Coding kind**:
+
+- polish, simplify, quality, performance, edge cases, error handling, UX, docs, etc.
+
+  When polishing codes, follow the first principle, try to simplify the solution, instead of bloating the code with extra checks, fallbacks, or safety nets that may hide potential issues.
+  The goal of polishing is to find real missing pieces, make the code more elegant, simple and efficient, not to add more layers of complexity.
+
+**Docs / research / reports kind:**
+
+- correctness, completeness, readability, logical clarity, accuracy
+- remove irrelevant and redundant content
+
+# Requirements
+
+- Don't ask the user questions. Decide and act autonomously.
+- Keep working until all tasks in the handoff file are complete.
+- Follow engineering rules in `AGENTS.md` (if present).
+- NEVER mention this workflow / "developer instruction" or what workflow steps you have followed in your response. This workflow should be transparent to the user.
+- You must NOT change handoff file status from `open` to `skip`.
+- To avoid regression, read full handoff file.
+- NEVER change any text in `Overall Goal`.
+
+# Knowledge capture (`.codexpotter/kb/`)
+
+- Before starting, read `.codexpotter/kb/README.md` (if present).
+- After deep research/exploration of a module, write intermediate facts + code locations to `.codexpotter/kb/xxx.md` and update the README index.
+- KB files may be stale; **code is the source of truth**—update KB promptly when conflicts are found.
+- No need to commit KB files.
+
+# When all tasks are done or the project is skipped
+
+Mark handoff file's `finite_incantatem` to true ONLY IF you have not changed any file or code since you received this workflow instruction.
+
+Updating handoff files or files under `.codexpotter/kb` doesn't matter, but any other file changes indicate you have done some work,
+so `finite_incantatem` should be kept false.
+
+# Review guidelines
+
+When you are acting as a reviewer for the code change made so far, here are the general guidelines
+for determining whether something is a bug and should be fixed:
+
+- It meaningfully impacts the accuracy, performance, security, or maintainability of the code.
+- The bug is discrete and actionable (i.e. not a general issue with the codebase or a combination of multiple issues).
+- Fixing the bug does not demand a level of rigor that is not present in the rest of the codebase (e.g. one doesn't need very detailed comments and input validation in a repository of one-off scripts in personal projects)
+- The bug was introduced by this project's change.
+- The author of the original PR would likely fix the issue if they were made aware of it.
+- The bug does not rely on unstated assumptions about the codebase or author's intent.
+- It is not enough to speculate that a change may disrupt another part of the codebase, to be considered a bug, one must identify the other parts of the code that are provably affected.
+- The bug is clearly not just an intentional change by the original author.
+
+</WORKFLOW_INSTRUCTIONS>
+
+"""