pi-skill-playbook 1.0.1 → 1.2.0

package/README.md

@@ -23,6 +23,7 @@ Define ordered skill workflows as YAML playbooks in your project, then drive the
 - **Active run widget** — Displays current step, skill command, completion criteria, and outcome labels below the editor.
 - **Strict YAML validation** — Playbooks are validated on load for structure, transitions, and skill references.
 - **Selection UI** — Playbook, run, and outcome selection use the Pi TUI selector instead of memorized ids.
+- **Record command** — Capture explicit skill usage with `/playbook:record:*` marks and convert the flow into a validated playbook draft.
 - **Local run state** — Run state is stored in `.pi/playbook-runs/` inside the target project, never in git.
 
 ## Install
@@ -67,6 +68,7 @@ pi -e .
 
    ```gitignore
    .pi/playbook-runs/
+   .pi/playbook-records/
    ```
 
 3. **Start a run** from the Pi TUI:
@@ -100,8 +102,22 @@ The widget displays the current step, exact skill command, completion criteria,
 | `/playbook:done` | Complete the current step (auto-advances if single outcome) |
 | `/playbook:choose` | Select an outcome for multi-branch steps |
 | `/playbook:cancel` | Select and confirm an active run cancellation |
+| `/playbook:record:start <id> [--name <name>]` | Start recording an explicit skill flow |
+| `/playbook:record:mark [<skill>]` | Mark explicit skill usage (selection UI when omitted) |
+| `/playbook:record:branch <outcome>` | Record a branch outcome label before the next skill mark |
+| `/playbook:record:stop` | Preview, validate, confirm, and save a recorded playbook draft |
+| `/playbook:record:status` | Show the active recording session |
 
-All commands are argument-free. Use the Pi TUI selection UI to pick playbooks, runs, and outcomes.
+All core run commands are argument-free. Record subcommands use explicit marks and optional args as shown above.
+
+### Record vs import-web
+
+| Command | Source | When to use |
+|---|---|---|
+| `/playbook:record:*` | Your own explicit skill usage during day-to-day work | Grow playbooks from internal flows you already run |
+| `/playbook:import-web` | Web search + URLs (deferred) | Import external workflow articles with Required Source Trace |
+
+Record never scrapes session logs or infers skills automatically. Import-web (when implemented) never replaces recording — it complements it for external sources.
 
 ### Auto advance
 
@@ -117,15 +133,26 @@ PLAYBOOK_OUTCOME: ready-for-prd
 | `suggest` | Marker only suggests `/playbook:done` or `/playbook:choose` |
 | `off` | No prompt injection or completion detection |
 
+## Sample playbooks
+
+| Playbook | File | When to use |
+|---|---|---|
+| Feature Development | `feature-development.yml` | Generic product work with standard `to-prd` / `to-issues` skills. Good default for non-OSS projects. |
+| Pi OSS New Extension Delivery | `pi-oss-new.yml` | Full Pi OSS lane from idea through PR verify and release post. Uses `-for-oss` skills and vault maintenance skills. |
+| Pi OSS Bootstrap Only | `pi-oss-bootstrap-only.yml` | Repo + vault bootstrap, then PRD and issue slicing only. Stops before implementation. |
+| OSS Maintenance Onboarding | `oss-maintenance-onboard.yml` | Add a new OSS target to the Multica maintenance operating model. |
+
+Copy one or more files from `samples/` into `.pi/playbooks/` in the target project. See [`docs/examples.md`](docs/examples.md) for copy-and-start steps.
+
 ## Package contents
 
 ```
 pi-skill-playbook/
 ├── extensions/     Pi extension entry point
 ├── src/            Domain logic: validation, state, rendering, auto-advance
-├── samples/        Example playbooks (feature-development.yml)
+├── samples/        Example playbooks (generic + Pi OSS lane)
 ├── tests/          Node.js test suite
-├── docs/adr/       Architecture decision records
+├── docs/           Examples and architecture decision records
 ├── LICENSE         MIT
 └── README.md
 ```
@@ -155,7 +182,7 @@ steps:
         to: complete        # "complete" ends the run
 ```
 
-See [`samples/feature-development.yml`](samples/feature-development.yml) for a full example.
+See [`samples/feature-development.yml`](samples/feature-development.yml) for a generic example and [`samples/pi-oss-new.yml`](samples/pi-oss-new.yml) for the Pi OSS delivery lane.
 
 ## Development
 
@@ -189,6 +216,7 @@ Manual dispatch is also available from the Actions tab.
 - [npm package](https://www.npmjs.com/package/pi-skill-playbook)
 - [GitHub repository](https://github.com/eiei114/pi-skill-playbook)
 - [Pi coding agent](https://github.com/earendil-works/pi-coding-agent)
+- [Roadmap](ROADMAP.md)
 - [Architecture decisions](docs/adr/)
 
 ## License

package/docs/examples.md

@@ -1,11 +1,45 @@
 # Examples
 
-## Selection-first TUI flow
+## Copy a sample into your project
 
-Copy or create YAML playbooks in the target project under `.pi/playbooks/`, then use argument-free commands from the Pi TUI:
+Package samples ship under `samples/`. Copy the playbook that matches your lane into the target project's `.pi/playbooks/` folder:
+
+```bash
+mkdir -p .pi/playbooks
+
+# Generic feature development
+cp node_modules/pi-skill-playbook/samples/feature-development.yml .pi/playbooks/
+
+# Pi OSS delivery lane (idea -> PRD -> issues -> TDD -> review -> PR verify -> release post)
+cp node_modules/pi-skill-playbook/samples/pi-oss-new.yml .pi/playbooks/
+
+# Pi OSS bootstrap only (repo + vault setup -> PRD -> issues)
+cp node_modules/pi-skill-playbook/samples/pi-oss-bootstrap-only.yml .pi/playbooks/
+
+# Multica OSS maintenance onboarding
+cp node_modules/pi-skill-playbook/samples/oss-maintenance-onboard.yml .pi/playbooks/
+```
+
+Add run state to the target repo's `.gitignore`:
+
+```gitignore
+.pi/playbook-runs/
+```
+
+## Start a run
+
+From the Pi TUI, list playbooks and start one with the selection UI:
 
 ```text
