orchestrator-workflow 0.1.0 → 0.3.0

package/INSTALL-AGENT.md

@@ -1,16 +1,71 @@
 # Installing via a coding agent
 
-The interactive installer asks a human questions on a TTY. When the install
-should be done by a coding agent instead (Claude Code, Codex, opencode), the
-agent takes over that interactivity: it asks the operator the same questions
-in chat, then runs the non-interactive CLI, or scaffolds manually where npx
-is unavailable.
+Give your agent this single line:
 
-Paste the prompt below to your agent, as is.
+```text
+Follow the install instructions at https://raw.githubusercontent.com/LanNguyenSi/agent-dx/master/packages/orchestrator-workflow/INSTALL-AGENT.md
+```
 
----
+The agent fetches this file and executes the numbered instructions in the
+"Instructions for the agent" section at the bottom. The two sections in
+between explain, for you, what those instructions make the agent do and
+which files it may touch, so you can audit the prompt before delegating.
 
-Install the orchestrator-workflow kit into this repository.
+The audit applies to the revision you read: the link above tracks `master`,
+which is mutable. For a stable audit, pin the URL to a commit SHA instead
+(replace `master` with the SHA).
+
+## What the linked instructions do
+
+1. **Locate existing harness configs** in the repo root and report them to
+   you (Claude Code, opencode, Codex marker files; full list in step 1
+   below).
+2. **Ask you, not guess**: which harnesses should get adapters, and which
+   model each subagent role (task-slicer, implementer, reviewer) should use.
+   Suggested defaults: task-slicer `sonnet`, implementer `sonnet`, reviewer
+   `opus`.
+3. **Run the non-interactive installer** with your answers:
+   `npx orchestrator-workflow init --yes --harness ... --models ...`.
+   If the installer reports conflicts with locally edited files, the agent
+   shows them to you and asks before any `--force` re-run.
+4. **Manual fallback only when npx or the registry is unavailable**: create
+   the same files by hand from this repository's `assets/` directory,
+   following the byte-precise rules in step 4 below.
+5. **Report back**: which harnesses were installed, which model each role
+   uses, and any conflicts left in place.
+
+### Write surface
+
+The install creates or touches only these paths:
+
+- `.ai/workflow/templates/00-goal.md` through `06-handoff.md`,
+  `.ai/workflow/manifest.json`, `.ai/runs/.gitkeep` (new files)
+- `AGENTS.md`: the marker-fenced workflow section is appended (file created
+  when missing); content outside the
+  `<!-- orchestrator-workflow:begin -->` / `<!-- orchestrator-workflow:end -->`
+  markers is never modified
+- `CLAUDE.md`: one `@AGENTS.md` import line appended when missing; the file
+  is created with a short heading when absent (Claude Code harness only)
+- `.claude/skills/orchestrator-workflow/SKILL.md` and
+  `.claude/agents/{task-slicer,implementer,reviewer}.md` (Claude Code)
+- `.agents/skills/orchestrator-workflow/SKILL.md` (Codex)
+- `.opencode/agents/{task-slicer,implementer,reviewer}.md` (opencode)
+
+Nothing else in the repository is modified. Locally edited files are
+reported as conflicts and left alone, never overwritten silently; the
+exceptions are the kit-owned surfaces: `.ai/workflow/manifest.json` (the
+kit's state file, rewritten whenever the applied state changes) and the
+fenced AGENTS.md section itself, which is restored on re-run. The install
+is fully reversible: `npx orchestrator-workflow uninstall` removes exactly
+this write surface again, keeping run history under `.ai/runs/` and any
+locally edited files. Network access is limited to the npm registry (for
+`npx`) and, in the manual fallback, this repository on github.com /
+raw.githubusercontent.com.
+
+## Instructions for the agent
+
+You are a coding agent that was pointed at this file. Execute the following
+steps in the repository you were asked to install into.
 
 1. Detect existing harness configs in the repo root: `.claude/` or
    `CLAUDE.md` (Claude Code), `.opencode/`, `opencode.json` or
@@ -42,7 +97,8 @@ Install the orchestrator-workflow kit into this repository.
      `assets/templates/`, unchanged.
    - `.ai/runs/.gitkeep`, empty.
    - Append the content of `assets/agents-md-section.md` to `AGENTS.md`
-     (create the file when missing). Never change anything outside the
+     (create the file when missing; the installer starts a fresh file with a
+     `# Agent instructions` heading). Never change anything outside the
      `<!-- orchestrator-workflow:begin -->` / `<!-- orchestrator-workflow:end -->`
      markers.
    - Claude Code: `.claude/skills/orchestrator-workflow/SKILL.md` from
@@ -59,7 +115,7 @@ Install the orchestrator-workflow kit into this repository.
      `anthropic/claude-sonnet-4-6`, `anthropic/claude-opus-4-8`,
      `anthropic/claude-haiku-4-5`.
    - `.ai/workflow/manifest.json`, exactly this shape (harnesses MUST be an
-     array, models keyed by role):
+     array, models keyed by role, version = the kit version you installed):
 
      ```json
      {

package/README.md

@@ -10,16 +10,56 @@ plan, task validation, acceptance, and the operator handoff. Implementation
 and review are delegated to narrow subagents that return structured YAML
 evidence. Every unit of work leaves an auditable run directory behind.
 
+## Why this shape
+
+```text
+              Operator
+          goal |    ^ handoff: what changed, how verified,
+               v    | what remains open
+          Orchestrator  . . . . . . .  .ai/runs/<date>-<slug>/
+          session model                  00-goal       04-implementation-summary
+          plans, validates slices,       01-plan       05-review-findings
+          decides acceptance             02-tasks      06-handoff
+               |                         03-decisions
+    narrow     |     ^ structured        (state lives in files,
+    contracts  v     | YAML evidence      not in chat history)
+      +--------------+--------------+
+      |              |              |
+  task-slicer    implementer    reviewer
+    sonnet         sonnet         opus
+  small,         one narrow     skeptical, severity-rated
+  testable       task, plus     findings, no rewrites
+  slices         tests
+```
+
+Two effects fall out of this shape:
+
+- **Token efficiency.** The orchestrator's context stays small: subagents
+  receive narrow task contracts instead of the whole conversation, return
+  structured YAML evidence instead of transcripts, and durable state lives
+  in run files that survive context compaction. The cheap models do the
+  volume work; the strongest model is spent only on orchestration decisions
+  and the skeptical review. The ceremony scales to the task: a trivial change
+  is done directly, the full flow is for non-trivial work.
+- **Quality through structure.** Writing and reviewing are separated by
+  role and model, task slices are validated before any implementation
+  starts, acceptance is decided on evidence (tests executed, findings
+  addressed), and every run leaves an auditable trail in `.ai/runs/`.
+
 ## Install
 
 ```bash
 npx orchestrator-workflow init
 ```
 
-Run it at the root of the target repository. The installer is interactive by
-default: it locates existing harness configs (`.claude/`, `CLAUDE.md`,
-`.opencode/`, `opencode.json`, `.agents/`, `.codex/`), preselects what it
-found, and asks which model each subagent role should use.
+Run it at the root of the target repository: **without a directory argument,
+files are created in the current working directory.** The CLI prints the
+resolved target (`Installing into ...`) before it writes anything and warns
+when the target is not a git repository root; pass `init <dir>` to install
+into a different directory. The installer is interactive by default: it
+locates existing harness configs (`.claude/`, `CLAUDE.md`, `.opencode/`,
+`opencode.json`, `.agents/`, `.codex/`), preselects what it found, and asks
+which model each subagent role should use.
 
 Non-interactive:
 
@@ -28,10 +68,18 @@ npx orchestrator-workflow init --yes
 npx orchestrator-workflow init --harness claude,codex,opencode --models "implementer=sonnet,reviewer=opus" --yes
 ```
 
