@cairnkeep/cli 2.14.0 → 2.15.0

package/scripts/playbook-instructions.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+import { randomBytes } from "node:crypto";
+import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const TEMPLATE = join(ROOT, "templates", "playbook-agent-instructions.md.template");
+const START = "<!-- cairnkeep:playbook:v1:start -->";
+const END = "<!-- cairnkeep:playbook:v1:end -->";
+const MAX_BYTES = 1024 * 1024;
+
+function safeRead(path) {
+  const info = lstatSync(path);
+  if (!info.isFile() || info.isSymbolicLink() || info.size > MAX_BYTES) throw new Error("AGENTS.md is not a safe bounded regular file.");
+  let descriptor;
+  try {
+    descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    const opened = fstatSync(descriptor);
+    if (!opened.isFile() || opened.dev !== info.dev || opened.ino !== info.ino || opened.size > MAX_BYTES) throw new Error("AGENTS.md changed during validation.");
+    return { text: readFileSync(descriptor, "utf8"), mode: info.mode & 0o777 };
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor);
+  }
+}
+
+function count(text, marker) {
+  return text.split(marker).length - 1;
+}
+
+function render(current, block) {
+  const starts = count(current, START);
+  const ends = count(current, END);
+  if (starts === 0 && ends === 0) return `${current.trimEnd()}${current.trim() ? "\n\n" : ""}${block.trim()}\n`;
+  if (starts !== 1 || ends !== 1) throw new Error("AGENTS.md contains malformed or duplicate Cairnkeep playbook markers.");
+  const start = current.indexOf(START);
+  const end = current.indexOf(END, start);
+  if (end < start) throw new Error("AGENTS.md contains reversed Cairnkeep playbook markers.");
+  return `${current.slice(0, start)}${block.trim()}${current.slice(end + END.length)}`.replace(/\s*$/, "\n");
+}
+
+function removeBlock(current) {
+  const starts = count(current, START);
+  const ends = count(current, END);
+  if (starts === 0 && ends === 0) return current;
+  if (starts !== 1 || ends !== 1) throw new Error("AGENTS.md contains malformed or duplicate Cairnkeep playbook markers.");
+  const start = current.indexOf(START);
+  const end = current.indexOf(END, start);
+  if (end < start) throw new Error("AGENTS.md contains reversed Cairnkeep playbook markers.");
+  return `${current.slice(0, start)}${current.slice(end + END.length)}`.replace(/\n{3,}/g, "\n\n").trimEnd();
+}
+
+function atomicWrite(path, text, mode) {
+  const temporary = join(dirname(path), `.AGENTS.md.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+  try {
+    writeFileSync(temporary, text, { encoding: "utf8", mode, flag: "wx" });
+    renameSync(temporary, path);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+}
+
+export function reconcilePlaybookInstructions(projectRoot = process.cwd(), options = {}) {
+  const root = resolve(projectRoot);
+  const path = join(root, "AGENTS.md");
+  if (dirname(path) !== root) throw new Error("AGENTS.md path escapes the project root.");
+  const block = readFileSync(TEMPLATE, "utf8");
+  const existing = existsSync(path) ? safeRead(path) : { text: "", mode: 0o644 };
+  const desired = render(existing.text, block);
+  const status = !existsSync(path) ? "created" : desired === existing.text ? "unchanged" : "updated";
+  if (!options.check && status !== "unchanged") atomicWrite(path, desired, existing.mode || 0o644);
+  return Object.freeze({ schema_version: 1, path, status: options.check && status !== "unchanged" ? `would-${status}` : status });
+}
+
+export function removePlaybookInstructions(projectRoot = process.cwd(), options = {}) {
+  const root = resolve(projectRoot);
+  const path = join(root, "AGENTS.md");
+  if (!existsSync(path)) return Object.freeze({ schema_version: 1, path, status: "unchanged" });
+  const existing = safeRead(path);
+  const desired = removeBlock(existing.text);
+  const status = desired === existing.text ? "unchanged" : "removed";
+  if (!options.check && status === "removed") {
+    if (desired.trim()) atomicWrite(path, `${desired}\n`, existing.mode || 0o644);
+    else rmSync(path);
+  }
+  return Object.freeze({ schema_version: 1, path, status: options.check && status === "removed" ? "would-remove" : status });
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const check = args.includes("--check");
+  const remove = args.includes("--remove");
+  const json = args.includes("--json");
+  const values = args.filter((arg) => !["--check", "--remove", "--json"].includes(arg));
+  if (values.length > 1) throw new Error("Usage: playbook-instructions.mjs [PROJECT] [--check] [--json]");
+  const value = remove
+    ? removePlaybookInstructions(values[0] ?? process.cwd(), { check })
+    : reconcilePlaybookInstructions(values[0] ?? process.cwd(), { check });
+  process.stdout.write(`${json ? JSON.stringify(value) : `${value.status}: ${value.path}`}\n`);
+  if (check && value.status !== "unchanged") process.exitCode = 1;
+}
+
+if (process.argv[1] && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) {
+  main().catch((error) => {
+    process.stderr.write(`cairn playbook instructions: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 2;
+  });
+}

