nanny-ai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Liv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "nanny-ai",
+  "version": "0.1.0",
+  "description": "Lightweight AI agent loop orchestrator. Ralph Wiggum loops with just enough structure.",
+  "module": "src/main.ts",
+  "type": "module",
+  "bin": {
+    "nanny": "./src/main.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "dev": "bun run src/main.ts",
+    "build": "bun build --compile src/main.ts --outfile nanny",
+    "build:linux": "bun build --compile --target=bun-linux-x64 src/main.ts --outfile nanny-linux-x64",
+    "build:mac-arm": "bun build --compile --target=bun-darwin-arm64 src/main.ts --outfile nanny-darwin-arm64",
+    "build:mac-x64": "bun build --compile --target=bun-darwin-x64 src/main.ts --outfile nanny-darwin-x64",
+    "test": "bun test",
+    "format": "bunx biome format --write src/",
+    "lint": "bunx biome lint src/",
+    "check": "bunx biome check src/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Michaelliv/nannycli.git"
+  },
+  "homepage": "https://github.com/Michaelliv/nannycli#readme",
+  "bugs": {
+    "url": "https://github.com/Michaelliv/nannycli/issues"
+  },
+  "keywords": [
+    "cli",
+    "ai",
+    "agent",
+    "loop",
+    "orchestrator",
+    "ralph-wiggum",
+    "tdd",
+    "claude",
+    "cursor",
+    "aider"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^13.1.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.14",
+    "bun-types": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  }
+}

package/src/commands/add.ts

@@ -0,0 +1,143 @@
+import chalk from "chalk";
+import type { Task, TaskCheck } from "../core/types.ts";
+import { loadState, nextTaskId, saveState } from "../core/state.ts";
+
+interface AddOptions {
+  file: string;
+  json?: boolean;
+  quiet?: boolean;
+  check?: string;
+  checkAgent?: string;
+  target?: string;
+  stdin?: boolean;
+}
+
+interface StdinTask {
+  description: string;
+  check?: TaskCheck | string;
+}
+
+export async function add(
+  description: string | undefined,
+  options: AddOptions,
+): Promise<void> {
+  const state = loadState(options.file);
+
+  if (options.stdin) {
+    const input = await readStdin();
+    const parsed = JSON.parse(input) as StdinTask[];
+
+    if (!Array.isArray(parsed)) {
+      if (options.json) {
+        console.log(
+          JSON.stringify({ ok: false, error: "invalid_input", message: "Expected JSON array" }),
+        );
+      } else {
+        console.error(chalk.red("✗"), "Expected a JSON array of tasks");
+      }
+      process.exit(1);
+    }
+
+    const added: Task[] = [];
+    for (const item of parsed) {
+      const task = createTask(
+        state.tasks,
+        nextTaskId(state) + added.length,
+        typeof item === "string" ? item : item.description,
+        resolveCheck(typeof item === "string" ? undefined : item.check),
+        state.maxAttempts,
+      );
+      added.push(task);
+    }
+    state.tasks.push(...added);
+    saveState(options.file, state);
+
+    if (options.json) {
+      console.log(JSON.stringify({ ok: true, added: added.length, tasks: added }));
+    } else if (!options.quiet) {
+      console.log(chalk.green("✓"), `Added ${added.length} task(s)`);
+      for (const t of added) {
+        console.log(chalk.dim(`  ${t.id}. ${t.description}`));
+      }
+      console.log();
+      console.log(`Start with ${chalk.bold("nanny next")}`);
+    }
+    return;
+  }
+
+  if (!description) {
+    if (options.json) {
+      console.log(
+        JSON.stringify({ ok: false, error: "missing_description" }),
+      );
+    } else {
+      console.error(chalk.red("✗"), "Task description required");
+      console.error(`  Usage: ${chalk.bold("nanny add <description>")}`);
+      console.error(`  Bulk:  ${chalk.bold('echo \'[{"description": "..."}]\' | nanny add --stdin')}`);
+    }
+    process.exit(1);
+  }
+
+  const check = buildCheck(options);
+  const id = nextTaskId(state);
+  const task = createTask(state.tasks, id, description, check, state.maxAttempts);
+  state.tasks.push(task);
+  saveState(options.file, state);
+
+  if (options.json) {
+    console.log(JSON.stringify({ ok: true, task }));
+  } else if (!options.quiet) {
+    console.log(chalk.green("✓"), `Task ${id} added`);
+    console.log(chalk.dim(`  ${description}`));
+    if (check) {
+      if (check.command) console.log(chalk.dim(`  Check: ${check.command}`));
+      if (check.agent) console.log(chalk.dim(`  Scorer: ${check.agent}`));
+    }
+  }
+}
+
+function createTask(
+  _existing: Task[],
+  id: number,
+  description: string,
+  check: TaskCheck | undefined,
+  maxAttempts: number,
+): Task {
+  return {
+    id,
+    description,
+    ...(check ? { check } : {}),
+    status: "pending",
+    attempts: 0,
+    maxAttempts,
+  };
+}
+
+function buildCheck(options: AddOptions): TaskCheck | undefined {
+  if (!options.check && !options.checkAgent) return undefined;
+  const check: TaskCheck = {};
+  if (options.check) check.command = options.check;
+  if (options.checkAgent) check.agent = options.checkAgent;
+  if (options.target) check.target = Number.parseInt(options.target, 10);
+  return check;
+}
+
+function resolveCheck(
+  check: TaskCheck | string | undefined,
+): TaskCheck | undefined {
+  if (!check) return undefined;
+  if (typeof check === "string") return { command: check };
+  return check;
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: string[] = [];
+  const reader = Bun.stdin.stream().getReader();
+  const decoder = new TextDecoder();
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    chunks.push(decoder.decode(value, { stream: true }));
+  }
+  return chunks.join("");
+}

