claude-plugin-viban 1.1.2 → 1.2.0

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/setup/SKILL.md

@@ -94,13 +94,21 @@ sudo dnf install -y gum
 sudo pacman -S --noconfirm zsh jq gum
 ```
 
-### Step 4: Install or Update viban CLI
+### Step 4: Install or Update viban CLI + Auto-detect (Parallel)
+
+Run dependency installation in the **background** while auto-detecting project configuration **in parallel**:
+
+**Background task (install):**
 
 ```bash
 npm install -g claude-plugin-viban@latest
 ```
 
-This installs viban if not present, or updates to the latest version if already installed.
+**Parallel task (auto-detect) — run simultaneously:**
+
+Jump to Step 7 (Auto-detect Project Configuration) and start gathering project context while installation proceeds.
+
+Wait for both tasks to complete before continuing to Step 5.
 
 ### Step 5: Verify Installation
 
@@ -128,21 +136,25 @@ You can now use:
   viban list         List all tasks
   /viban:assign      Auto-resolve next issue
   /viban:add         Create structured issue
+
+Tip: Use /viban:sync to integrate with GitHub Issues.
+     Run it anytime to set up two-way sync.
 ```
 
 ### Step 6: Workflow Setup Introduction
 
-After dependencies are installed, explain to the user:
+After dependencies are installed and auto-detection is complete, explain to the user:
 
 ```
 ╭──────────────────────────────────────────────────╮
-│         Workflow Setup (Optional)                 │
+│         Workflow Setup (Optional)                │
 ╰──────────────────────────────────────────────────╯
 
 /viban:assign uses your project's .viban/workflow.md
 as the TOP PRIORITY when resolving issues.
 
-Without a workflow, a default 4-step process is used.
+Without a workflow, a default process is used:
+analyze → implement → verify → ship.
 Let's set up a custom workflow for this project now.
 ```
 
@@ -194,10 +206,9 @@ Ask only what the agent **cannot infer on its own**. One AskUserQuestion call, 3
 - header: "Pipeline"
 - question: "After `/viban:assign`, how far should the agent go?"
 - options:
-  - "Full auto — analyze → implement → commit → PR → review"
-  - "Stop before PR — I'll review the diff then create PR myself"
-  - "Stop before commit — I'll review the code before anything ships"
-  - "Plan only — analyze and propose a plan, I'll implement"
+  - "Full auto — analyze → implement → commit → PR (review in PR)"
+  - "Stop before PR — I'll review the diff first (review in terminal/IDE)"
+  - "Stop before commit — I'll review the code first (review in terminal/IDE)"
 - multiSelect: false
 
 **Q2. Issue Numbering**
@@ -205,17 +216,32 @@ Ask only what the agent **cannot infer on its own**. One AskUserQuestion call, 3
 - question: "How should issues be numbered when using `/viban:add`?"
 - options:
   - "Auto — viban auto-assigns #1, #2, #3..."
+  - "Sync with provider — use `/viban:sync` to import from GitHub, Jira, Linear, etc."
   - "Manual — ask for an external ID each time (e.g. PROJ-42, JIRA-123)"
 - multiSelect: false
+- If user selects "Sync with provider", run `/viban:sync` to initialize sync after workflow setup completes.
 
 **Q3. Extra Rules**
+
+Before asking, show the user what was auto-detected from Step 7:
+
+```
+Detected conventions:
+  Commit style:  {e.g. "feat: ...", "fix: ..." (Conventional Commits)}
+  Branch naming: {e.g. "feat/*", "fix/*"}
+  Build command: {e.g. "npm run build && npm test"}
+  Project type:  {e.g. "CLI tool (zsh)"}
+```
+
+Then ask:
+
 - header: "Rules"
-- question: "Any additional rules the agent should follow? (e.g. commit conventions, language, CHANGELOG)"
+- question: "Anything to change or add to the detected conventions above?"
 - options:
-  - "No, auto-detect everything"
-  - "Let me describe"
+  - "Looks good, use as-is"
+  - "Let me adjust"
 - multiSelect: false
-- If user selects "Let me describe", collect free-text.
+- If user selects "Let me adjust", collect free-text.
 
 **Defaults for everything else (do NOT ask):**
 
