tospec

Spec-driven development CLI — 用 schema 定義文件與流程, 讓每個開發階段都能被檢查. 進度由檔案推算, 工作方法寫在 Skill 裡.

tospec 把需求釐清, 規格, 設計, 任務, 實作到歸檔串成一套工作流程. Skill 協助 AI 工具 (Claude Code / Codex) 處理各階段, CLI 負責建立檔案, 檢查狀態與驗證規格格式. 它不另外維護狀態資料庫; status 會依 change 目錄裡有哪些檔案, 推算目前進度.

安裝

需要 Node.js >=22.22.0.

npm install -g @seanmars/tospec

安裝後即可使用 tospec 指令:

tospec --help
tospec --version

也可以不安裝, 直接用 npx:

npx @seanmars/tospec --help

快速開始

# 1. 在專案根目錄初始化, 並安裝 Claude Code 的 Skill
tospec init --tools claude

# 2. 建立一個新需求 change
tospec new change add-dark-mode --schema sdd

# 3. 查看目前各文件的狀態
tospec status --change add-dark-mode

# 4. 驗證文件格式
tospec validate add-dark-mode

# 5. 完成後歸檔, 把規格合併進主 specs
tospec archive add-dark-mode

--tools 可填 claude, codex, all 或 none. 初始化後會建立 tospec/ 目錄與 Skill; Claude Code 另外會產生 /tosx:<name> 快捷指令.

兩種工作流程

建立 change 時用 --schema 選擇流程:

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

兩者都在 apply 階段實作, 最後由 archive 判斷是否需要先 sync 再歸檔. apply 以完整測試與 tospec validate 通過為完成標準; verify (雙軸審查) 是 opt-in, 只有使用者主動要求時才執行, apply 不會自己跑, 也不會主動詢問.

文件狀態的判斷方式:

• done — 對應檔案已存在
• ready — 前置文件都已建立, 這份還沒有, 可以開始
• blocked — 至少一個前置文件還沒建立
• skipped — 選配文件未建立, 不阻擋流程

Skill 工作流程

工作方法寫在 Skill 裡, CLI 只負責檔案與驗證. tospec init 會安裝 10 個 workflow Skill:

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

典型流程: explore (想清楚) → propose (寫成 change) → apply (實作) → sync (需要時核對規格) → archive (歸檔). 修 bug 則從 issue 開始, 走同樣的 apply → archive 收尾.

CLI 指令

多數指令支援 --json, 方便 AI 工具讀取結果.

專案管理

| 指令 | 作用 | |------|------| | tospec init [path] | 初始化專案, 建立 tospec/ 與 Skill. 選項: --tools <claude\|codex\|all\|none>, --force, --profile <name> | | tospec update [path] | 重新產生已設定的 Skill, 修復連結或複製檔案. 選項: --force | | tospec migrate [openspec-dir] | 把 OpenSpec 專案轉成 tospec 格式 (預設讀 ./openspec). 選項: -f, --force | | tospec config <sub> | 全域設定. 子命令: path, list, get <key>, set <key> <value>, unset <key>, reset, edit, profile [preset] (調整要安裝的 Skill) |

建立與查詢

| 指令 | 作用 | |------|------| | tospec new change <name> | 建立 change 目錄與 ticket 索引檔. 選項: --schema <sdd\|issue>, --description <text>, --goal <text>, --decisions <files>, --json | | tospec list | 列出進行中的 change (預設). 選項: --specs, --changes, --sort <recent\|name>, --type <requirement\|issue>, --json | | tospec show [item-name] | 顯示 change 或 spec 內容. 選項: --type <change\|spec>, --deltas-only, --requirements, --no-scenarios, -r, --requirement <id>, --no-interactive, --json | | tospec status | 依檔案與 schema 顯示各文件狀態. 選項: --change <id>, --schema <name>, --json | | tospec decision new <topic> | 建立 ADR (tospec/decisions/<yyyyMMdd_HHmmss>-<topic>.md) 與索引列. 選項: --title <text>, --summary <text>, --date <yyyyMMdd_HHmmss>, --status <proposed\|accepted\|superseded>, --force, --json | | tospec decision list | 以索引表列出 ADR. 選項: --status <proposed\|accepted\|superseded>, --sort <date\|name>, --json | | tospec skill-metrics | 開啟本機網頁, 以圖表呈現每個 Skill 的耗時. 選項: --no-open |

