revspec 0.2.2 → 0.3.0

package/CLAUDE.md

@@ -4,16 +4,24 @@
 - npm: `revspec` | GitHub: icyrainz/revspec
 - Run: `bun run bin/revspec.ts <file.md>`
 - Test: `bun test`
-- Release: `./scripts/release.sh [patch|minor|major]`
+- Release: `./scripts/release.sh` (version is set manually in package.json)
+- Dev: `bun link` to symlink local build to global `revspec` command
 
 ## OpenTUI Gotchas
-- Don't use StyledText for large content (BigInt FFI crash)
+- Don't use StyledText at all — BigInt FFI crash happens even on small content
 - Don't use ANSI escape codes in TextRenderable content (renders as literal text)
 - MarkdownRenderable needs `syntaxStyle` + `conceal: true` for proper rendering
 - Use `visible: false` to hide renderables, not removal/re-addition
+- ScrollBox: don't use `stickyScroll` with manual scrolling (fights scroll position)
+- ScrollBox: `scrollBy` overshoots silently on large deltas — use `scrollTo` with clamped position
+- Textarea consumes Ctrl+D/U (emacs bindings) — blur textarea in normal mode for vim-style scroll
 
 ## Conventions
 - Line mode is default, markdown mode via `m` toggle
 - Tab to submit in all text inputs (works through tmux)
 - Destructive actions need confirmation (dd double-tap, approve confirm dialog)
 - All review actions auto-switch to line mode
+- Thread popup uses vim-style normal/insert modes (blur textarea in normal)
+- Hint bars use `[key] action` bracket format consistently
+- No inline comment previews in pager — gutter indicators only (▌/█/✓)
+- Live integration: JSONL for communication, `revspec watch`/`reply` CLI subcommands

package/README.md

@@ -1,10 +1,10 @@
 # Revspec
 
-A review tool for AI-generated spec documents. Unlike traditional spec review (human reviews, human author edits), the author here is an AI — it reads structured feedback and acts on every comment instantly.
+A review tool for AI-generated spec documents with real-time AI conversation. Comment on specific lines, get AI replies instantly, resolve discussions, and approve — all without leaving the terminal.
 
 ## Why
 
-When an AI generates a spec, the human review step breaks the agentic loop. You have to open the file separately, read it, then type unstructured feedback in the terminal. Revspec closes this loop with a TUI that lets you comment inline and outputs structured JSON the AI can act on immediately.
+When an AI generates a spec, the human review step breaks the agentic loop. You have to open the file separately, read it, then type unstructured feedback. Revspec closes this loop with a TUI that lets you comment inline and discuss with the AI in real-time — like a chatroom anchored to the spec.
 
 ## Install
 
