jaan-release

Automate jaan-to release preparation from validation to PR creation.

LOCAL SKILL — For jaan-to maintainers only. Not distributed to plugin users.

What This Does

Orchestrates the complete release preparation workflow:

✅ Validates 24 compliance & plugin standards checks
📝 Syncs documentation (roadmap, docs, website, changelog)
🔢 Bumps version atomically across 4 files
🚀 Creates release PR (dev → main)
⏸️ Stops for human review and merge

Input

Optional:
```
vX.Y.Z
```
- Target version (auto-suggested if omitted)
Optional:
```
"release summary"
```
- 1-sentence description (extracted from CHANGELOG if omitted)

Pre-Execution Protocol

MANDATORY — Execute before PHASE 1:

Step 0: Init Guard — Verify we're in jaan-to repository root Step A: Load Lessons — Read

.claude/skills/jaan-release/LEARN.md

Step B: Branch Check — Verify on

dev

branch (releases prepare from dev) Step C: Offer Dry Run — Ask: "Run validation checks first? [y/n]"

PHASE 1: Pre-Release Validation

Purpose: Run all validation checks locally for fast feedback before any changes.

Step 1.1: Run Validation Scripts

Invoke all 4 validation scripts in sequence:

bash

# Check 1-10: Advisory compliance (warnings OK)
bash .claude/scripts/validate-compliance.sh

# Check 11-16: Critical plugin standards (must pass)
bash .claude/scripts/validate-plugin-standards.sh

# Security standards (must pass — no blocking errors)
bash scripts/validate-security.sh

# Check git state, docs sync, version detection
bash .claude/scripts/validate-release-readiness.sh

Expected output:

Compliance: 10 checks (warnings are advisory)
Plugin Standards: 6 checks (must pass)
Security Standards: 4 sections (must pass — no blocking errors)
Release Readiness: Git clean, docs synced, suggested version

Capture:

```
SUGGESTED_VERSION
```
from validate-release-readiness.sh output
Any blocking errors from plugin standards

Step 1.2: Aggregate Results

Parse validation output and summarize:

Pre-Release Validation Report
═══════════════════════════════════════════════════════════

## Compliance Checks (10/10)
  ✓ Check 1: Skill Alignment (all skills have two-phase + HARD STOP)
  ✓ Check 2: Generic Applicability (no user-specific refs)
  ✓ Check 3: Multi-Stack Coverage (Node.js/PHP/Go)
  ...
  ✓ Check 10: Security Review (no dangerous patterns)

## Plugin Standards (6/6)
  ✓ Check 11: Plugin Manifests (JSON valid, versions match)
  ✓ Check 12: Hooks Validation (4 hooks defined)
  ✓ Check 13: Skills Structure (40 skills, all have frontmatter)
  ✓ Check 14: Context Files (all have headers)
  ✓ Check 15: Output Structure (0 errors)
  ✓ Check 16: Permission Safety (no dangerous patterns)

## Security Standards (4/4)
  ✓ Section A: Skill Permission Safety (no bare Write/Bash/Edit)
  ✓ Section B: Shell Script Safety (set -euo pipefail, no eval/curl|sh)
  ✓ Section C: Hook Safety (static paths, no user input)
  ✓ Section D: Dangerous Patterns (no exec(), no rm -rf /)

## Git State (3/3)
  ✓ Working tree clean (0 uncommitted changes)
  ✓ On dev branch (up to date with origin/dev)
  ✓ Remotes fetched

## Documentation (2/2)
  ✓ Sync check: 0 stale files
  ✓ README indexes: all up to date

## Release Content (3/3)
  ✓ [Unreleased] section: 5 entries (3 Added, 1 Changed, 1 Fixed)
  ✓ CHANGELOG format: Keep a Changelog ✓
  ✓ Suggested version: v6.3.0 (minor bump - new features added)

───────────────────────────────────────────────────────────────
✅ All 24 checks passed. Ready for Phase 2.
───────────────────────────────────────────────────────────────

If any errors:

Show specific failures with remediation commands
Block Phase 2 until fixed
Suggest:
```
git status
```
,
```
git stash
```
, fix commands from script output

HARD STOP 1: Validation Report

Ask user:

Validation complete. All 24 checks passed.
Suggested version: v6.3.0 (minor bump)

