claude-plugin-viban 1.3.15 → 1.3.17

package/.claude-plugin/plugin.json

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

package/README.md

@@ -137,11 +137,11 @@ Assigns N issues (default 3, max 5) and spawns one agent per issue in isolated g
 
 ### `/viban:review` — Checkout for IDE review
 
-Checks out a review-status issue's branch for inspection in your IDE.
+Checks out the issue branch and soft-resets so all changes appear as staged diffs in your IDE.
 
 ```
 /viban:review
-→ Detects first review card, checks out branch, shows diff summary
+→ Finds first review card, checks out branch, staged diffs ready in IDE
 /viban:review 12
 → Checks out branch for issue #12
 ```
@@ -204,8 +204,8 @@ 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
+viban move <id> <status> [--force]                   # → any status
+viban done <id> [--purge] [--force]                  # → done
 
 # Dependencies
 viban link <id> blocks <id>
@@ -346,7 +346,7 @@ Issues are stored in `.viban/viban.json`:
 
 ```bash
 brew install gum jq
-zsh tests/run_all.zsh    # 19 suites, 212 tests
+zsh tests/run_all.zsh    # 20 suites, 237 tests
 ```
 
 See [docs/release.md](docs/release.md) for publishing.

package/bin/viban

@@ -149,18 +149,14 @@ export TERM=${TERM:-xterm-256color}
 # ============================================================
 # Priority:
 # 1. VIBAN_DATA_DIR env var (explicit override)
-# 2. Project root .viban/ directory
+# 2. CWD .viban/ directory (always uses $PWD, not git root — monorepo safe)
 
 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
-    if $VIBAN_IS_GIT_REPO; then
-        VIBAN_DATA_DIR="$(git rev-parse --show-toplevel)/.viban"
-    else
-        VIBAN_DATA_DIR="${PWD}/.viban"
-    fi
+    VIBAN_DATA_DIR="${PWD}/.viban"
 fi
 
 VIBAN_JSON="${VIBAN_DATA_DIR}/viban.json"

package/docs/CLAUDE.md

@@ -64,11 +64,10 @@ EOF
 
 ```bash
 # 1. 워크트리 생성
-REPO_ROOT=$(git rev-parse --show-toplevel)
-git worktree add -b issue-{ISSUE_ID} "$REPO_ROOT/.viban/worktrees/{ISSUE_ID}" origin/main
+git worktree add -b issue-{ISSUE_ID} "$PWD/.viban/worktrees/{ISSUE_ID}" origin/main
 
 # 2. 워크트리 안에서 작업 후 push
-cd "$REPO_ROOT/.viban/worktrees/{ISSUE_ID}"
+cd "$PWD/.viban/worktrees/{ISSUE_ID}"
 git push -u origin issue-{ISSUE_ID}
 
 # 3. PR 생성

package/package.json

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

package/skills/add/SKILL.md

@@ -90,6 +90,14 @@ Report the registered issue and **stop immediately**. Do not suggest next steps,
 - `Bash` for anything other than `viban` CLI and `cat`/`mkdir` above: FORBIDDEN.
 - No `git` commands. No source code reads. No codebase exploration.
 
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `viban list` | Print board (check for duplicates) |
+| `viban add "<title>" --desc-file <f> --priority <p> --type <t>` | Register issue |
+| `viban add "<title>" ... --ext-id "<id>"` | Register with external ID |
+
 ### Additional rules:
 - **NEVER read or write `viban.json` directly** — always use `viban` CLI commands
 - No solution proposals in the issue — symptoms only

package/skills/approve/SKILL.md

@@ -5,7 +5,7 @@ description: "Approve a reviewed issue — merge branch, cleanup worktree, mark
 
 # /approve
 
-Approve a review-status issue after IDE review. Restores commits, merges the branch, removes the worktree, and marks the card done.
+Approve a review-status issue after IDE review. Merges the branch, removes the worktree, and marks the card done.
 
 > **CLI only** (no direct viban.json access)
 
@@ -29,19 +29,18 @@ viban get $ID
 Confirm the issue is in `review` status. If not, tell the user and exit.
 
 ```bash
-REPO_ROOT=$(git rev-parse --show-toplevel)
 BRANCH="issue-$ID"
-WT_DIR="$REPO_ROOT/.viban/worktrees/$ID"
+WT_DIR="$PWD/.viban/worktrees/$ID"
 ```
 
 ---
 
-## Step 2: Restore Branch Commits
+## Step 2: Return to Main
 
-If worktree exists and was soft-reset (from `/viban:review`):
+Detached HEAD from `/viban:review` — branch is intact, just switch back:
 
 ```bash