tospec skill-metrics 會在 loopback 上啟動一台伺服器, 印出網址、開啟瀏覽器, 並停在前景直到 Ctrl+C. 連接埠固定從 26693 開始; 若已被占用則自動往上遞增直到找到可用的, 所以再開一個也不會失敗. 網頁是唯一的輸出形式, 沒有表格也沒有 --json; --no-open 只印網址而不開瀏覽器, 供沒有瀏覽器的環境使用.

頁面共五張圖: 各 Skill 的總投入時間 (實色為 engaged, 凹陷部分為 idle, 整根長度即 span)、典型的單次時長 (engaged 與 span 的中位數)、每次執行的分佈 (每一次 run 都是一個點)、每日投入時間, 以及執行時間軸. 總量與中位數刻意分成兩張: 一個 Skill 可能總量第一但每次都很短, 那是次數多而不是每次慢.

時間範圍、idle gap、split gap 都可在頁面上調整並即時重算, 選擇會記在瀏覽器中; 「只看 tospec workflow」單純隱藏列, 不重新計算. 右上角可切換主題與語言 (English / 正體中文), 兩者同樣會被記住. 終端機輸出維持英文, 與其他指令一致.

資料同時來自 Claude Code 與 Codex 兩種工具的紀錄, 一律唯讀且不寫入任何檔案. Claude Code 讀取 transcript 的 attributionSkill 欄位 (只存在於較新的 session, 舊紀錄無法回溯統計); Codex 的 session 沒有對應欄位, 因此改用推論 — 只要偵測到某個 Skill 的 SKILL.md 被讀取, 就視為該 Skill 開始執行. 由於 Codex 的歸屬是推論而非直接紀錄, 兩者精準度不同, 頁面上一律分開呈現、絕不合併成同一個數字, Codex 的數字並附上這項說明. 每一列的標籤結尾都會標上來源工具 (Claude/Codex), 兩者皆標而非只標其中一方, 以免另一方被讀成預設值. 頁面在統計為空時, 會分別指出兩種工具各自屬於哪一種情況.

驗證與歸檔

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

delta spec 的位置固定為 specs/<capability>/spec.md, 恰好一層: 更深的巢狀目錄不會被合併, 驗證會直接報錯. 完全沒有行為變更的 change (工具, CI, 純文件) 在 .tospec.yaml 設 skip_specs: true 宣告即可, 不要為了通過驗證捏造 requirement.

給 AI 工具的指令

| 指令 | 作用 | |------|------| | tospec instructions [artifact] | 回傳建立文件或套用任務的完整指引 (artifact 填 apply 時回傳實作指引). 選項: --change <id>, --schema <name>, --json | | tospec schemas | 列出可用的工作流程 schema 與其文件. 選項: --json | | tospec templates | 顯示指定 schema 中各文件範本的實際路徑. 選項: --schema <name>, --json |

Dashboard

tospec dashboard [path]

啟動本機唯讀 web dashboard, 檢視 change 與 specs 進度. 選項: -p, --port <n> (預設 5620), --host <addr> (預設 127.0.0.1), -o, --open (啟動後開啟瀏覽器), -d, --detach (背景執行), --stop (停止本專案的 dashboard), -l, --list (列出所有執行中的 dashboard), --allow-remote (允許綁定非 loopback 位址, 會對外網開放).

文件

• Agent 契約 —— --json 的成功/失敗封包與 exit code
• 自訂 schema —— schema.yaml 欄位, 解析順序, 佈局限制

更新日誌

各版本的變更與其根因說明: CHANGELOG.md

授權

MIT