From c54a1162e3580061906e94ccbe84c64e1784f9a5 Mon Sep 17 00:00:00 2001 From: Rody Vilchez <102562850+R0SEWT@users.noreply.github.com> Date: Sat, 26 Sep 2026 08:26:58 -0500 Subject: [PATCH 1/3] docs: define capability versions, consumer pins and rollback Co-Authored-By: Claude Opus 5.5 --- README.md | 7 +++ docs/capability-versioning.md | 92 +++++++++++++++++++++++++++++++++++ 2 files changed, 99 insertions(+) create mode 100644 docs/capability-versioning.md diff --git a/README.md b/README.md index 027c2e6..b3c7060 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,13 @@ Or add to `~/.claude/settings.json`: Restart the session for Claude Code to load the plugin. To use the script standalone, set `PROJECT_KIT_HOME` to this repo (defaults to `~/Code/project-kit`). +## Capability versioning + +The [capability versioning contract](docs/capability-versioning.md) defines how +skills, playbooks and runbooks are released, pinned and upgraded per repository. +The first pilot is manual; a package manager and generated lockfile are not +implemented by this contract. + ## Requirements `bd` (beads) and `uv` on PATH for those steps; the script prints a hint and continues if either is missing. diff --git a/docs/capability-versioning.md b/docs/capability-versioning.md new file mode 100644 index 0000000..3b38404 --- /dev/null +++ b/docs/capability-versioning.md @@ -0,0 +1,92 @@ +# Versioning capabilities + +Status: initial manual contract for review. There is no package resolver, +installer or automatic lockfile generator in project-kit yet. Git is the source +of immutable revisions; this contract can be exercised before building a CLI. + +## Units and responsibilities + +| Artifact | Responsibility | Example | +| --- | --- | --- | +| Skill | Agent capability, supporting scripts and validation cases | Diagnose a notebook environment | +| Playbook | Compose capabilities with decisions and expected deliverables | Bootstrap and validate a notebook project | +| Runbook | Repeat an operation with preconditions, checks and recovery | Repair or remove a registered kernel | + +A capability release versions the files that must work together. List their +paths explicitly; do not version a prompt independently of scripts it invokes. +Keep the native skill layout expected by the agent host. This document does not +introduce a replacement SKILL.md format. + +## Ownership boundary + +- The capability owns reusable instructions, scripts, examples and checks. +- The consuming repository owns project paths, scientific assumptions, data + references, thresholds and local overrides. +- Secrets belong in the environment or an appropriate secret store, never in + the capability record. + +Provide explicit configuration inputs rather than editing installed source. +When a local fork is necessary, record its own origin and revision. Never label +modified code as an unchanged upstream release. + +## Release contract + +Each candidate records: capability ID; version; purpose and activation scope; +input/output contract; required tools and versions; supported agent hosts; +dependency revisions; managed file paths; side effects and permissions; +validation cases; migration steps; rollback procedure; and release notes. + +Use SemVer for declared releases: + +- PATCH: corrections that preserve observable inputs, outputs and required steps. +- MINOR: compatible optional behavior or new optional inputs. +- MAJOR: changed or removed inputs/outputs, new mandatory dependencies or + permissions, or incompatible required workflow steps. + +For 0.x releases, explicitly describe compatibility even when the version does +not signal stability. A small wording change can alter agent behavior: classify +the observed contract impact, not the number of edited lines. Record candidate +versions as prereleases and validate them before advertising a stable release. + +## Pinning in a consumer repo + +Maintain `docs/capabilities.md` as a human-reviewed inventory initially. For each +capability record the following fields: + +| Field | Required value | +| --- | --- | +| ID and version | Capability name and declared release | +| Source | Repository URL and source subdirectory | +| Revision | Full immutable Git commit SHA; a branch or tag alone is insufficient | +| Installed files | Exact destination paths and file hashes | +| Dependencies | Capability IDs with tested exact revisions | +| Configuration | Local non-secret configuration paths | +| Validation | Evidence record and consumer commit tested | + +Playbooks reference capability IDs from this inventory. Resolve every ID to one +installed revision and reject missing dependencies or incompatible requirements +before running. For the pilot, perform this review manually; do not imply that +the repository already enforces it automatically. + +## Update and rollback + +1. Review candidate release notes, source diff and changed dependencies. +2. In a lab worktree, compare installed hashes with the inventory. Stop if local + changes are unexplained; preserve and reconcile them before replacement. +3. Update only the declared managed files. Preserve project configuration and + inspect any dependency or permission expansion. +4. Execute baseline, candidate and recovery cases. Record actual source revision + loaded by the agent and any host reload needed. +5. Submit files, inventory and evidence in the same PR. Consumers upgrade + independently; publishing a release does not upgrade all repositories. +6. To roll back, restore the previous file set and inventory together, then + execute the runbook's environment recovery and repeat checks. Never assume + a Git revert undoes external side effects. + +## Promotion criterion + +Before automating packaging, demonstrate one capability in two consumer repos: +pin both to the initial revision, update one to a candidate, verify the other +remains unchanged, and roll the first back successfully. A release decision must +include evidence from this exercise. A generated manifest or lockfile is future +automation of this contract, not a deliverable claimed by this change. From 77a6fdf716dde3b5d2a582e49879ba556c7d5810 Mon Sep 17 00:00:00 2001 From: Rody Vilchez <102562850+R0SEWT@users.noreply.github.com> Date: Sat, 26 Sep 2026 08:36:18 -0500 Subject: [PATCH 2/3] docs: tie capability releases to the plugin version Co-Authored-By: Claude Opus 5.5 --- docs/capability-versioning.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/capability-versioning.md b/docs/capability-versioning.md index 3b38404..6da7dbb 100644 --- a/docs/capability-versioning.md +++ b/docs/capability-versioning.md @@ -48,6 +48,24 @@ not signal stability. A small wording change can alter agent behavior: classify the observed contract impact, not the number of edited lines. Record candidate versions as prereleases and validate them before advertising a stable release. +## Relation to the plugin version + +Capabilities in this repository reach consumers through the Claude Code plugin. +The host installs it into a cache directory named after the `version` field of +`.claude-plugin/plugin.json` (for example +`~/.claude/plugins/cache/project-kit-local/project-kit/0.1.0/`) and records the +commit it installed. Changing files without changing that field can leave +installed copies on the old files. + +- A PR that releases a capability shipped by the plugin also bumps the plugin + `version`, at least as far as the largest capability bump it contains. Under + 0.x, an incompatible capability change bumps the plugin MINOR. +- The plugin version is the distribution version; capability versions stay in + their own release notes. Never reuse a plugin version for different contents. +- In the consumer inventory, a capability loaded through the plugin records the + plugin version and the installed commit from the host's install record as its + revision, instead of hashes of copied files. + ## Pinning in a consumer repo Maintain `docs/capabilities.md` as a human-reviewed inventory initially. For each From 0894c8d82293f37cb0268bc1627a4d2600e5dcec Mon Sep 17 00:00:00 2001 From: Rody Vilchez <102562850+R0SEWT@users.noreply.github.com> Date: Sat, 26 Sep 2026 23:12:02 -0500 Subject: [PATCH 3/3] docs: reconcile plugin-loaded pins with hashes and the 0.x bump rule Co-Authored-By: Claude Opus 5.5 --- docs/capability-versioning.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/capability-versioning.md b/docs/capability-versioning.md index 6da7dbb..259aa75 100644 --- a/docs/capability-versioning.md +++ b/docs/capability-versioning.md @@ -58,13 +58,17 @@ commit it installed. Changing files without changing that field can leave installed copies on the old files. - A PR that releases a capability shipped by the plugin also bumps the plugin - `version`, at least as far as the largest capability bump it contains. Under - 0.x, an incompatible capability change bumps the plugin MINOR. + `version` by the largest capability bump it contains. While the plugin is 0.x, + shift one level down: an incompatible change bumps MINOR, anything else PATCH. - The plugin version is the distribution version; capability versions stay in their own release notes. Never reuse a plugin version for different contents. - In the consumer inventory, a capability loaded through the plugin records the plugin version and the installed commit from the host's install record as its revision, instead of hashes of copied files. +- Install from a clean checkout. For a local-directory marketplace the host + copies the working tree, so uncommitted edits would land in a cache that + matches no commit, and rolling back to the recorded commit would not + reproduce what was loaded. ## Pinning in a consumer repo @@ -76,7 +80,7 @@ capability record the following fields: | ID and version | Capability name and declared release | | Source | Repository URL and source subdirectory | | Revision | Full immutable Git commit SHA; a branch or tag alone is insufficient | -| Installed files | Exact destination paths and file hashes | +| Installed files | Copied capabilities: exact destination paths and file hashes. Plugin-loaded: plugin version and install commit (see above) | | Dependencies | Capability IDs with tested exact revisions | | Configuration | Local non-secret configuration paths | | Validation | Evidence record and consumer commit tested | @@ -89,8 +93,10 @@ the repository already enforces it automatically. ## Update and rollback 1. Review candidate release notes, source diff and changed dependencies. -2. In a lab worktree, compare installed hashes with the inventory. Stop if local - changes are unexplained; preserve and reconcile them before replacement. +2. In a lab worktree, compare what is installed with the inventory: file + hashes for copied capabilities, plugin version and commit for plugin-loaded + ones. Stop if local changes are unexplained; preserve and reconcile them + before replacement. 3. Update only the declared managed files. Preserve project configuration and inspect any dependency or permission expansion. 4. Execute baseline, candidate and recovery cases. Record actual source revision