revspec 0.7.2 → 0.8.0

package/README.md

@@ -21,6 +21,22 @@ git clone https://github.com/icyrainz/revspec.git
 cd revspec && bun install && bun link
 ```
 
+### Claude Code plugin
+
+Install the `/revspec` skill for Claude Code:
+
+```bash
+/plugin marketplace add icyrainz/revspec
+/plugin install revspec
+```
+
+Or manually (clone + symlink, stays updated with `git pull`):
+
+```bash
+git clone https://github.com/icyrainz/revspec.git ~/.local/share/revspec
+ln -sfn ~/.local/share/revspec/skills/revspec ~/.claude/skills/revspec
+```
+
 ## Usage
 
 ```bash
@@ -137,16 +153,6 @@ Sends an AI reply that appears instantly in the reviewer's TUI.
 8. Repeat 3-7 until A (approve)
 ```
 
-### 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.
-
 ## Testing
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "revspec",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "Terminal-based spec review tool with real-time AI conversation",
   "type": "module",
   "license": "MIT",

package/skills/revspec/SKILL.md

@@ -1,17 +1,18 @@
 ---
 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.
+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. Works on any markdown file (ADRs, READMEs, etc.) but primarily designed for spec review. Works even when no .md file exists yet (inline or plan mode content gets saved to a file first). Supports `/revspec <path>` to review a specific file and resuming previous review sessions.
 ---
 
 # 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.
+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. Also works on any markdown file.
 
 ## 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
+- When the user provides a file path: `/revspec <path>`
 
 ## How It Works
 
@@ -21,12 +22,22 @@ You and the human communicate through revspec's CLI:
 
 The reviewer stays in the revspec TUI for the entire session. You run the watch/reply loop.
 
-## Step 1: Find the Spec File
+## Step 1: Find or Create the File
 
-Detect which spec was recently created or modified in this conversation. Look for:
+**If a file path was provided** (e.g., `/revspec docs/my-spec.md`):
+Use it directly — skip the search below.
+
+**Otherwise**, detect which file was recently created or modified in this conversation:
 - Files written to `docs/superpowers/specs/*.md`
 - The last `.md` file you created or edited
-- If ambiguous, ask the user which file to review
+
+**If the content was written inline** (proposed in conversation output or plan mode, never saved to a file):
+1. Save the content to a `.md` file — use `docs/superpowers/specs/<topic>.md` or a reasonable path in the project
+2. Confirm the file path with the user before proceeding
+
+If ambiguous, ask the user which file to review.
+
+**Resuming a previous review:** Check if a `.review.jsonl` file already exists for the target file (e.g., `spec.review.jsonl`). If it does, the TUI will restore previous threads automatically — let the user know they're resuming where they left off.
 
 ## Step 2: Launch Revspec
 
@@ -42,7 +53,21 @@ echo $TMUX
 tmux split-window -t "$TMUX_PANE" -v "revspec <spec-file>"
 ```
 
-**If no tmux:**
+**If no tmux, but on macOS:** detect the terminal and open a new window:
+
+```bash
+echo $TERM_PROGRAM
+```
+
+| `$TERM_PROGRAM` | Launch command |
+|---|---|
+| `Apple_Terminal` | `osascript -e 'tell application "Terminal" to do script "revspec <spec-file>"'` |
+| `iTerm.app` | `osascript -e 'tell application "iTerm2" to create window with default profile command "revspec <spec-file>"'` |
+| `WezTerm` | `wezterm start -- revspec <spec-file>` |
+| `ghostty` | `ghostty -e revspec <spec-file>` |
+| Other/unknown | Fall back to `osascript` with Terminal.app |
+
+**Otherwise (not macOS):**
 Tell the user: "Please run in another terminal: `revspec <spec-file>`"
 
 ## Step 3: Run the Watch/Reply Loop

package/src/state/review-state.ts

@@ -113,6 +113,36 @@ export class ReviewState {
     return this.threads.reduce((max, t) => (t.line > max.line ? t : max)).line;
   }
 
+  nextHeading(level: number): number | null {
+    const prefix = "#".repeat(level) + " ";
+    const guard = "#".repeat(level + 1);
+    for (let i = this.cursorLine; i < this.specLines.length; i++) {
+      const line = this.specLines[i];
+      if (line.startsWith(prefix) && !line.startsWith(guard)) return i + 1;
+    }
+    // Wrap: search from top
+    for (let i = 0; i < this.cursorLine - 1; i++) {
+      const line = this.specLines[i];
+      if (line.startsWith(prefix) && !line.startsWith(guard)) return i + 1;
+    }
+    return null;
+  }
+
+  prevHeading(level: number): number | null {
+    const prefix = "#".repeat(level) + " ";
+    const guard = "#".repeat(level + 1);
+    for (let i = this.cursorLine - 2; i >= 0; i--) {
+      const line = this.specLines[i];
+      if (line.startsWith(prefix) && !line.startsWith(guard)) return i + 1;
+    }
+    // Wrap: search from bottom
+    for (let i = this.specLines.length - 1; i >= this.cursorLine; i--) {
+      const line = this.specLines[i];
+      if (line.startsWith(prefix) && !line.startsWith(guard)) return i + 1;
+    }
+    return null;
+  }
+
   canApprove(): boolean {
     // No threads = clean approval (spec is good as-is)
     if (this.threads.length === 0) return true;

package/src/tui/app.ts

@@ -123,6 +123,21 @@ export async function runTui(
   // Command mode state
   let commandBuffer: string | null = null;
 
+  // Previous position for '' jump-back
+  let prevCursorLine: number = 1;
+  function savePrevPosition(): void {
+    prevCursorLine = state.cursorLine;
+  }
+
+  // Map visual row back to spec line number (for H/M/L)
+  function visualRowToSpecLine(targetRow: number): number {
+    for (let i = 0; i < state.specLines.length; i++) {
+      const row = i + countExtraVisualLines(state.specLines, i);
+      if (row >= targetRow) return i + 1;
+    }
+    return state.lineCount;
+  }
+
   // Active spec poll interval (for submit spinner leak prevention)
   let activeSpecPoll: ReturnType<typeof setInterval> | null = null;
 
@@ -203,6 +218,7 @@ export async function runTui(
     // :{N} — jump to line number
     const lineNum = parseInt(cmd, 10);
     if (!isNaN(lineNum) && lineNum > 0) {
+      savePrevPosition();
       state.cursorLine = Math.min(lineNum, state.lineCount);
       ensureCursorVisible();
       refreshPager();
@@ -271,6 +287,7 @@ export async function runTui(
       cursorLine: state.cursorLine,
       onResult: (lineNumber: number, query: string) => {
         searchQuery = query;
+        savePrevPosition();
         state.cursorLine = lineNumber;
         dismissOverlay();
         ensureCursorVisible();
@@ -289,6 +306,7 @@ export async function runTui(
       renderer,
       threads: state.threads,
       onSelect: (lineNumber: number) => {
+        savePrevPosition();
         state.cursorLine = lineNumber;
         dismissOverlay();
         ensureCursorVisible();
@@ -390,6 +408,16 @@ export async function runTui(
     { key: "[t", action: "prev-thread" },
     { key: "]r", action: "next-unread" },
     { key: "[r", action: "prev-unread" },
+    { key: "]1", action: "next-h1" },
+    { key: "[1", action: "prev-h1" },
+    { key: "]2", action: "next-h2" },
+    { key: "[2", action: "prev-h2" },
+    { key: "]3", action: "next-h3" },
+    { key: "[3", action: "prev-h3" },
+    { key: "''", action: "jump-back" },
+    { key: "H", action: "screen-top" },
+    { key: "M", action: "screen-middle" },
+    { key: "L", action: "screen-bottom" },
     { key: "zz", action: "center-cursor" },
     { key: "?", action: "help" },
     { key: "/", action: "search" },
@@ -512,11 +540,13 @@ export async function runTui(
           break;
         }
         case "goto-bottom":
+          savePrevPosition();
           state.cursorLine = state.lineCount;
           ensureCursorVisible();
           refreshPager();
           break;
         case "goto-top":
+          savePrevPosition();
           state.cursorLine = 1;
           ensureCursorVisible();
           refreshPager();
@@ -533,6 +563,7 @@ export async function runTui(
           if (searchQuery) {
             const match = findNextMatch(state.specLines, searchQuery, state.cursorLine, 1);
             if (match !== null) {
+              savePrevPosition();
               state.cursorLine = match;
               ensureCursorVisible();
             }
@@ -547,6 +578,7 @@ export async function runTui(
           if (searchQuery) {
             const match = findNextMatch(state.specLines, searchQuery, state.cursorLine, -1);
             if (match !== null) {
+              savePrevPosition();
               state.cursorLine = match;
               ensureCursorVisible();
             }
@@ -626,6 +658,11 @@ export async function runTui(
           break;
         }
         case "submit":
+          if (state.threads.length === 0) {
+            setBottomBarMessage(bottomBar, " No threads to submit.");
+            renderer.requestRender();
+            break;
+          }
           unresolvedGate(() => {
             appendEvent(jsonlPath, { type: "submit", author: "reviewer", ts: Date.now() });
 
@@ -688,6 +725,7 @@ export async function runTui(
         case "next-thread": {
           const next = state.nextThread();
           if (next !== null) {
+            savePrevPosition();
             state.cursorLine = next;
             ensureCursorVisible();
             refreshPager();
@@ -701,6 +739,7 @@ export async function runTui(
         case "prev-thread": {
           const prev = state.prevThread();
           if (prev !== null) {
+            savePrevPosition();
             state.cursorLine = prev;
             ensureCursorVisible();
             refreshPager();
@@ -714,6 +753,7 @@ export async function runTui(
         case "next-unread": {
           const nextLine = state.nextUnreadThread();
           if (nextLine !== null) {
+            savePrevPosition();
             state.cursorLine = nextLine;
             ensureCursorVisible();
             refreshPager();
@@ -727,6 +767,7 @@ export async function runTui(
         case "prev-unread": {
           const prevLine = state.prevUnreadThread();
           if (prevLine !== null) {
+            savePrevPosition();
             state.cursorLine = prevLine;
             ensureCursorVisible();
             refreshPager();
@@ -737,6 +778,69 @@ export async function runTui(
           }
           break;
         }
+        case "next-h1":
+        case "next-h2":
+        case "next-h3": {
+          const level = parseInt(action.slice(-1));
+          const next = state.nextHeading(level);
+          if (next !== null) {
+            savePrevPosition();
+            state.cursorLine = next;
+            ensureCursorVisible();
+            refreshPager();
+          } else {
+            setBottomBarMessage(bottomBar, ` No h${level} headings`);
+            renderer.requestRender();
+            setTimeout(() => { refreshPager(); }, 1500);
+          }
+          break;
+        }
+        case "prev-h1":
+        case "prev-h2":
+        case "prev-h3": {
+          const level = parseInt(action.slice(-1));
+          const prev = state.prevHeading(level);
+          if (prev !== null) {
+            savePrevPosition();
+            state.cursorLine = prev;
+            ensureCursorVisible();
+            refreshPager();
+          } else {
+            setBottomBarMessage(bottomBar, ` No h${level} headings`);
+            renderer.requestRender();
+            setTimeout(() => { refreshPager(); }, 1500);
+          }
+          break;
+        }
+        case "jump-back": {
+          const tmp = state.cursorLine;
+          state.cursorLine = prevCursorLine;
+          prevCursorLine = tmp;
+          ensureCursorVisible();
+          refreshPager();
+          break;
+        }
+        case "screen-top": {
+          const topRow = pager.scrollBox.scrollTop;
+          savePrevPosition();
+          state.cursorLine = visualRowToSpecLine(topRow);
+          refreshPager();
+          break;
+        }
+        case "screen-middle": {
+          const midRow = pager.scrollBox.scrollTop + Math.floor(pageSize() / 2);
+          savePrevPosition();
+          state.cursorLine = visualRowToSpecLine(midRow);
+          refreshPager();
+          break;
+        }
+        case "screen-bottom": {
+          const botRow = pager.scrollBox.scrollTop + pageSize() - 1;
+          savePrevPosition();
+          state.cursorLine = visualRowToSpecLine(botRow);
+          refreshPager();
+          break;
+        }
         case "help":
           showHelpOverlay();
           break;

package/src/tui/comment-input.ts

@@ -168,8 +168,10 @@ function createThreadView(
   const dialog = createDialog({
     renderer,
     title,
-    width: "80%",
-    height: "85%",
+    width: "70%",
+    height: "80%",
+    top: "8%",
+    left: "15%",
     borderColor: theme.blue,
     onDismiss: onCancel,
     hints: insertHints,
@@ -220,18 +222,29 @@ function createThreadView(
     scrollBox.add(renderMessage(msg));
   }
 
-  // --- Separator ---
-  const sep = new TextRenderable(renderer, {
-    content: "\u2500".repeat(40),
+  // --- Layout: pack bottom elements into a single container ---
+  // Outside tmux, opentui's ScrollBox expands over intermediate siblings.
+  // Keeping exactly 2 direct children (ScrollBox + bottomPanel) avoids the issue,
+  // matching the pattern that works in help/thread-list dialogs.
+  dialog.container.remove(dialog.hintBox.id);
+  const bottomPanel = new BoxRenderable(renderer, {
+    width: "100%",
+    height: 6, // separator(1) + textarea(4) + hints(1)
+    flexShrink: 0,
+    flexGrow: 0,
+    flexDirection: "column",
+  });
+  const sep = new BoxRenderable(renderer, {
     width: "100%",
     height: 1,
-    fg: theme.backgroundElement,
-    wrapMode: "none",
+    flexShrink: 0,
+    border: ["top"],
+    borderColor: theme.border,
   });
-  dialog.container.add(sep);
-
-  // --- Textarea (visible in both modes, focused only in insert) ---
-  dialog.container.add(textarea);
+  bottomPanel.add(sep);
+  bottomPanel.add(textarea);
+  bottomPanel.add(dialog.hintBox);
+  dialog.container.add(bottomPanel);
 
   // --- Mode helpers (need dialog.setHints available) ---
   function enterInsert(): void {

package/src/tui/confirm.ts

@@ -31,10 +31,10 @@ export function createConfirm(opts: ConfirmOptions): ConfirmOverlay {
   const dialog = createDialog({
     renderer,
     title,
-    width: "50%",
+    width: "44%",
     height: 9,
-    top: "35%",
-    left: "25%",
+    top: "30%",
+    left: "28%",
     borderColor: theme.warning,
     onDismiss: onCancel,
     hints: CONFIRM_HINTS,

package/src/tui/help.ts

@@ -50,10 +50,10 @@ export function createHelp(opts: {
   const dialog = createDialog({
     renderer,
     title: "Help",
-    width: "60%",
-    height: Math.min(34, renderer.height - 2),
+    width: "64%",
+    height: Math.min(32, renderer.height - 4),
     top: "10%",
-    left: "20%",
+    left: "18%",
     borderColor: theme.info,
     onDismiss: onClose,
     hints: HELP_HINTS,
@@ -92,6 +92,11 @@ export function createHelp(opts: {
     "  Esc       Clear search",
     "  ]t/[t     Next/prev thread",
     "  ]r/[r     Next/prev unread",
+    "  ]1/[1     Next/prev h1 heading",
+    "  ]2/[2     Next/prev h2 heading",
+    "  ]3/[3     Next/prev h3 heading",
+    "  ''        Jump to previous position",
+    "  H/M/L     Screen top/middle/bottom",
   ]);
 
   addHelpSection(dialog.content, renderer, "Review", [

package/src/tui/thread-list.ts

@@ -50,10 +50,10 @@ export function createThreadList(opts: ThreadListOptions): ThreadListOverlay {
   const dialog = createDialog({
     renderer,
     title: `Threads (${activeCount} active, ${allThreads.length} total)`,
-    width: "70%",
-    height: "60%",
-    top: "15%",
-    left: "15%",
+    width: "56%",
+    height: "50%",
+    top: "20%",
+    left: "22%",
     borderColor: theme.mauve,
     onDismiss: onCancel,
     hints: THREAD_LIST_HINTS,

package/src/tui/ui/dialog.ts

@@ -23,6 +23,7 @@ export interface DialogOptions {
 export interface DialogComponents {
   container: BoxRenderable;
   content: ScrollBoxRenderable;
+  hintBox: BoxRenderable;
   hintText: TextRenderable;
   setHints: (hints: Hint[]) => void;
   cleanup: () => void;
@@ -102,5 +103,5 @@ export function createDialog(opts: DialogOptions): DialogComponents {
     renderer.keyInput.off("keypress", keyHandler);
   }
 
-  return { container, content, hintText, setHints, cleanup };
+  return { container, content, hintBox, hintText, setHints, cleanup };
 }

package/src/tui/ui/theme.ts

@@ -1,8 +1,8 @@
 export const theme = {
   // Surfaces
-  base: "#1e1e2e",
+  base: undefined,
   backgroundPanel: "#313244",
-  backgroundElement: "#45475a",
+  backgroundElement: undefined,
 
   // Text hierarchy
   text: "#cdd6f4",