claude-plugin-viban 1.1.2 → 1.2.1

package/skills/assign/SKILL.md

@@ -5,71 +5,64 @@ description: "Assign and resolve first backlog issue from viban board through to
 
 # /assign
 
-Workflow: First backlog issue -> Resolve -> PR completion
+First backlog issue → Resolve → PR completion
 
-> **No direct `viban.json` access** - CLI only
-> **No Worktree** - Work directly on branch in main repo
-> **Workflow**: Read `.viban/workflow.md` first, then CLAUDE.md fallback
+> **CLI only** (no direct viban.json access) | **No worktree** (branch in main repo)
 
 ---
 
-## Phase 0: CONTEXT & SETUP
+## Phase 0: SETUP
 
-### 0.1 Read Project Workflow (CRITICAL)
+### 0.1 Read Workflow (CRITICAL)
 
-Before any work, read the project's workflow configuration. Check in priority order:
-
-**Priority 1: `.viban/workflow.md`** (dedicated workflow file)
-
-```bash
-[ -f ".viban/workflow.md" ] && cat ".viban/workflow.md"
-```
-
-**Priority 2: CLAUDE.md** (legacy fallback)
-
-Only if `.viban/workflow.md` does NOT exist:
+Check in priority order — first match wins, follow it exactly:
 
+1. `.viban/workflow.md` → `[ -f ".viban/workflow.md" ] && cat ".viban/workflow.md"`
+2. CLAUDE.md (legacy, only if no workflow.md):
 ```bash
 for path in "./CLAUDE.md" "./.claude/CLAUDE.md" "../CLAUDE.md"; do
     [ -f "$path" ] && cat "$path"
 done
 ```
+Look for `Issue Resolution Workflow` or `Workflow` section.
+3. Default workflow (Phase 1 below)
 
-Look for: `Issue Resolution Workflow` or `Workflow` section.
+### 0.2 Git Setup & Assign
 
-**Priority 3: Default workflow** (Phase 1 below)
+```bash
+# Check uncommitted changes → AskUserQuestion if dirty
+[ -n "$(git status --porcelain)" ] && echo "Warning: Uncommitted changes"
 
-IMPORTANT:
-- If `.viban/workflow.md` exists -> MUST follow it exactly (all phases)
-- Else if CLAUDE.md has a workflow section -> MUST follow it exactly
-- If no workflow found -> Use default workflow (Phase 1 below)
+git checkout main && git fetch origin main && git reset --hard origin/main
 
-### 0.2 Git Setup
+ISSUE_ID=$(viban assign 2>&1 | tail -1)
+[[ -z "$ISSUE_ID" || "$ISSUE_ID" == "No backlog" ]] && echo "No issues in backlog" && exit 0
+```
+
+### 0.3 Detect Sync & Create Branch
 
 ```bash
-# 1. Check for uncommitted changes
-if [ -n "$(git status --porcelain)" ]; then
-    echo "Warning: Uncommitted changes detected"
-    # Ask user whether to commit (use AskUserQuestion)
+ISSUE_JSON=$(viban get $ISSUE_ID)
+EXT_ID=$(echo "$ISSUE_JSON" | jq -r '.external_id // ""')
+SYNC_ACTIVE=false; EXTERNAL_NUM=""
+
+if [ -n "$EXT_ID" ] && [ "$EXT_ID" != "null" ]; then
+    SYNC_ACTIVE=true
+    EXTERNAL_NUM="${EXT_ID##*:}"  # "github:42" -> "42"
+    TITLE=$(echo "$ISSUE_JSON" | jq -r '.title' | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | head -c 40)
+    git checkout -b "issue-${EXTERNAL_NUM}-${TITLE}"
+else
+    git checkout -b issue-$ISSUE_ID
 fi
+```
 
-# 2. Switch to main branch and sync
-git checkout main
-git fetch origin main
-git reset --hard origin/main
-
-# 3. Assign issue
-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
+### 0.4 Load Plan (if available)
 
