@tcanaud/playbook 1.0.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,69 @@
+# @tcanaud/playbook
+
+YAML-driven orchestration for kai feature workflows — autonomous playbook execution with crash recovery, gates, and git-tracked audit journals.
+
+## Installation
+
+```bash
+npx @tcanaud/playbook init
+```
+
+This creates:
+- `.playbooks/` directory with built-in playbooks and template
+- `.claude/commands/playbook.run.md` and `playbook.resume.md` slash commands
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `npx @tcanaud/playbook init [--yes]` | Scaffold `.playbooks/` and install slash commands |
+| `npx @tcanaud/playbook update` | Refresh commands and built-in playbooks |
+| `npx @tcanaud/playbook start {playbook} {feature}` | Create worktree session for parallel execution |
+| `npx @tcanaud/playbook check {file}` | Validate playbook YAML against schema |
+| `npx @tcanaud/playbook help` | Show usage |
+
+## Claude Code Commands
+
+After installation, use these in the Claude Code TUI:
+
+| Command | Description |
+|---------|-------------|
+| `/playbook.run {playbook} {feature}` | Launch supervisor to orchestrate playbook steps |
+| `/playbook.resume` | Auto-detect and resume an interrupted session |
+
+## Built-in Playbooks
+
+| Playbook | Steps | Description |
+|----------|-------|-------------|
+| `auto-feature` | 8 | plan → tasks → agreement → implement → agreement check → QA plan → QA run → PR |
+| `auto-validate` | 2 | QA plan → QA run |
+
+## Custom Playbooks
+
+```bash
+cp .playbooks/playbooks/playbook.tpl.yaml .playbooks/playbooks/my-workflow.yaml
+# Edit the file, then validate:
+npx @tcanaud/playbook check .playbooks/playbooks/my-workflow.yaml
+```
+
+## Parallel Execution
+
+Run two features simultaneously in separate worktrees:
+
+```bash
+npx @tcanaud/playbook start auto-feature 013-another-feature
+# Follow the printed instructions
+```
+
+## Session Files
+
+After a run, session files are in `.playbooks/sessions/{id}/`:
+
+- `session.yaml` — manifest (playbook, feature, status, timestamps)
+- `journal.yaml` — step-by-step execution log (status, decision type, duration, human responses)
+
+These files are git-tracked and appear in PR diffs for auditability.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+import { argv, exit } from "node:process";
+
+const command = argv[2];
+const args = argv.slice(3);
+
+const HELP = `
+playbook — YAML-driven orchestration for kai feature workflows.
+
+Usage:
+  npx @tcanaud/playbook init       Scaffold .playbooks/ directory and install slash commands
+  npx @tcanaud/playbook update     Refresh slash commands and built-in playbooks
+  npx @tcanaud/playbook start      Create a worktree session for parallel execution
+  npx @tcanaud/playbook check      Validate a playbook YAML file against the schema
+  npx @tcanaud/playbook help       Show this help message
+
+Commands:
+  init [--yes]                Skip confirmation prompts
+  update                     Refresh commands without touching sessions or custom playbooks
+  start {playbook} {feature} Create git worktree + session for parallel playbook execution
+  check {file}               Validate playbook YAML against schema
+
+Claude Code commands (after init):
+  /playbook.run {playbook} {feature}   Launch supervisor to orchestrate playbook steps
+  /playbook.resume                     Auto-detect and resume an interrupted session
+`;
+
+switch (command) {
+  case "init": {
+    const { install } = await import("../src/installer.js");
+    await install(args);
+    break;
+  }
+  case "update": {
+    const { update } = await import("../src/updater.js");
+    await update(args);
+    break;
+  }
+  case "start": {
+    const { start } = await import("../src/worktree.js");
+    await start(args);
+    break;
+  }
+  case "check": {
+    const { check } = await import("../src/validator.js");
+    await check(args);
+    break;
+  }
+  case "help":
+  case "--help":
+  case "-h":
+  case undefined:
+    console.log(HELP);
+    break;
+  default:
+    console.error(`Unknown command: ${command}`);
+    console.log(HELP);
+    exit(1);
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@tcanaud/playbook",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "YAML-driven orchestration for kai feature workflows — autonomous playbook execution with crash recovery, gates, and git-tracked audit journals.",
+  "bin": {
+    "playbook": "./bin/cli.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/"
+  ],
+  "keywords": [
+    "kai",
+    "playbook",
+    "orchestration",
+    "supervisor",
+    "workflow",
+    "claude-code"
+  ],
+  "author": "Thibaud Canaud",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tcanaud/playbook.git"
+  }
+}