package/src/commands/done.ts

@@ -0,0 +1,73 @@
+import chalk from "chalk";
+import {
+  appendLog,
+  getRunningTask,
+  loadState,
+  saveState,
+} from "../core/state.ts";
+
+interface DoneOptions {
+  file: string;
+  json?: boolean;
+  quiet?: boolean;
+}
+
+export async function done(
+  summary: string | undefined,
+  options: DoneOptions,
+): Promise<void> {
+  const state = loadState(options.file);
+  const task = getRunningTask(state);
+
+  if (!task) {
+    if (options.json) {
+      console.log(
+        JSON.stringify({ ok: false, error: "no_running_task" }),
+      );
+    } else {
+      console.error(chalk.red("✗"), "No task is currently running");
+      console.error(`  Start one with ${chalk.bold("nanny next")}`);
+    }
+    process.exit(1);
+  }
+
+  task.status = "done";
+  task.finishedAt = new Date().toISOString();
+  if (summary) task.summary = summary;
+
+  appendLog(
+    state,
+    task.id,
+    "done",
+    summary ?? `Task ${task.id} completed`,
+  );
+  saveState(options.file, state);
+
+  const pending = state.tasks.filter((t) => t.status === "pending");
+  const total = state.tasks.length;
+  const completed = state.tasks.filter((t) => t.status === "done").length;
+
+  if (options.json) {
+    console.log(
+      JSON.stringify({
+        ok: true,
+        taskId: task.id,
+        completed,
+        total,
+        remaining: pending.length,
+      }),
+    );
+  } else if (!options.quiet) {
+    console.log(chalk.green("✓"), `Task ${task.id} done`, chalk.dim(`(${completed}/${total})`));
+    if (summary) {
+      console.log(chalk.dim(`  ${summary.slice(0, 120)}`));
+    }
+    if (pending.length > 0) {
+      console.log();
+      console.log(`Next: ${chalk.bold("nanny next")}`);
+    } else if (completed === total) {
+      console.log();
+      console.log(chalk.green("🎉 All tasks complete!"));
+    }
+  }
+}

package/src/commands/fail.ts

