docs: README 應列出 issue-driven-dev 仰賴的外部 plugin / MCP server (依 source type)

[kiki830621]

Problem

Original text (user chat, /idd-issue, 2026-05-07):
「我覺得 readme 上要寫說仰賴哪些 plugin 吧？」

兩份 README 都沒列出 issue-driven-dev 實際用到的外部 plugin / MCP server,使用者裝完只看 README 不會知道哪些來源類型(.docx / Telegram / Apple Mail / Apple Notes)需要額外裝什麼才會 work。

grep 確認 idd-issue skill 直接呼叫以下 MCP tools:

MCP Plugin	用途	觸發時機
che-word-mcp	讀 .docx 文字 + 抽圖 (get_document_text / list_images / export_image)	source 是 .docx / .doc
che-telegram-mcp (telegram-all)	讀 chat history (get_chat_history)	source 是 Telegram chat range
che-apple-mail-mcp (mail)	讀 email + attachments (get_email)	source 是 Apple Mail message
che-apple-notes-mcp (notes)	讀 note + 抽圖 (get_note)	source 是 Apple Notes

頂層 README 也已列出 idd-route 為 sister plugin (coming soon),但沒說明它跟 issue-driven-dev 的依賴關係(它需要 idd-route-swift binary,且是被 issue-driven-dev 內部選擇性使用)。

Type

documentation

Expected

兩份 README 應該各有一段 "Dependencies" / "Optional integrations" / "Source-type adapters" 章節,清楚說明:

1. 核心使用零依賴 — 純 chat / 直接貼文字 / .md 來源不需要任何外部 plugin
2. 依來源類型可選裝(matrix 表格,key 在「為什麼裝這個」+「不裝會發生什麼事」):
   • .docx / .doc → che-word-mcp
   • Telegram → che-telegram-mcp (telegram-all server)
   • Apple Mail → che-apple-mail-mcp
   • Apple Notes → che-apple-notes-mcp
3. Sister plugins(idd-route)說明它是 enrichment,非必要

Actual

• 頂層 README.md:只寫 install 指令 + migration,沒提任何 dependency
• plugins/issue-driven-dev/README.md(line 158 提到 idd-route install,但散落在內文,沒有統一 dependencies 章節)

Impact

• Onboarding 卡點:新使用者拿 .docx 餵 /idd-issue 失敗(mcp__che-word-mcp__get_document_text 不存在),不知道要裝什麼
• Discoverability:不知道 IDD 設計上支援多種 source type,以為只能貼純文字
• 預設無聲降級:Source-type adapter Step 1 在 MCP 不存在時不會明確報錯,只會 fallback 到請使用者手動處理,使用者誤以為「IDD 不支援這格式」

Suggested fix (non-blocking)

兩份 README 加 "Plugin dependencies" / "Source-type adapters" 章節,用 matrix 呈現 + 註明 install 指令(claude plugin install <name>@<marketplace>)。

Scope (per /idd-issue clarification)

• 頂層 README.md
• plugins/issue-driven-dev/README.md

Priority: P2

