potetos-for-everyone 0.1.0

package/npm/core.mjs

@@ -0,0 +1,318 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+export const MANIFEST = ".potetos/install.json";
+export const BEGIN = "<!-- potetos-for-everyone:begin -->";
+export const END = "<!-- potetos-for-everyone:end -->";
+export const GITIGNORE_BEGIN = "# potetos-for-everyone:begin";
+export const GITIGNORE_END = "# potetos-for-everyone:end";
+
+const BLOCK = `${BEGIN}\n## potetos-for-everyone\n\nFor non-trivial engineering work, use the Agent Skill at \`.agents/skills/poteto-mode/SKILL.md\`.\nIt routes the task to a playbook, loads supporting skills progressively, prefers simple changes,\nand requires evidence against the real artifact. Canonical skills are adapted from Lauren Tan's pstack.\nIf native skill discovery is unavailable, read that SKILL.md and its selected playbook manually.\n${END}`;
+const GITIGNORE_BLOCK = `${GITIGNORE_BEGIN}\n.potetos/\n${GITIGNORE_END}`;
+
+export function registry() {
+  return JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, "adapters", "registry.json"), "utf8"));
+}
+
+function die(message) {
+  const err = new Error(message);
+  err.isPotetos = true;
+  throw err;
+}
+
+function readText(file) {
+  return fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+}
+
+function mergeMarkedBlock(file, begin, end, block) {
+  const old = readText(file);
+  let next;
+  if (old.includes(begin) && old.includes(end)) {
+    const start = old.indexOf(begin);
+    const finish = old.indexOf(end, start) + end.length;
+    const pre = old.slice(0, start).replace(/\s+$/, "");
+    const post = old.slice(finish);
+    next = pre + (pre.trim() ? "\n\n" : "") + block + post;
+  } else {
+    next = old.replace(/\s+$/, "") + (old.trim() ? "\n\n" : "") + block + "\n";
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, next, "utf8");
+}
+
+function removeMarkedBlock(file, begin, end) {
+  if (!fs.existsSync(file)) return;
+  const old = fs.readFileSync(file, "utf8");
+  const start = old.indexOf(begin);
+  if (start < 0) return;
+  const endStart = old.indexOf(end, start);
+  if (endStart < 0) return;
+  const finish = endStart + end.length;
+  const pre = old.slice(0, start).replace(/\s+$/, "");
+  const post = old.slice(finish).replace(/^\s+/, "");
+  const next = (pre + (pre && post ? "\n\n" : "") + post).replace(/\s+$/, "") + "\n";
+  if (next.trim()) fs.writeFileSync(file, next, "utf8");
+  else fs.rmSync(file, { force: true });
+}
+
+function selectedAgents(selection, reg) {
+  if (selection === "all") {
+    return ["universal", ...Object.keys(reg).filter((name) => !["generic", "universal"].includes(name))];
+  }
+  if (!reg[selection]) die(`unknown agent ${JSON.stringify(selection)}; choose one of: all, ${Object.keys(reg).sort().join(", ")}`);
+  return [selection];
+}
+
+function skillDestination(target, agents, reg) {
+  const dirs = new Set(agents.map((name) => reg[name].skill_dir));
+  if (dirs.size !== 1) die("adapter registry uses multiple skill directories; one canonical install is required");
+  return path.join(target, [...dirs][0]);
+}
+
+function instructionFiles(agents, reg) {
+  return [...new Set(["AGENTS.md", ...agents.map((name) => reg[name].instruction_file)])];
+}
+
+function copyDir(src, dst) {
+  fs.cpSync(src, dst, { recursive: true, force: false, errorOnExist: true });
+}
+
+const TEXT_HASH_EXTENSIONS = new Set([".md", ".mdc", ".txt", ".json", ".yml", ".yaml", ".js", ".mjs", ".py", ".sh", ".ps1"]);
+
+function hashBytes(file) {
+  const data = fs.readFileSync(file);
+  if (!TEXT_HASH_EXTENSIONS.has(path.extname(file).toLowerCase())) return data;
+  return Buffer.from(data.toString("utf8").replace(/\r\n?/g, "\n"), "utf8");
+}
+
+function hashTree(root) {
+  const hash = crypto.createHash("sha512");
+  const walk = (dir, prefix = "") => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const full = path.join(dir, entry.name);
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) walk(full, rel);
+      else if (entry.isFile()) {
+        hash.update(rel);
+        hash.update("\0");
+        hash.update(hashBytes(full));
+        hash.update("\0");
+      }
+    }
+  };
+  walk(root);
+  return hash.digest("hex");
+}
+
+function removePath(file) {
+  fs.rmSync(file, { recursive: true, force: true });
+}
+
+function pruneEmptyParents(start, stop) {
+  const stopAbs = path.resolve(stop);
+  let current = path.resolve(start);
+  while (current !== stopAbs && current.startsWith(stopAbs + path.sep)) {
+    if (!fs.existsSync(current)) {
+      current = path.dirname(current);
+      continue;
+    }
+    if (fs.readdirSync(current).length) break;
+    fs.rmdirSync(current);
+    current = path.dirname(current);
+  }
+}
+
+function loadManifest(target) {
+  const file = path.join(target, MANIFEST);
+  if (!fs.existsSync(file)) die(`no install manifest at ${file}`);
+  try {
+    return [file, JSON.parse(fs.readFileSync(file, "utf8"))];
+  } catch (err) {
+    die(`cannot read install manifest: ${err.message}`);
+  }
+}
+
+export function modifiedManagedPaths(target, meta) {
+  const skillDir = path.join(target, meta.skill_dir || ".agents/skills");
+  if (!fs.existsSync(skillDir)) return [`${meta.skill_dir || ".agents/skills"} (missing)`];
+  const checksums = meta.checksums || {};
+  if (meta.mode === "copy" && Object.keys(checksums).length) {
+    const modified = [];
+    for (const rel of meta.installed || []) {
+      const item = path.join(target, rel);
+      if (!fs.existsSync(item)) modified.push(`${rel} (missing)`);
+      else if (checksums[rel] && hashTree(item) !== checksums[rel]) modified.push(rel);
+    }
+    return modified;
+  }
+  if (meta.mode === "copy" && meta.tree_checksum) {
+    return hashTree(skillDir) === meta.tree_checksum ? [] : [`${meta.skill_dir || ".agents/skills"} (content changed)`];
+  }
+  const modified = [];
+  for (const rel of meta.installed || []) {
+    const item = path.join(target, rel);
+    if (!fs.existsSync(item)) modified.push(`${rel} (missing)`);
+  }
+  return modified;
+}
+
+export function install({ target = process.cwd(), agent = "all", force = false, manageGitignore = true } = {}) {
+  target = path.resolve(target);
+  if (!fs.existsSync(target)) die(`target does not exist: ${target}`);
+  const reg = registry();
+  const agents = selectedAgents(agent, reg);
+  const skillsDst = skillDestination(target, agents, reg);
+  fs.mkdirSync(skillsDst, { recursive: true });
+  const installed = [];
+  const srcRoot = path.join(PACKAGE_ROOT, "skills");
+  const sources = fs.readdirSync(srcRoot).sort().filter((name) => {
+    const src = path.join(srcRoot, name);
+    return fs.statSync(src).isDirectory() && fs.existsSync(path.join(src, "SKILL.md"));
+  });
+  const identicalExisting = new Set();
+  if (!force) {
+    const collisions = [];
+    for (const name of sources) {
+      const src = path.join(srcRoot, name);
+      const dst = path.join(skillsDst, name);
+      if (!fs.existsSync(dst)) continue;
+      let identical = false;
+      try {
+        identical = fs.statSync(dst).isDirectory() && hashTree(dst) === hashTree(src);
+      } catch {
+        identical = false;
+      }
+      if (identical) identicalExisting.add(name);
+      else collisions.push(name);
+    }
+    if (collisions.length) {
+      const preview = collisions.slice(0, 5).map((name) => path.join(skillsDst, name)).join(", ");
+      const more = collisions.length > 5 ? ` (+${collisions.length - 5} more)` : "";
+      die(`skill destinations already exist with different content: ${preview}${more}; use --force to replace them`);
+    }
+  }
+  for (const name of sources) {
+    const src = path.join(srcRoot, name);
+    const dst = path.join(skillsDst, name);
+    if (!identicalExisting.has(name)) {
+      if (fs.existsSync(dst)) removePath(dst);
+      copyDir(src, dst);
+    }
+    installed.push(path.relative(target, dst).split(path.sep).join("/"));
+  }
+  const instructions = instructionFiles(agents, reg);
+  for (const rel of instructions) mergeMarkedBlock(path.join(target, rel), BEGIN, END, BLOCK);
+  if (manageGitignore) mergeMarkedBlock(path.join(target, ".gitignore"), GITIGNORE_BEGIN, GITIGNORE_END, GITIGNORE_BLOCK);
+  const meta = {
+    source: PACKAGE_ROOT,
+    package: "potetos-for-everyone",
+    package_version: packageVersion(),
+    installer: "node",
+    agent_selection: agent,
+    agents,
+    mode: "copy",
+    skill_dir: path.relative(target, skillsDst).split(path.sep).join("/"),
+    instruction_files: instructions,
+    gitignore_managed: manageGitignore,
+    installed,
+    checksums: Object.fromEntries(installed.map((rel) => [rel, hashTree(path.join(target, rel))])),
+    tree_checksum: hashTree(skillsDst)
+  };
+  const manifest = path.join(target, MANIFEST);
+  fs.mkdirSync(path.dirname(manifest), { recursive: true });
+  fs.writeFileSync(manifest, JSON.stringify(meta, null, 2) + "\n", "utf8");
+  return { target, installed: installed.length, agent, agents, skills: meta.skill_dir };
+}
+
+export function update({ target = process.cwd(), force = false } = {}) {
+  target = path.resolve(target);
+  const [, meta] = loadManifest(target);
+  const modified = modifiedManagedPaths(target, meta);
+  if (modified.length && !force) {
+    const sample = modified.slice(0, 5).join(", ");
+    const more = modified.length > 5 ? ` (+${modified.length - 5} more)` : "";
+    die(`managed skills were edited or removed: ${sample}${more}; rerun with --force to replace them`);
+  }
+  for (const rel of meta.installed || []) removePath(path.join(target, rel));
+  return install({
+    target,
+    agent: meta.agent_selection || "universal",
+    force: false,
+    manageGitignore: meta.gitignore_managed !== false
+  });
+}
+
+export function autoInstall({ target = process.cwd(), agent = "all" } = {}) {
+  const manifest = path.join(path.resolve(target), MANIFEST);
+  if (!fs.existsSync(manifest)) return { action: "installed", result: install({ target, agent }) };
+  return { action: "updated", result: update({ target }) };
+}
+
+export function uninstall({ target = process.cwd() } = {}) {
+  target = path.resolve(target);
+  const [manifest, meta] = loadManifest(target);
+  for (const rel of meta.installed || []) removePath(path.join(target, rel));
+  const skillDir = path.join(target, meta.skill_dir || ".agents/skills");
+  pruneEmptyParents(skillDir, target);
+  for (const rel of meta.instruction_files || ["AGENTS.md"]) {
+    const file = path.join(target, rel);
+    removeMarkedBlock(file, BEGIN, END);
+    if (!fs.existsSync(file)) pruneEmptyParents(path.dirname(file), target);
+  }
+  if (meta.gitignore_managed) removeMarkedBlock(path.join(target, ".gitignore"), GITIGNORE_BEGIN, GITIGNORE_END);
+  fs.rmSync(manifest, { force: true });
+  pruneEmptyParents(path.dirname(manifest), target);
+  return { target };
+}
+
+export function status({ target = process.cwd() } = {}) {
+  target = path.resolve(target);
+  const manifest = path.join(target, MANIFEST);
+  if (!fs.existsSync(manifest)) return { installed: false, target, clean: false };
+  const [, meta] = loadManifest(target);
+  const modified = modifiedManagedPaths(target, meta);
+  return {
+    installed: true,
+    target,
+    clean: modified.length === 0,
+    modified,
+    count: (meta.installed || []).length,
+    agent: meta.agent_selection || "unknown",
+    mode: meta.mode || "unknown",
+    packageVersion: meta.package_version || null
+  };
+}
+
+export function listSkills() {
+  const srcRoot = path.join(PACKAGE_ROOT, "skills");
+  return fs.readdirSync(srcRoot).filter((name) => fs.existsSync(path.join(srcRoot, name, "SKILL.md"))).sort();
+}
+
+export function doctor({ target = process.cwd() } = {}) {
+  const reg = registry();
+  const state = status({ target });
+  return {
+    packageRoot: PACKAGE_ROOT,
+    packageVersion: packageVersion(),
+    target: path.resolve(target),
+    canonicalSkills: listSkills().length,
+    install: state,
+    adapters: Object.fromEntries(Object.entries(reg).map(([name, spec]) => [name, {
+      skillDir: spec.skill_dir,
+      instructionFile: spec.instruction_file,
+      present: fs.existsSync(path.join(path.resolve(target), spec.instruction_file))
+    }]))
+  };
+}
+
+export function packageVersion() {
+  return JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf8")).version;
+}
+
+export function isPackageDevelopmentInstall(initCwd) {
+  if (!initCwd) return false;
+  return path.resolve(initCwd) === PACKAGE_ROOT;
+}

