Bug Workflow Plugin v4.0.3

跨 Host 的 Bug lifecycle：建立狀態、蒐集證據、驗證根因、修復、回歸測試，最後由 Human UAT 決定是否結案。核心流程依賴 CREW Host Capability Contract，而不是某一家的 agent/team 工具。

安裝

Claude Code

claude plugin marketplace add mark22013333/crew
claude plugin install bug-workflow

Codex

codex plugin marketplace add mark22013333/crew
codex plugin add bug-workflow@crew

首次使用可執行 /bug-setup，或由 /crew-init 統一引導。

更新

推薦：

/crew-upgrade
/crew-upgrade --check

Claude Code 手動更新：

claude plugin marketplace update company-marketplace
claude plugin update bug-workflow@company-marketplace
claude plugin list

Codex 手動更新：

codex plugin marketplace upgrade crew
codex plugin list

更新後開新 session。若 Codex marketplace 尚未註冊，先執行 codex plugin marketplace add mark22013333/crew。

Intake refinement

新的 Bug raw issue 會先經唯讀 bug-intake-refiner，再由 Human 明確確認；使用者不需要手動呼叫 Refiner，它不是 Slash Skill。

flowchart TD
    Raw["Raw bug report"] --> Refiner["bug-intake-refiner<br/>requirement_analysis + STANDARD"]
    Refiner --> Blocking{"Blocking ambiguity?"}
    Blocking -- "yes" --> Ask["Ask Human<br/>max 3 questions"]
    Ask --> Refiner
    Blocking -- "no" --> Confirm{"Human confirms intent?"}
    Confirm -- "modify" --> Refiner
    Confirm -- "cancel" --> Stop["Stop<br/>zero side effect"]
    Confirm -- "confirmed" --> Guard["Persistence security preflight<br/>redact credentials + .spec gitignore safeguard"]
    Guard --> Cache[".cache/intake.md<br/>page-aware recovery journal"]
    Cache --> Start["/bug-start<br/>Notion + minimal bug state"]
    Start --> Investigate["/bug-investigate"]

規則：

• /bug-start <問題> 自動使用 intake refinement；/bug-investigate <新問題> 會先進 /bug-start。
• 已存在的 Bug、/bug-investigate --resume、/bug-update、/bug-fix、/bug-close 不重新 refine。
• Host 支援 named sub-agent 時使用 bug-intake-refiner；不支援時 inline 執行同一 shared contract。
• Human confirmation 前禁止 Notion/state/.spec side effect。
• confirmation 後、持久化前做 credential preflight；疑似 secret 必須先由 Human 提供 redacted 版本。
• 在 Git repo 內寫 cache/state 前先確認 .spec/ 已被 .gitignore 保護。
• cache 固定保存 original/refined/title 與 notion_page_id；Notion page create 後 page ID 先寫 cache，再進 state init，所以中斷重跑能沿用既有 page。
• Notion「🔴 問題描述」保存 ### 原始通報 + ### 確認後問題描述。
• /bug-investigate、/bug-update、/bug-close 都執行 Bug intake recovery preflight：只補缺少內容、不覆蓋既有內容。
• cache 只有在重新 fetch 確認 intake headings + 五個標準 Bug sections（調查過程／根因分析／修復方案／驗證／經驗教訓）全部存在後才刪除；若只有 headings 完整，仍必須補齊缺少 section，不得提前清 cache。
• /bug-close 先以 Notion page ID deterministic 綁定唯一 Bug state / slug，再進 UAT gate；找不到或多筆都 BLOCK。
• CREW scripts 一律先解析 CREW_PLUGIN_ROOT，不直接依賴 Claude marketplace path。

完整 contract 見 references/intake-refinement.md。

核心流程

flowchart LR
    A["raw issue"] --> S["/bug-start<br/>refine + Human confirm"]
    S --> B["/bug-investigate"]
    B --> C["根因確認"]
    C --> D["/bug-fix"]
    D --> E["build/test/回歸 evidence"]
    E --> F["/bug-close"]
    F --> G{"Human UAT"}
    G -- accepted --> H["close"]
    G -- rejected --> D

Runtime state：

start → investigate → fix → close

.spec/{slug}/state.json 是唯一流程狀態，唯一寫者為 scripts/crew-state.py。調查與修復都使用 resumable work unit，因此 session 中斷後可從 deterministic state 繼續。

Human UAT

/bug-close 不能把 build/test、C1-C4 或其他 machine evidence 自動等同「使用者接受修復」。只有 Human 明確接受後，才能寫入 uat=approved 並完成 close；若 rejected，下一步回到 /bug-fix。

Model Routing

Bug workflow 使用 provider-neutral profiles：

實際 provider model 由 Host adapter 與 crew-model-route.py 決定。Host 無法精準套用 per-worker mapping 時，保留角色/write boundary 並標記 routing degraded；不可假裝已切換模型。

Host Capability Contract

Bug Skill 只依賴 capability：

• project_instructions：接受 AGENTS.md、CLAUDE.md
• delegate_readonly：證據蒐集與分析
• delegate_write：只有 /bug-fix 可用於正式產品碼
• parallel_delegate：可用則平行，不可用就 sequential
• tool_probe：判斷 DB/外部工具真的能否呼叫
• ask_user：根因歧義與 UAT 等 Human decision

完整 contract 見 references/host-capabilities.md。

首次設定與 Portable Config

/bug-setup 不再要求使用者選擇某個 Host-specific storage directory。CREW-owned config 透過 shared resolver 存取。

Portable root：

1. CREW_CONFIG_HOME
2. $XDG_CONFIG_HOME/crew
3. ~/.config/crew

Bug 相關 logical keys：

實際 read fallback / canonical write path 由 scripts/crew-config.py 決定。Skill 不自行拼 Host path，也不把 project mapping 複寫回 Bug 主設定。

專案指令與專案註冊

需要專案規範時使用 project_instructions：

• AGENTS.md
• CLAUDE.md

兩者都存在時都可讀；有衝突就列為 ambiguity。

/project-add 會：

1. 解析 repo-id。
2. 同步/更新 Notion 專案。
3. 以 portable feature/project 寫入 project frontmatter（stack、prod branch、可選 uat branch）。
4. legacy monolith 僅相容讀取；更新時寫 canonical project file。

指令

SessionStart hook

Claude Code adapter 會執行 python3 scripts/crew-state.py session-brief：

• 只讀當前專案 .spec/*/state.json
• 不外送資料
• 不寫產品檔案
• 顯示未結案任務與建議下一步
• 失敗時不阻擋 session

其他 Host 沒有同等 session hook 也沒關係；直接使用 workflow Skill / state next 即可。

設計參考

• Host Capability Contract
• Model Policy
• State Discipline
• Portable Config Contract
• Learning Schema
• Intake Refinement Contract

授權

MIT License