Orbit: OpenSpec + Superpowers 統一工作流程編排器
啟動閘門
Orbit 不得自動啟動，除非被明確調用。如果載入時沒有明確觸發，請保持靜止，讓使用者直接使用其他技能。
| 觸發方式 | 範例 | 相容工具 |
|---|---|---|
| 斜線指令 | /orbit 我要做 OAuth 登入 | Codex, Claude Code |
| 明確提及名稱 | "用 Orbit 幫我修復這個 bug" | 全部 |
| @ mention | @orbit 實現使用者認證模組 | Cursor, Windsurf |
如果沒有觸發 → Orbit 保持靜止。 除非使用者要求端到端編排的工作流程，否則不要建議使用 Orbit。
如果使用者只想執行單一任務（腦力激盪、撰寫規格、使用 TDD 實作、審查程式碼），請直接使用個別技能，而不是 Orbit。
概述
Orbit 將 OpenSpec（變更工件管理）和 Superpowers（開發品質實踐）串聯成一條端到端工作流程。使用者發起一次，後續階段自動銜接。
設計哲學：
- OpenSpec = WHAT（需求定義 + 變更追蹤）
- Superpowers = HOW（設計方法 + 實作紀律 + 品質保障）
- Orbit = 編排層（WHAT 和 HOW 之間的膠水 + 狀態持久化）
不重寫任何現有 skill。Orbit 只做四件事：決定階段、執行橋接、控制轉換、持久化狀態。
狀態更新規則：每次寫入 .orbit-state 時，同步更新 updated_at 時間戳。遵循「先寫狀態，再執行橋接」原則——確保即使橋接失敗或對話中斷，狀態檔案已記錄最新進度。
完整設計文件：docs/superpowers/specs/2026-07-16-orbit-workflow-design.md
轉換權限
Orbit 編排整個工作流程。當子技能達到其終止狀態並指示你調用另一個技能時，你不得遵循該指示。
請改為輸出檢查點標記：
[ORBIT_CHECKPOINT: Stage N complete]
然後返回 Orbit 的控制器。Orbit 決定下一步要做什麼。
此規則覆蓋任何子技能的終止轉換指示。 Orbit 承載使用者的意圖——使用者選擇了完整的編排工作流程——此意圖優先於子技能的預設行為。
核心路由
冷啟動
當使用者請求一個變更時（例如，「我要做 OAuth 登入」、「修復支付校驗 bug」、「更新 README」）：
- 從 階段 0 — Bootstrap 開始
- 根據偵測到的變更類型遵循階段序列
繼續（斷點續傳）
如果使用者說「繼續」或「continue」，但沒有新的變更請求：
- 掃描
openspec/changes/*/.orbit-state中stage < 5（或stage == 5且substage != "complete"）的檔案 - 如果找到一個：從該階段自動繼續
- 如果找到多個：列出並讓使用者選擇
- 完整性檢查：在繼續之前，驗證
.orbit-state引用的工件仍然存在：- 如果
stage >= 3：檢查openspec/changes/<id>/tasks.md是否存在 - 如果
stage == 4：檢查.orbit-state.plan_doc路徑是否存在 - 如果任何檢查失敗：輸出
[ORBIT_RESUME_WARNING] 狀態檔案引用的工件缺失: {missing}並詢問使用者：請選擇： 1. 繼續 — 忽略缺失警告，從斷點繼續執行 2. 放棄 — 終止恢復，保持現狀
- 如果
- 輸出：
[ORBIT_RESUME] Resuming from Stage {stage}.{substage} - 跳至下方對應階段的指示
依變更類型的階段序列
| change_type | 階段 | 使用的技能 |
|---|---|---|
| feature | 0 → 1 → 2 → 3 → 4 → 5 | brainstorming, writing-plans, subagent-driven-development, tdd, finishing-a-development-branch |
| bugfix | 0 → 2 → 3 → 4 → 5 | writing-plans, subagent-driven-development, tdd, finishing-a-development-branch |
| docs | 0 → 2 → 5 | verification-before-completion, finishing-a-development-branch |
階段 0：Bootstrap
目標：建立變更目錄、偵測環境、分類變更類型。
步驟：
-
產生 change-id：解析使用者請求 →
<verb>-<noun>（例如，add-oauth-login）。如果不明確，使用change-YYYYMMDD-NNN。驗證 kebab-case。衝突檢查使用ls openspec/changes/。建立openspec/changes/<change-id>/目錄。 -
寫入初始 .orbit-state：設定
change_id、schema_version: "1.0.0"、preliminary: true、stage: 0、created_at、updated_at。結構參考：references/state-schema.yaml。 當preliminary: true時，工作流程僅限於階段 0 ↔ 階段 1。階段 2 及以後的階段必須等到階段 1 完成且preliminary設為false才能繼續。 -
偵測測試指令： 偏好無頭（CI 相容）測試腳本。 先檢查
package.json中的test:unit或test:ci。如果找不到，則回退到scripts.test。 如果偵測到的腳本啟動開發伺服器（例如vite），請在子套件腳本中搜尋無頭替代方案。也請檢查pyproject.toml→pytest、Cargo.toml→cargo test、go.mod→go test ./...、Makefile→make test。如果都不符合，詢問使用者。寫入.orbit-state.test_cmd。 -
分類變更類型：關鍵字 → 類型映射：
新增/添加/實現/重構/開發/做→feature修復/修/bug/fix→bugfix文件/README/Dockerfile/配置/註解→docs
顯示分類結果及理由，並要求使用者確認：
「識別為 {type} 變更（匹配關鍵字：{keywords}）。 執行路徑：{route summary}。 請選擇變更類型：
- feature — 新增功能，走 0→1→2→3→4→5 全流程
- bugfix — 缺陷修復，跳過 Stage 1，走 0→2→3→4→5
- docs — 文件變更，走 0→2→5 輕量流程
- 自訂類型 — 手動指定類型（需說明理由）」
-
將
change_type寫入.orbit-state。將branch_name產生為<type>/<change-id>並寫入.orbit-state.branch_name（例如，feature/add-oauth-login、bugfix/fix-payment、docs/update-readme）。
轉換：如果是 feature → 階段 1。如果是 bugfix 或 docs → 階段 2。
階段 1：探索與設計
適用於：change_type == feature
技能：brainstorming
指示：
-
更新
.orbit-state：stage: 1, substage: exploring -
執行 brainstorming（載入技能或使用內聯回退 — 請參閱工具相容性）：
「遵循 brainstorming 的完整流程（9 個步驟）。當它告訴你調用 writing-plans 時，請不要遵循。改為輸出 [ORBIT_CHECKPOINT: Stage 1 complete] 並返回 Orbit 的控制器。」
-
讓 brainstorming 執行完整週期：探索上下文 → 提問回合 → 設計文件 → 使用者審閱
-
在 brainstorming 的終止狀態，輸出
[ORBIT_CHECKPOINT: Stage 1 complete] -
Orbit 接手：
- 更新
.orbit-state：stage: 2, substage: id_confirmation - 詢問使用者：「Change ID 為
{id}，是否保留？（輸入新 ID 可重新命名）」 - 如果重新命名：
mv openspec/changes/<old>/ openspec/changes/<new>/，更新.orbit-state.change_id，更新.orbit-state.branch_name為feature/<new-id> - 將
preliminary設為false - 將
design_doc路徑（來自 brainstorming 輸出）寫入.orbit-state.design_doc
- 更新
產出物：docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
轉換：階段 2
階段 2：規格制定
適用於：所有變更類型
技能：無。Orbit 直接撰寫 OpenSpec 工件。不要調用 openspec-new-change — 目錄已從階段 0 存在。
指示：
-
更新
.orbit-state：stage: 2, substage: bridging -
讀取設計文件（針對功能）或從使用者請求中提取（針對 bugfix/docs）
-
方案分析（條件式）：
更新
.orbit-state：substage: approach_analysis自我評估此變更是否具有有意義的替代實作方案 — 這是關於 HOW（技術路徑），而不是 WHAT（需求已被定義）：
觸發（呈現替代方案）當滿足任一條件時：
- 存在多個可行的技術路徑（修改現有模組 vs. 建立新的抽象）
- 需要跨模組協調（composable + pages + components）
- 方案以非明顯的方式影響現有行為
- 具有下游影響的架構決策
跳過（前往步驟 4）當滿足任一條件時：
- 使用者請求已明確指定方案
- 單行修復、錯字或明顯的機械性變更
- 純文件/配置變更，無需實作選擇
- 階段 1 的設計文件已選定並記錄了方案
當觸發時，呈現 2-3 個方案。對於每個方案：簡短描述（更改了什麼 + 在哪裡）、優缺點（技術權衡）、工作量（小/中/大）、風險（低/中/高，以及可能出錯的地方）。標記其中一個為主推 (Recommended)，並附上理由。
=== [ORBIT_APPROACH] 方案分析 === 需求摘要：<1-2 行> ── 方案 A (主推) ── 描述：<what + where> 優點：<pros> 缺點：<cons> 工作量：小/中/大 風險：低/中/高 ── 方案 B ── 描述：<what + where> 優點 / 缺點 / 工作量 / 風險 ── 方案 C ── 描述：<what + where> 優點 / 缺點 / 工作量 / 風險 主推理由：<為什麼推薦方案 A> 請選擇：A / B / C (或描述自訂方案)- 使用者選擇 A/B/C → 將
selected_approach寫入.orbit-state，繼續步驟 4 - 使用者描述自訂方案 → 視為已選定，繼續步驟 4
-
撰寫 OpenSpec 工件，使用
references/bridge-rules.md中的橋接規則。 從.orbit-state.change_id讀取 change-id 並替換到 proposal.md 的標題中（# Proposal: <change-id>）： 如果步驟 3 被觸發，工件必須反映所選方案：openspec/changes/<change-id>/proposal.md— 為什麼 / 更改了什麼 / 影響openspec/changes/<change-id>/design.md— 架構 / 資料流程openspec/changes/<change-id>/specs/<capability>/spec.md— EARS 格式的需求
-
驗證：執行
openspec status --change "<id>" --json -
封鎖性人工審閱關卡（不可跳過）：
=== [ORBIT_GATE] Stage 2 工件已產生，請審閱 === 📄 proposal.md: Why：<1-2 行摘要> What：<要點列表> Impact：<1 行> 📄 specs/<capability>/spec.md: Requirements：<編號列表，每條一行> 📄 design.md: Architecture：<1-2 行> 完整檔案：openspec/changes/<change-id>/ 請選擇： 1. 確認 — 審閱通過，繼續下一階段 2. 修改檔案 — 用自然語言描述需要調整的內容 範例：「proposal 的 Why 部分寫偏了，實際問題是 XXX」 「第三個需求描述不準確，應該是 YYY」 Orbit 會根據描述定位到對應的 OpenSpec 工件並修改， 修改完成後重新驗證並展示給你確認 3. 重新討論方案 — 回到 Step 3 方案分析，重新選擇實作路徑 適用於：審閱工件後發現技術方案需要調整 Orbit 會清空當前工件，回到方案分析步驟 4. 放棄 — 終止工作流程，保留檔案供手動處理- 「1」→ 繼續到步驟 7
- 「2」→ 理解使用者的自然語言意圖，使用橋接規則定位對應的 OpenSpec 工件，修改它們，重新執行
openspec status --change "<id>" --json進行驗證，然後顯示變更摘要（哪些檔案被修改以及修改了什麼），然後重新顯示審閱關卡 - 「3」→ 刪除已產生的工件，將
substage設為approach_analysis，返回步驟 3。先前呈現的方案可以根據審閱見解進行修改。 - 「4」→ 終止，保留檔案供手動處理
-
更新
.orbit-state：stage: 3, substage: ready_for_plan
轉換：
feature或bugfix→ 階段 3docs→ 階段 5
階段 3：計劃
適用於：change_type == feature || change_type == bugfix
技能：writing-plans
指示：
-
更新
.orbit-state：substage: planning -
執行 writing-plans（載入技能或使用內聯回退 — 請參閱工具相容性）：
「將 openspec/changes// 中的 OpenSpec 工件作為你的規格輸入。當你完成計劃並通常會調用 subagent-driven-development 時，請改為輸出 [ORBIT_CHECKPOINT: Stage 3 complete]。」
-
Writing-plans 執行：範圍檢查 → 檔案結構 → 小任務 → 自我審查
-
輸出
[ORBIT_CHECKPOINT: Stage 3 complete] -
Orbit 接手 — 橋接到 tasks.md：
- 解析計劃文件中的任務章節
- 使用參考連結（NOT 壓縮摘要）撰寫
openspec/changes/<change-id>/tasks.md：- [ ] 1. 實作認證模組 → 詳見：docs/superpowers/plans/2026-07-16-oauth.md#task-1 - [ ] 2. 實作授權中介軟體 → 詳見：docs/superpowers/plans/2026-07-16-oauth.md#task-2 - 讀取計劃文件路徑 → 寫入
.orbit-state.plan_doc - 解析總任務數量 → 寫入
.orbit-state.total_tasks
-
更新
.orbit-state：stage: 4, substage: implementing, current_task: 0
產出物：docs/superpowers/plans/YYYY-MM-DD-<name>.md、tasks.md
轉換：階段 4
階段 4：實作
適用於：change_type == feature || change_type == bugfix
技能：subagent-driven-development、test-driven-development、systematic-debugging
前置檢查：工作區乾淨度檢查
在提交模式選擇之前，請確認 git 工作區是乾淨的：
- 執行
git status --porcelain - 如果有未提交的變更：
[ORBIT] 偵測到工作區有未提交變更： <list modified files> 請選擇： 1. 提交後再繼續 — 輸入 commit message，提交後進入下一步 2. 暫停，我手動處理 — 工作流程暫停，處理後輸入 continue 恢復 3. 丟棄變更，繼續 — 警告：將丟失所有未提交內容（需二次確認）1→ 使用者提供 commit message →git add . && git commit -m "..."→ 繼續2→ 暫停，等待「continue」→ 重新檢查乾淨度3→ 顯示二次確認：
→ 「1」→將丟棄所有未提交變更，此操作不可恢復。 請選擇： 1. 確認丟棄 — 執行 git reset --hard + git clean -fd 2. 取消 — 返回上一級選擇git reset --hard+git clean -fd→ 「2」→ 重新顯示工作區乾淨度選項
- 如果乾淨：繼續進行提交模式選擇
理由：Stage 4 的原子化回滾會在每個任務之前記錄 git rev-parse HEAD。未提交的變更會使回滾點變得意義不明——重設會丟失從未屬於任何任務的工作。
前置檢查：提交模式選擇
在執行第一個任務之前，要求使用者選擇提交模式：
[ORBIT] Stage 4 開始。選擇提交模式：
1. auto（推薦） — 每個 Task 完成後自動提交，全程無需干預
2. review — 每個 Task 完成後展示變更摘要，等待確認後再提交
請選擇 (1/2)：
將選擇寫入 .orbit-state.commit_mode。
每個任務的迴圈
對於每個任務（1..total_tasks，依序執行）：
步驟 1 — 記錄回滾點：
git rev-parse HEAD → append to .orbit-state.task_history
步驟 2 — 分派實作子代理： 執行 subagent-driven-development（載入技能或使用內聯回退 — 請參閱工具相容性）並附上任務指示。子代理接收：
- 來自
tasks.md條目的任務描述 - 來自計劃文件的完整計劃章節（透過 tasks.md 中的參考連結讀取 — 不要壓縮）
- TDD 強制執行（內部載入
test-driven-development）
子代理內部流程：RED → VERIFY → GREEN → VERIFY → REFACTOR → SELF-REVIEW → COMMIT（始終如此 — 這是原子化回滾的先決條件）
子代理輸出 han...
[為翻譯而截斷]