-[ -d "$WT_DIR" ] && git -C "$WT_DIR" reset --soft ORIG_HEAD
+git checkout main
 ```
 
 ---
@@ -90,4 +89,29 @@ Nothing to merge. Proceed to Step 4.
 viban done $ID
 ```
 
+---
+
+## Step 6: Restore User State
+
+Check for stash:
+
+```bash
+STASH=$(git stash list | grep "viban-review: before #$ID" | head -1 | cut -d: -f1)
+[ -n "$STASH" ] && git stash pop "$STASH"
+```
+
+Check for temp commit:
+
+```bash
+TEMP=$(git log --oneline -1 | grep "viban-review: temp commit before #$ID")
+[ -n "$TEMP" ] && git reset HEAD~1
+```
+
 Report: "Issue #$ID approved and merged."
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `viban get <id>` | View issue details |
+| `viban done <id>` | Mark issue as done |

package/skills/assign/SKILL.md

@@ -14,6 +14,7 @@ Assign the first backlog issue and execute the full resolution workflow. If the
 ## Output Rules
 
 - **Do NOT output any preamble.** No "Your Task:", "I'll now...", "Let me...", or task summaries before starting work.
+- **NEVER delegate work back to the user.** You must complete the entire issue yourself — writing code, tests, and verifying. Phrases like "Your Task:", "TODO(human)", "Waiting for your implementation", "Take your time", or any message that asks the user to write code are strictly FORBIDDEN. If you encounter a TODO comment, implement it yourself.
 - Start executing Step 0 immediately and silently.
 
 ---
@@ -64,8 +65,7 @@ Assess whether the issue description provides enough context to start working.
 `viban assign` automatically creates a worktree. Locate it:
 
 ```bash
-REPO_ROOT=$(git rev-parse --show-toplevel)
-WT_DIR="$REPO_ROOT/.viban/worktrees/$ISSUE_ID"
+WT_DIR="$PWD/.viban/worktrees/$ISSUE_ID"
 BRANCH="issue-$ISSUE_ID"
 ```
 

package/skills/parallel-assign/SKILL.md

@@ -8,6 +8,8 @@ description: "Assign and resolve multiple independent backlog issues in parallel
 Parallel resolution of independent backlog issues via git worktrees.
 
 > **CLI only** (no direct viban.json access) | **Opus sub-agents** in isolated worktrees
+>
+> **`viban` is a zsh CLI tool.** Always invoke as `viban <command>`, NEVER as `python -m viban` or `python viban`.
 
 **Input**: `$ARGUMENTS` (optional: number of issues, default 3)
 
@@ -16,6 +18,7 @@ Parallel resolution of independent backlog issues via git worktrees.
 ## Output Rules
 
 - **Do NOT output any preamble.** No "Your Task:", "I'll now...", "Let me...", or task summaries before starting work.
+- **NEVER delegate work back to the user.** Each agent must complete its assigned issue fully — writing code, tests, and verifying. Phrases like "Your Task:", "TODO(human)", "Waiting for your implementation", "Take your time", or any message that asks the user to write code are strictly FORBIDDEN. If you encounter a TODO comment, implement it yourself.
 - Start executing Phase 0 immediately and silently.
 
 ---
@@ -75,14 +78,13 @@ If no issues were assigned: notify user and exit.
 For each assigned issue, create an isolated git worktree:
 
 ```bash
-REPO_ROOT=$(git rev-parse --show-toplevel)
-mkdir -p "$REPO_ROOT/.viban/worktrees"
+mkdir -p "$PWD/.viban/worktrees"
 
 for entry in "${ISSUES[@]}"; do
     ID="${entry%%|*}"
     BRANCH="${entry##*|}"
     # Use issue ID as worktree dir name (matches cmd_done cleanup at .viban/worktrees/{ID})
-    WT_DIR="$REPO_ROOT/.viban/worktrees/$ID"
+    WT_DIR="$PWD/.viban/worktrees/$ID"
 
     git worktree add -b "$BRANCH" "$WT_DIR" origin/main
 done
@@ -106,9 +108,9 @@ Spawn one **opus** agent per issue using `Task` tool. All agents launch in a sin
 You are resolving viban issue #{ID} in an isolated git worktree.
 
 ## Environment
-- Worktree path: {REPO_ROOT}/.viban/worktrees/{ID}
+- Worktree path: {PROJECT_ROOT}/.viban/worktrees/{ID}
 - Branch: {BRANCH}
-- Main repo: {REPO_ROOT}
+- Main repo: {PROJECT_ROOT}
 - ALL file operations must happen inside the worktree path
 
 ## Workflow (Analyze + Implement + Verify only)
@@ -125,7 +127,7 @@ You are resolving viban issue #{ID} in an isolated git worktree.
 
 You are one of {N} parallel agents working in isolated git worktrees.
 
-1. Work ONLY inside your worktree: {REPO_ROOT}/.viban/worktrees/{ID}
+1. Work ONLY inside your worktree: {PROJECT_ROOT}/.viban/worktrees/{ID}
    - cd to the worktree before any work
    - All reads, edits, and writes must target files under this path
 
@@ -136,7 +138,7 @@ You are one of {N} parallel agents working in isolated git worktrees.
 
 3. After implementation, commit on your branch:
    ```bash
