claude-plugin-viban 1.3.13 → 1.3.14

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "viban",
-  "version": "1.3.13",
+  "version": "1.3.14",
   "description": "Terminal Kanban TUI for AI-human collaborative issue tracking",
   "author": {
     "name": "happy-nut"

package/bin/viban

@@ -118,15 +118,23 @@ case "$1" in
 esac
 
 IN_TUI=false
+_CLEANUP_DONE=false
 cleanup() {
+    # Guard: prevent double execution (INT/TERM fires cleanup, then exit 0 fires EXIT)
+    $_CLEANUP_DONE && return
+    _CLEANUP_DONE=true
     # Skip cleanup in subshells — EXIT trap fires in $() command substitutions
     [[ ${ZSH_SUBSHELL:-0} -gt 0 ]] && return
     # Kill background sync if running
     [[ -n "${_sync_pid:-}" ]] && kill "$_sync_pid" 2>/dev/null && wait "$_sync_pid" 2>/dev/null
+    # Release file lock if held
+    ${_VIBAN_LOCK_HELD:-false} && rm -rf "${VIBAN_DATA_DIR}/.lock"
     _stop_coproc
-    printf '\033[?25h\033[0m'
-    stty echo 2>/dev/null
-    $IN_TUI && clear
+    if $IN_TUI; then
+        printf '\033[?25h\033[0m'
+        stty echo 2>/dev/null
+        clear
+    fi
     exit 0
 }
 trap cleanup INT TERM EXIT
@@ -209,27 +217,30 @@ source "$VIBAN_SCRIPT_DIR/lib/commands.zsh"
 main() {
     check_deps
     init_json
+    # Auto-archive old done issues (skip when user explicitly runs archive)
+    [[ "${1:-}" != "archive" ]] && auto_archive
     case "${1:-}" in
         list)   shift; cmd_list "$@";;
         history) cmd_history;;
-        add)    shift; cmd_add "$@";;
-        attach) shift; cmd_attach "$@";;
-        assign) cmd_assign "$2";;
-        review) cmd_review "$2";;
-        done)   shift; cmd_done "$@";;
-        move)   cmd_move "$2" "$3";;
+        add)    shift; _with_lock cmd_add "$@";;
+        attach) shift; _with_lock cmd_attach "$@";;
+        assign) shift; _with_lock cmd_assign "$@";;
+        review) shift; _with_lock cmd_review "$@";;
+        done)   shift; _with_lock cmd_done "$@";;
+        move)   shift; _with_lock cmd_move "$@";;
         get)    cmd_get "$2";;
-        comment) shift; cmd_comment "$@";;
-        link)   cmd_link "$2" "$3" "$4";;
-        unlink) shift; cmd_unlink "$@";;
-        edit)   [[ -z "$2" ]] && { echo "Usage: viban edit <id>"; exit 1; }; edit_issue "$2";;
-        priority) cmd_priority "$2" "$3";;
+        comment) shift; _with_lock cmd_comment "$@";;
+        link)   _with_lock cmd_link "$2" "$3" "$4";;
+        unlink) shift; _with_lock cmd_unlink "$@";;
+        edit)   [[ -z "$2" ]] && { echo "Usage: viban edit <id>"; exit 1; }; _with_lock edit_issue "$2";;
+        priority) _with_lock cmd_priority "$2" "$3";;
         stats)   cmd_stats;;
-        backup)  cmd_backup;;
-        restore) shift; cmd_restore "$@";;
+        backup)  _with_lock cmd_backup;;
+        restore) shift; _with_lock cmd_restore "$@";;
         changelog) cmd_changelog "$2";;
         export)  cmd_export "$2";;
-        migrate) cmd_migrate;;
+        migrate) _with_lock cmd_migrate;;
+        archive) shift; _with_lock cmd_archive "$@";;
         sync)   shift; cmd_sync "$@";;
         --version|-v)
             # Get version from package.json
