claude-plugin-viban 1.1.2 → 1.2.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "viban",
-  "version": "1.1.2",
+  "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
 
@@ -1051,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
@@ -1065,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'
@@ -1073,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")
 
@@ -1424,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=""
@@ -1473,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