@seanmars/tospec 0.4.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 seanmars
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# tospec
+
+> Spec-driven development CLI — 用 schema 定義文件與流程, 讓每個開發階段都能被檢查. 進度由檔案推算, 工作方法寫在 Skill 裡.
+
+tospec 把需求釐清, 規格, 設計, 任務, 實作到歸檔串成一套工作流程. Skill 協助 AI 工具 (Claude Code / Codex) 處理各階段, CLI 負責建立檔案, 檢查狀態與驗證規格格式. 它不另外維護狀態資料庫; `status` 會依 change 目錄裡有哪些檔案, 推算目前進度.
+
+## 安裝
+
+需要 Node.js `>=22.22.0`.
+
+```bash
+npm install -g @seanmars/tospec
+```
+
+安裝後即可使用 `tospec` 指令:
+
+```bash
+tospec --help
+tospec --version
+```
+
+也可以不安裝, 直接用 `npx`:
+
+```bash
+npx @seanmars/tospec --help
+```
+
+## 快速開始
+
+```bash
+# 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** 階段實作 (apply 最後會自動執行 verify), 最後由 **archive** 判斷是否需要先 **sync** 再歸檔.
+
+文件狀態的判斷方式:
+
+- `done` — 對應檔案已存在
+- `ready` — 前置文件都已建立, 這份還沒有, 可以開始
+- `blocked` — 至少一個前置文件還沒建立
+- `skipped` — 選配文件未建立, 不阻擋流程
+
+## 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 list` | 查看全域設定; `tospec config profile` 可調整要安裝的 Skill |
+
+### 建立與查詢
+
+| 指令 | 作用 |
+|------|------|
+| `tospec new change <name>` | 建立 change 目錄與 ticket 索引檔. 選項: `--schema <sdd\|issue>`, `--description <text>`, `--goal <text>`, `--json` |
+| `tospec list` | 列出進行中的 change (預設). 選項: `--specs`, `--changes`, `--sort <recent\|name>`, `--type <requirement\|issue>`, `--json` |
+| `tospec show [item-name]` | 顯示 change 或 spec 內容. 選項: `--type <change\|spec>`, `--deltas-only`, `--json` |
+| `tospec status` | 依檔案與 schema 顯示各文件狀態. 選項: `--change <id>`, `--schema <name>`, `--json` |
+
+### 驗證與歸檔
+
+| 指令 | 作用 |
+|------|------|
+| `tospec validate [item-name]` | 檢查必要段落與 delta spec 格式. 選項: `--all`, `--changes`, `--specs`, `--type <change\|spec>`, `--strict`, `--concurrency <n>`, `--json` |
+| `tospec archive [change-name]` | 重新驗證, 合併 delta specs 到主 specs, 再把 change 移到 archive. 選項: `-y, --yes`, `--skip-specs`, `--no-validate`, `--require-sync`, `--json` |
+
+### 給 AI 工具的指令
+
+| 指令 | 作用 |
+|------|------|
+| `tospec instructions [artifact]` | 回傳建立文件或套用任務的完整指引 (artifact 填 `apply` 時回傳實作指引). 選項: `--change <id>`, `--schema <name>`, `--json` |
+| `tospec schemas` | 列出可用的工作流程 schema 與其文件. 選項: `--json` |
+| `tospec templates` | 顯示指定 schema 中各文件範本的實際路徑. 選項: `--schema <name>`, `--json` |
+
+### Dashboard
+
+```bash
+tospec dashboard [path]
+```
+
+啟動本機唯讀 web dashboard, 檢視 change 與 specs 進度. 選項: `--port <n>` (預設 5620), `--host <addr>` (預設 127.0.0.1), `--open` (啟動後開啟瀏覽器).
+
+## 授權
+
+[MIT](./LICENSE)