@@ -0,0 +1,86 @@
+import chalk from "chalk";
+import {
+  appendLog,
+  getRunningTask,
+  loadState,
+  saveState,
+} from "../core/state.ts";
+
+interface FailOptions {
+  file: string;
+  json?: boolean;
+  quiet?: boolean;
+}
+
+export async function fail(
+  error: string,
+  options: FailOptions,
+): Promise<void> {
+  const state = loadState(options.file);
+  const task = getRunningTask(state);
+
+  if (!task) {
+    if (options.json) {
+      console.log(
+        JSON.stringify({ ok: false, error: "no_running_task" }),
+      );
+    } else {
+      console.error(chalk.red("✗"), "No task is currently running");
+      console.error(`  Start one with ${chalk.bold("nanny next")}`);
+    }
+    process.exit(1);
+  }
+
+  const exhausted = task.attempts >= task.maxAttempts;
+
+  task.status = "failed";
+  task.lastError = error;
+  task.finishedAt = new Date().toISOString();
+
+  // If not exhausted, auto-reset to pending for next pickup
+  if (!exhausted) {
+    task.status = "pending";
+  }
+
+  appendLog(
+    state,
+    task.id,
+    "fail",
+    `Attempt ${task.attempts}/${task.maxAttempts}: ${error.slice(0, 200)}`,
+  );
+  saveState(options.file, state);
+
+  if (options.json) {
+    console.log(
+      JSON.stringify({
+        ok: true,
+        taskId: task.id,
+        attempt: task.attempts,
+        maxAttempts: task.maxAttempts,
+        exhausted,
+        status: task.status,
+      }),
+    );
+  } else if (!options.quiet) {
+    if (exhausted) {
+      console.log(
+        chalk.red("✗"),
+        `Task ${task.id} failed — exhausted ${task.maxAttempts} attempts`,
+      );
+      console.log(chalk.red(`  ${error.slice(0, 120)}`));
+      console.log();
+      console.log(
+        `Retry with ${chalk.bold("nanny retry")} or move on with ${chalk.bold("nanny next")}`,
+      );
+    } else {
+      console.log(
+        chalk.yellow("↻"),
+        `Task ${task.id} failed — will retry`,
+        chalk.dim(`(${task.attempts}/${task.maxAttempts})`),
+      );
+      console.log(chalk.dim(`  ${error.slice(0, 120)}`));
+      console.log();
+      console.log(`Continue with ${chalk.bold("nanny next")}`);
+    }
+  }
+}

package/src/commands/init.ts

