openclacky 1.0.5 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 597ea8fc84ca69641339dbacf724e114d4fc7c5c43bcafb81767bcb83da89edd
-  data.tar.gz: 23f576f36023978f37dfe68e12ec942e3cedd591bec1cd098a5829a8d9057a24
+  metadata.gz: e897a7568d8b457d317c56ff402a76c1907b4a158e0e7382586e2b66115ee0f7
+  data.tar.gz: 5fbeb452695441035d7f7d4f7ba1f0ef63dbb198daebb17600eb6e9f9fb72c46
 SHA512:
-  metadata.gz: 0fed807f559eee7d3df5508bbef61d45f75a0943c5d76ac17cbf9a334bfc75be729ad6ab03485211c532de186b1f41aa27c54267f2e36efa7c191699e3fcca2e
-  data.tar.gz: c8943553c4cd0f721515e0ffad5aa554dcdffc0305aca6d7ac403a02762b59db63273415d452965767b0bd2157ab835c946b081e99b0ce5a8574a3bf622e6aa1
+  metadata.gz: 64d4764470f2f8bac52e7e8233afbf441336c8a81238def9800cf6735a90798435cc8d43e9056aa4c6e53f51760067e57b5b2670263339590b7f9fd744cc6920
+  data.tar.gz: c27a2313d3595adcb48a66e396c9eec8947550132a74bb5b8535b11d93e639b240bc1dafeab0a7bf9b4af665c2fa6a22630f8b23ab0061b2de4ebbfcae1f3299

data/.clacky/skills/gem-release/SKILL.md

@@ -1,5 +1,4 @@
 ---
----
 name: gem-release
 description: >-
   Automates the complete process of releasing a new version of the openclacky Ruby
@@ -12,237 +11,66 @@ user-invocable: true
 
 # Gem Release Skill
 
-This skill automates the complete process of releasing a new version of the openclacky Ruby gem.
-
-## Overview
-
-This skill handles the entire gem release workflow from version bumping to publishing on RubyGems and creating GitHub releases.
+Automates the complete openclacky gem release workflow via `SKILL_DIR/scripts/release.sh`.
 
 ## Usage
 
-To use this skill, simply say:
 - "Release a new version"
 - "Publish a new gem version"
 - "Release version 1.0.0.beta.1" (pre-release with explicit version)
-- Use the command: `/gem-release`
-
-## Process Steps
-
-### 1. Pre-Release Checks
-- Check for uncommitted changes in the working directory
-- Verify all tests pass before proceeding
-- Ensure the repository is in a clean state
-
-### 2. Version Management
-
-**Stable releases (default):**
-- Read current version from `lib/clacky/version.rb`
-- Increment version number (typically patch version: x.y.z → x.y.z+1)
-- Update the VERSION constant in the version file
-
-**Pre-release versions (when user specifies a version like `1.0.0.beta.1`):**
-- Accept the user-provided version string directly — do NOT auto-increment
-- The version must follow semver pre-release format: `X.Y.Z-<identifier>` or `X.Y.Z.<identifier>` (e.g., `1.0.0.beta.1`, `2.0.0-alpha`, `1.5.0-rc1`)
-- Before proceeding, warn the user about pre-release caveats (see Pre-Release Caveats below)
-
-### 2a. Pre-Release Caveats
-
-When releasing a pre-release version, inform the user of these known behaviors in the Clacky ecosystem:
-
-| Concern | Behavior | Impact |
-|---------|----------|--------|
-| **Version check notification** | RubyGems API returns the highest version number, including prereleases. `Gem::Version("0.9.38") < Gem::Version("1.0.0.beta.1")` → `true`. | ✅ The upgrade dot WILL appear in the Web UI for most users. |
-| **`gem update` (official source)** | `gem update openclacky --no-document` does NOT install prereleases without `--pre`. | ❌ Users on official RubyGems source who click "Upgrade" will see the notification but the upgrade will silently do nothing. |
-| **OSS CDN upgrade (mirror users)** | `upgrade_via_oss_cdn` downloads the exact `.gem` from `latest.txt` on OSS. | ⚠️ If you update `latest.txt` to point to the prerelease, mirror users WILL get the beta. |
-| **OSS `latest.txt`** | Stable users fetching `latest.txt` for fresh installs would get the beta. | ⚠️ By default, do NOT update `latest.txt` for pre-releases. Only update if this is intentional (e.g., a release candidate for broad testing). |
-
-**Action**: Ask the user whether to update `latest.txt` on OSS before proceeding. For internal testing, the answer is usually "no".
-
-### 3. Quality Assurance
-- Run the full test suite with `bundle exec rspec`
-- Ensure all 167+ tests pass
-- Verify no regressions introduced
-
-### 4. Build Process
-- Build the gem using `gem build openclacky.gemspec`
-- Generate the `.gem` file for distribution
-- Handle any build warnings appropriately
-
-### 5. Update Gemfile.lock and Verify CI
-
-1. **Update Gemfile.lock**
-   ```bash
-   bundle install
-   ```
-   This ensures Gemfile.lock reflects the new version.
-
-2. **Commit Gemfile.lock Changes**
-   ```bash
-   git add Gemfile.lock
-   git commit -m "chore: update Gemfile.lock to v{version}"
-   ```
-
-3. **Push and Verify CI**
-   ```bash
-   git push origin main
-   ```
-   - Wait for CI pipeline to complete successfully
-   - Verify all tests pass
-   - If CI fails, fix issues before proceeding
-
-4. **Proceed Only After CI Success**
-   - If CI fails: stop, fix issues, and restart the release process
-   - If CI passes: continue to build and publish
+- `/gem-release`
 
