claude-plugin-viban 1.2.2 → 1.3.0

package/.claude-plugin/plugin.json

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

package/bin/viban

@@ -906,7 +906,7 @@ draw_board() {
 
 draw_footer() {
     printf '\033[K\n'
-    print_center "←→ Column  │  ↑↓ Card  │  Shift+↑↓ Reorder  │  Shift+←→ Move  │  Enter Edit  │  ⌫ Del  │  A Add  │  Q Quit" "${A_DIM}"
+    print_center "←→ Column  │  ↑↓ Card  │  Shift+↑↓ Reorder  │  Shift+←→ Move  │  Enter Edit/PR  │  ⌫ Del  │  A Add  │  Q Quit" "${A_DIM}"
 }
 
 read_key() {
@@ -1173,11 +1173,24 @@ level1_columns() {
                 if (( cnt > 0 )); then
                     local id=$(get_issue_id_at_index "$st" "$card" "$json_data")
                     [[ -n "$id" ]] && {
-                        printf '\033[?25h'
-                        stty echo 2>/dev/null
-                        edit_issue "$id"
-                        stty -echo 2>/dev/null
-                        printf '\033[?25l\033[2J\033[H'
+                        if [[ "$st" == "review" ]]; then
+                            # Open associated PR in browser
+                            local _branch="issue-${id}"
+                            local _ext_id=$(get_ext_id "$id")
+                            if [[ -n "$_ext_id" && "$_ext_id" != "null" ]]; then
+                                local _num="${_ext_id##*:}"
+                                gh pr view "$_num" --web 2>/dev/null || \
+                                    gh pr list --head "$_branch" --web 2>/dev/null
+                            else
+                                gh pr list --head "$_branch" --web 2>/dev/null
+                            fi
+                        else
+                            printf '\033[?25h'
+                            stty echo 2>/dev/null
+                            edit_issue "$id"
+                            stty -echo 2>/dev/null
+                            printf '\033[?25l\033[2J\033[H'
+                        fi
                     }
                 fi
                 ;;

package/commands/assign.md

@@ -1,217 +1,14 @@
 ---
-description: "Assign and resolve first backlog issue from viban board through to PR completion"
+description: "Assign first backlog issue — clarify if unclear, then finish"
 ---
 
-# /assign
+Run `/viban:assign` to pick up the next backlog issue.
 
-First backlog issue → Resolve → PR completion
+Usage: `/viban:assign`
 
-> **CLI only** (no direct viban.json access) | **No worktree** (branch in main repo)
+What it does:
+1. Assigns the first backlog issue (by priority) to the current session
+2. If the issue description is unclear or lacks context, interviews you to gather missing information and updates the issue
+3. That's it — no implementation, no branch creation
 
----
-
-## Phase 0: SETUP
-
-### 0.1 Read Workflow (CRITICAL)
-
-Check in priority order — first match wins, follow it exactly:
-
-1. `.viban/workflow.md` → `[ -f ".viban/workflow.md" ] && cat ".viban/workflow.md"`
-2. CLAUDE.md (legacy, only if no workflow.md):
-```bash
-for path in "./CLAUDE.md" "./.claude/CLAUDE.md" "../CLAUDE.md"; do
-    [ -f "$path" ] && cat "$path"
-done
-```
-Look for `Issue Resolution Workflow` or `Workflow` section.
-3. Default workflow (Phase 1 below)
-
-### 0.2 Git Setup & Assign
-
-```bash
-# Check uncommitted changes → AskUserQuestion if dirty
-[ -n "$(git status --porcelain)" ] && echo "Warning: Uncommitted changes"
-
-git checkout main && git fetch origin main && git reset --hard origin/main
-
-ISSUE_ID=$(viban assign 2>&1 | tail -1)
-[[ -z "$ISSUE_ID" || "$ISSUE_ID" == "No backlog" ]] && echo "No issues in backlog" && exit 0
-```
-
-### 0.3 Detect Sync & Create Branch
-
-```bash
-ISSUE_JSON=$(viban get $ISSUE_ID)
-EXT_ID=$(echo "$ISSUE_JSON" | jq -r '.external_id // ""')
-SYNC_ACTIVE=false; EXTERNAL_NUM=""
-
-if [ -n "$EXT_ID" ] && [ "$EXT_ID" != "null" ]; then
-    SYNC_ACTIVE=true
-    EXTERNAL_NUM="${EXT_ID##*:}"  # "github:42" -> "42"
-    TITLE=$(echo "$ISSUE_JSON" | jq -r '.title' | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | head -c 40)
-    git checkout -b "issue-${EXTERNAL_NUM}-${TITLE}"
-else
-    git checkout -b issue-$ISSUE_ID
-fi
-```
-
-### 0.4 Load Plan (if available)
-
-```bash
-[ -f ".viban/plans/${ISSUE_ID}.md" ] && cat ".viban/plans/${ISSUE_ID}.md"
-```
-
-If plan exists: use as primary guide for Phase 1, skip redundant analysis, but verify plan is still current.
-
----
-
-## Phase 1: ANALYZE & IMPLEMENT
-
-```bash
-viban get $ISSUE_ID
-```
-
-**With project workflow**: follow its exact steps.
-**Default** (no workflow): Understand → Locate → Analyze root cause → Implement minimal changes.
-
----
-
-## Phase 2: VERIFY
-
-Manual verification — do NOT run build/test here (Phase 3).
-
-| Type | Tool |
-|------|------|
-| Web UI | Playwright MCP (`browser_navigate`, `browser_snapshot`, `browser_click`) |
-| API | WebFetch |
-| CLI | Bash |
-| Visual | Read (screenshot files) |
-| Browser | Chrome DevTools MCP |
-
-Steps: identify what proves the fix → execute → confirm behavior → document evidence.
-
-Examples:
-- Web feature: navigate to page, take snapshot, verify element exists
-- API fix: fetch endpoint, check response status and body
-- CLI change: run command, verify output format
-- UI bug: navigate, interact, confirm no error
-
-If verification fails: return to Phase 1.
-
----
-
-## Phase 3: SHIP
-
-### 3.1 Build & Test
-
-Run project's build/test commands. If fail: fix → return to Phase 2.
-
-### 3.2 Rebase
-
-```bash
-git fetch origin main && git rebase origin/main
-# On conflict: resolve -> git add -> git rebase --continue
-```
-
-### 3.3 Commit & Push
-
-```bash
-BRANCH=$(git branch --show-current)
-git add -A
-
-# Sync mode: "Closes #NUM" | Default: "Resolves: viban-ID"
-if [ "$SYNC_ACTIVE" = true ]; then
-    git commit -m "fix: issue title summary
-
-- Root cause: ...
-- Solution: ...
-
-Closes #$EXTERNAL_NUM"
-else
-    git commit -m "fix: issue title summary
-
-- Root cause: ...
-- Solution: ...
-
-Resolves: #$ISSUE_ID"
-fi
-
-git push -u origin "$BRANCH"
-```
-
-### 3.4 Create PR
-
-```bash
-EXISTING_PR=$(gh pr list --head "$BRANCH" --json number -q '.[0].number')
-
-if [ -z "$EXISTING_PR" ]; then
-    if [ "$SYNC_ACTIVE" = true ]; then
-        gh pr create --title "fix: title" \
-            --body "## Changes
-- ...
-
-Closes #$EXTERNAL_NUM
-
-## Verification
-- [ ] Manual verification completed
-- [ ] Build passing
-- [ ] Tests passing (if applicable)" --base main
-    else
-        gh pr create --title "fix: title" \
-            --body "## Changes
-- ...
-
-## Verification
-- [ ] Manual verification completed
-- [ ] Build passing
-- [ ] Tests passing (if applicable)" --base main
-    fi
-fi
-```
-
-### 3.5 Move to Review
-
-```bash
-viban review $ISSUE_ID
-```
-
----
-
-## Phase 4: HANDOFF
-
-```
-Issue #$ISSUE_ID → review | PR: gh pr view --web
-Verification: manual + build + workflow followed
-After approval: delete issue from viban TUI
-```
-
----
-
-## Checklist
-
-```
-[ ] Read .viban/workflow.md (or CLAUDE.md fallback) for project workflow
-[ ] Working on issue-$ISSUE_ID branch
-[ ] Implementation complete
-[ ] Manual verification passed (using appropriate tools)
-[ ] Build & tests passing
-[ ] Rebase complete
-[ ] PR created
-[ ] viban review executed
-```
-
----
-
-## CRITICAL: Status Transition Rule
-
-> **NEVER exit with issue still in `in_progress`.** Always run `viban review $ISSUE_ID` before exiting — whether completed or stopped early.
-
-## CLI Reference
-
-| Command | Description |
-|---------|-------------|
-| `viban` | Open TUI |
-| `viban list` | Print board |
-| `viban assign [session]` | Assign issue |
-| `viban get <id>` | View issue |
-| `viban review <id>` | Move to review |
+This command is for **assignment and clarification only**. Use other tools to start working on the assigned issue.

package/package.json

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

package/skills/assign/SKILL.md

@@ -1,21 +1,19 @@
 ---
 name: assign
-description: "Assign and resolve first backlog issue from viban board through to PR completion"
+description: "Assign first backlog issue — clarify if unclear, then finish"
 ---
 
 # /assign
 
-First backlog issue → Resolve → PR completion
+Assign the first backlog issue. If the description is unclear or lacks context, interview the user and enrich the issue. **Do NOT start implementation.**
 
-> **CLI only** (no direct viban.json access) | **No worktree** (branch in main repo)
+> **CLI only** (no direct viban.json access)
 
 ---
 
-## Phase 0: SETUP
+## Step 0: Read Workflow (CRITICAL)
 
-### 0.1 Read Workflow (CRITICAL)
-
-Check in priority order — first match wins, follow it exactly:
+Check in priority order — first match wins:
 
 1. `.viban/workflow.md` → `[ -f ".viban/workflow.md" ] && cat ".viban/workflow.md"`
 2. CLAUDE.md (legacy, only if no workflow.md):
@@ -25,193 +23,91 @@ for path in "./CLAUDE.md" "./.claude/CLAUDE.md" "../CLAUDE.md"; do
 done
 ```
 Look for `Issue Resolution Workflow` or `Workflow` section.
-3. Default workflow (Phase 1 below)
 
-### 0.2 Git Setup & Assign
+If a workflow exists, follow its conventions for issue handling.
 
-```bash
-# Check uncommitted changes → AskUserQuestion if dirty
-[ -n "$(git status --porcelain)" ] && echo "Warning: Uncommitted changes"
+---
 
-git checkout main && git fetch origin main && git reset --hard origin/main
+## Step 1: Assign
 
+```bash
 ISSUE_ID=$(viban assign 2>&1 | tail -1)
 [[ -z "$ISSUE_ID" || "$ISSUE_ID" == "No backlog" ]] && echo "No issues in backlog" && exit 0
 ```
 
-### 0.3 Detect Sync & Create Branch
+If backlog is empty: notify user and exit.
 
-```bash
-ISSUE_JSON=$(viban get $ISSUE_ID)
-EXT_ID=$(echo "$ISSUE_JSON" | jq -r '.external_id // ""')
-SYNC_ACTIVE=false; EXTERNAL_NUM=""
-
-if [ -n "$EXT_ID" ] && [ "$EXT_ID" != "null" ]; then
-    SYNC_ACTIVE=true
-    EXTERNAL_NUM="${EXT_ID##*:}"  # "github:42" -> "42"
-    git checkout -b "issue-${EXTERNAL_NUM}"
-else
-    git checkout -b issue-$ISSUE_ID
-fi
-```
-
-### 0.4 Load Plan (if available)
-
-```bash
-[ -f ".viban/plans/${ISSUE_ID}.md" ] && cat ".viban/plans/${ISSUE_ID}.md"
-```
-
-If plan exists: use as primary guide for Phase 1, skip redundant analysis, but verify plan is still current.
-
----
-
-## Phase 1: ANALYZE & IMPLEMENT
+## Step 2: Read Issue
 
 ```bash
 viban get $ISSUE_ID
 ```
 
-**With project workflow**: follow its exact steps.
-**Default** (no workflow): Understand → Locate → Analyze root cause → Implement minimal changes.
-
----
-
-## Phase 2: VERIFY
-
-Manual verification — do NOT run build/test here (Phase 3).
-
-| Type | Tool |
-|------|------|
-| Web UI | Playwright MCP (`browser_navigate`, `browser_snapshot`, `browser_click`) |
-| API | WebFetch |
-| CLI | Bash |
-| Visual | Read (screenshot files) |
-| Browser | Chrome DevTools MCP |
+Display the issue title, description, priority, and type to the user.
 
-Steps: identify what proves the fix → execute → confirm behavior → document evidence.
+## Step 3: Evaluate Clarity
 
-Examples:
-- Web feature: navigate to page, take snapshot, verify element exists
-- API fix: fetch endpoint, check response status and body
-- CLI change: run command, verify output format
-- UI bug: navigate, interact, confirm no error
+Assess whether the issue description provides enough context for someone to start working on it:
 
-If verification fails: return to Phase 1.
-
----
+- **Clear**: the symptom, affected area, and expected behavior are all understandable
+- **Unclear**: vague description, missing context, ambiguous scope, or multiple possible interpretations
 
-## Phase 3: SHIP
+### If Clear
 
-### 3.1 Build & Test
+Report the assignment and finish:
 
-Run project's build/test commands. If fail: fix → return to Phase 2.
-
-### 3.2 Rebase
-
-```bash
-git fetch origin main && git rebase origin/main
-# On conflict: resolve -> git add -> git rebase --continue
 ```
+Issue #{id} assigned
+  Title: {title}
+  Priority: {priority} | Type: {type}
+  Status: in_progress
 
-### 3.3 Commit & Push
-
-```bash
-BRANCH=$(git branch --show-current)
-git add -A
-
-# Sync mode: "Closes #NUM" | Default: "Resolves: viban-ID"
-if [ "$SYNC_ACTIVE" = true ]; then
-    git commit -m "fix: issue title summary
-
-- Root cause: ...
-- Solution: ...
-
-Closes #$EXTERNAL_NUM"
-else
-    git commit -m "fix: issue title summary
-
-- Root cause: ...
-- Solution: ...
-
-Resolves: #$ISSUE_ID"
-fi
-
-git push -u origin "$BRANCH"
+Ready for work.
 ```
 
-### 3.4 Create PR
+### If Unclear
 
-```bash
-EXISTING_PR=$(gh pr list --head "$BRANCH" --json number -q '.[0].number')
-
-if [ -z "$EXISTING_PR" ]; then
-    if [ "$SYNC_ACTIVE" = true ]; then
-        gh pr create --title "fix: title" \
-            --body "## Changes
-- ...
-
-Closes #$EXTERNAL_NUM
-
-## Verification
-- [ ] Manual verification completed
-- [ ] Build passing
-- [ ] Tests passing (if applicable)" --base main
-    else
-        gh pr create --title "fix: title" \
-            --body "## Changes
-- ...
-
-## Verification
-- [ ] Manual verification completed
-- [ ] Build passing
-- [ ] Tests passing (if applicable)" --base main
-    fi
-fi
-```
+Interview the user with AskUserQuestion to gather missing context. Ask about:
+- What specifically is the problem? (symptom)
+- Where does it happen? (location/trigger)
+- What is the expected behavior?
+- Any additional constraints or context?
 
-### 3.5 Move to Review
+After gathering answers, update the issue description:
 
 ```bash
-viban review $ISSUE_ID
-```
-
----
+cat > /tmp/viban-desc-update.md <<'VIBAN_EOF'
+{original description}
 
-## Phase 4: HANDOFF
+## Clarification
+{gathered context from interview}
+VIBAN_EOF
 
-```
-Issue #$ISSUE_ID → review | PR: gh pr view --web
-Verification: manual + build + workflow followed
-After approval: delete issue from viban TUI
+# Re-add the issue with enriched description (edit via TUI or recreate)
 ```
 
----
-
-## Checklist
+Then report:
 
 ```
-[ ] Read .viban/workflow.md (or CLAUDE.md fallback) for project workflow
-[ ] Working on issue-$ISSUE_ID branch
-[ ] Implementation complete
-[ ] Manual verification passed (using appropriate tools)
-[ ] Build & tests passing
-[ ] Rebase complete
-[ ] PR created
-[ ] viban review executed
+Issue #{id} assigned and clarified
+  Title: {title}
+  Priority: {priority} | Type: {type}
+  Status: in_progress
+
+Clarification added to issue description.
 ```
 
 ---
 
-## CRITICAL: Status Transition Rule
+## CRITICAL
 
-> **NEVER exit with issue still in `in_progress`.** Always run `viban review $ISSUE_ID` before exiting — whether completed or stopped early.
+> - This command **assigns only**. Do NOT create branches, write code, or start implementation.
+> - Do NOT run `viban review` — the issue stays in `in_progress` for the next work session.
+> - If the issue is clear, just report and finish immediately.
 
 ## CLI Reference
 
 | Command | Description |
 |---------|-------------|
-| `viban` | Open TUI |
-| `viban list` | Print board |
 | `viban assign [session]` | Assign issue |
 | `viban get <id>` | View issue |
-| `viban review <id>` | Move to review |

package/skills/parallel-assign/SKILL.md

@@ -104,8 +104,9 @@ You are resolving viban issue #{ID} in an isolated git worktree.
 - Main repo: {REPO_ROOT}
 - ALL file operations must happen inside the worktree path
 
-## Workflow
-{paste workflow.md content}
+## Workflow (Analyze + Implement + Verify only)
+{paste workflow.md Phase 1 (Analyze), Phase 2 (Implement), and Phase 3 (Verify) sections ONLY}
+{DO NOT include: Pipeline summary, GitHub Sync, Phase 4 (Build and Test), Phase 5 (Ship), Issue Management, Post-merge, or Additional Rules}
 
 ## Issue Details
 {paste viban get output}
@@ -152,6 +153,7 @@ You are one of {N} parallel agents working in isolated git worktrees.
 
 CRITICAL:
 - Always run `viban review {ID}` before finishing, even on errors.
+- Do NOT run `viban done` — the coordinator handles post-merge cleanup.
 - Do NOT run the full test suite — the coordinator handles that.
 - Do NOT remove the worktree — the coordinator handles cleanup.
 ```

package/commands/sync.md

@@ -1,99 +0,0 @@
----
-description: "Sync viban board with external issue tracker (GitHub, Jira, etc.)"
----
-
-# /sync - External Issue Tracker Sync
-
-Sync the viban board with an external issue tracker. Currently supports GitHub Issues via `gh` CLI.
-
-> **Principle**: Show what will happen before doing it. Never sync without user confirmation.
-
-## Input
-
-**User Input**: `$ARGUMENTS`
-
-## Step 1: Check Sync Configuration
-
-```bash
-# Check if sync is already configured
-if [ -f ".viban/sync.json" ]; then
-    echo "Sync configured"
-    viban sync --status
-else
-    echo "Sync not configured"
-fi
-```
-
-- If **not configured**, proceed to Step 2
-- If **configured**, skip to Step 3
-
-## Step 2: Initialize Sync
-
-```bash
-viban sync --init
-```
-
-This will:
-- Auto-detect the provider from git remote (defaults to GitHub)
-- Check that `gh` CLI is installed and authenticated
-- Create required labels on the remote repo
-- Initialize `sync.json` metadata
-
-If initialization fails, report the error and suggest fixes (install `gh`, run `gh auth login`, etc.).
-
-## Step 3: Preview Changes (Dry Run)
-
-```bash
-viban sync --dry-run
-```
-
-Show the user what will happen:
-- `<-` Issues to pull from remote
-- `->` Cards to push to remote
-- `==` Unchanged items
-- `!!` Conflicts (and resolution strategy)
-
-## Step 4: Confirm and Sync
-
-Ask the user for confirmation using AskUserQuestion:
-
-- header: "Sync"
-- question: "Apply these sync changes?"
-- options:
-  - "Yes, sync now"
-  - "Sync and push new local cards too (--push-new)"
-  - "Pull only (remote -> local)"
-  - "Cancel"
-- multiSelect: false
-
-Based on the answer:
-
-```bash
-# Yes, sync now
-viban sync
-
-# With push-new
-viban sync --push-new
-
-# Pull only
-viban sync --pull-only
-```
-
-## Step 5: Report Results
-
-Show the sync summary:
-```
-Sync complete:
-  Pulled: N new/updated cards from remote
-  Pushed: N cards to remote
-  Conflicts: N (resolved by: remote wins)
-  Unchanged: N
-```
-
-## Notes
-
-- **First sync imports all open issues** as backlog cards with `github:N` external IDs
-- **Conflicts**: when both sides changed, remote wins by default (with warning)
-- **Closed issues**: remote closed issues move viban card to `review` status
-- **Done cards**: `viban done` then sync closes the remote issue
-- **New local cards** are NOT pushed unless `--push-new` is specified (local-first default)

package/skills/sync/SKILL.md

@@ -1,100 +0,0 @@
----
-name: sync
-description: "Sync viban board with external issue tracker (GitHub, Jira, etc.)"
----
-
-# /sync - External Issue Tracker Sync
-
-Sync the viban board with an external issue tracker. Currently supports GitHub Issues via `gh` CLI.
-
-> **Principle**: Show what will happen before doing it. Never sync without user confirmation.
-
-## Input
-
-**User Input**: `$ARGUMENTS`
-
-## Step 1: Check Sync Configuration
-
-```bash
-# Check if sync is already configured
-if [ -f ".viban/sync.json" ]; then
-    echo "Sync configured"
-    viban sync --status
-else
-    echo "Sync not configured"
-fi
-```
-
-- If **not configured**, proceed to Step 2
-- If **configured**, skip to Step 3
-
-## Step 2: Initialize Sync
-
-```bash
-viban sync --init
-```
-
-This will:
-- Auto-detect the provider from git remote (defaults to GitHub)
-- Check that `gh` CLI is installed and authenticated
-- Create required labels on the remote repo
-- Initialize `sync.json` metadata
-
-If initialization fails, report the error and suggest fixes (install `gh`, run `gh auth login`, etc.).
-
-## Step 3: Preview Changes (Dry Run)
-
-```bash
-viban sync --dry-run
-```
-
-Show the user what will happen:
-- `<-` Issues to pull from remote
-- `->` Cards to push to remote
-- `==` Unchanged items
-- `!!` Conflicts (and resolution strategy)
-
-## Step 4: Confirm and Sync
-
-Ask the user for confirmation using AskUserQuestion:
-
-- header: "Sync"
-- question: "Apply these sync changes?"
-- options:
-  - "Yes, sync now"
-  - "Sync and push new local cards too (--push-new)"
-  - "Pull only (remote -> local)"
-  - "Cancel"
-- multiSelect: false
-
-Based on the answer:
-
-```bash
-# Yes, sync now
-viban sync
-
-# With push-new
-viban sync --push-new
-
-# Pull only
-viban sync --pull-only
-```
-
-## Step 5: Report Results
-
-Show the sync summary:
-```
-Sync complete:
-  Pulled: N new/updated cards from remote
-  Pushed: N cards to remote
-  Conflicts: N (resolved by: remote wins)
-  Unchanged: N
-```
-
-## Notes
-
-- **First sync imports all open issues** as backlog cards with `github:N` external IDs
-- **Conflicts**: when both sides changed, remote wins by default (with warning)
-- **Closed issues**: remote closed issues move viban card to `review` status
-- **Done cards**: `viban done` then sync closes the remote issue
-- **New local cards** are NOT pushed unless `--push-new` is specified (local-first default)