package/npm/postinstall.mjs

@@ -0,0 +1,22 @@
+import process from "node:process";
+import { autoInstall, isPackageDevelopmentInstall } from "./core.mjs";
+
+const skip = process.env.POTETOS_SKIP_AUTO_INSTALL === "1" || process.env.POTETOS_SKIP_AUTO_INSTALL === "true";
+const globalInstall = process.env.npm_config_global === "true" || process.env.npm_config_global === "1";
+const execInstall = process.env.npm_command === "exec";
+const target = process.env.INIT_CWD || process.env.PWD || process.cwd();
+
+if (skip || globalInstall || execInstall || !target || isPackageDevelopmentInstall(target)) {
+  if (globalInstall) console.log("potetos: global CLI installed; run `potetos install` inside a project.");
+  process.exit(0);
+}
+
+try {
+  const { action, result } = autoInstall({ target, agent: process.env.POTETOS_AGENT || "all" });
+  console.log(`potetos: ${action} ${result.installed} skills in ${result.target}`);
+  console.log("potetos: ready - ask your agent to use poteto-mode");
+} catch (err) {
+  console.error(`potetos: automatic project setup failed safely: ${err?.message || err}`);
+  console.error("potetos: no differing managed files were overwritten. Resolve the conflict or reinstall with POTETOS_SKIP_AUTO_INSTALL=1 and run the CLI manually.");
+  process.exitCode = 1;
+}