+/playbook:list
 /playbook:start
+```
+
+When multiple playbooks exist, Pi shows a selector with validation status for each file. The run id is generated automatically.
+
+## Drive the workflow
+
+```text
 /skill:grill-with-docs <feature idea>
 /playbook:done
 /playbook:choose
@@ -16,3 +50,5 @@ Copy or create YAML playbooks in the target project under `.pi/playbooks/`, then
 - `/playbook:resume` opens an active-run selector.
 - `/playbook:choose` opens a selector for the current step's valid outcomes.
 - `/playbook:cancel` selects an active run when needed and asks for confirmation before marking it cancelled.
+
+For Pi OSS samples, run the skill named in the widget's command hint at each step. Single-outcome steps can auto-advance when the assistant emits a visible `PLAYBOOK_OUTCOME:` marker.

package/extensions/index.ts

@@ -5,9 +5,36 @@ import { findPlaybook, loadPlaybooks } from "../src/playbooks.js";
 import { getGitignoreAdvisory } from "../src/gitignore.js";
 import { renderStepCard, renderValidationErrors } from "../src/render.js";
 import { normalizeSkillCommandName, validatePlaybook, validateUniquePlaybookIds } from "../src/validation.js";
+import { handleRecordCommand, RECORD_COMMANDS, recordUsage } from "../src/record-handlers.js";
 import type { LoadedPlaybook, PlaybookRunState } from "../src/types.js";
 
 const WIDGET_ID = "pi-skill-playbook";
+let gitignoreAdvisoryShownThisSession = false;
+
+export function resetGitignoreAdvisorySessionForTest(): void {
+  gitignoreAdvisoryShownThisSession = false;
+}
+
+async function notifyWithGitignoreAdvisory(
+  cwd: string,
+  ui: UiLike | undefined,
+  lines: string[],
+  defaultLevel: "info" | "warning" = "info",
+): Promise<void> {
+  if (gitignoreAdvisoryShownThisSession) {
+    notify(ui, lines.join("\n"), defaultLevel);
+    return;
+  }
+
+  const advisory = await getGitignoreAdvisory(cwd);
+  if (!advisory) {
+    notify(ui, lines.join("\n"), defaultLevel);
+    return;
+  }
+
+  gitignoreAdvisoryShownThisSession = true;
+  notify(ui, [...lines, "", advisory].join("\n"), "warning");
+}
 
 const COMMANDS = [
   ["list", "list available playbooks"],
@@ -90,6 +117,30 @@ export default function piSkillPlaybook(pi: ExtensionAPI) {
       },
     });
   }
