@punk6529/playbook 0.0.0 → 0.1.0

package/README.md

@@ -1,5 +1,68 @@
 # @punk6529/playbook
 
-Placeholder release to reserve the package name.
+CLI for initializing and updating Playbook workflow assets.
 
-The real implementation will be published in a later version.
+## Install
+
+```bash
+npm install -g @punk6529/playbook
+```
+
+Or run without global install:
+
+```bash
+npx @punk6529/playbook --help
+```
+
+## Commands
+
+```bash
+playbook init [path] [--tools all|none|codex,claude] [--force]
+playbook global init [--force]
+playbook update [path] [--tools all|none|codex,claude] [--force]
+```
+
+## Scope Boundaries
+
+- `playbook init` is project-scoped:
+  - creates `docs/playbook/{cases,patterns,checklists}` and `docs/playbook/INDEX.json`
+  - writes managed skill templates based on `--tools`:
+    - Codex: `.codex/skills/{playbook-query,playbook-case}/SKILL.md`
+    - Claude: `.claude/skills/{playbook-query,playbook-case}/SKILL.md`
+- `playbook global init` is global-scoped:
+  - creates `~/.playbook/repo/{cases,patterns,checklists}`
+  - creates `~/.playbook/repo/INDEX.json` and `~/.playbook/repo/tags.yml`
+  - does not support `--tools`
+- `playbook update` is project-scoped:
+  - updates only managed project templates
+  - does not modify user business content (for example case markdown files)
+- V1 does not include `playbook global update`
+
+## Skill Delivery
+
+- This release installs namespaced skills for supported tools (`codex`, `claude`):
+  - `playbook-query`
+  - `playbook-case`
+- CLI responsibility is asset delivery only (`init`/`update`). Runtime skill execution is handled by the host AI tool.
+
+## Conflict Policy
+
+- `playbook init` and `playbook global init` are non-destructive by default:
+  - conflicting managed files are skipped and reported as `conflict`
+- `playbook update` uses split behavior:
+  - managed skill templates are refreshed by default when content differs
+  - `docs/playbook/INDEX.json` remains conflict-safe unless `--force` is provided
+- Use `--force` to explicitly overwrite conflicting protected managed files.
+
+## Error Handling
+
+- Unknown command or invalid option fails with actionable guidance.
+- Managed file read/write failures include source path and reason.
+
+## Packaging Notes
+
+Before publish, verify exact package contents:
+
+```bash
+npm pack --dry-run
+```

package/bin/playbook.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+const { runCli } = require("../src/cli");
+
+async function main() {
+  const exitCode = await runCli(process.argv.slice(2), process);
+  process.exitCode = exitCode;
+}
+
+main().catch((error) => {
+  process.stderr.write(`Unexpected error: ${error.message}\n`);
+  process.exitCode = 1;
+});

package/package.json

@@ -1,18 +1,26 @@
 {
   "name": "@punk6529/playbook",
-  "version": "0.0.0",
-  "main": "index.js",
+  "version": "0.1.0",
+  "description": "CLI for initializing and updating Playbook & Case workflows.",
+  "main": "src/index.js",
+  "bin": {
+    "playbook": "bin/playbook.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node --test"
   },
-  "keywords": [],
+  "keywords": ["playbook", "knowledge-base", "cli", "ai-skills", "case-management"],
   "author": "",
   "license": "MIT",
-  "description": "Placeholder package. Real implementation coming soon.",
   "publishConfig": {
     "access": "public"
   },
   "files": [
-    "index.js"
+    "bin",
+    "src",
+    "templates"
   ]
 }

package/src/cli.js

