diff --git a/schemas/sdd-plus-superpowers/INTEGRATION.md b/schemas/sdd-plus-superpowers/INTEGRATION.md new file mode 100644 index 000000000..d8ced8f48 --- /dev/null +++ b/schemas/sdd-plus-superpowers/INTEGRATION.md @@ -0,0 +1,313 @@ +# OpenSpec × Superpowers 整合狀況 + +> 本文件說明 `sdd-plus-superpowers` schema 如何把 OpenSpec 的 artifact 治理流程與 +> Superpowers 的執行技能整合為單一工作流。適合作為新成員 onboarding、change review +> 時的對照表,以及日後修改 schema 前必讀。 +> +> 對應 schema 版本:`sdd-plus-superpowers` v1 + +--- + +## 一、整合的本質:什麼掛在哪裡 + +OpenSpec 負責 **「做什麼」(WHAT)**—— proposal / specs / design / tasks 這些 markdown artifact 的治理、驗證、歸檔。 +Superpowers 負責 **「怎麼做」(HOW)**—— brainstorming 對話、TDD 紀律、subagent 派發、code review 等**執行技能**。 + +兩者透過自定義 schema [schema.yaml](./schema.yaml) 整合。整合手法不是程式碼層級,而是在 OpenSpec 的 artifact instruction 裡寫「在這一步 use the Skill tool to invoke `superpowers:xxx`」。**不修改任一 superpowers skill 檔案**,也不修改 OpenSpec CLI —— 純粹透過 instruction 層串接。 + +--- + +## 二、7 個 Superpowers 觸點一覽 + +| # | Superpowers skill | 掛在哪 | 觸發方式 | +|---|---|---|---| +| 1 | `superpowers:brainstorming` | `brainstorm` artifact instruction | 直接 | +| 2 | `superpowers:writing-plans` | `plan` artifact instruction | 直接 | +| 3 | `superpowers:using-git-worktrees` | apply step 1 | 直接 | +| 4 | `superpowers:subagent-driven-development` | apply step 2a | 直接 | +| 5 | `superpowers:test-driven-development` | (#4 內部自動觸發) | **傳遞**(SKILL.md L205 / L274) | +| 6 | `superpowers:requesting-code-review` | (#4 內部自動觸發) | **傳遞**(SKILL.md L270) | +| 7 | `superpowers:finishing-a-development-branch` | apply step 4 | 直接 | + +另外還有一個 **fallback**: + +- `superpowers:executing-plans`(apply step 2b)—— 只在「當前平台無 subagent 支援」時才用。Claude Code 上永遠用 2a。依據 `superpowers:executing-plans` SKILL.md L14 原文:「If subagents are available, use `superpowers:subagent-driven-development` instead of this skill」。 + +--- + +## 三、Artifact DAG(含 superpowers 注入點) + +``` +┌──────────────┐ +│ brainstorm │ ◄── superpowers:brainstorming +│ (root) │ (2-3 方案 + Alternatives Considered) +└──────┬───────┘ + │ + ├──► ┌──────────┐ + │ │ proposal │ Why (50-1000 字元) / What Changes / Capabilities + │ └────┬─────┘ + │ │ + │ ▼ + │ ┌──────────────────┐ + │ │ specs/**/*.md │ ADDED / MODIFIED / REMOVED / RENAMED + │ │ (delta specs) │ 每 requirement 含 SHALL/MUST + scenario + │ └────┬─────────────┘ + │ │ + │ ▼ + │ ┌──────────┐ + │ │ tasks │ 粗粒度 checkbox(apply 的追蹤載體) + │ └────┬─────┘ + │ │ + │ ▼ + │ ┌──────────┐ + │ │ plan │ ◄── superpowers:writing-plans + │ └────┬─────┘ (2-5 分鐘 micro-step) + │ │ + │ │ ─────────┐ + │ │ │ + │ │ ┌────▼──────┐ + │ │ │ apply │ ◄── superpowers:using-git-worktrees + │ │ │ (phase) │ ◄── superpowers:subagent-driven-development + │ │ │ │ ├── superpowers:test-driven-development (transitive) + │ │ │ │ └── superpowers:requesting-code-review (transitive) + │ │ │ │ ◄── superpowers:finishing-a-development-branch + │ │ └────┬──────┘ + │ │ │ + ▼ ▼ ▼ + ┌──────────┐ ┌──────────┐ + │ design │ │ verify │ ◄── openspec-verify-change (5 checks) + │ (optional)│ └──────────┘ + └──────────┘ +``` + +**注意幾件事**: + +- `design` 是**可選的 leaf**。brainstorm 仍會嘗試預填 design.md,但 tasks 不再硬依賴(`tasks.requires: [specs]`)。依據 OpenSpec conventions:`design.md` 只在需要解釋非 trivial 技術決策時才寫。 +- `verify` 的 `requires: [plan]` 是為了讓 schema graph 完整;它的 instruction 明寫「**MUST run on a completed implementation, NOT during planning**」。這是 OpenSpec DAG 與實際時序的刻意錯位,為的是讓 `openspec status` 能顯示 verify 進度。 +- `apply` 不產生 artifact,它是一個 **phase**,改動的是 source code + tasks.md checkbox。 + +--- + +## 四、完整開發 workflow(一次 change 的生命週期) + +### 步驟 0:決定是否走 change 流程 + +先問自己:這是行為變更嗎? + +| 類型 | 是否需要 change | 用哪個 schema | +|---|---|---| +| 新功能 / 新 capability | ✅ 需要 | `sdd-plus-superpowers` | +| Breaking change | ✅ 需要 | `sdd-plus-superpowers` | +| 架構變更 | ✅ 需要 | `sdd-plus-superpowers` | +| Bug fix(恢復原本行為) | ❌ 不需要 | 直接 PR | +| 測試補寫 / 覆蓋率 | ❌ 不需要 | 直接 PR | +| 建置工具微調(linter 規則、覆蓋率門檻等) | ❌ 不需要 | 直接 PR | +| 依賴升級(非破壞性) | ❌ 不需要 | 直接 PR | +| 文件更新 | ❌ 不需要 | 直接 PR | + +這個判斷邏輯寫在 [openspec/specs/README.md](../../specs/README.md) 的「何時不建立 Spec」段。 + +--- + +### 步驟 1:建立 change + 進入 brainstorming + +```bash +/opsx:new my-feature --schema sdd-plus-superpowers +# → 建立 openspec/changes/my-feature/ 空目錄 + .openspec.yaml +# → 顯示 brainstorm artifact 的 instructions +``` + +接著: + +```bash +/opsx:continue +# → 觸發 brainstorm artifact +# → instruction 說「use the Skill tool to invoke superpowers:brainstorming」 +# → 進入多輪互動對話:context 探索 → 釐清問題 → 2-3 方案 + 取捨 → 批准設計 +# → 對話結束後寫入 brainstorm.md(含 Alternatives Considered) +# → 若有產出設計文件,同時寫入 design.md(預填) +``` + +**關鍵**:這一步是整個流程的對齊儀式。後續的 proposal / specs 都是從 brainstorm.md 萃取出來的。 + +--- + +### 步驟 2:串行產出 proposal → specs → tasks → plan + +可以 `/opsx:continue` 一步步做(每一步都有人類 review 機會),也可以 `/opsx:ff` 一口氣補齊剩下所有 artifact。 + +| 步驟 | 產物 | 關鍵規則 | +|---|---|---| +| 2a | `proposal.md` | Why 段 50-1000 字元;Capabilities 區段列出新增 / 修改的 capability | +| 2b | `specs//spec.md` | 4 種 delta(ADDED / MODIFIED / REMOVED / RENAMED);每 requirement 含 SHALL/MUST + `#### Scenario:` | +| 2c (opt) | `design.md` | 只有需要解釋技術決策時才寫;brainstorm 可能已經預填 | +| 2d | `tasks.md` | 粗粒度 checkbox(`- [ ] X.Y 描述`),會被 apply 追蹤進度 | +| 2e | `plan.md` | `/opsx:continue` 觸發 `superpowers:writing-plans`,把 tasks 拆成 2-5 分鐘 micro-step | + +完成後跑: + +```bash +openspec validate --all --json +# → 本地 git hook 已經掛了 pre-commit,commit 時會自動驗證 +``` + +--- + +### 步驟 3:Apply(實作階段) + +```bash +/opsx:apply +``` + +這會觸發 [schema.yaml](./schema.yaml) `apply.instruction` 的 4 個步驟: + +#### 3-1. Workspace — 呼叫 `superpowers:using-git-worktrees` + +- 建立 `.worktrees//` 隔離工作區 +- 切到新 branch +- 跑專案 setup、確認 test baseline 乾淨 + +#### 3-2. Executor — 呼叫 `superpowers:subagent-driven-development`(2a 預設路徑) + +- Main agent 讀 plan.md,為每個 micro-task **派發 fresh subagent** +- 每個 subagent 內部會自動: + - **TDD enforcement**(`superpowers:test-driven-development` 傳遞觸發) + - 先寫 failing test + - 看著它 fail + - 寫最小程式碼讓它 pass + - 寫 production code **前**沒測試?刪掉重來 + - **Per-task code review**(`superpowers:requesting-code-review` 傳遞觸發) + - spec compliance review(有符合 plan 嗎?) + - code quality review(有 smell 嗎?) + - Critical issue 擋下進度 +- Coarse task 完成就更新 `tasks.md` checkbox +- 全部 task 跑完後,對整個 implementation 再做一次 final code review + +> **2b fallback**:只在當前平台沒有 subagent 支援時才改用 `superpowers:executing-plans`。Claude Code 有 subagent,所以永遠用 2a。若被迫使用 2b,需自行手動維持 TDD 紀律並呼叫 `superpowers:requesting-code-review`。 + +#### 3-3. Verification — 呼叫 `openspec-verify-change`(產出 `verify.md`) + +5 項檢查: + +1. **Structural validation**:`openspec validate --all --json` 全部 PASS +2. **Task completion**:`tasks.md` 所有 `- [ ]` 變 `- [x]` +3. **Delta spec sync state**:`changes//specs/` 是否已 sync 到 `openspec/specs/` +4. **Design / specs coherence**:抽查 design 決策與 specs requirement 是否一致(非阻塞警告) +5. **Implementation signal**:worktree 沒有未 staged 檔案 + +若有失敗項目,退回對應 artifact 修正後重跑 verify。 + +#### 3-4. Completion — 呼叫 `superpowers:finishing-a-development-branch` + +- 確認 tests 全綠 +- 呈現選項:merge / PR / keep branch / discard +- 清理 worktree + +--- + +### 步驟 4:Archive + +```bash +/opsx:archive my-feature +``` + +- 驗證 + 檢查 task 完成度(未完成會 warn,不 block) +- 同步 delta specs 回 `openspec/specs//spec.md` + - 順序:RENAMED → REMOVED → MODIFIED → ADDED + - 若已手動 sync 過,可用 `--skip-specs` +- 把 `changes/my-feature/` 整個搬到 `changes/archive/YYYY-MM-DD-my-feature/` +- 歷史定格,unix 時間線視為 source of truth + +--- + +## 五、實際 CLI cheat sheet + +| 情境 | 指令 | +|---|---| +| **首次 clone 專案後** | `bash scripts/install-git-hooks.sh` | +| 新 change(互動式一步步) | `/opsx:new --schema sdd-plus-superpowers` 接著 `/opsx:continue` 若干次 | +| 新 change(一鍵補齊所有 artifact) | `/opsx:ff ` | +| 恢復中斷的 change | `/opsx:continue ` | +| 進入實作 | `/opsx:apply ` | +| 手動 verify | `/opsx:verify ` | +| 歸檔 | `/opsx:archive ` | +| 用原生 OpenSpec schema(跳過 brainstorm) | `/opsx:new --schema spec-driven` | +| 查看專案所有 schema | `openspec schemas` | +| 查看當前 change 進度 | `openspec status --change --json` | +| 列出 active changes | `openspec list` | +| 全專案驗證 | `openspec validate --all --json` | + +--- + +## 六、整合的精巧之處(值得記住的 5 個設計) + +### 1. Output redirection + +Superpowers 的 brainstorming 原本會寫到 `docs/superpowers/specs/`,writing-plans 寫到 `docs/superpowers/plans/`。我們的 artifact instruction **覆寫這個行為**,透過 prompt 上下文注入「寫到 change 目錄」的指示。不改 superpowers 源碼、不改 OpenSpec CLI。 + +### 2. Schema-level vs prompt-level 整合 + +整合完全發生在 `instruction` 欄位(純 prompt)。如果 superpowers 升級了某個 skill 的行為,我們**完全不用動 schema**。只有當 skill 被重新命名或移除時才需要 touch schema.yaml。 + +### 3. 傳遞依賴顯式化 + +TDD 和 code-review 原本藏在 subagent-driven-development 內部(SKILL.md 裡才看得到)。schema 在 apply step 2a 的 instruction 裡**直接列出**這兩個 transitive activation,讓讀者一眼就看懂「apply 階段到底會發生什麼」。 + +### 4. Fallback 路徑誠實標註 + +2b(executing-plans)存在但標為「platforms without subagent support」的 fallback,引用 superpowers 官方 SKILL.md L14 原文。我們不發明「小 change 用 2b」這種自創規則。 + +### 5. Verify 是 schema graph 的 leaf 但實際在 apply 之後 + +`verify` 的 `requires: [plan]` 只是為了讓 schema graph 完整;它的 instruction 明寫「**MUST run on a completed implementation, NOT during planning**」。這是 OpenSpec DAG 與實際時序的刻意錯位,為的是讓 `openspec status` 能顯示 verify 進度。 + +--- + +## 七、採用本 schema 的專案建議補充一個 snapshot 區段 + +建議每個採用 `sdd-plus-superpowers` 的專案,在自家 repo 的對應文件裡維護一份如下格式的 snapshot,讓新成員 onboarding 時一眼看清楚「本 repo 現在長什麼樣」: + +```markdown +## 本專案現況(snapshot: YYYY-MM-DD) + +- **OpenSpec CLI**:v +- **Schema**:`sdd-plus-superpowers` v +- **Specs(bounded-context 粒度)**: domain 存在、 domain 預留 lazy backfill + - 已存在:`` / `` / ... + - 預留:`` / ... +- **Automation**: +- **Superpowers plugin**:`superpowers@` 安裝於 ``,本整合用到 N 個 skill +``` + +> 此 snapshot 區段會隨時間 stale,權威狀態請用 `openspec list` + `openspec schemas` 現場查。 + +--- + +## 八、最重要的一件事 + +整合的核心價值不是「把很多 skill 串起來」,而是: + +> **把「需求對齊」(OpenSpec)和「嚴謹執行」(Superpowers)接起來,讓一個 change 從「想做什麼」到「code 已經通過 TDD + code review」這整條路徑全部可追溯、可重跑、可審計。** + +傳統流程的斷點是: + +- 需求在 Slack / 對話中 → apply 階段 LLM 靠記憶做事 → 對不上 spec +- 或:spec 寫在 Confluence → code 在 repo → 兩者漂移 + +sdd-plus-superpowers 的兩層約束解決這個問題: + +1. **OpenSpec 的 delta spec 治理** → 確保「要做什麼」不會漂移 +2. **Superpowers 的 subagent-driven + TDD + review** → 確保「已經做的」有品質紀律 + +換個角度看:OpenSpec 負責**把需求從對話中救出來**,Superpowers 負責**把紀律從人類意志中救出來**。兩者結合才是完整的 spec-driven development。 + +--- + +## 相關文件 + +- [schema.yaml](./schema.yaml) — 本 schema 的機器可讀定義 +- [README.md](./README.md) — schema 的設計動機與高層概覽 +- [templates/](./templates/) — 各 artifact 的 markdown 模板 +- [../../specs/README.md](../../specs/README.md) — capability 領域歸類指引 +- [openspec-conventions spec](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/specs/openspec-conventions/spec.md) — OpenSpec 官方 conventions +- [obra/superpowers](https://github.com/obra/superpowers) — Superpowers skill 來源 diff --git a/schemas/sdd-plus-superpowers/README.md b/schemas/sdd-plus-superpowers/README.md new file mode 100644 index 000000000..2af962418 --- /dev/null +++ b/schemas/sdd-plus-superpowers/README.md @@ -0,0 +1,125 @@ +# sdd-plus-superpowers Schema + +將 OpenSpec 的 artifact 治理流程與 Superpowers 的執行技能整合為單一工作流。 + +## 這個 Schema 解決什麼問題 + +OpenSpec 管理「做什麼」(proposal → specs → design → tasks),Superpowers 管理「怎麼做」(brainstorming、writing-plans、subagent-driven-development)。兩者各自優秀,但在實際開發中交替使用時出現三個結構性問題: + +1. **產出重複** — brainstorming 產出設計文件在 Superpowers 目錄(`docs/superpowers/specs/`),OpenSpec 又在 change 目錄重新撰寫 proposal/design,內容高度重疊。 +2. **Task 分裂** — OpenSpec 的 `tasks.md`(粗粒度 checkbox)和 Superpowers 的 plan(微型 TDD 步驟)描述同一件事,但格式、位置、狀態追蹤各自獨立。 +3. **手動編排** — 使用者必須自行判斷「現在該用哪個技能」,兩個系統之間沒有自動銜接。 + +### 為什麼用自定義 Schema 而非修改現有技能 + +曾考慮兩種替代方案: + +- **在 config.yaml 加自定義欄位**(如 `skill_bindings`):OpenSpec CLI 不認識這些欄位,無驗證、無發現性,且需要修改多個 SKILL.md 才能讀取。 +- **直接修改 opsx 技能檔案**:侵入性高,影響所有 change,且 SKILL.md 升級時會被覆蓋。 + +自定義 schema 利用 OpenSpec **原生支援的專案級 schema 機制**: +- CLI 會驗證 schema 結構 +- `openspec schemas` 自動列出 +- 每個 change 可獨立選擇 schema(`--schema spec-driven` 或 `--schema sdd-plus-superpowers`) +- 不動任何現有 SKILL.md 或 command 檔案 + +--- + +## 工作流概覽 + +``` +brainstorm ──→ proposal ──→ specs ──→ tasks ──→ plan + │ ↑ + └──→ design ──────────┘ +``` + +與 `spec-driven` 的差異: + +| | spec-driven | sdd-plus-superpowers | +|---|---|---| +| 起點 | proposal(手動撰寫) | **brainstorm**(調用 brainstorming skill) | +| 終點 | tasks(粗粒度) | **plan**(微型 TDD 步驟) | +| apply 需要 | tasks | **plan** | +| apply 方式 | 標準 task-by-task | **worktree + subagent-driven-development** | +| 新增 artifacts | — | brainstorm, plan | + +--- + +## 整合的 Superpowers 技能 + +| Schema 階段 | 調用的 Superpowers 技能 | 觸發方式 | +|------------|------------------------|---------| +| brainstorm artifact | `superpowers:brainstorming` | artifact instruction 指示 | +| plan artifact | `superpowers:writing-plans` | artifact instruction 指示 | +| apply phase | `superpowers:using-git-worktrees` | apply instruction 指示 | +| apply phase | `superpowers:subagent-driven-development` | apply instruction 指示 | +| apply 完成後 | `superpowers:finishing-a-development-branch` | apply instruction 指示 | + +所有整合都透過 schema.yaml 的 `instruction` 欄位實現 — 指示 AI 在適當時機用 Skill tool 調用對應技能。不修改任何 Superpowers 技能檔案本身。 + +### Output Redirection(產出重導) + +Superpowers 技能有預設的輸出路徑(如 brainstorming 寫到 `docs/superpowers/specs/`)。在此 schema 中,artifact instruction 包含重導指示,告知被調用的技能將產出寫入 change 目錄: + +- brainstorming → `openspec/changes//brainstorm.md`(+ 可選 `design.md`) +- writing-plans → `openspec/changes//plan.md` + +這透過上下文注入實現(在調用技能時附加指示),而非修改技能程式碼。 + +--- + +## 使用方式 + +### 快速流程(推薦) +```bash +/opsx:ff my-feature # 一條龍:建目錄 + brainstorm + proposal + design + specs + tasks + plan +/opsx:apply # worktree + subagent-driven-development +/opsx:archive # 封存 +``` + +### 逐步流程 +```bash +/opsx:new my-feature --schema sdd-plus-superpowers +/opsx:continue # → brainstorm(互動式對話) +/opsx:continue # → proposal +/opsx:continue # → design +/opsx:continue # → specs +/opsx:continue # → tasks +/opsx:continue # → plan +/opsx:apply +/opsx:archive +``` + +### 切回 spec-driven +```bash +# 單一 change 使用不同 schema +/opsx:new my-simple-fix --schema spec-driven + +# 或修改專案預設 +# openspec/config.yaml: schema: spec-driven +``` + +--- + +## 設計決策紀錄 + +### 為什麼 brainstorm 是 artifact 而非 hook + +brainstorming 是互動式多輪對話,需要使用者參與。將它做為第一個 artifact 而非 schema-level hook,有兩個好處: +1. **可跳過** — 如果使用者已經知道要做什麼,可以直接建立 brainstorm.md 而不調用技能 +2. **可追蹤** — `openspec status` 能顯示 brainstorm 是否完成,後續 artifacts 有明確的依賴關係 + +### 為什麼 plan 獨立於 tasks + +`tasks.md` 是粗粒度的 checkbox(「新增 PdfServiceTest」),`plan.md` 是微型步驟(「建立測試骨架 → 寫 downloadPdf 測試 → 執行 → commit」)。兩者的粒度和用途不同: +- `tasks.md` → 追蹤整體進度(apply phase 的 `tracks` 欄位解析 checkbox) +- `plan.md` → 指導 subagent 逐步實作(executor 的輸入) + +apply phase 要求 `plan` 而非 `tasks`,因為 executor 需要微型步驟才能有效工作。但 `tracks: tasks.md` 確保進度仍由粗粒度 checkbox 追蹤。 + +### 降級策略 + +如果 Superpowers 技能不可用(未安裝、版本不相容等),每個 instruction 都包含降級路徑: +- brainstorm → 手動撰寫 brainstorm.md +- plan → 手動撰寫 plan.md +- apply → 標準 task-by-task 手動實作 diff --git a/schemas/sdd-plus-superpowers/schema.yaml b/schemas/sdd-plus-superpowers/schema.yaml new file mode 100644 index 000000000..89e9c6d59 --- /dev/null +++ b/schemas/sdd-plus-superpowers/schema.yaml @@ -0,0 +1,282 @@ +name: sdd-plus-superpowers +version: 1 +description: > + Spec-driven workflow integrated with Superpowers skills. + brainstorm → proposal → specs → tasks → plan → verify. + design is optional (produced from brainstorm but not required by tasks). + Apply phase uses git worktrees + subagent-driven-development + (brings TDD and code-review transitively). executing-plans is + documented only as a fallback for platforms without subagent support. + +artifacts: + - id: brainstorm + generates: brainstorm.md + description: Collaborative design exploration using Superpowers brainstorming + template: brainstorm.md + instruction: | + Use the Skill tool to invoke **superpowers:brainstorming**. + + IMPORTANT output redirection: + - Do NOT write to `docs/superpowers/specs/`. Instead, write the + brainstorming design output directly to this change's `brainstorm.md`. + - If brainstorming produces a design document, also write it to + this change's `design.md` (this will pre-fill the design artifact). + + After brainstorming completes, summarize the agreed design in + brainstorm.md using the template structure. + + The brainstorming skill will: + 1. Explore project context + 2. Ask clarifying questions (one at a time) + 3. Propose 2-3 approaches with trade-offs + 4. Present design sections for approval + 5. Output the validated design + requires: [] + + - id: proposal + generates: proposal.md + description: Initial proposal document outlining the change + template: proposal.md + instruction: | + Create the proposal document based on the brainstorming output. + + Read brainstorm.md for the validated design. Extract: + - **Why**: The motivation (from brainstorming discussion) + - **What Changes**: Specific changes agreed upon + - **Capabilities**: Identify which specs will be created or modified: + - **New Capabilities**: List capabilities being introduced. Each becomes a new `specs//spec.md`. Use kebab-case names. + - **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Check `openspec/specs/` for existing spec names. + - **Impact**: Affected code, APIs, dependencies, or systems. + + Since brainstorming already explored the problem space, + this should be a concise extraction, not a new exploration. + + IMPORTANT: The Capabilities section is critical. It creates the contract between + proposal and specs phases. Each capability listed here will need a spec file. + + Keep it concise (1-2 pages). Focus on the "why" not the "how". + requires: + - brainstorm + + - id: design + generates: design.md + description: Technical design document with implementation details + template: design.md + instruction: | + Create the design document explaining HOW to implement the change. + + Check if brainstorming already produced a design.md file. + If design.md already exists with content from brainstorming, + review and refine it rather than starting from scratch. + + If design.md is empty or doesn't exist, create it from + the brainstorm.md output. + + Sections: + - **Context**: Background, current state, constraints, stakeholders + - **Goals / Non-Goals**: What this design achieves and explicitly excludes + - **Decisions**: Key technical choices with rationale (why X over Y?). Include alternatives considered. + - **Risks / Trade-offs**: Known limitations, things that could go wrong. Format: [Risk] → Mitigation + - **Migration Plan**: Steps to deploy, rollback strategy (if applicable) + - **Open Questions**: Outstanding decisions or unknowns to resolve + + Focus on architecture and approach, not line-by-line implementation. + Good design docs explain the "why" behind technical decisions. + requires: + - brainstorm + + - id: specs + generates: "specs/**/*.md" + description: Detailed specifications for the change + template: spec.md + instruction: | + Create specification files that define WHAT the system should do. + + Create one spec file per capability listed in the proposal's Capabilities section. + - New capabilities: use the exact kebab-case name from the proposal (specs//spec.md). + - Modified capabilities: use the existing spec folder name from openspec/specs// when creating the delta spec at specs//spec.md. + + Delta operations (use ## headers): + - **ADDED Requirements**: New capabilities + - **MODIFIED Requirements**: Changed behavior - MUST include full updated content + - **REMOVED Requirements**: Deprecated features - MUST include **Reason** and **Migration** + - **RENAMED Requirements**: Name changes only - use FROM:/TO: format + + Format requirements: + - Each requirement: `### Requirement: ` followed by description + - Use SHALL/MUST for normative requirements (avoid should/may) + - Each scenario: `#### Scenario: ` with WHEN/THEN format + - **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`). Using 3 hashtags or bullets will fail silently. + - Every requirement MUST have at least one scenario. + + Specs should be testable - each scenario is a potential test case. + requires: + - proposal + + - id: tasks + generates: tasks.md + description: Implementation checklist with trackable tasks + template: tasks.md + instruction: | + Create the task list that breaks down the implementation work. + + **IMPORTANT: Follow the template below exactly.** The apply phase parses + checkbox format to track progress. Tasks not using `- [ ]` won't be tracked. + + Guidelines: + - Group related tasks under ## numbered headings + - Each task MUST be a checkbox: `- [ ] X.Y Task description` + - Tasks should be small enough to complete in one session + - Order tasks by dependency (what must be done first?) + + Reference specs for what needs to be built. If design.md exists, + reference it for how to build it — but design is optional (see + openspec-conventions: design.md is only for changes that need to + explain non-trivial technical decisions). + requires: + - specs + + - id: plan + generates: plan.md + description: Micro-task implementation plan using Superpowers writing-plans + template: plan.md + instruction: | + Use the Skill tool to invoke **superpowers:writing-plans**. + + IMPORTANT output redirection: + - Do NOT write to `docs/superpowers/plans/`. Instead, write + the plan directly to this change's `plan.md`. + + The writing-plans skill will: + 1. Read the tasks.md and design.md for context + 2. Break each task into 2-5 minute micro-steps (TDD style) + 3. Include exact file paths, code snippets, test commands + 4. Add commit points after each task + + Pass the tasks.md content to the skill as the input for + decomposition. The plan should reference the specs and + design artifacts in this change directory. + requires: + - tasks + + - id: verify + generates: verify.md + description: Post-implementation verification against specs, design, and tasks + template: verify.md + instruction: | + Use the Skill tool to invoke **openspec-verify-change** (the + `/opsx:verify` slash command is its user-facing equivalent). + + IMPORTANT timing note: + - Unlike other artifacts, verify.md is produced AFTER the apply + phase completes, NOT during planning. The `requires: [plan]` + edge exists only for schema graph purposes — the actual + verification step MUST run on a completed implementation. + + The verify step MUST perform the following checks and record + results in verify.md using the template: + + 1. **Structural validation**: Run `openspec validate --all --json` + in the repository root and confirm every item returns + `"valid": true`. If any item fails, record the issues and + return to fix the underlying artifact before proceeding. + + 2. **Task completion**: Confirm every checkbox in tasks.md is + `- [x]`. For any `- [ ]` remaining, document the reason + (e.g. manual / out-of-scope / blocked) and whether it blocks + archive. + + 3. **Delta spec sync state**: For each directory under + `openspec/changes//specs/`, compare against the + corresponding `openspec/specs//spec.md` and + record one of: + - ✓ Already synced + - ✗ Needs sync (list the capabilities) + - N/A (no delta specs produced) + + 4. **Design/specs coherence**: Spot-check that design.md + decisions reference or align with the requirements listed + in specs/. Record any drift as a warning (non-blocking). + + 5. **Implementation signal**: Confirm all code changes are + committed (no unstaged files in the worktree). Cite the + commit range if known. + + Verify MAY be re-run multiple times as the implementation is + refined — each run overwrites verify.md with current state. + + If `openspec-verify-change` skill is unavailable, fall back to + running the 5 checks manually and recording results in verify.md. + requires: + - plan + +apply: + requires: [plan] + tracks: tasks.md + instruction: | + Before implementing, set up an isolated workspace and executor: + + 1. **Workspace**: Use the Skill tool to invoke + **superpowers:using-git-worktrees** to create an isolated + git worktree for this change. + + 2. **Executor** — on Claude Code you should **always use 2a**. + 2b exists only as a fallback for platforms without subagent + support; see the 2b section for details. + + **2a. Default — subagent-driven-development**: + + Use the Skill tool to invoke + **superpowers:subagent-driven-development** to execute + the plan.md micro-tasks with fresh subagents per task. + + Tell the executor: + - Read plan.md in this change directory for micro-tasks + - Update tasks.md checkboxes as coarse tasks complete + - Work within the created worktree + + IMPORTANT — transitive skill activation: + subagent-driven-development internally enforces the + following skills, so you do NOT need to invoke them + manually: + - **superpowers:test-driven-development** — every task + follows RED-GREEN-REFACTOR. Implementation code written + before a failing test is deleted. + - **superpowers:requesting-code-review** — after each + task, a code-reviewer subagent is dispatched to catch + spec compliance and code quality issues. A final review + runs for the entire implementation before apply + concludes. + + **2b. Fallback — executing-plans** (use ONLY when subagent + support is unavailable): + + The superpowers:executing-plans SKILL.md itself states: + "If subagents are available, use superpowers:subagent- + driven-development instead of this skill." executing-plans + exists for platforms or sessions without Task-tool / + subagent support. On Claude Code, subagents ARE available, + so this path should not be used under normal circumstances. + + If you must use 2b (e.g. running in a constrained runtime + without subagent support), use the Skill tool to invoke + **superpowers:executing-plans** and note that 2b does NOT + transitively activate TDD or code-review. You are + responsible for: + - Following TDD discipline manually (the executor will + not enforce it) + - Invoking **superpowers:requesting-code-review** yourself + after completing the plan, before proceeding to step 3 + + 3. **Verification**: When all tasks are done, produce the + `verify` artifact by invoking **openspec-verify-change** + to check completeness, correctness, and coherence. + Re-run verify until all blocking issues are resolved. + + 4. **Completion**: Once verify.md shows no blocking issues, + use the Skill tool to invoke + **superpowers:finishing-a-development-branch** for branch + cleanup, PR creation, etc. + + If any skill is unavailable, fall back to manual implementation + using the standard task-by-task loop from tasks.md. diff --git a/schemas/sdd-plus-superpowers/templates/brainstorm.md b/schemas/sdd-plus-superpowers/templates/brainstorm.md new file mode 100644 index 000000000..d8b07fdc9 --- /dev/null +++ b/schemas/sdd-plus-superpowers/templates/brainstorm.md @@ -0,0 +1,39 @@ +## Design Summary + + + +## Alternatives Considered + + + +## Agreed Approach + + + +## Key Decisions + + + +## Open Questions + + diff --git a/schemas/sdd-plus-superpowers/templates/design.md b/schemas/sdd-plus-superpowers/templates/design.md new file mode 100644 index 000000000..491cb8208 --- /dev/null +++ b/schemas/sdd-plus-superpowers/templates/design.md @@ -0,0 +1,19 @@ +## Context + + + +## Goals / Non-Goals + +**Goals:** + + +**Non-Goals:** + + +## Decisions + + + +## Risks / Trade-offs + + diff --git a/schemas/sdd-plus-superpowers/templates/plan.md b/schemas/sdd-plus-superpowers/templates/plan.md new file mode 100644 index 000000000..922fe10b5 --- /dev/null +++ b/schemas/sdd-plus-superpowers/templates/plan.md @@ -0,0 +1,17 @@ +# [Feature Name] Implementation Plan + +> **For agentic workers:** Use superpowers:subagent-driven-development +> to implement this plan task-by-task. + +**Goal:** + +**Architecture:** + +**Tech Stack:** + +--- + +## Task 1: + +- [ ] **Step 1:** +- [ ] **Step 2:** diff --git a/schemas/sdd-plus-superpowers/templates/proposal.md b/schemas/sdd-plus-superpowers/templates/proposal.md new file mode 100644 index 000000000..ad72b948a --- /dev/null +++ b/schemas/sdd-plus-superpowers/templates/proposal.md @@ -0,0 +1,50 @@ +## Why + + + +## What Changes + + + +## Capabilities + +### New Capabilities + +- ``: + +### Modified Capabilities + +- ``: + +## Impact + + diff --git a/schemas/sdd-plus-superpowers/templates/spec.md b/schemas/sdd-plus-superpowers/templates/spec.md new file mode 100644 index 000000000..d9c042a6f --- /dev/null +++ b/schemas/sdd-plus-superpowers/templates/spec.md @@ -0,0 +1,74 @@ + + +## ADDED Requirements + + + +### Requirement: + + +#### Scenario: +- **WHEN** +- **THEN** + +--- + +## MODIFIED Requirements + + + +### Requirement: + + +#### Scenario: +- **WHEN** +- **THEN** + +--- + +## REMOVED Requirements + + + +### Requirement: + +**Reason**: + +**Migration**: + +--- + +## RENAMED Requirements + + + +- FROM: `### Requirement: ` +- TO: `### Requirement: ` diff --git a/schemas/sdd-plus-superpowers/templates/tasks.md b/schemas/sdd-plus-superpowers/templates/tasks.md new file mode 100644 index 000000000..479c8e73b --- /dev/null +++ b/schemas/sdd-plus-superpowers/templates/tasks.md @@ -0,0 +1,9 @@ +## 1. + +- [ ] 1.1 +- [ ] 1.2 + +## 2. + +- [ ] 2.1 +- [ ] 2.2 diff --git a/schemas/sdd-plus-superpowers/templates/verify.md b/schemas/sdd-plus-superpowers/templates/verify.md new file mode 100644 index 000000000..4d564c16c --- /dev/null +++ b/schemas/sdd-plus-superpowers/templates/verify.md @@ -0,0 +1,86 @@ +# Verification Report + +> 此檔案由 `openspec-verify-change` skill 在 apply 完成後產生,用以確認實作 +> 與 specs / design / tasks 的一致性。失敗的檢查須返回對應 artifact 修正後 +> 再重跑 verify。 + +**Change**: `` +**Verified at**: `YYYY-MM-DD HH:mm` +**Verifier**: `` + +--- + +## 1. Structural Validation (`openspec validate --all --json`) + +- [ ] 全數 items `"valid": true` + +**結果**: + +``` +<貼上 openspec validate --all 的輸出摘要> +``` + +若有失敗項目,列出 id + issues: + +| Item | Type | Issues | +|---|---|---| +| — | — | — | + +--- + +## 2. Task Completion (`tasks.md`) + +- [ ] 所有 `- [ ]` 已變為 `- [x]` + +**未完成任務**(若有): + +| Task | 未完成原因 | 是否阻塞 archive | +|---|---|---| +| — | — | — | + +--- + +## 3. Delta Spec Sync State + +對每個 `openspec/changes//specs/` 下的 capability 目錄,與 +`openspec/specs//spec.md` 比對: + +| Capability | Sync 狀態 | 備註 | +|---|---|---| +| — | ✓ 已 sync / ✗ 待 sync / N/A | — | + +--- + +## 4. Design / Specs Coherence Spot Check + +抽樣比對 `design.md` 的決策是否反映在 `specs/*.md` 的 Requirements 與 +Scenarios 中: + +| 抽樣項 | design 描述 | specs 對應 | 差距 | +|---|---|---|---| +| — | — | — | — | + +**漂移警告**(非阻塞): + +- <若有,列出;無則填「無」> + +--- + +## 5. Implementation Signal + +- [ ] Worktree 內無未 staged 的檔案 +- [ ] 所有相關 commit 已推送 + +**Commit 範圍**(若知道):`..` + +--- + +## Overall Decision + +- [ ] ✅ PASS — 可進入 finishing-a-development-branch 與 archive +- [ ] ⚠️ PASS WITH WARNINGS — 可進入後續步驟但需注意:`<說明>` +- [ ] ❌ FAIL — 返回失敗的 artifact 修正後重跑 verify + +**下一步**: + +<說明下一個動作>