@@ -0,0 +1,89 @@
+import { existsSync, rmSync } from "node:fs";
+import chalk from "chalk";
+import type { NannyState } from "../core/types.ts";
+import { loadState, saveState } from "../core/state.ts";
+
+interface InitOptions {
+  file: string;
+  json?: boolean;
+  quiet?: boolean;
+  maxAttempts: string;
+  force?: boolean;
+}
+
+export async function init(
+  goal: string,
+  options: InitOptions,
+): Promise<void> {
+  const filePath = options.file;
+
+  if (existsSync(filePath) && !options.force) {
+    const existing = loadState(filePath);
+    const counts = {
+      total: existing.tasks.length,
+      done: existing.tasks.filter((t) => t.status === "done").length,
+      failed: existing.tasks.filter((t) => t.status === "failed").length,
+      running: existing.tasks.filter((t) => t.status === "running").length,
+      pending: existing.tasks.filter((t) => t.status === "pending").length,
+    };
+
+    if (options.json) {
+      console.log(
+        JSON.stringify({
+          ok: false,
+          error: "run_exists",
+          goal: existing.goal,
+          ...counts,
+          hint: "Use --force to replace the existing run.",
+        }),
+      );
+    } else {
+      console.error(
+        chalk.red("✗"),
+        `A run already exists: ${chalk.bold(existing.goal)}`,
+      );
+      console.error(
+        chalk.dim(
+          `  ${counts.done}/${counts.total} done, ${counts.failed} failed, ${counts.running} running, ${counts.pending} pending`,
+        ),
+      );
+      console.error();
+      console.error(
+        `  Use ${chalk.bold("nanny init --force")} to replace it.`,
+      );
+      console.error(
+        `  Use ${chalk.bold("nanny status")} to check the current run.`,
+      );
+    }
+    process.exit(1);
+  }
+
+  if (existsSync(filePath) && options.force) {
+    rmSync(filePath);
+  }
+
+  const now = new Date().toISOString();
+  const state: NannyState = {
+    version: 1,
+    goal,
+    maxAttempts: Number.parseInt(options.maxAttempts, 10),
+    tasks: [],
+    log: [],
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  saveState(filePath, state);
+
+  if (options.json) {
+    console.log(JSON.stringify({ ok: true, goal, file: filePath }));
+  } else if (!options.quiet) {
+    console.log(chalk.green("✓"), "Run created");
+    console.log(chalk.dim(`  Goal: ${goal}`));
+    console.log(chalk.dim(`  File: ${filePath}`));
+    console.log();
+    console.log(
+      `Add tasks with ${chalk.bold("nanny add")} or pipe JSON with ${chalk.bold("nanny add --stdin")}`,
+    );
+  }
+}

package/src/commands/list.ts

@@ -0,0 +1,50 @@
+import chalk from "chalk";
+import { loadState } from "../core/state.ts";
+
+interface ListOptions {
+  file: string;
+  json?: boolean;
+  quiet?: boolean;
+}
+
+const STATUS_ICON: Record<string, string> = {
+  done: chalk.green("✓"),
+  failed: chalk.red("✗"),
+  running: chalk.blue("▶"),
+  pending: chalk.dim("○"),
+};
+
+export async function list(options: ListOptions): Promise<void> {
+  const state = loadState(options.file);
+
+  if (options.json) {
+    console.log(JSON.stringify({ goal: state.goal, tasks: state.tasks }));
+    return;
+  }
+
+  if (state.tasks.length === 0) {
+    console.log(chalk.dim("No tasks."));
+    console.log(`Add some with ${chalk.bold("nanny add")}`);
+    return;
+  }
+
+  console.log(chalk.bold(state.goal));
+  console.log();
+
+  for (const task of state.tasks) {
+    const icon = STATUS_ICON[task.status] ?? "?";
+    const attempts =
+      task.attempts > 0
+        ? chalk.dim(` (${task.attempts}/${task.maxAttempts})`)
+        : "";
+
+    console.log(`  ${icon} ${task.id}. ${task.description}${attempts}`);
+
+    if (task.status === "done" && task.summary) {
+      console.log(chalk.green(`     ${task.summary.slice(0, 120)}`));
+    }
+    if (task.status === "failed" && task.lastError) {
+      console.log(chalk.red(`     ${task.lastError.slice(0, 120)}`));
+    }
+  }
+}

package/src/commands/log.ts

@@ -0,0 +1,49 @@
+import chalk from "chalk";
+import { loadState } from "../core/state.ts";
+
+interface LogOptions {
+  file: string;
+  lines: string;
+  json?: boolean;
+  quiet?: boolean;
+}
+
+const EVENT_STYLE: Record<string, (s: string) => string> = {
+  start: chalk.blue,
+  done: chalk.green,
+  fail: chalk.red,
+  retry: chalk.yellow,
+};
+
+const EVENT_ICON: Record<string, string> = {
+  start: "▶",
+  done: "✓",
+  fail: "✗",
+  retry: "↻",
+};
+
+export async function log(options: LogOptions): Promise<void> {
+  const state = loadState(options.file);
+  const n = Number.parseInt(options.lines, 10);
+  const entries = state.log.slice(-n);
+
+  if (options.json) {
+    console.log(JSON.stringify({ entries }));
+    return;
+  }
+
+  if (entries.length === 0) {
+    console.log(chalk.dim("No log entries."));
+    return;
+  }
+
+  for (const entry of entries) {
+    const icon = EVENT_ICON[entry.event] ?? " ";
+    const style = EVENT_STYLE[entry.event] ?? chalk.dim;
+    const time = new Date(entry.timestamp).toLocaleTimeString();
+
+    console.log(
+      `  ${chalk.dim(time)} ${style(icon)} ${chalk.dim(`[${entry.taskId}]`)} ${entry.message}`,
+    );
+  }
+}

package/src/commands/next.ts

@@ -0,0 +1,146 @@
+import chalk from "chalk";
+import {
+  appendLog,
+  getNextPendingTask,
+  getRunningTask,
+  loadState,
+  saveState,
+} from "../core/state.ts";
+
+interface NextOptions {
+  file: string;
+  json?: boolean;
+  quiet?: boolean;
+}
+
+export async function next(options: NextOptions): Promise<void> {
+  const state = loadState(options.file);
+
+  // Already have a running task
+  const running = getRunningTask(state);
+  if (running) {
+    if (options.json) {
+      console.log(
+        JSON.stringify({
+          ok: true,
+          task: running,
+          resumed: true,
+        }),
+      );
+    } else {
+      console.log(chalk.yellow("▶"), `Task ${running.id} is already running`);
+      console.log(chalk.dim(`  ${running.description}`));
+      console.log();
+      console.log(
+        `Complete with ${chalk.bold("nanny done")} or ${chalk.bold("nanny fail")}`,
+      );
+    }
+    return;
+  }
+
+  // Get next pending task
+  const task = getNextPendingTask(state);
+
+  if (!task) {
+    const failed = state.tasks.filter((t) => t.status === "failed");
+    const done = state.tasks.filter((t) => t.status === "done");
+
+    if (done.length === state.tasks.length) {
+      // All done
+      if (options.json) {
+        console.log(
+          JSON.stringify({
+            ok: true,
+            done: true,
+            total: state.tasks.length,
+            completed: done.length,
+          }),
+        );
+      } else {
+        console.log(chalk.green("✓"), `All ${state.tasks.length} tasks complete.`);
+      }
+      return;
+    }
+
+    if (failed.length > 0) {
+      // Stuck
+      if (options.json) {
+        console.log(
+          JSON.stringify({
+            ok: true,
+            stuck: true,
+            failed: failed.map((t) => ({
+              id: t.id,
+              description: t.description,
+              attempts: t.attempts,
+              lastError: t.lastError,
+            })),
+          }),
+        );
+      } else {
+        console.log(
+          chalk.red("✗"),
+          `Stuck — ${failed.length} task(s) failed`,
+        );
+        for (const t of failed) {
+          console.log(
+            chalk.dim(`  ${t.id}. ${t.description} (${t.attempts} attempts)`),
+          );
+          if (t.lastError) {
+            console.log(chalk.red(`     ${t.lastError.slice(0, 120)}`));
+          }
+        }
+        console.log();
+        console.log(
+          `Retry with ${chalk.bold("nanny retry")} or ${chalk.bold("nanny retry <id>")}`,
+        );
+      }
+      process.exit(1);
+    }
+
+    // No tasks at all
+    if (options.json) {
+      console.log(JSON.stringify({ ok: true, done: true, total: 0, completed: 0 }));
+    } else {
+      console.log(chalk.dim("No tasks. Add some with"), chalk.bold("nanny add"));
+    }
+    return;
+  }
+
+  // Claim the task
+  task.status = "running";
+  task.attempts += 1;
+  task.startedAt = new Date().toISOString();
+  appendLog(state, task.id, "start", `Attempt ${task.attempts}/${task.maxAttempts}: ${task.description}`);
+  saveState(options.file, state);
+
+  if (options.json) {
+    console.log(
+      JSON.stringify({
+        ok: true,
+        task: {
+          id: task.id,
+          description: task.description,
+          ...(task.check ? { check: task.check } : {}),
+          attempt: task.attempts,
+          maxAttempts: task.maxAttempts,
+          ...(task.lastError ? { previousError: task.lastError } : {}),
+        },
+      }),
+    );
+  } else if (!options.quiet) {
+    console.log(chalk.blue("▶"), `Task ${task.id}: ${task.description}`);
+    if (task.check?.command) {
+      console.log(chalk.dim(`  Check: ${task.check.command}`));
+    }
+    if (task.check?.agent) {
+      console.log(chalk.dim(`  Scorer: ${task.check.agent}`));
+    }
+    console.log(
+      chalk.dim(`  Attempt: ${task.attempts}/${task.maxAttempts}`),
+    );
+    if (task.lastError) {
+      console.log(chalk.red(`  Previous error: ${task.lastError.slice(0, 120)}`));
+    }
+  }
+}

package/src/commands/onboard.ts

@@ -0,0 +1,129 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import chalk from "chalk";
+
+interface OnboardOptions {
+  file?: string;
+  json?: boolean;
+  quiet?: boolean;
+}
+
+const NANNY_INSTRUCTIONS = `
+<nanny>
+Use \`nanny\` to orchestrate multi-step tasks. Nanny is a lightweight task state machine — you drive the loop, it tracks state.
+
+<workflow>
+1. \`nanny init "goal" --json\` — Create a run (use \`--force\` to replace existing)
+2. \`echo '[{"description": "..."}]' | nanny add --stdin --json\` — Add tasks (bulk JSON)
+3. \`nanny next --json\` — Get and claim the next pending task
+4. Perform the task (run code, delegate to sub-agent, etc.)
+5. \`nanny done "summary" --json\` or \`nanny fail "error" --json\` — Record result
+6. Repeat from step 3 until \`nanny next\` returns \`{"ok":true,"done":true}\`
+</workflow>
+
+<commands>
+- \`nanny init <goal> --json\` — Create a run (\`--force\` to replace, \`--max-attempts <n>\` for retries)
+- \`nanny add <desc> --json\` — Add a single task (\`--check "npm test"\` for verification command)
+- \`nanny add --stdin --json\` — Bulk add from JSON array on stdin
+- \`nanny next --json\` — Get + start next task (returns task with previousError on retries)
+- \`nanny done "summary" --json\` — Complete the running task
+- \`nanny fail "error" --json\` — Fail the running task (auto-requeues if under max attempts)
+- \`nanny retry [id] --json\` — Reset an exhausted failed task to pending
+- \`nanny status --json\` — Progress overview
+- \`nanny list --json\` — All tasks with status
+- \`nanny log --json\` — Execution history
+</commands>
+
+<task-format>
+When adding tasks via \`--stdin\`, pipe a JSON array:
+\`\`\`json
+[
+  {"description": "create users table", "check": "npm test"},
+  {"description": "implement endpoint"},
+  {"description": "verify coverage", "check": {"command": "npm test", "agent": "check coverage > 80%", "target": 80}}
+]
+\`\`\`
+</task-format>
+
+<retry-loop>
+When \`nanny next --json\` returns a task with \`previousError\`, use that error as context to fix the issue.
+The Ralph Wiggum loop: attempt → check → feed back errors → retry. Failures are data.
+</retry-loop>
+
+<rules>
+- ALWAYS use \`--json\` flag for structured output
+- ALWAYS call \`nanny next\` to claim a task before working on it
+- ALWAYS call \`nanny done\` or \`nanny fail\` after each task — never leave a task running
+- When \`nanny next\` returns \`done: true\`, the run is complete — stop looping
+- When \`nanny next\` returns \`stuck: true\`, decide whether to \`nanny retry\` or report to the user
+- Do not write to \`.nanny/state.json\` directly — always use the CLI
+</rules>
+</nanny>
+`.trim();
+
+const MARKER = "<nanny>";
+
+export async function onboard(options: OnboardOptions = {}): Promise<void> {
+  const cwd = process.cwd();
+  const claudeDir = join(cwd, ".claude");
+  const claudeMd = join(claudeDir, "CLAUDE.md");
+  const agentsMd = join(cwd, "AGENTS.md");
+
+  // Find target: prefer existing AGENTS.md, then .claude/CLAUDE.md, then create .claude/CLAUDE.md
+  let targetFile: string;
+  if (existsSync(agentsMd)) {
+    targetFile = agentsMd;
+  } else if (existsSync(claudeMd)) {
+    targetFile = claudeMd;
+  } else {
+    targetFile = claudeMd;
+  }
+
+  let existingContent = "";
+  if (existsSync(targetFile)) {
+    existingContent = readFileSync(targetFile, "utf-8");
+  }
+
+  // Idempotent
+  if (existingContent.includes(MARKER)) {
+    if (options.json) {
+      console.log(
+        JSON.stringify({
+          ok: true,
+          file: targetFile,
+          status: "already_onboarded",
+        }),
+      );
+    } else if (!options.quiet) {
+      console.log(chalk.green("✓"), "Already onboarded");
+      console.log(chalk.dim(`  ${targetFile}`));
+    }
+    return;
+  }
+
+  // Ensure directory exists for .claude/CLAUDE.md
+  const targetDir = join(targetFile, "..");
+  if (!existsSync(targetDir)) {
+    mkdirSync(targetDir, { recursive: true });
+  }
+
+  if (existingContent) {
+    writeFileSync(
+      targetFile,
+      `${existingContent.trimEnd()}\n\n${NANNY_INSTRUCTIONS}\n`,
+    );
+  } else {
+    writeFileSync(targetFile, `${NANNY_INSTRUCTIONS}\n`);
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify({ ok: true, file: targetFile }));
+  } else if (!options.quiet) {
+    console.log(
+      chalk.green("✓"),
+      `Added nanny instructions to ${chalk.bold(targetFile)}`,
+    );
+    console.log();
+    console.log(chalk.dim("Your agent now knows how to use nanny!"));
+  }
+}