Linked-Context Siblings Filed (v2.48.0+ #529)

Filed sibling issues: #27 (idd-issue Step 1 silent-degrade UX bug)

Current Status

Phase: closed
Last updated: 2026-05-07 by idd-close (auto via idd-update)

Key Decisions

• 用既有 plugins/issue-driven-dev/README.md ## Requirements 為 landing spot,重組為 Required / Optional / Sister 三節 (Strategy A, commit 78dbc15)
• 頂層 README 加簡短 ## Requirements 指向 plugin README (Strategy B, commit be4931b)
• 加 KEEP IN SYNC HTML comment 防 source type adapter ↔ README matrix drift (Strategy C, commit 6997e3f)
• 替 feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 預留 ### Required for specific modes 插入空間,但不直接寫 ralph-loop row (avoid scope creep)
• Complexity = Simple (Layer 1)
• Vagueness Pre-check: V1=1, V4=2 (not triggered)
• PR docs: README 列出 issue-driven-dev 仰賴的外部 plugin / MCP server #30 squash-merged → main (0e9bb99)

Scope Changes

• (none)

Blocking

• (none — closed)

Commits (squashed via PR #30)

• 78dbc15 docs: 擴充 plugin README ## Requirements (Required + Optional + Sister)
• be4931b docs: 頂層 README 加 ## Requirements summary + link to plugin README
• 6997e3f docs: 加 KEEP IN SYNC comment 防 source type adapter ↔ README matrix drift
• 0e9bb99 docs: README 列出 issue-driven-dev 仰賴的外部 plugin / MCP server (docs: README 列出 issue-driven-dev 仰賴的外部 plugin / MCP server #30) — squash on main

PR

• docs: README 列出 issue-driven-dev 仰賴的外部 plugin / MCP server #30 (merged)

Sister Concerns

• Diagnose: skipped (1: SKILL/README sync — covered as Strategy mitigation)
• Implement: filed docs: README install 指令的 <your-marketplace> placeholder 缺 lookup hint (sister from #26) #31 (marketplace placeholder UX), docs: spec 出 #27 fail-fast 訊息實際長相 (sister from #26) #32 (refine bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27 fail-fast format)
• Close: (none — no orphan mentions)

Follow-ups

• feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 (ralph-loop dependency, blocked by this issue, now unblocked)
• bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27 (source-type adapter fail-fast)
• docs: track upstream gap — Claude Code plugin schema 缺 inter-plugin dependency 機制 (sister from #28) #29 (upstream Claude Code schema gap)
• docs: README install 指令的 <your-marketplace> placeholder 缺 lookup hint (sister from #26) #31, docs: spec 出 #27 fail-fast 訊息實際長相 (sister from #26) #32 (sisters from implement)

[kiki830621]

Diagnosis

Type

documentation (docs gap with onboarding/UX impact)

Analysis

grep 對 plugins/issue-driven-dev/skills/ 的 hits 已在 issue body matrix 中列出,確認 4 個 MCP plugin 是 hard reference(skill 直接呼叫 mcp__che-word-mcp__* / mcp__plugin_che-telegram-mcp_* / mcp__plugin_che-apple-mail-mcp_* / mcp__plugin_che-apple-notes-mcp_*),不是「假設使用者會有」。

現有 landing spot 已存在(關鍵發現):plugins/issue-driven-dev/README.md line 180–184 已有 ## Requirements section,目前只列 3 項:gh CLI / Codex CLI / ChatGPT Pro。這是現成的擴充點,不需新增 section。

頂層 README.md 沒有 Requirements section,但有 Installation / Plugins 等。需新增一段。

需求拆解:

1. 核心使用零依賴的宣告 — 防止「裝什麼才能跑」恐慌。Single-issue invocation(/idd-issue、/idd-diagnose 不帶 doc/MCP source)應該明確寫出「無 extra dependency」
2. 依 source type 的 optional matrix — .docx / Telegram / Apple Mail / Apple Notes 各對應一個 plugin;表格而非 prose 才能對應 Step 1 Source Type Adapter table
3. Sister plugin discoverability — idd-route 已在頂層 README 提到「coming soon」但沒說它跟 issue-driven-dev 的關係(enrichment via Step 3.7)

Impact

• 影響的檔案:
  • README.md (頂層 marketplace) — 新增 ## Requirements section
  • plugins/issue-driven-dev/README.md — 擴充既有 ## Requirements (line 180–184)
• 影響的使用者流程:
  • 新使用者裝 plugin 後第一次跑 /idd-issue file.docx 會失敗
  • 既有使用者不知道 IDD 支援 Telegram / Mail / Notes source type,功能 dead in water

Strategy

Single PR,改兩個檔案,純 docs (無 code 改動):

• A. 擴充 plugins/issue-driven-dev/README.md 的 ## Requirements
  • 重組為兩節:### Required (always) 列現有 3 項 + ### Optional (per source type) 用 4-row matrix 列 MCP plugins
  • Matrix 欄位:Source type | Required plugin | MCP server | Why | Install
  • 加 ### Sister plugins mini-section 提 idd-route (enrichment via Step 3.7,non-required)
• B. 頂層 README.md 新增 ## Requirements
  • 在 ## Installation 之後、## Why a separate marketplace? 之前
  • 簡短版(避免重複 plugin README):「IDD core 零依賴,某些 source type 需要 optional MCP plugins — 詳見 plugins/issue-driven-dev/README.md#requirements」+ 一句話 summary
• C. (optional) 加 sister-issue cross-link 提 bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27(Layer 2 fail-fast)和 feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28(ralph-loop dependency)為 follow-ups

為什麼不加 install 自動化(例如 bundle install script):

• 各 MCP plugin 來源不同 marketplace,bundle 需要 hard-code marketplace name 容易過時
• 使用者預期 claude plugin install 是一行一個,bundle 改變 mental model

Complexity

Simple

Layer 1 命中:「主要 deliverable 是更新既有 prose 但不改 behavior(typo、wording cleanup、文件 restructure)」。改的是兩份 README 的 ## Requirements 段落,純 prose + matrix table,不改任何 code、skill、plugin behavior。沒有 cross-file dependency(兩份 README independent),沒有 published API change,沒有 risk-sensitive boundaries。

Layer 1 disqualifier 命中即跳過 Layer 2 / Layer P 評估。

Risks

• Matrix 過時風險:之後新增 source type adapter 但忘了更新 README — mitigation: 在 idd-issue/SKILL.md Step 1 Source Type Adapter table 上方加 comment 「KEEP IN SYNC WITH plugins/issue-driven-dev/README.md#optional-per-source-type」
• Marketplace name 寫死:目前 che-* plugins 在 che-claude-plugins marketplace,明文寫 install 指令會綁定 marketplace 名 — mitigation: 用 <your-marketplace> placeholder 而非具體名稱,並在 Install 欄附 marketplace 來源 URL
• Top-level 與 plugin README 失同步:頂層說一套、plugin 說另一套 — mitigation: top-level 只寫 summary + link,authoritative content 只在 plugin README

Related

• bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27 — sister concern: skill 內部 fail-fast 報錯(本 issue Layer 2 解法,已獨立 file)
• feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 — sister concern: ralph-loop runtime dependency,共用同一個 ## Requirements landing spot

Vagueness Pre-check

• V1: 1 — issue body 逐字引原話、4-row MCP matrix、3 段預期內容明確;Strategy A/B/C 各指明檔案路徑與 section 名 (line 180–184 / 頂層 README)
• V4: 2 — 兩份 README 各有 ## Requirements section + matrix 為可數二元條件;勾選清單在 issue body
• Triggered: no — both axes ≤ 3

Sister Concerns Filed (mid-diagnose, v2.47.0+ #528)

Skipped per user choice (1 item: docs sync mechanism between idd-issue SKILL.md Source Type Adapter table and README matrix — already covered as KEEP IN SYNC comment mitigation in Strategy)

[kiki830621]

Implementation Plan

依 Diagnosis Strategy 拆解 — Simple complexity,純 docs 改動,3 個 ordered changes:

• A. 擴充 plugins/issue-driven-dev/README.md ## Requirements

  • 重組為 ### Required (always) (現有 3 項) + ### Optional (per source type) (4-row matrix:.docx / Telegram / Apple Mail / Apple Notes → 對應 plugin)
  • 加 ### Sister plugins mini-section 提 idd-route (enrichment via Step 3.7)
  • 特別注意:section 結構要為 feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 future Layer 1 (Required for unattended/--loop modes) 預留空間 — ### Required (always) 之後可平滑插入 ### Required for specific modes,不需要 feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 重組

• B. 頂層 README.md 新增 ## Requirements summary

  • Insert position:## Installation 之後、## Why a separate marketplace? 之前
  • 內容:一段 prose summary 標明「IDD core 零依賴,某些 source type 需要 optional MCP plugins」+ link 到 plugin README anchor
  • 不重複 plugin README 的 matrix(authoritative content 留在 plugin README)

• C. 在 idd-issue/SKILL.md Step 1 Source Type Adapter table 上方加 KEEP IN SYNC comment

  • mitigation for diagnosis Risk「Matrix 過時風險」
  • 一行 HTML comment 不影響渲染:<!-- KEEP IN SYNC: plugins/issue-driven-dev/README.md#optional-per-source-type -->

Extra Requirements

(none — 純 markdown 編輯,無 with-skill / extra-text)

Scope check

• ✅ A 對應 Strategy A "擴充 plugins README"
• ✅ B 對應 Strategy B "頂層 README 新增"
• ✅ C 對應 Strategy Risk mitigation (Matrix 過時)
• ✅ Strategy C "(optional) 加 sister-issue cross-link" 已在 issue body Related section 完成,無需 commit

[kiki830621]

Implementation Complete

Checklist (synced from TaskList)

• A. 擴充 plugins/issue-driven-dev/README.md ## Requirements → commit 78dbc15
  • Required (always) / Optional (per source type) / Sister plugins 三節
  • 4-row matrix: .docx / Telegram / Apple Mail / Apple Notes → MCP plugin + install 指令
  • 預留結構讓 feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 Layer 1 可平滑插入 ### Required for specific modes
• B. 頂層 README.md 新增 ## Requirements summary → commit be4931b
  • 位置:## Installation 之後、## Why a separate marketplace? 之前
  • 短 prose + link 到 plugin README anchor;不重複 matrix
  • 提前點名 feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 (ralph-loop) 與 Codex CLI 為 mode-specific dependency
• C. 加 KEEP IN SYNC comment 在 idd-issue/SKILL.md → commit 6997e3f
  • mitigation for diagnosis Risk「Matrix 過時風險」
  • HTML comment <!-- KEEP IN SYNC: ... --> 不影響渲染

Legend: - [x] done · - [~] skipped (may revisit) · - [-] won't fix (scope)
idd-close will refuse to close if any - [ ] remains in this checklist.

Changes

• 78dbc15 docs: 擴充 plugin README ## Requirements (Required + Optional + Sister)
• be4931b docs: 頂層 README 加 ## Requirements summary + link to plugin README
• 6997e3f docs: 加 KEEP IN SYNC comment 防 source type adapter ↔ README matrix drift

Files Changed

 README.md                                          | 12 ++++++++++++
 plugins/issue-driven-dev/README.md                 | 21 +++++++++++++++++++++
 plugins/issue-driven-dev/skills/idd-issue/SKILL.md |  2 ++
 3 files changed, 35 insertions(+)

Figures

(none — pure docs change)

Scope Compliance

• ✅ 改動只觸及 issue body 列出的兩個 README + 1 個 SKILL.md sync comment
• ✅ 無 code 改動、無 plugin behavior 改動、無 plugin.json schema 改動 (那是 feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 的 Layer 3 探索範圍)
• ✅ 替 feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 預留 ### Required for specific modes 插入空間,但沒有直接寫 ralph-loop row(避免 scope creep into feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28)

Next: verification pending

Sister Bugs Filed (mid-impl, v2.44.0+ #526)

Filed:

• docs: README install 指令的 <your-marketplace> placeholder 缺 lookup hint (sister from #26) #31 — README install 指令 <your-marketplace> placeholder UX gap
• docs: spec 出 #27 fail-fast 訊息實際長相 (sister from #26) #32 — spec out concrete error format for bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27 fail-fast acceptance criteria

[kiki830621]

Closing Follow-ups Filed (v2.45.0+ #527)

(none — no orphan mentions in closing summary; all #28/#27/#29/#31/#32 references already cross-linked in Follow-ups section)