claude-plugin-viban 1.2.2 → 1.3.1

package/.claude-plugin/plugin.json

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

package/README.md

@@ -24,14 +24,14 @@ The most effective way to use viban is with **multiple terminal sessions**:
 │    Session 1      │  │    Session 2      │  │    Session 3      │
 │                   │  │                   │  │                   │
 │  Product QA       │  │  Issue Work       │  │  viban TUI        │
-│  + /viban:task    │  │  + /viban:assign  │  │                   │
+│  + /viban:add     │  │  + /viban:assign  │  │                   │
 │                   │  │                   │  │  (always open)    │
 │  Find bugs,       │  │  Pick & resolve   │  │  Monitor board    │
 │  register issues  │  │  issues           │  │  in real-time     │
 └───────────────────┘  └───────────────────┘  └───────────────────┘
 ```
 
-- **Session 1**: QA your product, find issues, run `/viban:task` to register them
+- **Session 1**: QA your product, find issues, run `/viban:add` to register them
 - **Session 2**: Run `/viban:assign` to pick the next issue and resolve it
 - **Session 3**: Keep `viban` TUI open to monitor the board
 
@@ -39,7 +39,7 @@ This separation keeps your workflow clean and prevents context switching.
 
 ## Features
 
-- **3-Column Kanban Board**: `backlog` → `in_progress` → `review` → `done`
+- **4-Column Kanban Board**: `backlog` → `in_progress` → `review` → `done`
 - **Priority Levels**: P0 (critical) to P3 (low priority)
 - **Type Tags**: bug, feat, chore, refactor
 - **TUI Navigation**: Interactive terminal UI with gum
@@ -118,12 +118,17 @@ viban           # Launch TUI
 
 ```bash
 viban list                              # Display kanban board
-viban add "Title" "Description" P2 feat # Create new issue
+viban add "Title" ["Desc"] [P0-P3] [type] [files...]  # Create new issue
+viban attach <id> <file1> [file2...]    # Attach files to issue
+viban priority <id> <P0-P3>            # Set priority
 viban assign [session-id]               # Assign top backlog issue
 viban review [id]                       # Move issue to review
-viban done <id>                         # Mark issue as done
+viban done <id>                         # Complete & remove
+viban edit <id>                         # Edit issue in editor
 viban get <id>                          # Get issue details (JSON)
 viban sync                              # Sync with external tracker
+viban migrate                           # Migrate: extract type from title
+viban update                            # Update to latest version
 viban help                              # Show help message
 ```
 
@@ -133,12 +138,18 @@ viban help                              # Show help message
 # Add a high-priority bug
 viban add "Fix login error" "Users cannot login after password reset" P1 bug
 
+# Add an issue with file attachments
+viban add "Refactor auth" "Simplify login flow" P2 refactor src/auth.ts src/login.ts
+
 # List all issues
 viban list
 
 # Assign first backlog issue to current session
 viban assign
 
+# Change priority of issue #3
+viban priority 3 P1
+
 # Mark issue #5 as done
 viban done 5
 
@@ -148,48 +159,55 @@ viban get 3
 
 ### Claude Code Integration
 
-viban provides commands for automated issue management in Claude Code:
-
-#### `/viban:assign` - Auto-resolve next issue
+viban provides skills and commands for automated issue management in Claude Code:
 
-Automatically picks the highest priority backlog issue and executes the full resolution workflow:
-
-1. Fetches top backlog issue
-2. Assigns to current session
-3. Analyzes and implements the fix
-4. Marks as review/done upon completion
-
-**Use cases:**
-- Autonomous issue resolution
-- Parallel agent workflows
-- Pre-prioritized backlog processing
-
-#### `/viban:task` - Create structured issue
+#### `/viban:add` - Register structured issue
 
 Analyzes a problem and creates a properly structured viban issue:
 
-1. Prompts for problem description
-2. Analyzes symptoms, root cause, expected behavior
-3. Creates issue with proper title, description, priority, type
+1. Clarifies the problem if vague
+2. Infers priority and type from description
+3. Registers with proper title, description, priority, type
+4. Optionally enters plan mode to design a solution
 
 **Use cases:**
 - Bug reporting
 - Feature requests
 - Converting free-form descriptions to structured issues
 
-#### `/viban:sync` - Sync with external tracker
+#### `/viban:assign` - Assign next backlog issue
+
+Picks the highest priority backlog issue and assigns it to the current session:
+
+1. Assigns top backlog issue
+2. Evaluates description clarity
+3. If unclear, interviews user and enriches the issue description
+
+This command is **assignment only** - it does not start implementation. Use your project's workflow (`.viban/workflow.md`) to define what happens next.
+
+#### `/viban:parallel-assign` - Parallel resolution with worktrees
 
-Two-way sync between your viban board and an external issue tracker (currently GitHub Issues):
+Resolves multiple backlog issues simultaneously using isolated git worktrees:
 
-1. Checks sync configuration (or initializes on first run)
-2. Shows a dry-run preview of changes
-3. Asks for confirmation before syncing
-4. Reports sync results
+1. Assigns N issues (default: 3, max: 5) and creates worktrees
+2. Spawns one opus agent per issue in its own worktree
+3. Each agent analyzes, implements, commits, and creates a PR
+4. Coordinator collects results, runs tests, and cleans up
 
 **Use cases:**
-- Importing GitHub Issues into your local board
-- Keeping remote issues in sync with local status changes
-- Team collaboration where some members use GitHub and others use viban
+- Batch processing a backlog
+- Parallel agent workflows with zero interference
+- Rapid issue throughput
+
+#### `/viban:setup` - Install & configure
+
+Installs all dependencies and optionally configures a project workflow:
+
+1. Detects OS and installs missing dependencies (zsh, gum, jq)
+2. Installs/updates viban CLI via npm
+3. Auto-detects project conventions (build/test, commit style, branch naming)
+4. Interviews for workflow preferences (pipeline depth, issue numbering)
+5. Generates `.viban/workflow.md` for `/viban:assign` to follow
 
 ## External Tracker Sync
 
@@ -208,7 +226,7 @@ viban sync --dry-run
 viban sync
 ```
 