-# 4. Create new branch
-git checkout -b viban-$ISSUE_ID
+```bash
+[ -f ".viban/plans/${ISSUE_ID}.md" ] && cat ".viban/plans/${ISSUE_ID}.md"
 ```
 
-If backlog is empty: Notify user and exit
+If plan exists: use as primary guide for Phase 1, skip redundant analysis, but verify plan is still current.
 
 ---
 
@@ -79,102 +72,105 @@ If backlog is empty: Notify user and exit
 viban get $ISSUE_ID
 ```
 
-### If Project Workflow Exists (from `.viban/workflow.md` or CLAUDE.md):
-
-Follow the project's exact steps.
-
-### 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
+**With project workflow**: follow its exact steps.
+**Default** (no workflow): Understand → Locate → Analyze root cause → Implement minimal changes.
 
 ---
 
 ## Phase 2: VERIFY
 
-Manual verification using available tools. Do NOT run build/test here - save that for Phase 3.
-
-### Verification Methods (use what's appropriate):
+Manual verification — do NOT run build/test here (Phase 3).
 
-| Type | Tool | Usage |
-|------|------|-------|
-| Web UI | Playwright MCP | `browser_navigate`, `browser_snapshot`, `browser_click` |
-| API | WebFetch | Fetch endpoints, check responses |
-| CLI | Bash | Run the CLI command, check output |
-| Visual | Read | Read screenshot files if provided |
-| Browser | Chrome DevTools MCP | `take_snapshot`, `navigate_page`, `click` |
+| Type | Tool |
+|------|------|
+| Web UI | Playwright MCP (`browser_navigate`, `browser_snapshot`, `browser_click`) |
+| API | WebFetch |
+| CLI | Bash |
+| Visual | Read (screenshot files) |
+| Browser | Chrome DevTools MCP |
 
-### Verification Steps:
+Steps: identify what proves the fix → execute → confirm behavior → document evidence.
 
-1. **Identify verification target**: What proves this fix works?
-2. **Execute verification**: Use appropriate tool from above
-3. **Confirm result**: Does the actual behavior match expected?
-4. **Document evidence**: Note what was verified and how
+Examples:
+- Web feature: navigate to page, take snapshot, verify element exists
+- API fix: fetch endpoint, check response status and body
+- CLI change: run command, verify output format
+- UI bug: navigate, interact, confirm no error
 
-Example verifications:
-- Web feature: Navigate to page, take snapshot, verify element exists
-- API fix: Fetch endpoint, check response status and body
-- CLI change: Run command, verify output format
-- UI bug: Navigate, interact, confirm no error
-
-If verification fails: Return to Phase 1, fix the issue, re-verify.
+If verification fails: return to Phase 1.
 
 ---
 
 ## Phase 3: SHIP
 
-### 3.1 Run Build & Tests
+### 3.1 Build & Test
 
-```bash
-# Run project's build/test commands
-# Example: npm run build && npm test
-# Example: pytest
-# Example: cargo build && cargo test
-```
-
-If build/test fails: Fix errors, return to Phase 2 for re-verification.
+Run project's build/test commands. If fail: fix → return to Phase 2.
 
 ### 3.2 Rebase
 
 ```bash
-git fetch origin main
-git rebase origin/main
+git fetch origin main && git rebase origin/main
 # On conflict: resolve -> git add -> git rebase --continue
 ```
 
 ### 3.3 Commit & Push
 
 ```bash
+BRANCH=$(git branch --show-current)
 git add -A
-git commit -m "fix: issue title summary
+
+# Sync mode: "Closes #NUM" | Default: "Resolves: viban-ID"
+if [ "$SYNC_ACTIVE" = true ]; then
+    git commit -m "fix: issue title summary
+
+- Root cause: ...
+- Solution: ...
+
+Closes #$EXTERNAL_NUM"
+else
+    git commit -m "fix: issue title summary
 
 - Root cause: ...
 - Solution: ...
 
