claude-plugin-viban 1.3.12 → 1.3.14

package/.claude-plugin/plugin.json

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

package/README.md

@@ -1,6 +1,6 @@
 # viban
 
-**Vi**sual Kan**ban** - A simple, lightweight local Kanban board for AI-human collaborative issue tracking.
+**Vi**sual Kan**ban** — Issue tracking designed for AI agents.
 
 [![CI](https://github.com/happy-nut/claude-plugin-viban/actions/workflows/ci.yml/badge.svg)](https://github.com/happy-nut/claude-plugin-viban/actions/workflows/ci.yml)
 [![npm version](https://badge.fury.io/js/claude-plugin-viban.svg)](https://www.npmjs.com/package/claude-plugin-viban)
@@ -8,316 +8,279 @@
 
 ![viban](assets/viban.png)
 
-## Why viban?
-
-- **No Worktree Complexity** - Just a single JSON file. No git worktrees, no complex setup.
-- **Lightweight & Fast** - Pure shell script with minimal dependencies. Starts instantly.
-- **Local First** - Your issues stay in your repo. No external services or accounts needed.
-- **AI-Native** - Built for Claude Code integration from the ground up.
+Register bugs. Claude picks them up, resolves them, and creates PRs — while you keep finding the next issue.
 
-## Recommended Workflow
-
-![recommended workflow](assets/screenshot.png)
+```bash
+# You find a bug and register it
+/viban:add "Login fails after password reset"
 
-The most effective way to use viban is with **multiple terminal sessions**:
+# Claude assigns itself the top-priority issue and starts working
+/viban:assign
 
+# Or resolve 3 issues in parallel — each in its own git worktree
+/viban:parallel-assign 3
 ```
-┌───────────────────┐  ┌───────────────────┐  ┌───────────────────┐
-│    Session 1      │  │    Session 2      │  │    Session 3      │
-│                   │  │                   │  │                   │
-│  Product QA       │  │  Issue Work       │  │  viban TUI        │
-│  + /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: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
 
-This separation keeps your workflow clean and prevents context switching.
-
-## Features
-
-- **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
-- **Parallel Sessions**: Multiple Claude Code sessions can work simultaneously
-- **Session Assignment**: Prevents duplicate work across parallel agents
-- **Claude Code Integration**: Built-in commands for automated issue resolution
-
-## Requirements
+## Why viban?
 
-- zsh
-- 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)
+GitHub Issues, Linear, and Jira are built for humans coordinating with humans. viban is built for **humans coordinating with AI agents**.
 
-> **Tip:** If using Claude Code, run `/viban:setup` to install all dependencies automatically.
+| | Traditional trackers | viban |
+|---|---|---|
+| **Who resolves issues?** | Human developers | AI agents (Claude Code) |
+| **Parallel work** | Manual branch management | Isolated worktrees, zero conflicts |
+| **Where it lives** | External SaaS | Your repo (single JSON file) |
+| **Setup** | Accounts, permissions, integrations | `npm install -g claude-plugin-viban` |
+| **Context switching** | Browser ↔ terminal | Everything in terminal |
+| **Already using GitHub Issues?** | — | Two-way sync included |
 
-## Installation
+## Quick Start
 
 ### For Claude Code Users
 
 ```bash
-/plugin marketplace add https://github.com/happy-nut/claude-plugin-viban
-/plugin install viban
-/viban:setup   # Installs all dependencies automatically
+/install claude-plugin-viban
+/viban:setup
 ```
 
 ### For Terminal Users
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/happy-nut/claude-plugin-viban/main/install.sh | bash
-```
-
-Or via npm (requires zsh, gum, jq pre-installed):
 ```bash
 npm install -g claude-plugin-viban
 ```
 
-<details>
-<summary>Troubleshooting: viban command not found</summary>
-
-Add npm global bin to your PATH:
-```bash
-# For zsh
-echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.zshrc && source ~/.zshrc
-
-# For bash
-echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc && source ~/.bashrc
-```
-</details>
-
-## Usage
-
-### TUI (Interactive Mode)
+Then start tracking:
 
 ```bash
-viban           # Launch TUI
+viban add "Fix login error" "Users cannot login after password reset" P1 bug
+viban add "Add dark mode" P2 feat
+viban                        # Open TUI board
 ```
 
-**Navigation:**
+## How It Works
 
-| Level | Screen | Controls |
-|-------|--------|----------|
-| 1 | Column List | ↑↓ select, Enter to enter |
-| 2 | Card List | ↑↓ select, Enter for details, `a` to add |
-| 3 | Card Details | Change status, delete |
+### Sequential Mode
 
-**TUI Features:**
-- Navigate between backlog, in_progress, review, done columns
-- View issue cards with priority and type badges
-- Create new issues with rich descriptions
-- Move issues between statuses
-- Delete issues
+Run multiple terminal sessions — one for QA, one for resolution, one for monitoring:
 
-### CLI Commands
+![recommended workflow](assets/screenshot.png)
 
-```bash
-viban list                              # Display kanban board
-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>                         # 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
+```
+┌───────────────────┐  ┌───────────────────┐  ┌───────────────────┐
+│    Session 1      │  │    Session 2      │  │    Session 3      │
+│                   │  │                   │  │                   │
+│  Product QA       │  │  Issue Work       │  │  viban TUI        │
+│  + /viban:add     │  │  + /viban:assign  │  │                   │
+│                   │  │                   │  │  (always open)    │
+│  Find bugs,       │  │  Pick & resolve   │  │  Monitor board    │
+│  register issues  │  │  issues           │  │  in real-time     │
+└───────────────────┘  └───────────────────┘  └───────────────────┘
 ```
 
-**Examples:**
-
-```bash
-# 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
+### Parallel Mode
 
-# Mark issue #5 as done
-viban done 5
+Resolve multiple issues at once with `/viban:parallel-assign`:
 
-# Get issue details as JSON
-viban get 3
+```
+┌───────────────────┐
+│   Coordinator     │  /viban:parallel-assign 3
+│                   │
+│  Assigns issues,  │──┬──────────────────────────────────────┐
+│  creates worktrees│  │                                      │
+│  collects results │  ▼                  ▼                   ▼
+│                   │  ┌──────────┐  ┌──────────┐  ┌──────────┐
+│                   │  │ Agent 1  │  │ Agent 2  │  │ Agent 3  │
+│                   │  │ wt/#12   │  │ wt/#13   │  │ wt/#14   │
+│                   │  │ Analyze  │  │ Analyze  │  │ Analyze  │
+│                   │  │ Implement│  │ Implement│  │ Implement│
+│                   │  │ Commit   │  │ Commit   │  │ Commit   │
+│  Push, create PRs │  └──────────┘  └──────────┘  └──────────┘
+│  Run tests, report│
+└───────────────────┘
 ```
 
-### Claude Code Integration
-
-viban provides skills and commands for automated issue management in Claude Code:
+- Each agent works in an isolated git worktree (`.viban/worktrees/{ID}`)
+- Zero interference between agents — no merge conflicts
+- Coordinator pushes branches, creates PRs, and runs tests after all agents finish
 
-#### `/viban:add` - Register structured issue
+## Claude Code Skills
 
-Analyzes a problem and creates a properly structured viban issue:
+These are the core AI-agent commands. Each one is a Claude Code slash command.
 
-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
+### `/viban:add` — Register an issue
 
-**Use cases:**
-- Bug reporting
-- Feature requests
-- Converting free-form descriptions to structured issues
+Analyzes your description and creates a structured issue with proper priority, type, and description.
 
-#### `/viban:assign` - Assign next backlog issue
+```
+/viban:add "Search is broken on mobile"
+→ Infers: P1 bug, enriches description, registers to backlog
+```
 
-Picks the highest priority backlog issue and assigns it to the current session:
+### `/viban:assign` — Assign and resolve
 
-1. Assigns top backlog issue
-2. Evaluates description clarity
-3. If unclear, interviews user and enriches the issue description
+Picks the highest-priority unblocked backlog issue, assigns it, and follows your project's workflow to resolve it.
 
-This command is **assignment only** - it does not start implementation. Use your project's workflow (`.viban/workflow.md`) to define what happens next.
+```
+/viban:assign
+→ Picks #7 (P0 bug), analyzes code, implements fix, creates PR
+```
 
-#### `/viban:parallel-assign` - Parallel resolution with worktrees
+### `/viban:parallel-assign` — Parallel resolution
 
-Resolves multiple backlog issues simultaneously using isolated git worktrees:
+Assigns N issues (default 3, max 5) and spawns one agent per issue in isolated git worktrees.
 
-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
+```
+/viban:parallel-assign 3
+→ Assigns #8, #9, #10 — three agents work simultaneously
+→ Each commits on its own branch, coordinator creates PRs
+```
 
-**Use cases:**
-- Batch processing a backlog
-- Parallel agent workflows with zero interference
-- Rapid issue throughput
+### `/viban:setup` — Install and configure
 
-#### `/viban:setup` - Install & configure
+Installs dependencies, detects your project conventions, and generates a workflow file.
 
-Installs all dependencies and optionally configures a project workflow:
+## TUI
 
-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
+```bash
+viban    # Launch interactive board
+```
 
-## External Tracker Sync
+3-column Kanban board (backlog → in_progress → review). Completed issues move to history.
 
-viban can sync two-way with external issue trackers. Currently supported: **GitHub Issues**.
+| Level | Screen | Controls |
+|-------|--------|----------|
+| 1 | Column List | ↑↓ select, Enter to enter |
+| 2 | Card List | ↑↓ select, Enter for details, `a` to add |
+| 3 | Card Details | Change status, delete |
 
-### Quick Start
+## CLI Reference
 
 ```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
+# Board
+viban list                                          # Show board
+viban list --status backlog --priority P0,P1        # Filter
+viban list --type bug --search "auth"               # Search
+viban history                                       # Completed issues
+viban stats                                         # Throughput metrics
+viban export [md|html]                              # Export board
+
+# Issues
+viban add "Title" ["Desc"] [P0-P3] [type] [--parent <id>]
+viban edit <id>                                     # Edit in editor
+viban get <id>                                      # JSON details
+viban priority <id> <P0-P3>
+viban comment <id> "msg"
+viban attach <id> <file1> [file2...]
+
+# Workflow
+viban assign                                        # Assign top backlog
+viban review [id]                                   # → review
+viban move <id> <status>                            # → any status
+viban done <id> [--purge] [--dry-run]               # → done
+
+# Dependencies
+viban link <id> blocks <id>
+viban unlink <id> blocks <id> [--dry-run]
+
+# Maintenance
+viban sync                                          # GitHub sync
+viban backup / viban restore [file]
+viban changelog [range]
+viban update
 ```
 
-> **Tip:** Use `viban sync --dry-run` first to preview changes before syncing.
+<details>
+<summary><strong>GitHub Issues Sync</strong></summary>
 
-### How It Works
+Two-way sync with GitHub Issues. Comments, dependencies, and sub-tasks are synced.
 
-- **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
+```bash
+viban sync --init       # Initialize (auto-detects from git remote)
+viban sync --dry-run    # Preview changes
+viban sync              # Pull + push
+viban sync --push-new   # Push local-only issues to GitHub
+```
 
-### Status-to-Label Mapping
+**Status mapping:**
 
-| viban status | GitHub label |
-|-------------|-------------|
+| viban | GitHub |
+|-------|--------|
 | `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)
+Requires [gh CLI](https://cli.github.com/) authenticated with `gh auth login`.
 
-viban stores issues in `viban.json` with the following priority:
+</details>
 
-| Priority | Location | When Used |
-|----------|----------|-----------|
-| 1 | `$VIBAN_DATA_DIR` | Explicit override via environment variable |
-| 2 | `.viban/` | Default (all projects) |
+<details>
+<summary><strong>Issue Templates</strong></summary>
 
-**Auto-Migration:** If viban detects `viban.json` or `sync.json` in `.git/` (legacy location), it automatically moves them to `.viban/`.
+Create `.viban/templates.json` to define defaults per issue type:
 
-**For Any Project:**
-```bash
-# viban will automatically create .viban/viban.json in current directory
-cd /path/to/project
-viban add "First issue" "Description" P2 feat
-# Creates: /path/to/non-git-project/.viban/viban.json
+```json
+{
+  "bug": {
+    "priority": "P1",
+    "description": "## Bug Report\n\n**Steps to reproduce:**\n\n**Expected:**\n\n**Actual:**"
+  },
+  "feat": {
+    "priority": "P2",
+    "description": "## Feature\n\n**User story:**\n\n**Acceptance criteria:**"
+  }
+}
 ```
 
-**Custom Data Directory:**
-```bash
-export VIBAN_DATA_DIR="/path/to/shared/data"
-viban list  # Uses /path/to/shared/data/viban.json
-```
+Unset fields are filled from the template when the type matches.
 
-### Auto-Initialization
+</details>
 
-viban automatically initializes when first used:
-- Creates data directory if not exists
-- Creates `viban.json` with empty issue list
-- No manual setup required
+<details>
+<summary><strong>Configuration</strong></summary>
 
-### Issue Status Flow
+### Data Location
 
-```
-backlog → in_progress → review → done
-            ↑              ↑
-      (assign)       (complete)
-```
+| Priority | Location | When |
+|----------|----------|------|
+| 1 | `$VIBAN_DATA_DIR` | Explicit override |
+| 2 | `.viban/` | Default |
+
+Auto-migrates from legacy `.git/` location.
 
 ### Priority Levels
 
 | Priority | Description |
 |----------|-------------|
-| **P0** | Critical - blocks all work |
-| **P1** | High - must do soon |
-| **P2** | Medium - normal priority |
-| **P3** | Low - nice to have |
+| **P0** | Critical — blocks all work |
+| **P1** | High — must do soon |
+| **P2** | Medium — normal priority |
+| **P3** | Low — nice to have |
 
 ### Type Tags
 
-| Type | Use Case |
-|------|----------|
-| **bug** | Fixing broken functionality |
-| **feat** | New feature or enhancement |
-| **refactor** | Code restructuring |
-| **chore** | Maintenance tasks |
+`bug` · `feat` · `refactor` · `chore`
+
+### Status Flow
+
+```
+backlog → in_progress → review → done
+   ↑           ↑           │
+   └───────────┴───────────┘
+        (viban move)
+```
+
+</details>
 
-## Data Structure
+<details>
+<summary><strong>Data Structure</strong></summary>
 
-Issues are stored in `viban.json`:
+Issues are stored in `.viban/viban.json`:
 
 ```json
 {
-  "version": 1,
+  "version": 2,
+  "next_id": 4,
   "issues": [
     {
       "id": 1,
@@ -327,115 +290,49 @@ Issues are stored in `viban.json`:
       "priority": "P1",
       "type": "bug",
       "assigned_to": "session-abc123",
-      "created_at": "2025-01-23T10:00:00Z",
-      "updated_at": "2025-01-23T14:30:00Z"
+      "parent_id": null,
+      "blocked_by": [3],
+      "comments": [
+        {"text": "Root cause found", "created_at": "2026-01-23T14:00:00Z"}
+      ],
+      "attachments": [],
+      "created_at": "2026-01-23T10:00:00Z",
+      "updated_at": "2026-01-23T14:30:00Z"
     }
   ]
 }
 ```
 
-## Parallel Session Handling
-
-Multiple Claude Code sessions can work simultaneously:
-
-1. Each session calls `/viban:assign`
-2. Session ID is recorded in `assigned_to` field
-3. Other sessions skip already-assigned issues
-4. Completion moves issue to `review` or `done`
-
-This prevents duplicate work and enables parallel agent workflows.
+</details>
 
-## File Structure
+## Requirements
 
-```
-claude-plugin-viban/
-├── .claude-plugin/
-│   └── plugin.json              # Plugin metadata
-├── .github/
-│   └── workflows/
-│       ├── ci.yml               # CI testing
-│       └── release.yml          # NPM publishing
-├── bin/
-│   └── viban                    # Main TUI/CLI script
-├── commands/
-│   ├── 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
-│   ├── 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
-├── skills/
-│   ├── 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_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
-```
+- zsh
+- 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 sync)
 
 ## Development
 
-### Running Tests
-
 ```bash
-# Install dependencies
 brew install gum jq
-
-# Run the full test suite (8 suites, 39 tests)
-zsh tests/run_all.zsh
+zsh tests/run_all.zsh    # 19 suites, 212 tests
 ```
 
-### Publishing
-
-See [docs/release.md](docs/release.md) for the full release workflow.
-
-```bash
-# GitHub Actions will automatically publish to npm on tag push
-```
+See [docs/release.md](docs/release.md) for publishing.
 
 ## Contributing
 
-Contributions are welcome! Please:
-
 1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+2. Create a feature branch
+3. Commit your changes
+4. Open a Pull Request
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) file for details.
-
-## Author
-
-**happy-nut**
-
-- GitHub: [@happy-nut](https://github.com/happy-nut)
-- Repository: [claude-plugin-viban](https://github.com/happy-nut/claude-plugin-viban)
+MIT — see [LICENSE](LICENSE).
 
 ## Links
 
-- [npm package](https://www.npmjs.com/package/claude-plugin-viban)
-- [Documentation](https://github.com/happy-nut/claude-plugin-viban/tree/main/docs)
-- [Issues](https://github.com/happy-nut/claude-plugin-viban/issues)
+- [npm](https://www.npmjs.com/package/claude-plugin-viban) · [Issues](https://github.com/happy-nut/claude-plugin-viban/issues) · [Docs](https://github.com/happy-nut/claude-plugin-viban/tree/main/docs)