package/src/commands/retry.ts

@@ -0,0 +1,83 @@
+import chalk from "chalk";
+import {
+  appendLog,
+  getTaskById,
+  loadState,
+  saveState,
+} from "../core/state.ts";
+
+interface RetryOptions {
+  file: string;
+  json?: boolean;
+  quiet?: boolean;
+}
+
+export async function retry(
+  idArg: string | undefined,
+  options: RetryOptions,
+): Promise<void> {
+  const state = loadState(options.file);
+
+  let task;
+
+  if (idArg) {
+    const id = Number.parseInt(idArg, 10);
+    task = getTaskById(state, id);
+    if (!task) {
+      if (options.json) {
+        console.log(JSON.stringify({ ok: false, error: "not_found", id }));
+      } else {
+        console.error(chalk.red("✗"), `Task ${id} not found`);
+      }
+      process.exit(1);
+    }
+  } else {
+    // Default: last failed task
+    const failed = state.tasks.filter((t) => t.status === "failed");
+    if (failed.length === 0) {
+      if (options.json) {
+        console.log(
+          JSON.stringify({ ok: false, error: "no_failed_tasks" }),
+        );
+      } else {
+        console.error(chalk.red("✗"), "No failed tasks to retry");
+      }
+      process.exit(1);
+    }
+    task = failed[failed.length - 1];
+  }
+
+  if (task.status !== "failed") {
+    if (options.json) {
+      console.log(
+        JSON.stringify({
+          ok: false,
+          error: "not_failed",
+          id: task.id,
+          status: task.status,
+        }),
+      );
+    } else {
+      console.error(
+        chalk.red("✗"),
+        `Task ${task.id} is ${task.status}, not failed`,
+      );
+    }
+    process.exit(1);
+  }
+
+  task.status = "pending";
+  task.attempts = 0;
+
+  appendLog(state, task.id, "retry", `Reset to pending for retry`);
+  saveState(options.file, state);
+
+  if (options.json) {
+    console.log(JSON.stringify({ ok: true, taskId: task.id }));
+  } else if (!options.quiet) {
+    console.log(chalk.green("↻"), `Task ${task.id} reset to pending`);
+    console.log(chalk.dim(`  ${task.description}`));
+    console.log();
+    console.log(`Pick it up with ${chalk.bold("nanny next")}`);
+  }
+}