@@ -260,8 +271,8 @@ main() {
             echo "  viban priority <id> <P0-P3>   Set priority"
             echo "  viban assign      Assign first backlog (by priority)"
             echo "  viban review      → Human Review"
-            echo "  viban move <id> <status>     Move to status (backlog,in_progress,review,done)"
-            echo "  viban done <id> [--purge]    Complete (--purge to permanently delete)"
+            echo "  viban move <id> <status> [--force]  Move to status (done requires review; --force to bypass)"
+            echo "  viban done <id> [--purge] [--force]  Complete (requires review status; --force to bypass)"
             echo "  viban comment <id> \"msg\"  Add comment to task"
             echo "  viban link <id> blocks <id>  Add dependency"
             echo "  viban unlink <id> blocks <id>  Remove dependency"
@@ -272,6 +283,7 @@ main() {
             echo "  viban restore [f] List or restore a backup"
             echo "  viban changelog [range]  Generate changelog from commits"
             echo "  viban export [md|html]   Export board as markdown or HTML"
+            echo "  viban archive [--days N]  Archive done issues older than N days (default 30)"
             echo "  viban migrate     Migrate: extract type from title"
             echo "  viban sync        Sync with external issue tracker (GitHub, etc.)"
             echo "  viban update      Update to latest version (if available)"

package/commands/approve.md

@@ -0,0 +1,15 @@
+---
+description: "Approve a reviewed issue — merge branch, cleanup, mark done"
+---
+
+Run `/viban:approve <id>` after reviewing an issue with `/viban:review`.
+
+Usage: `/viban:approve <id>`
+
+What it does:
+1. Merges the issue branch (via PR squash-merge or local merge)
+2. Cleans up worktree and branch
+3. Marks the card as done
+4. Restores any stashed changes from `/viban:review`
+
+**IMPORTANT:** Never read or write `viban.json` directly — always use `viban` CLI commands.

package/commands/reject.md

@@ -0,0 +1,16 @@
+---
+description: "Reject a reviewed issue — return to in_progress with feedback"
+---
+
+Run `/viban:reject <id> [feedback]` after reviewing an issue with `/viban:review`.
+
+Usage: `/viban:reject <id> [feedback text]`
+
+What it does:
+1. Moves the card back to in_progress (worktree stays intact)
+2. Records feedback as a comment on the issue (and PR if exists)
+3. Restores any stashed changes from `/viban:review`
+
+The agent can then pick the issue back up and address the feedback.
+
+**IMPORTANT:** Never read or write `viban.json` directly — always use `viban` CLI commands.

package/commands/review.md

@@ -0,0 +1,21 @@
+---
+description: "Checkout a review issue's branch for IDE review"
+---
+
+Run `/viban:review` to checkout a review-status issue's branch for IDE review.
+
+Usage: `/viban:review [id]`
+
+- `id`: (optional) specific issue ID. If omitted, picks the first review card.
+
+What it does:
+1. Detects review mode (PR / branch / main-direct)
+2. Stashes local changes if needed
+3. Checks out the branch via detached HEAD (worktree stays intact)
+4. Shows diff summary
+
+After reviewing in your IDE, run:
+- `/viban:approve <id>` — merge and mark done
+- `/viban:reject <id> [feedback]` — back to in_progress with feedback
+
+**IMPORTANT:** Never read or write `viban.json` directly — always use `viban` CLI commands.

package/docs/CLAUDE.md

@@ -57,27 +57,30 @@ EOF
 
 ## Workflow Rules
 
-### 🔴 Worktree 사용 금지
-- **main repo에서 feature branch로 직접 작업**
-- worktree 생성/사용 금지 (사용자 명시적 요청)
+### Worktree-Based Workflow
+- 모든 이슈 작업은 `.viban/worktrees/{ID}` 에서 격리된 워크트리로 수행
+- 메인 워크트리는 사용자 작업용으로 깨끗하게 유지
 - 브랜치 네이밍: `issue-{ISSUE_ID}` (예: `issue-78`)
 
-### Branch-Based Workflow
 ```bash
-# 1. main에서 분기
-git checkout main && git pull
-git checkout -b issue-{ISSUE_ID}
+# 1. 워크트리 생성
+REPO_ROOT=$(git rev-parse --show-toplevel)
+git worktree add -b issue-{ISSUE_ID} "$REPO_ROOT/.viban/worktrees/{ISSUE_ID}" origin/main
 
-# 2. 작업 후 push
+# 2. 워크트리 안에서 작업 후 push
+cd "$REPO_ROOT/.viban/worktrees/{ISSUE_ID}"
 git push -u origin issue-{ISSUE_ID}
 
 # 3. PR 생성
 gh pr create --title "..." --body "..."
 ```
 
+- 워크트리는 `/viban:approve`가 merge 후 정리
+- `/viban:reject` 시 워크트리 유지 (재작업용)
+
 ### Base Branch Sync
-- Before branch creation: `git fetch origin main`
-- Before PR push: `git fetch origin main && git rebase origin/main`
+- Before worktree creation: `git fetch origin main`
+- Before PR push: `git fetch origin main && git rebase origin/main` (inside worktree)
 - Resolve conflicts if any before pushing
 
 ## Shell Script Rules

package/install.sh

@@ -169,6 +169,20 @@ npm install -g claude-plugin-viban
 echo ""
 echo -e "${GREEN}✓${NC} viban installed globally"
 
+# Install zsh completion
+VIBAN_COMP_SRC="$(npm root -g)/claude-plugin-viban/scripts/_viban"
+if [[ -f "$VIBAN_COMP_SRC" ]]; then
+    COMP_DIR="${HOME}/.zsh/completions"
+    mkdir -p "$COMP_DIR"
+    cp "$VIBAN_COMP_SRC" "$COMP_DIR/_viban"
+    if ! grep -q 'fpath.*\.zsh/completions' "${HOME}/.zshrc" 2>/dev/null; then
+        # shellcheck disable=SC2016
+        echo 'fpath=(~/.zsh/completions $fpath)' >> "${HOME}/.zshrc"
+        echo 'autoload -Uz compinit && compinit' >> "${HOME}/.zshrc"
+    fi
+    echo -e "${GREEN}✓${NC} zsh completion installed (restart shell to activate)"
+fi
+
 # Register Claude Code plugin
 echo ""
 echo -e "${BOLD}Registering Claude Code plugin...${NC}"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin-viban",
-  "version": "1.3.13",
+  "version": "1.3.14",
   "description": "Terminal Kanban TUI for AI-human collaborative issue tracking",
   "main": "bin/viban",
   "bin": {

package/scripts/_viban

@@ -0,0 +1,117 @@
+#compdef viban
+# zsh completion for viban - Kanban board CLI
+
+_viban_issue_ids() {
+    local -a ids
+    if [[ -f "${VIBAN_DATA_DIR:-${PWD}/.viban}/viban.json" ]]; then
+        local json="${VIBAN_DATA_DIR:-${PWD}/.viban}/viban.json"
+        ids=(${(f)"$(jq -r '.issues[] | select(.status != "done") | "#\(.id) [\(.priority)] \(.title)"' "$json" 2>/dev/null)"})
+        _describe 'issue' ids
+    fi
+}
+
+_viban() {
+    local -a commands=(
+        'list:Show board'
+        'history:Show completed issues'
+        'add:Add task'
+        'attach:Attach files to task'
+        'assign:Assign first backlog issue'
+        'review:Move to review'
+        'done:Complete task'
+        'move:Move to status'
+        'get:Get task details'
+        'comment:Add comment'
+        'link:Add dependency'
+        'unlink:Remove dependency'
+        'edit:Edit task in editor'
+        'priority:Set priority'
+        'stats:Show statistics'
+        'archive:Archive old done issues'
+        'backup:Snapshot viban.json'
+        'restore:Restore a backup'
+        'changelog:Generate changelog'
+        'export:Export board'
+        'migrate:Migrate data'
+        'sync:Sync with GitHub'
+        'update:Update to latest version'
+        'help:Show help'
+    )
+
+    local -a statuses=('backlog' 'in_progress' 'review' 'done')
+    local -a priorities=('P0:Critical' 'P1:High' 'P2:Medium' 'P3:Low')
+    local -a types=('bug' 'feat' 'chore' 'refactor')
+
+    if (( CURRENT == 2 )); then
+        _describe 'command' commands
+        return
+    fi
+
+    case "${words[2]}" in
+        done|get|edit|review|comment|attach|priority)
+            if (( CURRENT == 3 )); then
+                _viban_issue_ids
+            fi
+            ;;
+        move)
+            if (( CURRENT == 3 )); then
+                _viban_issue_ids
+            elif (( CURRENT == 4 )); then
+                _describe 'status' statuses
+            fi
+            ;;
+        link|unlink)
+            if (( CURRENT == 3 )); then
+                _viban_issue_ids
+            elif (( CURRENT == 4 )); then
+                local -a rels=('blocks')
+                _describe 'relation' rels
+            elif (( CURRENT == 5 )); then
+                _viban_issue_ids
+            fi
+            ;;
+        priority)
+            if (( CURRENT == 3 )); then
+                _viban_issue_ids
+            elif (( CURRENT == 4 )); then
+                _describe 'priority' priorities
+            fi
+            ;;
+        list)
+            _arguments \
+                '--status[Filter by status]:status:(backlog in_progress review done)' \
+                '--priority[Filter by priority]:priority:(P0 P1 P2 P3)' \
+                '--type[Filter by type]:type:(bug feat chore refactor)' \
+                '--search[Search text]:text:'
+            ;;
+        export)
+            if (( CURRENT == 3 )); then
+                local -a formats=('md:Markdown' 'html:HTML')
+                _describe 'format' formats
+            fi
+            ;;
+        add)
+            _arguments \
+                '--parent[Parent issue ID]:id:_viban_issue_ids' \
+                '--type[Issue type]:type:(bug feat chore refactor)' \
+                '--priority[Priority]:priority:(P0 P1 P2 P3)' \
+                '--desc[Description]:text:'
+            ;;
+        archive)
+            _arguments \
+                '--days[Days threshold]:days:' \
+                '--dry-run[Preview changes]'
+            ;;
+        sync)
+            _arguments \
+                '--init[Initialize sync]' \
+                '--dry-run[Preview changes]' \
+                '--push-new[Push local issues]' \
+                '--pull-only[Pull only]' \
+                '--push-only[Push only]' \
+                '--auto[Silent auto-sync]'
+            ;;
+    esac
+}
+
+_viban "$@"