-### 6. Build and Publish Gem
+## Workflow
 
-1. **Build the Gem**
-   ```bash
-   gem build openclacky.gemspec
-   ```
-   Generates `openclacky-{version}.gem` file.
-
-2. **Publish to RubyGems.org**
-   ```bash
-   gem push openclacky-{version}.gem
-   ```
-   Verify successful publication.
-
-3. **Create Git Tag and Push**
-   ```bash
-   git tag v{version}
-   git push origin main --tags
-   ```
+The release script (`SKILL_DIR/scripts/release.sh`) handles everything end-to-end:
 
-4. **Create GitHub Release and Upload gem**
+1. Pre-release checks (clean working directory, required tools)
+2. Run test suite (`bundle exec rspec`)
+3. Bump version in `lib/clacky/version.rb`
+4. Update `Gemfile.lock` via `bundle install`
+5. Commit and push to origin, wait for CI
+6. Build gem (`gem build openclacky.gemspec`)
+7. Publish to RubyGems (`gem push`)
+8. Create git tag and push
+9. Create GitHub Release with .gem asset (uses CHANGELOG.md for notes)
+10. Upload .gem to Tencent Cloud OSS CDN
+11. Update `latest.txt` on OSS (stable only, unless `--update-latest`)
+12. Rebuild and sync `scripts/` to OSS
+13. Cleanup build artifacts
 
-   Extract the release notes for this version from CHANGELOG.md, then create a GitHub Release with the .gem file attached.
+## Agent Instructions
 
-   **For stable releases:**
-   ```bash
-   gh release create v{version} \
-     --title "v{version}" \
-     --notes-file /tmp/release_notes_{version}.md \
-     --latest \
-     openclacky-{version}.gem
-   ```
+### 1. Determine version and release type
 
-   **For pre-release versions (e.g., `1.0.0.beta.1`):** use `--prerelease` instead of `--latest`:
-   ```bash
-   gh release create v{version} \
-     --title "v{version}" \
-     --notes-file /tmp/release_notes_{version}.md \
-     --prerelease \
-     openclacky-{version}.gem
-   ```
-
-   Steps:
-   - Parse the CHANGELOG.md section for `[{version}]`
-   - Write it to a temp file (e.g., `/tmp/release_notes_{version}.md`) to avoid shell escaping issues
-   - Run `gh release create` with `--notes-file` **and the .gem file as an asset**
-   - Verify the release appears at: `https://github.com/clacky-ai/openclacky/releases`
+Read current version:
+```bash
+grep 'VERSION =' lib/clacky/version.rb
+```
 
-   > **Prerequisite**: `gh` CLI must be installed (`brew install gh`) and authenticated (`gh auth login`)
+**Stable release (default):** Increment patch version (e.g., `1.0.5` → `1.0.6`). Confirm with user if unsure which part to bump (major/minor/patch).
 
