docs: add release docs

packages/cli/CHANGELOG.md

@@ -1,5 +1,11 @@
 # diffity
 
+## 0.1.2
+
+### Patch Changes
+
+- Improve the skill files for comment resolution and add cleanup for the dev scripts.
+
 ## 0.1.1
 
 ### Patch Changes

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diffity",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "GitHub-style git diff viewer in the browser",
   "type": "module",
   "bin": {

packages/skills/diffity-resolve/SKILL.md

@@ -44,9 +44,17 @@ You are reading open review comments and resolving them by making the requested
 2. If there are no open threads, tell the user there's nothing to resolve.
 3. For each open thread:
    a. **Skip** general comments (filePath `__general__`) — these are summaries, not actionable code changes.
-   b. **Skip** threads tagged `[question]` or `[nit]` — these don't require code changes. Tell the user you skipped them and why.
-   c. Read the comment body from the JSON output and understand what change is requested.
-   d. Read the relevant source file to understand the full context around the commented lines, then make the requested code change using the Edit tool.
+   b. **Skip** threads where the comment body starts with an explicit `[question]` or `[nit]` tag prefix — these don't require code changes. Tell the user you skipped them and why.
+      - **Important:** Only skip if the comment body literally begins with `[question]` or `[nit]`. Do NOT skip comments just because they are phrased as a question (e.g. "should we add X?" or "can we rename this?"). Comments phrased as questions without explicit tags are suggestions — treat them as actionable requests.
+   c. Read the comment body from the JSON output and understand what change is requested. Interpret the intent:
+      - If the comment suggests a code change, make the change.
+      - If the comment suggests adding documentation, add or update the relevant docs.
+      - If the comment asks a question that implies an action (e.g. "should we add X?"), treat it as a request to do that action.
+      - If the comment is genuinely unclear and you cannot determine what action to take, reply asking for clarification instead of silently skipping:
+        ```
+        {{binary}} agent reply <thread-id> --body "Could you clarify what change you'd like here?"
+        ```
+   d. Read the relevant source file to understand the full context around the commented lines, then make the requested change using the Edit tool.
    e. After making the change, resolve the thread with a summary:
       ```
       {{binary}} agent resolve <thread-id> --summary "Fixed: <brief description of what was changed>"

packages/skills/diffity-start/SKILL.md

@@ -20,6 +20,6 @@ You are starting the diffity diff viewer so the user can see their changes in th
 
    > Diffity is running — check your browser.
    >
-   > Here's what you can do:
-   > - **{{slash}}review** — get a code review on your changes
-   > - **{{slash}}resolve** — fix issues from review comments
+   > When you're ready:
+   > - Leave comments on the diff in your browser, then run **{{slash}}resolve** to fix them
+   > - Or run **{{slash}}review** to get an AI code review

pnpm-lock.yaml

@@ -1,9 +0,0 @@
-lockfileVersion: '9.0'
-
-settings:
-  autoInstallPeers: true
-  excludeLinksFromLockfile: false
-
-importers:
-
-  .: {}

releasing.md

@@ -0,0 +1,57 @@
+# Releasing
+
+## Overview
+
+We use [changesets](https://github.com/changesets/changesets) to manage versioning and publishing. Only the `diffity` CLI package (in `packages/cli`) is published to npm. All other packages (`@diffity/git`, `@diffity/parser`, `@diffity/ui`) are private workspace packages bundled into the CLI.
+
+## Creating a Changeset
+
+After making changes that should be released, create a changeset:
+
+```bash
+npm run changeset
+```
+
+This will prompt you to:
+1. Select which packages changed (choose `diffity`)
+2. Pick a semver bump type (patch / minor / major)
+3. Write a summary of the changes
+
+A markdown file is created in `.changeset/` — commit it with your changes.
+
+### When to use each bump type
+
+- **patch** — bug fixes, internal refactors, dependency updates
+- **minor** — new features, new CLI flags, non-breaking UI changes
+- **major** — breaking changes to CLI arguments or behavior
+
+## Release Process
+
+```bash
+# 1. Consume changesets — bumps version in package.json, generates CHANGELOG.md
+npm run version
+
+# 2. Review and commit the version bump
+git add -A && git commit -m "chore: bump version"
+
+# 3. Build all packages and publish to npm
+npm run release
+
+# 4. Push the commit and tag
+git push && git push --tags
+```
+
+## Verifying a Release
+
+After publishing, verify the package works:
+
+```bash
+npm install -g diffity@latest
+diffity --version
+```
+
+## Notes
+
+- `npm run release` runs a full build before publishing, so you don't need to build separately.
+- Changesets automatically creates a git tag for each release (e.g. `diffity@0.2.0`).
+- If a publish fails, fix the issue and run `npm run release` again — changesets won't re-bump the version.

scripts/dev.ts

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 
 import { execSync } from 'child_process';
-import { dirname, resolve } from 'path';
+import { dirname, resolve, join } from 'path';
+import { rmSync } from 'fs';
 import { fileURLToPath } from 'url';
 import concurrently from 'concurrently';
 
@@ -13,6 +14,24 @@ execSync('tsx scripts/link-dev.ts && npm run build:skills', {
   stdio: 'inherit',
 });
 
+const localClaudeSkillsDir = join(rootDir, '.claude', 'skills');
+
+function cleanupDevSkills() {
+  try {
+    rmSync(localClaudeSkillsDir, { recursive: true, force: true });
+    console.log('Cleaned up dev skills');
+  } catch {}
+}
+
+process.on('SIGINT', () => {
+  cleanupDevSkills();
+  process.exit(0);
+});
+process.on('SIGTERM', () => {
+  cleanupDevSkills();
+  process.exit(0);
+});
+
 concurrently(
   [
     { command: 'npm run dev -w @diffity/parser', name: 'parser' },
@@ -29,4 +48,6 @@ concurrently(
   {
     prefixColors: ['blue', 'green', 'yellow', 'magenta', 'cyan'],
   }
-);
+).result.finally(() => {
+  cleanupDevSkills();
+});

skills/diffity-resolve/SKILL.md

@@ -44,9 +44,17 @@ diffity agent reply <id> --body "<text>"
 2. If there are no open threads, tell the user there's nothing to resolve.
 3. For each open thread:
    a. **Skip** general comments (filePath `__general__`) — these are summaries, not actionable code changes.
-   b. **Skip** threads tagged `[question]` or `[nit]` — these don't require code changes. Tell the user you skipped them and why.
-   c. Read the comment body from the JSON output and understand what change is requested.
-   d. Read the relevant source file to understand the full context around the commented lines, then make the requested code change using the Edit tool.
+   b. **Skip** threads where the comment body starts with an explicit `[question]` or `[nit]` tag prefix — these don't require code changes. Tell the user you skipped them and why.
+      - **Important:** Only skip if the comment body literally begins with `[question]` or `[nit]`. Do NOT skip comments just because they are phrased as a question (e.g. "should we add X?" or "can we rename this?"). Comments phrased as questions without explicit tags are suggestions — treat them as actionable requests.
+   c. Read the comment body from the JSON output and understand what change is requested. Interpret the intent:
+      - If the comment suggests a code change, make the change.
+      - If the comment suggests adding documentation, add or update the relevant docs.
+      - If the comment asks a question that implies an action (e.g. "should we add X?"), treat it as a request to do that action.
+      - If the comment is genuinely unclear and you cannot determine what action to take, reply asking for clarification instead of silently skipping:
+        ```
+        diffity agent reply <thread-id> --body "Could you clarify what change you'd like here?"
+        ```
+   d. Read the relevant source file to understand the full context around the commented lines, then make the requested change using the Edit tool.
    e. After making the change, resolve the thread with a summary:
       ```
       diffity agent resolve <thread-id> --summary "Fixed: <brief description of what was changed>"

skills/diffity-start/SKILL.md

@@ -22,6 +22,6 @@ You are starting the diffity diff viewer so the user can see their changes in th
 
    > Diffity is running — check your browser.
    >
-   > Here's what you can do:
-   > - **/diffity-review** — get a code review on your changes
-   > - **/diffity-resolve** — fix issues from review comments
+   > When you're ready:
+   > - Leave comments on the diff in your browser, then run **/diffity-resolve** to fix them
+   > - Or run **/diffity-review** to get an AI code review