package/src/commands/status.ts

@@ -0,0 +1,96 @@
+import chalk from "chalk";
+import { getRunningTask, loadState } from "../core/state.ts";
+
+interface StatusOptions {
+  file: string;
+  json?: boolean;
+  quiet?: boolean;
+}
+
+export async function status(options: StatusOptions): Promise<void> {
+  const state = loadState(options.file);
+
+  const counts = {
+    total: state.tasks.length,
+    done: state.tasks.filter((t) => t.status === "done").length,
+    failed: state.tasks.filter((t) => t.status === "failed").length,
+    pending: state.tasks.filter((t) => t.status === "pending").length,
+    running: state.tasks.filter((t) => t.status === "running").length,
+  };
+
+  const running = getRunningTask(state);
+
+  if (options.json) {
+    console.log(
+      JSON.stringify({
+        goal: state.goal,
+        ...counts,
+        ...(running
+          ? {
+              currentTask: {
+                id: running.id,
+                description: running.description,
+                attempt: running.attempts,
+                maxAttempts: running.maxAttempts,
+              },
+            }
+          : {}),
+      }),
+    );
+    return;
+  }
+
+  console.log(chalk.bold(state.goal));
+  console.log();
+
+  if (counts.total === 0) {
+    console.log(chalk.dim("  No tasks yet."));
+    console.log();
+    console.log(`Add tasks with ${chalk.bold("nanny add")}`);
+    return;
+  }
+
+  const bar = renderBar(counts.done, counts.failed, counts.total);
+  console.log(`  ${bar}  ${counts.done}/${counts.total}`);
+  console.log();
+
+  if (running) {
+    console.log(
+      chalk.blue(`  ▶ running: ${running.description}`),
+      chalk.dim(`(attempt ${running.attempts}/${running.maxAttempts})`),
+    );
+  }
+  if (counts.done > 0) {
+    console.log(chalk.green(`  ✓ ${counts.done} done`));
+  }
+  if (counts.failed > 0) {
+    console.log(chalk.red(`  ✗ ${counts.failed} failed`));
+  }
+  if (counts.pending > 0) {
+    console.log(chalk.dim(`  ○ ${counts.pending} pending`));
+  }
+
+  if (counts.done === counts.total) {
+    console.log();
+    console.log(chalk.green("  🎉 All tasks complete!"));
+  }
+}
+
+function renderBar(
+  done: number,
+  failed: number,
+  total: number,
+): string {
+  const width = 30;
+  if (total === 0) return chalk.dim("░".repeat(width));
+
+  const doneW = Math.round((done / total) * width);
+  const failW = Math.round((failed / total) * width);
+  const restW = width - doneW - failW;
+
+  return (
+    chalk.green("█".repeat(doneW)) +
+    chalk.red("█".repeat(failW)) +
+    chalk.dim("░".repeat(Math.max(0, restW)))
+  );
+}