-5. **Sync to Tencent Cloud OSS (CN mirror)**
+**Pre-release:** Use the exact version the user specified (e.g., `2.0.0.beta.1`). Before proceeding, warn about pre-release caveats (see section below).
 
-   After GitHub Release is created, upload the .gem file to OSS so Chinese users can install without hitting GitHub directly.
+### 2. Write CHANGELOG
 
-   ```bash
-   # Upload .gem file (always do this for any release)
-   coscli cp openclacky-{version}.gem cos://clackyai-1258723534/openclacky/openclacky-{version}.gem
-   ```
+This is the one step the agent handles manually — the script does not write changelog entries because it requires reviewing git history and exercising judgment.
 
-   **For stable releases only** — update `latest.txt` so fresh installs and mirror users pick up the new version:
+1. Find the previous version tag:
    ```bash
-   echo "{version}" > /tmp/latest.txt
-   coscli cp /tmp/latest.txt cos://clackyai-1258723534/openclacky/latest.txt
-
-   # Verify
-   curl -fsSL https://oss.1024code.com/openclacky/latest.txt
+   git describe --tags --abbrev=0
    ```
-   Expected output of verify: `{version}`
-
-   **For pre-release versions** — do NOT update `latest.txt` unless the user explicitly requested it. Updating `latest.txt` to a prerelease would cause:
-   - Mirror users clicking "Upgrade" to get the beta via `upgrade_via_oss_cdn`
-   - Fresh installs via the install script to get the beta
-   - Only skip this if the user explicitly wants broad beta distribution
-
-   > **Prerequisite**: `coscli` installed at `/usr/local/bin/coscli` and configured at `~/.cos.yaml`
-
-6. **Sync scripts/ to OSS**
-
-   After updating latest.txt, first rebuild all shell scripts from templates, then sync to OSS:
 
+2. Gather commits since last release:
    ```bash
-   # Step 1: Rebuild .sh files from .sh.cc templates
-   bash scripts/build/build.sh
-
-   # Step 2: Upload each script file to OSS
-   for script in scripts/*; do
-     coscli cp "$script" cos://clackyai-1258723534/clacky-ai/openclacky/main/scripts/$(basename "$script")
-   done
-
-   # Verify one of the key scripts
-   curl -fsSL https://oss.1024code.com/clacky-ai/openclacky/main/scripts/install.sh | head -5
+   git log <previous_tag>..HEAD --oneline
    ```
 
-   This ensures `scripts/install.sh`, `scripts/install_simple.sh`, `scripts/install.ps1`, `scripts/uninstall.sh` and any future scripts are compiled from latest templates and mirrored on OSS.
-
-   > **Prerequisite**: Same `coscli` setup as above
-
-5. **Verify Publication**
-   - Check gem appears on RubyGems.org
-   - Verify version information is correct
-   - Confirm GitHub Release is visible at the releases page
-
-### 6. Documentation - CHANGELOG Writing Process
-
-**Critical Step: Review Commits Before Writing CHANGELOG**
-
-1. **Find Previous Version Tag**
-   - Get the latest version tag (e.g., v0.6.3)
-   - Use `git describe --tags --abbrev=0` or manually identify
-
-2. **Gather All Commits Since Last Release**
-   ```bash
-   git log {previous_tag}..HEAD --oneline
-   git diff {previous_tag}..HEAD --stat
-   ```
-
-3. **Analyze and Categorize Commits**
-   - Review each commit message AND its diff (`git show <hash> --stat`) to understand the actual change
-   - Categorize into:
-     - **Major Features**: User-visible functionality additions
-     - **Improvements**: Performance, UX, architecture enhancements
-     - **Bug Fixes**: Error corrections and issue resolutions
-     - **Changes**: Breaking changes or significant refactoring
-     - **Minor Details**: Small fixes, style changes, trivial updates
-
-   **⚠️ Critical: Do NOT over-merge commits on the same topic**
-
-   It is tempting to group multiple commits under one bullet because they share a theme (e.g., "all about memory"). Resist this — each commit with **independent user-facing value** deserves its own bullet.
-
-   Ask for every commit: *"Does this enable something the user couldn't do before, separate from other commits on this topic?"*
-   - YES → write a separate CHANGELOG bullet
-   - NO (pure refactor, stability fix, threshold tweak) → merge into a related bullet or put in "More"
-
-   **Example of the mistake to avoid:**
-   - `feat: add long-term memory update system` and `feat: skill template context and recall-memory meta injection` are both "about memory", but they describe distinct capabilities:
-     - First: agent writes memories after sessions
-     - Second: skills receive a pre-built index so agent can selectively load only relevant memories
-   - These must be two separate bullets, not one.
-
-   **Sanity check after writing:** Count your `### Added` bullets vs the number of `feat:` commits. If `feat` commits > bullets, you likely merged too aggressively — revisit.
-
-4. **Write CHANGELOG Entries**
-
-   **Format for Significant Items:**
-   ```
-   ## [Version] - Date
+3. Write a new section in `CHANGELOG.md` following this format:
+   ```markdown
+   ## [X.Y.Z] - YYYY-MM-DD
 
    ### Added
