@seanmars/tospec 0.4.2

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@seanmars/tospec",
+  "version": "0.4.2",
+  "description": "Spec-driven development CLI for structured requirements and issue workflows",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "sdd",
+    "spec-driven-development",
+    "requirements",
+    "cli"
+  ],
+  "type": "module",
+  "bin": {
+    "tospec": "./bin/tospec.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "bin",
+    "schemas",
+    "assets"
+  ],
+  "scripts": {
+    "build": "node build.js",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "prepack": "node build.js",
+    "prepublish": "node build.js"
+  },
+  "engines": {
+    "node": ">=22.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
+  },
+  "dependencies": {
+    "@inquirer/core": "^11.2.1",
+    "@inquirer/prompts": "^8.5.2",
+    "commander": "^15.0.0",
+    "fast-glob": "^3.3.3",
+    "marked": "^18.0.6",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
+  }
+}

package/schemas/issue/schema.yaml

@@ -0,0 +1,34 @@
+name: issue
+version: 1
+description: Diagnosis and repair workflow for issues
+artifacts:
+  # ticket 是 CLI 管理的全域索引 (tospec/tickets/<yyyyMMdd_HHmmss>-<name>.md),
+  # 不是 graph artifact: 由 `tospec new change` 自動產生於 change 目錄之外, 故不列於此。
+  - id: task
+    generates: task.md
+    description: Root-cause diagnosis and repair plan
+    template: task.md
+    requires: []
+    instruction: |
+      診斷並撰寫 issue task: 先建立 tight feedback loop (一個指令能讓
+      這個 bug 變 red), 列 3-5 個可否證的假設並排序, 逐一驗證後寫下根因。
+      內容: 根因分析、修正方案、測試計畫 (既有測試為何沒抓到 / 缺哪些
+      edge case)、任務 checkbox 清單。
+    validation:
+      requiredSections: [Feedback Loop, Root Cause, Fix Plan, Test Plan, Tasks]
+  - id: specs
+    generates: specs/**/*.md
+    description: Optional behavior-changing delta specifications
+    template: spec.md
+    requires: []
+    optional: true
+    instruction: |
+      僅當修正會改變對外行為時撰寫 delta specs (文法同 sdd)。
+      若 bug 源於 spec 本身錯誤, 用 MODIFIED 修正該 Requirement。
+apply:
+  requires: [task]
+  tracks: task.md
+  instruction: |
+    依 task.md 修正: 先確認是否已有相關測試 —
+    有且失敗 → 找出為何失敗; 有且通過 → 檢查 edge case 缺漏, 補測試;
+    沒有 → 先寫會 red 的回歸測試。修到全綠, 並驗證符合 task.md 規範。

package/schemas/issue/templates/spec.md

@@ -0,0 +1,13 @@
+## ADDED Requirements
+
+### Requirement: [名稱]
+[系統 SHALL/MUST ... 的行為描述 — 關鍵字必須在內文, 不能只在標題]
+
+#### Scenario: [情境名稱]
+- **WHEN** [條件]
+- **THEN** [結果]
+- **AND** [附加結果]
+
+<!-- 亦可使用 MODIFIED、REMOVED、RENAMED Requirements。
+MODIFIED 必須包含完整更新後的 requirement 區塊。
+REMOVED 必須包含 Reason 與 Migration；RENAMED 使用 FROM/TO 配對。 -->

package/schemas/issue/templates/task.md

@@ -0,0 +1,21 @@
+# Task: [issue 名稱]
+
+## Feedback Loop
+[能讓這個 bug 變 red 的單一指令]
+
+## Root Cause
+[驗證過的根因 — 不是猜測; 附驗證方式]
+
+## Fix Plan
+[修正方案與理由; 為什麼修這裡是根因修法而非症狀修法]
+
+## Test Plan
+- 既有測試為何沒抓到: [分析]
+- 需補的測試 / edge cases: [清單]
+
+## Tasks
+### 1. 修正
+- [ ] 1.1 撰寫回歸測試 (red)
+- [ ] 1.2 實作修正至測試通過 (green)
+- [ ] 1.3 補 edge case 測試: [...]
+- [ ] 1.4 跑完整測試套件確認無回歸

package/schemas/issue/templates/ticket.md

@@ -0,0 +1,2 @@
+## Summary
+[一句話描述這個 issue 的現象 — 詳細根因/重現/修法見 task.md]

package/schemas/sdd/schema.yaml

