Release Management
Pathrule2 Rules • 1 Memory • 2 Skills
Release management turns a tested source revision into an immutable artifact that is promoted through environments with known compatibility and rollback behavior. This bundle defines artifact identity, provenance, database and API compatibility, approval, release notes, and reversible operations. Unlike Git Conventional Commits, it governs shipped artifacts and production change rather than commit message structure.
Suggested path map
Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.
/ workspace root
prepare-release-candidate
.github/
workflows/
Build once and promote the same artifact
scripts/
Make compatibility and rollback explicit before release
rehearse-release-rollback
docs/
releases/
A release identity names bytes and behavior
Rules
2Build once and promote the same artifact/.github/workflowshighstrictA release has one immutable digest and provenance record that every environment verifies before promotion.
| 1 | A release has one immutable digest and provenance record that every environment verifies before promotion. Rebuilding from the same commit can resolve different dependencies, tools, base images, or environment inputs, so staging and production are not equivalent. Enforce this boundary in /.github/workflows so invalid work stops before it reaches another subsystem or creates an externally visible side effect. |
| 2 | |
| 3 | - Build in a controlled job from an immutable source revision and pinned dependency, tool, and base-image inputs. |
| 4 | - Attach artifact digest, source revision, builder identity, test evidence, and software bill of materials where applicable. |
| 5 | - Promote by digest through environments and reject any artifact whose provenance or approval evidence does not match policy. |
| 6 | - Keep environment configuration outside the artifact while validating its schema before startup. |
| 7 | |
| 8 | Verification: Compare artifact digests across test, staging, canary, and production; tamper with provenance or rebuild one stage and confirm promotion fails. |
Make compatibility and rollback explicit before release/scriptshighstrictDatabase, API, event, client, and configuration changes declare the versions that can coexist during rollout and rollback.
| 1 | Database, API, event, client, and configuration changes declare the versions that can coexist during rollout and rollback. A backward-incompatible migration or event change can make the previous application unable to start or process new data, turning rollback into further damage. Enforce this boundary in /scripts so invalid work stops before it reaches another subsystem or creates an externally visible side effect. |
| 2 | |
| 3 | - Use expand and contract sequencing for shared schemas and keep old readers and writers during the compatibility window. |
| 4 | - Version external APIs and events when meaning or required fields change; test current and previous consumers against the candidate. |
| 5 | - Separate destructive cleanup from the release that stops using old data or behavior. |
| 6 | - Define forward-fix and rollback triggers, operator steps, data consequences, and the last safe decision point. |
| 7 | |
| 8 | Verification: Run the candidate beside the previous version against production-like schema and traffic, then execute the rollback rehearsal and verify stored data remains readable. |
Memories
1A release identity names bytes and behavior/docs/releasesA source tag alone cannot prove which artifact, dependency graph, migration set, configuration contract, or feature state reached an environment.
| 1 | A source tag alone cannot prove which artifact, dependency graph, migration set, configuration contract, or feature state reached an environment. Create a release record that binds semantic version where used, source revision, artifact digest, provenance, migrations, compatibility window, approvals, and notes. |
| 2 | |
| 3 | Treat an already released version and artifact as immutable; corrections produce a new release. Use deployment records to show where and when the release is active without changing its identity. Link incidents, rollbacks, and follow-up fixes to the same release record for audit and learning. Keep the decision explicit at /docs/releases; moving it into an incidental caller makes behavior depend on which route happened to execute first. |
| 4 | |
| 5 | See /.github/workflows for promotion evidence and /scripts for compatibility checks. That related boundary consumes this decision and carries the evidence that proves it still holds. |
Skills
2prepare-release-candidate/rootPrepare a release candidate with immutable artifacts, compatibility evidence, notes, approvals, and rollback readiness.
| 1 | --- |
| 2 | name: prepare-release-candidate |
| 3 | description: Prepare a release candidate with immutable artifacts, compatibility evidence, notes, approvals, and rollback readiness. |
| 4 | --- |
| 5 | |
| 6 | # Prepare Release Candidate |
| 7 | |
| 8 | Run this procedure whenever the governed surface changes or its operational evidence becomes stale. |
| 9 | |
| 10 | 1. Select the source revision and version, freeze scope, generate changelog and user-facing notes, and identify migrations or external contract changes. |
| 11 | 2. Build once, capture digest and provenance, run unit, integration, security, compatibility, and upgrade tests against production-like dependencies. |
| 12 | 3. Review rollout cohorts, feature flags, observability, support communication, approval owners, rollback triggers, and the last safe rollback point. |
| 13 | 4. Publish the candidate record without promoting it, then have an independent approver verify evidence and artifact identity. |
| 14 | |
| 15 | Record the decision, failed checks, and follow-up owner with the change. A successful run leaves reproducible evidence that another reviewer can inspect without repeating the investigation from memory. |
rehearse-release-rollback/scriptsRehearse rollback of a release candidate across application, schema, configuration, traffic, and queued work.
| 1 | --- |
| 2 | name: rehearse-release-rollback |
| 3 | description: Rehearse rollback of a release candidate across application, schema, configuration, traffic, and queued work. |
| 4 | --- |
| 5 | |
| 6 | # Rehearse Release Rollback |
| 7 | |
| 8 | Run this procedure whenever the governed surface changes or its operational evidence becomes stale. |
| 9 | |
| 10 | 1. Deploy the current release and representative data, traffic, jobs, clients, and external contract fixtures in a production-like environment. |
| 11 | 2. Promote the candidate through the real mechanism, exercise new and old paths, and capture the rollback trigger and decision timestamp. |
| 12 | 3. Roll back application and configuration while preserving safe migrations, then drain or replay queued work according to version compatibility. |
| 13 | 4. Verify user behavior, data integrity, previous-client compatibility, telemetry, and operator timing; record any condition that requires a forward fix instead. |
| 14 | |
| 15 | Record the decision, failed checks, and follow-up owner with the change. A successful run leaves reproducible evidence that another reviewer can inspect without repeating the investigation from memory. |
Why this pattern
Agents rebuild between environments, bundle irreversible schema changes with code, or publish from commit history without proving compatibility, provenance, and rollback.
Built for Teams shipping services, applications, libraries, or infrastructure through controlled environments.
Keeps your assistant from:
- Production receiving different bytes than staging tested
- A release that cannot run with the previous schema or client
- Rollback discovered to be unsafe only after an incident
- License
- Apache-2.0
- Version
- 1.0.0
- Updated
- 2026-08-25