diff --git a/.claude/skills/release-notes/SKILL.md b/.claude/skills/release-notes/SKILL.md new file mode 100644 index 0000000..27aac6b --- /dev/null +++ b/.claude/skills/release-notes/SKILL.md @@ -0,0 +1,331 @@ +--- +name: release-notes +description: >- + Generate a GitHub release note draft for this Obsidian plugin repository. + Use when the user asks to write, draft, or prepare release notes for a new version. + Invoked with a version number argument (e.g. "0.11.0", "0.11.0-preview.1"). + Analyzes git history and code diffs since the previous release to produce + user-facing release notes in the project's established format. +--- + +# Release Notes Generator + +Generate a release note draft for this repository by analyzing git changes since the previous release. The output is a Markdown code block ready to paste into a GitHub release — do NOT create the release itself. + +The version number is provided as an argument (e.g. `/release-notes 0.11.0`). If no version is given, ask for one before proceeding. + +## Step 1: Determine the previous release + +The "previous release" depends on the version type being drafted: + +- **Stable version** (no `-preview`): Find the most recent stable tag, skipping all prereleases. This is because stable release notes cover everything since the last stable release — they aggregate all prerelease changes into one cohesive set of notes. +- **Prerelease** (`-preview.N`): Find the most recent tag of any kind (stable or prerelease). Prerelease notes only cover the incremental delta since the last tag. + +Use `git tag --sort=-v:refname` to list tags and pick the right one. Confirm the previous tag to the user before continuing (e.g. "Previous release: v0.10.2 — generating notes for changes since then."). + +## Step 2: Gather information + +Run these in parallel where possible: + +1. **Commit log**: `git log {prev_tag}..HEAD --oneline` — the list of changes +2. **Diff stat**: `git diff --stat {prev_tag}..HEAD` — which files changed +3. **Actual diffs**: Read the diffs of changed source files (`src/`, `styles.css`, `manifest.json`, etc.) to understand what each change actually does at the code level. This is critical — commit messages alone are not enough to write accurate user-facing descriptions. +4. **Issue numbers**: Extract `#NNN` references from commit messages. Note: commit messages often contain PR numbers (from merge commits), not the original issue numbers. Use whatever `#NNN` is in the commit message as-is — the author will verify and correct these during review. +5. **New contributors**: Compare authors before and after the previous tag: + ``` + git log --format='%aN' {prev_tag} | sort -u # existing contributors + git log --format='%aN' {prev_tag}..HEAD | sort -u # contributors in this range + ``` + Anyone in the second set but not the first is a new contributor. To find their GitHub username and PR number, use `git log --format='%aN <%aE>' {prev_tag}..HEAD` and cross-reference with `#NNN` in their commit messages. The GitHub username may differ from the git author name — check the commit on GitHub if needed. +6. **Previous prerelease notes** (stable releases only): If drafting a stable release and there were prereleases in the range, read their release notes with `gh release view {tag}`. This helps identify bugs that were introduced and fixed within the prerelease cycle — those should be excluded from the stable release notes since they never affected stable users. + +## Step 3: Analyze and categorize + +Before writing, think through what each change means from a user's perspective: + +- **What can users do now that they couldn't before?** → New features (🌟 New) +- **What existing behavior got better?** → Improvements (🔧 Improvements) +- **What was broken and is now fixed?** → Bug fixes (🐛 Fixes) +- **Did anything get faster?** → Performance (⚡ Performance) +- **Does anything require user action on upgrade?** → Breaking changes (⚠️ Breaking Changes) + +For stable releases aggregating prereleases: exclude bugs that were both introduced and resolved during the prerelease cycle. Those never affected stable users and do not belong in the stable release notes. + +### Detecting breaking changes + +Breaking changes are easy to miss in diffs. Actively look for these patterns: + +- **Renamed settings keys** in default settings or settings types (e.g., `activeAgentId` → `defaultAgentId`) +- **Renamed command IDs** in plugin.ts `addCommand()` calls +- **Changed or removed public APIs** or exported interfaces +- **Changed default behavior** that users relied on (e.g., a button that now does something different) +- **Removed features or settings** + +If any are found, they MUST appear in the `### ⚠️ Breaking Changes:` section AND be mentioned in the Upgrade section. If the migration is automatic, say so — users still need to know something changed. + +## Step 4: Write the draft + +Output the release note as a single Markdown code block. Follow this format exactly. + +### Title line + +The title is plain text with bold formatting — NOT a Markdown heading. No `#` prefix. + +``` +{emoji} **{Release Type} (v{version})** +``` + +Choose the release type and emoji based on content: +- `🔬 **Preview Release**` — all prereleases +- `✨ **Feature Release**` — stable with new features +- `🔧 **Improvement & Bug Fix Release**` — stable with improvements and fixes but no major new features +- `🐛 **Bug Fix Release**` — stable with only bug fixes +- `🔧 **Improvement Release**` — stable with only improvements +- `⚡ **Performance Fix**` — stable with only performance changes +- `🔧 **Maintenance Release**` — stable with only dependency updates or internal changes + +### Prerelease warning (prereleases only) + +For ALL preview releases — regardless of size — add this immediately after the title line (with a blank line before and after): + +``` +⚠️ **This is a preview release** — Features are experimental and may change. Please report any issues! +``` + +This is mandatory for every prerelease. Never omit it. + +### Summary paragraph + +For stable 0.X.0 releases and substantial prereleases with multiple features, add a 1-2 sentence summary after the title (or after the prerelease warning). Patch releases and small prereleases with a single change can skip this. + +The summary should focus on the single biggest highlight or theme — not enumerate every change. One sentence is ideal. If you can't pick a single theme, pick the top 2-3 and keep it under two sentences. + +### Sections + +Include only sections that have content, in this order: + +```markdown +### ⚡ Performance: + +### 🌟 New: + +### 🔧 Improvements: + +### 🐛 Fixes: + +### ⚠️ Breaking Changes: + +### 🚀 Upgrade: + +-------- + +### 👋 New Contributors + +-------- + +**Thank you for your continued support! Your feedback helps make this plugin better for everyone.** 🙏 +``` + +### Item format + +Each item follows this pattern: + +``` +- **{emoji} {Short Title}**: {Description}. (#issue) +``` + +Rules: +- The **emoji** indicates the category (🪟 window/floating, ⌨️ keyboard/input, 📋 copy/clipboard, 🔗 links/paths, 🐧 Linux/WSL, 🍎 macOS, 📦 packages/SDK, 🔔 notifications, 📂 files/directories, 🔐 permissions, 📊 data/charts, 📜 scrolling, 🔍 search/focus, 🎨 styling/UI, 🖥️ terminal, 📝 text/editing, 🔄 sync/restore, 🗑️ deletion, 📏 sizing/layout, etc.) +- The **short title** is 2-5 words, bold, and scannable — readers should understand the topic from the title alone. +- The **description** explains what changed from the user's perspective. Do not describe implementation details — no function names, class names, React hooks, framework APIs, or internal architecture. If a change is purely internal (refactoring, performance optimization), describe its user-visible effect. +- **Issue numbers** go at the end in parentheses. Omit if no issue is referenced. +- **One item per logical change.** If a single commit or PR addresses one concern (e.g. "fix process cleanup"), that is one item — even if it touches multiple files or uses platform-specific strategies. Conversely, don't merge unrelated changes into one item. + +### Upgrade section + +Always present. Keep it short and plain — no links, no blockquotes, no extra formatting. + +- For patch/preview: `Simply update from v{prev} — no configuration needed.` or `Update from v{prev}. No configuration changes needed.` +- For stable 0.X.0: `Update from v{prev} — no extra configuration required.` with additional migration notes if there are breaking changes. +- If there are breaking changes, add a `⚠️` warning with specific user action required. + +### New Contributors section + +Only include if there are new contributors. Use this exact format: + +``` +- @username made their first contribution in #PR +``` + +Do not add bold formatting, descriptions, or extra text. Do not add a "Welcome" message. + +For stable releases: re-list contributors who were first listed in a prerelease within this cycle. They are still "new" from the stable user's perspective. + +### Closing + +Always end with this exact line: + +``` +**Thank you for your continued support! Your feedback helps make this plugin better for everyone.** 🙏 +``` + +## Writing principles + +- **User perspective only**: Describe benefits and behavior, not code changes. Never mention internal identifiers like component names, hook names, framework APIs, algorithm details, or data structures. The reader is an Obsidian user, not a developer reading the source code. +- **Accuracy over speed**: Read the actual code diffs. A commit message saying "fix: resolve issue" tells you nothing — the diff tells you everything. +- **Be specific**: "Fixed agents failing to start on NixOS" is better than "Fixed shell compatibility issue." Include concrete details like error messages or specific scenarios. +- **One item per logical change**: A single commit fixing process cleanup across platforms is one item. A single commit fixing two unrelated bugs is two items. Match the logical boundary, not the commit boundary. +- **Consistent tense**: Use past tense for fixes ("Fixed..."), present tense or imperative for features ("See how much context you've used" / "Attach non-image files"). +- **Performance items describe the user experience**: "Significantly improved responsiveness for long sessions" — not "Added virtual scrolling with @tanstack/react-virtual and RAF batching." + +## Examples + +These are real release notes from this repository. Study the tone, format, and level of detail. + +### Example 1: Bug fix release (v0.10.2) + +``` +🐛 **Bug Fix Release (v0.10.2)** + +### 🐛 Fixes: + +- **🪟 WSL Distribution Names with Dots**: Fixed "Invalid WSL distribution name" error when specifying versioned distribution names like `Ubuntu-22.04`. (#223) + +### 🚀 Upgrade: + +Simply update from v0.10.1 — no configuration needed. + +-------- + +**Thank you for your continued support! Your feedback helps make this plugin better for everyone.** 🙏 +``` + +Note: One fix, one item. Short title tells you the topic. Description includes the actual error message for specificity. No extra sections. + +### Example 2: Preview release (v0.10.0-preview.3) + +``` +🔬 **Preview Release (v0.10.0-preview.3)** + +⚠️ **This is a preview release** — Features are experimental and may change. Please report any issues! + +### 🐛 Fixes: + +- **🧹 Process Cleanup on Exit**: Fixed agent child processes (e.g., MCP server nodes) remaining after closing Obsidian, restarting agents, or switching sessions. The plugin now kills the entire process tree on disconnect using platform-specific strategies. Also added cleanup on plugin disable. (#205) + +### 🚀 Upgrade: + +Update from v0.10.0-preview.2. No configuration changes needed. + +-------- + +**Thank you for your continued support! Your feedback helps make this plugin better for everyone.** 🙏 +``` + +Note: The prerelease warning is always included. A multi-faceted fix (multiple platforms, multiple triggers) is still ONE item because it's one logical concern. "platform-specific strategies" is acceptable — it communicates the scope without naming specific APIs. + +### Example 3: Feature release with aggregated prereleases (v0.9.0, excerpt) + +``` +✨ **Feature Release (v0.9.0)** + +This release adds context usage tracking, file attachment support, agent update notifications, dynamic session configuration, and a chat export command. + +### 🌟 New: + +- **📊 Context Usage Indicator**: See how much of the agent's context window you've used, displayed next to the send button. Color changes at 70%/80%/90% thresholds to warn you before hitting limits. (#113) +- **📎 File Attachments**: Attach non-image files (text, code, PDFs, etc.) to your messages via paste or drag-and-drop. Files are sent as `resource_link` content and rendered in chat messages. (#77) + +### 🔧 Improvements: + +- **📦 ACP SDK Update**: Updated @agentclientprotocol/sdk to v0.14.1. + +### 🐛 Fixes: + +- **📜 Auto-Scroll Threshold**: Increased threshold from 20px to 35px for more reliable scroll tracking. +- **🔗 Settings Documentation Link**: Fixed clicking the documentation link in settings causing Obsidian popout windows to close due to missing `target="_blank"`. (#152) + +### 🚀 Upgrade: + +Update from v0.8.3 — no extra configuration required. New features activate automatically when supported by your agent. + +-------- + +**Thank you for your continued support! Your feedback helps make this plugin better for everyone.** 🙏 +``` + +Note: Summary paragraph lists the highlights. Features describe what users can now do. SDK update is a one-liner. Fixes describe the user-visible symptom, not the code fix. + +### Example 4: Improvement & bug fix release with new contributor (v0.9.4) + +``` +🔧 **Improvement & Bug Fix Release (v0.9.4)** + +This release adds a copy button to messages, fixes markdown overflow issues, and improves floating chat behavior. + +### 🌟 New: + +- **📋 Copy Message Button**: Hover over any message to reveal a copy-to-clipboard button. Works for both user and assistant messages. (#189) + +### 🔧 Improvements: + +- **🪟 Smarter Floating Chat Commands**: Floating chat commands (open, minimize, close) now only appear in the command palette when the feature is enabled. Minimize and close additionally require a focused floating window. (#188) + +### 🐛 Fixes: + +- **📜 Horizontal Scroll for Wide Content**: Fixed mermaid diagrams, tables, and SVGs being clipped instead of scrolling horizontally. (#190) +- **🪟 Floating Chat Toggle**: Fixed floating chat button not hiding when the feature is toggled off in settings. (#187) + +### 🚀 Upgrade: + +Simply update from v0.9.3 — no configuration needed. + +-------- + +### 👋 New Contributors + +- @aviatesk made their first contribution in #187 + +-------- + +**Thank you for your continued support! Your feedback helps make this plugin better for everyone.** 🙏 +``` + +Note: Even though it has a "New" section, the overall release type is "Improvement & Bug Fix Release" because the copy button is a small addition, not a major feature. New Contributors uses the exact `@username made their first contribution in #PR` format with no extra decoration. + +### Example 5: Feature release with breaking changes (v0.7.0, excerpt) + +``` +✨ **Feature Release (v0.7.0)** + +This release introduces multi-agent session support, allowing you to run multiple independent agent conversations simultaneously in separate chat views. + +### 🌟 New: + +- **🪟 Multi-Agent Sessions**: Run multiple agents simultaneously in separate chat views. Each view has its own independent agent process and session. (#59) +- **📢 Broadcast Commands**: Control multiple chat views at once: + - `Broadcast prompt`: Copy the active view's input to all other views + - `Broadcast send`: Send messages in all views simultaneously + - `Broadcast cancel`: Cancel operations in all views +- **🔀 Focus Navigation**: Quickly switch between chat views with `Focus next/previous chat view` commands +- **➕ Open New View Command**: Open additional chat views via command palette or Header Menu + +### 🔧 Improvements: + +- **🍔 Header Menu**: New ellipsis menu in chat header for quick agent switching, opening new views, restarting agent, and accessing plugin settings. +- **🚨 Error Overlay**: Errors are now displayed as a dismissible overlay above the input area instead of replacing the entire chat. + +### ⚠️ Breaking Changes: + +- **Setting Renamed**: `activeAgentId` → `defaultAgentId` (automatically migrated) + +### 🚀 Upgrade: + +Update from v0.6.1 — Settings are automatically migrated. Multi-session support works immediately with existing agent configurations. + +-------- + +**Thank you for your continued support! Your feedback helps make this plugin better for everyone.** 🙏 +``` + +Note: The summary focuses on the single biggest highlight (multi-agent sessions), not a list of everything. Breaking changes get their own section even when migration is automatic — users need to know. The Upgrade section mentions the auto-migration. Sub-bullet lists (as in Broadcast Commands) are fine when they improve scannability. Each distinct capability (Focus Navigation, Open New View) gets its own item rather than being folded into Multi-Agent Sessions.