package/src/detect.js

@@ -0,0 +1,118 @@
+import { existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { execSync } from "node:child_process";
+
+// ── Directory detection ─────────────────────────────────
+
+/**
+ * Checks if `.playbooks/` exists relative to cwd.
+ * @param {string} [cwd] - Directory to check from. Defaults to process.cwd().
+ * @returns {string|null} Absolute path to `.playbooks/` if found, null otherwise.
+ */
+export function detectPlaybooksDir(cwd = process.cwd()) {
+  const dir = resolve(cwd, ".playbooks");
+  return existsSync(dir) ? dir : null;
+}
+
+/**
+ * Checks if `.claude/commands/` exists relative to cwd.
+ * @param {string} [cwd] - Directory to check from. Defaults to process.cwd().
+ * @returns {string|null} Absolute path to `.claude/commands/` if found, null otherwise.
+ */
+export function detectClaudeCommands(cwd = process.cwd()) {
+  const dir = resolve(cwd, join(".claude", "commands"));
+  return existsSync(dir) ? dir : null;
+}
+
+// ── Git state ───────────────────────────────────────────
+
+/**
+ * Returns the absolute path of the git repository root.
+ * @returns {string} Trimmed output of `git rev-parse --show-toplevel`.
+ * @throws {Error} If not in a git repository or git is unavailable.
+ */
+export function getRepoRoot() {
+  try {
+    return execSync("git rev-parse --show-toplevel", {
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+  } catch (err) {
+    throw new Error(
+      `Failed to determine git repository root: ${err.message ?? String(err)}`
+    );
+  }
+}
+
+/**
+ * Determines whether the current directory is a git worktree (not the main working tree).
+ *
+ * Compares `git rev-parse --show-toplevel` with `git rev-parse --git-common-dir`.
+ * In the main working tree, `--git-common-dir` resolves to `{toplevel}/.git`.
+ * In a linked worktree, it resolves to the common `.git` directory of the main tree.
+ *
+ * @returns {boolean} True if current directory is a linked worktree, false otherwise.
+ * @throws {Error} If not in a git repository or git is unavailable.
+ */
+export function isWorktree() {
+  try {
+    const toplevel = execSync("git rev-parse --show-toplevel", {
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+
+    const gitCommonDir = execSync("git rev-parse --git-common-dir", {
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+
+    // In the main working tree, git-common-dir is "{toplevel}/.git" (or ".git" relative).
+    // Resolve both to absolute paths for a reliable comparison.
+    const expectedMainGitDir = join(toplevel, ".git");
+    const resolvedCommonDir = resolve(toplevel, gitCommonDir);
+
+    return resolvedCommonDir !== expectedMainGitDir;
+  } catch (err) {
+    throw new Error(
+      `Failed to determine worktree status: ${err.message ?? String(err)}`
+    );
+  }
+}
+
+/**
+ * Returns the name of the current git branch.
+ * @returns {string} Current branch name (trimmed).
+ * @throws {Error} If not in a git repository, in detached HEAD state, or git is unavailable.
+ */
+export function getCurrentBranch() {
+  try {
+    return execSync("git rev-parse --abbrev-ref HEAD", {
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+  } catch (err) {
+    throw new Error(
+      `Failed to determine current branch: ${err.message ?? String(err)}`
+    );
+  }
+}
+
+/**
+ * Returns true if the working tree has no uncommitted changes (clean state).
+ * Equivalent to checking that `git status --porcelain` produces no output.
+ * @returns {boolean} True if working tree is clean, false if there are uncommitted changes.
+ * @throws {Error} If not in a git repository or git is unavailable.
+ */
+export function isCleanWorkingTree() {
+  try {
+    const output = execSync("git status --porcelain", {
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return output.trim() === "";
+  } catch (err) {
+    throw new Error(
+      `Failed to check working tree status: ${err.message ?? String(err)}`
+    );
+  }
+}

package/src/installer.js

@@ -0,0 +1,142 @@
+import {
+  existsSync,
+  mkdirSync,
+  copyFileSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline";
+import { detectPlaybooksDir, detectClaudeCommands } from "./detect.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES = join(__dirname, "..", "templates");
+
+// ── Helpers ──────────────────────────────────────────────
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+function copyTemplate(src, dest) {
+  ensureDir(dirname(dest));
+  copyFileSync(src, dest);
+}
+
+function ask(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase());
+    });
+  });
+}
+
+// ── install ──────────────────────────────────────────────
+
+export async function install(flags = []) {
+  const projectRoot = process.cwd();
+  const autoYes = flags.includes("--yes");
+
+  console.log("\n  @tcanaud/playbook v1.0.0\n");
+
+  const playbooksDir = join(projectRoot, ".playbooks");
+  const alreadyExists = existsSync(playbooksDir);
+
+  // ── Confirmation prompt ──────────────────────────────
+  if (alreadyExists && !autoYes) {
+    const answer = await ask(
+      "  Playbook system already initialized. Re-install? (y/N) "
+    );
+    if (answer !== "y" && answer !== "yes") {
+      console.log("  Skipping. Use '@tcanaud/playbook update' to refresh commands only.\n");
+      return;
+    }
+  }
+
+  // ── Phase 1/3: Create .playbooks/ directory tree ─────
+  console.log("  [1/3] Creating .playbooks/ directory tree...");
+
+  const dirs = [
+    join(playbooksDir, "playbooks"),
+    join(playbooksDir, "sessions"),
+    join(playbooksDir, "templates"),
+  ];
+
+  for (const dir of dirs) {
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+      const rel = dir.replace(projectRoot + "/", "");
+      console.log(`    created .${rel.startsWith(".") ? "" : "/"}${rel}`);
+    }
+  }
+
+  // ── Phase 2/3: Copy built-in playbook files ──────────
+  console.log("  [2/3] Installing built-in playbooks...");
+
+  const playbookFiles = ["auto-feature.yaml", "auto-validate.yaml"];
+
+  for (const file of playbookFiles) {
+    const src = join(TEMPLATES, "playbooks", file);
+    const dest = join(playbooksDir, "playbooks", file);
+    if (existsSync(src)) {
+      copyTemplate(src, dest);
+      console.log(`    created .playbooks/playbooks/${file}`);
+    }
+  }
+
+  // Copy playbook template file
+  const tplSrc = join(TEMPLATES, "core", "playbook.tpl.yaml");
+  const tplDest = join(playbooksDir, "playbooks", "playbook.tpl.yaml");
+  if (existsSync(tplSrc)) {
+    copyTemplate(tplSrc, tplDest);
+    console.log("    created .playbooks/playbooks/playbook.tpl.yaml");
+  }
+
+  // Generate _index.yaml from template (replace {{TIMESTAMP}})
+  const indexSrc = join(TEMPLATES, "core", "_index.yaml");
+  const indexDest = join(playbooksDir, "_index.yaml");
+  if (existsSync(indexSrc)) {
+    const timestamp = new Date().toISOString();
+    const content = readFileSync(indexSrc, "utf8").replace(
+      /\{\{TIMESTAMP\}\}/g,
+      timestamp
+    );
+    writeFileSync(indexDest, content, "utf8");
+    console.log("    created .playbooks/_index.yaml");
+  }
+
+  // ── Phase 3/3: Install Claude Code commands ──────────
+  console.log("  [3/3] Installing Claude Code commands...");
+
+  const claudeCommandsDir = join(projectRoot, ".claude", "commands");
+  if (!detectClaudeCommands(projectRoot)) {
+    mkdirSync(claudeCommandsDir, { recursive: true });
+    console.log("    created .claude/commands/");
+  }
+
+  const commandFiles = ["playbook.run.md", "playbook.resume.md"];
+
+  for (const file of commandFiles) {
+    const src = join(TEMPLATES, "commands", file);
+    const dest = join(claudeCommandsDir, file);
+    if (existsSync(src)) {
+      copyTemplate(src, dest);
+      console.log(`    created .claude/commands/${file}`);
+    }
+  }
+
+  // ── Done ─────────────────────────────────────────────
+  console.log();
+  console.log("  Done! Playbook system installed.");
+  console.log();
+  console.log("  Next steps:");
+  console.log("    1. Run /playbook.run {playbook} {feature} to start a supervised workflow");
+  console.log("    2. Run /playbook.resume to recover an interrupted session");
+  console.log("    3. Explore .playbooks/playbooks/ to see built-in playbooks");
+  console.log();
+}