從一個咖啡電商，長出五個開源工具

一句話

我沒有「決定要做一套 AI 開發工具鏈」。我是在做一個咖啡電商的過程中，同一類痛點痛到第三次，才把它從那個專案裡挖出來、洗乾淨、變成一個獨立的開源 repo。五個工具就是這樣一個一個長出來的。這篇把它們的先後順序、彼此關係、和怎麼一行指令裝起來講清楚。

如果你只想看怎麼用：跳到最後「npx specmit init 怎麼用」。

緣起：工具不是設計出來的，是被痛出來的

這套工具的源頭是一個私有 repo：CS垂直整合SAAS（咖啡產業垂直整合電商，2025-12 開始）。它不是工具，它是我的生意。

但做著做著，我在這個 repo 裡反覆撞同一類牆：

同一個 PostgreSQL function overload bug，手動修了三次（2026-02、05-17、05-20）才捨得寫成自動檢查；
前端覆蓋資料庫真相值的 bug，admin 看正常、客人看缺貨，藏了一年；
多開幾個 AI session 並行，互相蓋掉對方的改動。

每解決一類，我就在那個 repo 裡長出一個機制——一條 governance-guard 規則、一支 trace 測試、一份協作看板。到了 2026 年 4 月中（governance-guard 誕生那天），我發現這些機制有個共同點：它們跟「咖啡」一點關係都沒有。它們是任何用 AI 寫程式的人都會需要的東西。

於是從 5 月底開始，我把它們一個一個搬出來，變成公開 repo。

💡 這就是知識複利的跨界版：一個專案踩過的坑，不該只讓那個專案受惠。把它抽象、剝掉專案特定的部分、變成可安裝的工具——下一個專案、甚至別人的專案，都直接站在你撞痛的肩膀上。

時間線：五個 repo 的誕生順序（GitHub 實查日期）

這是關鍵——它們的誕生順序，跟「正常的管線順序」是反過來的。

2025-12-05  ┌─ CS垂直整合SAAS（私有，生意本體 = 礦場）
            │
2026-03-26  ├─ ai-dev-toolkit（私有，跨專案 skill 雜物櫃 = 最早的中繼站）
            │
            │   ── 以下是公開工具，被一個一個挖出來 ──
            │
2026-05-25  ├─ ① goal-workflow-designer   塑形任務（先痛：任務描述不夠精準）
2026-05-27  ├─ ② claude-skills-governance-meta  治理（次痛：同類 bug 一直復發）
2026-06-05  ├─ ③ agent-work-board         協調（再痛：並行 session 撞車）
2026-06-09  ├─    RequiBridge（私有，顧問接案進料口）
2026-06-10  ├─ ④ spec-sonar               收斂＋分解（補上游：想法→規格→goal 圖）
2026-06-10  ├─ ⑤ specmit                  執行＋前門（最後才做：把全部串成一條管線）
2026-06-15  └─ reuse-hub（私有，複用櫃台）＋ ai-dev-toolkit 退役

我的詮釋（標明是詮釋）：如果我是「先設計一條 idea→spec→code 的管線、再依序實作」，誕生順序應該是 spec-sonar → goal-workflow-designer → specmit。但實際順序是反的——最先做的是「塑形任務」和「治理」這種做到一半最痛的中段工具，最上游的「想法收斂」(spec-sonar)和把全部串起來的「管線執行器」(specmit)反而最後才做。

這不是亂做。這是由痛點驅動的 bottom-up 組裝：哪裡最常流血就先包紮哪裡，等手上零件夠多了，才在 2026-06-10 那天回頭畫出整張地圖、把零件接成一條管線。ECOSYSTEM.md 自己的結尾就寫著：「*Established 2026-06-10 from an ecosystem-wide gap diagnosis*（源於一次全生態系的缺口診斷）」。

它們各自管什麼，又怎麼接在一起

