Skip to content
Open
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
2 changes: 1 addition & 1 deletion docs/DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
107 changes: 107 additions & 0 deletions docs/RELEASE_OPS_SKILLS_REVIEW.md
Original file line number Diff line number Diff line change
@@ -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.
51 changes: 25 additions & 26 deletions docs/TEAM_ROLLOUT_PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -409,23 +409,22 @@ 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
```

#### 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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
14 changes: 14 additions & 0 deletions sub-skills/changelog-management/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
12 changes: 12 additions & 0 deletions sub-skills/release-notes-generator/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
20 changes: 19 additions & 1 deletion sub-skills/release-qa/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <the files you edited> && 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
Expand Down