@@ -280,8 +306,8 @@ Combine **auto-detected values** (Step 7) with **interview answers** (Step 8) to
 | Extra rules | Q3 | User-typed rules or "None" |
 
 **Workflow generation principles:**
-- **Q1 (Pipeline) determines the entire automation structure** — which phases run automatically, where to stop, and whether to create PRs. "Full auto" = no stops + auto PR. "Stop before PR" = auto commit + user creates PR. "Stop before commit" = implement only + user reviews. "Plan only" = analyze only.
-- **Q2 (Issue numbering) determines how `/viban:add` handles IDs.** "Auto" = viban auto-assigns `#1`, `#2`. "Manual" = agent asks for an external ID each time and passes `--ext-id` to `viban add`. When manual, commits/PRs reference the external ID instead of `#N`.
+- **Q1 (Pipeline) determines the entire automation structure** — which phases run automatically, where to stop, and whether to create PRs. "Full auto" = no stops + auto PR. "Stop before PR" = auto commit + user creates PR. "Stop before commit" = implement only + user reviews.
+- **Q2 (Issue numbering) determines how `/viban:add` handles IDs.** "Auto" = viban auto-assigns `#1`, `#2`. "Sync with provider" = use `/viban:sync` to import/sync issues from GitHub, Jira, Linear, etc. "Manual" = agent asks for an external ID each time and passes `--ext-id` to `viban add`. When manual, commits/PRs reference the external ID instead of `#N`.
 - **Q3 (Extra rules) is appended verbatim to the Additional Rules section.** If user mentions conventions, evidence, CHANGELOG, language, etc., incorporate into the relevant phase.
 - **Commit/PR conventions are auto-detected from git history** (Step 7.2). If the user overrides via Q3, use the user's preference instead.
 - **Everything else uses smart defaults.** Analysis depth, implementation approach, quality gates, verification methods, issue numbering, post-merge — all auto-determined by the agent or set to sensible defaults.
@@ -301,7 +327,6 @@ Combine **auto-detected values** (Step 7) with **interview answers** (Step 8) to
 {- "Full auto": "Analyze → Implement → Verify → Build → Commit → PR → Review (fully autonomous)"}
 {- "Stop before PR": "Analyze → Implement → Verify → Build → Commit → STOP (user creates PR)"}
 {- "Stop before commit": "Analyze → Implement → STOP (user reviews code, then commits)"}
-{- "Plan only": "Analyze → STOP (user decides next steps)"}
 
 ---
 
@@ -319,9 +344,6 @@ The agent determines analysis depth based on issue priority and complexity.
 - [ ] Root cause identified (or hypothesis formed)
 - [ ] Scope of change estimated
 
-{IF Q1 is "Plan only":}
-### >>> STOP: Present analysis and proposed plan to user. Wait for approval.
-
 ---
 
 ## Phase 2: Implement
@@ -377,7 +399,7 @@ If build/test fails: fix errors, return to Phase 3.
 {FROM Q1:}
 {- "Full auto": create PR with body template, move issue to review via `viban review {id}`}
 {- "Stop before PR": commit and push only, notify user that PR is pending. Run `viban review {id}`.}
-{- "Stop before commit" / "Plan only": N/A — agent already stopped earlier}
+{- "Stop before commit": N/A — agent already stopped earlier}
 
 ### PR Body Template
 {AUTO_DETECTED from git history convention. If Q3 overrides, use that instead.}
@@ -391,7 +413,7 @@ If build/test fails: fix errors, return to Phase 3.
 
 ## Issue Management
 
-- Issue numbering: {FROM Q2: "Auto" = auto-increment (viban default), "Manual" = ask for external ID via `--ext-id` flag}
+- Issue numbering: {FROM Q2: "Auto" = auto-increment (viban default), "Sync with provider" = use `/viban:sync` for external tracker integration, "Manual" = ask for external ID via `--ext-id` flag}
 - Test evidence: include test output in PR body
 - Post-merge: auto-close issue (`viban done {id}`), delete branch
 

package/skills/sync/SKILL.md

@@ -17,7 +17,7 @@ Sync the viban board with an external issue tracker. Currently supports GitHub I
 
 ```bash
 # Check if sync is already configured
-if [ -f "$(git rev-parse --git-common-dir 2>/dev/null || echo .viban)/sync.json" ]; then
+if [ -f ".viban/sync.json" ]; then
     echo "Sync configured"
     viban sync --status
 else