@@ -0,0 +1,55 @@
+name: sdd
+version: 1
+description: Spec-driven development workflow for new requirements
+artifacts:
+  # ticket 是 CLI 管理的全域索引 (tospec/tickets/<yyyyMMdd_HHmmss>-<name>.md),
+  # 不是 graph artifact: 由 `tospec new change` 自動產生於 change 目錄之外, 故不列於此。
+  - id: proposal
+    generates: proposal.md
+    description: Main proposal — why, what changes, capabilities, impact
+    template: proposal.md
+    requires: []
+    instruction: |
+      承載主要細節: Why (動機, 為什麼現在做)、What Changes (具體新增/修改/移除)、
+      Capabilities (New/Modified capability 與對應 specs)、Impact (受影響的程式/API/相依/系統)。
+      這是 specs 與 design 展開的依據; 禁止寫入檔案路徑與程式碼片段 (會過時)。
+    validation:
+      requiredSections: [Why, What Changes, Impact]
+      minSectionLength:
+        Why: 50
+  - id: specs
+    generates: specs/**/*.md
+    description: Delta specifications for affected capabilities
+    template: spec.md
+    requires: [proposal]
+    instruction: |
+      依 proposal 撰寫 delta specs。每個 capability 一個檔案。
+      文法: ## ADDED|MODIFIED|REMOVED|RENAMED Requirements /
+      ### Requirement: <名稱> (內文必須含 SHALL 或 MUST) /
+      #### Scenario: <名稱> (四個 #, WHEN/THEN/AND bullet)。
+      MODIFIED 必須貼上完整更新後的 requirement 區塊。
+  - id: design
+    generates: design.md
+    description: Technical design and testing seams
+    template: design.md
+    requires: [proposal]
+    instruction: |
+      技術設計: Context、Goals/Non-Goals、Decisions、測試 seam 的選定
+      (優先沿用既有 seam, 越高層越好, 數量越少越好)、Risks、Open Questions。
+    validation:
+      requiredSections: [Context, Decisions, Testing Seams]
+  - id: tasks
+    generates: tasks.md
+    description: TDD tracer-bullet implementation slices
+    template: tasks.md
+    requires: [specs, design]
+    instruction: |
+      把 specs + design 切成 tracer-bullet 垂直切片任務。
+      每個任務群組 = 一條窄而完整的路徑 (可獨立驗證)。
+      每個實作任務前面都要有對應的「先寫測試」任務 (TDD red 先行)。
+apply:
+  requires: [tasks]
+  tracks: tasks.md
+  instruction: |
+    依 tasks.md 以 TDD 執行: 每個切片先寫失敗測試 (red), 再實作到通過 (green),
+    只測 design.md 選定的 seam。完成後對照 specs 驗證行為一致。

package/schemas/sdd/templates/design.md

@@ -0,0 +1,15 @@
+# Design: [change 名稱]
+
+## Context
+
+## Goals / Non-Goals
+
+## Decisions
+[每個決策: 選了什麼 / 考慮過什麼 / 為什麼]
+
+## Testing Seams
+[測試切入點: 沿用哪個既有 seam, 或新增哪個; 為什麼是這一層]
+
+## Risks / Trade-offs
+
+## Open Questions

package/schemas/sdd/templates/proposal.md

@@ -0,0 +1,15 @@
+## Why
+<!-- 動機: 解決什麼問題, 為什麼現在做 (>= 50 字) -->
+
+## What Changes
+<!-- 具體變更: 新增 / 修改 / 移除 了什麼 -->
+
+## Capabilities
+### New Capabilities
+- `<name>`: <描述> (對應 specs/<name>/spec.md)
+
+### Modified Capabilities
+- `<existing-name>`: <改變的 requirement>
+
+## Impact
+<!-- 受影響的程式 / API / 相依 / 系統 -->

package/schemas/sdd/templates/spec.md

@@ -0,0 +1,13 @@
+## ADDED Requirements
+
+### Requirement: [名稱]
+[系統 SHALL/MUST ... 的行為描述 — 關鍵字必須在內文, 不能只在標題]
+
+#### Scenario: [情境名稱]
+- **WHEN** [條件]
+- **THEN** [結果]
+- **AND** [附加結果]
+
+<!-- 亦可使用 MODIFIED、REMOVED、RENAMED Requirements。
+MODIFIED 必須包含完整更新後的 requirement 區塊。
+REMOVED 必須包含 Reason 與 Migration；RENAMED 使用 FROM/TO 配對。 -->

package/schemas/sdd/templates/tasks.md

@@ -0,0 +1,11 @@
+# Tasks: [change 名稱]
+
+## 1. [切片名稱 — 一條垂直路徑]
+- [ ] 1.1 撰寫失敗測試: [對應的 Scenario 名稱]
+- [ ] 1.2 實作至測試通過
+- [ ] 1.3 對照 spec 驗證行為
+
+## 2. [下一個切片]
+- [ ] 2.1 撰寫失敗測試
+- [ ] 2.2 實作至測試通過
+- [ ] 2.3 對照 spec 驗證行為

package/schemas/sdd/templates/ticket.md

@@ -0,0 +1,2 @@
+## Summary
+[一句話描述這個 change 要做什麼 — 詳細 why/what/capabilities/impact 見 proposal.md]