work-chronicler 0.2.0 → 0.2.1

package/.agent/skills/release-notes/skill.md

@@ -0,0 +1,129 @@
+---
+name: release-notes
+description: Use when releasing a new version, after tagging, or when the user asks to update release notes. Generates meaningful release notes from git history and updates the GitHub release.
+user-invocable: true
+---
+
+# Generate Release Notes
+
+Generate meaningful release notes from git history between two tags and update the corresponding GitHub release.
+
+## User Input
+
+**Optional:**
+- **Tag**: The tag to generate notes for (e.g., "v0.2.0")
+  - If omitted, uses the latest tag
+- **Previous tag**: The starting point for the diff
+  - If omitted, uses the tag immediately before the target tag
+
+**Example invocations:**
+- `/release-notes` (latest tag vs its predecessor)
+- `/release-notes v0.2.0` (specific tag)
+- `/release-notes v0.3.0 v0.1.1` (explicit range)
+
+## Instructions
+
+### 1. Determine the tag range
+
+```bash
+# If no tag specified, get the latest
+git tag --sort=-v:refname | head -1
+
+# Get the previous tag
+git tag --sort=-v:refname | head -2 | tail -1
+
+# Check when the tag was created (to detect stale releases)
+git log -1 --format="%ci" <latest-tag>
+```
+
+**Staleness check:** If no tag was explicitly provided, compare the tag's date to today. If the tag is older than 7 days, ask the user to confirm this is the intended release before proceeding — they may have forgotten to specify a tag, or may need to create a new one first.
+
+Confirm the two tags with the user before proceeding.
+
+### 2. Gather commit data
+
+```bash
+# All commits in the range
+git log --oneline <previous-tag>..<target-tag>
+
+# Merged PRs (first-parent view)
+git log --oneline --first-parent <previous-tag>..<target-tag>
+
+# Full commit messages for context
+git log --format="%h %s%n%b" <previous-tag>..<target-tag>
+```
+
+### 3. Gather PR details (if available)
+
+For each merged PR number found in commit messages:
+
+```bash
+gh pr view <number> --json title,body,labels
+```
+
+### 4. Categorize changes
+
+Group commits into categories based on conventional commit prefixes:
+
+| Prefix | Category |
+|--------|----------|
+| `feat` | New Features |
+| `fix` | Bug Fixes |
+| `perf` | Performance |
+| `refactor` | Refactoring |
+| `test` | Testing |
+| `docs` | Documentation |
+| `chore` | Maintenance |
+
+Within each category, group related commits together and summarize them as a single item rather than listing every commit individually. Focus on **what changed for the user**, not implementation details.
+
+### 5. Write release notes
+
+Structure:
+
+```markdown
+## Highlights
+
+[1-3 sentence summary of the most important changes in this release]
+
+## What's New
+
+### [Category Name]
+- **[Feature/change name]** — [Description of what it does and why it matters]
+- **[Feature/change name]** — [Description]
+
+### [Category Name]
+- **[Fix/change name]** — [Description]
+
+## Installation
+
+\`\`\`bash
+npm install -g work-chronicler@<version>
+\`\`\`
+```
+
+### 6. Update the GitHub release
+
+First, show the user the generated notes and get their approval. Then:
+
+```bash
+gh release edit <tag> --notes "<approved notes>"
+```
+
+Use a heredoc for the notes body to preserve formatting:
+
+```bash
+gh release edit <tag> --notes "$(cat <<'NOTES'
+<release notes content>
+NOTES
+)"
+```
+
+## Guidelines
+
+- **Summarize, don't list** — "Added manager mode with report management, per-report analysis, and team aggregations" is better than listing 15 individual commits
+- **User-facing language** — Describe what users can do now, not what files changed
+- **Group by feature, not by commit** — Multiple commits that build one feature should be a single bullet point
+- **Skip noise** — Formatting fixes, import cleanup, and file moves don't need to be mentioned unless they affect users
+- **Keep it scannable** — Someone should understand the release in 30 seconds
+- **Preserve the installation section** — The CI workflow includes this; keep it consistent

package/README.md

@@ -21,68 +21,37 @@ Manager mode extends work-chronicler for people managers tracking multiple direc
 
 ## Quick Start
 
-### Local Development (this repo)
-
-Use `pnpm cli` instead of `work-chronicler`:
-
-```bash
-pnpm install
-pnpm cli init
-pnpm cli fetch all
-```
-
-### Published Package Usage
-
-After the package is published to npm:
-
 ```bash
 # Install globally
 npm install -g work-chronicler
 
-# Initialize - interactive wizard guides you through setup
+# 1. Initialize — interactive wizard guides you through setup
 work-chronicler init
 
-# Or initialize in manager mode for tracking your team
-work-chronicler init --mode manager
-
-# Fetch your work history
+# 2. Fetch your work history from GitHub and JIRA
 work-chronicler fetch all
 
-# Analyze and generate stats
-work-chronicler analyze --projects --timeline
-
-# Check what you have
+# 3. Review what was fetched
 work-chronicler status
-```
-
-Data is stored in `~/.work-chronicler/profiles/<profile-name>/` with isolated configs, tokens, and work logs per profile.
 
