@agentproto/playbook 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agentproto contributors
+
+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,23 @@
+# @agentproto/playbook
+
+AIP-12 `PLAYBOOK.md` reference implementation. A markdown format for prompt-overlay fragments that ride on top of an operator's persona, plus a contract for how runtimes evolve them via reflective deltas without violating locked persona traits.
+
+> **Status: 0.1.0-alpha.** Generated by `scripts/scaffold-aip.mjs` — `build()` and `validate()` bodies are TODOs.
+
+Spec: <https://agentproto.sh/docs/aip-12>
+
+## Usage
+
+```ts
+import { definePlaybook } from "@agentproto/playbook"
+
+const x = definePlaybook({
+  id: "my-playbook",
+  description: "Short purpose.",
+  // ...
+})
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/chunk-QFIVEUBZ.mjs

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import { createDoctype } from '@agentproto/define-doctype';
+
+/**
+ * @agentproto/playbook v0.1.0-alpha
+ * AIP-12 PLAYBOOK.md `definePlaybook` reference implementation.
+ */
+
+var playbookFrontmatterSchema = z.object({ "schema": z.literal("playbooks/v1"), "slug": z.string().regex(new RegExp("^[a-z][a-z0-9-]*[a-z0-9]$")).min(2).max(80), "title": z.string().min(1).max(200), "entry": z.string().describe("Optional path to the entry file exposing definePlaybook. Defaults to playbook.ts.").optional(), "targets": z.array(z.any()).min(1).describe("DEPRECATED in favor of `selector`. Legacy axis-ambiguous binding \u2014 kept valid forever.").optional(), "selector": z.record(z.string(), z.any()).describe("Typed attachment binding evaluated against the subject's dimensions. Wins over `targets`/`binds_operator` when present.").optional(), "kind": z.enum(["overlay", "block-replacement"]).default("overlay"), "block": z.string().regex(new RegExp("^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)*$")).describe("Required when kind is 'block-replacement' \u2014 the named persona block to swap.").optional(), "priority": z.number().int().gte(0).lte(100).default(50), "lock_check": z.array(z.any()).describe("Locked persona traits this overlay MUST NOT modify. Author intent \u2014 runtime enforces independently.").default([]), "ttl": z.string().regex(new RegExp("^P(?:\\d+Y)?(?:\\d+M)?(?:\\d+W)?(?:\\d+D)?(?:T(?:\\d+H)?(?:\\d+M)?(?:\\d+S)?)?$")).describe("Optional ISO 8601 duration. Auto-archives at updated_at + ttl.").optional(), "evidence": z.array(z.any()).min(1), "status": z.enum(["shadow", "active", "archived"]).default("shadow"), "supersedes": z.array(z.any()).default([]), "history": z.array(z.any()).describe("Append-only audit trail of deltas, promotions, and archivals applied to this playbook.").default([]), "binds_operator": z.string().regex(new RegExp("^[a-z][a-z0-9-]*[a-z0-9]$")).describe("Optional \u2014 the specific operator (per AIP-9) this playbook is bound to. Narrower than targets[].").optional(), "created_at": z.string().datetime({ offset: true }).optional(), "updated_at": z.string().datetime({ offset: true }).optional(), "tags": z.array(z.string().regex(new RegExp("^[a-z][a-z0-9-]*$"))).default([]), "metadata": z.record(z.string(), z.any()).describe("Vendor extensions go under metadata.<vendor>.").default({}) }).strict().and(z.any()).describe("Validates the YAML frontmatter portion of an AIP-12 PLAYBOOK.md overlay manifest.");
+var definePlaybook = createDoctype({
+  aip: 12,
+  name: "playbook",
+  readIdentity: (def) => def.slug,
+  readDescription: (def) => def.title,
+  validate(def) {
+    const result = playbookFrontmatterSchema.safeParse(def);
+    if (!result.success) {
+      throw new Error(
+        `definePlaybook (AIP-12): ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+      );
+    }
+    const hasTargets = Array.isArray(def.targets) && def.targets.length > 0;
+    const selector = def.selector;
+    const hasSelector = !!selector && typeof selector === "object" && Object.keys(selector).length > 0;
+    if (!hasTargets && !hasSelector) {
+      throw new Error(
+        "definePlaybook (AIP-12): a binding is required \u2014 declare `selector` (preferred) or legacy `targets`"
+      );
+    }
+  },
+  build(def) {
+    return { ...def };
+  }
+});
+
+export { definePlaybook, playbookFrontmatterSchema };
+//# sourceMappingURL=chunk-QFIVEUBZ.mjs.map
+//# sourceMappingURL=chunk-QFIVEUBZ.mjs.map

