sequant 2.6.2 → 2.8.0

package/dist/marketplace/external_plugins/sequant/skills/release/SKILL.md

@@ -0,0 +1,661 @@
+---
+name: release
+description: "Automates the full release workflow: version bump, git tag, GitHub release, and npm publish."
+license: MIT
+metadata:
+  author: sequant
+  version: "1.0"
+allowed-tools:
+  - Read
+  - Bash(npm test:*)
+  - Bash(npm run build:*)
+  - Bash(npm version:*)
+  - Bash(npm pack:*)
+  - Bash(npm publish:*)
+  - Bash(npm whoami:*)
+  - Bash(npm view:*)
+  - Bash(npm audit:*)
+  - Bash(git status:*)
+  - Bash(git branch:*)
+  - Bash(git fetch:*)
+  - Bash(git log:*)
+  - Bash(git add:*)
+  - Bash(git commit:*)
+  - Bash(git tag:*)
+  - Bash(git push:*)
+  - Bash(gh auth status:*)
+  - Bash(gh release create:*)
+  - Bash(gh release view:*)
+---
+
+<!-- sequant:local-override -->
+> **Local overrides (read this first).** Before following any instruction below, check whether `.claude/.local/skills/release/overrides.md` exists. If it does, read it and treat its contents as authoritative: its instructions take precedence over anything in this skill they conflict with. This is the supported way to tailor `/release` without forking it — `overrides.md` lives under `.claude/.local/`, which `sequant update` and `sync` never overwrite.
+
+# Release Skill
+
+Automates the full release workflow: version bump, git tag, GitHub release, and npm publish.
+
+## Usage
+
+```
+/release [patch|minor|major] [--prerelease <tag>] [--dry-run]
+```
+
+- `/release` - Interactive, asks for version type
+- `/release patch` - Patch release (1.3.1 → 1.3.2)
+- `/release minor` - Minor release (1.3.1 → 1.4.0)
+- `/release major` - Major release (1.3.1 → 2.0.0)
+- `/release minor --prerelease beta` - Pre-release (1.3.1 → 1.4.0-beta.0)
+- `/release --dry-run` - Preview without publishing
+
+## Pre-flight Checks
+
+Run ALL checks before proceeding. **STOP if any fails.**
+
+### Git Checks
+
+```bash
+# 1. On main branch
+[ "$(git branch --show-current)" = "main" ] || { echo "Not on main"; exit 1; }
+
+# 2. Clean working tree
+[ -z "$(git status --porcelain)" ] || { echo "Uncommitted changes"; exit 1; }
+
+# 3. In sync with remote
+git fetch origin
+[ -z "$(git log HEAD..origin/main)" ] || { echo "Behind origin - pull first"; exit 1; }
+```
+
+### Quality Checks
+
+```bash
+# 4. Tests pass
+npm test
+
+# 5. Build works
+npm run build
+
+# 6. No security vulnerabilities (high/critical)
+npm audit --audit-level=high || echo "Warning: audit issues found"
+```
+
+### npm Checks
+
+```bash
+# 7. Logged into npm
+npm whoami || { echo "Not logged in - run: npm login"; exit 1; }
+
+# 8. Version doesn't already exist
+pkg_name=$(node -p "require('./package.json').name")
+current=$(node -p "require('./package.json').version")
+npm view "${pkg_name}@${current}" version 2>/dev/null && { echo "Version already published"; exit 1; }
+
+# 9. Preview package contents
+npm pack --dry-run 2>&1 | tail -20
+```
+
+### GitHub Checks
+
+```bash
+# 10. Authenticated with GitHub
+gh auth status || { echo "Not logged in - run: gh auth login"; exit 1; }
+```
+
+### Documentation Checks
+
+> **Note:** Documentation freshness checks that compare against the version *being released* run **after** Step 4 (the version bump), not here in pre-flight:
+> - `docs/internal/what-weve-built.md` title + ASCII version stamps → **Step 4.63**
+> - `CHANGELOG.md` freshness (version entry present) → **Step 4.65**
+> - `README.md` "What's new in <minor>" heading freshness → **Step 4.66**
+>
+> They must compare against the *new* version, which doesn't exist in `package.json` until Step 4 runs. Running them in pre-flight would compare against the *previous* release — which the docs already reflect — so the gate would never fire for the release in progress (root cause class of #684 / #687).
+
+## Release Steps
+
+### Step 1: Determine Version
+
+If version type not provided as argument, ask the user:
+
+| Type | When to Use | Example |
+|------|-------------|---------|
+| `patch` | Bug fixes, maintenance, no new features | 1.3.1 → 1.3.2 |
+| `minor` | New features, backwards compatible | 1.3.1 → 1.4.0 |
+| `major` | Breaking changes | 1.3.1 → 2.0.0 |
+| `prerelease` | Alpha/beta/RC versions | 1.3.1 → 1.4.0-beta.0 |
+
+```bash
+current=$(node -p "require('./package.json').version")
+echo "Current version: ${current}"
+```
+
+### Step 2: Generate Release Notes
+
+Gather commits since last tag:
+```bash
+last_tag=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+if [ -n "$last_tag" ]; then
+  git log ${last_tag}..HEAD --oneline --no-merges
+fi
+```
+
+Categorize by conventional commit prefix:
+- `feat:` → **Features**
+- `fix:` → **Bug Fixes**
+- `perf:` → **Performance**
+- `docs:` → **Documentation**
+- `refactor:` → **Refactoring**
+- `chore:` → **Maintenance**
+- `BREAKING CHANGE:` → **Breaking Changes** (for major releases)
+
+**Release notes template:**
+```markdown
+## What's Changed
+
+### Features
+- Feature description (#PR)
+
+### Bug Fixes
+- Fix description (#PR)
+
+### Breaking Changes
+- Description of breaking change and migration path
+
+**Full Changelog**: https://github.com/sequant-io/sequant/compare/v{old}...v{new}
+```
+
+**Show draft to user for approval before proceeding.**
+
+### Step 3: Update CHANGELOG.md (if exists)
+
+If `CHANGELOG.md` exists, use the **Edit tool** to:
+
+1. Replace `## [Unreleased]` with `## [{new_version}] - {YYYY-MM-DD}`
+2. Insert a fresh `## [Unreleased]` section above the newly stamped version:
+
+```markdown
+## [Unreleased]
+
+## [1.4.0] - 2026-01-10
+
+### Added
+- New feature X
+...
+```
+
+This ensures the next development cycle has an `[Unreleased]` section ready for contributors.
+
+### Step 4: Bump Version
+
+```bash
+# For regular releases
+npm version {patch|minor|major} --no-git-tag-version
+
+# For pre-releases
+npm version prerelease --preid=beta --no-git-tag-version
+```
+
+### Step 4.5: Sync Plugin Version
+
+**IMPORTANT:** Keep plugin.json in sync with package.json.
+
+Use the **Read tool** to read `.claude-plugin/plugin.json`, then use the **Edit tool** to update the version field:
+
+```
+Read(file_path=".claude-plugin/plugin.json")
+
+Edit(file_path=".claude-plugin/plugin.json",
+     old_string="\"version\": \"<old_version>\"",
+     new_string="\"version\": \"<new_version>\"")
+```
+
+If `.claude-plugin/plugin.json` does not exist, skip this step.
+
+**Why sync?** Sequant is distributed as both npm package and Claude Code plugin. Both must have matching versions to avoid user confusion and ensure compatibility.
+
+### Step 4.6: Update what-weve-built.md
+
+**IMPORTANT:** Keep `docs/internal/what-weve-built.md` version references in sync and document new features.
+
+Get the new version, then use the Edit tool to update the file:
+
+```bash
+new_version=$(node -p "require('./package.json').version")
+```
+
+Then use the **Edit tool** (not sed) to update `docs/internal/what-weve-built.md`:
+
+```
+# Update title version - use Edit tool with replace_all=true
+Edit(file_path="docs/internal/what-weve-built.md",
+     old_string="Sequant v<old_version>",
+     new_string="Sequant v${new_version}",
+     replace_all=true)
+
+# Update ASCII art version - use Edit tool with replace_all=true
+Edit(file_path="docs/internal/what-weve-built.md",
+     old_string="SEQUANT v<old_version>",
+     new_string="SEQUANT v${new_version}",
+     replace_all=true)
+
+# Update "Current Version" line - use Edit tool
+Edit(file_path="docs/internal/what-weve-built.md",
+     old_string="**Current Version:** <old_version>",
+     new_string="**Current Version:** ${new_version}")
+```
+
+**Auto-generate feature bullets from CHANGELOG:**
+
+Extract features from the `[Unreleased]` section of CHANGELOG.md:
+
+```bash
+# Extract [Unreleased] entries from CHANGELOG.md
+if [ -f "CHANGELOG.md" ]; then
+  # Get content between [Unreleased] and next version header
+  unreleased_content=$(sed -n '/^## \[Unreleased\]/,/^## \[/p' CHANGELOG.md | head -n -1)
+
+  # Extract Added entries (these become what-weve-built features)
+  added_entries=$(echo "$unreleased_content" | sed -n '/^### Added/,/^### /p' | grep -E '^\s*-' | head -n -1 || true)
+
+  if [ -n "$added_entries" ]; then
+    echo "Features to add to what-weve-built.md:"
+    echo "$added_entries"
+  else
+    echo "No new features in [Unreleased] section"
+  fi
+fi
+```
+
+**If CHANGELOG has features**, use the Edit tool to update `docs/internal/what-weve-built.md`:
+
+1. **Update the "Recent Additions" section header:**
+   ```
+   Edit(file_path="docs/internal/what-weve-built.md",
+        old_string="### Recent Additions (v<old_version>)",
+        new_string="### Recent Additions (v${new_version})")
+   ```
+
+2. **Add feature bullets under "Recent Additions":**
+   Transform CHANGELOG entries to what-weve-built format:
+
+   | CHANGELOG Format | what-weve-built Format |
+   |------------------|------------------------|
+   | `- Feature description (#123)` | `- **Feature Name** - Brief description` |
+   | `- Multi-line feature (#123)\n  - Sub-detail` | `- **Feature Name** - Brief description` |
+
+   Example transformation:
+   ```markdown
+   # From CHANGELOG:
+   - CHANGELOG update step in /exec skill (#320)
+     - Instructs /exec to add [Unreleased] entries during feature commits
+
+   # To what-weve-built:
+   - **CHANGELOG Automation** - Automatic CHANGELOG entry requirements in /exec and /qa
+   ```
+
+3. **Update counts in "At a Glance" table** if applicable:
+   - New skill added → increment skill count
+   - New command added → increment command count
+   - New MCP integration → increment integration count
+
+**Fallback to commit-based detection:**
+
+If CHANGELOG.md doesn't exist or has no `[Unreleased]` section, fall back to commit-based detection:
+
+```bash
+last_tag=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+if [ -n "$last_tag" ]; then
+  echo "New features since ${last_tag}:"
+  git log ${last_tag}..HEAD --oneline --no-merges | grep -E "^[a-f0-9]+ feat" || echo "  (none)"
+fi
+```
+
+**Ask the user to review what-weve-built.md before proceeding** if there are new features to document.
+
+### Step 4.63: Verify what-weve-built.md Version Stamps
+
+**IMPORTANT:** This runs **after** Step 4 (version bump) and Step 4.6 (which updates the stamps), so `package.json` already holds the *new* version. Running it earlier (in pre-flight) would compare against the previous release — which the file already reflects — so the gate would never fire for the version actually being released (root cause class of #684 / #687, the same ordering bug fixed for the README check in #685).
+
+Warn-only (like the CHANGELOG freshness check): prompt the releaser if the title or ASCII-art version stamp omits/mismatches the version being released.
+
+```bash
+# Warn if docs/internal/what-weve-built.md version stamps don't match the version being released
+if [ -f "docs/internal/what-weve-built.md" ]; then
+  new_version=$(node -p "require('./package.json').version")
+
+  # Check title version
+  title_version=$(grep -oE "Sequant v[0-9]+\.[0-9]+\.[0-9]+" docs/internal/what-weve-built.md | head -1 | grep -oE "[0-9]+\.[0-9]+\.[0-9]+" || true)
+  if [ "$title_version" != "$new_version" ]; then
+    echo "Warning: docs/internal/what-weve-built.md title shows v${title_version}, expected v${new_version}"
+  fi
+
+  # Check ASCII art version
+  ascii_version=$(grep -E "SEQUANT v[0-9]+\.[0-9]+\.[0-9]+" docs/internal/what-weve-built.md | grep -oE "[0-9]+\.[0-9]+\.[0-9]+" || true)
+  if [ "$ascii_version" != "$new_version" ]; then
+    echo "Warning: docs/internal/what-weve-built.md ASCII art shows v${ascii_version}, expected v${new_version}"
+  fi
+fi
+```
+
+### Step 4.65: Verify CHANGELOG Freshness
+
+**IMPORTANT:** This runs **after** Step 4 (version bump) so `package.json` already holds the *new* version. Running it earlier (in pre-flight) would compare against the previous release, which the CHANGELOG already lists — so the gate would never fire for the version actually being released (root cause class of #684).
+
+**Note (#701):** #694 moved the changelog wall out of `README.md` into `CHANGELOG.md` and removed the README "What's new" section, so this gate now checks `CHANGELOG.md` (the source of truth). Grepping `README.md` for a now-absent `# What's new` heading made the warn-only gate fire on every release.
+
+Warn-only (like the what-weve-built checks): prompt the releaser to add a `CHANGELOG.md` entry if the new version is absent.
+
+```bash
+# Warn if CHANGELOG.md omits the version being released
+if [ -f "CHANGELOG.md" ]; then
+  new_version=$(node -p "require('./package.json').version")
+
+  # Match the Keep-a-Changelog heading for this version, e.g. "## [2.4.0] - 2026-05-30"
+  if ! grep -qF "[${new_version}]" CHANGELOG.md; then
+    echo "Warning: CHANGELOG.md omits v${new_version} — add a \"## [${new_version}]\" entry before releasing"
+  fi
+fi
+```
+
+### Step 4.66: Verify README "What's new" Freshness
+
+**IMPORTANT:** This runs **after** Step 4 (version bump) so `package.json` already holds the *new* version. Running it earlier (in pre-flight) would compare against the previous release — which the README already reflects — so the gate would never fire for the version actually being released (root cause class of #684 / #687, the same ordering bug fixed for the README check in #685).
+
+**Note (#702 / #707):** This gate owns the hand-written `### What's new in <major>.<minor>` positioning section that #702 re-added to `README.md` — distinct from the changelog wall that #694 moved to `CHANGELOG.md` (covered by Step 4.65). It keys on the **minor** line, not a full semver: "What's new in 2.6" is correct for the entire 2.6.x line, so a **patch** release (2.6.0 → 2.6.1) does NOT fire against a matching heading. During v2.6.0 the heading still read "What's new in 2.5" and shipped stale (fixed manually in 18c2d42); this gate flags that case.
+
+Warn-only (like the CHANGELOG freshness check): prompt the releaser if the README's latest "What's new" heading lags the minor line being released. No README edit is auto-applied — the section's content and positioning are an editorial decision.
+
+```bash
+# Warn if README.md's latest "What's new" heading lags the minor line being released.
+# Keys on the MINOR line (e.g. "2.6"), so a patch release against a matching heading stays silent.
+if [ -f "README.md" ]; then
+  new_version=$(node -p "require('./package.json').version")
+  new_minor=$(echo "$new_version" | grep -oE '^[0-9]+\.[0-9]+')
+
+  # Anchor to a markdown heading (^#+) so a "What's new in X.Y" mention in prose can't be read as
+  # the section, and take the numerically-highest minor (sort -t. then tail -1) so the result is
+  # independent of heading order in the file rather than assuming newest-first.
+  readme_minor=$(grep -oE "^#+[[:space:]]+What's new in [0-9]+\.[0-9]+" README.md \
+    | grep -oE '[0-9]+\.[0-9]+' | sort -t. -k1,1n -k2,2n | tail -1 || true)
+
+  # The -n guard is load-bearing: if the section is ever removed again (as #694 did),
+  # this gate stays silent rather than firing on every release (the bug #701 fixed for the old gate).
+  if [ -n "$readme_minor" ] && [ "$readme_minor" != "$new_minor" ]; then
+    echo "Warning: README.md 'What's new' section is for $readme_minor, expected $new_minor — add/update the heading before releasing"
+  fi
+fi
+```
+
+### Step 4.7: Regenerate Marketplace Artifact
+
+**IMPORTANT:** The marketplace plugin artifact under `dist/marketplace/` is bundled into the published tgz via `files: ["dist", ...]` in package.json — even though `dist/` is gitignored. Regenerate it from current sources **before** packing/publishing so the bundled README always matches; otherwise a stale artifact ships (root cause of #684 — the v2.4.0 tgz carried a "Node.js 20+" README after the floor moved to 22.12).
+
+This is an action step, so it lives in Release Steps (not the read-only pre-flight checks). It MUST run before Step 5 (`npm pack`) and Step 9 (`npm publish`).
+
+```bash
+# Regenerate the marketplace plugin artifact from current sources
+npm run prepare:marketplace
+
+# Freshness sanity check: generated README's Node.js floor should match package.json engines.
+# Warn-only (regeneration above already fixes the artifact; this is a belt-and-suspenders signal).
+gen_readme="dist/marketplace/external_plugins/sequant/README.md"
+if [ -f "$gen_readme" ]; then
+  engines_floor=$(node -p "require('./package.json').engines.node.replace(/[^0-9.]/g,'')")  # e.g. 22.12.0
+  readme_floor=$(grep -oE "Node\.js [0-9]+\.[0-9]+" "$gen_readme" | head -1 | grep -oE "[0-9]+\.[0-9]+" || true)
+  if [ -n "$readme_floor" ] && [ "${engines_floor%.*}" != "$readme_floor" ]; then
+    echo "Warning: generated marketplace README shows Node.js ${readme_floor}, package.json engines floor is ${engines_floor}"
+  fi
+fi
+```
+
+### Step 5: Verify Package Size
+
+```bash
+# Check what will be published
+npm pack --dry-run
+
+# Verify size is reasonable (warn if > 500KB)
+size=$(npm pack --dry-run 2>&1 | grep "total files" -A1 | tail -1 || true)
+echo "Package size: ${size}"
+```
+
+### Step 6: Commit and Push
+
+```bash
+new_version=$(node -p "require('./package.json').version")
+git add package.json package-lock.json CHANGELOG.md .claude-plugin/plugin.json .claude-plugin/marketplace.json docs/internal/what-weve-built.md
+git commit -m "chore: release v${new_version}"
+git push origin main
+```
+
+### Step 7: Create and Push Tag
+
+```bash
+git tag -a "v${new_version}" -m "Release v${new_version}"
+git push origin "v${new_version}"
+```
+
+### Step 8: Create GitHub Release
+
+```bash
+# Regular release
+gh release create "v${new_version}" \
+  --title "v${new_version} - {title}" \
+  --notes "{release_notes}"
+
+# Pre-release (alpha/beta/rc)
+gh release create "v${new_version}" \
+  --title "v${new_version}" \
+  --notes "{release_notes}" \
+  --prerelease
+```
+
+For the title, use a short summary:
+- `v1.4.0 - New Feature Name`
+- `v1.3.2 - Bug Fix Release`
+- `v2.0.0 - Breaking Changes`
+
+### Step 9: Publish to npm
+
+Attempt to publish:
+
+```bash
+# Regular release
+npm publish
+
+# Pre-release with tag (prevents becoming "latest")
+npm publish --tag beta
+```
+
+**If npm returns `EOTP` (2FA required):**
+
+Non-interactive environments cannot handle the OTP prompt. Ask the user to publish manually:
+
+```
+npm publish --otp=<code>
+```
+
+Do NOT attempt to pass OTP codes programmatically or retry `npm publish` in a loop. Hand off to the user and continue with post-release verification once they confirm.
+
+## Post-Release Verification
+
+Verify both platforms show the new version:
+
+```bash
+# npm verification (may take 1-2 minutes to propagate)
+sleep 5
+npm view sequant version
+npm view sequant dist-tags
+
+# GitHub verification
+gh release view "v${new_version}"
+
+# Test install
+npx sequant@${new_version} --version
+```
+
+## Output Summary
+
+```
+Release v{version} Complete
+
+  Version:  {old} → {new}
+  Commit:   {hash}
+  Tag:      v{new}
+
+  GitHub:   https://github.com/sequant-io/sequant/releases/tag/v{new}
+  npm:      https://www.npmjs.com/package/sequant/v/{new}
+  Plugin:   Version synced in .claude-plugin/plugin.json
+  Docs:     Version synced in docs/internal/what-weve-built.md
+
+  Install (npm):
+    npm install sequant@{new}
+    npx sequant@{new}
+
+  Install (plugin):
+    /plugin marketplace update sequant-io/sequant
+    /plugin install sequant
+
+Verification:
+  [x] npm view shows correct version
+  [x] GitHub release created
+  [x] Tag pushed
+  [x] plugin.json version synced
+  [x] what-weve-built.md version synced
+  [x] New features documented (if any)
+
+Next steps:
+  - Announce release (if major/minor)
+  - Update dependent projects
+  - Monitor for issues
+```
+
+## Dry Run Mode
+
+When `--dry-run` is specified:
+
+1. Run all pre-flight checks
+2. Show what version would be created
+3. Show draft release notes
+4. Show `npm pack --dry-run` output
+5. **Do NOT** execute any publish commands
+
+```
+Dry Run Summary
+
+  Would release: 1.3.1 → 1.4.0
+
+  Package contents:
+    - 176 files
+    - 195.9 kB packed
+
+  Release notes:
+    [draft notes here]
+
+  To execute: /release minor
+```
+
+## Rollback Procedures
+
+### Before npm publish
+
+```bash
+# Undo version bump (if not committed)
+git checkout -- package.json package-lock.json
+
+# Undo commit (if not pushed)
+git reset --soft HEAD~1
+
+# Delete local tag
+git tag -d v{version}
+```
+
+### After git push, before npm publish
+
+```bash
+# Delete remote tag
+git push origin :refs/tags/v{version}
+
+# Delete GitHub release
+gh release delete v{version} --yes
+
+# Revert commit
+git revert HEAD
+git push origin main
+```
+
+### After npm publish
+
+**Do NOT use `npm unpublish`** - it breaks dependent projects.
+
+Instead:
+1. Publish a patch fix: `npm version patch && npm publish`
+2. Deprecate bad version: `npm deprecate sequant@{bad} "Use {good} instead"`
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| "Not on main" | Wrong branch | `git checkout main` |
+| "Uncommitted changes" | Dirty working tree | `git stash` or commit |
+| "Behind origin" | Remote has new commits | `git pull origin main` |
+| "Tests failed" | Failing tests | Fix tests first |
+| "Version exists" | Already published | Choose different version |
+| "Not logged in (npm)" | npm auth expired | `npm login` |
+| "Not logged in (gh)" | GitHub auth expired | `gh auth login` |
+| "OTP required" | npm 2FA enabled | Enter code when prompted |
+| "Package too large" | Bloated package | Check `.npmignore` |
+
+## Best Practices
+
+### Versioning
+- Follow [Semantic Versioning](https://semver.org/)
+- Use pre-release tags for testing: `1.4.0-beta.1`
+- Major version 0.x.x indicates unstable API
+
+### Release Notes
+- Write for users, not developers
+- Highlight breaking changes prominently
+- Include migration guides for major releases
+- Link to relevant issues/PRs
+
+### npm
+- Keep package size small (< 500KB ideal)
+- Use `files` in package.json or `.npmignore`
+- Test with `npm pack` before publishing
+- Use `--tag` for pre-releases to avoid becoming "latest"
+
+### GitHub
+- Use pre-release flag for beta/RC versions
+- Attach relevant assets (if any)
+- Use consistent title format
+
+### Security
+- Run `npm audit` before releasing
+- Don't include sensitive files (check `npm pack --dry-run`)
+- Verify `npm whoami` shows correct account
+
+## Examples
+
+### Standard Patch Release
+```
+/release patch
+```
+
+### Minor Release with Custom Notes
+```
+/release minor
+# Review generated notes
+# Edit if needed
+# Approve to publish
+```
+
+### Beta Pre-release
+```
+/release minor --prerelease beta
+```
+Creates: `1.4.0-beta.0`
+
+### Preview Without Publishing
+```
+/release minor --dry-run
+```