-   - Feature description (link to related commits)
+   - Feature description
 
    ### Improved
    - Enhancement description
@@ -250,56 +78,55 @@ When releasing a pre-release version, inform the user of these known behaviors i
    ### Fixed
    - Bug fix description
 
-   ### Changed
-   - Breaking change description
-   ```
-
-   **Format for Minor Items (group under "More"):**
-   ```
    ### More
-   - Minor fix 1
-   - Minor fix 2
+   - Minor items
    ```
 
-5. **Prioritization Rules**:
-   - Place user-facing value at the top
-   - Group related commits together
-   - Skip very trivial commits (typos, minor formatting)
+4. Categorization rules:
+   - Each commit with **independent user-facing value** gets its own bullet — don't over-merge commits sharing a theme
    - Use imperative mood ("Add" not "Added")
+   - Place user-facing value at the top
+   - Skip trivial commits (typos, minor formatting)
+   - Sanity check: count `### Added` bullets vs `feat:` commits — if commits > bullets, you likely merged too aggressively
 
-6. **Example CHANGELOG Section**:
-   ```markdown
-   ## [0.6.4] - 2026-02-03
+5. Commit the changelog:
+   ```bash
+   git add CHANGELOG.md
+   git commit -m "docs: update CHANGELOG for v<version>"
+   ```
 
-   ### Added
-   - Anthropic API support with full Claude model integration
-   - ClaudeCode environment compatibility (ANTHROPIC_API_KEY support)
+### 3. Run the release script
 
-   ### Improved
-   - API client architecture for multi-provider support
-   - Config loading with source tracking
+**Stable release:**
+```bash
+bash "SKILL_DIR/scripts/release.sh" <version>
+```
 
-   ### Fixed
-   - Handle absolute paths correctly in glob tool
+**Pre-release (skip latest.txt):**
+```bash
+bash "SKILL_DIR/scripts/release.sh" <version> --prerelease
+```
 
-   ### More
-   - Update dependencies
-   - Minor style adjustments
-   ```
+**Pre-release (update latest.txt — only if user explicitly requested):**
+```bash
+bash "SKILL_DIR/scripts/release.sh" <version> --prerelease --update-latest
+```
 
-7. **Commit and Push Documentation Updates**
-   - Commit CHANGELOG.md changes
-   - Push to remote repository
+**Dry run (preview only):**
+```bash
+bash "SKILL_DIR/scripts/release.sh" <version> --dry-run
+```
+
+The script runs all steps sequentially and stops on any failure. Monitor the output — if a step fails, diagnose and fix before retrying.
 
-### 7. Final Summary
+### 4. Present release summary
 
-Present a clear, user-facing release summary after all steps complete:
+After the script completes successfully, present this summary:
 