@@ -27,67 +27,124 @@ cd revspec && bun install && bun link
 revspec spec.md
 ```
 
-Opens a TUI with two modes:
-
-- **Markdown mode** (default) — rendered markdown for reading. `j/k` scrolls.
-- **Line mode** (`m`) — line numbers + thread indicators for commenting.
+Opens a TUI in line mode with vim-style navigation. Press `c` on any line to open a thread and start commenting.
 
 ### Keybindings
 
 | Key | Action |
 |-----|--------|
-| `j/k` | Scroll down/up |
+| `j/k` | Move cursor down/up |
 | `gg` / `G` | Go to top / bottom |
 | `Ctrl+D/U` | Half page down/up |
 | `m` | Toggle markdown / line mode |
-| `c` | Comment on line / view thread / reply |
+| `c` | Open thread / comment on line |
 | `r` | Resolve thread (toggle) |
 | `R` | Resolve all pending |
 | `dd` | Delete draft comment (double-tap) |
 | `/` | Search |
 | `n/N` | Next/prev search match |
 | `]t/[t` | Next/prev thread |
+| `]r/[r` | Next/prev unread AI reply |
 | `l` | List threads |
 | `a` | Approve spec |
-| `:w` | Save draft |
-| `:q` | Quit (blocks if unsaved) |
-| `:wq` | Save and quit |
-| `:q!` | Quit without saving |
+| `:w` | Merge changes to review JSON |
+| `:wq` | Merge and quit |
+| `:q` | Quit (only if merged) |
+| `:q!` | Quit without merging |
 | `?` | Help |
 
-### Comment input
+### Thread popup
+
+The thread popup has two modes:
+
+- **Insert mode** — type your comment, `Tab` sends, `Esc` switches to normal mode
+- **Normal mode** — `j/k` and `Ctrl+D/U` scroll the conversation history, `c` to reply, `r` to resolve, `Esc` to close
+
+## Live AI Integration
+
+Revspec supports real-time communication with AI coding tools (Claude Code, opencode, etc.) via two CLI subcommands:
+
+### `revspec watch <file.md>`
+
+Blocks until the reviewer adds comments, then returns them with spec context:
+
+```
+=== New Comments ===
+Thread: t1 (line 14)
+  Context:
+      12: The system uses polling...
+    > 14: it sends a notification via webhook.
+      16: resource state.
+  [reviewer]: this is unclear
+
+To reply: revspec reply spec.md t1 "<your response>"
+When done replying, run: revspec watch spec.md
+```
+
+### `revspec reply <file.md> <threadId> "<text>"`
+
+Sends an AI reply that appears instantly in the reviewer's TUI:
 
-`Tab` submits. `Enter` adds newline. `Esc` cancels.
+```bash
+revspec reply spec.md t1 "Good point. I'll clarify the polling vs webhook distinction."
+```
 
-## Review Protocol
+### The loop
 
-Revspec outputs a `.review.json` file next to the spec:
+```
+1. AI generates spec
+2. AI launches: revspec spec.md (in tmux pane or separate terminal)
+3. AI runs: revspec watch spec.md (blocks)
+4. Reviewer comments on lines in the TUI
+5. Watch returns with comments → AI replies → watch again
+6. Reviewer resolves threads → approves
+7. AI reads review JSON, rewrites spec, launches new round
+8. Repeat until clean approval
+```
+
+### Claude Code skill
+
+Install the `/revspec` skill for Claude Code:
+
+```bash
+./scripts/install-skill.sh
+```
+
+Then use `/revspec` in Claude Code after generating a spec.
+
+## Protocol
+
+Communication happens through a JSONL file (`spec.review.live.jsonl`) — append-only, both sides write to it. On session end, events are merged into `spec.review.json`.
+
+### Event types
+
+```jsonl
+{"type":"comment","threadId":"t1","line":14,"author":"reviewer","text":"unclear","ts":1710400000}
+{"type":"reply","threadId":"t1","author":"owner","text":"I'll fix it","ts":1710400005}
+{"type":"resolve","threadId":"t1","author":"reviewer","ts":1710400010}
+{"type":"approve","author":"reviewer","ts":1710400050}
+```
+
+### Review JSON
 
 ```json
 {
   "file": "spec.md",
   "threads": [
     {
-      "id": "1",
-      "line": 12,
-      "status": "open",
+      "id": "t1",
+      "line": 14,
+      "status": "resolved",
       "messages": [
-        { "author": "human", "text": "why webhook not polling?" }
+        { "author": "reviewer", "text": "this is unclear", "ts": 1710400000 },
+        { "author": "owner", "text": "I'll restructure this section", "ts": 1710400005 }
       ]
     }
   ]
 }
 ```
 
-Thread statuses: `open` (needs AI attention), `pending` (AI replied), `resolved`, `outdated`.
-
-The AI reads this JSON, addresses comments, updates the spec, rewrites the review file with updated anchors/statuses, and re-invokes Revspec. The loop continues until the human approves.
-
-## Roadmap
-
-- **v1** (current): Built-in TUI pager
-- **v2**: Neovim plugin, web UI, diff highlighting
-- **v3**: Google Docs integration
+Thread statuses: `open` (owner's turn), `pending` (reviewer's turn), `resolved`, `outdated`.
 
 ## License
 

package/bin/revspec.ts

@@ -66,7 +66,8 @@ const draftPath = join(specDir, `${specBase}.review.draft.json`);
 
 // 3. Launch TUI (skip if REVSPEC_SKIP_TUI=1)
 if (process.env.REVSPEC_SKIP_TUI !== "1") {
-  await runTui(specPath, reviewPath, draftPath);
+  const pkg = await Bun.file(new URL("../package.json", import.meta.url)).json();
+  await runTui(specPath, reviewPath, draftPath, pkg.version);
 }
 
 // 4. After TUI exits, check if approved via JSONL

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "revspec",
-  "version": "0.2.2",
+  "version": "0.3.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;
   }