-To let a coding agent do the install, paste the prompt from
-[INSTALL-AGENT.md](INSTALL-AGENT.md): the agent asks the operator the
-harness and model questions in chat, then runs the non-interactive CLI, or
-scaffolds manually where npx is unavailable.
+To let a coding agent do the install, give it this single line:
+
+```text
+Follow the install instructions at https://raw.githubusercontent.com/LanNguyenSi/agent-dx/master/packages/orchestrator-workflow/INSTALL-AGENT.md
+```
+
+The agent then asks you the harness and model questions in chat and runs the
+non-interactive CLI (manual scaffolding where npx is unavailable).
+[INSTALL-AGENT.md](INSTALL-AGENT.md) documents, step by step, what the
+linked instructions make the agent do and which files it may touch, so the
+prompt can be audited before delegating. The link tracks `master`; pin it
+to a commit SHA for a stable audit.
 
 ## What gets installed
 
@@ -85,6 +133,20 @@ in `.ai/workflow/manifest.json` and reused as the default on later re-runs.
   version, harnesses, models, and file hashes, and is rewritten whenever that
   state changes; do not edit it by hand.
 
+## Uninstall
+
+```bash
+npx orchestrator-workflow uninstall
+```
+
+Removes exactly what `init` created, driven by the manifest's file hashes:
+unedited kit files are deleted, locally edited ones are kept and reported
+(`--force` removes those too). The AGENTS.md section and the CLAUDE.md
+import line are taken out; either file is deleted only when nothing but
+init's own boilerplate remains. Kit directories are pruned only when empty,
+and run history under `.ai/runs/` is always kept. Interactive runs ask for
+confirmation; non-interactive runs require `--yes`.
+
 ## Relation to agentic-coding-playbook
 
 This kit ships the orchestration layer: who coordinates whom, where state