-**Format:**
 ```
 🎉 v{version} released successfully!
 
-✨ Highlight: [One sentence summarizing the biggest user-visible change in this release — use "verb + value" phrasing]
+✨ Highlight: [One sentence — the biggest user-visible change, verb + value phrasing]
 
 📦 What's new for users:
 
@@ -316,7 +143,6 @@ Present a clear, user-facing release summary after all steps complete:
 | Feature | How to verify |
 |---------|--------------|
 | [key new feature] | [concrete steps to test] |
-...
 
 🔗 Links:
 - RubyGems: https://rubygems.org/gems/openclacky/versions/{version}
@@ -324,137 +150,54 @@ Present a clear, user-facing release summary after all steps complete:
 
 ⬆️ Upgrade:
 - In the Clacky UI, click "Upgrade" in the bottom-left → detect new version → click upgrade → done
-- Manual upgrade (CLI): `gem update openclacky`
+- Manual upgrade (CLI): gem update openclacky
 
 🆕 Fresh install:
 /bin/bash -c "$(curl -sSL https://raw.githubusercontent.com/clacky-ai/openclacky/main/scripts/install.sh)"
 ```
 
-**Rules for writing the summary:**
-- Highlight: pick the single most impactful user-visible change, use "verb + value" phrasing, e.g. "Real browser control + WeChat channel support — agents can now navigate pages and chat via WeChat"
-- Write from the user's perspective — what can they now do, or what problem is now fixed
-- Avoid technical jargon (no "cursor-paginated", "frontmatter", "REST API" — explain what it means instead)
+Summary writing rules:
+- Write from the user's perspective — what they can now do, or what problem is fixed
+- Avoid technical jargon; explain what things mean
 - Skip "More" / chore items unless they directly affect users
 - Keep each bullet to one sentence, action-oriented
-- Example translation: `fix: expand ~ in file system tools path arguments` → "File paths starting with `~` (home directory) now work correctly in all file tools"
-- Testing suggestions: list only significant new features (3–8 items), each with concrete, actionable verification steps
+- Testing suggestions: 3–8 items with concrete, actionable verification steps
 
-## Commands Used
+## Pre-Release Caveats
 
-```bash
-# Pre-release checks
-git status --porcelain
-
-# Run tests
-bundle exec rspec
-
-# Update Gemfile.lock
-bundle install
-git add Gemfile.lock
-git commit -m "chore: update Gemfile.lock to vX.Y.Z"
-git push origin main
-
-# Build and publish gem
-gem build openclacky.gemspec
-gem push openclacky-X.Y.Z.gem
-
-# Git operations
-git add lib/clacky/version.rb
-git commit -m "chore: bump version to X.Y.Z"
-git tag vX.Y.Z
-git push origin main
-git push origin --tags
-
-# ── GitHub Release ──────────────────────────────────────────────────────
-
-# Stable release:
-gh release create vX.Y.Z \
-  --title "vX.Y.Z" \
-  --notes-file /tmp/release_notes_X.Y.Z.md \
-  --latest \
-  openclacky-X.Y.Z.gem
-
-# Pre-release (use --prerelease instead of --latest):
-gh release create vX.Y.Z-beta.1 \
-  --title "vX.Y.Z-beta.1" \
-  --notes-file /tmp/release_notes_X.Y.Z-beta.1.md \
-  --prerelease \
-  openclacky-X.Y.Z.beta.1.gem
-
-# ── OSS CDN (CN mirror) ─────────────────────────────────────────────────
-
-# Always upload the .gem file:
-coscli cp openclacky-X.Y.Z.gem cos://clackyai-1258723534/openclacky/openclacky-X.Y.Z.gem
-
-# Stable releases ONLY — update latest.txt:
-echo "X.Y.Z" > /tmp/latest.txt
-coscli cp /tmp/latest.txt cos://clackyai-1258723534/openclacky/latest.txt
-curl -fsSL https://oss.1024code.com/openclacky/latest.txt  # verify
-
-# Pre-releases — skip latest.txt update unless user explicitly requests it
-
-# Sync scripts/ to OSS (build from templates first)
-bash scripts/build/build.sh
-for script in scripts/*; do
-  coscli cp "$script" cos://clackyai-1258723534/clacky-ai/openclacky/main/scripts/$(basename "$script")
-done
-curl -fsSL https://oss.1024code.com/clacky-ai/openclacky/main/scripts/install.sh | head -5  # verify
-```
+When releasing a pre-release version, inform the user of these behaviors:
 