package/dist/chunk-QFIVEUBZ.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema.ts","../src/define-playbook.ts"],"names":[],"mappings":"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","file":"chunk-QFIVEUBZ.mjs","sourcesContent":["/**\n * AIP-12 PLAYBOOK.md frontmatter zod schema.\n *\n * Generated from `resources/aip-12/draft/PLAYBOOK.schema.json` via\n * json-schema-to-zod. Imported by both `define-playbook.ts` (TS path\n * validation) and `manifest/index.ts` (.md path validation) so every\n * field-level constraint runs in both authoring paths from a single\n * source of truth — re-run scaffold-aip to refresh after spec changes.\n *\n * Cross-field rules (if/then/allOf in JSON Schema) don't translate\n * cleanly and live in `define-playbook.ts`'s `validate(def)` instead.\n */\n\nimport { z } from \"zod\"\n\nexport const playbookFrontmatterSchema = z.object({ \"schema\": z.literal(\"playbooks/v1\"), \"slug\": z.string().regex(new RegExp(\"^[a-z][a-z0-9-]*[a-z0-9]$\")).min(2).max(80), \"title\": z.string().min(1).max(200), \"entry\": z.string().describe(\"Optional path to the entry file exposing definePlaybook. Defaults to playbook.ts.\").optional(), \"targets\": z.array(z.any()).min(1).describe(\"DEPRECATED in favor of `selector`. Legacy axis-ambiguous binding — kept valid forever.\").optional(), \"selector\": z.record(z.string(), z.any()).describe(\"Typed attachment binding evaluated against the subject's dimensions. Wins over `targets`/`binds_operator` when present.\").optional(), \"kind\": z.enum([\"overlay\",\"block-replacement\"]).default(\"overlay\"), \"block\": z.string().regex(new RegExp(\"^[a-z][a-z0-9-]*(\\\\.[a-z][a-z0-9-]*)*$\")).describe(\"Required when kind is 'block-replacement' — the named persona block to swap.\").optional(), \"priority\": z.number().int().gte(0).lte(100).default(50), \"lock_check\": z.array(z.any()).describe(\"Locked persona traits this overlay MUST NOT modify. Author intent — runtime enforces independently.\").default([] as never), \"ttl\": z.string().regex(new RegExp(\"^P(?:\\\\d+Y)?(?:\\\\d+M)?(?:\\\\d+W)?(?:\\\\d+D)?(?:T(?:\\\\d+H)?(?:\\\\d+M)?(?:\\\\d+S)?)?$\")).describe(\"Optional ISO 8601 duration. Auto-archives at updated_at + ttl.\").optional(), \"evidence\": z.array(z.any()).min(1), \"status\": z.enum([\"shadow\",\"active\",\"archived\"]).default(\"shadow\"), \"supersedes\": z.array(z.any()).default([] as never), \"history\": z.array(z.any()).describe(\"Append-only audit trail of deltas, promotions, and archivals applied to this playbook.\").default([] as never), \"binds_operator\": z.string().regex(new RegExp(\"^[a-z][a-z0-9-]*[a-z0-9]$\")).describe(\"Optional — the specific operator (per AIP-9) this playbook is bound to. Narrower than targets[].\").optional(), \"created_at\": z.string().datetime({ offset: true }).optional(), \"updated_at\": z.string().datetime({ offset: true }).optional(), \"tags\": z.array(z.string().regex(new RegExp(\"^[a-z][a-z0-9-]*$\"))).default([] as never), \"metadata\": z.record(z.string(), z.any()).describe(\"Vendor extensions go under metadata.<vendor>.\").default({} as never) }).strict().and(z.any()).describe(\"Validates the YAML frontmatter portion of an AIP-12 PLAYBOOK.md overlay manifest.\")\n\nexport type PlaybookFrontmatter = z.infer<typeof playbookFrontmatterSchema>\n","import { createDoctype } from \"@agentproto/define-doctype\"\nimport { playbookFrontmatterSchema } from \"./schema.js\"\nimport type { PlaybookDefinition, PlaybookHandle } from \"./types.js\"\n\n/**\n * AIP-12 reference implementation of `definePlaybook`.\n *\n * Built on `createDoctype` so the cross-AIP invariants (id pattern,\n * description length, top-level freeze, \"definePlaybook (AIP-12): …\"\n * error prefix) run uniformly with every other AIP defineX.\n *\n * Field-level validation runs the schema-derived zod from\n * `./schema.ts` against the input. Same source of truth as the .md\n * path uses (`parsePlaybookManifest`), so a malformed TS-authored\n * definition fails with the same diagnostic as a malformed manifest.\n * Cross-field rules go in `validate(def)` after the zod check.\n *\n * Identity / description extractors detected from the JSON Schema:\n *   readIdentity: def.slug\n *   readDescription: def.title.\n */\nexport const definePlaybook = createDoctype<PlaybookDefinition, PlaybookHandle>({\n  aip: 12,\n  name: \"playbook\",\n  readIdentity: (def) => def.slug,\n  readDescription: (def) => def.title,\n  validate(def) {\n    const result = playbookFrontmatterSchema.safeParse(def)\n    if (!result.success) {\n      throw new Error(\n        `definePlaybook (AIP-12): ${result.error.issues\n          .map((i) => `${i.path.join(\".\")}: ${i.message}`)\n          .join(\"; \")}`,\n      )\n    }\n    // Cross-field binding rule (anyOf in the JSON Schema): at least\n    // one of `selector` (preferred) / legacy `targets` must be present.\n    const hasTargets = Array.isArray(def.targets) && def.targets.length > 0\n    const selector = def.selector\n    const hasSelector =\n      !!selector &&\n      typeof selector === \"object\" &&\n      Object.keys(selector).length > 0\n    if (!hasTargets && !hasSelector) {\n      throw new Error(\n        \"definePlaybook (AIP-12): a binding is required — declare `selector` (preferred) or legacy `targets`\",\n      )\n    }\n    // TODO: remaining cross-field rules (kind=block-replacement →\n    // `block` required). See @agentproto/operator's autonomy=gated rule.\n  },\n  build(def) {\n    // Default build: spread the validated definition into a fresh object.\n    // Hand-tune for nested freezing (Object.freeze on arrays/objects) and\n    // for fields that need defaults applied — see @agentproto/operator\n    // for a reference shape.\n    return { ...def } as PlaybookHandle\n  },\n})\n"]}

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import { P as PlaybookDefinition } from './types-RHBIDQcG.js';
+export { a as PlaybookHandle } from './types-RHBIDQcG.js';
+
+/**
+ * AIP-12 reference implementation of `definePlaybook`.
+ *
+ * Built on `createDoctype` so the cross-AIP invariants (id pattern,
+ * description length, top-level freeze, "definePlaybook (AIP-12): …"
+ * error prefix) run uniformly with every other AIP defineX.
+ *
+ * Field-level validation runs the schema-derived zod from
+ * `./schema.ts` against the input. Same source of truth as the .md
+ * path uses (`parsePlaybookManifest`), so a malformed TS-authored
+ * definition fails with the same diagnostic as a malformed manifest.
+ * Cross-field rules go in `validate(def)` after the zod check.
+ *
+ * Identity / description extractors detected from the JSON Schema:
+ *   readIdentity: def.slug
+ *   readDescription: def.title.
+ */
+declare const definePlaybook: (def: PlaybookDefinition) => Readonly<PlaybookDefinition>;
+
+/**
+ * @agentproto/playbook — AIP-12 PLAYBOOK.md `definePlaybook` reference impl.
+ *
+ * A markdown format for prompt-overlay fragments that ride on top of an operator's persona, plus a contract for how runtimes evolve them via reflective deltas without violating locked persona traits.
+ *
+ * Spec: https://agentproto.sh/docs/aip-12
+ *
+ * Authoring paths:
+ *   - TS:  `definePlaybook({...})` → `PlaybookHandle`
+ *   - MD:  `parsePlaybookManifest(src) → playbookFromManifest({...})` → `PlaybookHandle`
+ */
+declare const SPEC_NAME: "agentplaybook/v1";
+declare const SPEC_VERSION: "1.0.0-alpha";
+
+export { PlaybookDefinition, SPEC_NAME, SPEC_VERSION, definePlaybook };