package/skills/approve/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: approve
+description: "Approve a reviewed issue — merge branch, cleanup worktree, mark done"
+---
+
+# /approve
+
+Approve a review-status issue after IDE review. Merges the branch, cleans up the worktree, and marks the card done.
+
+> **CLI only** (no direct viban.json access)
+
+**Input**: `$ARGUMENTS` (required: issue ID)
+
+---
+
+## Output Rules
+
+- **Do NOT output any preamble.**
+- Start executing Step 1 immediately.
+
+---
+
+## Step 1: Validate
+
+```bash
+viban get $ID
+```
+
+Confirm the issue is in `review` status. If not, tell the user and exit.
+
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel)
+BRANCH="issue-$ID"
+PREV_BRANCH=$(git branch --show-current)
+```
+
+If `$PREV_BRANCH` is empty (detached HEAD from `/viban:review`), determine the main branch:
+
+```bash
+PREV_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
+[ -z "$PREV_BRANCH" ] && PREV_BRANCH="main"
+```
+
+---
+
+## Step 2: Return to main branch
+
+```bash
+git checkout "$PREV_BRANCH"
+```
+
+---
+
+## Step 3: Merge
+
+### If PR exists
+
+```bash
+PR_NUM=$(gh pr list --head "$BRANCH" --json number --jq '.[0].number' 2>/dev/null)
+```
+
+If PR found:
+
+```bash
+gh pr merge "$PR_NUM" --squash --delete-branch
+```
+
+Clean up worktree if it still exists:
+
+```bash
+WT_DIR="$REPO_ROOT/.viban/worktrees/$ID"
+[ -d "$WT_DIR" ] && git worktree remove "$WT_DIR" --force 2>/dev/null
+```
+
+### If no PR (branch only)
+
+Remove worktree to free the branch:
+
+```bash
+WT_DIR="$REPO_ROOT/.viban/worktrees/$ID"
+[ -d "$WT_DIR" ] && git worktree remove "$WT_DIR" --force 2>/dev/null
+```
+
+Merge locally:
+
+```bash
+git merge "$BRANCH" --no-ff -m "Merge issue-$ID: <title>"
+git branch -d "$BRANCH"
+```
+
+If merge conflicts: help user resolve.
+
+### If no branch (main-direct work)
+
+Nothing to merge. Proceed to Step 4.
+
+---
+
+## Step 4: Complete
+
+```bash
+viban done $ID
+```
+
+Restore stash if one was created during `/viban:review`:
+
+```bash
+STASH=$(git stash list | grep "viban-review: before reviewing #$ID" | head -1 | cut -d: -f1)
+[ -n "$STASH" ] && git stash pop "$STASH"
+```
+
+Report: "Issue #$ID approved and merged."

package/skills/assign/SKILL.md

@@ -59,32 +59,46 @@ Assess whether the issue description provides enough context to start working.
 - **Clear** → **proceed directly to Step 4. Do NOT ask the user for confirmation. Do NOT ask "should I start?". Just start.**
 - **Unclear** → interview the user with AskUserQuestion to gather missing context, then proceed to Step 4 immediately.
 
-## Step 4: Execute Workflow
+## Step 4: Locate Worktree
+
+`viban assign` automatically creates a worktree. Locate it:
+
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel)
+WT_DIR="$REPO_ROOT/.viban/worktrees/$ISSUE_ID"
+BRANCH="issue-$ISSUE_ID"
+```
+
+**All subsequent work MUST happen inside `$WT_DIR`.**
+
+## Step 5: Execute Workflow
 
 Follow the workflow from Step 0. If no workflow was found, use this default pipeline:
 
