revspec 0.2.2 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "revspec",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "type": "module",
   "bin": {
     "revspec": "./bin/revspec.ts"

package/scripts/install-skill.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+set -e
+
+# Install/sync the revspec Claude Code skill to ~/.claude/skills/revspec/
+# Run this after cloning the repo or pulling updates.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_SKILL="$SCRIPT_DIR/../skills/revspec"
+LOCAL_SKILL="$HOME/.claude/skills/revspec"
+
+if [ ! -f "$REPO_SKILL/SKILL.md" ]; then
+  echo "Error: skill not found at $REPO_SKILL/SKILL.md"
+  exit 1
+fi
+
+mkdir -p "$LOCAL_SKILL"
+cp "$REPO_SKILL/SKILL.md" "$LOCAL_SKILL/SKILL.md"
+
+echo "Installed revspec skill to $LOCAL_SKILL"
+echo "Use /revspec in Claude Code to launch spec reviews."

package/scripts/release.sh

@@ -34,18 +34,17 @@ if [[ ! $REPLY =~ ^[Yy]$ ]]; then
   exit 0
 fi
 
-# Tag if not already tagged
-if ! git tag -l "v$VERSION" | grep -q .; then
-  git tag "v$VERSION"
-fi
+# Tag current commit (force-update if tag exists)
+git tag -f "v$VERSION"
 
 # Publish to npm
 echo ""
 echo "Publishing to npm..."
 npm publish
 
-# Push
-git push && git push origin "v$VERSION"
+# Push commit and tag (force-update remote tag if it exists)
+git push
+git push origin "v$VERSION" --force
 
 echo ""
 echo "Released v$VERSION"

package/skills/revspec/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: revspec
+description: Launch revspec to review a spec document with real-time AI feedback. Use when the user says /revspec, "review the spec", "let me review this", or after generating a spec/design document that needs human review. Also use when a brainstorming or writing-plans skill produces a markdown spec file.
+---
+
+# Revspec — Live Spec Review
+
+Launch revspec to let the human review a spec document with real-time AI conversation. The reviewer comments on specific lines, you reply instantly, and the discussion continues until the spec is approved.
+
+## When to Use
+
+- After writing or updating a spec/design document
+- When the user explicitly asks to review a spec
+- After the brainstorming or writing-plans skill produces a `.md` file
+
+## How It Works
+
+You and the human communicate through revspec's CLI:
+- `revspec watch <file.md>` — blocks until the reviewer adds comments, then returns them
+- `revspec reply <file.md> <threadId> "<text>"` — sends your reply (appears in the TUI instantly)
+
+The reviewer stays in the revspec TUI for the entire session. You run the watch/reply loop.
+
+## Step 1: Find the Spec File
+
+Detect which spec was recently created or modified in this conversation. Look for:
+- Files written to `docs/superpowers/specs/*.md`
+- The last `.md` file you created or edited
+- If ambiguous, ask the user which file to review
+
+## Step 2: Launch Revspec
+
+Check if running inside tmux:
+
+```bash
+echo $TMUX
+```
+
+**If tmux is available:**
+```bash
+tmux split-window -v "revspec <spec-file>"
+```
+
+**If no tmux:**
+Tell the user: "Please run in another terminal: `revspec <spec-file>`"
+
+## Step 3: Run the Watch/Reply Loop
+
+Start watching for reviewer comments:
+
+```bash
+revspec watch <spec-file>
+```
+
+This blocks until the reviewer adds comments. When it returns, you'll see output like:
+
+```
+--- New threads ---
+
+[t1] line 14 (new):
+  Context:
+    12: The system uses polling...
+   >14: it sends a notification via webhook.
+    16: resource state.
+  Comment: "this is unclear"
+
+To reply: revspec reply spec.md <threadId> "<your response>"
+When done replying, run: revspec watch spec.md
+```
+
+**For each comment:** Read the context, understand the concern, and reply thoughtfully:
+
+```bash
+revspec reply <spec-file> t1 "Good point. I'll clarify — it uses polling to detect changes, then sends a webhook notification to downstream services."
+```
+
+After replying to all comments, run `revspec watch` again to wait for the next batch.
+
+**If watch returns "Session ended. Reviewer exited revspec."** — the reviewer closed the TUI. Check the review JSON for resolved threads that require spec changes (see Step 4). If no resolved threads, stop and wait — the user can invoke `/revspec` again later to resume.
+
+**Important:** Your replies should be substantive — address the concern, explain your reasoning, or acknowledge the change you'll make. Don't just say "noted" or "will fix."
+
+## Step 4: Handle Session End or Approval
+
+The watch loop ends in one of two ways:
+
+### Session ended (reviewer exited with `:q`)
+
+Read the review JSON and check for **resolved threads**. Resolved = the reviewer acknowledged your reply and wants you to make that change.
+
+**If resolved threads with actionable feedback exist:**
+1. Rewrite the spec incorporating the feedback from resolved threads
+2. Commit the updated spec
+3. Append a round marker to the JSONL:
+   ```bash
+   echo '{"type":"round","author":"owner","round":2,"ts":'$(date +%s000)'}' >> <spec-file>.review.live.jsonl
+   ```
+4. Launch a new revspec session (go back to Step 2) so the reviewer can verify the changes
+
+**If no resolved threads (or only open/pending threads):**
+The reviewer left without resolving anything — stop and wait. The user can invoke `/revspec` again later.
+
+### Approved (reviewer pressed `a`)
+
+Watch returns:
+```
+Review approved.
+Review file: <path-to-review.json>
+```
+
+The spec is finalized. Report: "Spec approved and finalized at `<spec-file>`. Ready to proceed with implementation."
+
+## Thread Status Meanings
+
+- **Open** — under discussion, AI replied, reviewer hasn't responded yet
+- **Pending** — owner replied, waiting for reviewer to read
+- **Resolved** — reviewer acknowledged the plan, AI should make the change
+- **Approve** — spec is final, proceed to implementation
+
+## Loop Summary
+
+```
+1. Launch revspec on spec file
+2. Watch for comments
+3. Reply to each comment
+4. Watch again (repeat 2-3 until session-end or approval)
+5. On session-end: check for resolved threads
+6. If resolved threads need spec changes: rewrite spec, launch new round (go to 1)
+7. On approval: spec is finalized, done
+```
+
+## Tips
+
+- Read the full thread history in the watch output before replying — the reviewer may have added context across multiple messages
+- When rewriting the spec after approval, address every resolved thread — the reviewer trusted you to incorporate their feedback
+- Keep replies concise but complete — the reviewer can see them instantly and will follow up if needed
+- If a comment is about a section you're unsure about, say so honestly — "I'm not sure about the best approach here. Options are X or Y — which do you prefer?"

package/src/protocol/live-events.ts

@@ -29,6 +29,7 @@ const VALID_LIVE_EVENT_TYPES: readonly LiveEventType[] = [
   "approve",
   "delete",
   "round",
+  "session-end",
 ];
 
 export function isValidLiveEvent(value: unknown): value is LiveEvent {
@@ -47,8 +48,8 @@ export function isValidLiveEvent(value: unknown): value is LiveEvent {
   if (typeof v.ts !== "number") return false;
   if (typeof v.author !== "string") return false;
 
-  // threadId required for all except approve and round
-  if (v.type !== "approve" && v.type !== "round") {
+  // threadId required for all except approve, round, and session-end
+  if (v.type !== "approve" && v.type !== "round" && v.type !== "session-end") {
     if (typeof v.threadId !== "string") return false;
   }