package/scripts/setup-core.mjs

@@ -16,6 +16,7 @@ const COMMON_ASSETS = Object.freeze([
   ["env.example.template", ".ai/env.example", 0o644],
   ["trajectory-redaction.json.template", ".ai/trajectory-redaction.json", 0o644],
   ["capabilities.json.template", ".ai/capabilities.json", 0o600],
+  ["playbooks.json.template", ".ai/playbooks.json", 0o600],
   ["agentfs-gitignore.template", ".agentfs/.gitignore", 0o644],
   ["planning-config.json.template", ".planning/config.json", 0o644],
   ["project-brief.md.template", ".planning/PROJECT-BRIEF.md", 0o644],

package/scripts/setup.mjs

@@ -22,6 +22,7 @@ import {
 } from "./setup-core.mjs";
 import { reconcileSetupPlan } from "./setup-reconcile.mjs";
 import { HARNESS_IDS, machineSyncCommand, requiredHarnessAssetPaths } from "./harness-registry.mjs";
+import { reconcilePlaybookInstructions } from "./playbook-instructions.mjs";
 
 const HARNESSES = HARNESS_IDS;
 const GIT_MODES = Object.freeze(["init", "existing", "none"]);
@@ -33,6 +34,7 @@ const COMMON_SETUP_ASSETS = Object.freeze([
   ".ai/env.example",
   ".ai/trajectory-redaction.json",
   ".ai/capabilities.json",
+  ".ai/playbooks.json",
   ".agentfs/.gitignore",
   ".planning/config.json",
   ".planning/PROJECT-BRIEF.md",
@@ -186,6 +188,11 @@ async function executeSetup(args, options) {
   });
   let plan = buildSetupPlan({ target, preflight, choices });
   if (options.augmentPlan) plan = await options.augmentPlan(plan);
+  try {
+    reconcilePlaybookInstructions(plan.target, { check: true });
+  } catch (error) {
+    throw operational("unsafe-instructions", `Project AGENTS.md cannot be reconciled safely: ${error instanceof Error ? error.message : String(error)}`);
+  }
 
   if (interactive && !parsed.confirmed) {
     renderPlan(plan, options.output);
@@ -200,6 +207,7 @@ async function executeSetup(args, options) {
   createTarget(plan.target);
   if (plan.git === "init") initializeGit(plan.target);
   const reconciliation = await reconcileSetupPlan(plan);
+  reconcilePlaybookInstructions(plan.target);
   return resultFor(plan, reconciliation, options.platform);
 }
 

package/scripts/sync-kimi-assets.sh

@@ -5,7 +5,7 @@ usage() {
   cat <<'EOF'
 Usage: sync-kimi-assets.sh [--check|--apply] [--live-root PATH]
 
-Compare or sync Cairnkeep's thin graph Skill against the live Kimi Code tree.
+Compare or sync Cairnkeep's thin managed Skills against the live Kimi Code tree.
 
 Options:
   --check            Verify managed live assets match the repo copies (default)
@@ -19,7 +19,7 @@ ROOT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
 SOURCE_ROOT="$ROOT_DIR/kimi"
 LIVE_ROOT="${KIMI_CODE_HOME:-$HOME/.kimi-code}"
 MODE="check"
-ASSETS=("skills/graphify/SKILL.md")
+ASSETS=("skills/graphify/SKILL.md" "skills/cairn-work/SKILL.md")
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -74,4 +74,4 @@ if [[ "$MODE" == "apply" ]]; then
 fi
 
 check_assets
-printf 'Kimi graph Skill is in sync under %s\n' "$LIVE_ROOT"
+printf 'Kimi managed Skills are in sync under %s\n' "$LIVE_ROOT"

package/scripts/sync-opencode-memory-assets.sh

@@ -16,7 +16,7 @@ Options:
 
 Notes:
   - The repo-managed source of truth lives under ./opencode/
-  - This script manages the memory-sync / memory-review / code-review commands,
+  - This script manages the memory-sync / memory-review / code-review / cairn-work commands,
     the code-reviewer agent, and the memory-review workflow. The memory-wakeup
     plugin is handled by sync-opencode-plugin-assets.sh.
 EOF
@@ -33,6 +33,7 @@ ASSETS=(
   "command/code-review.md"
   "command/remember.md"
   "command/recall.md"
+  "command/cairn-work.md"
   "agents/code-reviewer.md"
   "workflows/memory-review-workflow.md"
 )

package/scripts/sync-pi-assets.sh

@@ -24,6 +24,7 @@ ASSETS=(
   "extensions/cairnkeep-memory.ts"
   "extensions/cairnkeep-trajectory.ts"
   "prompts/graphify.md"
+  "prompts/cairn-work.md"
 )
 
 while [[ $# -gt 0 ]]; do
@@ -105,4 +106,4 @@ if ! check_assets; then
   echo "Recovery: sync-pi-assets.sh --apply --live-root PATH" >&2
   exit 1
 fi
-printf 'Pi extension and graph prompt are in sync under %s\n' "$LIVE_ROOT"
+printf 'Pi extensions and managed prompts are in sync under %s\n' "$LIVE_ROOT"

package/scripts/test-cli-dispatch.sh

@@ -16,6 +16,7 @@ tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
 "$cairn" help | grep -q "cairn notes" || fail "help missing notes"
 "$cairn" help | grep -q "cairn artifact <list|show|delete|prune>" || fail "help missing artifact"
 "$cairn" help | grep -q "cairn evidence <list|show|delete|prune|doctor>" || fail "help missing evidence"
+"$cairn" help | grep -q "cairn playbook <list|status|init|set|enable|disable|reset|check|record|receipts|instructions|doctor>" || fail "help missing playbook"
 "$cairn" help | grep -q "cairn capabilities <list|status|enable|disable|reset|logging>" || fail "help missing capabilities"
 "$cairn" help | grep -q "cairn mcp-tools <list|status|set|reset>" || fail "help missing mcp-tools"
 "$cairn" help | grep -q "cairn pack <init|lock|validate|install|list|show|remove|enable|disable|update|skills|approve-skill|revoke-skill>" || fail "help missing pack"
@@ -26,6 +27,7 @@ tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
 env -u CAIRN_NOTE_DISTILLATION "$cairn" notes --help >/dev/null 2>&1 || fail "cairn notes dispatch"
 "$cairn" artifact --help | grep -q "cairn artifact list" || fail "cairn artifact dispatch"
 "$cairn" evidence --help | grep -q "cairn evidence list" || fail "cairn evidence dispatch"
+"$cairn" playbook --help | grep -q "cairn playbook list" || fail "cairn playbook dispatch"
 "$cairn" capabilities --help >"$tmp/capabilities-help" 2>/dev/null || fail "cairn capabilities dispatch"
 "$cairn" mcp-tools list --json >"$tmp/mcp-tools.json" || fail "cairn mcp-tools dispatch"
 CAIRN_PACK_BASE_DIR="$tmp/pack-store" "$cairn" pack list --json >"$tmp/packs.json" || fail "cairn pack dispatch"

package/scripts/test-completion.sh

@@ -22,7 +22,7 @@ for shell in bash zsh fish; do
   for capability_id in $capability_ids; do
     grep -qF "$capability_id" "$tmp/$shell"
   done
-  if grep -Eq '(^|[[:space:]"'"'"'])(guard|start|finish)([[:space:]"'"'"']|$)' "$tmp/$shell"; then
+  if grep -Eq '(^|[[:space:]"'"'"'])guard([[:space:]"'"'"']|$)' "$tmp/$shell"; then
     echo "completion exposed a private capability operation for $shell" >&2
     exit 1
   fi
@@ -34,7 +34,7 @@ for shell in bash zsh fish; do
   for capability_id in $capability_ids; do
     grep -qF "$capability_id" "$tmp/$shell"
   done
-  if grep -Eq '(^|[[:space:]"'"'"'])(doctor-diagnosis|guard|start|finish)([[:space:]"'"'"']|$)' "$tmp/$shell"; then
+  if grep -Eq '(^|[[:space:]"'"'"'])(doctor-diagnosis|guard)([[:space:]"'"'"']|$)' "$tmp/$shell"; then
     echo "completion exposed a private eval lifecycle operation for $shell" >&2
     exit 1
   fi
@@ -51,6 +51,14 @@ for shell in bash zsh fish; do
   grep -q 'evidence' "$tmp/$shell"
   grep -q 'list.*show.*delete.*prune.*doctor\|list show delete prune doctor' "$tmp/$shell"
   grep -q -- '--status\|-l status' "$tmp/$shell"
+  grep -q 'playbook' "$tmp/$shell"
+  grep -q 'list.*status.*init.*set.*enable.*disable.*reset.*check.*record.*receipts.*instructions.*doctor\|list status init set enable disable reset check record receipts instructions doctor' "$tmp/$shell"
+  for playbook_value in minimal balanced strict context.recall verify.tests review.security learning.capture; do
+    grep -qF "$playbook_value" "$tmp/$shell"
+  done
+  for playbook_flag in --project --json --enforce --changed --complexity --familiarity --risk --public-change --completed --skipped --failed; do
+    grep -q -- "$playbook_flag\|-l ${playbook_flag#--}" "$tmp/$shell"
+  done
 done
 
 "$ROOT/bin/cairn" help >"$tmp/root-help"
@@ -68,6 +76,7 @@ if grep -q 'doctor-diagnosis' "$tmp/eval-help"; then
 fi
 grep -qF 'cairn skill <harvest|list|show|review|propose|evaluate|apply|rollback>' "$tmp/root-help"
 grep -qF 'cairn evidence <list|show|delete|prune|doctor>' "$tmp/root-help"
+grep -qF 'cairn playbook <list|status|init|set|enable|disable|reset|check|record|receipts|instructions|doctor>' "$tmp/root-help"
 node "$ROOT/mcp-memory-server/dist/skill-cli.js" --help >"$tmp/skill-help"
 for command in $skill_commands; do
   grep -q "cairn skill $command" "$tmp/skill-help"

package/scripts/test-graph-harness-adapters.sh

@@ -9,9 +9,13 @@ fail() { echo "FAIL: $1" >&2; exit 1; }
 
 PI_SOURCE="$ROOT/pi/prompts/graphify.md"
 KIMI_SOURCE="$ROOT/kimi/skills/graphify/SKILL.md"
+PI_PLAYBOOK_SOURCE="$ROOT/pi/prompts/cairn-work.md"
+KIMI_PLAYBOOK_SOURCE="$ROOT/kimi/skills/cairn-work/SKILL.md"
 
 [[ -f "$PI_SOURCE" ]] || fail "Pi /graphify prompt source is missing"
 [[ -f "$KIMI_SOURCE" ]] || fail "Kimi graphify skill source is missing"
+[[ -f "$PI_PLAYBOOK_SOURCE" ]] || fail "Pi cairn-work prompt source is missing"
+[[ -f "$KIMI_PLAYBOOK_SOURCE" ]] || fail "Kimi cairn-work Skill source is missing"
 
 for adapter in "$PI_SOURCE" "$KIMI_SOURCE"; do
   grep -qF 'cairn graph' "$adapter" || fail "adapter does not delegate to cairn graph: $adapter"
@@ -31,16 +35,18 @@ PI_LIVE="$tmp/pi"
 "$ROOT/scripts/sync-pi-assets.sh" --apply --live-root "$PI_LIVE" >"$tmp/pi-first"
 [[ -f "$PI_LIVE/extensions/cairnkeep-trajectory.ts" ]] || fail "Pi sync omitted trajectory extension"
 cmp -s "$PI_SOURCE" "$PI_LIVE/prompts/graphify.md" || fail "Pi sync changed graphify prompt bytes"
+cmp -s "$PI_PLAYBOOK_SOURCE" "$PI_LIVE/prompts/cairn-work.md" || fail "Pi sync changed cairn-work prompt bytes"
 "$ROOT/scripts/sync-pi-assets.sh" --apply --live-root "$PI_LIVE" >"$tmp/pi-second"
-grep -qF 'Applied 0 Pi asset(s); 2 already matched.' "$tmp/pi-second" || fail "Pi sync is not idempotent"
+grep -qF 'Applied 0 Pi asset(s); 3 already matched.' "$tmp/pi-second" || fail "Pi sync is not idempotent"
 
 KIMI_LIVE="$tmp/kimi"
 "$ROOT/scripts/sync-kimi-assets.sh" --apply --live-root "$KIMI_LIVE" >"$tmp/kimi-first"
 cmp -s "$KIMI_SOURCE" "$KIMI_LIVE/skills/graphify/SKILL.md" || fail "Kimi sync changed graphify skill bytes"
+cmp -s "$KIMI_PLAYBOOK_SOURCE" "$KIMI_LIVE/skills/cairn-work/SKILL.md" || fail "Kimi sync changed cairn-work Skill bytes"
 "$ROOT/scripts/sync-kimi-assets.sh" --apply --live-root "$KIMI_LIVE" >"$tmp/kimi-second"
-grep -qF 'Applied 0 Kimi asset(s); 1 already matched.' "$tmp/kimi-second" || fail "Kimi sync is not idempotent"
+grep -qF 'Applied 0 Kimi asset(s); 2 already matched.' "$tmp/kimi-second" || fail "Kimi sync is not idempotent"
 
 "$ROOT/bin/cairn" help | grep -qF 'cairn sync-kimi' || fail "CLI help omits sync-kimi"
 "$ROOT/bin/cairn" sync-kimi --help >/dev/null || fail "CLI does not dispatch sync-kimi"
 
-echo "PASS: thin Pi and Kimi graph adapters delegate only to cairn graph"
+echo "PASS: thin Pi and Kimi graph/playbook adapters are bounded and idempotent"

package/scripts/test-harness-registry.sh

@@ -13,6 +13,17 @@ import { spawnSync } from "node:child_process";
 import { pathToFileURL } from "node:url";
 
 const [root, sandbox] = process.argv.slice(2);
+for (const path of [
+  "claude/commands/cairn-work.md",
+  "opencode/command/cairn-work.md",
+  "pi/prompts/cairn-work.md",
+  "kimi/skills/cairn-work/SKILL.md",
+]) {
+  const content = readFileSync(join(root, path), "utf8");
+  assert.match(content, /cairn playbook check/);
+  assert.match(content, /must/);
+  assert.match(content, /approval/);
+}
 const registry = await import(pathToFileURL(join(root, "scripts", "harness-registry.mjs")).href);
 assert.deepEqual(registry.HARNESS_IDS, ["claude", "opencode", "pi", "kimi", "qwen", "codex"]);
 assert.equal(new Set(registry.HARNESS_IDS).size, registry.HARNESS_IDS.length);

package/scripts/test-learning-docs.sh

@@ -22,7 +22,7 @@ done
 
 ready=0
 brief=0
-for number in $(seq -w 0 24); do
+for number in $(seq -w 0 25); do
   matches=(docs/learning/lessons/L"$number"-*.md)
   [[ ${#matches[@]} -eq 1 && -f ${matches[0]} ]] || {
     echo "learning path must contain exactly one L$number lesson" >&2
@@ -53,7 +53,7 @@ grep -qF '`cairn sync-kimi --apply`' "$graph_lesson"
 grep -qF '`cairn sync-pi --apply`' "$graph_lesson"
 grep -qF '`graphify-out/`' "$graph_lesson"
 
-[[ $ready -eq 10 && $brief -eq 15 ]] || {
+[[ $ready -eq 11 && $brief -eq 15 ]] || {
   echo "unexpected learning status totals: ready=$ready brief=$brief" >&2
   exit 1
 }
@@ -143,4 +143,25 @@ grep -Eqi 'cancel|shutdown|child process' "$l23"
 grep -Eqi '0\.84\.1' "$l23"
 grep -Eqi 'credentials|secrets|private state' "$l23"
 
+l25=docs/learning/lessons/L25-playbooks.md
+video25=docs/learning/video-scripts/V25-playbooks.md
+for file in "$l25" "$video25"; do
+  [[ -f "$file" ]]
+done
+for phrase in \
+  'cairn playbook check start' \
+  'cairn playbook check finish' \
+  '--enforce' \
+  'cairn playbook record' \
+  'unauthenticated' \
+  'does not run'; do
+  grep -qF -- "$phrase" "$l25" || {
+    echo "L25 missing playbook teaching boundary: $phrase" >&2
+    exit 1
+  }
+done
+grep -qF 'course-13-playbooks' "$coverage"
+grep -qF 'L25-playbooks.md' docs/learning/tracks/practitioner.md
+grep -qF 'L25-playbooks.md' docs/learning/tracks/operator.md
+
 echo "PASS: public learning path structure, readiness, links, and version alignment"

package/scripts/test-package-install.sh

@@ -48,6 +48,8 @@ bootstrap_output=$(cairn bootstrap "$tmp/project")
 [[ -x "$tmp/project/.ai/start-qwen.sh" ]] || fail "bootstrap did not install an executable Qwen launcher"
 [[ -x "$tmp/project/.ai/start-codex.sh" ]] || fail "bootstrap did not install an executable Codex launcher"
 [[ -f "$tmp/project/.planning/config.json" ]] || fail "bootstrap did not install the planning scaffold"
+[[ -f "$tmp/project/.ai/playbooks.json" ]] || fail "bootstrap did not install the playbook policy"
+grep -qF '<!-- cairnkeep:playbook:v1:start -->' "$tmp/project/AGENTS.md" || fail "bootstrap did not install playbook agent guidance"
 
 (cd "$tmp/project" && cairn doctor) >/dev/null || fail "installed package failed cairn doctor"
 env -u CAIRN_NOTE_DISTILLATION cairn notes --help >/dev/null \
@@ -104,6 +106,30 @@ CAIRN_PACK_BASE_DIR="$tmp/installed-packs" cairn pack list --json >"$tmp/install
 cairn mcp-tools list --json >"$tmp/installed-mcp-tools.json" || \
   fail "installed package mcp-tools CLI failed"
 
+for required in \
+  schemas/playbook.schema.json \
+  templates/playbooks.json.template \
+  templates/playbook-agent-instructions.md.template \
+  scripts/playbook-instructions.mjs \
+  mcp-memory-server/dist/playbook-schema.js \
+  mcp-memory-server/dist/playbook.js \
+  mcp-memory-server/dist/playbook-receipt.js \
+  mcp-memory-server/dist/playbook-cli.js \
+  claude/commands/cairn-work.md \
+  opencode/command/cairn-work.md \
+  pi/prompts/cairn-work.md \
+  kimi/skills/cairn-work/SKILL.md \
+  docs/design/team-mode.md \
+  docs/learning/lessons/L25-playbooks.md \
+  docs/learning/video-scripts/V25-playbooks.md
+do
+  [[ -f "$installed_root/$required" ]] || fail "npm tarball omitted $required"
+done
+cairn playbook status --project "$tmp/project" --json >"$tmp/installed-playbook-status.json" || \
+  fail "installed package playbook status failed"
+cairn playbook check start --project "$tmp/project" --session installed-playbook --json >"$tmp/installed-playbook-check.json" || \
+  fail "installed package playbook check failed"
+
 for required in \
   schemas/skill-adapter.schema.json \
   schemas/skill-proposal-protocol.schema.json \

package/scripts/test-playbook-instructions.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+project="$tmp/project"
+mkdir -p "$project"
+printf '# User rules\n\nKeep this line.\n' >"$project/AGENTS.md"
+chmod 0640 "$project/AGENTS.md"
+
+node "$ROOT/scripts/playbook-instructions.mjs" "$project" >/dev/null
+grep -qF 'Keep this line.' "$project/AGENTS.md"
+[[ $(grep -cF '<!-- cairnkeep:playbook:v1:start -->' "$project/AGENTS.md") -eq 1 ]]
+[[ $(stat -c '%a' "$project/AGENTS.md") == 640 ]]
+before=$(sha256sum "$project/AGENTS.md" | cut -d' ' -f1)
+node "$ROOT/scripts/playbook-instructions.mjs" "$project" >/dev/null
+after=$(sha256sum "$project/AGENTS.md" | cut -d' ' -f1)
+[[ "$before" == "$after" ]]
+"$ROOT/bin/cairn" playbook instructions check --project "$project" --json >/dev/null
+
+node "$ROOT/scripts/playbook-instructions.mjs" "$project" --remove >/dev/null
+grep -qF 'Keep this line.' "$project/AGENTS.md"
+! grep -qF 'cairnkeep:playbook' "$project/AGENTS.md"
+
+printf '%s\n%s\n%s\n' \
+  '<!-- cairnkeep:playbook:v1:start -->' \
+  '<!-- cairnkeep:playbook:v1:start -->' \
+  '<!-- cairnkeep:playbook:v1:end -->' >"$project/AGENTS.md"
+if node "$ROOT/scripts/playbook-instructions.mjs" "$project" >/dev/null 2>&1; then
+  echo 'duplicate managed markers were accepted' >&2
+  exit 1
+fi
+
+rm "$project/AGENTS.md"
+printf 'neighbor\n' >"$tmp/neighbor"
+ln -s "$tmp/neighbor" "$project/AGENTS.md"
+if node "$ROOT/scripts/playbook-instructions.mjs" "$project" >/dev/null 2>&1; then
+  echo 'symlink AGENTS.md was accepted' >&2
+  exit 1
+fi
+[[ $(cat "$tmp/neighbor") == neighbor ]]
+
+for command in bootstrap setup; do
+  unsafe="$tmp/unsafe-$command"
+  mkdir -p "$unsafe"
+  printf '%s\n%s\n' '<!-- cairnkeep:playbook:v1:start -->' '<!-- cairnkeep:playbook:v1:start -->' >"$unsafe/AGENTS.md"
+  if [[ "$command" == bootstrap ]]; then
+    if "$ROOT/bin/cairn" bootstrap "$unsafe" >/dev/null 2>&1; then
+      echo 'bootstrap accepted malformed managed markers' >&2
+      exit 1
+    fi
+  elif "$ROOT/bin/cairn" setup "$unsafe" --git init --harness codex --memory local --yes >/dev/null 2>&1; then
+    echo 'setup accepted malformed managed markers' >&2
+    exit 1
+  fi
+  [[ ! -e "$unsafe/.ai" ]]
+done
+
+echo 'PASS: ownership-safe playbook AGENTS.md reconciliation'

package/scripts/test-windows-native.mjs

@@ -28,6 +28,7 @@ try {
   process.env.USERPROFILE = sandbox;
   const project = join(sandbox, "Project with spaces – Unicode");
   mkdirSync(project, { recursive: true });
+  writeFileSync(join(project, "AGENTS.md"), "# User rules\n\nKeep this line.\n");
   bootstrapWindows(root, [project]);
   for (const harness of HARNESS_IDS) {
     assert.ok(existsSync(join(project, ".ai", `start-${harness}.cmd`)), `${harness} cmd launcher`);
@@ -38,6 +39,8 @@ try {
   assert.match(launcherPowerShell(), /post-exit\.ps1/);
   assert.match(launcherPowerShell(), /evidence run --harness/);
   assert.match(launcherPowerShell(), /CAIRN_WORK_EVIDENCE/);
+  assert.match(readFileSync(join(project, "AGENTS.md"), "utf8"), /cairnkeep:playbook:v1:start/);
+  assert.match(readFileSync(join(project, "AGENTS.md"), "utf8"), /Keep this line\./);
 
   const claudeRoot = join(sandbox, "Claude Config");
   await runWindowsCommand({ command: "sync", args: ["--apply", "--live-root", claudeRoot], root });
@@ -59,6 +62,9 @@ try {
   assert.equal(readFileSync(join(memory, "project.db"), "utf8"), "sqlite-a");
   assert.match(powershellCompletion(), /Register-ArgumentCompleter/);
   assert.match(powershellCompletion(), /evidence/);
+  assert.match(powershellCompletion(), /playbook/);
+  assert.match(powershellCompletion(), /review\.security/);
+  assert.match(powershellCompletion(), /--enforce/);
 
   let containerArgs = [];
   runNativeContainer(["stdio", "--image", "example/windows:1", "--volume", "windows-data"], root, (_engine, args) => { containerArgs = args; });
@@ -68,6 +74,7 @@ try {
 
   await runWindowsCommand({ command: "uninstall", args: ["--yes", "--live-root", claudeRoot, project], root });
   assert.ok(!existsSync(join(project, ".ai", "start-claude.cmd")));
+  assert.equal(readFileSync(join(project, "AGENTS.md"), "utf8"), "# User rules\n\nKeep this line.\n");
   assert.ok(!existsSync(join(claudeRoot, "commands", "remember.md")));
   const cleanedSettings = JSON.parse(readFileSync(join(claudeRoot, "settings.json"), "utf8"));
   assert.ok(!JSON.stringify(cleanedSettings).includes("memory-wakeup"));

package/scripts/uninstall.sh

@@ -49,6 +49,7 @@ PROJECT_AI_FILES=(
   env.example
   trajectory-redaction.json
   capabilities.json
+  playbooks.json
 )
 
 usage() {
@@ -150,7 +151,7 @@ if (!exact(state, ["schema_version", "cairnkeep_version", "git", "memory", "harn
     || typeof state.assets !== "object"
     || Array.isArray(state.assets)) process.exit(1);
 const allowed = new Set([
-  ".ai/env.example", ".ai/trajectory-redaction.json", ".ai/capabilities.json",
+  ".ai/env.example", ".ai/trajectory-redaction.json", ".ai/capabilities.json", ".ai/playbooks.json",
   ".agentfs/.gitignore", ".planning/config.json", ".planning/PROJECT-BRIEF.md",
   ".planning/wiki/index.md", ".planning/wiki/policy.md", ".planning/wiki/CONTRADICTIONS.md",
   ".planning/wiki/LOG.md", ".planning/alignment/policy.md", ".planning/alignment/gap-register.yaml",
@@ -213,8 +214,10 @@ echo "Pi adapters:"
 remove_path "$PI_LIVE_ROOT/extensions/cairnkeep-memory.ts"
 remove_path "$PI_LIVE_ROOT/extensions/cairnkeep-trajectory.ts"
 remove_path "$PI_LIVE_ROOT/prompts/graphify.md"
+remove_path "$PI_LIVE_ROOT/prompts/cairn-work.md"
 echo "Kimi adapter:"
 remove_path "$KIMI_LIVE_ROOT/skills/graphify/SKILL.md"
+remove_path "$KIMI_LIVE_ROOT/skills/cairn-work/SKILL.md"
 
 # 2. settings.json hook registrations (back up whole file, then de-register).
 SETTINGS="$LIVE_ROOT/settings.json"
@@ -310,6 +313,18 @@ for proj in "${PROJECTS[@]:-}"; do
   [[ -n "$proj" && -d "$proj" ]] || continue
   proj=$(cd "$proj" && pwd)
   echo "Project scaffold: $proj"
+  if [[ -f "$proj/AGENTS.md" && ! -L "$proj/AGENTS.md" ]] && grep -qF '<!-- cairnkeep:playbook:v1:start -->' "$proj/AGENTS.md" 2>/dev/null; then
+    if [[ $DRY_RUN -eq 1 ]]; then
+      echo "  would remove Cairnkeep playbook block from $proj/AGENTS.md"
+    else
+      back_up "$proj/AGENTS.md"
+      if node "$CAIRN_ROOT/scripts/playbook-instructions.mjs" "$proj" --remove >/dev/null; then
+        echo "  removed Cairnkeep playbook block from $proj/AGENTS.md"
+      else
+        echo "  kept AGENTS.md: playbook markers could not be removed safely"
+      fi
+    fi
+  fi
   # Truthy launchers create this project-local root only for the explicit
   # capability overlay. Back up the complete managed unit so its native Claude
   # hook registrations and OpenCode plugin bytes restore together exactly.

package/scripts/windows-platform.mjs

@@ -21,11 +21,13 @@ import { spawnSync } from "node:child_process";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { homedir, tmpdir } from "node:os";
 import { HARNESS_IDS, harnessProjectAssets } from "./harness-registry.mjs";
+import { reconcilePlaybookInstructions, removePlaybookInstructions } from "./playbook-instructions.mjs";
 
 const BOOTSTRAP_FILES = [
   ["env.example.template", ".ai/env.example"],
   ["trajectory-redaction.json.template", ".ai/trajectory-redaction.json"],
   ["capabilities.json.template", ".ai/capabilities.json"],
+  ["playbooks.json.template", ".ai/playbooks.json"],
   ["agentfs-gitignore.template", ".agentfs/.gitignore"],
   ["planning-config.json.template", ".planning/config.json"],
   ["project-brief.md.template", ".planning/PROJECT-BRIEF.md"],
@@ -257,9 +259,11 @@ export function bootstrapWindows(root, args) {
     prefix = git(["rev-parse", "--show-prefix"], target).replaceAll("\\", "/");
   }
 
+  if (!options.has("--untracked")) reconcilePlaybookInstructions(target, { check: true });
+
   const templates = join(root, "templates");
   for (const [source, destination] of BOOTSTRAP_FILES) {
-    installFile(join(templates, source), join(target, ...destination.split("/")), destination.endsWith("capabilities.json") ? 0o600 : 0o644);
+    installFile(join(templates, source), join(target, ...destination.split("/")), /(?:capabilities|playbooks)\.json$/.test(destination) ? 0o600 : 0o644);
   }
   for (const harness of HARNESSES) {
     const asset = harnessProjectAssets(harness, "local")[0];
@@ -271,6 +275,9 @@ export function bootstrapWindows(root, args) {
   if (!existsSync(modulePath)) atomicWrite(modulePath, launcherModule(), 0o755);
   const powershellPath = join(target, ".ai", "start-harness.ps1");
   if (!existsSync(powershellPath)) atomicWrite(powershellPath, launcherPowerShell(), 0o600);
+  if (!options.has("--untracked")) {
+    reconcilePlaybookInstructions(target);
+  }
 
   if (excludeFile) {
     mkdirSync(dirname(excludeFile), { recursive: true });
@@ -456,6 +463,7 @@ async function doctorWindows(root, args) {
     ["typed memory", "node-cli.js", ["doctor", "--project-root", process.cwd(), ...(repair ? ["--repair"] : [])]],
     ["capability", "capability-cli.js", ["doctor", "--json"]],
     ["context pack", "context-pack-cli.js", ["doctor", "--json"]],
+    ["playbook", "playbook-cli.js", ["doctor", "--json"]],
   ]) {
     const entry = join(root, "mcp-memory-server", "dist", file);
     if (!existsSync(entry)) { line("FAIL", `${label} diagnostics are unavailable`); continue; }
@@ -627,9 +635,11 @@ function uninstallWindows(root, args) {
     join(piLive, "extensions", "cairnkeep-memory.ts"),
     join(piLive, "extensions", "cairnkeep-trajectory.ts"),
     join(piLive, "prompts", "graphify.md"),
+    join(piLive, "prompts", "cairn-work.md"),
   );
   const kimiLive = resolve(expandHome(options.get("--kimi-live-root") || process.env.KIMI_CODE_HOME || join(homedir(), ".kimi-code")));
   targets.push(join(kimiLive, "skills", "graphify", "SKILL.md"));
+  targets.push(join(kimiLive, "skills", "cairn-work", "SKILL.md"));
   for (const project of projects) {
     const base = resolve(project);
     for (const [, rel] of BOOTSTRAP_FILES) targets.push(join(base, ...rel.split("/")));
@@ -677,6 +687,16 @@ function uninstallWindows(root, args) {
       console.log(`updated: ${settingsPath}`);
     }
   }
+  for (const project of projects) {
+    const agents = join(resolve(project), "AGENTS.md");
+    if (!existsSync(agents)) continue;
+    const info = lstatSync(agents);
+    if (!info.isFile() || info.isSymbolicLink()) continue;
+    if (!readFileSync(agents, "utf8").includes("<!-- cairnkeep:playbook:v1:start -->")) continue;
+    backupTarget(agents);
+    removePlaybookInstructions(resolve(project));
+    console.log(`removed Cairnkeep playbook block: ${agents}`);
+  }
   for (const target of existing) {
     backupTarget(target);
     rmSync(target, { recursive: true, force: true });
@@ -708,9 +728,10 @@ export function powershellCompletion() {
   const harnesses = HARNESS_IDS.map((id) => `'${id}'`).join(",");
   return `Register-ArgumentCompleter -Native -CommandName cairn -ScriptBlock {
   param($wordToComplete, $commandAst, $cursorPosition)
-  $commands = 'bootstrap','setup','memory-server','sync','sync-pi','sync-kimi','doctor','trajectory','artifact','evidence','capabilities','mcp-tools','pack','notes','eval','skill','graph','memory','audit-timer','uninstall','completion','version','help'
+  $commands = 'bootstrap','setup','memory-server','sync','sync-pi','sync-kimi','doctor','trajectory','artifact','evidence','playbook','capabilities','mcp-tools','pack','notes','eval','skill','graph','memory','audit-timer','uninstall','completion','version','help'
   $setup = '--git','--harness','--memory','--policy','--yes','--json','init','existing','none',${harnesses},'local'
-  $candidates = if ($commandAst.ToString() -match '^\\s*cairn\\s+setup(?:\\s|$)') { $setup } else { $commands }
+  $playbook = 'list','status','init','set','enable','disable','reset','check','record','receipts','instructions','doctor','minimal','balanced','strict','must','should','may','off','start','finish','install','remove','context.recall','context.explore','work.plan','verify.tests','review.repository','review.security','docs.update','learning.capture','--project','--json','--enforce','--complexity','--familiarity','--risk','--public-change','--changed','--change-type','--completed','--skipped','--failed','--actor','--actor-kind','--session','--policy','--decision','--event','--action','--outcome','--reason'
+  $candidates = if ($commandAst.ToString() -match '^\\s*cairn\\s+setup(?:\\s|$)') { $setup } elseif ($commandAst.ToString() -match '^\\s*cairn\\s+playbook(?:\\s|$)') { $playbook } else { $commands }
   $candidates | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
     [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
   }