-### 4.1 Analyze
+### 5.1 Analyze
 - Explore the codebase to understand the issue
 - Identify root cause and scope of change
 
-### 4.2 Implement
-- Create a branch: `git checkout -b issue-{ISSUE_ID}`
+### 5.2 Implement
+- Work inside the worktree: `cd $WT_DIR`
 - Make the fix/feature changes
 - Write or update tests as appropriate
 
-### 4.3 Verify
-- Run build and tests to confirm the fix works
+### 5.3 Verify
+- Run build and tests inside the worktree to confirm the fix works
 - Verify no regressions
 
-### 4.4 Ship (MANDATORY — execute ALL 4 commands in sequence)
+### 5.4 Ship (MANDATORY — execute ALL 4 commands in sequence)
 
 ```bash
+cd $WT_DIR
+
 # 1. Commit
 git add -A
 git commit -m "fix: {description} (#$ISSUE_ID)"
 
 # 2. Push
-git push -u origin issue-$ISSUE_ID
+git push -u origin $BRANCH
 
 # 3. Create PR (REQUIRED — do NOT skip)
 gh pr create --title "fix: {description}" --body "Resolves #$ISSUE_ID
@@ -100,17 +114,20 @@ viban review $ISSUE_ID
 ```
 
 **If any command fails**: fix the error and retry. Do NOT skip any step.