@@ -0,0 +1,129 @@
+const { CliError } = require("./errors");
+const { parseProjectCommandArgs, parseGlobalInitArgs } = require("./options");
+const { initProject } = require("./commands/init-project");
+const { initGlobal } = require("./commands/global-init");
+const { updateProject } = require("./commands/update-project");
+const { printSummary } = require("./reporting");
+
+function usageText() {
+  return [
+    "Usage:",
+    "  playbook init [path] [--tools all|none|codex,claude] [--force]",
+    "  playbook global init [--force]",
+    "  playbook update [path] [--tools all|none|codex,claude] [--force]",
+    "",
+    "Notes:",
+    "  - `init` and `update` are project-scoped commands.",
+    "  - `global init` initializes ~/.playbook/repo and does not support --tools.",
+    "  - V1 does not support `playbook global update`.",
+  ].join("\n");
+}
+
+function writeStdout(io, line) {
+  io.stdout.write(`${line}\n`);
+}
+
+function writeStderr(io, line) {
+  io.stderr.write(`${line}\n`);
+}
+
+function ensureNoHelpRequest(options, io) {
+  if (options.help) {
+    writeStdout(io, usageText());
+    return true;
+  }
+
+  return false;
+}
+
+function runInit(args, io) {
+  const options = parseProjectCommandArgs(args, "playbook init");
+  if (ensureNoHelpRequest(options, io)) {
+    return 0;
+  }
+
+  const result = initProject(options);
+  printSummary("playbook init completed", result.projectRoot, result.results, (line) =>
+    writeStdout(io, line)
+  );
+  return 0;
+}
+
+function runUpdate(args, io) {
+  const options = parseProjectCommandArgs(args, "playbook update");
+  if (ensureNoHelpRequest(options, io)) {
+    return 0;
+  }
+
+  const result = updateProject(options);
+  printSummary("playbook update completed", result.projectRoot, result.results, (line) =>
+    writeStdout(io, line)
+  );
+  return 0;
+}
+
+function runGlobal(args, io) {
+  const subcommand = args[0];
+  if (!subcommand) {
+    throw new CliError("Missing subcommand for `playbook global`. Supported: init");
+  }
+
+  if (subcommand === "update") {
+    throw new CliError(
+      "Unsupported command: `playbook global update` (V1). Use `playbook global init` or `playbook update`."
+    );
+  }
+
+  if (subcommand !== "init") {
+    throw new CliError(`Unknown command: playbook global ${subcommand}`);
+  }
+
+  const options = parseGlobalInitArgs(args.slice(1));
+  if (ensureNoHelpRequest(options, io)) {
+    return 0;
+  }
+
+  const result = initGlobal(options);
+  printSummary("playbook global init completed", result.globalRoot, result.results, (line) =>
+    writeStdout(io, line)
+  );
+  writeStdout(io, "Next: run `playbook init` inside a project to scaffold project assets.");
+  return 0;
+}
+
+async function runCli(argv, io = process) {
+  try {
+    if (argv.length === 0 || argv[0] === "-h" || argv[0] === "--help") {
+      writeStdout(io, usageText());
+      return 0;
+    }
+
+    const command = argv[0];
+    if (command === "init") {
+      return runInit(argv.slice(1), io);
+    }
+
+    if (command === "update") {
+      return runUpdate(argv.slice(1), io);
+    }
+
+    if (command === "global") {
+      return runGlobal(argv.slice(1), io);
+    }
+
+    throw new CliError(`Unknown command: ${command}. Supported: init, global, update`);
+  } catch (error) {
+    if (error instanceof CliError) {
+      writeStderr(io, `Error: ${error.message}`);
+      return error.exitCode;
+    }
+
+    writeStderr(io, `Unexpected error: ${error.message}`);
+    return 1;
+  }
+}
+
+module.exports = {
+  runCli,
+  usageText,
+};

package/src/commands/global-init.js

@@ -0,0 +1,31 @@
+const path = require("path");
+const { resolveGlobalRoot } = require("../core/context");
+const { GLOBAL_SKELETON_DIRS, GLOBAL_MANAGED_FILES } = require("../manifest");
+const { readTemplate } = require("../template-store");
+const { ensureDirectory, writeManagedFile } = require("../file-ops");
+
+function initGlobal(options) {
+  const globalRoot = resolveGlobalRoot();
+  const results = [];
+
+  for (const relativeDirectory of GLOBAL_SKELETON_DIRS) {
+    const directoryPath = path.join(globalRoot, relativeDirectory);
+    results.push(ensureDirectory(directoryPath));
+  }
+
+  for (const managedFile of GLOBAL_MANAGED_FILES) {
+    const targetPath = path.join(globalRoot, managedFile.relativePath);
+    const content = readTemplate(managedFile.templatePath);
+    results.push(writeManagedFile(targetPath, content, options.force));
+  }
+
+  return {
+    globalRoot,
+    results,
+  };
+}
+
+module.exports = {
+  initGlobal,
+  resolveGlobalRoot,
+};