-   cd {REPO_ROOT}/.viban/worktrees/{ID}
+   cd {PROJECT_ROOT}/.viban/worktrees/{ID}
    git add <specific files>
    git commit -m "type: description
 
@@ -149,6 +151,7 @@ You are one of {N} parallel agents working in isolated git worktrees.
 4. That's it. Stop after committing.
 
 ABSOLUTE RULES:
+- **NEVER delegate work back to the user.** You must complete the entire issue yourself. Phrases like "Your Task:", "TODO(human)", "Waiting for your implementation" are FORBIDDEN. If you encounter a TODO comment, implement it yourself.
 - **Your job ends after committing.** The coordinator handles push, PR creation, and issue status.
 - **FORBIDDEN: `git push`** — the coordinator pushes from the main repo after verifying.
 - **FORBIDDEN: `gh pr create`** — the coordinator creates PRs after transplanting branches.
@@ -161,7 +164,7 @@ ABSOLUTE RULES:
 
 ### Dispatch Pattern
 
-```python
+```text
 # Pseudo-code for the dispatch
 for each (ID, BRANCH) in ISSUES:
     Task(
@@ -183,12 +186,7 @@ for each (ID, BRANCH) in ISSUES:
 
 ## Phase 3: TRANSPLANT & CLEANUP
 
-After all agents finish, the coordinator handles everything from the main repo root.
-
-```bash
-REPO_ROOT=$(git rev-parse --show-toplevel)
-cd "$REPO_ROOT"
-```
+After all agents finish, the coordinator handles everything from the main project root (`$PWD`).
 
 ### 3.1 Verify Local Branches
 

package/skills/reject/SKILL.md

@@ -5,7 +5,7 @@ description: "Reject a reviewed issue — return to in_progress with feedback"
 
 # /reject
 
-Reject a review-status issue and move it back to in_progress. Restores the worktree so the agent can address feedback.
+Reject a review-status issue and move it back to in_progress. The worktree stays intact so the agent can address feedback.
 
 > **CLI only** (no direct viban.json access)
 
@@ -31,26 +31,39 @@ Confirm the issue is in `review` status. If not, tell the user and exit.
 Parse `$ARGUMENTS`: first token is `$ID`, rest is `$FEEDBACK`.
 
 ```bash
-REPO_ROOT=$(git rev-parse --show-toplevel)
 BRANCH="issue-$ID"
-WT_DIR="$REPO_ROOT/.viban/worktrees/$ID"
+WT_DIR="$PWD/.viban/worktrees/$ID"
 ```
 
 ---
 
-## Step 2: Restore Branch Commits
+## Step 2: Return to Main
 
-If worktree was soft-reset (from `/viban:review`):
+Detached HEAD from `/viban:review` — branch is intact, just switch back:
 
 ```bash
-[ -d "$WT_DIR" ] && git -C "$WT_DIR" reset --soft ORIG_HEAD
+git checkout main
 ```
 
-Worktree stays intact for the agent to continue working.
+---
+
+## Step 3: Re-attach Worktree
+
+If worktree exists (detached during review), re-attach it to the branch:
+
+```bash
+[ -d "$WT_DIR" ] && git -C "$WT_DIR" checkout "$BRANCH"
+```
+
+If worktree does not exist, recreate it:
+
+```bash
+[ ! -d "$WT_DIR" ] && git worktree add "$WT_DIR" "$BRANCH"
+```
 
 ---
 
-## Step 3: Move Back to in_progress
+## Step 4: Move Back to in_progress
 
 ```bash
 viban move $ID in_progress
@@ -58,7 +71,7 @@ viban move $ID in_progress
 
 ---
 
-## Step 4: Record Feedback
+## Step 5: Record Feedback
 
 If `$FEEDBACK` is provided:
 
@@ -79,6 +92,28 @@ If no feedback provided, ask the user: "Any feedback for the developer?"
 
 ---
 
-## Step 5: Report
+## Step 6: Restore User State
+
+Check for stash:
+
+```bash
+STASH=$(git stash list | grep "viban-review: before #$ID" | head -1 | cut -d: -f1)
+[ -n "$STASH" ] && git stash pop "$STASH"
+```
+
+Check for temp commit:
+
+```bash
+TEMP=$(git log --oneline -1 | grep "viban-review: temp commit before #$ID")
+[ -n "$TEMP" ] && git reset HEAD~1
+```
 
 Report: "Issue #$ID rejected → in_progress. Worktree intact at `$WT_DIR`."
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `viban get <id>` | View issue details |
+| `viban move <id> <status>` | Move issue to status |
+| `viban comment <id> "<text>"` | Add comment to issue |

package/skills/review/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: review
-description: "Prepare a review issue for IDE review via staged diffs"
+description: "Checkout a review issue's branch for IDE diff review"
 ---
 
 # /review
 
-Prepare a review-status issue for IDE review. Soft-resets the worktree so all changes appear as staged diffs.
+Checkout a review-status issue's branch into the main worktree so the user can review all changes as staged diffs in their IDE.
 
 > **CLI only** (no direct viban.json access)
 
@@ -40,35 +40,49 @@ Show the user a one-line summary: `#ID [PRIORITY] Title`.
 
 ---
 
-## Step 2: Locate Worktree
+## Step 2: Prepare Branch
 
 ```bash
-REPO_ROOT=$(git rev-parse --show-toplevel)
 BRANCH="issue-$ID"
-WT_DIR="$REPO_ROOT/.viban/worktrees/$ID"
+WT_DIR="$PWD/.viban/worktrees/$ID"
 ```
 
-If worktree does not exist:
+If worktree exists, detach it to free the branch:
 
 ```bash
-[ ! -d "$WT_DIR" ]
+[ -d "$WT_DIR" ] && git -C "$WT_DIR" checkout --detach 2>/dev/null
 ```
 
-Tell the user "No worktree found for #$ID. Cannot review." and exit.
+---
+
+## Step 3: Handle Dirty Working Tree
+
+```bash
+git status --porcelain
+```
+
+If dirty, ask user with AskUserQuestion:
+- "You have uncommitted changes. How should we save them?"
+- Options:
+  - "Stash" → `git stash push -m "viban-review: before #$ID"`
+  - "Temp commit" → `git add -A && git commit -m "viban-review: temp commit before #$ID"`
+
+If clean, proceed directly.
 
 ---
 
-## Step 3: Soft-Reset for IDE Review
+## Step 4: Detached Checkout and Reset
 
 ```bash
-git -C "$WT_DIR" reset --soft main
+git checkout --detach "$BRANCH"
+git reset --soft main
 ```
 
-Now all changes from the issue branch appear as **staged diffs** when the worktree directory is opened in the IDE.
+This checks out the branch's commit without moving the branch pointer. Now all changes appear as **staged diffs** in the IDE, and the `$BRANCH` ref stays intact.
 
 ---
 
-## Step 4: Report and Exit
+## Step 5: Report and Exit
 
 ```bash
 PR_INFO=$(gh pr list --head "$BRANCH" --json number,url --jq '.[0]' 2>/dev/null)
@@ -77,9 +91,16 @@ PR_INFO=$(gh pr list --head "$BRANCH" --json number,url --jq '.[0]' 2>/dev/null)
 Tell the user:
 
 ```
-Reviewing #$ID — open $WT_DIR in your IDE to see staged diffs.
+Reviewing #$ID — all changes are staged in your IDE.
 {PR #N: <url> if PR exists}
 Run /viban:approve $ID or /viban:reject $ID when ready.
 ```
 
 **Done.** Do not wait for user input. The skill exits here.
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `viban list --status review` | List review-status issues |
+| `viban get <id>` | View issue details |

package/skills/setup/SKILL.md

@@ -445,6 +445,15 @@ You can edit .viban/workflow.md anytime to adjust it.
 - **Package manager not found**: Show manual installation instructions
 - **npm not found**: Install Node.js first
 
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `viban help` | Show help and verify installation |
+| `viban add "<title>"` | Add a task |
+| `viban list` | List all tasks |
+| `viban sync` | Initialize external tracker sync |
+
 ## Notes
 
 - This command requires terminal access to run shell commands