claude-plugin-viban 1.0.36 → 1.0.37

package/.claude-plugin/plugin.json

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

package/bin/viban

@@ -354,6 +354,12 @@ init_json() {
 
 get_next_id() { jq -r '.next_id // (([.issues[].id] | max // 0) + 1)' "$VIBAN_JSON"; }
 
+# Display ID: show external_id if present, otherwise #id
+display_id() { local id="$1" ext_id="${2:-}"; [[ -n "$ext_id" && "$ext_id" != "null" ]] && echo "$ext_id" || echo "#$id"; }
+
+# Get external_id for an issue by internal id
+get_ext_id() { jq -r --argjson id "$1" '.issues[]|select((.id|tonumber)==$id)|.external_id//""' "$VIBAN_JSON"; }
+
 # Calculate effective order for sorting (priority-based virtual order for cards without order)
 # Used internally for fractional indexing calculations
 # Cards with order: use actual order
@@ -403,7 +409,7 @@ add_issue() {
         local today=$(date +"%Y-%m-%d")
         cat > "$tmpfile" <<TEMPLATE
 # ─────────────────────────────────────────────
-# VIBAN Issue #$next_id
+# VIBAN Issue #${next_id}
 # ─────────────────────────────────────────────
 # Title: $title
 # Priority: $priority
@@ -597,10 +603,13 @@ build_column_lines() {
     [[ "$st" == "review" ]] && sort_expr='sort_by(.updated_at) | reverse'
     local issues_data=$(printf '%s' "$json_data" | jq -r --arg s "$st" "
         .issues | map(select(.status==\$s)) | $sort_expr |
-        .[] | \"\\(.id)\t\\(.title)\t\\((.description // \"\") | gsub(\"[\\n\\t\\r]\"; \" \"))\t\\(.priority // \"P3\")\t\\(.type // \"\")\"")
+        .[] | \"\\(.id)\t\\(.title)\t\\((.description // \"\") | gsub(\"[\\n\\t\\r]\"; \" \"))\t\\(.priority // \"P3\")\t\\(.type // \"\")\t\\(.external_id // \"\")\"")
     local count=0
-    # Count lines without subprocess using zsh array splitting
-    [[ -n "$issues_data" ]] && count=${#${(f)issues_data}}
+    # Count total issues (not capped) for overflow indicator
+    if [[ -n "$issues_data" ]]; then
+        local -a _count_arr=("${(f)issues_data}")
+        count=${#_count_arr[@]}
+    fi
 
     # Header centered in column
     local hdr_text="● $label"
@@ -623,14 +632,14 @@ build_column_lines() {
     local border=$(gen_border $card_inner)
 
     # --- Pass 1: Collect card data into arrays ---
-    local -a _ids _titles _descs _priorities _types _title_max_ws _title_pfxs
+    local -a _ids _titles _descs _priorities _types _ext_ids _title_max_ws _title_pfxs
     local _has_nonascii=0
     local _desc_max_w=$((card_inner - 4))
     local _spinner_w=0
     [[ "$st" == "in_progress" ]] && _spinner_w=2
     local _cc _bc _pfx
 
-    while IFS=$'\t' read -r _id _title _desc _priority _type; do
+    while IFS=$'\t' read -r _id _title _desc _priority _type _ext_id; do
         [[ -z "$_id" ]] && continue
         (( ${#_ids} >= CACHED_MAX_TASKS )) && break
         [[ -z "$_priority" || "$_priority" == "null" ]] && _priority="P3"
@@ -638,14 +647,15 @@ build_column_lines() {
         [[ "$_desc" == "null" ]] && _desc=""
 
         _ids+=("$_id"); _titles+=("$_title"); _descs+=("$_desc")
-        _priorities+=("$_priority"); _types+=("$_type")
+        _priorities+=("$_priority"); _types+=("$_type"); _ext_ids+=("$_ext_id")
 
-        # Per-card title width limit
-        _title_max_ws+=($((card_inner - 4 - ${#_id} - _spinner_w - 1)))
+        # Per-card title width limit (use display ID length)
+        local _did; _did=$(display_id "$_id" "$_ext_id")
+        _title_max_ws+=($((card_inner - 4 - ${#_did} - _spinner_w)))
         # Prefix for width calc (X as spinner placeholder - same width 1 as braille chars)
         _pfx="  "
         (( _spinner_w )) && _pfx="  X "
-        _title_pfxs+=("${_pfx}#${_id} ")
+        _title_pfxs+=("${_pfx}${_did} ")
 
         # Check for non-ASCII
         if (( ! _has_nonascii )); then
@@ -711,11 +721,13 @@ build_column_lines() {
         local id="${_ids[$_i]}"
         local priority="${_priorities[$_i]}"
         local issue_type="${_types[$_i]}"
+        local ext_id="${_ext_ids[$_i]}"
+        local did; did=$(display_id "$id" "$ext_id")
 
         # Title line
         local spinner_prefix=""
         [[ "$st" == "in_progress" ]] && spinner_prefix="${SPINNER_FRAMES[$((SPINNER_IDX % ${#SPINNER_FRAMES[@]} + 1))]} "
-        local title_content="  ${spinner_prefix}#${id} ${_short_titles[$_i]}"
+        local title_content="  ${spinner_prefix}${did} ${_short_titles[$_i]}"
         local title_pad=$((card_inner - ${_title_cws[$_i]}))
         (( title_pad < 0 )) && title_pad=0
 
@@ -1158,7 +1170,7 @@ level1_columns() {
                         stty echo 2>/dev/null
                         # Clear footer line and show confirm
                         printf '\033[%d;1H\033[K' "$CACHED_TERM_H"
-                        if gum confirm "Delete #$id?" --affirmative "Yes" --negative "No" \
+                        if gum confirm "Delete $(display_id "$id" "$(get_ext_id "$id")")?" --affirmative "Yes" --negative "No" \
                             --selected.foreground="#000000" --selected.background "${C[accent]}"; then
                             delete_issue "$id"
                             (( card > 0 )) && card=$((card - 1))
@@ -1193,13 +1205,15 @@ edit_issue() {
     local created=$(printf '%s' "$issue" | jq -r '.created_at')
     local priority=$(printf '%s' "$issue" | jq -r '.priority // "P3"')
     local issue_type=$(printf '%s' "$issue" | jq -r '.type // ""')
+    local ext_id=$(printf '%s' "$issue" | jq -r '.external_id // ""')
+    local did; did=$(display_id "$id" "$ext_id")
 
     local tmpfile=$(mktemp)
     local editor="${EDITOR:-${VISUAL:-vim}}"
 
     cat > "$tmpfile" <<TEMPLATE
 # ─────────────────────────────────────────────
-# VIBAN Issue #$id
+# VIBAN Issue $did
 # ─────────────────────────────────────────────
 # Status: ${STATUS_LABEL[$ist]}
 # Created: ${created:0:10}
@@ -1310,7 +1324,7 @@ cmd_list() {
     echo ""
     for st in $VIBAN_STATUSES; do
         gum style --foreground "${STATUS_COLOR[$st]}" --bold "● ${STATUS_LABEL[$st]} ($(count_issues_by_status "$st"))"
-        get_issues_by_status "$st" | jq -r '.[]|"  #\(.id) [\(.priority // "P3")]\(if .type then " [\(.type | ascii_upcase)]" else "" end) \(.title)"'
+        get_issues_by_status "$st" | jq -r '.[]|"  \(if .external_id then .external_id else "#\(.id)" end) [\(.priority // "P3")]\(if .type then " [\(.type | ascii_upcase)]" else "" end) \(.title)"'
         echo ""
     done
 }
@@ -1336,15 +1350,15 @@ cmd_priority() {
         '(.issues[]|select((.id|tonumber)==$id)) |= . + {priority:$priority,updated_at:$now}' \
         "$VIBAN_JSON" > "$VIBAN_JSON.tmp" && mv "$VIBAN_JSON.tmp" "$VIBAN_JSON"
 
-    echo "✓ #$id priority → $new_priority"
+    echo "✓ $(display_id "$id" "$(get_ext_id "$id")") priority → $new_priority"
 }
 
 cmd_add() {
     init_json
     [[ -z "$1" ]] && { echo "Usage: viban add \"title\" [\"description\"] [priority] [type] [attachments...]"; exit 1; }
 
-    # Support both positional and named args (--title, --description, --priority, --type)
-    local title="" desc="" priority="P3" issue_type=""
+    # Support both positional and named args (--title, --description, --priority, --type, --ext-id)
+    local title="" desc="" priority="P3" issue_type="" ext_id=""
     local -a attachments=()
     local positional=()
 
@@ -1355,6 +1369,7 @@ cmd_add() {
             --desc-file) [[ -f "$2" ]] && desc="$(cat "$2")"; shift 2 ;;
             --priority)  priority="$2"; shift 2 ;;
             --type)      issue_type="$2"; shift 2 ;;
+            --ext-id|--external-id) ext_id="$2"; shift 2 ;;
             --attach|--attachments) shift; while [[ $# -gt 0 && "$1" != --* ]]; do attachments+=("$1"); shift; done ;;
             --*)         shift 2 2>/dev/null || shift ;; # skip unknown flags
             *)           positional+=("$1"); shift ;;
@@ -1386,7 +1401,7 @@ cmd_add() {
     # Order is only assigned when manually moved
     local tmpjson=$(mktemp)
     printf '%s' "$desc" > "$tmpjson"
-    jq --arg id "$id" --arg title "$title" --rawfile desc "$tmpjson" --arg priority "$priority" --arg issue_type "$issue_type" --argjson attachments "$attachments_json" --arg now "$now" '
+    jq --arg id "$id" --arg title "$title" --rawfile desc "$tmpjson" --arg priority "$priority" --arg issue_type "$issue_type" --arg ext_id "$ext_id" --argjson attachments "$attachments_json" --arg now "$now" '
         .next_id = ((.next_id // 0) + 1) |
         .issues += [{
             id:($id|tonumber),
@@ -1395,6 +1410,7 @@ cmd_add() {
             status:"backlog",
             priority:$priority,
             type:(if $issue_type == "" then null else $issue_type end),
+            external_id:(if $ext_id == "" then null else $ext_id end),
             attachments:$attachments,
             assigned_to:null,
             created_at:$now,
@@ -1405,7 +1421,7 @@ cmd_add() {
     [[ -n "$issue_type" ]] && type_info=" [$issue_type]"
     local attach_info=""
     [[ ${#attachments[@]} -gt 0 ]] && attach_info=" +${#attachments[@]} files"
-    echo "✓ #$id added ($priority)$type_info$attach_info"
+    echo "✓ $(display_id "$id" "$ext_id") added ($priority)$type_info$attach_info"
 }
 
 cmd_assign() {
@@ -1414,16 +1430,18 @@ cmd_assign() {
     local issue=$(jq -r '.issues|map(select(.status=="backlog"))|sort_by(if .order != null then [0, .order] else [1, ({"P0":0,"P1":1,"P2":2,"P3":3}[.priority // "P3"] // 3), .id] end)|first' "$VIBAN_JSON")
     [[ "$issue" == "null" || -z "$issue" ]] && { echo "No backlog"; exit 1; }
     local id=$(printf '%s' "$issue" | jq -r '.id') now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    local ext_id=$(printf '%s' "$issue" | jq -r '.external_id // ""')
 
     # Update status to in_progress (no worktree - use branch workflow)
     jq --argjson id "$id" --arg s "$session" --arg now "$now" \
         '(.issues[]|select((.id|tonumber)==$id)) |= . + {status:"in_progress",assigned_to:$s,updated_at:$now}' \
         "$VIBAN_JSON" > "$VIBAN_JSON.tmp" && mv "$VIBAN_JSON.tmp" "$VIBAN_JSON"
 
-    # Set iTerm2 session name to issue number
-    printf '\033]1;#%s\007' "$id"
+    # Set iTerm2 session name to issue display ID
+    local did; did=$(display_id "$id" "$ext_id")
+    printf '\033]1;%s\007' "$did"
 
-    echo "✓ #$id assigned"
+    echo "✓ $did assigned"
     echo "$id"
 }
 
@@ -1439,7 +1457,7 @@ cmd_review() {
     # Clear iTerm2 session name
     printf '\033]1;\007'
 
-    echo "✓ #$id → review"
+    echo "✓ $(display_id "$id" "$(get_ext_id "$id")") → review"
 }
 
 cmd_done() {
@@ -1461,7 +1479,7 @@ cmd_done() {
     # Clear iTerm2 session name
     printf '\033]1;\007'
 
-    echo "✓ #$1 completed & removed"
+    echo "✓ $(display_id "$1" "$(get_ext_id "$1")") completed & removed"
 }
 
 cmd_get() { init_json; jq --argjson id "$1" '.issues[]|select((.id|tonumber)==$id)' "$VIBAN_JSON"; }
@@ -1489,7 +1507,7 @@ cmd_attach() {
         }
     ' "$VIBAN_JSON" > "$VIBAN_JSON.tmp" && mv "$VIBAN_JSON.tmp" "$VIBAN_JSON"
 
-    echo "✓ #$id: ${#files[@]} file(s) attached"
+    echo "✓ $(display_id "$id" "$(get_ext_id "$id")"): ${#files[@]} file(s) attached"
 }
 
 cmd_migrate() {

package/commands/add.md

@@ -1,257 +1,94 @@
 ---
-description: "Analyze problem and register as viban issue with evidence"
+description: "Register a problem as a viban issue"
 ---
 
-# /add - Problem Analysis and Issue Registration
+# /add - Register Issue
 
-Analyze problem situation and register as viban issue with file locations and evidence.
+Register a problem as a viban issue. Keep it lightweight — no codebase exploration, no heavy analysis.
 
-> **Core Principle**: Focus on **symptoms and problem definition**, not solutions.
-> Solutions are decided by the assignee after understanding full context.
+> **Principle**: Clarify symptoms only if vague. Don't explore code or propose solutions.
 
-## Input Verification
+## Input
 
 **User Input**: `$ARGUMENTS`
 
-If input is empty or unclear:
-1. Use AskUserQuestion to ask about the problem
-2. Proceed after receiving response
+## Step 1: Clarify (only if needed)
 
-## Execution Steps
+If the user's description is **clear enough** to register (who/what/where), skip to Step 2.
 
-### Step 1: Problem Identification
+If **vague or ambiguous**, concretize with one AskUserQuestion:
 
-Analyze the problem described by user:
-1. **Identify symptoms**: Clearly define what the problem is
-2. **Extract keywords**: Error messages, feature names, module names, etc.
-3. **Determine priority**:
-   | Condition | Priority |
-   |-----------|----------|
-   | System down, data loss | P0 |
-   | Feature broken, errors | P1 |
-   | Performance degradation, warnings | P2 |
-   | Improvements, refactoring | P3 |
+- header: "Problem"
+- question: "Can you describe the symptom more specifically?"
+- options based on context, e.g.:
+  - "Error/crash on specific action"
+  - "Feature not working as expected"
+  - "Performance issue"
+  - "Let me describe"
+- multiSelect: false
 
-### Step 2: Codebase Exploration
+Goal: get a **one-sentence symptom** clear enough for an assignee to understand.
 
-**Required**: Must find code location related to the problem
+## Step 2: Determine Priority & Type
 
-1. **Search by keywords**:
-   ```bash
-   # Search by error message or function name
-   grep -r "keyword" . --include="*.py" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx"
-   ```
+Infer from the description. Do NOT ask unless truly ambiguous.
 
-2. **Check related files**:
-   - Find module where error occurred
-   - Check stack trace files if available
-   - For API endpoints: trace router → use case → domain
+| Condition | Priority |
+|-----------|----------|
+| System down, data loss | P0 |
+| Feature broken, errors | P1 |
+| Performance, warnings | P2 |
+| Improvements, refactoring | P3 |
 
-3. **Collect location information**:
-   - File path: relative to project root
-   - Function/class name
-   - Line number (if possible)
+| Type | When |
+|------|------|
+| bug | Something is broken |
+| feat | New functionality |
+| chore | Maintenance, config |
+| refactor | Code restructuring |
 
-### Step 3: Issue Body Composition
-
-Write issue body in this format:
-
-```markdown
-## Symptoms
-One-sentence summary of what happened.
-- Frequency: (if known)
-- Affected features:
-
-## Reproduction Steps
-1. Step-by-step reproduction
-2. ...
-3. Environment: local/staging/production
-
-## Expected Result
-- How it should work normally
-
-## Actual Result
-- The problem that actually occurred
-
-## Stack Trace (if available)
-```
-Error log or stack trace
-```
-
-## Location
-- File: `path/to/file.ext`
-- Function/Class:
-- Line: (if known)
-
-## Possible Cause (hypothesis)
-- Estimate which code/condition is causing the problem
-- List items to verify (not solutions)
-
-## Meta Information
-- Registered: (current timestamp)
-- Reporter: user
-```
-
-### Step 4: Register viban Issue
-
-Write the description body to a temp file using a heredoc, then pass via `--desc-file`:
+## Step 3: Check Workflow for Issue Numbering
 
 ```bash
-cat > /tmp/viban-desc.md <<'VIBAN_EOF'
-## Symptoms
-One-sentence summary...
-
-## Reproduction Steps
-1. ...
-
-## Location
-- File: `path/to/file.ext`
-VIBAN_EOF
-
-viban add "{short_title}" --desc-file /tmp/viban-desc.md --priority {priority} --type {type}
+[ -f ".viban/workflow.md" ] && cat ".viban/workflow.md"
 ```
 
-**Why heredoc?** Using `<<'VIBAN_EOF'` (single-quoted delimiter) prevents shell interpretation of backticks, `$`, parentheses, and other special characters in the description.
+- If workflow says **Manual** issue numbering → ask user for an external ID (e.g. `PROJ-42`)
+- If workflow says **Auto** or no workflow exists → let viban auto-assign
+- If user provided a specific ID in `$ARGUMENTS` → use it regardless of workflow
 
-**Parameters**:
-- `title`: Plain title (no tags) — first positional argument
-- `--desc-file`: Path to file containing issue body (Markdown)
-- `--priority`: P0, P1, P2, P3 (default: P3)
-- `--type`: bug, feat, chore, refactor
-- `--attach`: (optional) File paths to attach (screenshots, logs, etc.)
+## Step 4: Register
 
-**Examples**:
-```bash
-# BUG issue
-cat > /tmp/viban-desc.md <<'VIBAN_EOF'
-## Symptoms
-API responds with 504 after 30 seconds.
-- File: `src/api/handler.ts:42`
-VIBAN_EOF
-viban add "API response timeout" --desc-file /tmp/viban-desc.md --priority P1 --type bug
+Write the description to a temp file, then register:
 
-# FEATURE issue
-cat > /tmp/viban-desc.md <<'VIBAN_EOF'
-## Symptoms
-Users request dark mode support.
-VIBAN_EOF
-viban add "Dark mode support" --desc-file /tmp/viban-desc.md --priority P2 --type feat
-
-# With screenshot attachments
+```bash
 cat > /tmp/viban-desc.md <<'VIBAN_EOF'
 ## Symptoms
-Layout broken on mobile viewport.
+{concretized one-sentence symptom from Step 1}
+{additional context from user input, if any}
 VIBAN_EOF
-viban add "Layout broken on mobile" --desc-file /tmp/viban-desc.md --priority P1 --type bug --attach ./screenshots/mobile-bug.png
-```
-
-### Step 4a: Attaching Screenshots (Recommended for Visual Issues)
-
-For visual bugs (layout issues, UI glitches, rendering problems), attaching screenshots significantly helps:
-
-1. **Take a screenshot** of the problem:
-   - macOS: `Cmd + Shift + 4` (selection) or `Cmd + Shift + 3` (full screen)
-   - Save to project directory: `./screenshots/` or `./.viban/attachments/`
-
-2. **Attach during creation**:
-   ```bash
-   viban add "Button misaligned on dashboard" --desc-file /tmp/viban-desc.md --priority P1 --type bug --attach ./screenshots/button-issue.png
-   ```
-
-3. **Or attach to existing issue**:
-   ```bash
-   viban attach {issue_id} ./screenshots/screenshot1.png ./screenshots/screenshot2.png
-   ```
-
-4. **View attachments**:
-   ```bash
-   viban get {issue_id}
-   ```
-
-> **Why attach screenshots?**
-> - Claude Code can read image files and understand visual context
-> - The assignee can see exactly what the problem looks like
-> - Reduces back-and-forth clarification
-
-### Step 5: Report Results
-
-After registration, report to user:
-
-```
-=== viban Issue Registered ===
-- Issue ID: #{id}
-- Title: {title}
-- Type: {type}
-- Priority: {priority}
-- Location: {file_path}:{line}
-- Status: backlog
-
-Next steps:
-- `viban list` to view issue list
-- `viban start {id}` to start working
-```
-
-## When Input is Missing
 
-Use AskUserQuestion with these prompts:
+# Auto numbering (default)
+viban add "{title}" --desc-file /tmp/viban-desc.md --priority {priority} --type {type}
 
+# Manual numbering (when workflow specifies manual)
+viban add "{title}" --desc-file /tmp/viban-desc.md --priority {priority} --type {type} --ext-id "{external_id}"
 ```
-What problem should be registered as an issue?
 
-Please include:
-1. What is the problem? (error message, unexpected behavior, etc.)
-2. Where does it occur? (page, API, feature, etc.)
-3. How to reproduce? (step-by-step)
-```
-
-## Example
+**Why heredoc?** `<<'VIBAN_EOF'` prevents shell interpretation of backticks, `$`, etc.
 
-**Input**: "Charts not showing on backtest results page"
+## Step 5: Report
 
-**Analysis Process**:
-1. Keywords: backtest, results, chart
-2. Code exploration:
-   ```bash
-   grep -r "chart" . --include="*.tsx" --include="*.ts"
-   ```
-3. Related file found: `src/pages/backtest/results.tsx`
-4. Check chart rendering logic
-
-**Registration Command**:
-```bash
-cat > /tmp/viban-desc.md <<'VIBAN_EOF'
-## Symptoms
-Backtest results chart not displayed when clicking chart tab.
-- File: `src/pages/backtest/results.tsx`
-VIBAN_EOF
-viban add "Backtest results chart not displayed" --desc-file /tmp/viban-desc.md --priority P1 --type bug
 ```
-
-**Registered Issue**:
+Issue #{id} registered
+  Title: {title}
+  Priority: {priority} | Type: {type}
+  Status: backlog
 ```
-Title: Backtest results chart not displayed
-Priority: P1
-Type: bug
-Location: src/pages/backtest/results.tsx
-```
-
-## Important Notes
-
-- **Location Required**: Do not register without file path
-- **Evidence Required**: Do not register based on guesses without code exploration
-- **Avoid Solutions**: Do not write specific solutions (assignee decides)
-- **Check Duplicates**: Check existing issues before registration
-  ```bash
-  viban list
-  ```
-- **Accurate Priority**: P0 only for system-down level, avoid over-estimation
-
-## Final Step: Auto Update Check
 
-After completing issue registration, run:
-
-```bash
-viban update
-```
+## Notes
 
-This silently checks for updates and only outputs if an update is applied.
+- **No codebase exploration** — the assignee does that during `/viban:assign`
+- **No solution proposals** — focus on symptoms only
+- **Check duplicates** before registering: `viban list`
+- **Don't over-prioritize** — P0 is system-down only

package/commands/assign.md

@@ -8,7 +8,7 @@ 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
+> **Workflow**: Read `.viban/workflow.md` first, then CLAUDE.md fallback
 
 ---
 
@@ -16,7 +16,17 @@ Workflow: First backlog issue -> Resolve -> PR completion
 
 ### 0.1 Read Project Workflow (CRITICAL)
 
-Before any work, read the project's CLAUDE.md:
+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:
 
 ```bash
 for path in "./CLAUDE.md" "./.claude/CLAUDE.md" "../CLAUDE.md"; do
@@ -24,12 +34,13 @@ for path in "./CLAUDE.md" "./.claude/CLAUDE.md" "../CLAUDE.md"; do
 done
 ```
 
-Look for:
-- `Issue Resolution Workflow` or `Workflow` section
-- Testing requirements (manual verification, specific tools, etc.)
+Look for: `Issue Resolution Workflow` or `Workflow` section.
+
+**Priority 3: Default workflow** (Phase 1 below)
 
 IMPORTANT:
-- If project has a defined workflow -> MUST follow it exactly
+- 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)
 
 ### 0.2 Git Setup
@@ -67,7 +78,7 @@ If backlog is empty: Notify user and exit
 viban get $ISSUE_ID
 ```
 
-### If Project Workflow Exists (from CLAUDE.md):
+### If Project Workflow Exists (from `.viban/workflow.md` or CLAUDE.md):
 
 Follow the project's exact steps.
 
@@ -192,7 +203,7 @@ After approval: Delete issue from viban TUI
 ## Checklist
 
 ```
-[ ] Read CLAUDE.md for project workflow
+[ ] Read .viban/workflow.md (or CLAUDE.md fallback) for project workflow
 [ ] Working on viban-$ISSUE_ID branch
 [ ] Implementation complete
 [ ] Manual verification passed (using appropriate tools)