Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 65 additions & 0 deletions .github/workflows/contract.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# SPDX-FileCopyrightText: 2026 Igor Santos
# SPDX-License-Identifier: Apache-2.0
#
# The contract with the playbook binary. intents.json lists the intents the
# plugin relies on. This job downloads the latest released playbook binary,
# checks its SHA256SUMS entry and compares `playbook tools map --json` with the
# list. A listed intent the binary lacks is a warning, and a failure only when
# intents.json marks it required. A daily run catches a binary release that
# drops an intent.

name: contract

on:
pull_request:
merge_group:
workflow_dispatch:
schedule:
- cron: "41 6 * * *"

permissions:
contents: read

concurrency:
group: contract-${{ github.ref }}
cancel-in-progress: true

jobs:
contract:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
with:
egress-policy: block
allowed-endpoints: >
api.github.com:443
github.com:443
objects.githubusercontent.com:443
release-assets.githubusercontent.com:443

- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

- name: Lint the script
run: shellcheck --severity=warning scripts/*.sh

- name: Download the latest playbook release
env:
GH_TOKEN: ${{ github.token }}
run: |
set -euo pipefail
tag="$(gh release list --repo pragmatic-engineer/playbook --limit 100 --json tagName,isDraft,isPrerelease \
--jq '[.[] | select(.isDraft == false and .isPrerelease == false) | .tagName | select(test("^v[0-9]+\\.[0-9]+\\.[0-9]+$"))] | first // empty')"
[ -n "$tag" ] || { echo "::error::no playbook release found"; exit 1; }
asset="playbook-${tag#v}-x86_64-unknown-linux-musl"
mkdir -p "$RUNNER_TEMP/playbook"
gh release download "$tag" --repo pragmatic-engineer/playbook \
--pattern "$asset" --pattern SHA256SUMS --dir "$RUNNER_TEMP/playbook"
(cd "$RUNNER_TEMP/playbook" && grep " ${asset}\$" SHA256SUMS | sha256sum -c -)
chmod +x "$RUNNER_TEMP/playbook/$asset"
echo "PLAYBOOK_BIN=$RUNNER_TEMP/playbook/$asset" >> "$GITHUB_ENV"

- name: Compare intents.json with the tool map
run: scripts/check-intents.sh "$PLAYBOOK_BIN"
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,10 @@ shell/check-marketplace.sh

`shell/check-marketplace.sh` keeps installs keyless: a plugin source is either a path in this repository, or an https url or archive, and an archive carries a sha256.

## The binary contract

`intents.json` lists the tool intents the plugin relies on, named like the entries of `playbook tools map`. The `contract` workflow downloads the latest released playbook binary and compares its tool map with the list. A missing intent is a warning, and a failure only for an entry marked `required`. Run it by hand with `scripts/check-intents.sh [path-to-playbook]`.

## The hooks plugin pin

`playbook-hooks` is versioned with the playbook binary. Its entry points at the release archive `playbook-hooks-plugin-<version>.zip` in `pragmatic-engineer/playbook` and pins its sha256. The `pin-hooks` workflow runs daily at 06:37 UTC and can be started by hand. If a newer playbook release carries the archive, it runs `shell/bump-marketplace.sh`, which downloads the archive, verifies its build provenance attestation and writes the URL and the sha256 of those exact bytes. The workflow commits the change to a `bump/hooks-v<version>` branch through the GitHub API, opens a pull request, approves the held checks run, waits for it to pass and squash merges. It uses only the built-in `GITHUB_TOKEN`. Don't edit the pin by hand.
Expand Down
194 changes: 194 additions & 0 deletions intents.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,194 @@
[
{
"intent": "add-glossary-term",
"required": false
},
{
"intent": "atlassian-check",
"required": false
},
{
"intent": "checkpoint",
"required": false
},
{
"intent": "commit-prepare",
"required": false
},
{
"intent": "commit-run",
"required": false
},
{
"intent": "config-get",
"required": false
},
{
"intent": "effort-choose",
"required": false
},
{
"intent": "effort-resolve",
"required": false
},
{
"intent": "gate-check",
"required": false
},
{
"intent": "gate-record",
"required": false
},
{
"intent": "gate-snapshot",
"required": false
},
{
"intent": "handoff-check",
"required": false
},
{
"intent": "handoff-facts",
"required": false
},
{
"intent": "handoff-save",
"required": false
},
{
"intent": "handoff-show",
"required": false
},
{
"intent": "handoff-template",
"required": false
},
{
"intent": "implement-dir",
"required": false
},
{
"intent": "learn-collect",
"required": false
},
{
"intent": "learn-preflight",
"required": false
},
{
"intent": "list-plans",
"required": false
},
{
"intent": "memory-context",
"required": false
},
{
"intent": "memory-rebuild",
"required": false
},
{
"intent": "mode-status",
"required": false
},
{
"intent": "next-adr-number",
"required": false
},
{
"intent": "plans-dir",
"required": false
},
{
"intent": "pr-ci-wait",
"required": false
},
{
"intent": "pr-comments",
"required": false
},
{
"intent": "pr-create",
"required": false
},
{
"intent": "pr-land-wait",
"required": false
},
{
"intent": "pr-merge",
"required": false
},
{
"intent": "pr-prepare",
"required": false
},
{
"intent": "pr-reply",
"required": false
},
{
"intent": "pr-review-triage",
"required": false
},
{
"intent": "pr-rules",
"required": false
},
{
"intent": "pr-stack",
"required": false
},
{
"intent": "review-checks",
"required": false
},
{
"intent": "review-prepare",
"required": false
},
{
"intent": "review-size",
"required": false
},
{
"intent": "review-triage-merge",
"required": false
},
{
"intent": "review-worktree-setup",
"required": false
},
{
"intent": "review-worktree-teardown",
"required": false
},
{
"intent": "route-model",
"required": false
},
{
"intent": "run-mode",
"required": false
},
{
"intent": "segment-branch",
"required": false
},
{
"intent": "segment-resplit",
"required": false
},
{
"intent": "segment-size",
"required": false
},
{
"intent": "work-unit-briefs",
"required": false
},
{
"intent": "worktrees-dir",
"required": false
}
]
51 changes: 51 additions & 0 deletions scripts/check-intents.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
#!/usr/bin/env bash
# SPDX-FileCopyrightText: 2026 Igor Santos
# SPDX-License-Identifier: Apache-2.0
#
# check-intents.sh: the contract between this repo and the playbook binary.
#
# intents.json lists the intents the skills, commands and agents rely on, each
# named like a tool map entry (for example `pr-reply`). The binary prints its
# own list with `playbook tools map --json`. This script:
# 1. fails when intents.json is not valid: sorted, unique ids in kebab case
# with a boolean `required` field;
# 2. when a playbook binary is given, warns about each listed intent the
# binary does not offer, and fails only for an intent marked required.
#
# Usage: check-intents.sh [path-to-playbook-binary]
set -euo pipefail

ROOT="$(cd "$(dirname "$0")/.." && pwd)"
FILE="$ROOT/intents.json"
fail=0

jq -e 'type == "array" and length > 0' "$FILE" >/dev/null || { echo "FAIL intents.json must be a non-empty array"; exit 1; }
if ! jq -e 'all(.[]; (.intent | type == "string" and test("^[a-z][a-z0-9]*(-[a-z0-9]+)*$")) and (.required | type == "boolean"))' "$FILE" >/dev/null; then
echo "FAIL every entry needs a kebab-case intent and a boolean required"; exit 1
fi
if [ "$(jq -r '[.[].intent] | . == (sort | unique)' "$FILE")" != "true" ]; then
echo "FAIL intents must be sorted and unique"; exit 1
fi
echo "PASS intents.json lists $(jq length "$FILE") intents"

bin="${1:-}"
if [ -z "$bin" ]; then
echo "SKIP no playbook binary given, offered intents not compared"
exit 0
fi
if ! map="$("$bin" tools map --json 2>/dev/null)" || ! printf '%s' "$map" | jq -e 'type == "array"' >/dev/null 2>&1; then
echo "WARN $("$bin" --version 2>&1 | head -1) has no tools map yet, offered intents not compared"
exit 0
fi
offered="$(printf '%s' "$map" | jq -r '.[].intent' | sort -u)"
while IFS=$'\t' read -r intent required; do
if printf '%s\n' "$offered" | grep -qx "$intent"; then
continue
fi
if [ "$required" = "true" ]; then
echo "FAIL required intent $intent is not in the tool map"; fail=1
else
echo "WARN intent $intent is not in the tool map"
fi
done < <(jq -r '.[] | [.intent, (.required | tostring)] | @tsv' "$FILE")
exit "$fail"
Loading