-## Usage
-
-work-chronicler uses a portable workspace at `~/.work-chronicler/` with support for multiple profiles. Each profile has its own config, tokens, and work log.
-
-```bash
-# Initialize with interactive wizard (creates profile)
-work-chronicler init
+# 4. Filter to relevant work (exclude minor PRs, personal repos, etc.)
+work-chronicler filter
 
-# Fetch from GitHub and JIRA
-work-chronicler fetch all
+# 5. Run analysis on the filtered data
+work-chronicler analyze --all
 
-# Cross-reference PRs ↔ tickets
-work-chronicler link
+# 6. Install AI skills to your coding assistant
+work-chronicler skills install
 
-# Generate analysis files
-work-chronicler analyze --projects --timeline
+# 7. Use a skill in Claude Code, Cursor, etc.
+#    /work-chronicler-summarize-work
+```
 
-# Check status
-work-chronicler status
+> Skills are slash commands for AI coding assistants — they won't work in a regular terminal. Run them from Claude Code, Cursor, Codex, or Gemini after running `skills install`.
 
-# Use a specific profile for any command
-work-chronicler fetch all --profile work
-work-chronicler status --profile personal
-```
+Data is stored in `~/.work-chronicler/profiles/<profile-name>/` with isolated configs, tokens, and work logs per profile.
 
-> **Note**: For local development in this repo, prefix all commands with `pnpm cli` (e.g., `pnpm cli init`).
+> **Local development:** Use `pnpm cli` instead of `work-chronicler` (e.g., `pnpm cli init`).
 
 ### Profiles
 
@@ -319,9 +288,13 @@ Create an API token at https://id.atlassian.com/manage-profile/security/api-toke
 | `WORK_CHRONICLER_DIR` | Legacy: directory containing config (for MCP server) |
 | `WORK_CHRONICLER_CONFIG` | Legacy: full path to config file |
 
-## AI Skills Installation
+## AI Skills
+
+work-chronicler includes AI skills that can be installed to your preferred coding assistant. Skills are **stateless** — they don't embed any file paths. At runtime, each skill shells out to `work-chronicler workspace work-log` (and similar commands) to resolve the active profile's data directory. This means:
 
-work-chronicler includes AI skills that can be installed to your preferred coding assistant:
+- Skills work regardless of where they're installed (`~/.claude/skills/`, `~/.cursor/skills/`, etc.)
+- Switching profiles with `work-chronicler profile switch` changes what data skills read
+- No reinstallation is needed when you change profiles
 
 ```bash
 # Install skills to Claude Code, Cursor, etc.
@@ -336,7 +309,7 @@ work-chronicler skills uninstall
 
 ### Available Skills
 
-After installation, these skills are available as slash commands:
+After installation, these skills are available as slash commands in your AI coding assistant:
 
 **Individual Contributor (IC) Mode:**
 
@@ -470,6 +443,8 @@ work-chronicler includes an MCP (Model Context Protocol) server that exposes you
 
 3. Restart your AI assistant to load the MCP server.
 
+> **Profile resolution:** The MCP server resolves the active profile **once at startup**. If you switch profiles with `work-chronicler profile switch`, you need to restart the MCP server (i.e., restart your AI assistant) for the change to take effect. Alternatively, set `WORK_CHRONICLER_PROFILE` in the MCP config to pin to a specific profile.
+
 **Environment Variables:**
 - `WORK_CHRONICLER_HOME` - Workspace root (default: `~/.work-chronicler`)
 - `WORK_CHRONICLER_PROFILE` - Profile name (default: active profile in `~/.work-chronicler/config.json`)

package/dist/cli/commands/init/index.js

@@ -364,17 +364,20 @@ async function runInitialFetch(config, outputDir) {
  */
 function showNextSteps(profileName, tokens) {
     console.log(chalk.cyan('\nNext steps:\n'));
+    let step = 1;
     if (!tokens.githubToken && !tokens.jiraToken) {
         const envPath = getProfileEnvPath(profileName);
-        console.log(`  1. Add your API tokens to: ${envPath}`);
-        console.log('  2. Fetch your work history: work-chronicler fetch:all');
+        console.log(`  ${step}. Add your API tokens to: ${envPath}`);
+        step++;
     }
-    else {
-        console.log('  1. Fetch your work history: work-chronicler fetch:all');
-    }
-    console.log('  2. Check what was fetched: work-chronicler status');
-    console.log('  3. Generate a summary: Use /summarize-work in your AI assistant');
+    console.log(`  ${step}. Fetch your work history:       work-chronicler fetch all`);
+    console.log(`  ${step + 1}. Review what was fetched:       work-chronicler status`);
+    console.log(`  ${step + 2}. Filter for relevant work:       work-chronicler filter`);
+    console.log(`  ${step + 3}. Run analysis on filtered data:  work-chronicler analyze --all`);
+    console.log(`  ${step + 4}. Install AI skills:              work-chronicler skills install`);
+    console.log(`  ${step + 5}. Use a skill in your AI editor:   /work-chronicler-summarize-work`);
     console.log();
+    console.log(chalk.dim('Skills are slash commands for AI coding assistants (Claude Code, Cursor, etc.).'));
     console.log(chalk.dim('Switch profiles: work-chronicler profile switch <name>'));
     console.log(chalk.dim('List profiles:   work-chronicler profile list'));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "work-chronicler",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Gather, analyze, and summarize your work history from GitHub PRs and JIRA tickets for performance reviews and resumes",
   "type": "module",
   "main": "dist/cli/index.js",