tospec

用 schema 定義文件與流程的 spec-driven development CLI. 進度由檔案推算, 工作方法寫在 Skill 裡.

寫需求時最常遇到的問題不是「不會寫」, 而是「寫到一半就跳去實作, 最後規格跟程式對不上」. tospec 把釐清需求, 寫規格, 設計, 拆任務, 實作, 歸檔串成一條線: Skill 帶著 AI 工具 (Claude Code / Codex) 走每一步, CLI 負責建檔, 看狀態, 驗證格式.

它沒有狀態資料庫. tospec status 看 change 目錄裡有哪些檔案, 就知道走到哪一步; 檔案出現, 狀態就前進.

安裝

需要 Node.js 22.22.0 以上.

npm install -g @seanmars/tospec
tospec --help

不想全域安裝也可以直接 npx @seanmars/tospec --help.

快速開始

# 初始化專案, 順便裝好 Claude Code 的 Skill
tospec init --tools claude

# 開一個新需求
tospec new change add-dark-mode --schema sdd

# 看這個 change 走到哪了
tospec status --change add-dark-mode

# 檢查文件格式
tospec validate add-dark-mode

# 做完了, 把規格合併進主 specs 並歸檔
tospec archive add-dark-mode

--tools 可填 claude, agents, all 或 none. Skill 一律先寫進 .agents/skills/ 這份 canonical 副本, 再複製到各工具目錄, 所以 claude 隱含 agents. Codex 直接讀 .agents/, 不會另外產生 .codex/. none 只建 tospec/ 目錄, 不碰任何 agent 內容.

.claude/skills/ 是複本不是連結, 因為 junction 與 symlink 進 git 的記錄方式不同, 會讓追蹤內容取決於貢獻者的作業系統. 改了 .agents/skills/ 之後要跑 tospec update 才會同步過去.

兩種工作流程

開 change 時用 --schema 選:

| schema | 用途 | 文件流程 | |--------|------|----------| | sdd | 開發新需求 | proposal → specs / design → tasks | | issue | 修正問題 | task (根因診斷) + 選配 specs |

兩者都在 apply 階段實作, 最後由 archive 判斷要不要先 sync 再歸檔. apply 的完成標準是測試與 tospec validate 通過; 雙軸審查 (verify) 是 opt-in, 使用者開口才做.

文件狀態有六種:

• done: 檔案已存在且有內容
• stub: 檔案存在但是空白或與 template 相同, 不算完成, 也不解鎖後續文件
• ready: 前置文件都齊了, 這份還沒寫, 可以開始
• blocked: 至少一份前置文件還沒建立
• optional: 選配文件沒建, 不擋流程, 需要時再寫
• skipped: change 以 skip_specs: true 宣告不需要 specs, 不擋流程

Skill

tospec init 會裝 10 個 workflow Skill, 在 Claude Code 中以 /tospec-<name> 呼叫.

| Skill | 作用 | |-------|------| | tospec-explore | 用訪談收斂還很模糊的需求或問題 | | tospec-grill | 對計畫, 決策, 設計做壓力測試 | | tospec-propose | 把討論清楚的需求整理成完整的 sdd change | | tospec-issue | 診斷 bug 到根因, 產出 issue change | | tospec-decision | 把架構決策記成永久 ADR | | tospec-update | 修訂 change 的規劃文件並保持一致 | | tospec-apply | 逐項實作任務 | | tospec-apply-with-tdd | 同上, 但強制先寫測試 (red → green) | | tospec-sync | 以程式碼為準核對規格, 產出 sync-report | | tospec-archive | 判斷要不要 sync, 然後歸檔 |

典型流程: explore 想清楚, propose 寫成 change, apply 實作, 需要時 sync 核對規格, 最後 archive. 修 bug 從 issue 開始, 一樣走 apply → archive 收尾.

CLI 指令

多數指令支援 --json, 給 AI 工具讀. 封包格式與 exit code 見 Agent 契約.

專案管理

| 指令 | 作用 | 選項 | |------|------|------| | tospec init [path] | 初始化專案, 建立 tospec/, Skill 與 workflow 規則 | --tools, --force, --profile <name>, --json | | tospec update [path] | 重新產生 Skill 並同步到各工具目錄 | --force, --json | | tospec rules [path] | 只刷新 workflow 規則檔, 不動 Skill 與設定 | --json | | tospec migrate [openspec-dir] | 把 OpenSpec 專案轉成 tospec 格式 (預設讀 ./openspec) | -f, --force, --json | | tospec config <sub> | 全域設定: path, list, get, set, unset, reset, edit, profile [preset] | 各子命令多支援 --json |

workflow 規則檔 (.agents/rules/tospec/single-source-of-truth.md 與 .claude/ 下的複本) 由套件產生, 內含版本標記與內容雜湊. 一旦偵測到手改, init / update / rules 都會在寫入任何檔案前整次失敗, --force 也不例外. 想保留修改, 先備份再刪掉該檔重跑.

建立與查詢