+
+  for (const [command, description] of RECORD_COMMANDS) {
+    pi.registerCommand(`playbook:${command}`, {
+      description: `Playbook: ${description}.`,
+      handler: async (args, ctx) => {
+        try {
+          await handleRecordCommand(pi, command, args, ctx);
+        } catch (error) {
+          notify(ctx.hasUI ? ctx.ui : undefined, error instanceof Error ? error.message : String(error), "error");
+        }
+      },
+    });
+  }
+
+  pi.registerCommand("playbook:record", {
+    description: "Playbook: record an explicit skill flow into a draft.",
+    handler: async (args, ctx) => {
+      try {
+        await handleRecordCommand(pi, "record", args, ctx);
+      } catch (error) {
+        notify(ctx.hasUI ? ctx.ui : undefined, error instanceof Error ? error.message : String(error), "error");
+      }
+    },
+  });
 }
 
 export async function handlePlaybookCommand(
@@ -124,7 +175,6 @@ export async function handlePlaybookCommand(
       await cancelRun(ctx.cwd, ui);
       return;
     case "import-web":
-    case "record":
       notify(ui, `/playbook:${command} is deferred after the Core 6 MVP scaffold.`, "warning");
       return;
     default:
@@ -172,8 +222,7 @@ async function createAndActivateRun(cwd: string, playbook: LoadedPlaybook, runNa
   await saveRun(cwd, run);
   await setActiveRun(cwd, run.runId);
   renderWidget(ui, playbook, run);
-  const advisory = await getGitignoreAdvisory(cwd);
-  notify(ui, [`Started ${run.runId}.`, ...(advisory ? ["", advisory] : [])].join("\n"), advisory ? "warning" : "info");
+  await notifyWithGitignoreAdvisory(cwd, ui, [`Started ${run.runId}.`]);
 }
 
 async function resumeRun(cwd: string, ui: UiLike | undefined): Promise<void> {
@@ -184,7 +233,7 @@ async function resumeRun(cwd: string, ui: UiLike | undefined): Promise<void> {
   if (!playbook) throw new Error(`Run '${run.runId}' references missing playbook '${run.playbookId}'.`);
   await setActiveRun(cwd, run.runId);
   renderWidget(ui, playbook, run);
-  notify(ui, `Resumed ${run.runId}.`, "info");
+  await notifyWithGitignoreAdvisory(cwd, ui, [`Resumed ${run.runId}.`]);
 }
 
 async function cancelRun(cwd: string, ui: UiLike | undefined): Promise<void> {
@@ -226,8 +275,7 @@ async function showStatus(cwd: string, ui: UiLike | undefined): Promise<void> {
   if (!playbook) throw new Error(`Run '${runId}' references missing playbook '${run.playbookId}'.`);
   const lines = renderStepCard(playbook, run);
   renderWidget(ui, playbook, run);
-  const advisory = await getGitignoreAdvisory(cwd);
-  notify(ui, [...lines, ...(advisory ? ["", advisory] : [])].join("\n"), advisory ? "warning" : "info");
+  await notifyWithGitignoreAdvisory(cwd, ui, lines);
 }
 
 async function completeCurrentStep(cwd: string, ui: UiLike | undefined): Promise<void> {
@@ -508,6 +556,8 @@ function usage(): string {
     "/playbook:done",
     "/playbook:choose",
     "/playbook:cancel",
+    "",
+    recordUsage(),
   ].join("\n");
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-skill-playbook",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "type": "module",
   "description": "Pi extension for passive, human-mediated Agent Skill playbooks.",
   "keywords": ["pi-package", "pi-extension", "agent-skills", "playbook"],

package/samples/oss-maintenance-onboard.yml

@@ -0,0 +1,22 @@
+version: 1
+id: oss-maintenance-onboard
+name: OSS Maintenance Onboarding
+entry: onboard
+autoAdvance: auto
+
+skills:
+  oss-maintenance-onboarding:
+    role: entry
+
+steps:
+  onboard:
+    primarySkill: oss-maintenance-onboarding
+    commandHint: "/skill:oss-maintenance-onboarding add this OSS target to Multica maintenance"
+    doneWhen:
+      - Target is registered in the vault maintenance control surface.
+      - Live Multica project is created or linked when requested.
+      - Controllers and Autopilot tracking are configured conservatively.
+      - Pilot issue verification notes are captured for the first maintenance slice.
+    transitions:
+      - outcome: complete
+        to: complete

package/samples/pi-oss-bootstrap-only.yml

@@ -0,0 +1,43 @@
+version: 1
+id: pi-oss-bootstrap-only
+name: Pi OSS Bootstrap Only
+entry: bootstrap
+autoAdvance: auto
+
+skills:
+  pi-oss-bootstrap:
+    role: entry
+  to-prd-for-oss:
+    role: internal
+  to-issues-for-oss:
+    role: internal
+
+steps:
+  bootstrap:
+    primarySkill: pi-oss-bootstrap
+    commandHint: "/skill:pi-oss-bootstrap bootstrap a new Pi extension OSS project"
+    doneWhen:
+      - OSS repo exists under Projects/OSS/.
+      - Vault project folder exists under 4_Project/OSS/<project_key>/.
+    transitions:
+      - outcome: ready-for-prd
+        to: prd
+
+  prd:
+    primarySkill: to-prd-for-oss
+    commandHint: "/skill:to-prd-for-oss create PRD in 4_Project/<project>/Docs/"
+    doneWhen:
+      - PRD exists under the target OSS project Docs folder.
+    transitions:
+      - outcome: ready-for-issues
+        to: issues
+
+  issues:
+    primarySkill: to-issues-for-oss
+    commandHint: "/skill:to-issues-for-oss break PRD into tracer-bullet issues"
+    doneWhen:
+      - Issue files exist under 4_Project/<project>/Issues/.
+      - Issues are independently grabbable.
+    transitions:
+      - outcome: complete
+        to: complete

package/samples/pi-oss-new.yml

@@ -0,0 +1,91 @@
+version: 1
+id: pi-oss-new
+name: Pi OSS New Extension Delivery
+entry: grill
+autoAdvance: auto
+
+skills:
+  grill-with-docs:
+    role: entry
+  to-prd-for-oss:
+    role: internal
+  to-issues-for-oss:
+    role: internal
+  tdd:
+    role: internal
+  review:
+    role: internal
+  pi-extension-pr-verify:
+    role: internal
+  x-release-post:
+    role: internal
+
+steps:
+  grill:
+    primarySkill: grill-with-docs
+    commandHint: "/skill:grill-with-docs <Pi OSS extension idea>"
+    doneWhen:
+      - Problem boundary is clear for the new Pi OSS project.
+      - Key terminology and repo layout are resolved.
+    transitions:
+      - outcome: ready-for-prd
+        to: prd
+
+  prd:
+    primarySkill: to-prd-for-oss
+    commandHint: "/skill:to-prd-for-oss create PRD in 4_Project/<project>/Docs/"
+    doneWhen:
+      - PRD exists under the target OSS project Docs folder.
+    transitions:
+      - outcome: ready-for-issues
+        to: issues
+
+  issues:
+    primarySkill: to-issues-for-oss
+    commandHint: "/skill:to-issues-for-oss break PRD into tracer-bullet issues"
+    doneWhen:
+      - Issue files exist under 4_Project/<project>/Issues/.
+      - Issues are independently grabbable.
+    transitions:
+      - outcome: ready-for-implementation
+        to: implement
+
+  implement:
+    primarySkill: tdd
+    commandHint: "/skill:tdd implement the next OSS issue"
+    doneWhen:
+      - Tests pass.
+      - Implementation is complete for the current slice.
+    transitions:
+      - outcome: ready-for-review
+        to: review
+
+  review:
+    primarySkill: review
+    commandHint: "/skill:review review this branch against the plan"
+    doneWhen:
+      - Standards and spec review results are known.
+    transitions:
+      - outcome: pass
+        to: pr-verify
+      - outcome: fail
+        to: implement
+
+  pr-verify:
+    primarySkill: pi-extension-pr-verify
+    commandHint: "/skill:pi-extension-pr-verify verify the PR locally"
+    doneWhen:
+      - PR worktree is set up and automated checks pass.
+      - Manual Pi TUI verification checklist is complete.
+    transitions:
+      - outcome: ready-for-release
+        to: release-post
+
+  release-post:
+    primarySkill: x-release-post
+    commandHint: "/skill:x-release-post draft X release announcement"
+    doneWhen:
+      - English and Japanese release post drafts are saved.
+    transitions:
+      - outcome: complete
+        to: complete

package/src/draft-save.ts

@@ -0,0 +1,81 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { stringify } from "yaml";
+import { PLAYBOOK_DIR } from "./playbooks.js";
+import { renderValidationErrors } from "./render.js";
+import type { LoadedPlaybook, PlaybookDefinition } from "./types.js";
+import { parsePlaybookYaml, validatePlaybook } from "./validation.js";
+
+export interface DraftSaveUi {
+  notify(message: string, level: "info" | "warning" | "error"): void;
+  confirm?(title: string, message: string): Promise<boolean>;
+}
+
+export function definitionToYaml(definition: PlaybookDefinition): string {
+  return `${stringify(definition)}\n`;
+}
+
+export function previewDraft(definition: PlaybookDefinition, targetPath: string): string {
+  const yaml = definitionToYaml(definition);
+  return [`Target: ${targetPath}`, "", yaml.trimEnd()].join("\n");
+}
+
+export function validateDraftDefinition(
+  definition: PlaybookDefinition,
+  targetPath: string,
+  availableSkills: ReadonlySet<string>,
+): { loaded: LoadedPlaybook; result: ReturnType<typeof validatePlaybook> } {
+  const loaded = parsePlaybookYaml(definitionToYaml(definition), targetPath);
+  const result = validatePlaybook(loaded, availableSkills, { requireSkills: true });
+  return { loaded, result };
+}
+
+export async function savePlaybookDraft(
+  cwd: string,
+  definition: PlaybookDefinition,
+  availableSkills: ReadonlySet<string>,
+  ui: DraftSaveUi | undefined,
+  options: { sourceLabel: string },
+): Promise<boolean> {
+  const targetPath = join(cwd, PLAYBOOK_DIR, `${definition.id}.yml`);
+  const preview = previewDraft(definition, targetPath);
+  const { result } = validateDraftDefinition(definition, targetPath, availableSkills);
+
+  notify(ui, preview, "info");
+
+  if (!result.valid) {
+    notify(ui, `${options.sourceLabel} draft validation failed:\n${renderValidationErrors(result.errors)}`, "error");
+    return false;
+  }
+
+  if (!ui?.confirm) {
+    notify(ui, "Confirmation UI is required before saving a recorded draft.", "error");
+    return false;
+  }
+
+  const confirmed = await ui.confirm(
+    `Save ${options.sourceLabel} playbook draft?`,
+    `Write ${definition.id}.yml to ${PLAYBOOK_DIR}/ after validation.`,
+  );
+  if (!confirmed) {
+    notify(ui, `${options.sourceLabel} draft save skipped.`, "info");
+    return false;
+  }
+
+  await mkdir(join(cwd, PLAYBOOK_DIR), { recursive: true });
+  try {
+    await writeFile(targetPath, definitionToYaml(definition), { encoding: "utf8", flag: "wx" });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+      notify(ui, `${options.sourceLabel} draft already exists at ${targetPath}.`, "error");
+      return false;
+    }
+    throw error;
+  }
+  notify(ui, `Saved playbook draft to ${targetPath}.`, "info");
+  return true;
+}
+
+function notify(ui: DraftSaveUi | undefined, message: string, level: "info" | "warning" | "error"): void {
+  ui?.notify(message, level);
+}

package/src/gitignore.ts

@@ -2,13 +2,46 @@ import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { RUNS_DIR } from "./state.js";
 
+export const GITIGNORE_SNIPPET = `${RUNS_DIR}/`;
+
+const IGNORE_PATTERNS = new Set([
+  RUNS_DIR,
+  `${RUNS_DIR}/`,
+  `/${RUNS_DIR}`,
+  `/${RUNS_DIR}/`,
+  `${RUNS_DIR}/**`,
+  ".pi",
+  ".pi/",
+  "/.pi",
+  "/.pi/",
+  ".pi/**",
+  "/.pi/**",
+]);
+
+export function isPlaybookRunsGitignored(gitignoreContent: string): boolean {
+  let ignored = false;
+  for (const raw of gitignoreContent.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+
+    const negated = line.startsWith("!");
+    const candidate = negated ? line.slice(1).trim() : line;
+    if (!IGNORE_PATTERNS.has(candidate)) continue;
+
+    ignored = !negated;
+  }
+  return ignored;
+}
+
 export async function getGitignoreAdvisory(cwd: string): Promise<string | undefined> {
   try {
     const gitignore = await readFile(join(cwd, ".gitignore"), "utf8");
-    const lines = gitignore.split(/\r?\n/).map((line) => line.trim());
-    if (lines.includes(RUNS_DIR) || lines.includes(`${RUNS_DIR}/`)) return undefined;
-  } catch {
+    if (isPlaybookRunsGitignored(gitignore)) return undefined;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw error;
+    }
     // Missing .gitignore still needs advisory.
   }
-  return `Run state is personal. Add this to .gitignore:\n${RUNS_DIR}/`;
+  return `Run state is personal. Add this to .gitignore:\n${GITIGNORE_SNIPPET}`;
 }

package/src/record-handlers.ts

@@ -0,0 +1,225 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { savePlaybookDraft } from "./draft-save.js";
+import {
+  createRecordSession,
+  markSkill,
+  recordBranch,
+  recordSessionToDefinition,
+  renderRecordStatus,
+  validatePlaybookId,
+} from "./record.js";
+import {
+  clearActiveRecordSession,
+  loadActiveRecordSession,
+  saveRecordSession,
+  setActiveRecordSession,
+} from "./record-state.js";
+import { normalizeSkillCommandName } from "./validation.js";
+
+type RecordUi = {
+  notify(message: string, level: "info" | "warning" | "error"): void;
+  select?(title: string, options: string[]): Promise<string | undefined>;
+  confirm?(title: string, message: string): Promise<boolean>;
+};
+
+type RecordContext = {
+  cwd: string;
+  hasUI: boolean;
+  ui?: RecordUi;
+};
+
+export const RECORD_COMMANDS = [
+  ["record:start", "start recording an explicit skill flow"],
+  ["record:mark", "mark explicit skill usage in the active recording"],
+  ["record:branch", "record a branch outcome label"],
+  ["record:stop", "stop recording and save a playbook draft"],
+  ["record:status", "show active recording status"],
+] as const;
+
+export function recordUsage(): string {
+  return [
+    "Usage:",
+    "/playbook:record:start <playbook-id> [--name <display name>]",
+    "/playbook:record:mark [<skill-name>]",
+    "/playbook:record:branch <outcome-label> [--to <step-id>]",
+    "/playbook:record:stop",
+    "/playbook:record:status",
+  ].join("\n");
+}
+
+export async function handleRecordCommand(
+  pi: ExtensionAPI,
+  command: string,
+  args: string,
+  ctx: RecordContext,
+): Promise<void> {
+  const ui = ctx.hasUI ? ctx.ui : undefined;
+  const tokens = tokenize(args);
+
+  switch (command) {
+    case "record":
+      if (tokens.length === 0) {
+        await showRecordStatus(ctx.cwd, ui);
+        notify(ui, recordUsage(), "info");
+        return;
+      }
+      notify(ui, recordUsage(), "error");
+      return;
+    case "record:start":
+      await startRecording(tokens, ctx.cwd, ui);
+      return;
+    case "record:mark":
+      await markRecordingSkill(pi, tokens, ctx.cwd, ui);
+      return;
+    case "record:branch":
+      await branchRecording(tokens, ctx.cwd, ui);
+      return;
+    case "record:stop":
+      await stopRecording(pi, ctx.cwd, ui);
+      return;
+    case "record:status":
+      await showRecordStatus(ctx.cwd, ui);
+      return;
+    default:
+      notify(ui, recordUsage(), "error");
+  }
+}
+
+async function startRecording(tokens: string[], cwd: string, ui: RecordUi | undefined): Promise<void> {
+  const playbookId = tokens[0];
+  if (!playbookId) {
+    notify(ui, "Playbook id is required. Example: /playbook:record:start my-recorded-flow", "error");
+    return;
+  }
+
+  validatePlaybookId(playbookId);
+  const nameFlag = tokens.indexOf("--name");
+  const playbookName = nameFlag >= 0 ? tokens.slice(nameFlag + 1).join(" ").trim() : titleCase(playbookId);
+  if (nameFlag >= 0 && !playbookName) {
+    notify(ui, "Display name is required after --name.", "error");
+    return;
+  }
+
+  const existing = await loadActiveRecordSession(cwd);
+  if (existing) {
+    notify(ui, `Recording already active (${existing.playbookId}). Run /playbook:record:stop first.`, "warning");
+    return;
+  }
+
+  const session = createRecordSession(playbookId, playbookName);
+  await saveRecordSession(cwd, session);
+  await setActiveRecordSession(cwd, session.sessionId);
+  notify(ui, [`Started recording ${playbookId}.`, ...renderRecordStatus(session)].join("\n"), "info");
+}
+
+async function markRecordingSkill(
+  pi: ExtensionAPI,
+  tokens: string[],
+  cwd: string,
+  ui: RecordUi | undefined,
+): Promise<void> {
+  const session = await requireActiveSession(cwd, ui);
+  if (!session) return;
+
+  const availableSkills = getAvailableSkills(pi);
+  let skillName = tokens[0];
+  if (!skillName) {
+    const selected = await pickSkill(pi, ui);
+    if (!selected) return;
+    skillName = selected;
+  } else {
+    skillName = normalizeSkillCommandName(skillName);
+    if (!availableSkills.has(skillName)) {
+      notify(ui, `Unknown Agent Skill '${skillName}'.`, "error");
+      return;
+    }
+  }
+
+  const updated = markSkill(session, skillName);
+  await saveRecordSession(cwd, updated);
+  notify(ui, [`Marked skill '${skillName}' on step '${updated.currentStepId}'.`, ...renderRecordStatus(updated)].join("\n"), "info");
+}
+
+async function branchRecording(tokens: string[], cwd: string, ui: RecordUi | undefined): Promise<void> {
+  const session = await requireActiveSession(cwd, ui);
+  if (!session) return;
+
+  const outcome = tokens[0];
+  if (!outcome) {
+    notify(ui, "Outcome label is required. Example: /playbook:record:branch ready-for-prd", "error");
+    return;
+  }
+
+  const toFlag = tokens.indexOf("--to");
+  const toStepId = toFlag >= 0 ? tokens[toFlag + 1] : undefined;
+  const updated = recordBranch(session, outcome, toStepId);
+  await saveRecordSession(cwd, updated);
+  notify(ui, [`Recorded branch outcome '${outcome}'.`, ...renderRecordStatus(updated)].join("\n"), "info");
+}
+
+async function stopRecording(pi: ExtensionAPI, cwd: string, ui: RecordUi | undefined): Promise<void> {
+  const session = await requireActiveSession(cwd, ui);
+  if (!session) return;
+
+  const definition = recordSessionToDefinition(session);
+  const saved = await savePlaybookDraft(cwd, definition, getAvailableSkills(pi), ui, { sourceLabel: "Recorded" });
+  if (saved) {
+    await clearActiveRecordSession(cwd);
+    notify(ui, `Recording ${session.playbookId} converted to playbook draft.`, "info");
+  }
+}
+
+async function showRecordStatus(cwd: string, ui: RecordUi | undefined): Promise<void> {
+  const session = await loadActiveRecordSession(cwd);
+  if (!session) {
+    notify(ui, "No active recording. Start one with /playbook:record:start <playbook-id>.", "info");
+    return;
+  }
+  notify(ui, renderRecordStatus(session).join("\n"), "info");
+}
+
+async function requireActiveSession(cwd: string, ui: RecordUi | undefined) {
+  const session = await loadActiveRecordSession(cwd);
+  if (!session) {
+    notify(ui, "No active recording. Start one with /playbook:record:start <playbook-id>.", "error");
+    return undefined;
+  }
+  return session;
+}
+
+async function pickSkill(pi: ExtensionAPI, ui: RecordUi | undefined): Promise<string | undefined> {
+  const skills = [...getAvailableSkills(pi)].sort();
+  if (skills.length === 0) {
+    notify(ui, "No Agent Skills are available to mark.", "error");
+    return undefined;
+  }
+  if (!ui?.select) {
+    notify(ui, "Skill name is required when selection UI is unavailable. Example: /playbook:record:mark grill-with-docs", "error");
+    return undefined;
+  }
+  const selected = await ui.select("Mark which skill?", skills);
+  return selected ? normalizeSkillCommandName(selected) : undefined;
+}
+
+function getAvailableSkills(pi: ExtensionAPI): ReadonlySet<string> {
+  const skills = pi.getCommands()
+    .filter((command) => command.source === "skill")
+    .map((command) => normalizeSkillCommandName(command.name));
+  return new Set(skills);
+}
+
+function tokenize(args: string): string[] {
+  return args.trim().split(/\s+/).filter(Boolean);
+}
+
+function titleCase(slug: string): string {
+  return slug
+    .split("-")
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+function notify(ui: RecordUi | undefined, message: string, level: "info" | "warning" | "error"): void {
+  ui?.notify(message, level);
+}

package/src/record-state.ts

@@ -0,0 +1,72 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { RecordSession } from "./record-types.js";
+
+export const RECORDS_DIR = ".pi/playbook-records";
+const ACTIVE_FILE = "active.json";
+const SESSION_ID_PATTERN = /^record-[a-z0-9][a-z0-9-]*-\d+$/;
+
+function assertValidSessionId(sessionId: string): string {
+  if (!SESSION_ID_PATTERN.test(sessionId)) {
+    throw new Error(`Invalid record session id '${sessionId}'.`);
+  }
+  return sessionId;
+}
+
+export function recordsDir(cwd: string): string {
+  return join(cwd, RECORDS_DIR);
+}
+
+export function sessionFile(cwd: string, sessionId: string): string {
+  return join(recordsDir(cwd), `${assertValidSessionId(sessionId)}.json`);
+}
+
+export function activeRecordFile(cwd: string): string {
+  return join(recordsDir(cwd), ACTIVE_FILE);
+}
+
+export async function saveRecordSession(cwd: string, session: RecordSession): Promise<void> {
+  await mkdir(recordsDir(cwd), { recursive: true });
+  await writeFile(sessionFile(cwd, session.sessionId), `${JSON.stringify(session, null, 2)}\n`, "utf8");
+}
+
+export async function loadRecordSession(cwd: string, sessionId: string): Promise<RecordSession | undefined> {
+  try {
+    return JSON.parse(await readFile(sessionFile(cwd, sessionId), "utf8")) as RecordSession;
+  } catch (error) {
+    if (isNotFound(error)) return undefined;
+    throw error;
+  }
+}
+
+export async function setActiveRecordSession(cwd: string, sessionId: string): Promise<void> {
+  assertValidSessionId(sessionId);
+  await mkdir(recordsDir(cwd), { recursive: true });
+  await writeFile(activeRecordFile(cwd), `${JSON.stringify({ sessionId }, null, 2)}\n`, "utf8");
+}
+
+export async function loadActiveRecordSessionId(cwd: string): Promise<string | undefined> {
+  try {
+    const state = JSON.parse(await readFile(activeRecordFile(cwd), "utf8")) as { sessionId?: string };
+    return typeof state.sessionId === "string" && SESSION_ID_PATTERN.test(state.sessionId)
+      ? state.sessionId
+      : undefined;
+  } catch (error) {
+    if (isNotFound(error)) return undefined;
+    throw error;
+  }
+}
+
+export async function clearActiveRecordSession(cwd: string): Promise<void> {
+  await rm(activeRecordFile(cwd), { force: true });
+}
+
+export async function loadActiveRecordSession(cwd: string): Promise<RecordSession | undefined> {
+  const sessionId = await loadActiveRecordSessionId(cwd);
+  if (!sessionId) return undefined;
+  return loadRecordSession(cwd, sessionId);
+}
+
+function isNotFound(error: unknown): boolean {
+  return typeof error === "object" && error !== null && "code" in error && (error as { code?: string }).code === "ENOENT";
+}

package/src/record-types.ts

@@ -0,0 +1,34 @@
+import type { PlaybookTransition } from "./types.js";
+
+export type RecordMarkKind = "skill" | "branch";
+
+export interface RecordMark {
+  at: string;
+  kind: RecordMarkKind;
+  skillName?: string;
+  outcome?: string;
+  toStepId?: string;
+}
+
+export interface RecordedStepDraft {
+  id: string;
+  primarySkill: string;
+  commandHint: string;
+  doneWhen: string[];
+  transitions: PlaybookTransition[];
+  closed: boolean;
+}
+
+export interface RecordSession {
+  sessionId: string;
+  playbookId: string;
+  playbookName: string;
+  status: "recording";
+  createdAt: string;
+  updatedAt: string;
+  entryStepId: string | null;
+  currentStepId: string | null;
+  steps: Record<string, RecordedStepDraft>;
+  pendingBranch: { fromStepId: string; outcome: string } | null;
+  marks: RecordMark[];
+}

package/src/record.ts

@@ -0,0 +1,219 @@
+import type { PlaybookDefinition, PlaybookSkillDefinition } from "./types.js";
+import type { RecordMark, RecordSession, RecordedStepDraft } from "./record-types.js";
+
+const ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
+export function createRecordSession(playbookId: string, playbookName: string, now = new Date().toISOString()): RecordSession {
+  validatePlaybookId(playbookId);
+  return {
+    sessionId: `record-${playbookId}-${stamp(now)}`,
+    playbookId,
+    playbookName,
+    status: "recording",
+    createdAt: now,
+    updatedAt: now,
+    entryStepId: null,
+    currentStepId: null,
+    steps: {},
+    pendingBranch: null,
+    marks: [],
+  };
+}
+
+export function markSkill(session: RecordSession, skillName: string, now = new Date().toISOString()): RecordSession {
+  const normalizedSkillName = skillName.trim();
+  validateSkillName(normalizedSkillName);
+  const next = cloneSession(session);
+
+  if (next.pendingBranch) {
+    const step = createStep(normalizedSkillName, next.steps);
+    next.steps[step.id] = step;
+    linkPendingBranch(next, step.id);
+    next.entryStepId ??= step.id;
+    next.currentStepId = step.id;
+    next.marks.push({ at: now, kind: "skill", skillName: normalizedSkillName });
+    next.updatedAt = now;
+    return next;
+  }
+
+  if (!next.currentStepId) {
+    const step = createStep(normalizedSkillName, next.steps);
+    next.steps[step.id] = step;
+    next.entryStepId = step.id;
+    next.currentStepId = step.id;
+    next.marks.push({ at: now, kind: "skill", skillName: normalizedSkillName });
+    next.updatedAt = now;
+    return next;
+  }
+
+  const current = next.steps[next.currentStepId];
+  if (!current) throw new Error(`Current step '${next.currentStepId}' is missing.`);
+  if (!current.closed) {
+    throw new Error(`Step '${current.id}' is still open. Run /playbook:record:branch <outcome> before marking the next skill.`);
+  }
+
+  throw new Error("No pending branch outcome. Run /playbook:record:branch <outcome> before marking the next skill.");
+}
+
+export function recordBranch(
+  session: RecordSession,
+  outcome: string,
+  toStepId?: string,
+  now = new Date().toISOString(),
+): RecordSession {
+  const label = outcome.trim();
+  if (!label) throw new Error("Branch outcome label is required.");
+
+  const next = cloneSession(session);
+  if (!next.currentStepId) throw new Error("No step is open. Run /playbook:record:mark first.");
+
+  const current = next.steps[next.currentStepId];
+  if (!current) throw new Error(`Current step '${next.currentStepId}' is missing.`);
+  if (current.closed) throw new Error(`Step '${current.id}' is already closed.`);
+
+  if (current.transitions.some((transition) => transition.outcome === label)) {
+    throw new Error(`Outcome '${label}' is already recorded for step '${current.id}'.`);
+  }
+
+  if (toStepId) {
+    if (!(toStepId in next.steps)) throw new Error(`Target step '${toStepId}' does not exist.`);
+    current.transitions.push({ outcome: label, to: toStepId });
+    current.closed = true;
+    next.currentStepId = toStepId;
+    next.pendingBranch = null;
+    next.marks.push({ at: now, kind: "branch", outcome: label, toStepId });
+    next.updatedAt = now;
+    return next;
+  }
+
+  current.transitions.push({ outcome: label, to: "pending" });
+  current.closed = true;
+  next.pendingBranch = { fromStepId: current.id, outcome: label };
+  next.currentStepId = null;
+  next.marks.push({ at: now, kind: "branch", outcome: label });
+  next.updatedAt = now;
+  return next;
+}
+
+export function finalizeRecordSession(session: RecordSession, now = new Date().toISOString()): RecordSession {
+  const next = cloneSession(session);
+  if (!next.entryStepId) throw new Error("Recording is empty. Mark at least one skill before stopping.");
+
+  if (next.pendingBranch) {
+    throw new Error(`Pending branch outcome '${next.pendingBranch.outcome}' needs a target skill mark.`);
+  }
+
+  if (next.currentStepId) {
+    const current = next.steps[next.currentStepId];
+    if (current && !current.closed) {
+      current.transitions.push({ outcome: "complete", to: "complete" });
+      current.closed = true;
+    }
+  }
+
+  for (const step of Object.values(next.steps)) {
+    for (const transition of step.transitions) {
+      if (transition.to === "pending") {
+        throw new Error(`Step '${step.id}' still has an unresolved branch target.`);
+      }
+    }
+  }
+
+  next.updatedAt = now;
+  return next;
+}
+
+export function recordSessionToDefinition(session: RecordSession): PlaybookDefinition {
+  const finalized = finalizeRecordSession(session);
+  const skills: Record<string, PlaybookSkillDefinition> = {};
+  const steps: PlaybookDefinition["steps"] = {};
+
+  for (const step of Object.values(finalized.steps)) {
+    if (!(step.primarySkill in skills)) {
+      skills[step.primarySkill] = { role: step.id === finalized.entryStepId ? "entry" : "internal" };
+    }
+    steps[step.id] = {
+      primarySkill: step.primarySkill,
+      commandHint: step.commandHint,
+      doneWhen: step.doneWhen,
+      transitions: step.transitions.map((transition) => ({
+        outcome: transition.outcome,
+        to: transition.to,
+      })),
+    };
+  }
+
+  return {
+    version: 1,
+    id: finalized.playbookId,
+    name: finalized.playbookName,
+    entry: finalized.entryStepId!,
+    autoAdvance: "auto",
+    skills,
+    steps,
+  };
+}
+
+export function renderRecordStatus(session: RecordSession): string[] {
+  const lines = [
+    `Recording ${session.playbookId} (${session.playbookName})`,
+    `Session: ${session.sessionId}`,
+    `Steps: ${Object.keys(session.steps).length}`,
+    `Marks: ${session.marks.length}`,
+  ];
+  if (session.currentStepId) {
+    const step = session.steps[session.currentStepId];
+    lines.push(`Current step: ${session.currentStepId}${step?.closed ? " (closed)" : " (open)"}`);
+  } else if (session.pendingBranch) {
+    lines.push(`Pending branch: ${session.pendingBranch.outcome} → awaiting next skill mark`);
+  }
+  return lines;
+}
+
+export function validatePlaybookId(playbookId: string): void {
+  if (!ID_PATTERN.test(playbookId)) {
+    throw new Error(`Playbook id '${playbookId}' must be lower-kebab-case.`);
+  }
+}
+
+function createStep(skillName: string, existing: Record<string, RecordedStepDraft>): RecordedStepDraft {
+  const id = uniqueStepId(skillName, existing);
+  return {
+    id,
+    primarySkill: skillName,
+    commandHint: `/skill:${skillName}`,
+    doneWhen: [`Recorded completion criteria for ${skillName}.`],
+    transitions: [],
+    closed: false,
+  };
+}
+
+function uniqueStepId(skillName: string, existing: Record<string, RecordedStepDraft>): string {
+  const base = skillName.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "step";
+  if (!(base in existing)) return base;
+  let index = 2;
+  while (`${base}-${index}` in existing) index += 1;
+  return `${base}-${index}`;
+}
+
+function linkPendingBranch(session: RecordSession, toStepId: string): void {
+  if (!session.pendingBranch) return;
+  const from = session.steps[session.pendingBranch.fromStepId];
+  if (!from) throw new Error(`Pending branch source '${session.pendingBranch.fromStepId}' is missing.`);
+  const transition = from.transitions.find((candidate) => candidate.outcome === session.pendingBranch!.outcome);
+  if (!transition) throw new Error(`Pending branch outcome '${session.pendingBranch.outcome}' is missing.`);
+  transition.to = toStepId;
+  session.pendingBranch = null;
+}
+
+function validateSkillName(skillName: string): void {
+  if (!skillName.trim()) throw new Error("Skill name is required.");
+}
+
+function cloneSession(session: RecordSession): RecordSession {
+  return structuredClone(session);
+}
+
+function stamp(now: string): string {
+  return now.replace(/[-:.TZ]/g, "");
+}