agentleFS
Sign inStart free
Thank-you-LinusThank-you-Linus/Linus-Dashboard/.claude/skills/release-stable/SKILL.md

release-stable

Skill214 starsChanged 31 days agoMITView on GitHub

Create a stable production release with intelligent detection (finalize beta or direct release). Use when publishing stable releases, finalizing beta versions, or creating production releases.

  • Commits and pushes

6 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

16 rules. 0 are common, 12 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 6 edited versions we read keep these.

  • 12

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Create a STABLE release for production use.

    line 8
  2. Very specific:

    All scripts (bump-version.sh, create-release.sh) already create tags without 'v'.

    line 20
  3. Distinctive:

    Never create tags manually: - always use the scripts.

    line 21
  4. Very specific:

    Run commit analysis: npm run analyze:commits

    line 47
  5. Distinctive:

    No additional analysis or validation required

    line 61
  6. Distinctive:

    If user chooses [2] CREATE BETA: Stop and use release-beta skill

    line 82
  7. Distinctive:

    Commit breakdown (feat, fix, breaking, etc.)

    line 91
  8. Distinctive:

    Remove noise (version bumps, merges, CI commits, deps updates)

    line 111
  9. Distinctive:

    Remove beta testing section (not needed for stable)

    line 114
  10. Distinctive:

    Add upgrade instructions if needed

    line 115
  11. Distinctive:

    No beta testing section

    line 128
  12. Very specific:

    Every release logged to: .opencode/logs/release-stable-{timestamp}.log

    line 241
  13. Distinctive:

    Check status: Use release-check skill

    line 263
  14. Distinctive:

    Best practice: Always test with beta first (release-beta → test → release-stable)

    line 285
  15. Distinctive:

    All validations are blocking (must pass)

    line 286
  16. Very specific:

    After successful release, use npm run forums:open to announce on Home Assistant Community Forum and HACF.

    line 300

“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Create Stable Production Release

Create a STABLE release for production use.

Current version: Check package.json for current version.

⚠️ CRITICAL TAG FORMAT RULE

NEVER use 'v' prefix in git tags!

  • ✅ CORRECT: 1.5.0
  • ❌ WRONG: v1.5.0

The GitHub workflows expect tags WITHOUT 'v' prefix. Using 'v' will cause workflow failures. All scripts (bump-version.sh, create-release.sh) already create tags without 'v'. Never create tags manually - always use the scripts.

Intelligent Workflow

The workflow adapts automatically based on the current version:

From beta (1.5.0-beta.3 → 1.5.0) → Automatic finalization, no analysis needed Direct stable release (1.4.0 → 1.5.0) → AI analyzes commits and suggests version type with warning

Phase 1: Release Type Detection

Automatically detect release scenario:

  1. Detect release scenario:
    • Current version: 1.5.0-beta.3 → Finalize beta (automatic, no validation)
    • Current version: 1.4.0 (stable) → Direct release (requires AI analysis + warning)
  2. For finalize beta:
    • Strip -beta.N suffix automatically
    • Skip commit analysis (already done during beta)
    • Faster workflow (3-5 min)
  3. For direct stable release:
    • Show WARNING about skipping beta testing (risky)
    • Run commit analysis: npm run analyze:commits
    • Analyze commit types (feat, fix, BREAKING CHANGE)
    • Determine version bump type (patch/minor/major)
    • Present detailed validation with option to create beta instead

Phase 2A: Finalize Beta (Automatic)

Current: 1.5.0-beta.3 → Stable: 1.5.0

Present automatic finalization message:

  • Current version and target stable version
  • Note that version type was already determined during beta
  • No additional analysis or validation required
  • Proceed automatically to release notes and validation

No user validation required → Proceeds directly to Phase 3

Phase 2B: Direct Stable Release (Requires Validation)

Current: 1.4.0 → Proposed: 1.5.0

Beta Testing Warning

Present warning about direct stable release:

  • Risks: No community feedback, untested in real environments, bugs reach production, harder rollback
  • Recommendation: Create beta first
  • User options:
    • [1] YES - Continue with direct release (risky)
    • [2] CREATE BETA INSTEAD - Safer approach
    • [3] CANCEL - Abort

If user chooses [2] CREATE BETA: Stop and use release-beta skill

If user chooses [1] PROCEED: Show detailed AI analysis

AI Semantic Analysis (Direct Release Only)

Present detailed analysis with:

  • Current version and proposed version
  • Warning about skipping beta
  • Commit breakdown (feat, fix, breaking, etc.)
  • AI reasoning with confidence level
  • Recommendation to test as beta first
  • Key commits (most impactful)
  • User decision options:
    • [1] APPROVE - Proceed with AI suggestion (skipping beta)
    • [2] DOWNGRADE TO PATCH - Override AI (skipping beta)
    • [3] UPGRADE TO MAJOR - Override AI (skipping beta)
    • [4] CREATE BETA INSTEAD - Safer approach (recommended)
    • [5] VIEW COMMITS - Show full commit list
    • [6] CANCEL - Abort safely

Phase 3: Release Notes Generation & Editing

Automatically:

  1. Generate release notes (bash scripts/generate-release-notes.sh)
  2. AI-powered editing:
    • Remove noise (version bumps, merges, CI commits, deps updates)
    • Enhance features/fixes (bold title + detailed description)
    • Translate to French (same detail level)
    • Remove beta testing section (not needed for stable)
    • Add upgrade instructions if needed
    • Remove TODO markers
  3. Format for GitHub (bash scripts/format-release-notes.sh)

Phase 4: Quality Validation (BLOCKING)