package/src/core/state.ts

@@ -0,0 +1,50 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import type { LogEntry, NannyState, Task } from "./types.ts";
+
+export function loadState(filePath: string): NannyState {
+  if (!existsSync(filePath)) {
+    throw new Error(`No run found. Run 'nanny init <goal>' first.`);
+  }
+  return JSON.parse(readFileSync(filePath, "utf-8"));
+}
+
+export function saveState(filePath: string, state: NannyState): void {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  state.updatedAt = new Date().toISOString();
+  writeFileSync(filePath, `${JSON.stringify(state, null, 2)}\n`);
+}
+
+export function appendLog(
+  state: NannyState,
+  taskId: number,
+  event: LogEntry["event"],
+  message: string,
+): void {
+  state.log.push({
+    timestamp: new Date().toISOString(),
+    taskId,
+    event,
+    message,
+  });
+}
+
+export function getRunningTask(state: NannyState): Task | undefined {
+  return state.tasks.find((t) => t.status === "running");
+}
+
+export function getNextPendingTask(state: NannyState): Task | undefined {
+  return state.tasks.find((t) => t.status === "pending");
+}
+
+export function getTaskById(state: NannyState, id: number): Task | undefined {
+  return state.tasks.find((t) => t.id === id);
+}
+
+export function nextTaskId(state: NannyState): number {
+  if (state.tasks.length === 0) return 1;
+  return Math.max(...state.tasks.map((t) => t.id)) + 1;
+}