Proceed to Phase 2 (Documentation & Version Prep)? [y/n/abort]

Options:

```
y
```
→ Continue to Phase 2
```
n
```
→ Show detailed validation output, then re-ask
```
abort
```
→ Exit skill (no changes made)

Rollback: None needed (read-only phase)

PHASE 2: Documentation & Version Prep

Purpose: Sync all documentation and prepare release content.

Step 2.1: Roadmap Sync

Invoke:

/jaan-to:pm-roadmap-update sync

This skill:

Reads git history since last version tag
Marks completed tasks as "done" in roadmap.md
Updates task statuses based on commit messages

Expected:

✓ Roadmap synced: 3 tasks marked done

Step 2.2: Documentation Auto-Fix

Invoke:

/jaan-to:docs-update --fix

This skill:

Updates stale timestamps in docs
Generates missing doc files
Rebuilds README.md indexes

Expected:

✓ Documentation updated: 2 files fixed, 0 missing

Step 2.3: Website Update (ENHANCED)

Run intelligent website updater:

bash

bash .claude/scripts/update-website.sh

This script:

Updates version badge (v6.1.0 → v6.3.0)
Updates skill counts (3 locations)
Updates role counts (2 locations)
Detects new/removed skills from CHANGELOG
Generates HTML for catalog updates
Smart suggestions (new roles, efficiency metrics, etc.)

Expected output:

Website Update Summary
────────────────────────────────────────────────────────────
  ✓ Version badge:   v6.3.0
  ✓ Skill counts:    40 skills (3 locations)
  ✓ Role count:      11 roles (2 locations)

  ⚠ MANUAL REVIEW REQUIRED

  Next steps:
  1. Review catalog changes above
  2. Edit website/index.html to add/remove skills
  3. Preview: open website/index.html in browser

If new skills detected:

Script shows generated HTML for each new skill
Ask user: "Apply these catalog updates? [y/n/manual]"
If
```
y
```
: Apply updates automatically
If
```
n
```
: Skip catalog updates (user will do manually)
If
```
manual
```
: Open website/index.html in editor, wait for user confirmation

Step 2.4: Changelog Generation

Invoke:

/jaan-to:release-iterate-changelog auto-generate

This skill:

Parses git commits since last tag
Generates CHANGELOG entries from conventional commits
Categorizes: Added, Changed, Fixed, Removed
Merges with existing [Unreleased] items

Expected:

✓ CHANGELOG generated: 5 entries categorized

HARD STOP 2: Review Prepared Changes

Show diff summary:

bash

git status --short

Expected files modified:

```
docs/roadmap/roadmap.md
```
(3 tasks marked done)
```
docs/**/*.md
```
(2 README indexes updated)
```
website/index.html
```
(version, counts, possibly catalog)
```
CHANGELOG.md
```
(5 entries organized)

Ask user:

Documentation Sync Complete
───────────────────────────
Modified files:
  M CHANGELOG.md
  M docs/roadmap/roadmap.md
  M website/index.html
  M docs/guides/README.md

Preview changes? [y/n/proceed]

Options:

```
y
```
→ Show
```
git diff
```
for each file
```
n
```
→ Skip preview
```
proceed
```
→ Continue to Phase 3
```
abort
```
→ Rollback changes

Rollback if aborted:

bash

git restore CHANGELOG.md docs/ website/index.html

PHASE 3: Atomic Version Bump

Purpose: Create single atomic commit with version bump across all files.

Step 3.1: Determine Target Version

If version provided as argument:

Use provided version (e.g.,
```
v6.3.0
```
)

If version omitted:

Use
```
SUGGESTED_VERSION
```
from Step 1.2
Confirm with user: "Use suggested version v6.3.0? [y/n/custom]"

Validate version:

Check format:
```
vX.Y.Z
```
(semantic versioning)
Check tag doesn't exist:
```
git tag -l v6.3.0
```
If exists: Error and abort

Step 3.2: Atomic Version Bump

Invoke:

/jaan-to:pm-roadmap-update release v6.3.0 "Add jaan-release skill"

This skill atomically:

Moves CHANGELOG
```
[Unreleased]
```
→
```
[6.3.0]
```
with date
Creates roadmap version section with tasks from this release

Updates