雖然做的順序是 bottom-up，但用的順序是一條乾淨的管線。以下角色定義以 specmit/ECOSYSTEM.md（拓撲 SSOT）為準：

   模糊的想法
       │
       ▼
  ┌────────────────────────────────────────────┐
  │ ④ spec-sonar          收斂 & 分解            │
  │   idea-to-spec   → 5–7 輪問答 → 規格         │
  │   goal-decomposer → 依賴排序的 goal 圖       │
  └────────────────────────────────────────────┘
       │  goals / 規格
       ▼
  ┌────────────────────────────────────────────┐
  │ ① goal-workflow-designer   塑形任務          │
  │   goal           （深度：一個任務打磨到位）  │
  │   workflow-shaper（廣度：同一檢查跑很多單位）│
  └────────────────────────────────────────────┘
       │  精準的 /goal prompt 或 workflow 腳本
       ▼
  ┌────────────────────────────────────────────┐
  │ ⑤ specmit（前門）          執行管線          │
  │   specmit skill → idea-to-mvp.js 執行器      │
  │   批次平行 agent、凍結契約、獨立計分稽核     │
  └────────────────────────────────────────────┘
       │ 被治理               │ 被協調
       ▼                      ▼
  ┌──────────────────┐  ┌──────────────────┐
  │ ② governance-meta│  │ ③ agent-work-board│
  │  CI 防線、閘門     │  │  跨 session 看板  │
  │  skill、反向哨兵  │  │  領土 + 足跡       │
  └──────────────────┘  └──────────────────┘

逐個說明（含「什麼時候該伸手拿它」）：

Repo	層	它管什麼	什麼時候拿它
spec-sonar	收斂＋分解	`idea-to-spec`、`goal-decomposer`、`audit-existing-project`（brownfield 補全入口）、Audit / 複雜系統 / 衝突分析模式	「我有一個產品想法」「幫我把這份規格拆成依賴排序的任務」「audit / 補全一個既有專案有沒有盲點」
goal-workflow-designer	塑形	`goal`（深度）、`workflow-shaper`（廣度）	「一個任務要做到位」「同一個檢查要跑很多檔案」
claude-skills-governance-meta	治理	`governance-guard` + `step-back` 哨兵模板、architecture-guardian / trace-lock / step-back-review 鷹架 skill、可攜的 Supabase/網頁安全閘 playbook	「我不想再出同一類 bug」「擋住『我要加 X』這種架構宣告」「想要一份 advisor 抓不到的安全規則集」
agent-work-board	協調	WORK-BOARD 模板、認領儀式、足跡方法論	「我同時開 2+ 個 AI session 在同一個 repo 上」
specmit	執行＋前門	這張地圖、`PIPELINE-CONTRACT.md`、`idea-to-mvp` 執行器、`specmit` npm CLI（init/complete/sync/contrib）、確定性階段交接 hooks	「一個指令跑完 spec→goals→執行」「補全一個既有專案」「我該從哪開始？」

一句話辨向（來自 goal-workflow-designer）：數一下有幾個單位。一件事要做到完美 → goal；同一個檢查跨很多件 → workflow-shaper；一整份多模組規格 → goal-decomposer。

鬆耦合是鐵律

這套東西最關鍵的設計，是 specmit 的執行器什麼都不 import、不呼叫任何 repo 的程式碼。工具之間唯一的介面是檔案格式（goal-graph.json、goals/G*.md、run-report.json）。

ECOSYSTEM.md 的原話：「*Delete this repo and nothing upstream breaks*（刪掉這個 repo，上游一個都不會壞）。」

這也是知識複利能成立的前提：每個工具獨立可用、可單獨被別人裝、可單獨演化。它們不是一個會綁死你的框架，是五塊可以各自拿走的積木。

那兩個私有 repo 是什麼？

時間線裡有三個私有 repo，順帶交代（它們不是任何公開工作流的必要件）：

ai-dev-toolkit（2026-03-26 → 2026-06-15 退役）：最早的「跨專案 skill 雜物櫃」。所有東西最初都堆在這。後來它太雜，2026-06-15 拆解退役——治理進 governance-meta、複用進 reuse-hub、生態地圖進 specmit。它是中繼站，不是終點。 ECOSYSTEM 的 canonical 家也在 2026-06-12 從它搬到 specmit，好讓「地圖」是公開可達的。
reuse-hub（2026-06-15，私有）：跨專案複用的櫃台（manifest + 踩坑庫）。
RequiBridge（2026-06-09，私有）：顧問接案的需求進料口。