package/src/commands/init-project.js

@@ -0,0 +1,30 @@
+const path = require("path");
+const { PROJECT_SKELETON_DIRS, getProjectManagedFiles } = require("../manifest");
+const { readTemplate } = require("../template-store");
+const { ensureDirectory, writeManagedFile } = require("../file-ops");
+
+function initProject(options) {
+  const projectRoot = path.resolve(options.targetPath);
+  const results = [];
+
+  for (const relativeDirectory of PROJECT_SKELETON_DIRS) {
+    const directoryPath = path.join(projectRoot, relativeDirectory);
+    results.push(ensureDirectory(directoryPath));
+  }
+
+  const managedFiles = getProjectManagedFiles(options.tools);
+  for (const managedFile of managedFiles) {
+    const targetPath = path.join(projectRoot, managedFile.relativePath);
+    const content = readTemplate(managedFile.templatePath);
+    results.push(writeManagedFile(targetPath, content, options.force));
+  }
+
+  return {
+    projectRoot,
+    results,
+  };
+}
+
+module.exports = {
+  initProject,
+};

package/src/commands/update-project.js

@@ -0,0 +1,30 @@
+const path = require("path");
+const { getProjectManagedFiles } = require("../manifest");
+const { readTemplate } = require("../template-store");
+const { writeManagedFile } = require("../file-ops");
+
+function updateProject(options) {
+  const projectRoot = path.resolve(options.targetPath);
+  const results = [];
+
+  const managedFiles = getProjectManagedFiles(options.tools);
+  for (const managedFile of managedFiles) {
+    const targetPath = path.join(projectRoot, managedFile.relativePath);
+    const content = readTemplate(managedFile.templatePath);
+    const defaultOverwrite = managedFile.overwriteOnUpdate === true;
+    const effectiveForce = options.force || defaultOverwrite;
+    const overwriteReason = !options.force && defaultOverwrite
+      ? "overwritten by default managed skill refresh"
+      : undefined;
+    results.push(writeManagedFile(targetPath, content, effectiveForce, overwriteReason));
+  }
+
+  return {
+    projectRoot,
+    results,
+  };
+}
+
+module.exports = {
+  updateProject,
+};

package/src/constants.js

@@ -0,0 +1,5 @@
+const SUPPORTED_TOOLS = ["codex", "claude"];
+
+module.exports = {
+  SUPPORTED_TOOLS,
+};

package/src/core/context.js

@@ -0,0 +1,24 @@
+const os = require("os");
+const path = require("path");
+const { CliError } = require("../errors");
+
+function resolveGlobalRoot() {
+  const home = os.homedir();
+  if (!home) {
+    throw new CliError("Cannot resolve home directory for global playbook path");
+  }
+
+  return path.join(home, ".playbook", "repo");
+}
+
+function resolveRuntimeContext(projectRoot = ".") {
+  return {
+    projectRoot: path.resolve(projectRoot),
+    globalRoot: resolveGlobalRoot(),
+  };
+}
+
+module.exports = {
+  resolveRuntimeContext,
+  resolveGlobalRoot,
+};

package/src/errors.js

@@ -0,0 +1,11 @@
+class CliError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+  }
+}
+
+module.exports = {
+  CliError,
+};

package/src/file-ops.js