| 指令 | 作用 | 選項 | |------|------|------| | tospec new change <name> | 建立 change 目錄與 ticket | --schema <sdd\|issue>, --description, --goal, --decisions <files>, --json | | tospec list | 列出進行中的 change | --specs, --changes, --sort <recent\|name>, --type <requirement\|issue>, --json | | tospec show [item-name] | 顯示 change 或 spec | --type <change\|spec>, --diff, --requirements, --no-scenarios, -r <id>, --no-interactive, --json | | tospec status | 顯示各文件狀態 | --change <id>, --all, --schema <name>, --json | | tospec decision new <topic> | 建立 ADR 與索引列 | --title, --summary, --date, --status, --force, --json | | tospec decision list | 列出 ADR | --status, --sort <date\|name>, --reindex, --json | | tospec skill-metrics | 開本機網頁看每個 Skill 的耗時 | --no-open |

show --diff 會把 change 裡每個 requirement 對照主 specs 顯示差異, 包括 REMOVED 會刪掉的那段.

skill-metrics 讀 Claude Code 與 Codex 的 session 紀錄, 只讀不寫. Claude Code 是直接讀 transcript 的歸屬欄位 (舊 session 沒有, 統計不到); Codex 沒有對應欄位, 改用「讀了哪個 SKILL.md」推論. 兩者精準度不同, 頁面上分開呈現, 不合併.

驗證與歸檔

| 指令 | 作用 | 選項 | |------|------|------| | tospec validate [item-name] | 檢查必要段落與 delta spec 格式 | --all, --changes, --specs, --type, --strict, --concurrency <n>, --no-interactive, --json | | tospec archive [change-name] | 重新驗證, 合併 delta specs, 把 change 移到 archive | -y, --skip-specs, --no-validate, --require-sync, --json |

delta spec 固定放在 specs/<capability>/spec.md, 恰好一層, 更深的目錄不會被合併. 完全沒有行為變更的 change (工具, CI, 純文件) 在 .tospec.yaml 設 skip_specs: true 就好, 不要為了過驗證捏造 requirement.

requirement 內文慣例上要有 SHALL 或 MUST, 缺了是 WARNING; --strict 才會把它當錯誤.

給 AI 工具的指令

| 指令 | 作用 | 選項 | |------|------|------| | tospec instructions [artifact] | 回傳建立文件的完整指引; artifact 填 apply 回傳實作指引 | --change <id>, --schema <name>, --json | | tospec schemas | 列出可用的 schema 與其文件 | --json | | tospec templates | 顯示 schema 中各文件範本的路徑 | --schema <name>, --json |

Dashboard

tospec dashboard start    # 在背景啟動 hub
tospec dashboard status   # 是否在執行, session 數量, 各 session 所屬的 project
tospec dashboard stop     # 停止 hub

本機 web dashboard hub, 一個 service 服務所有 project, 在任何目錄都能啟動. Hub 不讀專案檔案:

1. tospec init / tospec update 把 Claude Code mod 寫到 .claude/skills/tospec-dashboard/.
2. Session 啟動後, mod 自動向 hub 註冊, 並推送 project 快照. 同一個 project 的多個 session 都可以註冊, 以最後推送的快照為準. Dashboard 的 Sessions 區塊會列出目前連線的 session 數量和 session id, 並標出提供目前快照的 session.
3. Mod 在編輯 tospec/ 檔案後和每個 turn 結束時推送新快照. Hub 沒有啟動時, mod 會靜默略過並定期重試.
4. Claude Code 只在你對這個專案資料夾本身接受信任對話框之後, 才會載入 .claude/skills/ 下的 plugin. 只信任上層資料夾不夠. 如果上層資料夾已被信任, 對話框不會出現, mod 也不會載入. 這時 claude plugin list 會顯示 "skipped because this workspace was not trusted".
5. Claude Code 介面右下角顯示 hub 狀態 (tospec hub: connected / offline / unregistered / error). 用 /tospec-dashboard register, /tospec-dashboard unregister 手動註冊或取消註冊, 不帶參數則顯示目前狀態.
6. Mod 也回報每個 session 的狀態 (工作中 / 等你回覆 / 閒置) 與即時 log (prompt, Claude 的回覆, tool 呼叫). 點 session 會在右側開啟面板, 可以看 log, 回答 AskUserQuestion, 以及允許或拒絕權限請求. Dashboard 只能回答 session 提出的問題, 不能送出其他輸入; 指示一律在 terminal 輸入.
7. Session 開始等你回覆, 或一個回合結束而閒置時, 頁面右下角會跳出 Toast; 點一下就開啟該 project 與這個 session 的面板. 在上方工具列開啟「通知」後, 頁面不在前景時也會跳出瀏覽器通知.

勾 task checkbox 由 hub 轉給該 project 的 session 執行, 已歸檔或 sync 通過的 change 不能勾. 沒有 session 的 project 只能瀏覽最後一次快照.

從 dashboard 回答問題或允許權限, 等於讓 session 執行 tool, 所以只有 hub 綁在 loopback 時才開放; 加上 --allow-remote 時 dashboard 只能檢視. 權限請求與 AskUserQuestion 會同時出現在 terminal 與 dashboard, 先回答的一方有效; 在 terminal 回答後, dashboard 會自動撤回這個問題, 不會重複回應.

start 的選項: -p, --port <n> (預設 5620; mod 預設連 http://127.0.0.1:5620, 可用環境變數 TOSPEC_DASHBOARD_URL 改變), --host <addr> (預設 127.0.0.1), -o, --open, --allow-remote (綁非 loopback 位址, 會對外網開放).

文件

• Agent 契約: --json 的成功/失敗封包與 exit code
• 自訂 schema: schema.yaml 欄位, 解析順序, 佈局限制
• CHANGELOG: 各版本的變更與根因說明

授權

MIT