All must pass:

A. Release notes validation (scripts/validate-release-notes.sh)

  • Required sections EN/FR
  • No TODO
  • No beta testing section
  • Bold features

B. Code quality (17 checks) (scripts/check-release-ready.sh)

  1. Git clean 2. Branch main 3. Up-to-date 4. Deps installed 5. Lint 6. Type-check 7. Build 8. Version consistency 9. No FIXME 10. CHANGELOG 11. manifest.json 12. hacs.json 13. No secrets 14. Python syntax 15. README 16. LICENSE 17. Smoke tests ready

C. Smoke tests (15 tests) (npm run test:smoke)

Phase 5: Final Approval & Publication

For finalize beta:

Present approval with:

  • Version and finalization info
  • Note that beta testing completed successfully
  • Changes summary (features, bug fixes) since last stable
  • Validation results
  • What happens if approved

User options:

  • [1] APPROVE - Publish stable release
  • [2] REQUEST CHANGES - Modify release notes
  • [3] VIEW FULL NOTES - See complete file
  • [4] CANCEL - Abort

For direct stable release:

Present approval with:

  • Version and bump type
  • Warning about skipping beta testing
  • Changes summary
  • Validation results
  • Reminder to monitor closely

User options:

  • [1] APPROVE - Publish stable release (skipping beta)
  • [2] CREATE BETA INSTEAD - Safer approach
  • [3] REQUEST CHANGES - Modify release notes
  • [4] VIEW FULL NOTES - See complete file
  • [5] CANCEL - Abort

Phase 6: Publication (Only after approval)

For finalize beta (automatic version):

  1. Bump version (bash scripts/bump-version.sh release)
    • Strips -beta.N: 1.5.0-beta.3 → 1.5.0
  2. Update release notes with final version
  3. Commit + tag (git commit + git tag)
  4. Push (git push && git push --tags)
  5. Report success with forum links

For direct stable release (explicit version type):

  1. Bump version (bash scripts/bump-version.sh release <patch|minor|major>)
    • Example: bash scripts/bump-version.sh release minor → 1.5.0
  2. Update release notes with final version
  3. Commit + tag (git commit + git tag)
  4. Push (git push && git push --tags)
  5. Report success with forum links

GitHub Actions automatically:

  • Builds project
  • Runs smoke tests
  • Creates ZIP
  • Creates stable release
  • Cleans up RELEASE_NOTES.md

Discord #annonces: a tag pushed by this command is not announced (release.yml never announces; only the Stable Release (manual) button does). Run Actions -> Announce stable release on Discord (manual) with the tag: it posts .github/release-highlights/<version>.discord.md if it exists, else a generic text.

Manual step (forums):

  • Open forum threads: npm run forums:open
  • Post release announcement (templates provided)

Quality Standards

Release notes: EN+FR equal quality, no TODO, detailed explanations, user-focused, clean, no beta testing section

Code: 17 checks passed, 15 smoke tests passed, lint+type-check passed, build succeeded

Version decision:

  • Finalize beta: Automatic, no validation
  • Direct release: AI analyzes commits, warns about skipping beta, requires user validation

Options

Dry Run

--dry-run

Runs everything, creates commit+tag locally, STOPS before push. Nothing published. To undo: git reset HEAD~1 && git tag -d X.Y.Z

Skip Approval (Final approval only)

--skip-approval

Shows summary but auto-approves final publication. Still shows warning and requires version decision for direct releases. ⚠️ Use with extreme caution.

Logs

Every release logged to: .opencode/logs/release-stable-{timestamp}.log

Contains: timestamps, detection logic, commit analysis (if direct), AI reasoning, warnings shown, user decisions, git hashes, URLs, duration

Common Errors

Validation fails → Fix issues, re-run command Smoke tests fail → Check npm run test:smoke, fix, re-run Build fails → Run npm run build, fix errors, re-run Push fails → git pull --rebase, re-run Tag exists → git tag -d X.Y.Z then re-run Ambiguous commits (direct release) → AI asks you to decide manually Beta recommended → Use release-beta skill first for safer release

Related Commands

Before stable release:

  • Recommended: Use release-beta skill (test first)
  • Check status: Use release-check skill

After stable release:

  • Hotfix needed → Use release-stable skill again (creates patch: 1.5.0 → 1.5.1)
  • Critical issue → Use release-rollback skill
  • Announce → npm run forums:open

Release Type Detection Logic

Current VersionDetectionAI AnalysisBeta WarningUser ValidationResult
1.5.0-beta.3Finalize❌ No❌ No❌ Not required1.5.0 (stable)
1.4.0 (stable)Direct✅ Yes✅ Yes✅ Required1.5.0 (if MINOR)

Important

  • Finalize beta: Automatic and fast (no validation, already tested)
  • Direct stable: Requires AI analysis + shows warning about skipping beta + requires your validation
  • Best practice: Always test with beta first (release-beta → test → release-stable)
  • All validations are blocking (must pass)
  • Idempotent (safe to re-run)
  • Logs everything
  • Time: 3-5 min (finalize) or 5-10 min (direct release)

Scripts Used:

  • scripts/analyze-commits.sh - Commit analysis (direct release only)
  • scripts/bump-version.sh release [patch|minor|major] - Version bumping
  • scripts/generate-release-notes.sh - Release notes generation
  • scripts/format-release-notes.sh - Formatting
  • scripts/validate-release-notes.sh - Validation
  • scripts/check-release-ready.sh - Code quality checks

Forum Announcement: After successful release, use npm run forums:open to announce on Home Assistant Community Forum and HACF.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free