@@ -0,0 +1,91 @@
+const fs = require("fs");
+const path = require("path");
+const { CliError } = require("./errors");
+
+function withFsError(action, targetPath, error) {
+  throw new CliError(`Failed to ${action} '${targetPath}': ${error.code || error.message}`);
+}
+
+function ensureDirectory(directoryPath) {
+  const existed = fs.existsSync(directoryPath);
+
+  if (existed) {
+    return {
+      action: "skipped",
+      path: directoryPath,
+      reason: "directory already exists",
+      type: "directory",
+    };
+  }
+
+  try {
+    fs.mkdirSync(directoryPath, { recursive: true });
+    return {
+      action: "added",
+      path: directoryPath,
+      reason: "directory created",
+      type: "directory",
+    };
+  } catch (error) {
+    withFsError("create directory", directoryPath, error);
+  }
+}
+
+function writeManagedFile(targetPath, content, force, overwriteReason) {
+  try {
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  } catch (error) {
+    withFsError("prepare parent directory for", targetPath, error);
+  }
+
+  let exists = false;
+  let currentContent = "";
+
+  try {
+    exists = fs.existsSync(targetPath);
+    if (exists) {
+      currentContent = fs.readFileSync(targetPath, "utf8");
+    }
+  } catch (error) {
+    withFsError("read file", targetPath, error);
+  }
+
+  if (!exists) {
+    try {
+      fs.writeFileSync(targetPath, content, "utf8");
+      return { action: "added", path: targetPath, reason: "file created", type: "file" };
+    } catch (error) {
+      withFsError("write file", targetPath, error);
+    }
+  }
+
+  if (currentContent === content) {
+    return { action: "skipped", path: targetPath, reason: "unchanged", type: "file" };
+  }
+
+  if (!force) {
+    return {
+      action: "conflict",
+      path: targetPath,
+      reason: "content differs (rerun with --force to overwrite)",
+      type: "file",
+    };
+  }
+
+  try {
+    fs.writeFileSync(targetPath, content, "utf8");
+    return {
+      action: "updated",
+      path: targetPath,
+      reason: overwriteReason || "overwritten by --force",
+      type: "file",
+    };
+  } catch (error) {
+    withFsError("overwrite file", targetPath, error);
+  }
+}
+
+module.exports = {
+  ensureDirectory,
+  writeManagedFile,
+};

package/src/index.js

@@ -0,0 +1,5 @@
+const { runCli } = require("./cli");
+
+module.exports = {
+  runCli,
+};

package/src/manifest.js

@@ -0,0 +1,73 @@
+const PROJECT_SKELETON_DIRS = [
+  "docs/playbook/cases",
+  "docs/playbook/patterns",
+  "docs/playbook/checklists",
+];
+
+const PROJECT_MANAGED_FILES = [
+  {
+    relativePath: "docs/playbook/INDEX.json",
+    templatePath: "project/docs/playbook/INDEX.json",
+  },
+  {
+    relativePath: "docs/playbook/cases/_example-001-delete-me.md",
+    templatePath: "project/docs/playbook/cases/_example-001-delete-me.md",
+  },
+  {
+    relativePath: "docs/playbook/patterns/_example-001-delete-me.md",
+    templatePath: "project/docs/playbook/patterns/_example-001-delete-me.md",
+  },
+  {
+    relativePath: "docs/playbook/checklists/_example-001-delete-me.md",
+    templatePath: "project/docs/playbook/checklists/_example-001-delete-me.md",
+  },
+  {
+    relativePath: ".codex/skills/playbook-query/SKILL.md",
+    templatePath: "project/skills/playbook-query/SKILL.md",
+    tool: "codex",
+    overwriteOnUpdate: true,
+  },
+  {
+    relativePath: ".codex/skills/playbook-case/SKILL.md",
+    templatePath: "project/skills/playbook-case/SKILL.md",
+    tool: "codex",
+    overwriteOnUpdate: true,
+  },
+  {
+    relativePath: ".claude/skills/playbook-query/SKILL.md",
+    templatePath: "project/skills/playbook-query/SKILL.md",
+    tool: "claude",
+    overwriteOnUpdate: true,
+  },
+  {
+    relativePath: ".claude/skills/playbook-case/SKILL.md",
+    templatePath: "project/skills/playbook-case/SKILL.md",
+    tool: "claude",
+    overwriteOnUpdate: true,
+  },
+];
+
+const GLOBAL_SKELETON_DIRS = ["cases", "patterns", "checklists"];
+
+const GLOBAL_MANAGED_FILES = [
+  {
+    relativePath: "INDEX.json",
+    templatePath: "global/INDEX.json",
+  },
+  {
+    relativePath: "tags.yml",
+    templatePath: "global/tags.yml",
+  },
+];
+
+function getProjectManagedFiles(tools) {
+  return PROJECT_MANAGED_FILES.filter((file) => !file.tool || tools.includes(file.tool));
+}
+
+module.exports = {
+  PROJECT_SKELETON_DIRS,
+  PROJECT_MANAGED_FILES,
+  GLOBAL_SKELETON_DIRS,
+  GLOBAL_MANAGED_FILES,
+  getProjectManagedFiles,
+};