package/npm/potetos.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+import childProcess from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { PACKAGE_ROOT, doctor, install, listSkills, status, uninstall, update } from "./core.mjs";
+
+function fail(message, code = 2) {
+  console.error(`potetos: ${message}`);
+  process.exit(code);
+}
+
+function parse(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) { out._.push(arg); continue; }
+    const key = arg.slice(2);
+    if (["force", "no-gitignore", "copy", "link", "help", "version"].includes(key)) out[key] = true;
+    else {
+      if (i + 1 >= argv.length) fail(`missing value for --${key}`);
+      out[key] = argv[++i];
+    }
+  }
+  return out;
+}
+
+function help() {
+  console.log(`potetos-for-everyone
+
+Usage:
+  npx potetos                     # auto-installs or updates in current repo
+  potetos install [--target .] [--agent all] [--force]
+  potetos update [--target .] [--force]
+  potetos status [--target .]
+  potetos uninstall [--target .]
+  potetos list
+  potetos doctor [--target .]
+  potetos delegate ...            # forwards to bundled Python runner
+  potetos panel ...               # forwards to bundled Python runner
+
+Package manager zero-config install:
+  npm install --save-dev potetos-for-everyone
+  pnpm add -D potetos-for-everyone
+  bun add -d potetos-for-everyone
+  yarn add -D potetos-for-everyone
+
+Local npm installs auto-install/update the skills. Set POTETOS_SKIP_AUTO_INSTALL=1 to disable that lifecycle behavior.`);
+}
+
+function printInstall(result, verb = "installed") {
+  console.log(`${verb} ${result.installed} skills in ${result.target}`);
+  console.log(`compatibility: ${result.agent} (${result.agents.join(", ")})`);
+  console.log(`mode: copy`);
+  console.log(`skills: ${result.skills}`);
+  console.log("ready: ask your agent to use poteto-mode");
+}
+
+function forwardPython(command, rest) {
+  const script = path.join(PACKAGE_ROOT, "bin", "potetos");
+  const candidates = process.platform === "win32" ? [["py", ["-3"]], ["python", []], ["python3", []]] : [["python3", []], ["python", []]];
+  for (const [exe, prefix] of candidates) {
+    const probe = childProcess.spawnSync(exe, [...prefix, "--version"], { stdio: "ignore" });
+    if (!probe.error && probe.status === 0) {
+      const run = childProcess.spawnSync(exe, [...prefix, script, command, ...rest], { stdio: "inherit" });
+      process.exit(run.status ?? 1);
+    }
+  }
+  fail(`${command} needs Python 3.10+ for the external-agent runner. Core install/update/status/uninstall commands do not require Python.`);
+}
+
+const argv = process.argv.slice(2);
+
+if (argv.includes("--help") || argv.includes("-h") || argv[0] === "help") {
+  help();
+  process.exit(0);
+}
+
+if (argv.includes("--version") || argv.includes("-v") || argv[0] === "version") {
+  const { packageVersion } = await import("./core.mjs");
+  console.log(packageVersion());
+  process.exit(0);
+}
+
+let command = argv[0];
+if (!command || command.startsWith("--")) {
+  command = "auto";
+} else {
+  command = argv.shift();
+}
+
+if (["delegate", "panel"].includes(command)) forwardPython(command, argv);
+
+const args = parse(argv);
+const target = args.target || ".";
+if (args.link) fail("the npm CLI installs self-contained copies only; use a source checkout with the Python CLI for development symlinks");
+try {
+  switch (command) {
+    case "auto": {
+      const manifestPath = path.join(path.resolve(target), ".potetos", "install.json");
+      if (fs.existsSync(manifestPath)) {
+        printInstall(update({ target, force: !!args.force }), "updated");
+      } else {
+        printInstall(install({ target, agent: args.agent || "all", force: !!args.force, manageGitignore: !args["no-gitignore"] }));
+      }
+      break;
+    }
+    case "install":
+      printInstall(install({ target, agent: args.agent || "all", force: !!args.force, manageGitignore: !args["no-gitignore"] }));
+      break;
+    case "update":
+      printInstall(update({ target, force: !!args.force }), "updated");
+      break;
+    case "uninstall": {
+      const result = uninstall({ target });
+      console.log(`uninstalled potetos-for-everyone from ${result.target}`);
+      break;
+    }
+    case "status": {
+      const state = status({ target });
+      if (!state.installed) fail(`not installed in ${state.target}`, 1);
+      console.log(`installed: ${state.count} skills`);
+      console.log(`compatibility: ${state.agent}`);
+      console.log(`mode: ${state.mode}`);
+      if (state.packageVersion) console.log(`package: ${state.packageVersion}`);
+      if (!state.clean) {
+        console.log(`state: modified (${state.modified.length} managed paths differ)`);
+        for (const rel of state.modified.slice(0, 10)) console.log(`  ${rel}`);
+        process.exit(1);
+      }
+      console.log("state: clean");
+      break;
+    }
+    case "list":
+      for (const name of listSkills()) console.log(name);
+      break;
+    case "doctor":
+      console.log(JSON.stringify(doctor({ target }), null, 2));
+      break;
+    default:
+      fail(`unknown command ${JSON.stringify(command)}; run potetos --help`);
+  }
+} catch (err) {
+  fail(err?.message || String(err));
+}

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "potetos-for-everyone",
+  "version": "0.1.0",
+  "description": "Universal pstack and Poteto Mode engineering workflow for Claude Code, Cursor, Codex, Gemini, and all AI coding agents. Drop-in pstack-claude alternative with native plugin support.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "potetos": "npm/potetos.mjs",
+    "potetos-for-everyone": "npm/potetos.mjs"
+  },
+  "files": [
+    "npm/",
+    "bin/",
+    "runtime/",
+    "adapters/",
+    "skills/",
+    "agents/",
+    "automations/",
+    "docs/",
+    "assets/",
+    "hooks/",
+    ".claude-plugin/",
+    ".codex-plugin/",
+    ".agents/",
+    "AGENTS.md",
+    "PORTABILITY.md",
+    "NOTICE.md",
+    "UPSTREAM.json",
+    "UPSTREAM_INVENTORY.json",
+    "VERSION",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test tests/npm.test.mjs",
+    "postinstall": "node npm/postinstall.mjs",
+    "test:npm": "node --test tests/npm.test.mjs",
+    "check:pack": "node scripts/check_npm_package.mjs",
+    "prepack": "node scripts/check_npm_package.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TheOnlyFusionCube/potetos-for-everyone.git"
+  },
+  "homepage": "https://github.com/TheOnlyFusionCube/potetos-for-everyone#readme",
+  "bugs": {
+    "url": "https://github.com/TheOnlyFusionCube/potetos-for-everyone/issues"
+  },
+  "keywords": [
+    "pstack",
+    "pstack-claude",
+    "pstack-for-claude",
+    "poteto-mode",
+    "lauren-tan",
+    "claude-code",
+    "claude-code-plugin",
+    "claude-plugin",
+    "claude-skills",
+    "claude",
+    "anthropic",
+    "codex",
+    "codex-plugin",
+    "cursor",
+    "cursor-rules",
+    "gemini",
+    "gemini-cli",
+    "windsurf",
+    "cline",
+    "roo-code",
+    "continue-dev",
+    "copilot",
+    "github-copilot",
+    "agent-skills",
+    "ai-agents",
+    "coding-agents",
+    "developer-tools",
+    "tdd",
+    "test-driven-development",
+    "multi-agent",
+    "subagents",
+    "pi-package",
+    "pi-pstack",
+    "open-pstack",
+    "skills-cli",
+    "pstack-without-cursor",
+    "worktrees"
+  ],
+  "pi": {
+    "skills": ["./skills"],
+    "prompts": [".codex-plugin/prompts"]
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/runtime/README.md

@@ -0,0 +1,21 @@
+# Portable runner protocol
+
+Hosts with native subagents should use them. When native delegation is missing, `potetos-for-everyone` can run arbitrary user-configured AI agent CLIs without knowing their vendor syntax.
+
+Create `.potetos/config.json` from `config.example.json`. Each runner supplies an argv array. Supported placeholders are `{prompt}`, `{prompt_file}`, `{workspace}`, and `{output_file}`. Set `stdin: true` when the CLI accepts the prompt on stdin. Prefer `env_passthrough` for credential variable names; do not commit secret values into `environment`.
+
+Run one worker:
+
+```bash
+./bin/potetos delegate --workspace . --runner default --prompt-file task.md
+```
+
+Run an independent panel:
+
+```bash
+./bin/potetos panel --workspace . --runners default,reviewer --prompt-file review.md
+```
+
+Add `--isolate` for code-writing workers. It refuses a dirty base (except `.potetos/` runtime state), creates a separate Git worktree and `potetos/<run-id>/<runner>` branch per worker, and leaves that worktree intact for review. Outputs and metadata are stored under `.potetos/runs/` by default.
+
+The runner never invokes a shell implicitly: `command` is an argv array executed directly. Any program named there is explicitly user-configured and runs with the permissions of the current process.

package/runtime/__init__.py

@@ -0,0 +1 @@
+"""Portable runtime helpers for potetos-for-everyone."""

package/runtime/capabilities.json

@@ -0,0 +1,36 @@
+{
+  "schema_version": 1,
+  "capabilities": {
+    "files.read": {
+      "required": true
+    },
+    "files.write": {
+      "required": false,
+      "fallback": "return patch/draft"
+    },
+    "run": {
+      "required": false,
+      "fallback": "report verification gap"
+    },
+    "vcs": {
+      "required": false,
+      "fallback": "workspace evidence only"
+    },
+    "delegate": {
+      "required": false,
+      "fallback": "sequential labeled passes"
+    },
+    "search": {
+      "required": false,
+      "fallback": "available local evidence only"
+    },
+    "observe": {
+      "required": false,
+      "fallback": "proxy evidence, explicitly labeled"
+    },
+    "track": {
+      "required": false,
+      "fallback": "Markdown/TSV log when writable"
+    }
+  }
+}

package/runtime/config.example.json

@@ -0,0 +1,17 @@
+{
+  "max_parallel": 4,
+  "runners": {
+    "default": {
+      "command": ["your-agent-cli", "--prompt-file", "{prompt_file}"],
+      "stdin": false,
+      "timeout_seconds": 1800,
+      "env_passthrough": []
+    },
+    "reviewer": {
+      "command": ["another-agent-cli", "--prompt", "{prompt}"],
+      "stdin": false,
+      "timeout_seconds": 1800,
+      "env_passthrough": []
+    }
+  }
+}