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:

1. ✅ Validates 24 compliance & plugin standards checks
2. 📝 Syncs documentation (roadmap, docs, website, changelog)
3. 🔢 Bumps version atomically across 4 files
4. 🚀 Creates release PR (dev → main)
5. ⏸️ 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:

# 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 .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:

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:

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:

1. Moves CHANGELOG [Unreleased] → [6.3.0] with date
2. Creates roadmap version section with tasks from this release
3. Updates .claude-plugin/plugin.json → "version": "6.3.0"
4. Updates .claude-plugin/marketplace.json → 2 version fields
5. Creates commit: release: 6.3.0 — Add jaan-release skill
6. 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:

# 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:

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

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)

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

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:

1. Dirty working tree → Block at Phase 1, show uncommitted files
2. Version already exists → Block at Phase 3, suggest next version
3. CI workflow failure → Show logs, continue (user fixes manually)
4. Merge conflict on PR → Show conflicting files, continue (user resolves)
5. GitHub CLI not authenticated → Block at Phase 4, show gh auth login instructions
6. 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.