@runtypelabs/cli 2.17.0 → 2.19.0

package/README.md

@@ -211,7 +211,7 @@ milestones:
 EOF
 ```
 
-**Search order**: Exact path → `.runtype/marathons/playbooks/<name>.yaml|yml|json` (repo) → `~/.runtype/marathons/playbooks/<name>.yaml|yml|json` (user).
+**Search order**: Exact path → `.runtype/marathons/playbooks/<name>.yaml|yml|json|ts|mts` (repo) → `~/.runtype/marathons/playbooks/<name>.yaml|yml|json|ts|mts` (user).
 
 **Completion criteria types**:
 
@@ -248,6 +248,33 @@ milestones:
 | `requireVerification`    | `boolean`  | Require verification before `TASK_COMPLETE`.                                                                                  |
 | `outputRoot`             | `string`   | For creation tasks: confine writes to this directory (e.g. `"public/"`).                                                      |
 
+#### TypeScript playbooks
+
+Playbooks can also be TypeScript modules (`.ts`/`.mts`), loaded at runtime via jiti — no build step or special Node version required. Every behavior slot (`instructions`, `completionCriteria`, `recovery`, `intercept`, ...) then accepts a plain function in addition to inline data and hook references:
+
+```ts
+// .runtype/marathons/playbooks/my-task.ts
+import { definePlaybook, type RunTaskStateSlice } from '@runtypelabs/sdk'
+
+export default definePlaybook({
+  name: 'my-task',
+  stallPolicy: { nudgeAfter: 1, stopAfter: 4 },
+  milestones: [
+    {
+      name: 'build',
+      instructions: (state: RunTaskStateSlice) => `Build it. Plan: ${state.planPath}`,
+      recovery: (state) =>
+        `You went ${state.consecutiveEmptySessions ?? 0} sessions without a tool call. Write a file now.`,
+      canAcceptCompletion: true,
+    },
+  ],
+})
+```
+
+`definePlaybook` (from `@runtypelabs/sdk`, install as a devDependency for editor types) is optional sugar — a plain object export with the same shape works without the package installed. To register named hooks (reusable from YAML playbooks too), export a factory instead: `export default ({ registerWorkflowHook }) => ({ ... })`. A complete example lives at [`examples/playbooks/release-notes.ts`](./examples/playbooks/release-notes.ts).
+
+**Hook references**: any slot can reference a registered behavior by name instead of carrying data — `builtin:*` names expose the default workflow's behaviors (e.g. `instructions: builtin:research-instructions`, `completionCriteria: { type: builtin:research-complete }`), and YAML playbooks can load custom hooks from JS modules listed under `plugins:` (paths relative to the playbook file). See the comments in [`examples/playbooks/design-library.yaml`](./examples/playbooks/design-library.yaml).
+
 #### Marathon Anatomy
 
 ```