claude-plugin-viban 1.0.0

package/commands/assign.md

@@ -0,0 +1,14 @@
+---
+name: assign
+description: "Assign and resolve first backlog issue from viban board"
+---
+
+# /assign
+
+Invokes the `viban:assign` skill to handle the complete workflow:
+- Assign first backlog issue
+- Analyze and resolve
+- Create PR
+- Move to review status
+
+Usage: `/assign`

package/commands/todo.md

@@ -0,0 +1,15 @@
+---
+name: todo
+description: "Analyze problem and register as viban issue"
+---
+
+# /todo
+
+Invokes the `viban:todo` skill to:
+- Analyze problem situation
+- Search codebase for evidence
+- Register issue with proper priority and type
+
+Usage:
+- `/todo` (will prompt for details)
+- `/todo "Charts not showing on results page"`

package/docs/CLAUDE.md

@@ -0,0 +1,245 @@
+# viban - Kanban TUI Tool
+
+Kanban board TUI tool written in zsh.
+
+## 필수 검증
+
+### 레이아웃 검증 (수정 후 필수)
+**커밋 전 반드시 스크립트로 검증** - 추측 금지
+
+```bash
+# 카드 렌더링 검증 스크립트 실행
+zsh << 'EOF'
+source .claude/viban/viban 2>/dev/null || true
+col_w=38; card_inner=$((col_w - 4))
+# 테스트: 한글 포함 긴 제목으로 truncate 및 박스 정렬 확인
+title="feat(shared): BacktestEngine 통합 및 추상화"
+spinner_w=2; title_w=$((card_inner - 7 - spinner_w))
+short=$(truncate_str "$title" $title_w)
+content="  / #5 $short"
+content_w=$(str_width "$content")
+pad=$((card_inner - content_w))
+border=$(gen_border $card_inner)
+printf "╭%s╮\n│%s%${pad}s│\n╰%s╯\n" "$border" "$content" "" "$border"
+EOF
+```
+
+**검증 항목:**
+- 박스 테두리(╭╮╰╯│) 정렬
+- 스피너 있을 때/없을 때 둘 다 확인
+- 한글 포함 제목 truncation
+
+## Workflow Rules
+
+### 🔴 Worktree 사용 금지
+- **main repo에서 feature branch로 직접 작업**
+- worktree 생성/사용 금지 (사용자 명시적 요청)
+- 브랜치 네이밍: `viban-{ISSUE_ID}` (예: `viban-78`)
+
+### Branch-Based Workflow
+```bash
+# 1. main에서 분기
+git checkout main && git pull
+git checkout -b viban-{ISSUE_ID}
+
+# 2. 작업 후 push
+git push -u origin viban-{ISSUE_ID}
+
+# 3. PR 생성
+gh pr create --title "..." --body "..."
+```
+
+### Base Branch Sync
+- Before branch creation: `git fetch origin main`
+- Before PR push: `git fetch origin main && git rebase origin/main`
+- Resolve conflicts if any before pushing
+
+## Shell Script Rules
+
+### JSON Handling (Critical)
+
+**Use `printf '%s'` when piping shell variables to jq**
+
+```bash
+# BAD: echo interprets escape sequences (\n, \t) → JSON corruption
+local title=$(echo "$issue" | jq -r '.title')
+
+# GOOD: printf passes data as-is
+local title=$(printf '%s' "$issue" | jq -r '.title')
+```
+
+Violating this rule causes jq parse errors on issues with newlines/tabs in description.
+
+### Locale Handling (zsh-specific)
+
+**`LC_ALL=C var=val` persists in zsh (unlike bash)**
+
+```bash
+# BAD: LC_ALL=C persists after this line, breaks subsequent ${#str}
+LC_ALL=C byte_count=${#str}
+
+# GOOD: Restore locale after use
+LC_ALL=C byte_count=${#str}
+unset LC_ALL
+```
+
+- 서브셸 `$(...)` 호출은 부모에 영향 없음
+- 직접 호출 함수에서만 `unset LC_ALL` 필요
+
+### ANSI Color in printf
+
+**ANSI 코드는 format string 안에 넣어야 함**
+
+```bash
+# BAD: %s는 이스케이프 시퀀스를 해석하지 않음 → raw \033[2m 출력
+printf "%s" "${A_DIM}text${A_RESET}"
+
+# GOOD: format string에 직접 포함
+printf "${A_DIM}%s${A_RESET}" "text"
+```
+
+### Terminal State for External Commands
+
+**외부 명령(에디터, gum 등) 호출 전 터미널 상태 복원**
+
+```bash
+# stty -echo 상태에서 에디터 열면 입력 불가
+stty echo 2>/dev/null   # 복원
+$EDITOR "$file"
+stty -echo 2>/dev/null  # 다시 비활성화
+```
+
+## Claude Code Integration
+
+### Skills
+
+The viban plugin provides two skills for automated issue management:
+
+#### `/viban:assign`
+
+Assigns the top backlog issue to the current session and executes the full resolution workflow:
+
+1. Fetches the highest priority backlog issue
+2. Assigns it to the current session
+3. Analyzes the issue and executes the fix
+4. Marks the issue as review/done upon completion
+
+**Usage:**
+```
+/viban:assign
+```
+
+**When to use:**
+- When you want Claude to autonomously pick and solve the next issue
+- For continuous workflow in parallel sessions
+- When issues are pre-prioritized in the backlog
+
+#### `/viban:todo`
+
+Analyzes a problem situation and creates a new viban issue with proper structure:
+
+1. Analyzes the user's description
+2. Creates a structured issue with:
+   - Clear, concise title (Korean)
+   - Detailed description with symptoms, root cause, and expected behavior
+   - Appropriate priority (P0-P3)
+   - Type tag (bug/feat/chore/etc)
+
+**Usage:**
+```
+/viban:todo
+```
+
+Then describe the problem when prompted.
+
+**When to use:**
+- When you encounter a bug or want to track a new feature
+- To convert free-form problem descriptions into structured issues
+- Before starting work on a new problem
+
+### CLI Commands
+
+All CLI commands are available via the `viban` binary:
+
+```bash
+viban list              # Display kanban board
+viban add "Title" "Desc" P2 feat  # Create issue
+viban assign [session]  # 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 help              # Show help
+```
+
+### Data Location
+
+Issues are stored in `viban.json` at the git common directory:
+
+```bash
+# Find viban.json
+git rev-parse --git-common-dir
+# → .git/viban.json (or ../../.git/viban.json in worktrees)
+```
+
+**Custom location:**
+```bash
+export VIBAN_DATA_DIR="/path/to/data"
+```
+
+### Issue Status Flow
+
+```
+backlog → in_progress → review → done
+            ↑              ↑
+      (assign)       (complete)
+```
+
+### Parallel Sessions
+
+Multiple Claude sessions can work in parallel:
+
+1. Each session calls `/viban:assign`
+2. Session ID is stored in `assigned_to`
+3. Other sessions skip assigned issues
+4. Completion moves issue to review/done
+
+### Issue Structure
+
+```json
+{
+  "version": 1,
+  "issues": [
+    {
+      "id": 1,
+      "title": "Issue title",
+      "description": "Detailed description",
+      "status": "backlog|in_progress|review|done",
+      "priority": "P0|P1|P2|P3",
+      "type": "bug|feat|chore|refactor|docs",
+      "assigned_to": null | "session-id",
+      "created_at": "2025-01-23T10:00:00Z",
+      "updated_at": "2025-01-23T10:00:00Z"
+    }
+  ]
+}
+```
+
+### Priority Levels
+
+| Priority | Meaning |
+|----------|---------|
+| 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 |
+| docs | Documentation updates |
+| test | Test additions/fixes |

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "claude-plugin-viban",
+  "version": "1.0.0",
+  "description": "Terminal Kanban TUI for AI-human collaborative issue tracking",
+  "main": "bin/viban",
+  "bin": {
+    "viban": "./bin/viban"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "skills/",
+    "commands/",
+    "docs/",
+    ".claude-plugin/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "bash scripts/check-deps.sh || true",
+    "test": "bash scripts/check-deps.sh && ./bin/viban help"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/happy-nut/claude-plugin-viban.git"
+  },
+  "author": {
+    "name": "happy-nut",
+    "url": "https://github.com/happy-nut"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/happy-nut/claude-plugin-viban/issues"
+  },
+  "homepage": "https://github.com/happy-nut/claude-plugin-viban#readme",
+  "keywords": [
+    "claude-code",
+    "plugin",
+    "kanban",
+    "tui",
+    "issue-tracking",
+    "viban",
+    "terminal",
+    "cli",
+    "ai-tools"
+  ],
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "preferGlobal": true
+}