公開的五個 repo 就是上面那張表的全部；私有的這幾個是我自己的商業資產，不影響你裝來用。

npx specmit init 怎麼用

如果你想把這整套裝進你自己的新專案，一行：

# 在你的新專案資料夾裡執行：
npx specmit init

它會做的事（來自 ECOSYSTEM.md，specmit ≥ 0.4.2）：

裝核心 skill：spec-sonar 三套（idea-to-spec + goal-decomposer + audit-existing-project brownfield 補全入口）+ specmit + idea-to-mvp workflow
裝確定性階段交接 hooks（ADR-007）到 .claude/，讓管線每個階段交棒時自動通知，不靠人記得
建立 spec/ 與 runs/ 資料夾
跑 awaken（init 的第 4/4 步）：冷啟動掃這台機器有哪些 skill / repo / 工具，寫進你的 CLAUDE.md —— 新對話一開場就知道手上有什麼，不必每次從零問
已有全域 skill？init 自動跳過、不覆蓋（要強制更新加 --force）

裝完之後，直接在 Claude Code 裡用白話開始：

想從頭做：說「我想做一個……」→ 觸發 idea-to-spec，跟你來回 5–7 輪把想法收斂成規格
既有專案要補全 / 體檢：說「幫我補全這個專案」或 npx specmit complete → 走 brownfield 補全入口（archetype 完備性軸 + 網頁/Supabase 安全 lens），照出缺的、薄的、危險的，再接力修
想一條龍跑完：說「跑完整管線」→ specmit 讀 goal 圖、批次平行跑 agent、每個結果再過一個獨立唯讀的計分稽核才算數

四個 CLI 指令：

指令	說明
`specmit init`	安裝核心 skill（spec-sonar 三套 + specmit + idea-to-mvp workflow）+ 階段交接 hooks + 建 `spec/`、`runs/`，最後跑 `awaken` 掃資源
`specmit complete`	確保 brownfield 補全 / 體檢入口已裝，並印出怎麼啟動（既有專案說「幫我補全這個專案」）
`specmit sync`	把已裝的 skill 更新到最新 canonical 版
`specmit contrib`	顯示你本地的修改與 canonical 的差異、印出 PR 步驟

goal / workflow-shaper / 治理 skill / 看板是選配，到各自的 repo 依 README 裝。

一個值得抄的設計：計分棘輪（verification ratchet）

specmit 裡我最想推薦你抄的，是它不信任 agent 的自我回報。一個 agent 說自己「verified（驗證通過）」，是球員兼裁判。所以每個正面結果都要過一個獨立、唯讀、只能往下調信心、永不往上的計分稽核：

Tier-1（純 JS、零 token）：抓自相矛盾（說 verified 但 verify.passed 是 false）
Tier-2（一個全新的唯讀稽核 agent）：自己 git diff 確認檔案真的改了、重跑驗證指令拿真實 exit code
單向棘輪：稽核只能降信心，不能升。信心要升，只能靠通過一個真實檢查，不能靠嘴巴說

這條原則跟「曲線 B」那篇講的是同一件事：讓機制比記性／嘴巴可靠。 一個 agent 的「我做完了」，跟一個人的「我記得要先 DROP FUNCTION」一樣不可靠。複利就是把這些不可靠的人為環節，一個一個換成不會忘、不會騙的機器。

收束

五個開源工具，不是一張藍圖的產物，是一個咖啡電商流過的血結痂之後，被我刮下來、洗乾淨、裝進別人也能用的瓶子。

誕生順序是 bottom-up（哪裡痛先包哪裡），使用順序才是乾淨的管線（想法→規格→塑形→執行）。
鬆耦合讓每塊積木能單獨被拿走，這是它們能變成「基礎設施」而非「框架」的關鍵。
npx specmit init 是那扇前門：把我撞牆撞出來的整條管線，一行裝進你的下一個專案。

知識複利的最後一哩，不是把經驗寫成文章（雖然這篇就是），而是把它寫成別人能 npx 一下就裝起來的東西。