-Resolves: viban-$ISSUE_ID"
+Resolves: #$ISSUE_ID"
+fi
 
-git push -u origin viban-$ISSUE_ID
+git push -u origin "$BRANCH"
 ```
 
 ### 3.4 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
+EXISTING_PR=$(gh pr list --head "$BRANCH" --json number -q '.[0].number')
+
+if [ -z "$EXISTING_PR" ]; then
+    if [ "$SYNC_ACTIVE" = true ]; then
+        gh pr create --title "fix: title" \
+            --body "## Changes
+- ...
+
+Closes #$EXTERNAL_NUM
+
+## Verification
+- [ ] Manual verification completed
+- [ ] Build passing
+- [ ] Tests passing (if applicable)" --base main
+    else
+        gh pr create --title "fix: title" \
+            --body "## Changes
 - ...
 
 ## Verification
 - [ ] Manual verification completed
 - [ ] Build passing
-- [ ] Tests passing (if applicable)" \
-    --base main
+- [ ] Tests passing (if applicable)" --base main
+    fi
+fi
 ```
 
-### 3.5 Issue -> review
+### 3.5 Move to Review
 
 ```bash
 viban review $ISSUE_ID
@@ -185,18 +181,9 @@ viban review $ISSUE_ID
 ## Phase 4: HANDOFF
 
 ```
-Human Review Required
-
-Issue #$ISSUE_ID -> review status
-
-PR: gh pr view viban-$ISSUE_ID --web
-
-Verification complete:
-   - Manual verification done with available tools
-   - Build passing
-   - Project workflow followed
-
-After approval: Delete issue from viban TUI
+Issue #$ISSUE_ID → review | PR: gh pr view --web
+Verification: manual + build + workflow followed
+After approval: delete issue from viban TUI
 ```
 
 ---
@@ -205,7 +192,7 @@ After approval: Delete issue from viban TUI
 
 ```
 [ ] Read .viban/workflow.md (or CLAUDE.md fallback) for project workflow
-[ ] Working on viban-$ISSUE_ID branch
+[ ] Working on issue-$ISSUE_ID branch
 [ ] Implementation complete
 [ ] Manual verification passed (using appropriate tools)
 [ ] Build & tests passing
@@ -218,13 +205,7 @@ After approval: Delete issue from viban TUI
 
 ## CRITICAL: Status Transition Rule
 
-> **NEVER end this skill with the issue still in `in_progress`.**
->
-> Before exiting — whether you completed all phases or stopped early due to errors:
-> ```bash
-> viban review $ISSUE_ID
-> ```
-> This is MANDATORY. If you skip this, the board becomes stale and misleading.
+> **NEVER exit with issue still in `in_progress`.** Always run `viban review $ISSUE_ID` before exiting — whether completed or stopped early.
 
 ## CLI Reference
 

package/skills/parallel-assign/SKILL.md

