claude-plugin-viban 1.0.37 → 1.1.0

package/.claude-plugin/plugin.json

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

package/bin/viban

@@ -35,7 +35,7 @@ check_dependencies() {
 }
 
 # Only check dependencies for interactive commands (not help)
-[[ "$1" != "help" && "$1" != "--help" && "$1" != "-h" ]] && check_dependencies
+[[ "$1" != "help" && "$1" != "--help" && "$1" != "-h" && "$1" != "sync" ]] && check_dependencies
 
 # ============================================================
 # Auto-update Check (once per day, cached)
@@ -113,7 +113,7 @@ auto_update_check() {
 
 # Run auto-update for all commands except help/version/update itself
 case "$1" in
-    help|--help|-h|--version|-v|update) ;;
+    help|--help|-h|--version|-v|update|sync) ;;
     *) auto_update_check "$@" ;;
 esac
 
@@ -246,7 +246,7 @@ EOF
 
 # Auto-initialize for commands that need data (not help/init)
 case "$1" in
-    help|--help|-h|--version|-v|update|init) ;;
+    help|--help|-h|--version|-v|update|init|sync) ;;
     *) init_viban_json ;;
 esac
 
@@ -1571,6 +1571,26 @@ cmd_migrate() {
     ' "$VIBAN_JSON"
 }
 
+cmd_sync() {
+    local provider="${VIBAN_SYNC_PROVIDER:-}"
+    # Auto-detect provider from existing sync.json or default to github
+    if [[ -z "$provider" && -f "$VIBAN_DATA_DIR/sync.json" ]]; then
+        provider=$(jq -r '.provider // "github"' "$VIBAN_DATA_DIR/sync.json")
+    fi
+    provider="${provider:-github}"
+
+    local provider_script="$VIBAN_SCRIPT_DIR/scripts/providers/${provider}.sh"
+    if [[ ! -f "$provider_script" ]]; then
+        echo "Error: Unknown sync provider '$provider'"
+        echo "Available: $(ls "$VIBAN_SCRIPT_DIR/scripts/providers/" 2>/dev/null | sed 's/\.sh$//' | tr '\n' ' ')"
+        exit 1
+    fi
+
+    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.sh" "$@"
+}
+
 main() {
     check_deps
     init_json
@@ -1585,6 +1605,7 @@ main() {
         edit)   [[ -z "$2" ]] && { echo "Usage: viban edit <id>"; exit 1; }; edit_issue "$2";;
         priority) cmd_priority "$2" "$3";;
         migrate) cmd_migrate;;
+        sync)   shift; cmd_sync "$@";;
         --version|-v)
             # Get version from package.json
             if [[ -f "$VIBAN_SCRIPT_DIR/package.json" ]]; then