+**Do NOT remove the worktree** — it stays for the review/approve/reject flow.
 
 ### Completion Checklist (ALL must be true before you stop)
 
 - [ ] PR created (you have a PR URL)
 - [ ] `viban review` called (issue status is "review")
+- [ ] Worktree preserved at `.viban/worktrees/$ISSUE_ID`
 - [ ] Completion message includes PR URL
 
 ```
 Issue #{id} resolved → review
   Title: {title}
   PR: {pr_url}
+  Worktree: .viban/worktrees/{id}
 ```
 
 **If you don't have a PR URL or haven't called `viban review`, you are NOT done. Go back and do it.**

package/skills/parallel-assign/SKILL.md

@@ -190,19 +190,7 @@ REPO_ROOT=$(git rev-parse --show-toplevel)
 cd "$REPO_ROOT"
 ```
 
-### 3.1 Remove Worktrees (branches survive)
-
-Worktree removal does NOT delete the branch or its commits — they remain in the local repo.
-
-```bash
-for entry in "${ISSUES[@]}"; do
-    ID="${entry%%|*}"
-    WT_DIR="$REPO_ROOT/.viban/worktrees/$ID"
-    git worktree remove "$WT_DIR" --force
-done
-```
-
-### 3.2 Verify Local Branches
+### 3.1 Verify Local Branches
 
 Confirm each branch has commits from the agent:
 
@@ -215,7 +203,7 @@ done
 
 If a branch has no new commits (agent failed), skip it and report.
 
-### 3.3 Push Branches & Create PRs
+### 3.2 Push Branches & Create PRs
 
 For each branch with commits, push from the main repo and create a PR:
 
@@ -237,7 +225,7 @@ for entry in "${ISSUES[@]}"; do
 done
 ```
 