.claude-plugin/plugin.json

→

"version": "6.3.0"

Updates
```
.claude-plugin/marketplace.json
```
→ 2 version fields

Creates commit:

release: 6.3.0 — Add jaan-release skill

Creates tag:
```
v6.3.0
```
(local only, not pushed)

Expected:

✓ Version bumped: v6.2.0 → v6.3.0
✓ Files updated: CHANGELOG.md, roadmap.md, plugin.json (×3)
✓ Commit created: abc1234
✓ Tag created: v6.3.0 (local)

Step 3.3: CI Simulation (Local Validation)

Run the same checks CI will run:

bash

# Check version consistency
V1=$(jq -r '.version' .claude-plugin/plugin.json)
V2=$(jq -r '.version' .claude-plugin/marketplace.json)
V3=$(jq -r '.plugins[0].version' .claude-plugin/marketplace.json)

if [[ "$V1" == "$V2" ]] && [[ "$V1" == "$V3" ]]; then
  echo "✓ Version consistency: $V1"
else
  echo "✗ Version mismatch (CI will fail)"
  exit 1
fi

# Validate skill description budget
bash scripts/validate-skills.sh || exit 1

# Security standards validation
bash scripts/validate-security.sh || exit 1
echo "✓ Security standards passed"

# Build docs site (verify no build errors)
cd website/docs && npm ci && npm run build && cd ../..
echo "✓ Docs site builds successfully"

Expected: All checks pass (CI will run same checks)

HARD STOP 3: Version Bump Confirmation

Show complete atomic operation result:

Version Bump Complete
─────────────────────
Version: 6.3.0 ✓
Files Updated:
  - CHANGELOG.md (new [6.3.0] section with date)
  - docs/roadmap/roadmap.md (version section added)
  - .claude-plugin/plugin.json (version: "6.3.0")
  - .claude-plugin/marketplace.json (version: "6.3.0" × 2)

Git State:
  - Commit: abc1234 (release: 6.3.0 — Add jaan-release skill)
  - Tag: v6.3.0 (local, not pushed)

CI Simulation: ✓ PASS (all checks)

Push to origin and create PR? [y/n/abort]

Options:

```
y
```
→ Continue to Phase 4
```
n
```
→ Show commit details, then re-ask
```
abort
```
→ Rollback

Rollback if aborted:

bash

git tag -d v6.3.0              # Delete local tag
git reset --soft HEAD~1        # Undo commit, keep changes staged
# OR
git reset --hard HEAD~1        # Undo commit and discard all changes

PHASE 4: PR Creation

Purpose: Push changes and create PR for human review.

Step 4.1: Push Branch with Tag

bash

git push origin dev --tags

Expected:

✓ Pushed to origin/dev
✓ Pushed tag v6.3.0

If push fails:

Check network connectivity
Check GitHub authentication:
```
gh auth status
```
Show error, offer retry

Step 4.2: Create PR (dev → main)

bash

gh pr create --base main \
  --title "release: 6.3.0 — Add jaan-release skill" \
  --body "$(cat <<'EOF'
## Release Summary
Add jaan-release skill for automated release preparation.

## Changes This Release
### Added
- jaan-release skill for release automation
- Compliance validation (10-item checklist)
- Documentation sync automation

### Changed
- (list from CHANGELOG [6.3.0] section)

### Fixed
- (list from CHANGELOG [6.3.0] section)

## Pre-Merge Checklist
- [x] All 24 validation checks passed locally
- [x] Security standards validation passed
- [x] Documentation synced and up to date
- [x] CHANGELOG entry complete
- [x] Version bumped in all 3 locations
- [x] CI simulation passed locally
- [ ] CI checks pass on GitHub (wait for workflow)
- [ ] Human review approved