package/dist/index.mjs

@@ -0,0 +1,14 @@
+export { definePlaybook } from './chunk-QFIVEUBZ.mjs';
+
+/**
+ * @agentproto/playbook v0.1.0-alpha
+ * AIP-12 PLAYBOOK.md `definePlaybook` reference implementation.
+ */
+
+// src/index.ts
+var SPEC_NAME = "agentplaybook/v1";
+var SPEC_VERSION = "1.0.0-alpha";
+
+export { SPEC_NAME, SPEC_VERSION };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;AAYO,IAAM,SAAA,GAAY;AAClB,IAAM,YAAA,GAAe","file":"index.mjs","sourcesContent":["/**\n * @agentproto/playbook — AIP-12 PLAYBOOK.md `definePlaybook` reference impl.\n *\n * A markdown format for prompt-overlay fragments that ride on top of an operator's persona, plus a contract for how runtimes evolve them via reflective deltas without violating locked persona traits.\n *\n * Spec: https://agentproto.sh/docs/aip-12\n *\n * Authoring paths:\n *   - TS:  `definePlaybook({...})` → `PlaybookHandle`\n *   - MD:  `parsePlaybookManifest(src) → playbookFromManifest({...})` → `PlaybookHandle`\n */\n\nexport const SPEC_NAME = \"agentplaybook/v1\" as const\nexport const SPEC_VERSION = \"1.0.0-alpha\" as const\n\nexport { definePlaybook } from \"./define-playbook.js\"\nexport type { PlaybookDefinition, PlaybookHandle } from \"./types.js\"\n"]}