package/src/options.js

@@ -0,0 +1,113 @@
+const { CliError } = require("./errors");
+const { SUPPORTED_TOOLS } = require("./constants");
+
+function parseToolsValue(rawValue) {
+  if (!rawValue) {
+    throw new CliError("Missing value for --tools");
+  }
+
+  const normalized = rawValue.trim().toLowerCase();
+  if (normalized === "all") {
+    return SUPPORTED_TOOLS.slice();
+  }
+
+  if (normalized === "none") {
+    return [];
+  }
+
+  const values = normalized
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+
+  if (values.length === 0) {
+    throw new CliError("Invalid --tools value. Use all, none, or codex,claude");
+  }
+
+  const invalid = values.filter((value) => !SUPPORTED_TOOLS.includes(value));
+  if (invalid.length > 0) {
+    throw new CliError(
+      `Unsupported tool(s): ${invalid.join(", ")}. Supported: ${SUPPORTED_TOOLS.join(", ")}`
+    );
+  }
+
+  return SUPPORTED_TOOLS.filter((tool) => values.includes(tool));
+}
+
+function parseProjectCommandArgs(args, commandName) {
+  let force = false;
+  let tools = SUPPORTED_TOOLS.slice();
+  const positionals = [];
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+
+    if (arg === "--force") {
+      force = true;
+      continue;
+    }
+
+    if (arg === "--tools") {
+      const next = args[i + 1];
+      tools = parseToolsValue(next);
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--tools=")) {
+      const value = arg.slice("--tools=".length);
+      tools = parseToolsValue(value);
+      continue;
+    }
+
+    if (arg === "-h" || arg === "--help") {
+      return { help: true };
+    }
+
+    if (arg.startsWith("-")) {
+      throw new CliError(`Unknown option for ${commandName}: ${arg}`);
+    }
+
+    positionals.push(arg);
+  }
+
+  if (positionals.length > 1) {
+    throw new CliError(`Too many path arguments for ${commandName}`);
+  }
+
+  return {
+    help: false,
+    force,
+    tools,
+    targetPath: positionals[0] || ".",
+  };
+}
+
+function parseGlobalInitArgs(args) {
+  let force = false;
+
+  for (const arg of args) {
+    if (arg === "--force") {
+      force = true;
+      continue;
+    }
+
+    if (arg === "-h" || arg === "--help") {
+      return { help: true };
+    }
+
+    if (arg === "--tools" || arg.startsWith("--tools=")) {
+      throw new CliError("`playbook global init` does not support --tools");
+    }
+
+    throw new CliError(`Unknown option for playbook global init: ${arg}`);
+  }
+
+  return { help: false, force };
+}
+
+module.exports = {
+  parseProjectCommandArgs,
+  parseGlobalInitArgs,
+  parseToolsValue,
+};

package/src/reporting.js