package/scripts/check-deps.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# viban dependency checker
+
+set -e
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+NC='\033[0m'
+
+echo "Checking viban dependencies..."
+echo ""
+
+missing=0
+
+check_dep() {
+    local name="$1"
+    local install_macos="$2"
+    local install_linux="$3"
+
+    if command -v "$name" &> /dev/null; then
+        echo -e "  ${GREEN}✓${NC} $name"
+        return 0
+    else
+        echo -e "  ${RED}✗${NC} $name not found"
+        if [[ "$OSTYPE" == "darwin"* ]]; then
+            echo -e "    Install: ${YELLOW}$install_macos${NC}"
+        else
+            echo -e "    Install: ${YELLOW}$install_linux${NC}"
+        fi
+        missing=1
+        return 1
+    fi
+}
+
+check_dep "gum" "brew install gum" "See https://github.com/charmbracelet/gum#installation"
+check_dep "jq" "brew install jq" "apt install jq"
+
+echo ""
+if [[ $missing -eq 1 ]]; then
+    echo -e "${YELLOW}Please install missing dependencies for full functionality.${NC}"
+    exit 0  # Don't fail npm install
+fi
+
+echo -e "${GREEN}All dependencies installed!${NC}"

package/skills/assign/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: viban:assign
+description: "Assign and resolve the first backlog issue from viban board through to PR completion. Reads project CLAUDE.md for workflow."
+category: debugging
+complexity: advanced
+mcp-servers: [serena]
+personas: []
+---
+
+# /viban:assign
+
+Workflow: First backlog issue → Resolve → PR completion
+
+> **⛔ No direct `viban.json` access** — CLI only
+> **🔴 No Worktree** — Work directly on branch in main repo
+> **📋 Workflow**: Read CLAUDE.md first, follow project workflow if exists
+
+---
+
+## Phase 0: CONTEXT & SETUP
+
+### 0.1 Read Project Workflow (CRITICAL)
+
+**Before any work, read the project's CLAUDE.md:**
+
+```bash
+# Check for CLAUDE.md at common locations
+for path in "./CLAUDE.md" "./.claude/CLAUDE.md" "../CLAUDE.md"; do
+    [ -f "$path" ] && cat "$path"
+done
+```
+
+**Look for:**
+- `Issue Resolution Workflow` section
+- `Workflow` or `Development Process` section
+- Specific steps like `ultrawork`, `code-simplifier`, `code-review`
+- Testing requirements (`pytest`, manual verification, etc.)
+
+**IMPORTANT:**
+- If project has a defined workflow → **MUST follow it exactly**
+- If no workflow found → Use default workflow (Phase 1 below)
+
+### 0.2 Git Setup
+
+```bash
+# 1. Check for uncommitted changes
+if [ -n "$(git status --porcelain)" ]; then
+    echo "⚠️ Uncommitted changes detected"
+    # → Ask user whether to commit (use AskUserQuestion)
+fi
+
+# 2. Switch to main branch and sync
+git checkout main
+git fetch origin main
+git reset --hard origin/main
+
+# 3. Assign issue (state change only, no worktree)
+ISSUE_ID=$(viban assign 2>&1 | tail -1)
+if [ -z "$ISSUE_ID" ] || [ "$ISSUE_ID" = "No backlog" ]; then
+    echo "⚠️ No issues in backlog"
+    exit 0
+fi
+
+# 4. Create new branch
+git checkout -b viban-$ISSUE_ID
+```
+
+**If backlog is empty**: Notify user and exit
+
+---
+
+## Phase 1: ANALYZE → VERIFY
+
+```bash
+viban get $ISSUE_ID
+```
+
+### If Project Workflow Exists (from CLAUDE.md):
+
+**Follow the project's exact steps.** Common patterns include:
+
+1. Root cause analysis (5 Whys)
+2. Context verification (ask if unclear)
+3. Implementation & verification strategy
+4. Code implementation (`/ultrawork` for 2+ files)
+5. **Manual verification** (browser/API, NOT pytest)
+6. Code simplification (`/code-simplifier`)
+7. Code review (`/code-review`)
+
+### Default Workflow (if no project workflow):
+
+1. **Understand**: Read the issue, understand the problem
+2. **Locate**: Find relevant code files
+3. **Analyze**: Determine root cause
+4. **Implement**: Make minimal, focused changes
+5. **Verify**: Test the fix works (appropriate method for the project)
+6. **Review**: Self-review changes for quality
+
+---
+
+## Phase 2: SHIP
+
+### 2.1 Rebase
+
+```bash
+git fetch origin main
+git rebase origin/main
+# On conflict: resolve → git add → git rebase --continue
+```
+
+### 2.2 Commit & Push
+
+```bash
+git add -A
+git commit -m "fix: issue title summary
+
+- Root cause: ...
+- Solution: ...
+
+Resolves: viban-$ISSUE_ID"
+
+git push -u origin viban-$ISSUE_ID
+```
+
+### 2.3 Create PR
+
+```bash
+EXISTING_PR=$(gh pr list --head viban-$ISSUE_ID --json number -q '.[0].number')
+[ -z "$EXISTING_PR" ] && gh pr create \
+    --title "viban-$ISSUE_ID: title" \
+    --body "## Changes
+- ...
+
+## Testing
+- [ ] Tests passing (if applicable)
+- [ ] Manual verification (if applicable)" \
+    --base main
+```
+
+### 2.4 Issue → review
+
+```bash
+viban review $ISSUE_ID
+```
+
+---
+
+## Phase 3: HANDOFF
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📋 Human Review Required
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Issue #$ISSUE_ID → review status
+
+🔗 PR: gh pr view viban-$ISSUE_ID --web
+
+✅ Verification complete:
+   - Project workflow followed
+   - Changes tested appropriately
+   - Code reviewed
+
+📌 After approval: Delete issue from viban TUI
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+## Phase 4: REFLECT (if available)
+
+> **Optional**: Run `/self-reflect` if project has this skill
+
+```
+/self-reflect
+```
+
+---
+
+## Checklist
+
+```
+[ ] Read CLAUDE.md for project workflow
+[ ] Working on viban-$ISSUE_ID branch
+[ ] Project workflow steps completed (or default if none)
+[ ] Rebase complete
+[ ] PR pushed
+[ ] viban review executed
+[ ] Self-reflection done (if available)
+```
+
+---
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `viban` | Open TUI |
+| `viban list` | Print board |
+| `viban assign [session]` | Assign issue |
+| `viban get <id>` | View issue |
+| `viban review <id>` | Move to review |