-### 3.4 Verify PRs Exist
+### 3.3 Verify PRs Exist
 
 ```bash
 for entry in "${ISSUES[@]}"; do
@@ -303,7 +291,7 @@ Worktrees cleaned up. All PRs ready for human review.
 
 > 1. **NEVER read or write `viban.json` directly** — always use `viban` CLI commands. Direct JSON access causes race conditions and data corruption.
 > 2. **NEVER exit with any issue still in `in_progress`.** For every assigned issue, ensure `viban review {ID}` has been called.
-> 3. **ALWAYS clean up worktrees** after PRs are created. Worktree dirs must not linger in `.viban/worktrees/`.
+> 3. **Do NOT remove worktrees** after PRs are created. Worktrees stay at `.viban/worktrees/{ID}` for the review flow (`/viban:approve` cleans up).
 
 ## CLI Reference
 

package/skills/reject/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: reject
+description: "Reject a reviewed issue — return to in_progress with feedback"
+---
+
+# /reject
+
+Reject a review-status issue and move it back to in_progress. The worktree stays intact so the agent can address feedback.
+
+> **CLI only** (no direct viban.json access)
+
+**Input**: `$ARGUMENTS` (required: issue ID, optional: feedback text)
+
+---
+
+## Output Rules
+
+- **Do NOT output any preamble.**
+- Start executing Step 1 immediately.
+
+---
+
+## Step 1: Validate
+
+```bash
+viban get $ID
+```
+
+Confirm the issue is in `review` status. If not, tell the user and exit.
+
+Parse `$ARGUMENTS`: first token is `$ID`, rest is `$FEEDBACK`.
+
+---
+
+## Step 2: Return to main branch
+
+```bash
+PREV_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
+[ -z "$PREV_BRANCH" ] && PREV_BRANCH="main"
+git checkout "$PREV_BRANCH"
+```
+
+---
+
+## Step 3: Move back to in_progress
+
+```bash
+viban move $ID in_progress
+```
+
+---
+
+## Step 4: Record feedback
+
+If `$FEEDBACK` is provided:
+
+```bash
+viban comment $ID "$FEEDBACK"
+```
+
+Also comment on PR if one exists:
+
+```bash
+BRANCH="issue-$ID"
+PR_NUM=$(gh pr list --head "$BRANCH" --json number --jq '.[0].number' 2>/dev/null)
+[ -n "$PR_NUM" ] && gh pr comment "$PR_NUM" --body "$FEEDBACK"
+```
+
+If no feedback provided, ask the user: "Any feedback for the developer?"
+- If provided → store as comment
+- If none → skip
+
+---
+
+## Step 5: Restore stash
+
+```bash
+STASH=$(git stash list | grep "viban-review: before reviewing #$ID" | head -1 | cut -d: -f1)
+[ -n "$STASH" ] && git stash pop "$STASH"
+```
+
+Report: "Issue #$ID rejected and moved to in_progress. Worktree is intact for the agent to continue."

package/skills/review/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: review
+description: "Checkout a review issue's branch for IDE review"
+---
+
+# /review
+
+Checkout a review-status issue's branch into the main working directory so the user can review changes in their IDE.
+
+> **CLI only** (no direct viban.json access)
+
+**Input**: `$ARGUMENTS` (optional: issue ID)
+
+---
+
+## Output Rules
+
+- **Do NOT output any preamble.** No "Your Task:", "I'll now...", "Let me...", or task summaries before starting work.
+- Start executing Step 1 immediately and silently.
+
+---
+
+## Step 1: Find Review Card
+
+If `$ARGUMENTS` contains an issue ID, use it. Otherwise find the first review card:
+
+```bash
+viban list --status review
+```
+
+If no review cards exist, tell the user and exit.
+
+Extract the issue ID. Store as `$ID`.
+
+```bash
+viban get $ID
+```
+
+Show the user a one-line summary: `#ID [PRIORITY] Title`.
+
+---
+
+## Step 2: Detect Review Mode
+
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel)
+BRANCH="issue-$ID"
+WT_DIR="$REPO_ROOT/.viban/worktrees/$ID"
+```
+
+Check in priority order — first match wins:
+
+### Mode W: Worktree exists
+
+```bash
+[ -d "$WT_DIR" ]
+```
+
+If worktree exists → **Worktree mode**.
+
+### Mode A: PR exists (no worktree)
+
+```bash
+gh pr list --head "$BRANCH" --json number,url --jq '.[0]' 2>/dev/null
+```
+
+If PR found → **PR mode**.
+
+### Mode B: Branch exists (no PR, no worktree)
+
+```bash
+git rev-parse --verify "$BRANCH" 2>/dev/null
+```
+
+If branch exists → **Branch mode**.
+
+### Mode C: No branch
+
+No branch → **Commit mode**.
+
+---
+
+## Step 3: Present for Review
+
+### Mode W (worktree exists)
+
+Show changes against main:
+
+```bash
+git -C "$WT_DIR" log main.."$BRANCH" --oneline
+git -C "$WT_DIR" diff main..."$BRANCH" --stat
+```
+
+Check if PR exists:
+
+```bash
+PR_INFO=$(gh pr list --head "$BRANCH" --json number,url --jq '.[0]' 2>/dev/null)
+```
+
+### Mode A / B (no worktree, branch exists)
+
+Stash if dirty:
+
+```bash
+git status --porcelain
+```
+
+If dirty, ask user: "You have uncommitted changes. Stash them to proceed?"
+- Yes → `git stash push -m "viban-review: before reviewing #$ID"`
+- No → exit
+
+Detached HEAD checkout:
+
+```bash
+PREV_BRANCH=$(git branch --show-current)
+git checkout --detach "$BRANCH"
+```
+
+Show changes:
+
+```bash
+git log "$PREV_BRANCH".."$BRANCH" --oneline
+git diff "$PREV_BRANCH"..."$BRANCH" --stat
+```
+
+### Mode C (no branch)
+
+Show recent commits:
+
+```bash
+git log --oneline -10
+```
+
+---
+
+## Step 4: Report and Exit
+
+Tell the user:
+
+**Mode W**: "Issue #$ID worktree is at `$WT_DIR`. Open it in your IDE to review. {PR #N link if PR exists.} Run `/viban:approve $ID` or `/viban:reject $ID` when ready."
+
+**Mode A**: "PR #N for issue #$ID is checked out. Review in your IDE. Run `/viban:approve $ID` or `/viban:reject $ID` when ready."
+
+**Mode B**: "Branch `issue-$ID` is checked out. Review in your IDE. Run `/viban:approve $ID` or `/viban:reject $ID` when ready."
+
+**Mode C**: "Issue #$ID was worked on main directly. Run `/viban:approve $ID` or `/viban:reject $ID` when ready."
+
+**Done.** Do not wait for user input. The skill exits here.

package/skills/setup/SKILL.md

@@ -415,7 +415,7 @@ If build/test fails: fix errors, return to Phase 3.
 
 - Issue tracking: {FROM Q2: "Yes" = synced with external tracker via `viban sync`, "No — auto-number" = auto-increment (viban default), "No — manual IDs" = ask for external ID via `--ext-id` flag}
 - Test evidence: include test output in PR body
-- Post-merge: auto-close issue (`viban done {id}`), delete branch
+- Post-merge: handled by `/viban:approve` (merges PR, runs `viban done {id}`, deletes branch)
 
 ---