@@ -0,0 +1,42 @@
+const path = require("path");
+
+function formatPath(basePath, absolutePath) {
+  const relative = path.relative(basePath, absolutePath);
+  return relative || ".";
+}
+
+function countByAction(results) {
+  const counters = {
+    added: 0,
+    updated: 0,
+    skipped: 0,
+    conflict: 0,
+  };
+
+  for (const result of results) {
+    if (Object.prototype.hasOwnProperty.call(counters, result.action)) {
+      counters[result.action] += 1;
+    }
+  }
+
+  return counters;
+}
+
+function printSummary(title, basePath, results, writeLine) {
+  writeLine(`\n${title}`);
+
+  for (const result of results) {
+    const displayPath = formatPath(basePath, result.path);
+    const reasonSuffix = result.reason ? ` (${result.reason})` : "";
+    writeLine(`- [${result.action}] ${displayPath}${reasonSuffix}`);
+  }
+
+  const counts = countByAction(results);
+  writeLine(
+    `Summary: added=${counts.added}, updated=${counts.updated}, skipped=${counts.skipped}, conflict=${counts.conflict}`
+  );
+}
+
+module.exports = {
+  printSummary,
+};

package/src/template-store.js

@@ -0,0 +1,22 @@
+const fs = require("fs");
+const path = require("path");
+const { CliError } = require("./errors");
+
+const TEMPLATE_ROOT = path.resolve(__dirname, "..", "templates");
+
+function readTemplate(templatePath) {
+  const absolutePath = path.join(TEMPLATE_ROOT, templatePath);
+
+  try {
+    return fs.readFileSync(absolutePath, "utf8");
+  } catch (error) {
+    throw new CliError(
+      `Failed to read template '${templatePath}': ${error.code || error.message}`
+    );
+  }
+}
+
+module.exports = {
+  TEMPLATE_ROOT,
+  readTemplate,
+};

package/templates/global/INDEX.json

@@ -0,0 +1,9 @@
+{
+  "_example-001-delete-me": {
+    "type": "case",
+    "title": "Example entry — delete this and add real entries via playbook-case skill",
+    "tags": ["workflow"],
+    "path": "cases/_example-001-delete-me.md",
+    "created": "2026-01-01"
+  }
+}

package/templates/global/tags.yml

@@ -0,0 +1,34 @@
+tags:
+  - id: auth
+    desc: Authentication and authorization issues.
+    aliases: [login, oauth, permission]
+  - id: web
+    desc: Frontend and browser behavior.
+    aliases: [frontend, browser, ui]
+  - id: db
+    desc: Database schema, query, and migration issues.
+    aliases: [database, sql, migration]
+  - id: env
+    desc: Environment variables and local setup problems.
+    aliases: [environment, dotenv, config]
+  - id: proxy
+    desc: Networking, proxy, and request forwarding issues.
+    aliases: [gateway, reverse-proxy, tunnel]
+  - id: ci
+    desc: Continuous integration and pipeline failures.
+    aliases: [pipeline, github-actions, build]
+  - id: ios
+    desc: iOS build, signing, and simulator issues.
+    aliases: [xcode, swift, mobile]
+  - id: testing
+    desc: Test failures, flaky tests, and test infra.
+    aliases: [test, qa, flaky]
+  - id: workflow
+    desc: Engineering process and development workflow issues.
+    aliases: [process, collaboration, handoff]
+  - id: api
+    desc: API contract, integration, and compatibility issues.
+    aliases: [endpoint, contract, integration]
+  - id: cli
+    desc: Command-line interface behavior and ergonomics.
+    aliases: [command, terminal, shell]

package/templates/project/docs/playbook/INDEX.json

@@ -0,0 +1,23 @@
+{
+  "case-001-example-node-version-mismatch": {
+    "type": "case",
+    "title": "Deployment failed due to Node.js version mismatch",
+    "tags": ["env", "ci"],
+    "path": "cases/_example-001-delete-me.md",
+    "created": "2026-01-01"
+  },
+  "pattern-001-example-pin-runtime-versions": {
+    "type": "pattern",
+    "title": "Pin runtime versions before upgrading dependencies",
+    "tags": ["env", "workflow"],
+    "path": "patterns/_example-001-delete-me.md",
+    "created": "2026-01-01"
+  },
+  "checklist-001-example-pre-publish": {
+    "type": "checklist",
+    "title": "Pre-publish checklist",
+    "tags": ["workflow", "ci"],
+    "path": "checklists/_example-001-delete-me.md",
+    "created": "2026-01-01"
+  }
+}

