diff --git a/superpowers-bridge/README.md b/superpowers-bridge/README.md index 0dc2966..7f33489 100644 --- a/superpowers-bridge/README.md +++ b/superpowers-bridge/README.md @@ -243,7 +243,7 @@ flowchart TD subgraph Apply ["⚙️ APPLY — 7 ordered steps (requires: plan, tracks: tasks.md)"] direction TB A0["0. Pre-flight skill check"] - A1["1. Workspace
using-git-worktrees"] + A1["1. Workspace
worktree check (created by /bridge-new)"] A2["2. Executor
subagent-driven-development
↳ TDD + code-review (transitive)"] A3["3. Verification
openspec-verify-change → verify.md"] A4["4. Retrospective → retrospective.md
(BEFORE PR; hot context)"] @@ -278,8 +278,8 @@ PLANNING ━━━━━━━━━━━━━━━━━━━━━━━ apply.requires: [plan], apply.tracks: tasks ▼ APPLY ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 0. Pre-flight skill check - 1. superpowers:using-git-worktrees - 2. superpowers:subagent-driven-development (+ TDD + code-review transitive) + 1. Worktree check (created by `/bridge-new`; STOP if missing) + 2. subagent-driven-development (+ TDD + code-review transitive) 3. openspec-verify-change → verify.md ◄┐ │ │ blocking → fix ▼ │ @@ -289,6 +289,7 @@ APPLY ━━━━━━━━━━━━━━━━━━━━━━━━ ``` > **Timing notes** (full rationale in "Six design touches" #6): +> - `/bridge-new` creates the worktree before any artifact is written — the change directory and all artifacts land directly in the isolated branch with zero main-tree pollution. > - `verify.md` declares `requires: plan` in the graph but is actually produced inside apply step 3. > - `retrospective.md` declares `requires: verify` and per Step 4 is produced **before** the PR opens — so the PR diff includes the complete archived cycle (all artifacts done, spec synced, change folder under `archive/`). > - The `requires:` edges are file-existence dependencies for OpenSpec's graph engine; runtime ordering lives in instruction prose. @@ -299,7 +300,7 @@ APPLY ━━━━━━━━━━━━━━━━━━━━━━━━ |---|---|---|---| | 1 | `superpowers:brainstorming` | `brainstorm` artifact instruction | Direct (with PRECHECK) | | 2 | `superpowers:writing-plans` | `plan` artifact instruction | Direct (with PRECHECK) | -| 3 | `superpowers:using-git-worktrees` | apply step 1 | Direct | +| 3 | `superpowers:using-git-worktrees` | `bridge-new` skill (before any artifact) | Direct | | 4 | `superpowers:subagent-driven-development` | apply step 2 | Direct | | 5 | `superpowers:test-driven-development` | (activated inside #4) | **Transitive** | | 6 | `superpowers:requesting-code-review` | (activated inside #4) | **Transitive** | @@ -324,16 +325,22 @@ Implemented purely via context injection at invocation time, not by modifying sk ### Quick flow (recommended) ```bash -/opsx:ff my-feature # one-shot: scaffold + brainstorm + proposal + design + specs + tasks + plan -/opsx:apply # worktree + subagent-driven-development (with TDD + code-review) -/opsx:verify # produces verify.md (7 checks) -/opsx:continue # → retrospective (produces retrospective.md, §0 + 6 sections) -/opsx:archive # archive +/bridge-new my-feature # scaffold change in isolated worktree (use this instead of /opsx:new) +/opsx:continue # → brainstorm (interactive dialogue) +/opsx:continue # → proposal +/opsx:continue # → design +/opsx:continue # → specs +/opsx:continue # → tasks +/opsx:continue # → plan +/opsx:apply # → implement in worktree +/opsx:verify # → verify.md +/opsx:continue # → retrospective +/opsx:archive # → archive ``` ### Step-by-step flow ```bash -/opsx:new my-feature --schema superpowers-bridge +/bridge-new my-feature # scaffold change in isolated worktree (use this instead of /opsx:new) /opsx:continue # → brainstorm (interactive dialogue) /opsx:continue # → proposal /opsx:continue # → design (reorganize brainstorm into structured decisions) @@ -370,11 +377,11 @@ Confirms these skills are installed before proceeding: Missing skill → STOP with explicit error. No silent fallback, no manual mode within this schema. The user should either install Superpowers or switch to the built-in `spec-driven` schema for that change. -> The v0 version of this schema once placed an "auto-commit change artifacts to current branch" step here. It was removed after the [PR #970 review](https://github.com/Fission-AI/OpenSpec/pull/970): handling untracked change directories is the worktree skill's responsibility, not the schema's. +> The v0 version of this schema once placed an "auto-commit change artifacts to current branch" step here. It was removed after the [PR #970 review](https://github.com/Fission-AI/OpenSpec/pull/970): the current version ships a bundled `bridge-new` skill that creates the worktree **before** `openspec new change` runs — the change directory and all artifacts land directly in the isolated branch, with zero main-tree pollution. -#### 1. Workspace — `superpowers:using-git-worktrees` +#### 1. Workspace — worktree check -Creates `.worktrees//`, switches to a new branch, runs setup, confirms a clean test baseline. +Confirms the worktree created by `/bridge-new` still exists via `git worktree list`. If found, switches into it. If NOT found, STOP and tell the user to run `/bridge-new ` first. #### 2. Executor — `superpowers:subagent-driven-development` @@ -416,7 +423,7 @@ Confirms tests are green, presents merge / PR / keep-branch / discard options, c | Scenario | Command | |---|---| | First clone of a project | `bash scripts/install-git-hooks.sh` | -| New change (interactive) | `/opsx:new --schema superpowers-bridge` then `/opsx:continue` | +| New change (interactive) | `/bridge-new ` then `/opsx:continue` | | New change (one-shot) | `/opsx:ff ` | | Resume an interrupted change | `/opsx:continue ` | | Enter implementation | `/opsx:apply ` | @@ -461,6 +468,8 @@ The LLM does not need to interpret timing prose — it runs commands and reads r `verify.requires: [plan]` and `retrospective.requires: [verify]` are file-existence dependencies in the schema graph, but each instruction explicitly states "MUST run AFTER apply phase / verify pass". This is intentional misalignment — OpenSpec's engine only checks predecessor file existence. Engine-native fix awaits a `post_apply` phase concept upstream (analogous to spec-kit's `after_implement` hook); evidence-based PRECHECK above is the v1 mitigation. +The worktree is now created by the bundled `/bridge-new` skill **before** any artifact is written. This is the earliest point the schema can control — `openspec new change` runs inside the worktree, so the change directory and all subsequent artifacts land directly in the isolated branch. Main-tree pollution is zero. This required shipping a skill because OpenSpec schemas have no `before_create` hook at the CLI level. + --- ## Versioning @@ -524,6 +533,14 @@ Brainstorming is multi-turn interactive dialogue requiring user participation. M Apply requires `plan` (not `tasks`) because the executor needs micro-steps; `tracks: tasks.md` ensures progress is still surfaced via the coarse checkboxes. +### Why `/bridge-new` is a bundled skill + +OpenSpec's schema mechanism has no `before_create` hook — the earliest execution point is `artifact.instruction` (first run at `/opsx:continue`). By that point, `/opsx:new` has already written `openspec/changes//.openspec.yaml` on the main working tree. + +Shipping a skill lets us invert the order: create the worktree first, then run `openspec new change` inside it. This is the only way to achieve zero main-tree pollution without upstream changes to OpenSpec CLI. + +The skill lives in `templates/skills/` so adopters can install it alongside the schema. It is intentionally short-lived — if OpenSpec ever adds a schema-level `before_create` hook, the skill can be retired and the logic folded into schema.yaml. + ### Fallback strategy If a Superpowers skill is unavailable: diff --git a/superpowers-bridge/README.zh-TW.md b/superpowers-bridge/README.zh-TW.md index 6a9e105..5f6ffd1 100644 --- a/superpowers-bridge/README.zh-TW.md +++ b/superpowers-bridge/README.zh-TW.md @@ -278,8 +278,8 @@ PLANNING ━━━━━━━━━━━━━━━━━━━━━━━ apply.requires: [plan], apply.tracks: tasks ▼ APPLY ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 0. Pre-flight skill check - 1. superpowers:using-git-worktrees - 2. superpowers:subagent-driven-development(+ TDD + code-review 傳遞) + 1. Worktree check(由 `/bridge-new` 建立;若不存在就 STOP) + 2. subagent-driven-development(+ TDD + code-review 傳遞) 3. openspec-verify-change → verify.md ◄┐ │ │ blocking → 回去修 ▼ │ @@ -289,6 +289,7 @@ APPLY ━━━━━━━━━━━━━━━━━━━━━━━━ ``` > **時序註記**(完整理由見下方「設計觸點 #6」): +> - `/bridge-new` 在任何 artifact 寫入前先建立 worktree —— change 目錄和所有 artifact 直接落在隔離 branch,主工作樹零污染。 > - `verify.md` 在 graph 上宣告 `requires: plan`,但實際產在 apply step 3 內。 > - `retrospective.md` 宣告 `requires: verify`,並依 Step 4 在 PR 開啟**之前**產出 —— PR diff 才會包含完整 archived cycle(所有 artifact 完成、spec 已 sync、change folder 在 `archive/`)。 > - `requires:` 邊是給 OpenSpec graph 引擎用的「檔案存在」依賴;runtime 順序由 instruction prose 控制。 @@ -299,7 +300,7 @@ APPLY ━━━━━━━━━━━━━━━━━━━━━━━━ |---|---|---|---| | 1 | `superpowers:brainstorming` | `brainstorm` artifact instruction | 直接(含 PRECHECK) | | 2 | `superpowers:writing-plans` | `plan` artifact instruction | 直接(含 PRECHECK) | -| 3 | `superpowers:using-git-worktrees` | apply step 1 | 直接 | +| 3 | `superpowers:using-git-worktrees` | `bridge-new` skill(在任何 artifact 之前) | 直接 | | 4 | `superpowers:subagent-driven-development` | apply step 2 | 直接 | | 5 | `superpowers:test-driven-development` | (#4 內部觸發) | **傳遞** | | 6 | `superpowers:requesting-code-review` | (#4 內部觸發) | **傳遞** | @@ -324,16 +325,22 @@ Superpowers skill 有預設輸出路徑(例如 brainstorming 寫到 `docs/superp ### 快速流程(推薦) ```bash -/opsx:ff my-feature # 一條龍:scaffold + brainstorm + proposal + design + specs + tasks + plan -/opsx:apply # worktree + subagent-driven-development(含 TDD + code-review) -/opsx:verify # 產出 verify.md(7 項檢查) -/opsx:continue # → retrospective(產出 retrospective.md,§0 + 6 sections) -/opsx:archive # 封存 +/bridge-new my-feature # 在隔離 worktree 中 scaffold change(用這個取代 /opsx:new) +/opsx:continue # → brainstorm(互動式對話) +/opsx:continue # → proposal +/opsx:continue # → design +/opsx:continue # → specs +/opsx:continue # → tasks +/opsx:continue # → plan +/opsx:apply # → 在 worktree 中實作 +/opsx:verify # → verify.md +/opsx:continue # → retrospective +/opsx:archive # → 封存 ``` ### 逐步流程 ```bash -/opsx:new my-feature --schema superpowers-bridge +/bridge-new my-feature # 在隔離 worktree 中 scaffold change(用這個取代 /opsx:new) /opsx:continue # → brainstorm(互動式對話) /opsx:continue # → proposal /opsx:continue # → design(將 brainstorm 重組為結構化決策) @@ -370,11 +377,11 @@ Superpowers skill 有預設輸出路徑(例如 brainstorming 寫到 `docs/superp skill 缺失 → STOP 並通知使用者,不靜默 fallback,本 schema 內也沒有 manual mode。建議使用者在那個 change 改用 OpenSpec 內建的 `spec-driven` schema,或安裝缺失的 skill 後重來。 -> 本 schema 的 v0 版本曾在這裡放「自動 commit change artifacts 到當前分支」邏輯,在 [PR #970 review](https://github.com/Fission-AI/OpenSpec/pull/970) 後移除:處理未追蹤的 change 目錄是 worktree skill 的責任,schema 不該主動改寫使用者的 git history。 +> 本 schema 的 v0 版本曾在這裡放「自動 commit change artifacts 到當前分支」邏輯,在 [PR #970 review](https://github.com/Fission-AI/OpenSpec/pull/970) 後移除。目前版本附帶 bundled `bridge-new` skill,在 `openspec new change` 執行**之前**先建立 worktree —— change 目錄和所有 artifact 直接落在隔離 branch,主工作樹零污染。 -#### 1. Workspace — `superpowers:using-git-worktrees` +#### 1. Workspace — worktree check -建立 `.worktrees//`、切到新 branch、跑專案 setup、確認 test baseline 乾淨。 +確認由 `/bridge-new` 建立的 worktree 仍存在(透過 `git worktree list`)。若存在就切換過去。若不存在,STOP 並通知使用者先跑 `/bridge-new `。 #### 2. Executor — `superpowers:subagent-driven-development` @@ -416,7 +423,7 @@ Evidence-first 反思:§0 Evidence(量化前置數據 —— commit 數、diff | 情境 | 指令 | |---|---| | 首次 clone 專案後 | `bash scripts/install-git-hooks.sh` | -| 新 change(互動式) | `/opsx:new --schema superpowers-bridge` 接著多次 `/opsx:continue` | +| 新 change(互動式) | `/bridge-new ` 接著多次 `/opsx:continue` | | 新 change(一鍵) | `/opsx:ff ` | | 恢復中斷的 change | `/opsx:continue ` | | 進入實作 | `/opsx:apply ` | @@ -461,6 +468,8 @@ LLM 不必解讀 timing 文字 —— 跑指令、看結果即可。這是顧慮 `verify.requires: [plan]` 與 `retrospective.requires: [verify]` 在 schema graph 上是「檔案存在」依賴,但兩者的 instruction 都明寫「MUST run AFTER apply phase / verify pass」。這是刻意錯位 —— OpenSpec 引擎只看前置 artifact 檔案存在,不會檢查 apply 是否真的跑完、verify 是否真的 pass。引擎原生的修法等 OpenSpec 引入 `post_apply` phase(對應 spec-kit 的 `after_implement` hook);上述第 5 點 evidence-based PRECHECK 是 v1 的緩解。 +Worktree 現由 bundled `/bridge-new` skill 在任何 artifact 寫入**之前**建立。這是本 schema 能控制的最早時間點 —— `openspec new change` 在 worktree 內執行,change 目錄和所有後續 artifact 直接落在隔離 branch。主工作樹零污染。這需要附帶一個 skill,因為 OpenSpec schema 沒有 `before_create` hook。 + --- ## 版本識別 @@ -524,6 +533,14 @@ Brainstorming 是多輪互動對話,需要使用者參與。把它做為第一 apply 要求 `plan` 而非 `tasks`,因為 executor 需要 micro-step 才能有效工作;`tracks: tasks.md` 確保進度仍由粗粒度 checkbox 追蹤。 +### 為什麼 `/bridge-new` 是 bundled skill + +OpenSpec 的 schema 機制沒有 `before_create` hook —— 最早的執行點是 `artifact.instruction`(在 `/opsx:continue` 首次觸發)。那時 `/opsx:new` 已經在主工作樹上寫了 `openspec/changes//.openspec.yaml`。 + +附帶一個 skill 讓我們可以反轉順序:先建 worktree,再在裡面跑 `openspec new change`。這是在不修改 OpenSpec CLI 的前提下達成主工作樹零污染的唯一方法。 + +Skill 放在 `templates/skills/` 讓採用者可隨 schema 一起安裝。這是刻意短命的設計 —— 若 OpenSpec 未來加入 schema-level `before_create` hook,skill 就可退役,邏輯可以摺回 schema.yaml。 + ### 降級策略 若 Superpowers skill 不可用: diff --git a/superpowers-bridge/schema.yaml b/superpowers-bridge/schema.yaml index 65e2ca1..5d986a3 100644 --- a/superpowers-bridge/schema.yaml +++ b/superpowers-bridge/schema.yaml @@ -18,6 +18,9 @@ description: > and plan for implementation guidance). Apply phase uses git worktrees + subagent-driven-development (brings TDD and code-review transitively). + Use `/bridge-new ` (bundled skill) instead of `/opsx:new` + to scaffold the change directly in an isolated worktree — prevents + untracked artifact pollution on the main working tree. artifacts: - id: brainstorm @@ -25,6 +28,12 @@ artifacts: description: Collaborative design exploration using Superpowers brainstorming template: brainstorm.md instruction: | + 0. **Workspace — worktree check**: + Run `git worktree list` and check for a worktree whose path + or branch name matches this change. If found, switch into it + before proceeding. If NOT found, STOP and tell the user to + run `/bridge-new ` first. + PRECHECK — required skill availability: Before invoking, confirm `superpowers:brainstorming` appears in your available skills list. If missing, STOP and inform the user @@ -61,6 +70,12 @@ artifacts: description: Initial proposal document outlining the change template: proposal.md instruction: | + 0. **Workspace — worktree check**: + Run `git worktree list` and check for a worktree whose path + or branch name matches this change. If found, switch into it + before proceeding. If NOT found, STOP and tell the user to + run `/bridge-new ` first. + Create the proposal document based on the brainstorming output. Read brainstorm.md for the validated design. Extract: @@ -86,6 +101,12 @@ artifacts: description: Technical design document with implementation details template: design.md instruction: | + 0. **Workspace — worktree check**: + Run `git worktree list` and check for a worktree whose path + or branch name matches this change. If found, switch into it + before proceeding. If NOT found, STOP and tell the user to + run `/bridge-new ` first. + Create the design document explaining HOW to implement the change. Read brainstorm.md as input. brainstorm.md is a raw capture of @@ -118,6 +139,12 @@ artifacts: description: Detailed specifications for the change template: spec.md instruction: | + 0. **Workspace — worktree check**: + Run `git worktree list` and check for a worktree whose path + or branch name matches this change. If found, switch into it + before proceeding. If NOT found, STOP and tell the user to + run `/bridge-new ` first. + Create specification files that define WHAT the system should do. Create one spec file per capability listed in the proposal's Capabilities section. @@ -146,6 +173,12 @@ artifacts: description: Implementation checklist with trackable tasks template: tasks.md instruction: | + 0. **Workspace — worktree check**: + Run `git worktree list` and check for a worktree whose path + or branch name matches this change. If found, switch into it + before proceeding. If NOT found, STOP and tell the user to + run `/bridge-new ` first. + Create the task list that breaks down the implementation work. **IMPORTANT: Follow the template below exactly.** The apply phase parses @@ -168,6 +201,12 @@ artifacts: description: Micro-task implementation plan using Superpowers writing-plans template: plan.md instruction: | + 0. **Workspace — worktree check**: + Run `git worktree list` and check for a worktree whose path + or branch name matches this change. If found, switch into it + before proceeding. If NOT found, STOP and tell the user to + run `/bridge-new ` first. + PRECHECK — required skill availability: Before invoking, confirm `superpowers:writing-plans` appears in your available skills list. If missing, STOP and inform the user @@ -489,9 +528,11 @@ apply: may have a fallback. Print the missing list once at apply start so the user isn't surprised mid-cycle. - 1. **Workspace**: Use the Skill tool to invoke - **superpowers:using-git-worktrees** to create an isolated - git worktree for this change. + 1. **Workspace — worktree check**: + Run `git worktree list` and check for a worktree whose path + or branch name matches this change. If found, switch into it + and confirm a clean test baseline. If NOT found, STOP and + tell the user to run `/bridge-new ` first. 2. **Executor — subagent-driven-development**: diff --git a/superpowers-bridge/templates/skills/bridge-new.md b/superpowers-bridge/templates/skills/bridge-new.md new file mode 100644 index 0000000..06e75ff --- /dev/null +++ b/superpowers-bridge/templates/skills/bridge-new.md @@ -0,0 +1,67 @@ +--- +name: bridge-new +description: Scaffold a new superpowers-bridge change in an isolated git worktree — prevents untracked artifact pollution on the main working tree +--- + +# bridge-new + +Scaffold a new OpenSpec change using the superpowers-bridge schema inside an +isolated git worktree. + +## Why this skill exists + +`/opsx:new --schema superpowers-bridge` creates the change directory on +the main working tree. All subsequent artifacts (brainstorm.md, proposal.md, +design.md, specs/, tasks.md, plan.md) are written as **untracked files** on +main — git worktree creation during apply does NOT carry them over. This skill +reverses the order: create the worktree **first**, then run `openspec new +change` inside it. The change directory and all artifacts land directly in the +isolated branch, with zero main-tree pollution. + +## When to use + +Use this skill INSTEAD of `/opsx:new` when starting a superpowers-bridge +change. It is the canonical entry point for the schema. + +## Usage + +``` +/bridge-new my-feature +``` + +Optionally pass `--schema superpowers-bridge` (the default). + +## Procedure + +### 1. Pre-flight + +Confirm `superpowers:using-git-worktrees` is in the available skills list. If +missing, STOP — the user must install the Superpowers plugin. + +### 2. Create the worktree + +Invoke **superpowers:using-git-worktrees** to create an isolated git worktree +for ``. The worktree branch should be named after the change +(e.g., `feat/` or ``). + +### 3. Scaffold the change inside the worktree + +Switch into the worktree, then run: + +```bash +openspec new change --schema superpowers-bridge +``` + +This creates `openspec/changes//.openspec.yaml` directly inside +the worktree (not on main). + +### 4. Confirm and hand off + +Run `git status` in the worktree to confirm the scaffolded directory exists. +Then tell the user: + +> Worktree ready at ``. Change scaffolded on branch ``. +> Run `/opsx:continue` to start brainstorming — all artifacts will land in +> the isolated worktree. + +No files are written to the main working tree.