## Post-Merge Steps
After merging this PR:
1. **Tag on main**: \`git checkout main && git pull && git tag v6.3.0 && git push origin main --tags\`
2. **Create release**: \`gh release create v6.3.0 --title "v6.3.0" --notes-file CHANGELOG.md\`
3. **Sync dev**: \`git checkout dev && git merge main && git push\`
4. **Bump dev**: \`./scripts/bump-version.sh 6.4.0 && git commit -am "chore: bump to 6.4.0" && git push\`
5. **Acknowledge issues**: For each closed issue in this release, run \`/jaan-issue-solve #{issue_number}\`

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

Expected:

✓ PR created: https://github.com/parhumm/jaan-to/pull/123

Step 4.3: Monitor CI Checks

bash

gh pr checks --watch

Show CI status:

CI Checks:
  - release-check.yml: ✓ PASSED (2m 15s)
  - deploy-docs.yml: ⏳ Running...

If CI fails:

Show error logs:
```
gh run view <run-id> --log
```
Suggest fixes based on error type
User can push fixes to same branch

HARD STOP 4: PR Created — Human Takes Over

Show final status:

PR Created Successfully
───────────────────────
URL: https://github.com/parhumm/jaan-to/pull/123
Status: Waiting for CI checks

CI Checks:
  - release-check.yml: ✓ PASSED
  - deploy-docs.yml: ✓ PASSED

Next Steps (Manual):
1. Review PR at URL above
2. Approve and merge PR (via GitHub UI or gh pr merge)
3. Follow "Post-Merge Steps" in PR description

SKILL COMPLETE - Human merge required.

Skill exits here. Human performs:

PR review and approval
Merge to main
Tag creation on main (not dev)
GitHub release publication
Dev branch sync and version bump
Issue acknowledgments via
```
/jaan-issue-solve
```

Definition of Done

All 24 validation checks passed
Documentation synced (roadmap, docs, website, CHANGELOG)
Version bumped atomically (4 files + commit + tag)
CI simulation passed locally
PR created (dev → main)
CI checks passed on GitHub
Human review and merge (manual)
Post-merge steps (tag, release, sync, bump - manual)
Issue acknowledgments (manual)

Skill Alignment

Aligns with jaan-to principles:

✅ Two-phase workflow with HARD STOP gates (4 gates)
✅ Single source of truth (validation logic in
```
.claude/scripts/
```
)
✅ Reuses existing skills (pm-roadmap-update, docs-update, release-iterate-changelog)
✅ Token-optimized (orchestrates, doesn't duplicate)
✅ Maintains human control (stops at PR creation)
✅ Generic and scalable (works for any version)
✅ LOCAL skill (not distributed to users)

Error Handling

Common issues:

Dirty working tree → Block at Phase 1, show uncommitted files
Version already exists → Block at Phase 3, suggest next version
CI workflow failure → Show logs, continue (user fixes manually)
Merge conflict on PR → Show conflicting files, continue (user resolves)
GitHub CLI not authenticated → Block at Phase 4, show
```
gh auth login
```
instructions
Documentation build failure → Block at Phase 3, show npm error

Rollback at each gate:

Phase 1: None needed (read-only)
Phase 2:
```
git restore <files>
```

Phase 3:

git tag -d v6.3.0 && git reset --hard HEAD~1

Phase 4:

gh pr close <PR> && git push origin :v6.3.0

Local Development Only

This skill is LOCAL to jaan-to repository:

Location:
```
.claude/skills/jaan-release/
```
Not in
```
skills/
```
(not distributed to users)
References LOCAL scripts in
```
.claude/scripts/
```
Only jaan-to maintainers have access

Users don't see this skill when they install jaan-to plugin.

jaan-release

NPX Install

Tags

SKILL.md Content

jaan-release

What This Does

Input

Pre-Execution Protocol

PHASE 1: Pre-Release Validation

Step 1.1: Run Validation Scripts

Step 1.2: Aggregate Results

HARD STOP 1: Validation Report

PHASE 2: Documentation & Version Prep

Step 2.1: Roadmap Sync

Step 2.2: Documentation Auto-Fix

Step 2.3: Website Update (ENHANCED)

Step 2.4: Changelog Generation

HARD STOP 2: Review Prepared Changes

PHASE 3: Atomic Version Bump

Step 3.1: Determine Target Version

Step 3.2: Atomic Version Bump

Step 3.3: CI Simulation (Local Validation)

HARD STOP 3: Version Bump Confirmation

PHASE 4: PR Creation

Step 4.1: Push Branch with Tag

Step 4.2: Create PR (dev → main)

Step 4.3: Monitor CI Checks

HARD STOP 4: PR Created — Human Takes Over

Definition of Done

Skill Alignment

Error Handling

Local Development Only