{"_id":"@eforge-build/eforge-playbooks","_rev":"2-10efd150e84915702b877fa9a566e34f","name":"@eforge-build/eforge-playbooks","dist-tags":{"latest":"0.8.1"},"versions":{"0.8.0":{"name":"@eforge-build/eforge-playbooks","version":"0.8.0","keywords":["eforge","extension","playbooks"],"author":{"name":"Schaake Solutions LLC"},"license":"Apache-2.0","_id":"@eforge-build/eforge-playbooks@0.8.0","maintainers":[{"name":"schaakesolutions","email":"mark@schaake.solutions"}],"homepage":"https://eforge.build","bugs":{"url":"https://github.com/eforge-build/eforge/issues"},"dist":{"shasum":"18326d1b2291fc03f4b9bc06659ab50f1a5bc598","tarball":"https://registry.npmjs.org/@eforge-build/eforge-playbooks/-/eforge-playbooks-0.8.0.tgz","fileCount":5,"integrity":"sha512-YaMOLwyvXR/HrP8QXglYcYZO6pyvkz82JrFWxk3nt56J76t5SqeY/su2KMtIweGGJ6xkLfYXpScEAThOLRqEgA==","signatures":[{"sig":"MEYCIQD63waQ1IzF1MqWXlKbu0qe2m1JnAacZ4f1NFuhDpyLWAIhALhLyA/P5P9P7k3JdEX1z1RjwpL2iQclN9XgLC5ZG5dv","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":693350},"type":"module","_from":"file:eforge-build-eforge-playbooks-0.8.0.tgz","types":"./dist/index.d.ts","eforge":{"extension":{"name":"eforge-playbooks","entrypoint":"./dist/index.js","capabilities":[{"name":"eforge.playbooks.management","version":"1.0.0"},{"name":"eforge.playbooks.run","version":"1.0.0"}],"dependencies":{"optional":[{"name":"eforge-plan","capabilities":[{"name":"eforge.plan.planning-workstation","version":">=1.0.0"}]}]}}},"engines":{"node":">=22"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./package.json":"./package.json"},"scripts":{"build":"tsup","type-check":"tsc --noEmit"},"_npmUser":{"name":"schaakesolutions","email":"mark@schaake.solutions"},"_resolved":"/private/var/folders/y7/kqt_cjxn2sl5d991wn35nbfr0000gn/T/e33b397bb68f2dca09934c7ba82a4178/eforge-build-eforge-playbooks-0.8.0.tgz","_integrity":"sha512-YaMOLwyvXR/HrP8QXglYcYZO6pyvkz82JrFWxk3nt56J76t5SqeY/su2KMtIweGGJ6xkLfYXpScEAThOLRqEgA==","repository":{"url":"git+https://github.com/eforge-build/eforge.git","type":"git"},"_npmVersion":"11.9.0","description":"First-party eforge playbooks extension with scoped management actions, planning-mode handoff metadata, and autonomous queue handoff.","directories":{},"_nodeVersion":"24.14.0","dependencies":{"zod":"^4.4.3","yaml":"^2.9.0","@eforge-build/input":"0.8.0","@eforge-build/scopes":"0.8.0","@eforge-build/extension-sdk":"0.8.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","typescript":"^6.0.3","@types/node":"^26.1.1"},"_npmOperationalInternal":{"tmp":"tmp/eforge-playbooks_0.8.0_1783877864803_0.9773657662429005","host":"s3://npm-registry-packages-npm-production"}},"0.8.1":{"name":"@eforge-build/eforge-playbooks","version":"0.8.1","description":"First-party eforge playbooks extension with scoped management actions, planning-mode handoff metadata, and autonomous queue handoff.","license":"Apache-2.0","type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./package.json":"./package.json"},"types":"./dist/index.d.ts","engines":{"node":">=22"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/eforge-build/eforge.git"},"homepage":"https://eforge.build","keywords":["eforge","extension","playbooks"],"dependencies":{"yaml":"^2.9.0","zod":"^4.4.3","@eforge-build/input":"0.8.1","@eforge-build/extension-sdk":"0.8.1","@eforge-build/scopes":"0.8.1"},"devDependencies":{"@types/node":"^26.1.1","tsup":"^8.5.1","typescript":"^6.0.3"},"author":{"name":"Schaake Solutions LLC"},"eforge":{"extension":{"name":"eforge-playbooks","entrypoint":"./dist/index.js","capabilities":[{"name":"eforge.playbooks.management","version":"1.0.0"},{"name":"eforge.playbooks.run","version":"1.0.0"}],"dependencies":{"optional":[{"name":"eforge-plan","capabilities":[{"name":"eforge.plan.planning-workstation","version":">=1.0.0"}]}]}}},"scripts":{"build":"tsup","type-check":"tsc --noEmit"},"_id":"@eforge-build/eforge-playbooks@0.8.1","bugs":{"url":"https://github.com/eforge-build/eforge/issues"},"_integrity":"sha512-o/OSIgbsqXvGVuOCKjGyFKiD4FRT34XyUxnh7NmiWGrcfOOyLCqcPWUUk5H40B3cvqbGUeDIw+TXMul7+dJssg==","_resolved":"/tmp/7df4f2240c310233437e1f938fe5794a/eforge-build-eforge-playbooks-0.8.1.tgz","_from":"file:eforge-build-eforge-playbooks-0.8.1.tgz","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-o/OSIgbsqXvGVuOCKjGyFKiD4FRT34XyUxnh7NmiWGrcfOOyLCqcPWUUk5H40B3cvqbGUeDIw+TXMul7+dJssg==","shasum":"1b172d38f1ed8e124c4a038f7fe87384c550dd1f","tarball":"https://registry.npmjs.org/@eforge-build/eforge-playbooks/-/eforge-playbooks-0.8.1.tgz","fileCount":5,"unpackedSize":693350,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@eforge-build%2feforge-playbooks@0.8.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCaSFB32QIjSUhwXExZkh/qdHUJJX6OX6BRZHVZ3v3vQAIgZ2dpY9PowRWiu/nNdRVGk20mVaXodnQoHJzLApzeF/M="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:e655e6dc-47bf-4dba-8ada-ad416a5d69bb"}},"directories":{},"maintainers":[{"name":"schaakesolutions","email":"mark@schaake.solutions"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/eforge-playbooks_0.8.1_1783884311939_0.22014274319694604"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-12T17:37:44.666Z","modified":"2026-07-12T19:25:12.450Z","0.8.0":"2026-07-12T17:37:44.973Z","0.8.1":"2026-07-12T19:25:12.103Z"},"bugs":{"url":"https://github.com/eforge-build/eforge/issues"},"author":{"name":"Schaake Solutions LLC"},"license":"Apache-2.0","homepage":"https://eforge.build","keywords":["eforge","extension","playbooks"],"repository":{"type":"git","url":"git+https://github.com/eforge-build/eforge.git"},"description":"First-party eforge playbooks extension with scoped management actions, planning-mode handoff metadata, and autonomous queue handoff.","maintainers":[{"name":"schaakesolutions","email":"mark@schaake.solutions"}],"readme":"# eforge-playbooks Extension\n\n`eforge-playbooks` is the first-party extension that owns reusable playbook management and playbook execution handoff. It exposes playbook inventory, CRUD-style management, validation, scope moves, planning-mode handoff metadata, and autonomous build-queue enqueue through generic extension actions.\n\nThe extension owns its playbook parser, serializer, validation, scope-aware storage, compiler, and planning-seed extraction locally. `@eforge-build/input` remains a dependency only for domain-neutral acceptance-criteria quality helpers. The extension does not add direct daemon playbook routes, Console core sections, queue internals, or host-specific command implementations. Hosts discover and invoke the extension through normal extension action, integration-command, capability, and Console contribution metadata.\n\n## Trust model\n\nExtensions run as project-team code. Install and enable `eforge-playbooks` only in repositories where you trust the extension source and the team-maintained playbook content.\n\n`eforge-playbooks` is not a sandbox boundary. Actions can read and write playbook files in project-local, project-team, and user scopes, and `run-playbook` can enqueue autonomous builds through the generic build queue. Review extension changes with the same care as build tooling, scripts, or other automation that runs in the repository.\n\nPlaybooks are reusable build-input artifacts. Treat them as executable workflow intent: a playbook can define normalized build source, profile defaults, post-merge commands, and a planning or autonomous mode.\n\n## Install and manage\n\n`eforge-playbooks` is published as the first-party npm package `@eforge-build/eforge-playbooks`. The package declares `eforge.extension.name: \"eforge-playbooks\"` and loads from the compiled runtime entrypoint `./dist/index.js`.\n\n```bash\n# Install from npm into the default local scope (.eforge/extensions/)\neforge extension install @eforge-build/eforge-playbooks\n\n# Install from a local package directory or packed tarball after building\neforge extension install ./eforge/extensions/eforge-playbooks\neforge extension install ./eforge/extensions/eforge-playbooks/eforge-build-eforge-playbooks-<version>.tgz\n\n# Install into the project/team scope and trust the reviewed artifact\neforge extension install @eforge-build/eforge-playbooks --scope project --trust\n```\n\nScope behavior follows normal extension management rules:\n\n- `local` (default) installs under `.eforge/extensions/` and loads without a project/team trust record.\n- `project` installs under `eforge/extensions/`; each user must inspect and run `eforge extension trust eforge-playbooks`, or install/update with `--trust`, before it loads.\n- `user` installs under the user eforge config directory and is trusted for that user.\n\nCommon lifecycle commands:\n\n```bash\neforge extension validate eforge-playbooks\neforge extension trust eforge-playbooks\neforge extension reload\neforge extension show eforge-playbooks\n\neforge extension update eforge-playbooks\neforge extension update eforge-playbooks --version latest\neforge extension remove eforge-playbooks\n```\n\nThe npm artifact contains the compiled runtime in `dist/`, `README.md`, `LICENSE`, and package metadata. Tests and development config are not part of the runtime artifact.\n\n## Declared capabilities\n\nThe package manifest declares two stable first-party capabilities:\n\n- `eforge.playbooks.management` version `1.0.0` — the extension owns playbook inventory, validation, copy, save, promote, and demote actions.\n- `eforge.playbooks.run` version `1.0.0` — the extension owns playbook execution handoff for autonomous and planning-mode playbooks.\n\nThe extension declares an optional dependency on provider `eforge-plan` with capability `eforge.plan.planning-workstation` satisfying `>=1.0.0`. Planning-mode playbooks use that generic planning workstation capability when available, but the extension still loads without it and returns diagnostics instead of enqueueing a build.\n\n## Extension-owned playbook domain\n\n`eforge-playbooks` is the implementation owner for playbook domain behavior:\n\n- `model.ts` defines the playbook frontmatter and body model, schemas, parsing, serialization, validation, and mode mismatch errors.\n- `storage-core.ts` resolves named-set storage locations, lists and loads playbooks, writes scoped files, and performs copy, promote, and demote moves while preserving existing shadowing behavior.\n- `compile.ts` converts autonomous playbooks to normalized build source and planning playbooks to JSON-safe planning seeds.\n\nThe package entrypoint exposes the extension contribution surface, not these domain helpers as host-facing APIs. Runtime imports from `@eforge-build/input` are limited to `analyzeAcceptanceCriteria`, `analyzeAcceptanceCriteriaInBody`, and `formatAcDiagnostics`.\n\n## Actions\n\nRegistered action IDs are local to the extension and are exposed with effective IDs such as `eforge-playbooks:run-playbook`. Integration commands mirror the same eight local IDs so hosts can discover the same capabilities through command metadata.\n\n| Action | Purpose | Side effects |\n| --- | --- | --- |\n| `list-playbooks` | List playbooks from project-local, project-team, and user scopes. Supports optional `scope`, `mode`, and `includeShadowed`; shadowed entries are included by default. | `local-read` |\n| `show-playbook` | Show the highest-precedence playbook by name, or an exact scoped copy when `scope` is supplied. | `local-read` |\n| `save-playbook` | Save a playbook from raw Markdown, nested `{ playbook: { frontmatter, body } }`, or flattened fields. Defaults `overwrite` to `true` and validates acceptance criteria before writing. | `local-write` |\n| `validate-playbook` | Validate raw playbook Markdown without filesystem writes. This preserves raw validation semantics and does not run the save/run acceptance-criteria quality gate. | `none` |\n| `copy-playbook` | Copy a playbook to another scope, updating frontmatter `scope`; `overwrite` defaults to `true` (set `false` to reject existing destinations). | `local-read`, `local-write` |\n| `promote-playbook` | Move a playbook from `project-local` to `project-team`; `overwrite` defaults to `true` (set `false` to reject existing destinations). | `local-write` |\n| `demote-playbook` | Move a playbook from `project-team` to `project-local`; `overwrite` defaults to `true` (set `false` to reject existing destinations). | `local-write` |\n| `run-playbook` | Resolve and run a playbook. Autonomous playbooks compile to normalized build source and enqueue through the generic build queue. Planning-mode playbooks return eforge-plan planning entry metadata or diagnostics and never enqueue. | `local-read`, `daemon-state`, `build-queue` |\n\nCommon action input forms:\n\n```json\n{ \"scope\": \"project-team\", \"mode\": \"autonomous\", \"includeShadowed\": false }\n```\n\n```json\n{ \"name\": \"weekly-maintenance\", \"scope\": \"project-local\" }\n```\n\n```json\n{\n  \"scope\": \"project-team\",\n  \"playbook\": {\n    \"frontmatter\": {\n      \"name\": \"weekly-maintenance\",\n      \"description\": \"Run routine maintenance\",\n      \"mode\": \"autonomous\",\n      \"profile\": \"excursion\"\n    },\n    \"body\": {\n      \"goal\": \"Update routine maintenance checks.\",\n      \"acceptanceCriteria\": \"Maintenance checks are documented and pass.\"\n    }\n  },\n  \"overwrite\": true\n}\n```\n\n```json\n{\n  \"name\": \"weekly-maintenance\",\n  \"mode\": \"autonomous\",\n  \"profile\": \"excursion\",\n  \"afterQueueId\": \"session_123\",\n  \"landingAction\": \"pr\",\n  \"landingAutoMerge\": false\n}\n```\n\n`save-playbook` accepts exactly one payload shape: `raw` Markdown, the nested `{ \"playbook\": { \"frontmatter\", \"body\" } }` form, or flattened playbook fields (`name`, `description`, `mode`, `profile`, `postMerge`, `goal`, `outOfScope`, `acceptanceCriteria`, and `plannerNotes`). When a top-level `name` is supplied, it must match the parsed or structured playbook name. `run-playbook` rejects a supplied `mode` when it differs from the playbook frontmatter mode.\n\n## Planning-mode behavior\n\nA playbook whose frontmatter mode is `planning` is an investigation-first handoff. `run-playbook` converts the playbook to a JSON-safe planning seed and checks:\n\n```text\neforge.plan.planning-workstation >=1.0.0\n```\n\nWhen the optional `eforge-plan` provider is available, the action returns `kind: \"requires-agent\"` with planning entry metadata for `eforge-plan:open-planning-entry`, workstation `eforge-plan:planning-workstation`, and workstation URL `/console/workstations/eforge-plan%3Aplanning-workstation`.\n\nWhen the provider is unavailable, the action returns `kind: \"planning-unavailable\"` with diagnostics and guidance to install, trust, and reload `eforge-plan`. It does not create session plans, enqueue PRDs, or call the build queue.\n\nPlanning seed output is JSON-safe: section maps are projected to plain objects, and undefined values are omitted.\n\n## Autonomous queue handoff\n\nA playbook whose frontmatter mode is `autonomous` compiles to normalized build source using the extension-local compiler. Before enqueueing, `run-playbook` runs the existing domain-neutral acceptance-criteria quality gate from `@eforge-build/input` against the compiled source. Invalid criteria fail as user-visible invalid input.\n\nAutonomous handoff uses only the generic build queue API:\n\n```ts\nctx.buildQueue.enqueue({\n  source,\n  profile,\n  postMerge,\n  afterQueueId,\n  landingAction,\n  landingAutoMerge,\n});\n```\n\n`profile` defaults to the compiled playbook profile when the action input does not override it. `postMerge`, `afterQueueId`, `landingAction`, and `landingAutoMerge` are passed through to generic queue validation. Queue validation failures remain invalid-input action failures; unexpected daemon/runtime enqueue errors propagate as handler errors.\n\nThe success result is `kind: \"enqueued\"` and aliases `id` to `sessionId`.\n\n## Console contribution\n\n`eforge-playbooks` contributes playbook management declaratively through extension Console metadata rather than a core Console section or a packaged workstation bundle. The contribution includes a Markdown summary plus action controls for listing, showing, saving, validating, copying, promoting, demoting, and running playbooks.\n\nConsole action bindings reference the canonical effective action IDs owned by this extension, such as `eforge-playbooks:list-playbooks` and `eforge-playbooks:run-playbook`.\n\n## Storage model\n\nPlaybook storage is resolved by the extension-local storage layer through `@eforge-build/scopes` named-set APIs with the daemon-provided project root and config directory:\n\n- project-local playbooks live under `.eforge/playbooks/`;\n- project-team playbooks live under `eforge/playbooks/`;\n- user playbooks live under the user's eforge config directory.\n\nHigher-precedence scopes shadow lower-precedence copies with the same playbook name. `show-playbook` without a scope returns the highest-precedence copy; exact-scope actions fail with a not-found user error when that scope lacks the requested playbook.\n\nThe extension imports public `@eforge-build/extension-sdk` APIs, `@eforge-build/scopes` named-set helpers, and only the domain-neutral acceptance-criteria helpers from `@eforge-build/input` for runtime behavior. It does not import playbook-specific input symbols, the legacy playbook workflow adapter, or use `builtin:playbooks`.\n","readmeFilename":"README.md"}