@@ -1616,6 +1637,7 @@ main() {
             echo "  viban edit <id>   Edit task in editor"
             echo "  viban get <id>    Get task details (JSON)"
             echo "  viban migrate     Migrate: extract type from title"
+            echo "  viban sync        Sync with external issue tracker (GitHub, etc.)"
             echo "  viban update      Update to latest version (if available)"
             echo ""
             echo "  Priority: P0=CRITICAL, P1=HIGH, P2=MEDIUM, P3=LOW"

package/commands/sync.md

@@ -0,0 +1,99 @@
+---
+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 "$(git rev-parse --git-common-dir 2>/dev/null || echo .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/install.sh

@@ -4,6 +4,8 @@
 
 set -e
 
+main() {
+
 RED='\033[0;31m'
 GREEN='\033[0;32m'
 YELLOW='\033[0;33m'
@@ -172,39 +174,14 @@ echo ""
 echo -e "${BOLD}Registering Claude Code plugin...${NC}"
 echo ""
 
-CLAUDE_CONFIG_DIR="${HOME}/.claude"
-CLAUDE_PLUGINS_FILE="${CLAUDE_CONFIG_DIR}/plugins.json"
-
-mkdir -p "$CLAUDE_CONFIG_DIR"
-
-# Get npm global prefix to find viban
-NPM_PREFIX=$(npm prefix -g)
-VIBAN_PLUGIN_DIR="${NPM_PREFIX}/lib/node_modules/claude-plugin-viban"
-
-# Check if plugins.json exists
-if [[ -f "$CLAUDE_PLUGINS_FILE" ]]; then
-    # Check if viban is already registered
-    if jq -e '.plugins[] | select(.name == "viban")' "$CLAUDE_PLUGINS_FILE" > /dev/null 2>&1; then
-        echo -e "${GREEN}✓${NC} Plugin already registered"
-    else
-        # Add viban to existing plugins
-        jq --arg path "$VIBAN_PLUGIN_DIR" '.plugins += [{"name": "viban", "path": $path}]' "$CLAUDE_PLUGINS_FILE" > "${CLAUDE_PLUGINS_FILE}.tmp"
-        mv "${CLAUDE_PLUGINS_FILE}.tmp" "$CLAUDE_PLUGINS_FILE"
-        echo -e "${GREEN}✓${NC} Plugin registered"
-    fi
+if command -v claude &> /dev/null; then
+    claude plugin marketplace add https://github.com/happy-nut/claude-plugin-viban 2>/dev/null || true
+    claude plugin install viban 2>/dev/null || true
+    echo -e "${GREEN}✓${NC} Plugin registered in Claude Code"
 else
-    # Create new plugins.json
-    cat > "$CLAUDE_PLUGINS_FILE" << EOF
-{
-  "plugins": [
-    {
-      "name": "viban",
-      "path": "$VIBAN_PLUGIN_DIR"
-    }
-  ]
-}
-EOF
-    echo -e "${GREEN}✓${NC} Plugin registered"
+    echo -e "${YELLOW}!${NC} Claude Code CLI not found. To register the plugin manually, run:"
+    echo -e "  ${YELLOW}claude plugin marketplace add https://github.com/happy-nut/claude-plugin-viban${NC}"
+    echo -e "  ${YELLOW}claude plugin install viban${NC}"
 fi
 
 echo ""
@@ -220,3 +197,7 @@ echo -e "  ${YELLOW}viban help${NC}         Show all commands"
 echo ""
 echo -e "In Claude Code, the plugin is now available."
 echo ""
+
+}
+
+main "$@"

package/package.json

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

package/scripts/providers/github.sh

@@ -0,0 +1,268 @@
+#!/bin/bash
+# GitHub provider for viban sync
+# Implements the provider interface using the `gh` CLI
+
+# ============================================================
+# Provider Interface
+# ============================================================
+
+provider_name() {
+    echo "github"
+}
+
+provider_check_deps() {
+    if ! command -v gh &>/dev/null; then
+        echo "Error: gh CLI not found"
+        echo "  Install: brew install gh"
+        echo "  Or visit: https://cli.github.com/"
+        return 1
+    fi
+}
+
+provider_check_auth() {
+    if ! gh auth status &>/dev/null; then
+        echo "Error: Not authenticated with GitHub"
+        echo "  Run: gh auth login"
+        return 1
+    fi
+}
+
+provider_detect_config() {
+    local remote_url
+    remote_url=$(git remote get-url origin 2>/dev/null) || {
+        echo "Error: No git remote 'origin' found"
+        return 1
+    }
+
+    local repo=""
+    # SSH format: git@github.com:owner/repo.git
+    if [[ "$remote_url" =~ git@github\.com:([^/]+/[^/.]+)(\.git)?$ ]]; then
+        repo="${BASH_REMATCH[1]}"
+    # HTTPS format: https://github.com/owner/repo.git
+    elif [[ "$remote_url" =~ github\.com/([^/]+/[^/.]+)(\.git)?$ ]]; then
+        repo="${BASH_REMATCH[1]}"
+    fi
+
+    if [[ -z "$repo" ]]; then
+        echo "Error: Could not detect GitHub repo from remote URL: $remote_url"
+        return 1
+    fi
+
+    echo "{\"repo\":\"$repo\"}"
+}
+
+# ============================================================
+# Label Mapping
+# ============================================================
+
+# Status labels
+_gh_status_to_viban() {
+    local gh_state="$1" labels="$2"
+    if [[ "$gh_state" == "closed" ]]; then
+        echo "done"
+    elif echo "$labels" | grep -q "review"; then
+        echo "review"
+    elif echo "$labels" | grep -q "in-progress"; then
+        echo "in_progress"
+    else
+        echo "backlog"
+    fi
+}
+
+_viban_status_labels() {
+    local st="$1"
+    case "$st" in
+        in_progress) echo "in-progress" ;;
+        review)      echo "review" ;;
+        *)           echo "" ;;
+    esac
+}
+
+# Priority mapping
+_gh_priority_to_viban() {
+    local labels="$1"
+    if echo "$labels" | grep -q "P0-critical"; then echo "P0"
+    elif echo "$labels" | grep -q "P1-high"; then echo "P1"
+    elif echo "$labels" | grep -q "P2-medium"; then echo "P2"
+    elif echo "$labels" | grep -q "P3-low"; then echo "P3"
+    else echo "P3"
+    fi
+}
+
+_viban_priority_label() {
+    local priority="$1"
+    case "$priority" in
+        P0) echo "P0-critical" ;;
+        P1) echo "P1-high" ;;
+        P2) echo "P2-medium" ;;
+        P3) echo "P3-low" ;;
+        *)  echo "" ;;
+    esac
+}
+
+# Type mapping
+_gh_type_to_viban() {
+    local labels="$1"
+    if echo "$labels" | grep -q "bug"; then echo "bug"
+    elif echo "$labels" | grep -q "enhancement"; then echo "feat"
+    elif echo "$labels" | grep -q "chore"; then echo "chore"
+    elif echo "$labels" | grep -q "refactor"; then echo "refactor"
+    else echo ""
+    fi
+}
+
+_viban_type_label() {
+    local type="$1"
+    case "$type" in
+        bug)      echo "bug" ;;
+        feat)     echo "enhancement" ;;
+        chore)    echo "chore" ;;
+        refactor) echo "refactor" ;;
+        *)        echo "" ;;
+    esac
+}
+
+# ============================================================
+# Core Provider Functions
+# ============================================================
+
+provider_fetch_issues() {
+    local repo="$1"
+
+    local issues
+    issues=$(gh issue list --repo "$repo" --state open --json number,title,body,labels,updatedAt --limit 200 2>/dev/null) || {
+        echo "Error: Failed to fetch issues from $repo"
+        return 1
+    }
+
+    # Transform to normalized format
+    echo "$issues" | jq '[.[] | {
+        remote_id: (.number | tostring),
+        title: .title,
+        description: (.body // ""),
+        status: (
+            if ([.labels[].name] | any(. == "review")) then "review"
+            elif ([.labels[].name] | any(. == "in-progress")) then "in_progress"
+            else "backlog"
+            end
+        ),
+        priority: (
+            if ([.labels[].name] | any(. == "P0-critical")) then "P0"
+            elif ([.labels[].name] | any(. == "P1-high")) then "P1"
+            elif ([.labels[].name] | any(. == "P2-medium")) then "P2"
+            elif ([.labels[].name] | any(. == "P3-low")) then "P3"
+            else "P3"
+            end
+        ),
+        type: (
+            if ([.labels[].name] | any(. == "bug")) then "bug"
+            elif ([.labels[].name] | any(. == "enhancement")) then "feat"
+            elif ([.labels[].name] | any(. == "chore")) then "chore"
+            elif ([.labels[].name] | any(. == "refactor")) then "refactor"
+            else null
+            end
+        ),
+        updated_at: .updatedAt
+    }]'
+}
+
+provider_create_issue() {
+    local repo="$1"
+    # Read normalized JSON from stdin
+    local issue_json
+    issue_json=$(cat)
+
+    local title body labels_args
+    title=$(echo "$issue_json" | jq -r '.title')
+    body=$(echo "$issue_json" | jq -r '.description // ""')
+
+    # Build labels
+    local labels=()
+    local status_label priority_label type_label
+
+    status_label=$(_viban_status_labels "$(echo "$issue_json" | jq -r '.status // "backlog"')")
+    [[ -n "$status_label" ]] && labels+=("$status_label")
+
+    priority_label=$(_viban_priority_label "$(echo "$issue_json" | jq -r '.priority // "P3"')")
+    [[ -n "$priority_label" ]] && labels+=("$priority_label")
+
+    type_label=$(_viban_type_label "$(echo "$issue_json" | jq -r '.type // ""')")
+    [[ -n "$type_label" ]] && labels+=("$type_label")
+
+    local label_args=()
+    for l in "${labels[@]}"; do
+        label_args+=(--label "$l")
+    done
+
+    local result
+    result=$(gh issue create --repo "$repo" --title "$title" --body "$body" "${label_args[@]}" 2>/dev/null) || {
+        echo "Error: Failed to create issue '$title'"
+        return 1
+    }
+
+    # Extract issue number from URL (gh returns URL like https://github.com/owner/repo/issues/42)
+    echo "$result" | grep -o '[0-9]*$'
+}
+
+provider_update_issue() {
+    local repo="$1" remote_id="$2"
+    # Read normalized JSON from stdin
+    local issue_json
+    issue_json=$(cat)
+
+    local title body
+    title=$(echo "$issue_json" | jq -r '.title')
+    body=$(echo "$issue_json" | jq -r '.description // ""')
+
+    # Collect all desired labels
+    local labels=()
+    local status_label priority_label type_label
+
+    status_label=$(_viban_status_labels "$(echo "$issue_json" | jq -r '.status // "backlog"')")
+    [[ -n "$status_label" ]] && labels+=("$status_label")
+
+    priority_label=$(_viban_priority_label "$(echo "$issue_json" | jq -r '.priority // "P3"')")
+    [[ -n "$priority_label" ]] && labels+=("$priority_label")
+
+    type_label=$(_viban_type_label "$(echo "$issue_json" | jq -r '.type // ""')")
+    [[ -n "$type_label" ]] && labels+=("$type_label")
+
+    # Remove old status/priority/type labels, then add new ones
+    local remove_labels="in-progress,review,P0-critical,P1-high,P2-medium,P3-low,bug,enhancement,chore,refactor"
+    gh issue edit "$remote_id" --repo "$repo" --title "$title" --body "$body" \
+        --remove-label "$remove_labels" 2>/dev/null
+
+    if [[ ${#labels[@]} -gt 0 ]]; then
+        local add_labels
+        add_labels=$(IFS=,; echo "${labels[*]}")
+        gh issue edit "$remote_id" --repo "$repo" --add-label "$add_labels" 2>/dev/null
+    fi
+}
+
+provider_close_issue() {
+    local repo="$1" remote_id="$2"
+    gh issue close "$remote_id" --repo "$repo" 2>/dev/null || {
+        echo "Error: Failed to close issue #$remote_id"
+        return 1
+    }
+}
+
+provider_ensure_labels() {
+    local repo="$1"
+
+    local required_labels=(
+        "in-progress:Status: In Progress:0E8A16"
+        "review:Status: In Review:FBCA04"
+        "P0-critical:Priority: Critical:B60205"
+        "P1-high:Priority: High:D93F0B"
+        "P2-medium:Priority: Medium:FBCA04"
+        "P3-low:Priority: Low:0E8A16"
+        "chore:Type: Chore:EEEEEE"
+        "refactor:Type: Refactor:C5DEF5"
+    )
+
+    for label_def in "${required_labels[@]}"; do
+        IFS=: read -r name desc color <<< "$label_def"
+        gh label create "$name" --repo "$repo" --description "$desc" --color "$color" 2>/dev/null || true
+    done
+}

package/scripts/sync.sh

@@ -0,0 +1,530 @@
+#!/bin/bash
+# viban sync - Core sync engine (provider-agnostic)
+# Orchestrates two-way sync between viban board and external issue trackers.
+#
+# Environment variables (set by bin/viban cmd_sync):
+#   VIBAN_JSON       - Path to viban.json
+#   VIBAN_DATA_DIR   - Path to viban data directory
+#   VIBAN_PROVIDER   - Provider name (e.g., "github")
+#   VIBAN_SCRIPT_DIR - Path to viban install directory
+
+set -euo pipefail
+
+SYNC_JSON="${VIBAN_DATA_DIR}/sync.json"
+PROVIDER_SCRIPT="${VIBAN_SCRIPT_DIR}/scripts/providers/${VIBAN_PROVIDER}.sh"
+
+# ============================================================
+# Provider Loading
+# ============================================================
+
+load_provider() {
+    if [[ ! -f "$PROVIDER_SCRIPT" ]]; then
+        echo "Error: Provider script not found: $PROVIDER_SCRIPT"
+        return 1
+    fi
+    source "$PROVIDER_SCRIPT"
+
+    # Validate provider interface
+    local required_funcs=(
+        provider_name provider_check_deps provider_check_auth
+        provider_detect_config provider_fetch_issues provider_create_issue
+        provider_update_issue provider_close_issue provider_ensure_labels
+    )
+    for func in "${required_funcs[@]}"; do
+        if ! declare -f "$func" &>/dev/null; then
+            echo "Error: Provider '${VIBAN_PROVIDER}' missing required function: $func"
+            return 1
+        fi
+    done
+}
+
+# ============================================================
+# Sync Metadata (sync.json)
+# ============================================================
+
+read_sync_meta() {
+    if [[ -f "$SYNC_JSON" ]]; then
+        cat "$SYNC_JSON"
+    else
+        echo '{}'
+    fi
+}
+
+write_sync_meta() {
+    local data="$1"
+    echo "$data" > "${SYNC_JSON}.tmp" && mv "${SYNC_JSON}.tmp" "$SYNC_JSON"
+}
+
+get_issue_meta() {
+    local viban_id="$1"
+    read_sync_meta | jq -r --arg id "$viban_id" '.issues[$id] // empty'
+}
+
+set_issue_meta() {
+    local viban_id="$1" remote_id="$2" remote_updated="$3" viban_updated="$4"
+    local meta
+    meta=$(read_sync_meta)
+    meta=$(echo "$meta" | jq --arg vid "$viban_id" --arg rid "$remote_id" \
+        --arg ru "$remote_updated" --arg vu "$viban_updated" \
+        '.issues[$vid] = {remote_id: $rid, remote_updated_at: $ru, viban_updated_at: $vu}')
+    write_sync_meta "$meta"
+}
+
+# ============================================================
+# Sync Init
+# ============================================================
+
+sync_init() {
+    local repo_override="$1"
+
+    echo "Initializing sync..."
+
+    # Check provider dependencies and auth
+    provider_check_deps || exit 1
+    provider_check_auth || exit 1
+
+    # Detect or use provided config
+    local config
+    if [[ -n "$repo_override" ]]; then
+        config="{\"repo\":\"$repo_override\"}"
+    else
+        config=$(provider_detect_config) || exit 1
+    fi
+
+    local repo
+    repo=$(echo "$config" | jq -r '.repo')
+    echo "Detected $(provider_name) repo: $repo"
+
+    # Ensure required labels exist
+    echo "Ensuring labels..."
+    provider_ensure_labels "$repo"
+
+    # Initialize sync.json
+    local now
+    now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    write_sync_meta "$(jq -n \
+        --arg provider "$(provider_name)" \
+        --argjson config "$config" \
+        --arg now "$now" \
+        '{provider: $provider, provider_config: $config, last_sync_at: $now, issues: {}}')"
+
+    echo "Sync initialized for $(provider_name) ($repo)"
+}
+
+# ============================================================
+# Sync Pull (remote -> viban)
+# ============================================================
+
+sync_pull() {
+    local repo="$1" dry_run="${2:-false}"
+    local pulled=0 updated=0 unchanged=0
+
+    local remote_issues
+    remote_issues=$(provider_fetch_issues "$repo") || exit 1
+
+    local provider_prefix
+    provider_prefix="$(provider_name):"
+
+    local count
+    count=$(echo "$remote_issues" | jq 'length')
+
+    for i in $(seq 0 $((count - 1))); do
+        local issue
+        issue=$(echo "$remote_issues" | jq ".[$i]")
+
+        local remote_id title description status priority type remote_updated
+        remote_id=$(echo "$issue" | jq -r '.remote_id')
+        title=$(echo "$issue" | jq -r '.title')
+        description=$(echo "$issue" | jq -r '.description // ""')
+        status=$(echo "$issue" | jq -r '.status')
+        priority=$(echo "$issue" | jq -r '.priority // "P3"')
+        type=$(echo "$issue" | jq -r '.type // ""')
+        remote_updated=$(echo "$issue" | jq -r '.updated_at')
+
+        local ext_id="${provider_prefix}${remote_id}"
+
+        # Find existing viban card with this external_id
+        local viban_card
+        viban_card=$(jq -r --arg eid "$ext_id" \
+            '.issues[] | select(.external_id == $eid)' "$VIBAN_JSON" 2>/dev/null)
+
+        if [[ -z "$viban_card" || "$viban_card" == "null" ]]; then
+            # New remote issue -> import
+            if [[ "$dry_run" == "true" ]]; then
+                echo "  <- ${ext_id} \"${title}\" (new card to create)"
+            else
+                # Use jq to add card directly
+                local now viban_id
+                now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+                viban_id=$(jq -r '.next_id // (([.issues[].id] | max // 0) + 1)' "$VIBAN_JSON")
+
+                local type_val="null"
+                [[ -n "$type" && "$type" != "null" ]] && type_val="\"$type\""
+
+                jq --arg id "$viban_id" --arg title "$title" --arg desc "$description" \
+                    --arg status "$status" --arg priority "$priority" \
+                    --arg ext_id "$ext_id" --arg now "$now" --argjson type_val "$type_val" \
+                    '.next_id = ((.next_id // 0) + 1) |
+                    .issues += [{
+                        id: ($id | tonumber),
+                        title: $title,
+                        description: $desc,
+                        status: $status,
+                        priority: $priority,
+                        type: $type_val,
+                        external_id: $ext_id,
+                        attachments: [],
+                        assigned_to: null,
+                        created_at: $now,
+                        updated_at: $now
+                    }]' "$VIBAN_JSON" > "${VIBAN_JSON}.tmp" && mv "${VIBAN_JSON}.tmp" "$VIBAN_JSON"
+
+                set_issue_meta "$viban_id" "$remote_id" "$remote_updated" "$now"
+                echo "  <- ${ext_id} \"${title}\" (new card created)"
+            fi
+            ((pulled++))
+        else
+            # Existing card - check for changes
+            local viban_id viban_updated
+            viban_id=$(echo "$viban_card" | jq -r '.id')
+            viban_updated=$(echo "$viban_card" | jq -r '.updated_at')
+
+            # Get last known sync timestamps
+            local meta
+            meta=$(get_issue_meta "$viban_id")
+
+            if [[ -z "$meta" ]]; then
+                # First time seeing this linked card in sync - record and skip
+                set_issue_meta "$viban_id" "$remote_id" "$remote_updated" "$viban_updated"
+                echo "  == ${ext_id} \"${title}\" (tracking started)"
+                ((unchanged++))
+                continue
+            fi
+
+            local last_remote_updated last_viban_updated
+            last_remote_updated=$(echo "$meta" | jq -r '.remote_updated_at')
+            last_viban_updated=$(echo "$meta" | jq -r '.viban_updated_at')
+
+            local remote_changed=false viban_changed=false
+            [[ "$remote_updated" != "$last_remote_updated" ]] && remote_changed=true
+            [[ "$viban_updated" != "$last_viban_updated" ]] && viban_changed=true
+
+            if [[ "$remote_changed" == "false" && "$viban_changed" == "false" ]]; then
+                echo "  == ${ext_id} \"${title}\" (no changes)"
+                ((unchanged++))
+            elif [[ "$remote_changed" == "true" && "$viban_changed" == "false" ]]; then
+                # Only remote changed -> pull
+                if [[ "$dry_run" == "true" ]]; then
+                    echo "  <- ${ext_id} \"${title}\" (remote updated, will pull)"
+                else
+                    local now
+                    now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+                    local type_val="null"
+                    [[ -n "$type" && "$type" != "null" ]] && type_val="\"$type\""
+
+                    jq --argjson vid "$viban_id" --arg title "$title" --arg desc "$description" \
+                        --arg status "$status" --arg priority "$priority" \
+                        --arg now "$now" --argjson type_val "$type_val" \
+                        '(.issues[] | select((.id | tonumber) == $vid)) |=
+                        . + {title: $title, description: $desc, status: $status,
+                             priority: $priority, type: $type_val, updated_at: $now}' \
+                        "$VIBAN_JSON" > "${VIBAN_JSON}.tmp" && mv "${VIBAN_JSON}.tmp" "$VIBAN_JSON"
+
+                    set_issue_meta "$viban_id" "$remote_id" "$remote_updated" "$now"
+                    echo "  <- ${ext_id} \"${title}\" (pulled remote changes)"
+                fi
+                ((updated++))
+            elif [[ "$remote_changed" == "false" && "$viban_changed" == "true" ]]; then
+                # Only viban changed -> will be handled in push phase
+                echo "  == ${ext_id} \"${title}\" (local changes, will push)"
+                ((unchanged++))
+            else
+                # Both changed -> conflict resolution (remote wins by default)
+                if [[ "$dry_run" == "true" ]]; then
+                    echo "  !! ${ext_id} \"${title}\" (conflict: remote wins)"
+                else
+                    local now
+                    now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+                    local type_val="null"
+                    [[ -n "$type" && "$type" != "null" ]] && type_val="\"$type\""
+
+                    jq --argjson vid "$viban_id" --arg title "$title" --arg desc "$description" \
+                        --arg status "$status" --arg priority "$priority" \
+                        --arg now "$now" --argjson type_val "$type_val" \
+                        '(.issues[] | select((.id | tonumber) == $vid)) |=
+                        . + {title: $title, description: $desc, status: $status,
+                             priority: $priority, type: $type_val, updated_at: $now}' \
+                        "$VIBAN_JSON" > "${VIBAN_JSON}.tmp" && mv "${VIBAN_JSON}.tmp" "$VIBAN_JSON"
+
+                    set_issue_meta "$viban_id" "$remote_id" "$remote_updated" "$now"
+                    echo "  !! ${ext_id} \"${title}\" (conflict: remote wins)"
+                fi
+                ((pulled++))
+            fi
+        fi
+    done
+
+    echo "Pull: $pulled new/conflict, $updated updated, $unchanged unchanged"
+}
+
+# ============================================================
+# Sync Push (viban -> remote)
+# ============================================================
+
+sync_push() {
+    local repo="$1" dry_run="${2:-false}" push_new="${3:-false}"
+    local pushed=0 closed=0 unchanged=0
+
+    local provider_prefix
+    provider_prefix="$(provider_name):"
+
+    # Get all viban cards with this provider's external_id
+    local linked_cards
+    linked_cards=$(jq -r --arg prefix "$provider_prefix" \
+        '[.issues[] | select(.external_id != null and (.external_id | startswith($prefix)))]' \
+        "$VIBAN_JSON")
+
+    local count
+    count=$(echo "$linked_cards" | jq 'length')
+
+    for i in $(seq 0 $((count - 1))); do
+        local card
+        card=$(echo "$linked_cards" | jq ".[$i]")
+
+        local viban_id ext_id remote_id title status viban_updated
+        viban_id=$(echo "$card" | jq -r '.id')
+        ext_id=$(echo "$card" | jq -r '.external_id')
+        remote_id="${ext_id#${provider_prefix}}"
+        title=$(echo "$card" | jq -r '.title')
+        status=$(echo "$card" | jq -r '.status')
+        viban_updated=$(echo "$card" | jq -r '.updated_at')
+
+        # Get last known sync timestamps
+        local meta
+        meta=$(get_issue_meta "$viban_id")
+        if [[ -z "$meta" ]]; then
+            ((unchanged++))
+            continue
+        fi
+
+        local last_viban_updated
+        last_viban_updated=$(echo "$meta" | jq -r '.viban_updated_at')
+
+        if [[ "$viban_updated" == "$last_viban_updated" ]]; then
+            ((unchanged++))
+            continue
+        fi
+
+        # Viban card changed since last sync -> push
+        if [[ "$dry_run" == "true" ]]; then
+            echo "  -> ${ext_id} \"${title}\" (will push local changes)"
+            ((pushed++))
+        else
+            echo "$card" | jq '{
+                title: .title,
+                description: (.description // ""),
+                status: .status,
+                priority: (.priority // "P3"),
+                type: (.type // "")
+            }' | provider_update_issue "$repo" "$remote_id"
+
+            local now remote_updated
+            now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+            # Fetch updated remote timestamp
+            remote_updated="$now"
+
+            set_issue_meta "$viban_id" "$remote_id" "$remote_updated" "$viban_updated"
+            echo "  -> ${ext_id} \"${title}\" (pushed)"
+            ((pushed++))
+        fi
+    done
+
+    # Handle push-new: viban cards without external_id
+    if [[ "$push_new" == "true" ]]; then
+        local unlinked_cards
+        unlinked_cards=$(jq -r \
+            '[.issues[] | select(.external_id == null or .external_id == "")]' \
+            "$VIBAN_JSON")
+
+        local unlinked_count
+        unlinked_count=$(echo "$unlinked_cards" | jq 'length')
+
+        for i in $(seq 0 $((unlinked_count - 1))); do
+            local card
+            card=$(echo "$unlinked_cards" | jq ".[$i]")
+
+            local viban_id title
+            viban_id=$(echo "$card" | jq -r '.id')
+            title=$(echo "$card" | jq -r '.title')
+
+            if [[ "$dry_run" == "true" ]]; then
+                echo "  -> (new) #${viban_id} \"${title}\" (will create remote issue)"
+                ((pushed++))
+            else
+                local new_remote_id
+                new_remote_id=$(echo "$card" | jq '{
+                    title: .title,
+                    description: (.description // ""),
+                    status: .status,
+                    priority: (.priority // "P3"),
+                    type: (.type // "")
+                }' | provider_create_issue "$repo") || {
+                    echo "  !! Failed to create remote issue for #${viban_id}"
+                    continue
+                }
+
+                local ext_id="${provider_prefix}${new_remote_id}"
+                local now
+                now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+                # Update viban card with external_id
+                jq --argjson vid "$viban_id" --arg eid "$ext_id" --arg now "$now" \
+                    '(.issues[] | select((.id | tonumber) == $vid)) |= . + {external_id: $eid, updated_at: $now}' \
+                    "$VIBAN_JSON" > "${VIBAN_JSON}.tmp" && mv "${VIBAN_JSON}.tmp" "$VIBAN_JSON"
+
+                set_issue_meta "$viban_id" "$new_remote_id" "$now" "$now"
+                echo "  -> ${ext_id} #${viban_id} \"${title}\" (created remote issue)"
+                ((pushed++))
+            fi
+        done
+    fi
+
+    echo "Push: $pushed pushed, $closed closed, $unchanged unchanged"
+}
+
+# ============================================================
+# Sync Status
+# ============================================================
+
+sync_status() {
+    if [[ ! -f "$SYNC_JSON" ]]; then
+        echo "Sync not configured. Run: viban sync --init"
+        return 1
+    fi
+
+    local meta
+    meta=$(read_sync_meta)
+
+    local provider repo last_sync tracked_count
+    provider=$(echo "$meta" | jq -r '.provider')
+    repo=$(echo "$meta" | jq -r '.provider_config.repo // "unknown"')
+    last_sync=$(echo "$meta" | jq -r '.last_sync_at // "never"')
+    tracked_count=$(echo "$meta" | jq '.issues | length')
+
+    local provider_prefix="${provider}:"
+    local total_cards linked_cards unlinked_cards
+    total_cards=$(jq '.issues | length' "$VIBAN_JSON")
+    linked_cards=$(jq --arg prefix "$provider_prefix" \
+        '[.issues[] | select(.external_id != null and (.external_id | startswith($prefix)))] | length' \
+        "$VIBAN_JSON")
+    unlinked_cards=$((total_cards - linked_cards))
+
+    echo "Sync status:"
+    echo "  Provider: $provider ($repo)"
+    echo "  Last sync: $last_sync"
+    echo "  Tracked: $tracked_count issues"
+    echo "  Linked cards: $linked_cards"
+    echo "  Unlinked cards: $unlinked_cards"
+}
+
+# ============================================================
+# Full Sync
+# ============================================================
+
+sync_full() {
+    local repo="$1" dry_run="${2:-false}" push_new="${3:-false}"
+
+    echo "Syncing with $(provider_name) ($repo)..."
+    sync_pull "$repo" "$dry_run"
+    sync_push "$repo" "$dry_run" "$push_new"
+
+    if [[ "$dry_run" == "false" ]]; then
+        # Update last_sync_at
+        local now
+        now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+        local meta
+        meta=$(read_sync_meta)
+        meta=$(echo "$meta" | jq --arg now "$now" '.last_sync_at = $now')
+        write_sync_meta "$meta"
+    fi
+}
+
+# ============================================================
+# Main CLI Parser
+# ============================================================
+
+main() {
+    local action="full"
+    local dry_run=false
+    local push_new=false
+    local pull_only=false
+    local push_only=false
+    local repo_override=""
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --init)      action="init"; shift ;;
+            --status)    action="status"; shift ;;
+            --dry-run)   dry_run=true; shift ;;
+            --push-new)  push_new=true; shift ;;
+            --pull-only) pull_only=true; shift ;;
+            --push-only) push_only=true; shift ;;
+            --repo)      repo_override="$2"; shift 2 ;;
+            --provider)  shift 2 ;;  # Already handled by bin/viban
+            *)           echo "Unknown option: $1"; exit 1 ;;
+        esac
+    done
+
+    # Load provider
+    load_provider || exit 1
+
+    # Handle init
+    if [[ "$action" == "init" ]]; then
+        sync_init "$repo_override"
+        return
+    fi
+
+    # Handle status
+    if [[ "$action" == "status" ]]; then
+        sync_status
+        return
+    fi
+
+    # For sync operations, check that sync is configured
+    if [[ ! -f "$SYNC_JSON" ]]; then
+        echo "Sync not configured. Run: viban sync --init"
+        exit 1
+    fi
+
+    # Check provider deps and auth
+    provider_check_deps || exit 1
+    provider_check_auth || exit 1
+
+    # Get repo from sync config or override
+    local repo
+    if [[ -n "$repo_override" ]]; then
+        repo="$repo_override"
+    else
+        repo=$(jq -r '.provider_config.repo' "$SYNC_JSON")
+    fi
+
+    if [[ -z "$repo" || "$repo" == "null" ]]; then
+        echo "Error: No repo configured. Run: viban sync --init"
+        exit 1
+    fi
+
+    # Execute sync
+    if [[ "$pull_only" == "true" ]]; then
+        echo "Pulling from $(provider_name) ($repo)..."
+        sync_pull "$repo" "$dry_run"
+    elif [[ "$push_only" == "true" ]]; then
+        echo "Pushing to $(provider_name) ($repo)..."
+        sync_push "$repo" "$dry_run" "$push_new"
+    else
+        sync_full "$repo" "$dry_run" "$push_new"
+    fi
+}
+
+main "$@"

package/skills/sync/SKILL.md

@@ -0,0 +1,100 @@
+---
+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 "$(git rev-parse --git-common-dir 2>/dev/null || echo .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)