-> If using Claude Code, run `/viban:sync` for a guided experience with dry-run preview and confirmation.
+> **Tip:** Use `viban sync --dry-run` first to preview changes before syncing.
 
 ### How It Works
 
@@ -290,8 +308,6 @@ backlog → in_progress → review → done
 | **feat** | New feature or enhancement |
 | **refactor** | Code restructuring |
 | **chore** | Maintenance tasks |
-| **docs** | Documentation updates |
-| **test** | Test additions/fixes |
 
 ## Data Structure
 
@@ -332,34 +348,47 @@ This prevents duplicate work and enables parallel agent workflows.
 ```
 claude-plugin-viban/
 ├── .claude-plugin/
-│   └── plugin.json          # Plugin metadata
+│   └── plugin.json              # Plugin metadata
 ├── .github/
 │   └── workflows/
-│       ├── ci.yml           # CI testing
-│       └── release.yml      # NPM publishing
+│       ├── ci.yml               # CI testing
+│       └── release.yml          # NPM publishing
 ├── bin/
-│   └── viban                # Main TUI/CLI script
-├── docs/
-│   └── CLAUDE.md            # Claude Code integration guide
+│   └── viban                    # Main TUI/CLI script
 ├── commands/
-│   └── sync.md              # /viban:sync command
+│   ├── add.md                   # /viban:add command
+│   ├── assign.md                # /viban:assign command
+│   ├── parallel-assign.md       # /viban:parallel-assign command
+│   └── setup.md                 # /viban:setup command
+├── docs/
+│   ├── CLAUDE.md                # Claude Code integration guide
+│   └── release.md               # Release workflow
 ├── scripts/
-│   ├── check-deps.sh        # Dependency checker
-│   ├── sync.sh              # Core sync engine (provider-agnostic)
+│   ├── check-deps.sh            # Dependency checker
+│   ├── generate-release-notes.sh # Release notes generator
+│   ├── sync.sh                  # Core sync engine (provider-agnostic)
+│   ├── sync_create.sh           # Sync initialization
 │   ├── providers/
-│   │   └── github.sh        # GitHub Issues provider
-│   └── tui_coprocess.py     # Persistent Python coprocess for TUI rendering
+│   │   └── github.sh            # GitHub Issues provider
+│   └── tui_coprocess.py         # Persistent Python coprocess for TUI rendering
 ├── skills/
-│   ├── assign/SKILL.md      # /viban:assign skill
-│   ├── setup/SKILL.md       # /viban:setup skill
-│   ├── sync/SKILL.md        # /viban:sync skill
-│   └── task/SKILL.md        # /viban:task skill
+│   ├── add/SKILL.md             # /viban:add skill
+│   ├── assign/SKILL.md          # /viban:assign skill
+│   ├── parallel-assign/SKILL.md # /viban:parallel-assign skill
+│   └── setup/SKILL.md           # /viban:setup skill
 ├── tests/
-│   ├── run_all.zsh          # Test runner
-│   └── test_sync.zsh        # Sync engine tests
-├── LICENSE                  # MIT License
-├── package.json             # NPM package config
-└── README.md                # This file
+│   ├── run_all.zsh              # Test runner
+│   ├── test_cmd_add.zsh         # Add command tests
+│   ├── test_coprocess.zsh       # Python coprocess tests
+│   ├── test_install.zsh         # Installation tests
+│   ├── test_layout.zsh          # TUI layout tests
+│   ├── test_pad_width.zsh       # Unicode width tests
+│   ├── test_sort_order.zsh      # Sort order tests
+│   ├── test_sync.zsh            # Sync engine tests
+│   └── test_sync_auto.zsh       # Auto-sync tests
+├── LICENSE                      # MIT License
+├── package.json                 # NPM package config
+└── README.md                    # This file
 ```
 
 ## Development