package/templates/project/docs/playbook/cases/_example-001-delete-me.md

@@ -0,0 +1,24 @@
+# Deployment failed due to Node.js version mismatch
+
+> Delete this example file and create real cases using the playbook-case skill.
+
+## Problem
+
+Production deployment failed silently. The build succeeded locally but crashed on startup in CI with `SyntaxError: Unexpected token ??=`.
+
+## Context
+
+- Local dev environment: Node 20
+- CI runner: Node 16 (inherited from base image, not pinned)
+- The `??=` operator (logical nullish assignment) requires Node 15+
+- No `engines` field in package.json to catch this earlier
+
+## Solution
+
+1. Added `"engines": { "node": ">=20" }` to package.json
+2. Updated CI base image to `node:20-slim`
+3. Added `engine-strict=true` to `.npmrc` so mismatches fail fast on `npm install`
+
+## Takeaway
+
+Always pin the Node.js version in `engines` and enforce it. Silent version mismatches cause the worst kind of debugging — everything works locally.

package/templates/project/docs/playbook/checklists/_example-001-delete-me.md

@@ -0,0 +1,10 @@
+# Pre-publish checklist
+
+> Delete this example file and create real checklists using the playbook-case skill.
+
+- [ ] Run `npm pack --dry-run` and verify included files
+- [ ] Check `files` field in package.json matches intended contents
+- [ ] Verify version number is correct and not already published
+- [ ] Run full test suite: `npm test`
+- [ ] Check for accidentally included secrets or credentials
+- [ ] Confirm README is up to date with current API/usage

package/templates/project/docs/playbook/patterns/_example-001-delete-me.md

@@ -0,0 +1,15 @@
+# Pin runtime versions before upgrading dependencies
+
+> Delete this example file and create real patterns using the playbook-case skill.
+
+## When to Use
+
+Apply this pattern whenever you upgrade a major runtime (Node.js, Python, Ruby) or a core dependency that has runtime version requirements.
+
+## Pattern
+
+1. **Pin the current version first** — add `engines` field (Node), `python_requires` (Python), or equivalent before making any changes
+2. **Upgrade in CI first** — update the CI base image/config before changing local dev setup
+3. **Run full test suite against new version** — don't rely on local smoke tests
+4. **Update lockfile** — regenerate `package-lock.json` / `yarn.lock` under the new runtime
+5. **Communicate** — update README and onboarding docs with new version requirement

