From a93f8358c4289129856a1ad910fe8e181eaa1d5a Mon Sep 17 00:00:00 2001 From: Brandonma21 Date: Thu, 5 Nov 2026 15:42:08 +0200 Subject: [PATCH] docs: Merge release-ops notes, fix rollout flags and set GPL-3.0 (LS-4771, batch 4) Release-ops review - Add docs/RELEASE_OPS_SKILLS_REVIEW.md comparing the six lightspeed-release-ops skills with the existing sub-skills - Pin the source to lightspeedwp/.github at 47aee0722033f65d4d9d57429b410b518646b817 - Record the decisions: merge, keep linking from the root SKILL.md, use the source licence (GPL-3.0) Merged notes - release-qa: readiness, risk assessment and rollout checklist notes - changelog-management: changelog compliance and version bump planner notes - release-notes-generator: release notes note - Each note quotes the stub description, credits the source and says what is not covered Cleanup - Replace unsupported flags in docs/TEAM_ROLLOUT_PLAN.md with the real /release flags - Replace git add -A in the release-qa version mismatch example with named files Licence - Set package.json license to GPL-3.0 to match the LICENSE file - Update the LICENSE line in docs/DEVELOPMENT.md Not done - No new sub-skill folders, manifests or platform files were imported - /release --draft-notes in the rollout plan is not a documented flag and was not on the issue list - Root skill name and deployment scope stay open Refs LS-4771 --- docs/DEVELOPMENT.md | 2 +- docs/RELEASE_OPS_SKILLS_REVIEW.md | 107 ++++++++++++++++++++ docs/TEAM_ROLLOUT_PLAN.md | 51 +++++----- package.json | 2 +- sub-skills/changelog-management/SKILL.md | 14 +++ sub-skills/release-notes-generator/SKILL.md | 12 +++ sub-skills/release-qa/SKILL.md | 20 +++- 7 files changed, 179 insertions(+), 29 deletions(-) create mode 100644 docs/RELEASE_OPS_SKILLS_REVIEW.md diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 7bbb55f..bc4c3ef 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -232,7 +232,7 @@ Required files for the release skill: release/ ├── README.md # Quick start guide ├── SKILL.md # Skill specification -├── LICENSE # GPL-2.0 license +├── LICENSE # GPL-3.0 license ├── package.json # npm configuration ├── .lefthook.yml # Git hooks configuration ├── .markdownlint.json # Markdown linter config diff --git a/docs/RELEASE_OPS_SKILLS_REVIEW.md b/docs/RELEASE_OPS_SKILLS_REVIEW.md new file mode 100644 index 0000000..25335b1 --- /dev/null +++ b/docs/RELEASE_OPS_SKILLS_REVIEW.md @@ -0,0 +1,107 @@ +--- +name: Release Ops Skills Review +description: Review of the lightspeed-release-ops plugin skills and how they were merged into this repository +version: 1.1.0 +updated: 2026-11-05 +--- + +# Release Ops Skills Review + +This document reviews the six skills in the `lightspeed-release-ops` plugin and records how they were handled. +The approach was approved on 5 November 2026: **merge the pack's content into the existing sub-skills**, keep +linking the sub-skills from the root `SKILL.md`, and use the source pack's licence (GPL-3.0). No new sub-skill +folders were created. + +## Summary + +- The pack has six skills. Each `SKILL.md` is a stub: one heading, one sentence that repeats its description, and a + footer. None has steps, inputs, outputs or checks. The orchestrator agent has no instructions either. +- Five of the six cover ground that existing sub-skills already cover in detail. The sixth (version bump planning) + has no dedicated sub-skill, but its rules already live in the release prompt, the agent and `changelog-management`. +- Because the stubs only hold a description, merging means recording each description, with attribution, in the + sub-skill it overlaps. This keeps both contents and says plainly what the existing skill does not cover. +- Importing the stubs as separate sub-skills would have added six files that restate the existing sub-skills with + less detail, so that was not done. + +## Source reviewed + +| Item | Value | +| ---- | ----- | +| Repository | `lightspeedwp/.github` | +| Path | `plugins/lightspeed-release-ops` | +| Commit | `47aee0722033f65d4d9d57429b410b518646b817` | +| Contents | 6 skills, 1 orchestrator agent, plugin manifests for Claude, Codex, Gemini and Copilot | +| Versions | Pack `0.1.0`, skills `0.1.1`, orchestrator `v0.1.1` | +| Licence stated | `GPL-3.0` (pack README) | + +Only `SKILL.md` content was in scope. The Codex, Gemini and Copilot manifests, the per-skill `agents/*.yaml` and +`metadata.yml` files, and the orchestrator agent were not used. + +## What the source skills contain + +| Skill | `SKILL.md` size | Body | +| ----- | --------------- | ---- | +| `lightspeed-release-readiness` | 441 bytes | Heading, one sentence, footer | +| `lightspeed-changelog-compliance` | 462 bytes | Heading, one sentence, footer | +| `lightspeed-release-notes-generator` | 460 bytes | Heading, one sentence, footer | +| `lightspeed-version-bump-planner` | 466 bytes | Heading, one sentence, footer | +| `lightspeed-release-rollout-checklist` | 470 bytes | Heading, one sentence, footer | +| `lightspeed-release-risk-assessment` | 434 bytes | Heading, one sentence, footer | + +- The pack README is frontmatter plus a link to a `CONTRIBUTING.md` that is not in the pack. It states + `stability: stable` for a `0.1.0` pack of stubs. +- The orchestrator agent has frontmatter and a footer, and no operational instructions. + +## How each skill was handled + +| Source skill | Overlaps | Result | +| ------------ | -------- | ------ | +| `lightspeed-release-readiness` | [release-qa](../sub-skills/release-qa/SKILL.md): seven quality gates, a pre-release checklist and a risk score | Merged: source note added to `release-qa` | +| `lightspeed-release-risk-assessment` | `release-qa` risk score and approval rules, and risk scoring in [release-approval-workflow](../sub-skills/release-approval-workflow/SKILL.md) | Merged: source note added to `release-qa` | +| `lightspeed-release-rollout-checklist` | `release-qa` pre-release checklist, the post-release checklist in [SKILL.md](../SKILL.md), and the rollback plan and monitoring sections of the handoff document that [release-handoff-generator](../sub-skills/release-handoff-generator/SKILL.md) produces | Merged: source note added to `release-qa` | +| `lightspeed-changelog-compliance` | [changelog-management](../sub-skills/changelog-management/SKILL.md): Keep a Changelog format, validation and versioning | Merged: source note added to `changelog-management` | +| `lightspeed-version-bump-planner` | No dedicated sub-skill. Scope rules are in the [release prompt](../prompts/release.prompt.md) and the [agent](../agents/release-agent.md), and `changelog-management` determines the version | Merged: source note added to `changelog-management` | +| `lightspeed-release-notes-generator` | [release-notes-generator](../sub-skills/release-notes-generator/SKILL.md): a full skill with references and scripts | Merged: source note added to `release-notes-generator` | + +Each note quotes the stub's description, credits the source (repository, path, commit and licence), and states what +the existing sub-skill does not cover. No existing text was changed, and no skill name or frontmatter was changed. + +## Concepts the source names that this repository does not cover + +The stubs give no content for these, so they are recorded as gaps and not implemented: + +- **semantic-release alignment** (in the changelog compliance description). The existing skills use Keep a Changelog + and SemVer. The term `semantic-release` does not appear anywhere else in this repository. +- **Deployment safety, deployment controls and cutover** (in the readiness, rollout and risk descriptions). This + repository covers publishing a release (tag, GitHub Release, WordPress.org). It does not cover deploying a site. + The word "deploy" appears in only three sub-skills. +- **Mitigation recommendations** (in the risk assessment description). `release-qa` scores risk but does not + recommend mitigations. + +## Decisions + +| Question | Decision | +| -------- | -------- | +| Import, merge or skip | Merge, so that neither the stubs' content nor the existing content is lost | +| Discovery | Keep linking the sub-skills from the root `SKILL.md`. No plugin packaging | +| Licence | Use the source pack's licence, GPL-3.0 | + +## Still open + +1. **Licence.** Resolved: the `LICENSE` file is the GNU GPL version 3, and `package.json` and `docs/DEVELOPMENT.md` + now say `GPL-3.0` to match. The README's "internal toolkit" licence line is unchanged. +2. **Root identity.** The root `SKILL.md` frontmatter says `name: release`, while the repository is `ls-wp-release`. + Whether that name collides with anything else has not been checked. +3. **Nested discovery.** The 3 November report that nested `sub-skills/` folders are not discovered has not been + verified here. Linking from the root `SKILL.md` does not depend on it. +4. **Deployment scope.** Whether deployment safety belongs in this skill at all. +5. **Real content for the gaps.** Version bump planning, a rollout checklist, deployment safety, semantic-release + alignment and mitigation advice would each be new work with its own spec. They are not covered by this change. + +## What was and was not checked + +- **Checked:** the six `SKILL.md` files, the orchestrator, the pack README, the Claude plugin manifest, one + `metadata.yml` and one `agents/claude.yaml`, all at the commit above. The named sections of the existing + sub-skills. A search of this repository for `semantic-release` and `deploy`, and of `release-qa` for `mitigat`. +- **Not checked:** how any host discovers or loads nested skills, whether the plugin installs, other revisions of the + source pack, and licence compatibility in law. This is not legal advice. diff --git a/docs/TEAM_ROLLOUT_PLAN.md b/docs/TEAM_ROLLOUT_PLAN.md index c046561..a2445f1 100644 --- a/docs/TEAM_ROLLOUT_PLAN.md +++ b/docs/TEAM_ROLLOUT_PLAN.md @@ -134,9 +134,9 @@ All notable changes to this project will be documented in this file. 4. Add `.lefthook-local.yml` to .gitignore -5. Run setup check: +5. Run a read-only check: ```bash -/release --validate-setup +/release --dry-run ``` ### Thursday: Team Training Session @@ -164,7 +164,7 @@ All notable changes to this project will be documented in this file. **Topic:** How to use the skill for your first release **Content:** -- Reading help: `/release --help` +- Reading the skill docs: [SKILL.md](../SKILL.md) (scope parameters and guardrails) - Dry run mode: `/release --dry-run` - Real release flow - Handling release notes @@ -190,7 +190,7 @@ All notable changes to this project will be documented in this file. - [ ] CHANGELOG.md in Keep a Changelog format - [ ] .lefthook.yml configured - [ ] lefthook install runs without errors -- [ ] /release --validate-setup passes +- [ ] /release --dry-run passes - [ ] Pre-commit hooks fire on test commit - [ ] Documentation added to project README - [ ] Team trained on release workflow @@ -199,14 +199,14 @@ All notable changes to this project will be documented in this file. Run on each project: ```bash -/release --validate-setup --verbose +/release --dry-run ``` **Output should show:** -- All hooks installed ✓ -- Version file readable ✓ +- Pre-release checklist with no blockers +- Version file readable and aligned ✓ - Changelog valid ✓ -- Configuration complete ✓ +- Hooks are checked separately: `lefthook install` runs without errors **Report to:** #release-skill channel @@ -257,9 +257,9 @@ cd /path/to/plugin-or-theme **For each project type:** **Plugin teams:** -- Feature: Run /release --dry-run --type minor -- Bug fix: Run /release --dry-run --type patch -- Breaking change: Run /release --dry-run --type major +- Feature: Run /release --scope=minor --dry-run +- Bug fix: Run /release --scope=patch --dry-run +- Breaking change: Run /release --scope=major --dry-run **Theme teams:** - Same workflow as plugins @@ -409,8 +409,8 @@ For next **real** release, draft release notes: □ Security scan clean □ Team communication sent -□ Run: /release --validate-release - (checks all above) +□ Run: /release --dry-run + (read-only checks of the technical items above) □ Final go/no-go decision ``` @@ -418,14 +418,13 @@ For next **real** release, draft release notes: #### Execute Release ```bash -# Step 1: Create release -/release --type patch --version 2.5.1 +# Step 1: Review the plan first (read-only) +/release --scope=patch --version=2.5.1 --dry-run -# Step 2: Review release details -/release --show-details +# Step 2: Create release +/release --scope=patch --version=2.5.1 -# Step 3: Confirm and proceed -/release --confirm +# Step 3: Confirm each step when the agent pauses and asks # Step 4: Monitor release process # - Git branch creation @@ -435,7 +434,7 @@ For next **real** release, draft release notes: # - Push to repository # Step 5: Post-release -/release --post-release-check +/release --verify --version=2.5.1 ``` #### Document Findings @@ -753,7 +752,7 @@ cat VERSION # verify content 2. Fix the identified issue 3. Run tests locally 4. Retry push -**Support:** Run `/release --help` for options +**Support:** See [SKILL.md](../SKILL.md) for the available options #### Issue: Release blocked by hook **Cause:** Validation caught a real problem @@ -1031,20 +1030,20 @@ PRE-RELEASE □ README updated VALIDATION -□ Run: /release --validate-release +□ Run: /release --dry-run □ Fix any issues □ Run again until passing RELEASE □ Team approval obtained □ Support person assigned as observer -□ Run: /release --show-details +□ Run: /release --scope=[patch|minor|major] --dry-run □ Review output carefully -□ Run: /release --confirm +□ Run: /release --scope=[patch|minor|major] and confirm each step when the agent asks □ Monitor progress POST-RELEASE -□ Run: /release --post-release-check +□ Run: /release --verify --version=[released-version] □ Verify version bumped everywhere □ Verify tag created □ Verify changelog updated @@ -1176,7 +1175,7 @@ Your feedback directly shapes how this tool evolves. □ Run: lefthook install -□ Run: /release --validate-setup +□ Run: /release --dry-run □ Add documentation to project README diff --git a/package.json b/package.json index 560b66d..d7aa40d 100644 --- a/package.json +++ b/package.json @@ -3,7 +3,7 @@ "version": "1.0.0", "description": "Comprehensive release management skill for WordPress block plugins and themes", "author": "LightSpeedWP Release Team", - "license": "GPL-2.0", + "license": "GPL-3.0", "repository": { "type": "git", "url": "https://github.com/lightspeedwp/ls-wp-release.git" diff --git a/sub-skills/changelog-management/SKILL.md b/sub-skills/changelog-management/SKILL.md index 1ef3b59..95947d7 100644 --- a/sub-skills/changelog-management/SKILL.md +++ b/sub-skills/changelog-management/SKILL.md @@ -611,6 +611,20 @@ pre-commit: run: npm run validate:changelog ``` +## Source Pack Notes + +The `lightspeed-release-ops` plugin pack (`lightspeedwp/.github`, `plugins/lightspeed-release-ops`, commit +`47aee07`, GPL-3.0) has two stub skills that overlap with this one. Each stub is a heading and one sentence. +Their descriptions are recorded here so nothing is lost: + +- `lightspeed-changelog-compliance`: "validate changelog completeness and semantic-release alignment before release + handoff." This skill validates Keep a Changelog format compliance and catches incomplete entries. It does not + cover semantic-release alignment. The term is not used anywhere else in this repository. +- `lightspeed-version-bump-planner`: "plan semantic version bump recommendations from change scope and release + policy signals." This skill determines the version type from commit analysis (see Preparing for Release). + +See [the review](../../docs/RELEASE_OPS_SKILLS_REVIEW.md) for the full comparison. + ## See Also - [[release]] — main release skill with changelog integration diff --git a/sub-skills/release-notes-generator/SKILL.md b/sub-skills/release-notes-generator/SKILL.md index 9b4eb18..7acb4a5 100644 --- a/sub-skills/release-notes-generator/SKILL.md +++ b/sub-skills/release-notes-generator/SKILL.md @@ -685,6 +685,18 @@ For social media and newsletter: 7. **Mention Contributors** — Give credit to your community 8. **Version Consistently** — Use SemVer for all versions +## Source Pack Notes + +The `lightspeed-release-ops` plugin pack (`lightspeedwp/.github`, `plugins/lightspeed-release-ops`, commit +`47aee07`, GPL-3.0) has a stub skill that overlaps with this one. The stub is a heading and one sentence. Its +description is recorded here so nothing is lost: + +- `lightspeed-release-notes-generator`: "generate structured release notes from validated changelog and repository + signals." This skill already covers it in full: it generates release notes from the changelog and the commit + history in several output formats. + +See [the review](../../docs/RELEASE_OPS_SKILLS_REVIEW.md) for the full comparison. + ## Version History - **1.0.0** (2026-10-30) — Initial release diff --git a/sub-skills/release-qa/SKILL.md b/sub-skills/release-qa/SKILL.md index 507bba5..1af2901 100644 --- a/sub-skills/release-qa/SKILL.md +++ b/sub-skills/release-qa/SKILL.md @@ -461,10 +461,28 @@ Investigation steps: Fix: 1. Identify the source: VERSION file is the source of truth 2. Update all others to match: plugin.php, style.css, readme.txt - 3. Commit: git add -A && git commit -m "chore: sync versions to 1.2.4" + 3. Commit: git add && git commit -m "chore: sync versions to 1.2.4" 4. Retry: /release-qa ``` +## Source Pack Notes + +The `lightspeed-release-ops` plugin pack (`lightspeedwp/.github`, `plugins/lightspeed-release-ops`, commit +`47aee07`, GPL-3.0) has three stub skills that overlap with this one. Each stub is a heading and one sentence. +Their descriptions are recorded here so nothing is lost: + +- `lightspeed-release-readiness`: "Runs structured release-readiness checks for versioning, changelog completeness, + and deployment safety." This skill covers the versioning and changelog checks (Gates 3 and 4). It does not cover + deployment safety. +- `lightspeed-release-risk-assessment`: "assess release risk signals and recommend mitigations before cutover." + This skill produces a risk score and approval rules (see Release Risk Assessment). It does not recommend + mitigations. +- `lightspeed-release-rollout-checklist`: "build release rollout checklists aligned with release policy and + deployment controls." This skill generates a pre-release checklist (see Pre-Release Checklist). It does not cover + deployment controls. + +See [the review](../../docs/RELEASE_OPS_SKILLS_REVIEW.md) for the full comparison. + ## See Also - [[release]] — main release orchestration skill