@@ -370,29 +399,16 @@ claude-plugin-viban/
 # Install dependencies
 brew install gum jq
 
-# Make executable
-chmod +x bin/viban scripts/check-deps.sh
-
-# Run tests
-./bin/viban help
-
-# Test in a git repo
-cd /path/to/git/repo
-viban add "Test issue" "Test description" P2 feat
-viban list
+# Run the full test suite (8 suites, 39 tests)
+zsh tests/run_all.zsh
 ```
 
 ### Publishing
 
-```bash
-# Update version in package.json
-npm version patch  # or minor, major
+See [docs/release.md](docs/release.md) for the full release workflow.
 
-# Create and push tag
-git tag v1.0.1
-git push origin v1.0.1
-
-# GitHub Actions will automatically publish to npm
+```bash
+# GitHub Actions will automatically publish to npm on tag push
 ```
 
 ## Contributing

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/add.md

@@ -64,12 +64,20 @@ Issue #{id} registered
 
 ## Step 6: Suggest Plan Mode
 
-**Skip** for trivial issues (typo, one-liner config, simple copy edit).
-**Recommend** for everything else. Use AskUserQuestion:
+**Skip** unless the issue clearly needs upfront design. Most issues don't.
 
-- header: "Next step", question: "Want to start planning the solution now?"
+Only suggest plan mode when:
+- The issue spans multiple subsystems or requires architectural decisions
+- The description is too vague to act on without investigation
+- P0 issues where a wrong fix could make things worse
+
+**Do NOT suggest** for: single-file fixes, straightforward bugs, feature additions with clear scope, chores, refactors with obvious targets.
+
+When suggesting, use AskUserQuestion:
+
+- header: "Next step", question: "This looks complex — want to plan before working on it?"
 - options:
-  - "Plan now (Recommended)" — Enter plan mode to analyze and design a solution
+  - "Plan now" — Enter plan mode to analyze and design a solution
   - "Later" — Just register, work on it later
 
 **"Plan now"**: `EnterPlanMode` → after approval, save to `.viban/plans/{issue-id}.md`:
@@ -89,11 +97,14 @@ Report: `Plan saved to .viban/plans/{issue-id}.md — /viban:assign will auto-lo
 
 **"Later"**: end skill.
 
-> **Bias towards planning.** When in doubt, suggest plan mode.
+> **Bias towards skipping.** When in doubt, just register and finish.
 
 ## Rules
 
+- **NEVER edit, create, or modify any source code files** — this skill registers issues only
+- **NEVER start implementation** — even after plan mode, just save the plan and stop
 - No codebase exploration — assignee does that in `/viban:assign`
-- No solution proposals — symptoms only
+- No solution proposals in the issue — symptoms only
 - Check duplicates first: `viban list`
 - P0 is system-down only
+- After Step 6 completes (plan saved or skipped), the skill is **done**. Do not continue.

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.1",
   "description": "Terminal Kanban TUI for AI-human collaborative issue tracking",
   "main": "bin/viban",
   "bin": {

package/skills/add/SKILL.md

@@ -65,12 +65,20 @@ Issue #{id} registered
 
 ## Step 6: Suggest Plan Mode
 
-**Skip** for trivial issues (typo, one-liner config, simple copy edit).
-**Recommend** for everything else. Use AskUserQuestion:
+**Skip** unless the issue clearly needs upfront design. Most issues don't.
 
-- header: "Next step", question: "Want to start planning the solution now?"
+Only suggest plan mode when:
+- The issue spans multiple subsystems or requires architectural decisions
+- The description is too vague to act on without investigation
+- P0 issues where a wrong fix could make things worse
+
+**Do NOT suggest** for: single-file fixes, straightforward bugs, feature additions with clear scope, chores, refactors with obvious targets.
+
+When suggesting, use AskUserQuestion:
+
+- header: "Next step", question: "This looks complex — want to plan before working on it?"
 - options:
-  - "Plan now (Recommended)" — Enter plan mode to analyze and design a solution
+  - "Plan now" — Enter plan mode to analyze and design a solution
   - "Later" — Just register, work on it later
 
 **"Plan now"**: `EnterPlanMode` → after approval, save to `.viban/plans/{issue-id}.md`:
@@ -90,11 +98,14 @@ Report: `Plan saved to .viban/plans/{issue-id}.md — /viban:assign will auto-lo
 
 **"Later"**: end skill.
 
-> **Bias towards planning.** When in doubt, suggest plan mode.
+> **Bias towards skipping.** When in doubt, just register and finish.
 
 ## Rules
 
+- **NEVER edit, create, or modify any source code files** — this skill registers issues only
+- **NEVER start implementation** — even after plan mode, just save the plan and stop
 - No codebase exploration — assignee does that in `/viban:assign`
-- No solution proposals — symptoms only
+- No solution proposals in the issue — symptoms only
 - Check duplicates first: `viban list`
 - P0 is system-down only
+- After Step 6 completes (plan saved or skipped), the skill is **done**. Do not continue.

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)