package/dist/manifest/index.d.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+import { a as PlaybookHandle } from '../types-RHBIDQcG.js';
+
+/**
+ * AIP-12 PLAYBOOK.md frontmatter zod schema.
+ *
+ * Generated from `resources/aip-12/draft/PLAYBOOK.schema.json` via
+ * json-schema-to-zod. Imported by both `define-playbook.ts` (TS path
+ * validation) and `manifest/index.ts` (.md path validation) so every
+ * field-level constraint runs in both authoring paths from a single
+ * source of truth — re-run scaffold-aip to refresh after spec changes.
+ *
+ * Cross-field rules (if/then/allOf in JSON Schema) don't translate
+ * cleanly and live in `define-playbook.ts`'s `validate(def)` instead.
+ */
+
+declare const playbookFrontmatterSchema: z.ZodIntersection<z.ZodObject<{
+    schema: z.ZodLiteral<"playbooks/v1">;
+    slug: z.ZodString;
+    title: z.ZodString;
+    entry: z.ZodOptional<z.ZodString>;
+    targets: z.ZodOptional<z.ZodArray<z.ZodAny>>;
+    selector: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    kind: z.ZodDefault<z.ZodEnum<{
+        overlay: "overlay";
+        "block-replacement": "block-replacement";
+    }>>;
+    block: z.ZodOptional<z.ZodString>;
+    priority: z.ZodDefault<z.ZodNumber>;
+    lock_check: z.ZodDefault<z.ZodArray<z.ZodAny>>;
+    ttl: z.ZodOptional<z.ZodString>;
+    evidence: z.ZodArray<z.ZodAny>;
+    status: z.ZodDefault<z.ZodEnum<{
+        shadow: "shadow";
+        active: "active";
+        archived: "archived";
+    }>>;
+    supersedes: z.ZodDefault<z.ZodArray<z.ZodAny>>;
+    history: z.ZodDefault<z.ZodArray<z.ZodAny>>;
+    binds_operator: z.ZodOptional<z.ZodString>;
+    created_at: z.ZodOptional<z.ZodString>;
+    updated_at: z.ZodOptional<z.ZodString>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.core.$strict>, z.ZodAny>;
+type PlaybookFrontmatter = z.infer<typeof playbookFrontmatterSchema>;
+
+/**
+ * AIP-12 PLAYBOOK.md sidecar parser + manifest-to-handle constructor.
+ *
+ * Mirror of `@agentproto/tool/manifest` and `@agentproto/driver/manifest`:
+ * the .md provides metadata; the TS module supplies any spec-specific
+ * runtime bits (schemas, execute bodies, …) that can't live in
+ * frontmatter. Both inputs end up in `definePlaybook` so the cross-AIP
+ * invariants run uniformly.
+ *
+ *
+ * The frontmatter zod schema below was generated from
+ * `resources/aip-12/draft/PLAYBOOK.schema.json` via json-schema-to-zod.
+ * Re-run scaffold-aip to refresh after spec changes (or hand-tune
+ * any constraint the converter doesn't capture cleanly).
+ */
+
+interface PlaybookManifest {
+    frontmatter: PlaybookFrontmatter;
+    body: string;
+}
+declare function parsePlaybookManifest(source: string): PlaybookManifest;
+declare function playbookFromManifest(manifest: PlaybookManifest): PlaybookHandle;
+
+export { type PlaybookFrontmatter, type PlaybookManifest, parsePlaybookManifest, playbookFromManifest, playbookFrontmatterSchema };

package/dist/manifest/index.mjs

@@ -0,0 +1,28 @@
+import { playbookFrontmatterSchema, definePlaybook } from '../chunk-QFIVEUBZ.mjs';
+export { playbookFrontmatterSchema } from '../chunk-QFIVEUBZ.mjs';
+import matter from 'gray-matter';
+
+/**
+ * @agentproto/playbook v0.1.0-alpha
+ * AIP-12 PLAYBOOK.md `definePlaybook` reference implementation.
+ */
+function parsePlaybookManifest(source) {
+  const parsed = matter(source);
+  if (Object.keys(parsed.data).length === 0) {
+    throw new Error("parsePlaybookManifest: missing or empty frontmatter");
+  }
+  const result = playbookFrontmatterSchema.safeParse(parsed.data);
+  if (!result.success) {
+    throw new Error(
+      `parsePlaybookManifest: invalid frontmatter \u2014 ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+    );
+  }
+  return { frontmatter: result.data, body: parsed.content };
+}
+function playbookFromManifest(manifest) {
+  return definePlaybook(manifest.frontmatter);
+}
+
+export { parsePlaybookManifest, playbookFromManifest };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/manifest/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/manifest/index.ts"],"names":[],"mappings":";;;;;;;;AA8BO,SAAS,sBAAsB,MAAA,EAAkC;AACtE,EAAA,MAAM,MAAA,GAAS,OAAO,MAAM,CAAA;AAC5B,EAAA,IAAI,OAAO,IAAA,CAAK,MAAA,CAAO,IAAI,CAAA,CAAE,WAAW,CAAA,EAAG;AACzC,IAAA,MAAM,IAAI,MAAM,qDAAqD,CAAA;AAAA,EACvE;AACA,EAAA,MAAM,MAAA,GAAS,yBAAA,CAA0B,SAAA,CAAU,MAAA,CAAO,IAAI,CAAA;AAC9D,EAAA,IAAI,CAAC,OAAO,OAAA,EAAS;AACnB,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,CAAA,kDAAA,EAAgD,OAAO,KAAA,CAAM,MAAA,CAC1D,IAAI,CAAC,CAAA,KAAM,GAAG,CAAA,CAAE,IAAA,CAAK,KAAK,GAAG,CAAC,KAAK,CAAA,CAAE,OAAO,EAAE,CAAA,CAC9C,IAAA,CAAK,IAAI,CAAC,CAAA;AAAA,KACf;AAAA,EACF;AACA,EAAA,OAAO,EAAE,WAAA,EAAa,MAAA,CAAO,IAAA,EAAM,IAAA,EAAM,OAAO,OAAA,EAAQ;AAC1D;AAEO,SAAS,qBAAqB,QAAA,EAA4C;AAK/E,EAAA,OAAO,cAAA,CAAe,SAAS,WAA4C,CAAA;AAC7E","file":"index.mjs","sourcesContent":["/**\n * AIP-12 PLAYBOOK.md sidecar parser + manifest-to-handle constructor.\n *\n * Mirror of `@agentproto/tool/manifest` and `@agentproto/driver/manifest`:\n * the .md provides metadata; the TS module supplies any spec-specific\n * runtime bits (schemas, execute bodies, …) that can't live in\n * frontmatter. Both inputs end up in `definePlaybook` so the cross-AIP\n * invariants run uniformly.\n *\n *\n * The frontmatter zod schema below was generated from\n * `resources/aip-12/draft/PLAYBOOK.schema.json` via json-schema-to-zod.\n * Re-run scaffold-aip to refresh after spec changes (or hand-tune\n * any constraint the converter doesn't capture cleanly).\n */\n\nimport matter from \"gray-matter\"\nimport { playbookFrontmatterSchema, type PlaybookFrontmatter } from \"../schema.js\"\nimport { definePlaybook } from \"../define-playbook.js\"\nimport type { PlaybookDefinition, PlaybookHandle } from \"../types.js\"\n\n// Re-export so consumers can import the schema + inferred type either\n// from \"@@agentproto/playbook/manifest\" or directly from \"@@agentproto/playbook/schema\".\nexport { playbookFrontmatterSchema, type PlaybookFrontmatter }\n\nexport interface PlaybookManifest {\n  frontmatter: PlaybookFrontmatter\n  body: string\n}\n\nexport function parsePlaybookManifest(source: string): PlaybookManifest {\n  const parsed = matter(source)\n  if (Object.keys(parsed.data).length === 0) {\n    throw new Error(\"parsePlaybookManifest: missing or empty frontmatter\")\n  }\n  const result = playbookFrontmatterSchema.safeParse(parsed.data)\n  if (!result.success) {\n    throw new Error(\n      `parsePlaybookManifest: invalid frontmatter — ${result.error.issues\n        .map((i) => `${i.path.join(\".\")}: ${i.message}`)\n        .join(\"; \")}`,\n    )\n  }\n  return { frontmatter: result.data, body: parsed.content }\n}\n\nexport function playbookFromManifest(manifest: PlaybookManifest): PlaybookHandle {\n  // The zod-validated frontmatter is structurally compatible with\n  // PlaybookDefinition; the cast pins the typing once the manifest\n  // schema and the TS interface diverge (e.g. handle has frozen fields\n  // a literal config doesn't carry yet).\n  return definePlaybook(manifest.frontmatter as unknown as PlaybookDefinition)\n}\n"]}

package/dist/types-RHBIDQcG.d.ts

@@ -0,0 +1,129 @@
+/**
+ * AIP-12 PlaybookDefinition + PlaybookHandle.
+ *
+ * `PlaybookDefinition` was generated from
+ * `resources/aip-12/draft/PLAYBOOK.schema.json` via json-schema-to-typescript.
+ * `PlaybookHandle` is the readonly view of the same shape; tighten it
+ * by hand for fields that get defaults applied in build().
+ */
+/**
+ * Validates the YAML frontmatter portion of an AIP-12 PLAYBOOK.md overlay manifest.
+ */
+type PlaybookDefinition = {
+    [k: string]: unknown;
+} & {
+    schema: "playbooks/v1";
+    slug: string;
+    title: string;
+    /**
+     * Optional path to the entry file exposing definePlaybook. Defaults to playbook.ts.
+     */
+    entry?: string;
+    /**
+     * @deprecated In favor of `selector`. Legacy axis-ambiguous binding —
+     * runtimes compile it into a selector (see AIP-12 §Selector binding).
+     * Kept valid forever. At least one of `targets` / `selector` is required.
+     *
+     * @minItems 1
+     */
+    targets?: [Target, ...Target[]];
+    /**
+     * Typed attachment binding evaluated against the subject's dimensions.
+     * Short form: axis → ref | ref[] (AND across keys, OR within a list).
+     * Long form: `allOf` / `anyOf` lists of `{axis, anyOf}` terms.
+     * Wins over `targets`/`binds_operator` when present.
+     */
+    selector?: SelectorFrontmatter;
+    kind: "overlay" | "block-replacement";
+    /**
+     * Required when kind is 'block-replacement' — the named persona block to swap.
+     */
+    block?: string;
+    priority?: number;
+    /**
+     * Locked persona traits this overlay MUST NOT modify. Author intent — runtime enforces independently.
+     */
+    lock_check: TraitId[];
+    /**
+     * Optional ISO 8601 duration. Auto-archives at updated_at + ttl.
+     */
+    ttl?: string;
+    /**
+     * @minItems 1
+     */
+    evidence: [EvidenceItem, ...EvidenceItem[]];
+    status: "shadow" | "active" | "archived";
+    supersedes?: Slug[];
+    /**
+     * Append-only audit trail of deltas, promotions, and archivals applied to this playbook.
+     */
+    history?: HistoryEntry[];
+    /**
+     * @deprecated As a binding — provenance only when `selector` is present.
+     * Without `selector`, runtimes compile it like a kind 'operator' target
+     * (matches BOTH identity and role axes).
+     */
+    binds_operator?: string;
+    created_at?: string;
+    updated_at?: string;
+    tags?: string[];
+    /**
+     * Vendor extensions go under metadata.<vendor>.
+     */
+    metadata?: {
+        [k: string]: unknown;
+    };
+};
+type TraitId = string;
+type Slug = string;
+/** Axis value slug, prefixed ref (e.g. 'role/sales-rep'), or '*' (any present value). */
+type SelectorRef = string;
+interface SelectorTermFrontmatter {
+    axis: string;
+    /**
+     * @minItems 1
+     */
+    anyOf: [SelectorRef, ...SelectorRef[]];
+}
+/**
+ * Short form: axis keys → ref | ref[]. Long form: explicit `allOf` /
+ * `anyOf` term lists for OR across axes.
+ */
+type SelectorFrontmatter = {
+    allOf?: SelectorTermFrontmatter[];
+    anyOf?: SelectorTermFrontmatter[];
+} & {
+    [axis: string]: SelectorRef | SelectorRef[] | SelectorTermFrontmatter[] | undefined;
+};
+interface Target {
+    kind: "operator" | "role" | "skill" | "runtime";
+    /**
+     * Slug, glob, or qualified path. Examples: 'role/companion', 'operator/alice', 'skill/research', 'operator/*'.
+     */
+    ref: string;
+}
+interface EvidenceItem {
+    kind: "run" | "conversation" | "work-item" | "reflection" | "human";
+    ref: string;
+    note?: string;
+}
+interface HistoryEntry {
+    at: string;
+    kind: "created" | "delta" | "promoted" | "archived" | "superseded" | "lock-violation";
+    summary: string;
+    /**
+     * Pointer to the run/reflection/governance ticket that produced this entry.
+     */
+    source?: string;
+    /**
+     * User id, agent id, or system identifier responsible for the entry.
+     */
+    by?: string;
+    /**
+     * For kind='promoted', the gate that passed.
+     */
+    gate?: "a-b" | "scorer" | "human" | "governance";
+}
+type PlaybookHandle = Readonly<PlaybookDefinition>;
+
+export type { PlaybookDefinition as P, PlaybookHandle as a };

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@agentproto/playbook",
+  "version": "0.1.0-alpha.1",
+  "description": "@agentproto/playbook — AIP-12 PLAYBOOK.md reference implementation. A markdown format for prompt-overlay fragments that ride on top of an operator's persona, plus a contract for how runtimes evolve them via reflective deltas without violating locked persona traits.",
+  "keywords": [
+    "agentproto",
+    "aip-12",
+    "playbook",
+    "definePlaybook",
+    "open-standard",
+    "agentic"
+  ],
+  "homepage": "https://agentproto.sh/docs/aip-12",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentproto/ts",
+    "directory": "packages/playbook"
+  },
+  "bugs": {
+    "url": "https://github.com/agentproto/ts/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./manifest": {
+      "types": "./dist/manifest/index.d.ts",
+      "import": "./dist/manifest/index.mjs",
+      "default": "./dist/manifest/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "zod": "^4.4.3",
+    "@agentproto/define-doctype": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@agentproto/tooling": "0.1.0-alpha.0"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  }
+}