package/assets/agents-md-section.md

@@ -5,10 +5,9 @@ This repository uses an orchestrator-led agent workflow, installed and updated b
 [orchestrator-workflow](https://github.com/LanNguyenSi/agent-dx/tree/master/packages/orchestrator-workflow).
 
 The primary agent acts as the orchestrator. It owns the goal, planning, task
-validation, delegation, final acceptance, and the operator handoff.
-Implementation and technical review are delegated to narrow subagents. The full
-procedure and the subagent I/O contracts live in the `orchestrator-workflow`
-skill.
+validation, delegation, final acceptance, and the operator handoff. Non-trivial
+implementation and review are delegated to narrow subagents. The full procedure
+and the subagent I/O contracts live in the `orchestrator-workflow` skill.
 
 ### Core rules
 
@@ -16,12 +15,28 @@ skill.
   further subagents.
 - The orchestrator plans features itself. It may delegate task slicing, but it
   validates the sliced tasks before implementation starts.
-- Implementation goes to narrow implementer subagents, one task per subagent.
-- Technical review goes to a separate reviewer subagent. Review is never
-  skipped, not even for docs or batch changes.
+- Non-trivial implementation goes to narrow implementer subagents, one task
+  per subagent.
+- Non-trivial review goes to a separate reviewer subagent (see Scaling
+  delegation). Review itself is never skipped, not even for docs or batch
+  changes.
 - Final acceptance and the final answer to the operator stay with the
   orchestrator.
 
+### Scaling delegation
+
+The orchestrator matches the ceremony to the task; the full flow is a
+default, not a ritual.
+
+- A trivial change (a typo, a one-line fix, a rename) may be implemented by
+  the orchestrator directly, without slicing or an implementer subagent.
+- Slicing and implementer subagents are for non-trivial work: multiple files,
+  real logic, or anything that benefits from decomposition or a fresh context.
+- Review judgment applies to every change. For a trivial change the
+  orchestrator may review it itself; reserve the reviewer subagent for
+  changes whose risk or size warrants an independent skeptical pass. Either
+  way, review is never skipped.
+
 ### Context discipline
 
 - Prefer task-local context over repository-wide context.

package/assets/skill/SKILL.md

@@ -15,6 +15,12 @@ tasks to specialized subagents. The goal is to improve quality, reduce
 context-window pressure, and keep the operator informed through structured
 handoffs.
 
+Scale the ceremony to the task. The workflow below is the default for
+non-trivial work; a trivial change (a typo, a one-line fix) may be done
+directly by the orchestrator and reviewed by it, without slicing or spawning
+subagents. Review judgment still applies to every change; only the size of
+the apparatus changes.
+
 ## Roles
 
 - **Operator**: the human requester. Provides goal and constraints, approves or
@@ -58,6 +64,10 @@ older directories are the auditable history. Do not edit past runs.
 
 ## Workflow
 
+For a non-trivial change, run the full flow below. For a trivial change, do
+the work directly, review it, and still leave a short handoff; skip the run
+directory and the subagents.
+
 1. **Understand the goal.** Create the run directory and fill `00-goal.md`:
    operator request, goal, non-goals, constraints, assumptions, open questions.
    If the task can proceed on reasonable assumptions, proceed without blocking.

package/dist/cli.js

@@ -1,15 +1,32 @@
 #!/usr/bin/env node
 import { existsSync, statSync } from "node:fs";
-import { resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { Command } from "commander";
 import inquirer from "inquirer";
 import { PACKAGE_VERSION } from "./assets.js";
 import { HARNESSES, detectHarnesses, parseHarnessList } from "./detect.js";
 import { DEFAULT_MODELS, MODEL_ALIASES, ROLES, assertValidModelId, parseModelsSpec, } from "./models.js";
 import { readInstalledManifest, runInit } from "./init.js";
+import { runUninstall } from "./uninstall.js";
 function isInteractive() {
     return Boolean(process.stdin.isTTY && process.stdout.isTTY);
 }
+function showPaths(label, paths) {
+    if (paths.length === 0)
+        return;
+    console.log(`${label}:`);
+    for (const path of paths)
+        console.log(`  ${path}`);
+}
+function requireDirectory(dir) {
+    const targetDir = resolve(dir);
+    if (!existsSync(targetDir) || !statSync(targetDir).isDirectory()) {
+        console.error(`Target is not a directory: ${targetDir}`);
+        process.exitCode = 1;
+        return undefined;
+    }
+    return targetDir;
+}
 async function promptHarnesses(detected, installed) {
     const known = [...new Set([...detected, ...installed])];
     const preselected = known.length > 0 ? known : ["claude"];
@@ -85,13 +102,16 @@ program
     .option("--harness <list>", `comma-separated harnesses (${HARNESSES.join(", ")}); default: detected`)
     .option("--models <spec>", 'per-role model overrides, e.g. "implementer=sonnet,reviewer=opus"')
     .action(async (dir, opts) => {
-    const targetDir = resolve(dir);
-    if (!existsSync(targetDir) || !statSync(targetDir).isDirectory()) {
-        console.error(`Target is not a directory: ${targetDir}`);
-        process.exitCode = 1;
+    const targetDir = requireDirectory(dir);
+    if (!targetDir)
         return;
-    }
     const interactive = !opts.yes && isInteractive();
+    // Say where files will land BEFORE anything is written; an accidental
+    // cwd (e.g. $HOME) is the most likely operator mistake.
+    console.log(`Installing into ${targetDir}`);
+    if (!existsSync(join(targetDir, ".git"))) {
+        console.log("Note: the target is not a git repository root. Pass a directory argument (init <dir>) if this is not the repo you meant.");
+    }
     const detected = detectHarnesses(targetDir);
     console.log(detected.length > 0
         ? `Detected harness configs: ${detected.join(", ")}`
@@ -133,19 +153,58 @@ program
         models,
         force: opts.force,
     });
-    const show = (label, paths) => {
-        if (paths.length === 0)
-            return;
-        console.log(`${label}:`);
-        for (const path of paths)
-            console.log(`  ${path}`);
-    };
-    show("Created", report.written);
-    show("Updated", report.updated);
-    show("Unchanged", report.skipped);
-    show("Conflicts (local edits kept, re-run with --force to overwrite)", report.conflicted);
+    showPaths("Created", report.written);
+    showPaths("Updated", report.updated);
+    showPaths("Unchanged", report.skipped);
+    showPaths("Conflicts (local edits kept, re-run with --force to overwrite)", report.conflicted);
     console.log(`\norchestrator-workflow v${PACKAGE_VERSION} installed for: ${harnesses.join(", ")}`);
 });
+program
+    .command("uninstall")
+    .description("Remove everything init installed from a target repository; run history under .ai/runs/ is kept")
+    .argument("[dir]", "target repository directory", ".")
+    .option("-y, --yes", "do not ask for confirmation")
+    .option("-f, --force", "also remove kit files that have local edits")
+    .action(async (dir, opts) => {
+    const targetDir = requireDirectory(dir);
+    if (!targetDir)
+        return;
+    console.log(`Uninstalling from ${targetDir}`);
+    if (!opts.yes) {
+        if (!isInteractive()) {
+            console.error("Refusing to uninstall without confirmation in a non-interactive session; pass --yes.");
+            process.exitCode = 1;
+            return;
+        }
+        const { confirmed } = await inquirer.prompt([
+            {
+                type: "confirm",
+                name: "confirmed",
+                message: `Remove the orchestrator-workflow kit from ${targetDir}?`,
+                default: false,
+            },
+        ]);
+        if (!confirmed) {
+            console.log("Aborted.");
+            return;
+        }
+    }
+    let report;
+    try {
+        report = runUninstall({ targetDir, force: opts.force });
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+        process.exitCode = 1;
+        return;
+    }
+    showPaths("Removed", report.removed);
+    showPaths("Kept (local edits or damaged fence)", report.kept);
+    showPaths("Already absent", report.missing);
+    for (const note of report.notes)
+        console.log(note);
+    console.log(`\norchestrator-workflow uninstalled from ${targetDir}`);
+});
 program.parseAsync(process.argv).catch((error) => {
     console.error(error instanceof Error ? error.message : error);
     process.exitCode = 1;

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { runInit } from "./init.js";
 export type { InitOptions } from "./init.js";
+export { runUninstall } from "./uninstall.js";
+export type { UninstallReport } from "./uninstall.js";
 export { detectHarnesses, parseHarnessList, HARNESSES } from "./detect.js";
 export type { Harness } from "./detect.js";
 export { DEFAULT_MODELS, MODEL_ALIASES, ROLES, claudeModelValue, opencodeModelValue, parseModelsSpec, } from "./models.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 export { runInit } from "./init.js";
+export { runUninstall } from "./uninstall.js";
 export { detectHarnesses, parseHarnessList, HARNESSES } from "./detect.js";
 export { DEFAULT_MODELS, MODEL_ALIASES, ROLES, claudeModelValue, opencodeModelValue, parseModelsSpec, } from "./models.js";
 export { PACKAGE_VERSION } from "./assets.js";

package/dist/init.d.ts

@@ -19,6 +19,13 @@ export interface Manifest {
     files: Record<string, string>;
     installedAt: string;
 }
+/**
+ * A manifest can be hand-written or tampered with, and uninstall deletes by
+ * these paths. Only relative paths that stay inside the target are accepted;
+ * an absolute path or one that normalizes to a `..` escape is rejected so it
+ * can never reach an unlink.
+ */
+export declare function isContainedRelativePath(relativePath: string): boolean;
 /**
  * Reads the manifest of a previous install, if any. Manifests can be written
  * by hand (manual agent installs) or damaged, so every field is sanitized;

package/dist/init.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { isAbsolute, join, normalize, sep } from "node:path";
 import { PACKAGE_VERSION, listTemplateNames, readAgentAsset, readAsset, } from "./assets.js";
 import { HARNESSES } from "./detect.js";
 import { ROLES, assertValidModelId, claudeModelValue, opencodeModelValue, } from "./models.js";
@@ -10,6 +10,18 @@ const MANIFEST_PATH = join(".ai", "workflow", "manifest.json");
 function sha256(content) {
     return createHash("sha256").update(content, "utf8").digest("hex");
 }
+/**
+ * A manifest can be hand-written or tampered with, and uninstall deletes by
+ * these paths. Only relative paths that stay inside the target are accepted;
+ * an absolute path or one that normalizes to a `..` escape is rejected so it
+ * can never reach an unlink.
+ */
+export function isContainedRelativePath(relativePath) {
+    if (relativePath === "" || isAbsolute(relativePath))
+        return false;
+    const normalized = normalize(relativePath);
+    return normalized !== ".." && !normalized.startsWith(`..${sep}`);
+}
 /**
  * Reads the manifest of a previous install, if any. Manifests can be written
  * by hand (manual agent installs) or damaged, so every field is sanitized;
@@ -51,8 +63,11 @@ export function readInstalledManifest(targetDir) {
     const files = {};
     if (typeof candidate.files === "object" && candidate.files !== null) {
         for (const [key, value] of Object.entries(candidate.files)) {
-            if (typeof value === "string")
+            // Drop absolute or directory-escaping keys: uninstall deletes by these
+            // paths, so a tampered key must never enter the record.
+            if (typeof value === "string" && isContainedRelativePath(key)) {
                 files[key] = value;
+            }
         }
     }
     return {

package/dist/uninstall.d.ts

@@ -0,0 +1,14 @@
+export interface UninstallReport {
+    /** Kit files removed (hash matched the install record, or --force). */
+    removed: string[];
+    /** Files left in place: locally edited kit files, damaged fences. */
+    kept: string[];
+    /** Ledger entries whose file was already gone. */
+    missing: string[];
+    /** Human-readable notes (run history kept, fence state, ...). */
+    notes: string[];
+}
+export declare function runUninstall(options: {
+    targetDir: string;
+    force?: boolean;
+}): UninstallReport;

package/dist/uninstall.js

@@ -0,0 +1,150 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, rmdirSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { isContainedRelativePath, readInstalledManifest } from "./init.js";
+import { AGENTS_MD_HEADING, CLAUDE_IMPORT_LINE, CLAUDE_MD_BOILERPLATE, SECTION_BEGIN, SECTION_END, } from "./writers.js";
+function sha256(content) {
+    return createHash("sha256").update(content, "utf8").digest("hex");
+}
+function removeAgentsSection(report, path) {
+    if (!existsSync(path))
+        return;
+    const existing = readFileSync(path, "utf8");
+    const lines = existing.split("\n");
+    const beginLines = [];
+    const endLines = [];
+    lines.forEach((line, index) => {
+        if (line.trim() === SECTION_BEGIN)
+            beginLines.push(index);
+        if (line.trim() === SECTION_END)
+            endLines.push(index);
+    });
+    if (beginLines.length === 0 && endLines.length === 0)
+        return;
+    if (beginLines.length !== 1 ||
+        endLines.length !== 1 ||
+        endLines[0] < beginLines[0]) {
+        report.kept.push(path);
+        report.notes.push(`${path}: marker fence is broken or duplicated; section left in place.`);
+        return;
+    }
+    const remaining = [
+        ...lines.slice(0, beginLines[0]),
+        ...lines.slice(endLines[0] + 1),
+    ]
+        .join("\n")
+        .trim();
+    if (remaining === "" || remaining === AGENTS_MD_HEADING) {
+        // Nothing but what init itself created remains; remove the file.
+        unlinkSync(path);
+        report.removed.push(path);
+        return;
+    }
+    writeFileSync(path, `${remaining}\n`, "utf8");
+    report.removed.push(`${path} (workflow section)`);
+}
+function removeClaudeImport(report, path) {
+    if (!existsSync(path))
+        return;
+    const existing = readFileSync(path, "utf8");
+    if (existing === CLAUDE_MD_BOILERPLATE) {
+        unlinkSync(path);
+        report.removed.push(path);
+        return;
+    }
+    const lines = existing.split("\n");
+    const without = lines.filter((line) => line.trim() !== CLAUDE_IMPORT_LINE);
+    if (without.length === lines.length)
+        return;
+    const remaining = without.join("\n").trimEnd();
+    if (remaining === "") {
+        unlinkSync(path);
+        report.removed.push(path);
+        return;
+    }
+    writeFileSync(path, `${remaining}\n`, "utf8");
+    report.removed.push(`${path} (@AGENTS.md import line)`);
+}
+/**
+ * Directories init may have created, deepest first. Each is removed only
+ * when empty, so directories shared with user content always survive.
+ */
+const PRUNE_CANDIDATES = [
+    join(".ai", "workflow", "templates"),
+    join(".ai", "workflow"),
+    join(".ai", "runs"),
+    ".ai",
+    join(".claude", "skills", "orchestrator-workflow"),
+    join(".claude", "skills"),
+    join(".claude", "agents"),
+    ".claude",
+    join(".agents", "skills", "orchestrator-workflow"),
+    join(".agents", "skills"),
+    ".agents",
+    join(".opencode", "agents"),
+    ".opencode",
+];
+export function runUninstall(options) {
+    const { targetDir } = options;
+    const force = options.force ?? false;
+    const manifest = readInstalledManifest(targetDir);
+    if (!manifest) {
+        throw new Error(`No orchestrator-workflow install found in ${targetDir} (missing or unreadable .ai/workflow/manifest.json)`);
+    }
+    const report = {
+        removed: [],
+        kept: [],
+        missing: [],
+        notes: [],
+    };
+    for (const [relativePath, recordedHash] of Object.entries(manifest.files)) {
+        // Defense in depth: readInstalledManifest already drops escaping keys,
+        // but never unlink a path that is absolute, escapes the target, or is a
+        // directory rather than a kit file.
+        if (!isContainedRelativePath(relativePath)) {
+            report.kept.push(relativePath);
+            report.notes.push(`${relativePath}: manifest path is outside the target; ignored.`);
+            continue;
+        }
+        const path = join(targetDir, relativePath);
+        if (!existsSync(path)) {
+            report.missing.push(path);
+            continue;
+        }
+        if (!statSync(path).isFile()) {
+            report.kept.push(path);
+            report.notes.push(`${path}: not a regular file; ignored.`);
+            continue;
+        }
+        const content = readFileSync(path, "utf8");
+        if (force || sha256(content) === recordedHash) {
+            unlinkSync(path);
+            report.removed.push(path);
+        }
+        else {
+            report.kept.push(path);
+            report.notes.push(`${path}: locally edited since install; re-run with --force to remove.`);
+        }
+    }
+    removeAgentsSection(report, join(targetDir, "AGENTS.md"));
+    removeClaudeImport(report, join(targetDir, "CLAUDE.md"));
+    const manifestPath = join(targetDir, ".ai", "workflow", "manifest.json");
+    if (existsSync(manifestPath)) {
+        unlinkSync(manifestPath);
+        report.removed.push(manifestPath);
+    }
+    for (const candidate of PRUNE_CANDIDATES) {
+        const path = join(targetDir, candidate);
+        try {
+            rmdirSync(path);
+        }
+        catch {
+            // Not empty or not present; either way it stays.
+        }
+    }
+    const runsDir = join(targetDir, ".ai", "runs");
+    if (existsSync(runsDir)) {
+        report.notes.push(`${runsDir}: run history kept; remove manually if no longer needed.`);
+    }
+    return report;
+}

package/dist/writers.d.ts

@@ -18,6 +18,8 @@ export declare function installFile(report: Report, path: string, content: strin
 }): void;
 export declare const SECTION_BEGIN = "<!-- orchestrator-workflow:begin -->";
 export declare const SECTION_END = "<!-- orchestrator-workflow:end -->";
+/** Heading used when init creates AGENTS.md itself. */
+export declare const AGENTS_MD_HEADING = "# Agent instructions";
 /**
  * Creates AGENTS.md or replaces exactly the marker-fenced workflow section in
  * it. Content outside the markers is never touched. Markers only count when
@@ -26,6 +28,9 @@ export declare const SECTION_END = "<!-- orchestrator-workflow:end -->";
  */
 export declare function upsertMarkerSection(report: Report, path: string, section: string): void;
 export declare const CLAUDE_IMPORT_LINE = "@AGENTS.md";
+/** The exact CLAUDE.md that init creates from scratch; uninstall relies on
+ * recognizing this byte-identically before removing the whole file. */
+export declare const CLAUDE_MD_BOILERPLATE = "# CLAUDE.md\n\nProject agent instructions live in AGENTS.md.\n\n@AGENTS.md\n";
 /**
  * Claude Code reads CLAUDE.md, not AGENTS.md. Ensure CLAUDE.md exists and
  * imports AGENTS.md so the policy section is loaded there too.

package/dist/writers.js

@@ -31,6 +31,8 @@ export function installFile(report, path, content, options) {
 }
 export const SECTION_BEGIN = "<!-- orchestrator-workflow:begin -->";
 export const SECTION_END = "<!-- orchestrator-workflow:end -->";
+/** Heading used when init creates AGENTS.md itself. */
+export const AGENTS_MD_HEADING = "# Agent instructions";
 /**
  * Creates AGENTS.md or replaces exactly the marker-fenced workflow section in
  * it. Content outside the markers is never touched. Markers only count when
@@ -40,7 +42,7 @@ export const SECTION_END = "<!-- orchestrator-workflow:end -->";
 export function upsertMarkerSection(report, path, section) {
     const block = section.trimEnd();
     if (!existsSync(path)) {
-        write(path, `# Agent instructions\n\n${block}\n`);
+        write(path, `${AGENTS_MD_HEADING}\n\n${block}\n`);
         report.written.push(path);
         return;
     }
@@ -80,13 +82,16 @@ export function upsertMarkerSection(report, path, section) {
     report.updated.push(path);
 }
 export const CLAUDE_IMPORT_LINE = "@AGENTS.md";
+/** The exact CLAUDE.md that init creates from scratch; uninstall relies on
+ * recognizing this byte-identically before removing the whole file. */
+export const CLAUDE_MD_BOILERPLATE = `# CLAUDE.md\n\nProject agent instructions live in AGENTS.md.\n\n${CLAUDE_IMPORT_LINE}\n`;
 /**
  * Claude Code reads CLAUDE.md, not AGENTS.md. Ensure CLAUDE.md exists and
  * imports AGENTS.md so the policy section is loaded there too.
  */
 export function ensureClaudeImport(report, path) {
     if (!existsSync(path)) {
-        write(path, `# CLAUDE.md\n\nProject agent instructions live in AGENTS.md.\n\n${CLAUDE_IMPORT_LINE}\n`);
+        write(path, CLAUDE_MD_BOILERPLATE);
         report.written.push(path);
         return;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orchestrator-workflow",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Installer for an orchestrator-led agent workflow: .ai/ run state, an AGENTS.md policy section, and per-harness subagent definitions for Claude Code, OpenAI Codex, and opencode",
   "main": "dist/index.js",
   "type": "module",