claude-plugin-viban 1.1.1 → 1.2.0

package/.claude-plugin/plugin.json

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

package/README.md

@@ -53,6 +53,7 @@ This separation keeps your workflow clean and prevents context switching.
 - python3 (macOS/Linux built-in)
 - [gum](https://github.com/charmbracelet/gum)
 - [jq](https://jqlang.github.io/jq/)
+- [gh](https://cli.github.com/) (optional, for GitHub Issues sync)
 
 > **Tip:** If using Claude Code, run `/viban:setup` to install all dependencies automatically.
 
@@ -122,6 +123,7 @@ viban assign [session-id]               # Assign top backlog issue
 viban review [id]                       # Move issue to review
 viban done <id>                         # Mark issue as done
 viban get <id>                          # Get issue details (JSON)
+viban sync                              # Sync with external tracker
 viban help                              # Show help message
 ```
 
@@ -175,6 +177,60 @@ Analyzes a problem and creates a properly structured viban issue:
 - Feature requests
 - Converting free-form descriptions to structured issues
 
+#### `/viban:sync` - Sync with external tracker
+
+Two-way sync between your viban board and an external issue tracker (currently GitHub Issues):
+
+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
+
+**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
+
+## External Tracker Sync
+
+viban can sync two-way with external issue trackers. Currently supported: **GitHub Issues**.
+
+### Quick Start
+
+```bash
+# First time: initialize sync (auto-detects provider from git remote)
+viban sync --init
+
+# Preview what will change
+viban sync --dry-run
+
+# Run sync
+viban sync
+```
+
+> If using Claude Code, run `/viban:sync` for a guided experience with dry-run preview and confirmation.
+
+### How It Works
+
+- **First sync** imports all open remote issues as backlog cards with external IDs (e.g. `github:42`)
+- **Subsequent syncs** pull remote changes and push local status updates
+- **New local cards** are NOT pushed unless `--push-new` is specified (local-first default)
+- **Conflicts** (both sides changed) resolve to remote-wins by default
+
+### Status-to-Label Mapping
+
+| viban status | GitHub label |
+|-------------|-------------|
+| `backlog` | *(no label)* |
+| `in_progress` | `in-progress` |
+| `review` | `review` |
+| `done` | *(issue closed)* |
+
+### Requirements
+
+- [gh CLI](https://cli.github.com/) installed and authenticated (`gh auth login`)
+- Repository must have a GitHub remote
+
 ## Configuration
 
 ### Data Location (viban.json)
@@ -184,18 +240,14 @@ viban stores issues in `viban.json` with the following priority:
 | Priority | Location | When Used |
 |----------|----------|-----------|
 | 1 | `$VIBAN_DATA_DIR` | Explicit override via environment variable |
-| 2 | `.git/` (git common dir) | In a git repository (shared across worktrees) |
-| 3 | `.viban/` | Non-git directories (fallback) |
+| 2 | `.viban/` | Default (all projects) |
 
-**Why Git Common Dir?**
-- Shared across git worktrees (parallel work sessions)
-- Survives branch switches
-- Single source of truth for the repository
+**Auto-Migration:** If viban detects `viban.json` or `sync.json` in `.git/` (legacy location), it automatically moves them to `.viban/`.
 
-**For Non-Git Projects:**
+**For Any Project:**
 ```bash
 # viban will automatically create .viban/viban.json in current directory
-cd /path/to/non-git-project
+cd /path/to/project
 viban add "First issue" "Description" P2 feat
 # Creates: /path/to/non-git-project/.viban/viban.json
 ```
@@ -289,13 +341,22 @@ claude-plugin-viban/
 │   └── viban                # Main TUI/CLI script
 ├── docs/
 │   └── CLAUDE.md            # Claude Code integration guide
+├── commands/
+│   └── sync.md              # /viban:sync command
 ├── scripts/
 │   ├── check-deps.sh        # Dependency checker
+│   ├── sync.sh              # Core sync engine (provider-agnostic)
+│   ├── providers/
+│   │   └── 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
+├── tests/
+│   ├── run_all.zsh          # Test runner
+│   └── test_sync.zsh        # Sync engine tests
 ├── LICENSE                  # MIT License
 ├── package.json             # NPM package config
 └── README.md                # This file

package/bin/viban

@@ -121,6 +121,8 @@ IN_TUI=false
 cleanup() {
     # 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
     _stop_coproc
     printf '\033[?25h\033[0m'
     stty echo 2>/dev/null
@@ -193,24 +195,14 @@ export TERM=${TERM:-xterm-256color}
 # ============================================================
 # Priority:
 # 1. VIBAN_DATA_DIR env var (explicit override)
-# 2. Git common dir (shared across worktrees)
-# 3. Project root .viban/ directory (non-git projects)
+# 2. Project root .viban/ directory
 
 VIBAN_DATA_DIR="${VIBAN_DATA_DIR:-}"
 VIBAN_IS_GIT_REPO=false
+git rev-parse --git-dir &>/dev/null && VIBAN_IS_GIT_REPO=true
 
 if [[ -z "$VIBAN_DATA_DIR" ]]; then
-    # Try git common dir first (shared across worktrees)
-    if _git_common="$(git rev-parse --git-common-dir 2>/dev/null)"; then
-        VIBAN_IS_GIT_REPO=true
-        if [[ -d "$_git_common" ]]; then
-            VIBAN_DATA_DIR="$(cd "$_git_common" && pwd)"
-        fi
-    fi
-    # Fallback: project root .viban directory
-    if [[ -z "$VIBAN_DATA_DIR" ]]; then
-        VIBAN_DATA_DIR="${PWD}/.viban"
-    fi
+    VIBAN_DATA_DIR="${PWD}/.viban"
 fi
 
 VIBAN_JSON="${VIBAN_DATA_DIR}/viban.json"
@@ -218,13 +210,16 @@ VIBAN_JSON="${VIBAN_DATA_DIR}/viban.json"
 # Ensure data directory exists
 mkdir -p "$VIBAN_DATA_DIR"
 
-# Auto-migrate: .viban/viban.json -> .git/ when git repo is initialized
-if $VIBAN_IS_GIT_REPO; then
-    _legacy_json="${PWD}/.viban/viban.json"
-    if [[ -f "$_legacy_json" && ! -f "$VIBAN_JSON" ]]; then
-        mv "$_legacy_json" "$VIBAN_JSON"
-        rmdir "${PWD}/.viban" 2>/dev/null
-        echo "✓ Migrated viban data from .viban/ to git directory"
+# Auto-migrate: .git/viban.json -> .viban/ (legacy location)
+if _git_common="$(git rev-parse --git-common-dir 2>/dev/null)"; then
+    _git_dir="$(cd "$_git_common" && pwd)"
+    if [[ -f "${_git_dir}/viban.json" && ! -f "$VIBAN_JSON" ]]; then
+        mv "${_git_dir}/viban.json" "$VIBAN_JSON"
+        echo "✓ Migrated viban.json from .git/ to .viban/"
+    fi
+    if [[ -f "${_git_dir}/sync.json" && ! -f "${VIBAN_DATA_DIR}/sync.json" ]]; then
+        mv "${_git_dir}/sync.json" "${VIBAN_DATA_DIR}/sync.json"
+        echo "✓ Migrated sync.json from .git/ to .viban/"
     fi
 fi
 
@@ -336,8 +331,9 @@ init_json() {
     if [[ ! -f "$VIBAN_JSON" ]]; then
         local max_wt_id=0
         if [[ -d "$VIBAN_DATA_DIR/worktrees" ]]; then
+            local wt_id
             for d in "$VIBAN_DATA_DIR/worktrees/"*(/N); do
-                local wt_id="${d:t}"
+                wt_id="${d:t}"
                 [[ "$wt_id" =~ ^[0-9]+$ ]] && (( wt_id > max_wt_id )) && max_wt_id=$wt_id
             done
         fi
@@ -700,14 +696,15 @@ build_column_lines() {
             done <<< "$_batch_output"
         else
             # All-ASCII fast path - no Python needed
+            local _t _mw _fc _d
             for (( _i=1; _i<=_n; _i++ )); do
-                local _t="${_titles[$_i]}" _mw=${_title_max_ws[$_i]}
+                _t="${_titles[$_i]}" _mw=${_title_max_ws[$_i]}
                 (( ${#_t} > _mw )) && _t="${_t:0:$_mw}"
                 _short_titles+=("$_t")
-                local _fc="${_title_pfxs[$_i]}${_t}"
+                _fc="${_title_pfxs[$_i]}${_t}"
                 _title_cws+=(${#_fc})
 
-                local _d="${_descs[$_i]}"
+                _d="${_descs[$_i]}"
                 (( ${#_d} > _desc_max_w )) && _d="${_d:0:$_desc_max_w}"
                 _short_descs+=("$_d")
                 _desc_cws+=($((2 + ${#_d})))
@@ -717,29 +714,34 @@ build_column_lines() {
 
     # --- Pass 3: Render cards ---
     local shown=0
+    local id priority issue_type ext_id did
+    local spinner_prefix title_content title_pad
+    local desc_content desc_pad
+    local priority_tag priority_color type_tag type_color tags_w tags_pad
+    local border_color text_color desc_color
     for (( _i=1; _i<=_n; _i++ )); do
-        local id="${_ids[$_i]}"
-        local priority="${_priorities[$_i]}"
-        local issue_type="${_types[$_i]}"
-        local ext_id="${_ext_ids[$_i]}"
-        local did; did=$(display_id "$id" "$ext_id")
+        id="${_ids[$_i]}"
+        priority="${_priorities[$_i]}"
+        issue_type="${_types[$_i]}"
+        ext_id="${_ext_ids[$_i]}"
+        did=$(display_id "$id" "$ext_id")
 
         # Title line
-        local spinner_prefix=""
+        spinner_prefix=""
         [[ "$st" == "in_progress" ]] && spinner_prefix="${SPINNER_FRAMES[$((SPINNER_IDX % ${#SPINNER_FRAMES[@]} + 1))]} "
-        local title_content="  ${spinner_prefix}${did} ${_short_titles[$_i]}"
-        local title_pad=$((card_inner - ${_title_cws[$_i]}))
+        title_content="  ${spinner_prefix}${did} ${_short_titles[$_i]}"
+        title_pad=$((card_inner - ${_title_cws[$_i]}))
         (( title_pad < 0 )) && title_pad=0
 
         # Description line
-        local desc_content="  ${_short_descs[$_i]}"
-        local desc_pad=$((card_inner - ${_desc_cws[$_i]}))
+        desc_content="  ${_short_descs[$_i]}"
+        desc_pad=$((card_inner - ${_desc_cws[$_i]}))
         (( desc_pad < 0 )) && desc_pad=0
 
         # Priority and type tags
-        local priority_tag="[$priority]"
-        local priority_color="${PRIORITY_COLOR[$priority]:-$A_DIM}"
-        local type_tag="" type_color="" tags_w=0
+        priority_tag="[$priority]"
+        priority_color="${PRIORITY_COLOR[$priority]:-$A_DIM}"
+        type_tag="" type_color="" tags_w=0
         if [[ -n "$issue_type" ]]; then
             type_tag="[${TYPE_LABEL[$issue_type]:-$issue_type}]"
             type_color="${TYPE_COLOR[$issue_type]:-$A_DIM}"
@@ -747,11 +749,11 @@ build_column_lines() {
         else
             tags_w=${#priority_tag}
         fi
-        local tags_pad=$((card_inner - tags_w - 2))
+        tags_pad=$((card_inner - tags_w - 2))
 
-        local border_color="$A_DIM"
-        local text_color="$A_FG"
-        local desc_color="$A_DIM"
+        border_color="$A_DIM"
+        text_color="$A_FG"
+        desc_color="$A_DIM"
         if (( is_col_selected && shown == card_sel )); then
             border_color="${A_SELECTED}"
             text_color="${A_BOLD}${A_ACCENT}"
@@ -1044,7 +1046,17 @@ delete_issue() {
     local id=$1
     local repo_root=$(git rev-parse --show-toplevel 2>/dev/null)
     local wt_dir="$VIBAN_DATA_DIR/worktrees/$id"
+
+    # Determine branch name: prefer issue-{num} when external_id present
     local branch="viban-$id"
+    local _ext_id=$(get_ext_id "$id")
+    if [[ -n "$_ext_id" && "$_ext_id" != "null" ]]; then
+        local _issue_num="${_ext_id##*:}"
+        if git -C "$repo_root" rev-parse --verify "issue-${_issue_num}" &>/dev/null 2>&1; then
+            branch="issue-${_issue_num}"
+        fi
+    fi
+
     if [[ -d "$wt_dir" ]]; then
         git -C "$repo_root" worktree remove "$wt_dir" --force 2>/dev/null
         git -C "$repo_root" branch -D "$branch" 2>/dev/null
@@ -1058,6 +1070,11 @@ level1_columns() {
     _start_coproc
     local col=0 card=0
 
+    # Auto-sync state (120 iterations × 0.5s timeout = ~60s interval)
+    local _sync_counter=0
+    local _SYNC_INTERVAL=120
+    local _sync_pid=""
+
     # Hide cursor and disable input echo
     stty -echo 2>/dev/null
     printf '\033[?25l\033[2J\033[H'
@@ -1066,6 +1083,27 @@ level1_columns() {
     update_term_cache
 
     while true; do
+        # Auto-sync: reap finished background sync
+        if [[ -n "$_sync_pid" ]]; then
+            if ! kill -0 "$_sync_pid" 2>/dev/null; then
+                wait "$_sync_pid" 2>/dev/null
+                _sync_pid=""
+            fi
+        fi
+
+        # Auto-sync: trigger when interval reached and sync configured
+        ((_sync_counter++)) || true
+        if (( _sync_counter >= _SYNC_INTERVAL )) && [[ -z "$_sync_pid" && -f "$VIBAN_DATA_DIR/sync.json" ]]; then
+            _sync_counter=0
+            local _sync_provider
+            _sync_provider=$(jq -r '.provider // ""' "$VIBAN_DATA_DIR/sync.json" 2>/dev/null)
+            if [[ -n "$_sync_provider" && "$_sync_provider" != "null" ]]; then
+                VIBAN_JSON="$VIBAN_JSON" VIBAN_DATA_DIR="$VIBAN_DATA_DIR" \
+                    VIBAN_PROVIDER="$_sync_provider" VIBAN_SCRIPT_DIR="$VIBAN_SCRIPT_DIR" \
+                    bash "$VIBAN_SCRIPT_DIR/scripts/sync.sh" --auto &
+                _sync_pid=$!
+            fi
+        fi
         # Cache JSON data once per frame
         local json_data=$(cat "$VIBAN_JSON")
 
@@ -1417,6 +1455,20 @@ cmd_add() {
             updated_at:$now
         }]' "$VIBAN_JSON" > "$VIBAN_JSON.tmp" && mv "$VIBAN_JSON.tmp" "$VIBAN_JSON"
     rm -f "$tmpjson"
+
+    # Auto-create remote issue if sync is configured and no ext_id provided
+    if [[ -z "$ext_id" && -f "$VIBAN_DATA_DIR/sync.json" ]]; then
+        local provider
+        provider=$(jq -r '.provider // ""' "$VIBAN_DATA_DIR/sync.json" 2>/dev/null)
+        if [[ -n "$provider" && "$provider" != "null" ]]; then
+            local created_ext_id
+            created_ext_id=$(VIBAN_JSON="$VIBAN_JSON" VIBAN_DATA_DIR="$VIBAN_DATA_DIR" \
+                VIBAN_PROVIDER="$provider" VIBAN_SCRIPT_DIR="$VIBAN_SCRIPT_DIR" \
+                bash "$VIBAN_SCRIPT_DIR/scripts/sync_create.sh" "$id" 2>/dev/null) || true
+            [[ -n "$created_ext_id" ]] && ext_id="$created_ext_id"
+        fi
+    fi
+
     local type_info=""
     [[ -n "$issue_type" ]] && type_info=" [$issue_type]"
     local attach_info=""
@@ -1466,7 +1518,17 @@ cmd_done() {
     # Cleanup worktree if exists
     local repo_root=$(git rev-parse --show-toplevel 2>/dev/null)
     local wt_dir="$VIBAN_DATA_DIR/worktrees/$1"
+
+    # Determine branch name: prefer issue-{num} when external_id present
     local branch="viban-$1"
+    local _ext_id=$(get_ext_id "$1")
+    if [[ -n "$_ext_id" && "$_ext_id" != "null" ]]; then
+        local _issue_num="${_ext_id##*:}"
+        if git -C "$repo_root" rev-parse --verify "issue-${_issue_num}" &>/dev/null 2>&1; then
+            branch="issue-${_issue_num}"
+        fi
+    fi
+
     if [[ -d "$wt_dir" ]]; then
         git -C "$repo_root" worktree remove "$wt_dir" --force 2>/dev/null
         git -C "$repo_root" branch -D "$branch" 2>/dev/null

package/commands/add.md

@@ -4,78 +4,54 @@ description: "Register a problem as a viban issue"
 
 # /add - Register Issue
 
-Register a problem as a viban issue. Keep it lightweight — no codebase exploration, no heavy analysis.
+Register a problem as a viban issue. No codebase exploration, no solutions — symptoms only.
 
-> **Principle**: Clarify symptoms only if vague. Don't explore code or propose solutions.
+**Input**: `$ARGUMENTS`
 
-## Input
+## Step 1: Clarify (only if vague)
 
-**User Input**: `$ARGUMENTS`
+If clear enough (who/what/where), skip to Step 2. Otherwise, one AskUserQuestion:
+- header: "Problem", question: "Can you describe the symptom more specifically?"
+- options: context-appropriate (e.g. "Error/crash", "Feature not working", "Performance issue", "Let me describe")
 
-## Step 1: Clarify (only if needed)
+## Step 2: Priority & Type
 
-If the user's description is **clear enough** to register (who/what/where), skip to Step 2.
+Infer from description. Don't ask unless truly ambiguous.
 
-If **vague or ambiguous**, concretize with one AskUserQuestion:
+| Priority | Condition | Type | When |
+|----------|-----------|------|------|
+| P0 | System down, data loss | bug | Something broken |
+| P1 | Feature broken, errors | feat | New functionality |
+| P2 | Performance, warnings | chore | Maintenance, config |
+| P3 | Improvements, refactoring | refactor | Code restructuring |
 
-- header: "Problem"
-- question: "Can you describe the symptom more specifically?"
-- options based on context, e.g.:
-  - "Error/crash on specific action"
-  - "Feature not working as expected"
-  - "Performance issue"
-  - "Let me describe"
-- multiSelect: false
-
-Goal: get a **one-sentence symptom** clear enough for an assignee to understand.
-
-## Step 2: Determine Priority & Type
-
-Infer from the description. Do NOT ask unless truly ambiguous.
-
-| Condition | Priority |
-|-----------|----------|
-| System down, data loss | P0 |
-| Feature broken, errors | P1 |
-| Performance, warnings | P2 |
-| Improvements, refactoring | P3 |
-
-| Type | When |
-|------|------|
-| bug | Something is broken |
-| feat | New functionality |
-| chore | Maintenance, config |
-| refactor | Code restructuring |
-
-## Step 3: Check Workflow for Issue Numbering
+## Step 3: Issue Numbering
 
 ```bash
 [ -f ".viban/workflow.md" ] && cat ".viban/workflow.md"
 ```
 
-- If workflow says **Manual** issue numbering → ask user for an external ID (e.g. `PROJ-42`)
-- If workflow says **Auto** or no workflow exists → let viban auto-assign
-- If user provided a specific ID in `$ARGUMENTS` → use it regardless of workflow
+- Workflow says **Manual** → ask user for external ID (e.g. `PROJ-42`)
+- **Auto** or no workflow → let viban auto-assign
+- ID in `$ARGUMENTS` → use it regardless
 
 ## Step 4: Register
 
-Write the description to a temp file, then register:
-
 ```bash
 cat > /tmp/viban-desc.md <<'VIBAN_EOF'
 ## Symptoms
-{concretized one-sentence symptom from Step 1}
-{additional context from user input, if any}
+{one-sentence symptom}
+{additional context, if any}
 VIBAN_EOF
 
 # Auto numbering (default)
 viban add "{title}" --desc-file /tmp/viban-desc.md --priority {priority} --type {type}
 
-# Manual numbering (when workflow specifies manual)
+# Manual numbering (when workflow specifies)
 viban add "{title}" --desc-file /tmp/viban-desc.md --priority {priority} --type {type} --ext-id "{external_id}"
 ```
 
-**Why heredoc?** `<<'VIBAN_EOF'` prevents shell interpretation of backticks, `$`, etc.
+Use `<<'VIBAN_EOF'` (quoted) to prevent shell interpretation.
 
 ## Step 5: Report
 
@@ -86,9 +62,38 @@ Issue #{id} registered
   Status: backlog
 ```
 
-## Notes
+## Step 6: Suggest Plan Mode
+
+**Skip** for trivial issues (typo, one-liner config, simple copy edit).
+**Recommend** for everything else. Use AskUserQuestion:
+
+- header: "Next step", question: "Want to start planning the solution now?"
+- options:
+  - "Plan now (Recommended)" — 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`:
+
+```bash
+mkdir -p .viban/plans
+```
+
+```markdown
+# Plan: {issue title}
+> Issue #{id} | {priority} | {type} | Created: {timestamp}
+
+{full plan content}
+```
+
+Report: `Plan saved to .viban/plans/{issue-id}.md — /viban:assign will auto-load it.`
+
+**"Later"**: end skill.
+
+> **Bias towards planning.** When in doubt, suggest plan mode.
+
+## Rules
 
-- **No codebase exploration** — the assignee does that during `/viban:assign`
-- **No solution proposals** — focus on symptoms only
-- **Check duplicates** before registering: `viban list`
-- **Don't over-prioritize** — P0 is system-down only
+- No codebase exploration — assignee does that in `/viban:assign`
+- No solution proposals — symptoms only
+- Check duplicates first: `viban list`
+- P0 is system-down only