package/src/core/types.ts

@@ -0,0 +1,40 @@
+export type TaskStatus = "pending" | "running" | "done" | "failed";
+
+export interface TaskCheck {
+  /** Shell command to verify (e.g. "npm test") */
+  command?: string;
+  /** Prompt for an agent scorer */
+  agent?: string;
+  /** Score threshold (0-100) for agent checks */
+  target?: number;
+}
+
+export interface Task {
+  id: number;
+  description: string;
+  check?: TaskCheck;
+  status: TaskStatus;
+  attempts: number;
+  maxAttempts: number;
+  summary?: string;
+  lastError?: string;
+  startedAt?: string;
+  finishedAt?: string;
+}
+
+export interface LogEntry {
+  timestamp: string;
+  taskId: number;
+  event: "start" | "done" | "fail" | "retry";
+  message: string;
+}
+
+export interface NannyState {
+  version: 1;
+  goal: string;
+  maxAttempts: number;
+  tasks: Task[];
+  log: LogEntry[];
+  createdAt: string;
+  updatedAt: string;
+}

package/src/main.ts

@@ -0,0 +1,94 @@
+#!/usr/bin/env bun
+
+import { Command } from "commander";
+import { version } from "../package.json";
+import { init } from "./commands/init.ts";
+import { add } from "./commands/add.ts";
+import { next } from "./commands/next.ts";
+import { done } from "./commands/done.ts";
+import { fail } from "./commands/fail.ts";
+import { retry } from "./commands/retry.ts";
+import { status } from "./commands/status.ts";
+import { list } from "./commands/list.ts";
+import { log } from "./commands/log.ts";
+import { onboard } from "./commands/onboard.ts";
+
+const program = new Command();
+
+program
+  .name("nanny")
+  .description("Lightweight AI agent task orchestrator")
+  .version(version)
+  .option("--json", "Structured JSON output")
+  .option("-q, --quiet", "Suppress non-essential output")
+  .option(
+    "-f, --file <path>",
+    "State file path",
+    ".nanny/state.json",
+  );
+
+program
+  .command("init")
+  .description("Create a new run")
+  .argument("<goal>", "What needs to be accomplished")
+  .option("--max-attempts <n>", "Max attempts per task", "3")
+  .option("--force", "Replace existing run")
+  .action((goal, opts) => init(goal, { ...program.opts(), ...opts }));
+
+program
+  .command("add")
+  .description("Add a task")
+  .argument("[description]", "Task description")
+  .option("--check <command>", "Shell command to verify (e.g. npm test)")
+  .option("--check-agent <prompt>", "Agent scorer prompt")
+  .option("--target <n>", "Score threshold for agent check (0-100)")
+  .option("--stdin", "Read tasks from JSON stdin")
+  .action((description, opts) =>
+    add(description, { ...program.opts(), ...opts }),
+  );
+
+program
+  .command("next")
+  .description("Get and start the next pending task")
+  .action((opts) => next({ ...program.opts(), ...opts }));
+
+program
+  .command("done")
+  .description("Complete the current task")
+  .argument("[summary]", "Summary of what was done")
+  .action((summary, opts) => done(summary, { ...program.opts(), ...opts }));
+
+program
+  .command("fail")
+  .description("Fail the current task")
+  .argument("<error>", "What went wrong")
+  .action((error, opts) => fail(error, { ...program.opts(), ...opts }));
+
+program
+  .command("retry")
+  .description("Reset a failed task to pending")
+  .argument("[id]", "Task ID (defaults to last failed)")
+  .action((id, opts) => retry(id, { ...program.opts(), ...opts }));
+
+program
+  .command("status")
+  .description("Progress overview")
+  .action((opts) => status({ ...program.opts(), ...opts }));
+
+program
+  .command("list")
+  .description("All tasks with status")
+  .action((opts) => list({ ...program.opts(), ...opts }));
+
+program
+  .command("log")
+  .description("Execution history")
+  .option("-n, --lines <n>", "Number of entries to show", "20")
+  .action((opts) => log({ ...program.opts(), ...opts }));
+
+program
+  .command("onboard")
+  .description("Add nanny instructions to your agent config")
+  .action((opts) => onboard({ ...program.opts(), ...opts }));
+
+program.parse();