@@ -0,0 +1,297 @@
+---
+name: parallel-assign
+description: "Assign and resolve multiple independent backlog issues in parallel using git worktrees and coordinated agents"
+---
+
+# /parallel-assign
+
+Parallel resolution of independent backlog issues via git worktrees.
+
+> **CLI only** (no direct viban.json access) | **Opus sub-agents** in isolated worktrees
+
+**Input**: `$ARGUMENTS` (optional: number of issues, default 3)
+
+---
+
+## Phase 0: SETUP
+
+### 0.1 Read Workflow
+
+```bash
+[ -f ".viban/workflow.md" ] && cat ".viban/workflow.md"
+```
+
+Fallback to CLAUDE.md, then default. Same as `/viban:assign` Phase 0.1.
+
+### 0.2 Parse Arguments
+
+Extract count from `$ARGUMENTS`:
+- Number provided (e.g. `/viban:parallel-assign 5`) → use that number
+- No number → default to 3
+- Maximum: 5
+
+### 0.3 Check Backlog & Git State
+
+```bash
+viban list
+```
+
+Count available backlog issues. Adjust N down if fewer available.
+If backlog is empty: notify user and exit.
+
+```bash
+[ -n "$(git status --porcelain)" ] && echo "Warning: Uncommitted changes"
+git checkout main && git fetch origin main && git reset --hard origin/main
+```
+
+### 0.4 Assign Issues
+
+Assign N issues, each with a unique session ID. Determine branch names per workflow convention:
+
+```bash
+ISSUES=()  # Array of "ID|BRANCH" pairs
+for i in $(seq 1 $N); do
+    SESSION=$(echo "${RANDOM}${i}" | md5 | head -c 8)
+    ID=$(viban assign "$SESSION" 2>&1 | tail -1)
+    [[ -z "$ID" || "$ID" == "No backlog" ]] && break
+
+    # Determine branch name (same logic as /viban:assign Phase 0.3)
+    ISSUE_JSON=$(viban get "$ID")
+    EXT_ID=$(echo "$ISSUE_JSON" | jq -r '.external_id // ""')
+    if [ -n "$EXT_ID" ] && [ "$EXT_ID" != "null" ]; then
+        EXTERNAL_NUM="${EXT_ID##*:}"
+        TITLE=$(echo "$ISSUE_JSON" | jq -r '.title' | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | head -c 40)
+        BRANCH="issue-${EXTERNAL_NUM}-${TITLE}"
+    else
+        BRANCH="issue-${ID}"
+    fi
+
+    ISSUES+=("${ID}|${BRANCH}")
+done
+```
+
+If no issues were assigned: notify user and exit.
+
+### 0.5 Create Worktrees
+
+For each assigned issue, create an isolated git worktree:
+
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel)
+mkdir -p "$REPO_ROOT/.viban/worktrees"
+
+for entry in "${ISSUES[@]}"; do
+    ID="${entry%%|*}"
+    BRANCH="${entry##*|}"
+    WT_DIR="$REPO_ROOT/.viban/worktrees/$BRANCH"
+
+    git worktree add -b "$BRANCH" "$WT_DIR" origin/main
+done
+```
+
+### 0.6 Sync Status
+
+```bash
+viban sync --push-only
+```
+
+---
+
+## Phase 1: DISPATCH PARALLEL AGENTS
+
+Spawn one **opus** agent per issue using `Task` tool. All agents launch in a single message with `run_in_background: true`.
+
+**Agent prompt template** (per issue):
+
+```
+You are resolving viban issue #{ID} in an isolated git worktree.
+
+## Environment
+- Worktree path: {REPO_ROOT}/.viban/worktrees/{BRANCH}
+- Branch: {BRANCH}
+- Main repo: {REPO_ROOT}
+- ALL file operations must happen inside the worktree path
+
+## Workflow
+{paste workflow.md content}
+
+## Issue Details
+{paste viban get output}
+
+## Plan (if available)
+{paste .viban/plans/{ID}.md content, or "No plan available"}
+
+## Instructions
+
+You are one of {N} parallel agents working in isolated git worktrees.
+
+1. Work ONLY inside your worktree: {REPO_ROOT}/.viban/worktrees/{BRANCH}
+   - cd to the worktree before any work
+   - All reads, edits, and writes must target files under this path
+
+2. Follow the project workflow phases:
+   - Analyze: understand the issue, locate code, identify root cause
+   - Implement: make focused changes following project conventions
+   - Verify: manual verification of the fix
+
+3. After implementation, commit on your branch:
+   ```bash
+   cd {REPO_ROOT}/.viban/worktrees/{BRANCH}
+   git add <specific files>
+   git commit -m "type: description
+
+   - Root cause: ...
+   - Solution: ...
+
+   Resolves: #{ID}"
+   ```
+
+4. Push and create PR:
+   ```bash
+   git push -u origin {BRANCH}
+   gh pr create --title "type: title" --body "..." --base main
+   ```
+
+5. Move issue to review:
+   ```bash
+   cd {REPO_ROOT}
+   viban review {ID}
+   ```
+
+CRITICAL:
+- Always run `viban review {ID}` before finishing, even on errors.
+- Do NOT run the full test suite — the coordinator handles that.
+- Do NOT remove the worktree — the coordinator handles cleanup.
+```
+
+### Dispatch Pattern
+
+```python
+# Pseudo-code for the dispatch
+for each (ID, BRANCH) in ISSUES:
+    Task(
+        subagent_type="general-purpose",
+        model="opus",
+        run_in_background=True,
+        prompt=filled_template(ID, BRANCH, workflow, issue_json, plan)
+    )
+```
+
+---
+
+## Phase 2: MONITOR & COLLECT
+
+1. Wait for all background agents to complete (poll via `TaskOutput`)
+2. Collect results — note successes and failures
+3. For any issue where `viban review` was not called, run it now as safety net:
+   ```bash
+   viban review $ID
+   ```
+
+---
+
+## Phase 3: TRANSPLANT & CLEANUP
+
+After all agents finish, for each issue:
+
+### 3.1 Verify Local Branches
+
+The local branch already exists (created by `git worktree add -b`). After worktree removal, the branch and its commits remain in the local repo.
+
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel)
+cd "$REPO_ROOT"
+
+for entry in "${ISSUES[@]}"; do
+    BRANCH="${entry##*|}"
+    git log --oneline -3 "$BRANCH"
+done
+```
+
+### 3.2 Remove Worktrees
+
+PRs have been created — worktrees are no longer needed:
+
+```bash
+for entry in "${ISSUES[@]}"; do
+    BRANCH="${entry##*|}"
+    WT_DIR="$REPO_ROOT/.viban/worktrees/$BRANCH"
+    git worktree remove "$WT_DIR" --force
+done
+```
+
+### 3.3 Verify PRs Exist
+
+```bash
+for entry in "${ISSUES[@]}"; do
+    BRANCH="${entry##*|}"
+    gh pr list --head "$BRANCH" --json number,title,url -q '.[0]'
+done
+```
+
+---
+
+## Phase 4: TEST & REPORT
+
+### 4.1 Run Tests
+
+Run the full test suite once on main (not per-agent):
+
+```bash
+zsh tests/run_all.zsh
+```
+
+If tests fail: identify which agent's changes caused the failure and report.
+
+### 4.2 Sync
+
+```bash
+viban sync --push-only
+```
+
+### 4.3 Report
+
+```
+Parallel Resolution Complete
+
+| Issue | Title | Branch | PR | Status |
+|-------|-------|--------|----|--------|
+| #ID   | ...   | ...    | #N | review |
+
+Total: N issues processed
+  Succeeded: X
+  Failed: Y
+
+Local branches available:
+  - {BRANCH_1}
+  - {BRANCH_2}
+  ...
+
+Worktrees cleaned up. All PRs ready for human review.
+```
+
+---
+
+## Error Handling
+
+- **Agent fails mid-work**: coordinator calls `viban review {ID}` as safety net
+- **Worktree creation fails**: skip that issue, log error, continue with others
+- **PR creation fails in agent**: coordinator reports it; local branch still available for manual PR
+- **Test failures**: report which branch likely caused the failure
+
+---
+
+## CRITICAL RULES
+
+> 1. **NEVER exit with any issue still in `in_progress`.** For every assigned issue, ensure `viban review {ID}` has been called.
+> 2. **ALWAYS clean up worktrees** after PRs are created. Worktree dirs must not linger in `.viban/worktrees/`.
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `viban list` | Print board |
+| `viban assign [session]` | Assign issue |
+| `viban get <id>` | View issue |
+| `viban review <id>` | Move to review |
+| `viban sync --push-only` | Sync to GitHub |