package/templates/project/skills/playbook-case/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: playbook-case
+description: Draft and inspect playbook case entries with explicit scope and tags.
+license: MIT
+---
+
+Use this skill when the user asks to create, review, or inspect case entries.
+
+## Behavior
+
+- Keep scope explicit (`project` or `global`).
+- Keep draft generation non-destructive by default.
+- For new cases, enforce this guided flow:
+  1. If the user has not provided a concrete problem statement, ask first:
+     "你想把之前遇到的哪个问题沉淀为 case？请一句话描述。"
+  2. After problem statement is available, suggest tags from registry/index context first:
+     - Prefer project index: `docs/playbook/INDEX.json`
+     - Use global index only when relevant: `~/.playbook/repo/INDEX.json`
+     - Ask user to choose existing tags or explicitly confirm a new tag
+  3. If scope is not confirmed, ask for scope confirmation:
+     - default is `project`
+     - use `global` only when user explicitly confirms
+  4. Only after required inputs are complete, produce the draft package.
+- Required inputs before any draft output:
+  - problem statement
+  - tag decision (existing tags or confirmed new tag)
+  - scope confirmation
+- Hard gate: while any required input is missing, do not output case ID, suggested path, markdown draft, or INDEX update suggestion.
+- For new cases, once inputs are complete, produce a complete draft package:
+  - case ID (format: `{type}-{NNN}-{slug}`, e.g. `case-001-oauth-token-race`)
+  - suggested path (e.g. `cases/case-001-oauth-token-race.md`)
+  - markdown draft
+  - INDEX.json update: the exact JSON entry to add
+
+## INDEX.json Schema
+
+INDEX.json is a flat object keyed by entry ID. Each entry has this structure:
+
+```json
+{
+  "case-001-oauth-token-race": {
+    "type": "case",
+    "title": "OAuth token refresh race condition under concurrency",
+    "tags": ["auth", "api"],
+    "path": "cases/case-001-oauth-token-race.md",
+    "created": "2026-02-10"
+  }
+}
+```
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `"case"` \| `"pattern"` \| `"checklist"` | Entry classification |
+| `title` | string | Human-readable one-line summary |
+| `tags` | string[] | Tag IDs from registry (`tags.yml` or INDEX context) |
+| `path` | string | Relative path to the content file |
+| `created` | string | Creation date in YYYY-MM-DD format |
+
+### Entry ID Convention
+
+Format: `{type}-{NNN}-{slug}`
+- `type`: one of `case`, `pattern`, `checklist`
+- `NNN`: zero-padded 3-digit sequence number (check existing entries to determine next number)
+- `slug`: lowercase hyphenated descriptor derived from the title
+
+### Draft Package Output
+
+When producing the draft package, output the INDEX entry as a ready-to-merge JSON snippet:
+
+```
+**Entry ID:** case-001-oauth-token-race
+**Path:** cases/case-001-oauth-token-race.md
+**INDEX update:**
+Add this entry to INDEX.json:
+{
+  "case-001-oauth-token-race": {
+    "type": "case",
+    "title": "...",
+    "tags": ["..."],
+    "path": "cases/case-001-oauth-token-race.md",
+    "created": "YYYY-MM-DD"
+  }
+}
+```

package/templates/project/skills/playbook-query/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: playbook-query
+description: Query project and global playbook knowledge in a concise, index-first way.
+license: MIT
+---
+
+Use this skill when the user asks to search, filter, or inspect playbook knowledge.
+
+## Behavior
+
+### Lookup Sequence
+
+**IMPORTANT: Only read the specific files listed below by their exact path. Do NOT use broad file search, glob, or grep across the filesystem — this can trigger macOS privacy prompts.**
+
+1. **Project first**: Read `docs/playbook/INDEX.json` (relative to project root)
+2. **Global fallback**: If no matches found, or user asks for broader results, read `~/.playbook/repo/INDEX.json` (this exact path only)
+3. Merge results if both scopes have relevant entries. Label scope in output.
+
+### Matching
+
+- Parse INDEX.json: each key is an entry ID, each value has `type`, `title`, `tags`, `path`, `created`
+- Match user query against:
+  - `tags` array (primary match — compare with tag IDs and aliases from `tags.yml`)
+  - `title` text (secondary match — keyword overlap)
+  - `type` filter (if user specifies "show me patterns" or "any checklists for...")
+- If no matches found in either scope, say so clearly
+
+### Progressive Disclosure
+
+Return results in order of increasing detail and token cost:
+
+1. **Checklists first** — actionable, cheapest to show. Display inline if short.
+2. **Patterns next** — show title + tags summary. Offer to expand.
+3. **Cases last** — show title + tags summary only. Expand full content only when user explicitly asks.
+
+For each match, show:
+```
+[{type}] {title}  (tags: {tags})  [{scope}]
+```
+
+### Expanding Entries
+
+- When user asks to see details, read the content file at the entry's `path` (relative to `docs/playbook/` for project, `~/.playbook/repo/` for global)
+- Show the full markdown content of the referenced file
+
+### Edge Cases
+
+- If INDEX.json is empty (`{}`), tell the user: "No entries yet. Use playbook-case to create your first entry."
+- If a referenced file at `path` doesn't exist, report it as a broken reference
+- If user query is vague, show all entries grouped by type

package/index.js

@@ -1 +0,0 @@
-module.exports = {};