-## File Locations
+| Concern | Behavior | Impact |
+|---------|----------|--------|
+| **Version check notification** | `Gem::Version("0.9.38") < Gem::Version("1.0.0.beta.1")` is true | The upgrade dot WILL appear in the Web UI for most users |
+| **`gem update` (official source)** | Does NOT install prereleases without `--pre` | Users who click "Upgrade" will see notification but upgrade silently does nothing |
+| **OSS CDN upgrade (mirror users)** | Downloads exact `.gem` from `latest.txt` | If latest.txt points to prerelease, mirror users WILL get the beta |
+| **OSS `latest.txt`** | Fresh installs fetch latest.txt | By default, do NOT update latest.txt for pre-releases |
 
-- Version file: `lib/clacky/version.rb`
-- Gem specification: `openclacky.gemspec`
-- Changelog: `CHANGELOG.md`
-- Built gem: `openclacky-{version}.gem`
-
-## Success Criteria
-
-- All tests pass
-- CI pipeline completes successfully
-- Gemfile.lock updated and committed
-- New version successfully published to RubyGems
-- Git repository updated with version tag
-- CHANGELOG.md updated with release notes
-- GitHub Release created with .gem file attached at https://github.com/clacky-ai/openclacky/releases
-  - Use `--latest` for stable releases, `--prerelease` for pre-releases
-- .gem file uploaded to OSS: https://oss.1024code.com/openclacky/openclacky-{version}.gem
-- For stable releases: `latest.txt` updated on OSS: https://oss.1024code.com/openclacky/latest.txt returns the new version
-- For pre-releases: `latest.txt` NOT updated (unless user explicitly opts in)
-- No build or deployment errors
-- User-facing release summary presented at the end
+Ask the user whether to use `--update-latest` before running the script.
 
 ## Error Handling
 
-- If tests fail, stop the process and report issues
-- If CI fails after Gemfile.lock update, fix issues before proceeding
-- If gem build fails, check gemspec configuration
-- If git push fails, verify repository permissions
-- If gem push fails, check RubyGems credentials
-- If `gh release create` fails, ensure `gh` CLI is installed (`brew install gh`) and authenticated (`gh auth login`)
-- If GitHub Release notes look wrong, check CHANGELOG.md formatting for the version section
-
-## Notes
+The script uses `set -euo pipefail` and stops on any failure. Common issues:
 
-- This skill follows semantic versioning
-- Always update CHANGELOG.md as part of the release
-- Verify RubyGems.org shows the new version after publication
-- The search index on RubyGems may take a few minutes to update
+- **Tests fail** → fix tests before re-running
+- **CI fails** → script pushes then watches CI; fix and re-push if needed
+- **gem push fails** → check RubyGems credentials (`gem signin`)
+- **gh release fails** → check `gh auth status`
+- **coscli fails** → check `~/.cos.yaml` config
 
-## Dependencies
+After fixing an issue, you can re-run the script — it's safe to retry. If a partial release happened (e.g., gem pushed but tag not created), handle remaining steps manually.
 
-- Ruby development environment
-- Git repository access
-- RubyGems account with push permissions
-- Bundle and RSpec for testing
-- `gh` CLI installed and authenticated (`brew install gh && gh auth login`)
-
-## Version History
+## File Locations
 
-- Created: 2026-01-18
-- Used for: openclacky gem releases
-- Compatible with: Ruby gems following standard conventions
+- Release script: `SKILL_DIR/scripts/release.sh`
+- Version file: `lib/clacky/version.rb`
+- Gem specification: `openclacky.gemspec`
+- Changelog: `CHANGELOG.md`
 
-## User Experience Summary
+## Dependencies
 
-This skill takes the complexity out of gem releases. Instead of remembering 8+ different commands and worrying about the correct order, you just say "release a new version" and the AI handles everything - from running tests to publishing on RubyGems. It's like having an experienced release engineer on your team who never forgets a step, always runs the tests first, and makes sure your changelog is updated. The whole process that used to take 15-20 minutes and multiple terminal windows now happens smoothly in one conversation, with clear feedback at each step so you know exactly what's happening.
+- Ruby >= 3.1.0, Bundler, RSpec
+- `gh` CLI installed and authenticated
+- `coscli` installed at `/usr/local/bin/coscli` with `~/.cos.yaml`
+- RubyGems push credentials