diff --git a/.github/workflows/version-check.yml b/.github/workflows/version-check.yml deleted file mode 100644 index a9e5599..0000000 --- a/.github/workflows/version-check.yml +++ /dev/null @@ -1,171 +0,0 @@ -name: Weekly upstream version check - -on: - schedule: - # Mondays at 14:00 UTC (Tuesday 22:00 Asia/Taipei) - - cron: '0 14 * * 1' - workflow_dispatch: - -permissions: - contents: read - issues: write - -jobs: - check: - runs-on: ubuntu-latest - timeout-minutes: 10 - steps: - - name: Checkout - uses: actions/checkout@v6 - - - name: Set up Node.js - uses: actions/setup-node@v6 - with: - node-version: "24" - - - name: Get latest OpenSpec CLI version - id: openspec - run: | - version=$(npm view @fission-ai/openspec version) - echo "version=$version" >> "$GITHUB_OUTPUT" - echo "Latest OpenSpec CLI: $version" - - - name: Get latest Superpowers release - id: superpowers - run: | - response=$(curl -fsSL https://api.github.com/repos/obra/superpowers/releases/latest) - tag=$(echo "$response" | jq -r '.tag_name') - echo "tag=$tag" >> "$GITHUB_OUTPUT" - echo "Latest Superpowers: $tag" - - - name: Read pinned versions from README - id: pinned - run: | - line=$(grep -E '^\| v1 \| `' superpowers-bridge/README.md | head -1) - if [ -z "$line" ]; then - echo "::error::Could not find Compatibility table row in superpowers-bridge/README.md" - exit 1 - fi - pinned_openspec=$(echo "$line" | awk -F'`' '{print $2}') - pinned_superpowers=$(echo "$line" | awk -F'`' '{print $4}') - echo "openspec=$pinned_openspec" >> "$GITHUB_OUTPUT" - echo "superpowers=$pinned_superpowers" >> "$GITHUB_OUTPUT" - echo "Pinned in README: OpenSpec=$pinned_openspec, Superpowers=$pinned_superpowers" - - - name: Install OpenSpec CLI (latest) - run: npm install -g @fission-ai/openspec@${{ steps.openspec.outputs.version }} - - - name: Validate schema against latest OpenSpec - id: validate - continue-on-error: true - run: | - mkdir -p /tmp/test-project/openspec/schemas - cp -R superpowers-bridge /tmp/test-project/openspec/schemas/ - cd /tmp/test-project - openspec schema validate superpowers-bridge - - - name: Ensure drift label exists - # Always run so the label exists from day 1, even before the first drift fires. - # The Upstream Drift badge in README queries for issues with this label and would - # otherwise show an error / undefined state when the label doesn't yet exist. - uses: actions/github-script@v9 - with: - script: | - try { - await github.rest.issues.createLabel({ - owner: context.repo.owner, - repo: context.repo.repo, - name: 'upstream-version-check', - color: 'fbca04', - description: 'Drift detected by weekly version-check workflow', - }); - core.info('Label upstream-version-check created'); - } catch (e) { - if (e.status === 422) { - core.info('Label upstream-version-check already exists'); - } else { - throw e; - } - } - - - name: Open or update drift issue - if: steps.openspec.outputs.version != steps.pinned.outputs.openspec || steps.superpowers.outputs.tag != steps.pinned.outputs.superpowers || steps.validate.outcome == 'failure' - uses: actions/github-script@v9 - env: - OPENSPEC_LATEST: ${{ steps.openspec.outputs.version }} - OPENSPEC_PINNED: ${{ steps.pinned.outputs.openspec }} - SUPERPOWERS_LATEST: ${{ steps.superpowers.outputs.tag }} - SUPERPOWERS_PINNED: ${{ steps.pinned.outputs.superpowers }} - VALIDATE_OUTCOME: ${{ steps.validate.outcome }} - RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} - with: - script: | - const openspecLatest = process.env.OPENSPEC_LATEST; - const openspecPinned = process.env.OPENSPEC_PINNED; - const superpowersLatest = process.env.SUPERPOWERS_LATEST; - const superpowersPinned = process.env.SUPERPOWERS_PINNED; - const validateBroken = process.env.VALIDATE_OUTCOME === 'failure'; - const runUrl = process.env.RUN_URL; - - const openspecDrift = openspecPinned !== openspecLatest; - const superpowersDrift = superpowersPinned !== superpowersLatest; - - const title = '[upstream-version-check] Drift detected'; - const body = [ - '> Auto-generated by `.github/workflows/version-check.yml` (weekly cron).', - '', - '## Detected versions', - '', - '| Component | Pinned in README | Latest upstream | Drift? |', - '|---|---|---|---|', - `| OpenSpec CLI | \`${openspecPinned}\` | \`${openspecLatest}\` | ${openspecDrift ? '**Yes**' : 'No'} |`, - `| Superpowers | \`${superpowersPinned}\` | \`${superpowersLatest}\` | ${superpowersDrift ? '**Yes**' : 'No'} |`, - '', - `## Schema validation against \`${openspecLatest}\``, - '', - validateBroken - ? '❌ **`openspec schema validate superpowers-bridge` FAILED.** Structural breakage — investigate immediately.' - : '✅ `openspec schema validate superpowers-bridge` passed.', - '', - '## Action required', - '', - '- [ ] Review Superpowers release notes for behavioral changes (skill renames, PRECHECK semantics, transitive deps): https://github.com/obra/superpowers/releases', - '- [ ] Review OpenSpec changelog: https://github.com/Fission-AI/OpenSpec/releases', - '- [ ] If safe, bump the Compatibility table in `superpowers-bridge/README.md` and `superpowers-bridge/README.zh-TW.md` (set `Last verified` to today).', - '- [ ] If breaking, add an entry under "Known breaking changes" in both READMEs.', - '', - `_Workflow run: ${runUrl}_`, - ].join('\n'); - - const { data: issues } = await github.rest.issues.listForRepo({ - owner: context.repo.owner, - repo: context.repo.repo, - state: 'open', - labels: 'upstream-version-check', - per_page: 10, - }); - const existing = issues.find(i => i.title === title); - if (existing) { - await github.rest.issues.createComment({ - owner: context.repo.owner, - repo: context.repo.repo, - issue_number: existing.number, - body, - }); - core.info(`Updated existing issue #${existing.number}`); - } else { - const { data: created } = await github.rest.issues.create({ - owner: context.repo.owner, - repo: context.repo.repo, - title, - body, - labels: ['upstream-version-check'], - }); - core.info(`Created issue #${created.number}`); - } - - - name: Fail run on schema breakage - if: steps.validate.outcome == 'failure' - run: | - echo "::error::Schema validation failed against latest OpenSpec ${{ steps.openspec.outputs.version }}" - exit 1 diff --git a/superpowers-bridge/README.md b/superpowers-bridge/README.md index 00e4688..6cb4bde 100644 --- a/superpowers-bridge/README.md +++ b/superpowers-bridge/README.md @@ -2,14 +2,15 @@ [English](./README.md) · [繁體中文](./README.zh-TW.md) -[![Schema Structure](https://github.com/JiangWay/openspec-schemas/actions/workflows/validate-schemas.yml/badge.svg?branch=main)](https://github.com/JiangWay/openspec-schemas/actions/workflows/validate-schemas.yml) -[![Upstream Drift](https://img.shields.io/github/issues-search/JiangWay/openspec-schemas?query=is%3Aopen%20label%3Aupstream-version-check&label=Upstream%20Drift&color=yellow)](https://github.com/JiangWay/openspec-schemas/issues?q=is%3Aopen+label%3Aupstream-version-check) -[![OpenSpec baseline](https://img.shields.io/badge/OpenSpec_baseline-1.4.1-0277bd)](#compatibility) -[![Superpowers baseline](https://img.shields.io/badge/Superpowers_baseline-v5.1.0-0277bd)](#compatibility) +[![Schema Structure](https://github.com/AdrianTheopold/openspec-schemas/actions/workflows/validate-schemas.yml/badge.svg?branch=main)](https://github.com/AdrianTheopold/openspec-schemas/actions/workflows/validate-schemas.yml) +[![OpenSpec baseline](https://img.shields.io/badge/OpenSpec_baseline-1.5.0-0277bd)](#compatibility) +[![Superpowers baseline](https://img.shields.io/badge/Superpowers_baseline-6.1.0-0277bd)](#compatibility) > Bridges [OpenSpec](https://github.com/Fission-AI/OpenSpec)'s artifact governance (the **what**) with [obra/superpowers](https://github.com/obra/superpowers) execution skills (the **how**) into a single workflow. Adds an evidence-first `retrospective` artifact filling a gap Superpowers does not natively cover. > > The integration lives entirely at the prompt layer — no Superpowers source modified, no OpenSpec CLI changes. Schema version: v1. +> +> **Fork** of [JiangWay/openspec-schemas](https://github.com/JiangWay/openspec-schemas) (upstream commit `f5d4040`), independently maintained since 2026-07-02 as the actively-maintained working fork (upstream is inactive); it diverges as needed and is not aimed at upstream PR-back. --- @@ -23,7 +24,7 @@ Copy and paste this into Claude Code in your project root: Install the superpowers-bridge schema for OpenSpec into this project: 1. Verify the project has an `openspec/` directory (run `openspec init` if missing). -2. Clone https://github.com/JiangWay/openspec-schemas to a temp dir. +2. Clone https://github.com/AdrianTheopold/openspec-schemas to a temp dir. 3. Copy the `superpowers-bridge/` subdirectory to `openspec/schemas/superpowers-bridge/`. 4. Run `openspec schema validate superpowers-bridge` to verify. 5. Run `openspec schemas` and confirm `superpowers-bridge` is listed. @@ -37,7 +38,7 @@ Install the superpowers-bridge schema for OpenSpec into this project: ### Method 2: Manual bash (CI / non-Claude environments) ```bash -git clone https://github.com/JiangWay/openspec-schemas /tmp/oss +git clone https://github.com/AdrianTheopold/openspec-schemas /tmp/oss cp -R /tmp/oss/superpowers-bridge ~/your-project/openspec/schemas/superpowers-bridge # Optional: insert workflow-routing fragment into CLAUDE.md @@ -64,7 +65,7 @@ In your project root, paste this into Claude Code: Upgrade the superpowers-bridge schema in this project: 1. Verify `openspec/schemas/superpowers-bridge/` already exists (upgrade, not fresh install). If missing, abort and tell me to use the install instructions instead. -2. Clone https://github.com/JiangWay/openspec-schemas to a temp dir. +2. Clone https://github.com/AdrianTheopold/openspec-schemas to a temp dir. 3. Show me the diff between the local `openspec/schemas/superpowers-bridge/` and the cloned `superpowers-bridge/` (use `diff -ruN`). Wait for my ack before overwriting. 4. After my ack, overwrite the local schema dir with the cloned one. 5. Run `openspec schema validate superpowers-bridge` to verify. @@ -83,7 +84,7 @@ Upgrade the superpowers-bridge schema in this project: ```bash # 1. Get the latest bundle -git clone https://github.com/JiangWay/openspec-schemas /tmp/oss-upgrade +git clone https://github.com/AdrianTheopold/openspec-schemas /tmp/oss-upgrade # 2. Review the diff first (don't overwrite blindly) diff -ruN ~/your-project/openspec/schemas/superpowers-bridge /tmp/oss-upgrade/superpowers-bridge @@ -187,7 +188,7 @@ If any condition is missing, keep brainstorming. When all five hold: | Anti-pattern | Why it's wrong | |---|---| | Letting brainstorming write to `docs/superpowers/specs/` after the schema is installed | Bypasses redirection at [schema.yaml](./schema.yaml) lines 35-39; produces orphan artifacts | -| Letting writing-plans write to `docs/superpowers/plans/` | Same reason (schema.yaml lines 169-171) | +| Letting writing-plans write to `docs/superpowers/plans/` | Same reason (schema.yaml lines 180-182) | | Promoting to opsx with unresolved blocking TBDs | Those TBDs will block apply phase too — promotion just defers the same problem | | Opening a change for bug fix / typo / config tweak | Process ceremony exceeds actual risk; slows delivery without value | @@ -222,7 +223,7 @@ The Artifact DAG above shows **file-existence** dependencies. The runtime lifecy flowchart TD Start([/opsx:propose · /opsx:new]) - subgraph Plan ["📝 PLANNING — 7 artifacts"] + subgraph Plan ["📝 PLANNING — 6 artifacts"] direction TB BS["brainstorm.md
superpowers:brainstorming"] PROP["proposal.md"] @@ -246,9 +247,9 @@ flowchart TD A1["1. Workspace
using-git-worktrees"] 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)"] + A4["4. Retrospective → retrospective.md
(BEFORE finish; hot context)"] A5["5. Archive
openspec archive -y
(sync delta + move folder)"] - A6["6. Completion
finishing-a-development-branch
🏁 PR is LAST"] + A6["6. Completion
finishing-a-development-branch
🏁 push is LAST"] A0 --> A1 --> A2 --> A3 A3 -. blocking → fix .-> A2 @@ -285,12 +286,12 @@ APPLY ━━━━━━━━━━━━━━━━━━━━━━━━ ▼ │ 4. retrospective.md (BEFORE PR; hot context) 5. openspec archive -y (sync delta + move folder) - 6. superpowers:finishing-a-development-branch (🏁 PR is LAST) + 6. superpowers:finishing-a-development-branch (🏁 push is LAST) ``` > **Timing notes** (full rationale in "Six design touches" #6): > - `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/`). +> - `retrospective.md` declares `requires: verify` and per Step 4 is produced **before** finish/push (step 6) — so the pushed branch 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. ### Seven Superpowers touchpoints @@ -303,11 +304,11 @@ APPLY ━━━━━━━━━━━━━━━━━━━━━━━━ | 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** | -| 7 | `superpowers:finishing-a-development-branch` | apply step 4 | Direct | +| 7 | `superpowers:finishing-a-development-branch` | apply step 6 | Direct | Plus one OpenSpec built-in: `openspec-verify-change` (apply step 3, produces `verify.md`). -> **No `executing-plans` fallback.** This schema is opinionated: it requires a subagent-capable platform (Claude Code, Codex, etc.). The alternative executor `superpowers:executing-plans` does not transitively activate TDD or code-review (verified against its [SKILL.md](https://github.com/obra/superpowers/blob/main/skills/executing-plans/SKILL.md)) — falling back would silently degrade Superpowers' core value. If your platform lacks subagent support, use the built-in `spec-driven` schema instead. +> **No `executing-plans` fallback.** This schema is opinionated: it requires a subagent-capable platform (Claude Code, Codex, etc.). The alternative executor `superpowers:executing-plans` does not transitively activate TDD or code-review (verified against its [SKILL.md](https://github.com/obra/superpowers/blob/v6.1.0/skills/executing-plans/SKILL.md)) — falling back would silently degrade Superpowers' core value. If your platform lacks subagent support, use the built-in `spec-driven` schema instead. ### Output redirection @@ -346,6 +347,8 @@ Implemented purely via context injection at invocation time, not by modifying sk /opsx:archive ``` +> **Profile note — this bridge's opsx flow requires OpenSpec's expanded workflow profile.** The **core** profile (the `openspec init` default) provides only `propose, explore, apply, sync, archive`; the expanded-only commands are `new, continue, ff, verify, bulk-archive, onboard` — and this bridge's flows lean on `/opsx:continue`, `/opsx:ff`, and `/opsx:verify` throughout, not just `/opsx:new`. Enable the expanded set by running `openspec config profile` (select the full workflow set in the picker) and then `openspec update`; running `openspec update` alone does **not** switch profiles. If you must stay on core, only the first step has a CLI equivalent (`openspec new change --schema superpowers-bridge`) — `/opsx:continue`/`/opsx:verify` have none, so the expanded profile is effectively required. (`/opsx:new` is the only create-command that accepts `--schema`; `/opsx:propose` and `/opsx:ff` use your project's default schema.) + ### Switching back to spec-driven ```bash # Use a different schema for one change @@ -378,12 +381,12 @@ Creates `.worktrees//`, switches to a new branch, runs setup, confi #### 2. Executor — `superpowers:subagent-driven-development` -Main agent reads `plan.md`, dispatches a fresh subagent per micro-task. Each subagent transitively activates: +Main agent reads `plan.md`, dispatches a fresh subagent per micro-task: -- **TDD** (`superpowers:test-driven-development`): write failing test → watch it fail → minimal code → pass; production code without prior test gets deleted -- **Per-task code review** (`superpowers:requesting-code-review`): spec-compliance review + code-quality review; critical issues block forward motion +- **TDD** (`superpowers:test-driven-development`): each subagent transitively activates it — write failing test → watch it fail → minimal code → pass; production code without prior test gets deleted +- **Per-task review**: after each task the controller dispatches subagent-driven-development's own merged task-reviewer (spec-compliance + code-quality) — not a separate skill invocation; critical issues block forward motion -Coarse `tasks.md` checkboxes tick as tasks complete. After all tasks, a final code review covers the whole implementation. +Coarse `tasks.md` checkboxes tick as tasks complete. After all tasks, a final whole-branch code review (`superpowers:requesting-code-review`) covers the implementation. This schema does NOT support `superpowers:executing-plans` as a fallback. See the "Six design touches" section below for rationale. @@ -407,7 +410,7 @@ Syncs delta specs into `openspec/specs//spec.md` and moves the chang #### 6. Completion — `superpowers:finishing-a-development-branch` -Confirms tests are green, presents merge / PR / keep-branch / discard options, cleans up the worktree. **PR is the last step** — if retro or archive haven't been done, finish them first. +Confirms tests are green, presents merge / PR / keep-branch / discard options. The worktree is cleaned up only on the merge or discard options; the push/PR path preserves it so you can iterate on PR feedback. **PR is the last step** — if retro or archive haven't been done, finish them first. --- @@ -415,7 +418,6 @@ 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 (one-shot) | `/opsx:ff ` | | Resume an interrupted change | `/opsx:continue ` | @@ -442,11 +444,11 @@ Integration lives entirely in `instruction:` fields (pure prompts). If Superpowe ### 3. Transitive dependencies made explicit -TDD and code-review are normally hidden inside `subagent-driven-development`'s SKILL.md. Our schema's apply step 2a instruction lists these two transitive activations explicitly, so a reader can see "what actually happens during apply" at a glance. +TDD and code-review are normally hidden inside `subagent-driven-development`'s SKILL.md. Our schema's apply step 2 instruction lists these two transitive activations explicitly, so a reader can see "what actually happens during apply" at a glance. ### 4. Opinionated: subagent platforms only, no manual fallback -This schema requires a subagent-capable platform (Claude Code, Codex, etc.). The alternative executor `superpowers:executing-plans` does NOT transitively activate TDD or code-review (verified against its [SKILL.md](https://github.com/obra/superpowers/blob/main/skills/executing-plans/SKILL.md) — its body has no mention of either, and its Integration section omits both `test-driven-development` and `requesting-code-review`). Falling back to it would silently lose what Superpowers brings to this integration. We prefer to fail loud at Step 0 and direct users to the built-in `spec-driven` schema instead. +This schema requires a subagent-capable platform (Claude Code, Codex, etc.). The alternative executor `superpowers:executing-plans` does NOT transitively activate TDD or code-review (verified against its [SKILL.md](https://github.com/obra/superpowers/blob/v6.1.0/skills/executing-plans/SKILL.md) — its body has no mention of either, and its Integration section omits both `test-driven-development` and `requesting-code-review`). Falling back to it would silently lose what Superpowers brings to this integration. We prefer to fail loud at Step 0 and direct users to the built-in `spec-driven` schema instead. ### 5. Evidence-based PRECHECK for verify and retrospective (Layer 2 capability detection) @@ -480,20 +482,22 @@ A bundle release `1.x.y` is a published cut of schema major `v1`. A future schem Baseline versions this schema was authored against. This is a **historical snapshot, not an end-to-end compatibility guarantee** — CI cannot run the full prompt-layer workflow in headless mode, so behavioral compatibility relies on human review when drift fires. -Current bundle release: **`1.0.0`** (git tag `v1.0.0`; see [VERSION](./VERSION)). +Current bundle release: **`1.1.0`** (see [VERSION](./VERSION)). | superpowers-bridge | OpenSpec CLI | Superpowers plugin | Baseline as of | |---|---|---|---| -| v1 | `1.4.1` | `v5.1.0` | 2026-06-10 | +| v1 | `1.5.0` | `6.1.0` | 2026-07-02 | + +> Re-attested against **Superpowers 6.1.0** (2026-07-02) via a full v5.1.0→6.1.0 skill diff: only `finishing-a-development-branch` (its push option no longer auto-creates the PR) and the merged SDD task-reviewer needed prose alignment; the SDD self-finish conflict predates v6 and is suppressed by the apply instruction. **OpenSpec 1.5.0** "Stores" is opt-in beta and does not affect this bridge — re-check the `changes/`+`specs/` paths only if a future release makes Stores the default layout. ### How this is checked -The contract is three layers — **baseline declaration + automated drift detection + human review** — not automated compatibility enforcement. +The contract is two layers — **baseline declaration + human review** — not automated compatibility enforcement. (The automated weekly drift bot was retired when this fork was established — upstream JiangWay is inactive.) | Layer | Mechanism | Catches | When it fires | |---|---|---|---| -| Structural | [`validate-schemas.yml`](../.github/workflows/validate-schemas.yml) on every push/PR; [`version-check.yml`](../.github/workflows/version-check.yml) weekly against latest OpenSpec | Schema-graph breaks (field renames, removed `requires:` edges, PRECHECK syntax changes) | CI run fails red | -| Drift notification | [`version-check.yml`](../.github/workflows/version-check.yml) weekly, compares baseline above against latest npm / GitHub release | Pinned ≠ latest upstream | Opens / updates a [labelled drift issue](https://github.com/JiangWay/openspec-schemas/issues?q=is%3Aopen+label%3Aupstream-version-check) for human review (workflow stays green — drift is normal, not a failure) | +| Structural | [`validate-schemas.yml`](../.github/workflows/validate-schemas.yml) on every push/PR | Schema-graph breaks (field renames, removed `requires:` edges, PRECHECK syntax changes) | CI run fails red | +| Baseline drift | Manual — a maintainer periodically compares the pinned baselines above against latest OpenSpec / Superpowers releases | Pinned ≠ latest upstream | Maintainer bumps the baselines + re-attests (no automated drift bot — it was retired with the fork) | | End-to-end workflow | **Not automated** | Behavioral changes inside Superpowers skills (renames, prose rewrites altering PRECHECK semantics, transitive-dependency changes); subtle OpenSpec engine semantic shifts | A human reads upstream release notes when the drift issue fires | The "Baseline as of" date is bumped when a maintainer manually re-runs a full cycle against the listed versions and confirms nothing degraded. Until then, the date marks human attestation, not an automated test pass. diff --git a/superpowers-bridge/README.zh-TW.md b/superpowers-bridge/README.zh-TW.md index 6f6d569..5af9a91 100644 --- a/superpowers-bridge/README.zh-TW.md +++ b/superpowers-bridge/README.zh-TW.md @@ -2,14 +2,15 @@ [English](./README.md) · [繁體中文](./README.zh-TW.md) -[![Schema Structure](https://github.com/JiangWay/openspec-schemas/actions/workflows/validate-schemas.yml/badge.svg?branch=main)](https://github.com/JiangWay/openspec-schemas/actions/workflows/validate-schemas.yml) -[![Upstream Drift](https://img.shields.io/github/issues-search/JiangWay/openspec-schemas?query=is%3Aopen%20label%3Aupstream-version-check&label=Upstream%20Drift&color=yellow)](https://github.com/JiangWay/openspec-schemas/issues?q=is%3Aopen+label%3Aupstream-version-check) -[![OpenSpec baseline](https://img.shields.io/badge/OpenSpec_baseline-1.4.1-0277bd)](#相容性) -[![Superpowers baseline](https://img.shields.io/badge/Superpowers_baseline-v5.1.0-0277bd)](#相容性) +[![Schema Structure](https://github.com/AdrianTheopold/openspec-schemas/actions/workflows/validate-schemas.yml/badge.svg?branch=main)](https://github.com/AdrianTheopold/openspec-schemas/actions/workflows/validate-schemas.yml) +[![OpenSpec baseline](https://img.shields.io/badge/OpenSpec_baseline-1.5.0-0277bd)](#相容性) +[![Superpowers baseline](https://img.shields.io/badge/Superpowers_baseline-6.1.0-0277bd)](#相容性) > 把 [OpenSpec](https://github.com/Fission-AI/OpenSpec) 的 artifact 治理流程(**做什麼**)與 [obra/superpowers](https://github.com/obra/superpowers) 的執行技能(**怎麼做**)整合為單一工作流。額外提供 evidence-first 的 `retrospective` artifact,補上 Superpowers 沒有的 retro 能力。 > > 整合**完全發生在 prompt 層**——不修改 Superpowers 任何程式碼,不修改 OpenSpec CLI。Schema 版本:v1。 +> +> 本 repo 是 [JiangWay/openspec-schemas](https://github.com/JiangWay/openspec-schemas) 的 **fork**(upstream commit `f5d4040`),自 2026-07-02 起作為實際維護的 working fork 獨立維護(upstream 已停止維護);會依需要自由分歧,不以回饋 upstream PR 為目標。 --- @@ -23,7 +24,7 @@ Install the superpowers-bridge schema for OpenSpec into this project: 1. Verify the project has an `openspec/` directory (run `openspec init` if missing). -2. Clone https://github.com/JiangWay/openspec-schemas to a temp dir. +2. Clone https://github.com/AdrianTheopold/openspec-schemas to a temp dir. 3. Copy the `superpowers-bridge/` subdirectory to `openspec/schemas/superpowers-bridge/`. 4. Run `openspec schema validate superpowers-bridge` to verify. 5. Run `openspec schemas` and confirm `superpowers-bridge` is listed. @@ -37,7 +38,7 @@ Install the superpowers-bridge schema for OpenSpec into this project: ### 方法 2:手動 bash(CI / 非 Claude 環境) ```bash -git clone https://github.com/JiangWay/openspec-schemas /tmp/oss +git clone https://github.com/AdrianTheopold/openspec-schemas /tmp/oss cp -R /tmp/oss/superpowers-bridge ~/your-project/openspec/schemas/superpowers-bridge # 可選:把 workflow-routing fragment 插進 CLAUDE.md @@ -64,7 +65,7 @@ claude plugin install superpowers@claude-plugins-official # 若尚未安裝 Upgrade the superpowers-bridge schema in this project: 1. Verify `openspec/schemas/superpowers-bridge/` already exists (upgrade, not fresh install). If missing, abort and tell me to use the install instructions instead. -2. Clone https://github.com/JiangWay/openspec-schemas to a temp dir. +2. Clone https://github.com/AdrianTheopold/openspec-schemas to a temp dir. 3. Show me the diff between the local `openspec/schemas/superpowers-bridge/` and the cloned `superpowers-bridge/` (use `diff -ruN`). Wait for my ack before overwriting. 4. After my ack, overwrite the local schema dir with the cloned one. 5. Run `openspec schema validate superpowers-bridge` to verify. @@ -83,7 +84,7 @@ Upgrade the superpowers-bridge schema in this project: ```bash # 1. 取最新的 bundle -git clone https://github.com/JiangWay/openspec-schemas /tmp/oss-upgrade +git clone https://github.com/AdrianTheopold/openspec-schemas /tmp/oss-upgrade # 2. 先看差異(不直接覆蓋) diff -ruN ~/your-project/openspec/schemas/superpowers-bridge /tmp/oss-upgrade/superpowers-bridge @@ -187,7 +188,7 @@ OpenSpec 管 **「做什麼」**(artifact 生命週期:proposal / specs / tasks | 反模式 | 為什麼錯 | |---|---| | schema 已安裝後仍讓 brainstorming 寫到 `docs/superpowers/specs/` | 繞過 [schema.yaml](./schema.yaml) line 35-39 的 redirection,留下 orphan artifact | -| 讓 writing-plans 寫到 `docs/superpowers/plans/` | 同理(schema.yaml line 169-171) | +| 讓 writing-plans 寫到 `docs/superpowers/plans/` | 同理(schema.yaml line 180-182) | | TBD 還沒收斂就升級到 opsx | 那些 TBD 在 apply phase 一樣會擋住進度,只是把問題往後挪 | | 對 bug fix / typo 也建 change | 流程儀式 > 實質風險,反而拖慢交付 | @@ -222,7 +223,7 @@ brainstorm ──┬──→ proposal ──→ specs ──┐ flowchart TD Start([/opsx:propose · /opsx:new]) - subgraph Plan ["📝 PLANNING — 7 個 artifact"] + subgraph Plan ["📝 PLANNING — 6 個 artifact"] direction TB BS["brainstorm.md
superpowers:brainstorming"] PROP["proposal.md"] @@ -246,9 +247,9 @@ flowchart TD A1["1. Workspace
using-git-worktrees"] A2["2. Executor
subagent-driven-development
↳ TDD + code-review(傳遞)"] A3["3. Verification
openspec-verify-change → verify.md"] - A4["4. Retrospective → retrospective.md
(PR 之前;hot context)"] + A4["4. Retrospective → retrospective.md
(finish 之前;hot context)"] A5["5. Archive
openspec archive -y
(sync delta + 搬 folder)"] - A6["6. Completion
finishing-a-development-branch
🏁 PR 是最後一步"] + A6["6. Completion
finishing-a-development-branch
🏁 push 是最後一步"] A0 --> A1 --> A2 --> A3 A3 -. blocking → 回去修 .-> A2 @@ -283,9 +284,9 @@ APPLY ━━━━━━━━━━━━━━━━━━━━━━━━ 3. openspec-verify-change → verify.md ◄┐ │ │ blocking → 回去修 ▼ │ - 4. retrospective.md(PR 之前;hot context) + 4. retrospective.md(finish 之前;hot context) 5. openspec archive -y(sync delta + 搬 folder) - 6. superpowers:finishing-a-development-branch(🏁 PR 是最後一步) + 6. superpowers:finishing-a-development-branch(🏁 push 是最後一步) ``` > **時序註記**(完整理由見下方「設計觸點 #6」): @@ -303,11 +304,11 @@ APPLY ━━━━━━━━━━━━━━━━━━━━━━━━ | 4 | `superpowers:subagent-driven-development` | apply step 2 | 直接 | | 5 | `superpowers:test-driven-development` | (#4 內部觸發) | **傳遞** | | 6 | `superpowers:requesting-code-review` | (#4 內部觸發) | **傳遞** | -| 7 | `superpowers:finishing-a-development-branch` | apply step 4 | 直接 | +| 7 | `superpowers:finishing-a-development-branch` | apply step 6 | 直接 | 加上一個 OpenSpec built-in:`openspec-verify-change`(apply step 3,產出 `verify.md`)。 -> **不支援 `executing-plans` fallback**。本 schema 是 opinionated 的:要求 subagent-capable 平台(Claude Code、Codex 等)。替代 executor `superpowers:executing-plans` 並**不會** transitively 觸發 TDD 或 code-review(已對 [SKILL.md](https://github.com/obra/superpowers/blob/main/skills/executing-plans/SKILL.md) 做事實查核 —— body 完全沒提到 TDD 或 code-review,Integration 段也未列出 `test-driven-development` 與 `requesting-code-review`)。退到 2b 等於靜默降級 Superpowers 的核心價值。若你的平台沒有 subagent 支援,改用 OpenSpec 內建的 `spec-driven` schema。 +> **不支援 `executing-plans` fallback**。本 schema 是 opinionated 的:要求 subagent-capable 平台(Claude Code、Codex 等)。替代 executor `superpowers:executing-plans` 並**不會** transitively 觸發 TDD 或 code-review(已對 [SKILL.md](https://github.com/obra/superpowers/blob/v6.1.0/skills/executing-plans/SKILL.md) 做事實查核 —— body 完全沒提到 TDD 或 code-review,Integration 段也未列出 `test-driven-development` 與 `requesting-code-review`)。退到 executing-plans 等於靜默降級 Superpowers 的核心價值。若你的平台沒有 subagent 支援,改用 OpenSpec 內建的 `spec-driven` schema。 ### Output redirection(產出重導) @@ -346,6 +347,8 @@ Superpowers skill 有預設輸出路徑(例如 brainstorming 寫到 `docs/superp /opsx:archive ``` +> **Profile 註記 —— 本 bridge 的 opsx 流程需要 OpenSpec 的擴充(expanded)workflow profile。** 核心(core)profile(`openspec init` 的預設)只提供 `propose, explore, apply, sync, archive`;擴充專屬的指令是 `new, continue, ff, verify, bulk-archive, onboard` —— 本 bridge 的流程從頭到尾都用到 `/opsx:continue`、`/opsx:ff`、`/opsx:verify`,不只 `/opsx:new`。啟用擴充指令請執行 `openspec config profile`(在互動選單選取完整 workflow 集)再跑 `openspec update`;單獨跑 `openspec update` **不會**切換 profile。若必須留在 core,只有第一步有 CLI 等效指令(`openspec new change --schema superpowers-bridge`)—— `/opsx:continue`/`/opsx:verify` 沒有等效,因此實務上必須啟用擴充 profile。(`/opsx:new` 是唯一接受 `--schema` 的建立指令;`/opsx:propose` 與 `/opsx:ff` 使用專案的預設 schema。) + ### 切回 spec-driven ```bash # 單一 change 用不同 schema @@ -378,12 +381,12 @@ skill 缺失 → STOP 並通知使用者,不靜默 fallback,本 schema 內也沒 #### 2. Executor — `superpowers:subagent-driven-development` -Main agent 讀 `plan.md`,為每個 micro-task 派發 fresh subagent。每個 subagent 自動傳遞: +Main agent 讀 `plan.md`,為每個 micro-task 派發 fresh subagent: -- **TDD**(`superpowers:test-driven-development`):先寫失敗測試 → 看著它 fail → 寫最小程式碼 → pass;production code 寫在沒測試之前會被刪掉重來 -- **per-task code review**(`superpowers:requesting-code-review`):spec compliance review + code quality review;Critical 級問題擋下進度 +- **TDD**(`superpowers:test-driven-development`):每個 subagent 自動傳遞 —— 先寫失敗測試 → 看著它 fail → 寫最小程式碼 → pass;production code 寫在沒測試之前會被刪掉重來 +- **per-task review**:每個 task 完成後由 controller 派發 subagent-driven-development 自己的 merged task-reviewer(spec compliance + code quality)—— 不是另外呼叫一個 skill;Critical 級問題擋下進度 -完成 coarse task 就更新 `tasks.md` checkbox。所有 task 跑完後,對整個 implementation 再做一次 final code review。 +完成 coarse task 就更新 `tasks.md` checkbox。所有 task 跑完後,對整個 branch 再做一次 final code review(`superpowers:requesting-code-review`)。 本 schema **不支援** `superpowers:executing-plans` 作為 fallback。理由見下方「六個值得記住的設計觸點」段。 @@ -399,15 +402,15 @@ Main agent 讀 `plan.md`,為每個 micro-task 派發 fresh subagent。每個 sub Evidence-first 反思:§0 Evidence(量化前置數據 —— commit 數、diff 大小、tasks done 比例、新依賴、validate 狀態等)加上 6 段分析(Wins / Misses / Plan deviations / Skill compliance / Surprises / Promote candidates)。每個 claim 引用 commit / file / 可量化事實,通常指向 §0 而非每行 inline 證據。procedure 直接內嵌在 artifact instruction —— 不依賴外部 skill(Decision 3 in 設計 spec:Claude Code plugin 化延後到 v1.x)。 -在開 PR **之前**寫好,讓 retro 跟其他 artifact 一起落在同一個 PR diff。 +在 finish/push **之前**寫好,讓 retro 跟其他 artifact 一起落在同一個 PR diff。 #### 5. Archive — `openspec archive -y`(或 `/opsx:archive`) -把 delta spec sync 到 `openspec/specs//spec.md`、把 change 目錄搬到 `openspec/changes/archive/YYYY-MM-DD-/`。在開 PR **之前**跑完,這樣 PR diff 反映完整的 archived cycle 狀態(所有 artifact 完成、spec 已 sync、folder 在 `archive/`)。 +把 delta spec sync 到 `openspec/specs//spec.md`、把 change 目錄搬到 `openspec/changes/archive/YYYY-MM-DD-/`。在 finish/push **之前**跑完,這樣 PR diff 反映完整的 archived cycle 狀態(所有 artifact 完成、spec 已 sync、folder 在 `archive/`)。 #### 6. Completion — `superpowers:finishing-a-development-branch` -確認 tests 全綠、呈現 merge / PR / keep-branch / discard 選項、清理 worktree。**PR 是最後一步** —— 若 retro 或 archive 還沒跑,先補完。 +確認 tests 全綠、呈現 merge / PR / keep-branch / discard 選項。worktree 只在 merge 或 discard 選項時清理;push/PR 路徑會保留它,方便你依 PR feedback 迭代。**PR 是最後一步** —— 若 retro 或 archive 還沒跑,先補完。 --- @@ -415,7 +418,6 @@ Evidence-first 反思:§0 Evidence(量化前置數據 —— commit 數、diff | 情境 | 指令 | |---|---| -| 首次 clone 專案後 | `bash scripts/install-git-hooks.sh` | | 新 change(互動式) | `/opsx:new --schema superpowers-bridge` 接著多次 `/opsx:continue` | | 新 change(一鍵) | `/opsx:ff ` | | 恢復中斷的 change | `/opsx:continue ` | @@ -442,11 +444,11 @@ Evidence-first 反思:§0 Evidence(量化前置數據 —— commit 數、diff ### 3. 傳遞依賴顯式化 -TDD 與 code-review 平常藏在 `subagent-driven-development` 的 SKILL.md 裡。本 schema apply step 2a 的 instruction **直接列出**這兩個 transitive activation,讓讀者一眼看懂「apply 階段到底會發生什麼」。 +TDD 與 code-review 平常藏在 `subagent-driven-development` 的 SKILL.md 裡。本 schema apply step 2 的 instruction **直接列出**這兩個 transitive activation,讓讀者一眼看懂「apply 階段到底會發生什麼」。 ### 4. Opinionated:只支援 subagent 平台,沒有手動 fallback -本 schema 要求 subagent-capable 平台(Claude Code、Codex 等)。替代 executor `superpowers:executing-plans` **不會** transitively 觸發 TDD 或 code-review(已對其 [SKILL.md](https://github.com/obra/superpowers/blob/main/skills/executing-plans/SKILL.md) 做事實查核 —— body 完全沒提及這兩者,Integration 段也未列出 `test-driven-development` 與 `requesting-code-review`)。退到 2b 等於靜默丟掉 Superpowers 帶給整合的核心價值。我們選擇在 Step 0 fail loud,並指引使用者改用內建的 `spec-driven` schema。 +本 schema 要求 subagent-capable 平台(Claude Code、Codex 等)。替代 executor `superpowers:executing-plans` **不會** transitively 觸發 TDD 或 code-review(已對其 [SKILL.md](https://github.com/obra/superpowers/blob/v6.1.0/skills/executing-plans/SKILL.md) 做事實查核 —— body 完全沒提及這兩者,Integration 段也未列出 `test-driven-development` 與 `requesting-code-review`)。退到 executing-plans 等於靜默丟掉 Superpowers 帶給整合的核心價值。我們選擇在 Step 0 fail loud,並指引使用者改用內建的 `spec-driven` schema。 ### 5. Evidence-based PRECHECK for verify and retrospective(Layer 2 capability detection) @@ -480,20 +482,22 @@ LLM 不必解讀 timing 文字 —— 跑指令、看結果即可。這是顧慮 本 schema 撰寫時所對齊的 upstream 基準版本。這是**歷史快照,不是端對端相容性承諾** — CI 無法在 headless 環境跑完整的 prompt-layer workflow,行為相容性依賴 drift 觸發人類檢核。 -目前 bundle release: **`1.0.0`**(git tag `v1.0.0`;見 [VERSION](./VERSION))。 +目前 bundle release: **`1.1.0`**(見 [VERSION](./VERSION))。 | superpowers-bridge | OpenSpec CLI | Superpowers plugin | 基準日期 | |---|---|---|---| -| v1 | `1.4.1` | `v5.1.0` | 2026-06-10 | +| v1 | `1.5.0` | `6.1.0` | 2026-07-02 | + +> 已對 **Superpowers 6.1.0**(2026-07-02)做完整 v5.1.0→6.1.0 skill diff 重新對齊:只有 `finishing-a-development-branch`(push 選項不再自動開 PR)與合併後的 SDD task-reviewer 需要 prose 對齊;SDD self-finish 衝突早於 v6 就存在,由 apply instruction 抑制。**OpenSpec 1.5.0** 的 "Stores" 是 opt-in beta,不影響本 bridge —— 只有未來某版把 Stores 設為預設 layout 時,才需重新檢查 `changes/`+`specs/` 路徑。 ### 驗證機制 -契約分三層 — **基準聲明 + 自動 drift 偵測 + 人類檢核** — 不是自動相容性 enforcement。 +契約分兩層 — **基準聲明 + 人類檢核** — 不是自動相容性 enforcement。(每週自動 drift bot 已隨 fork 建立而退役 —— upstream JiangWay 已停止維護。) | 層級 | 機制 | 抓什麼 | 觸發時機 | |---|---|---|---| -| 結構性 | [`validate-schemas.yml`](../.github/workflows/validate-schemas.yml) 每次 push/PR;[`version-check.yml`](../.github/workflows/version-check.yml) 每週對 latest OpenSpec 跑 | schema graph 結構性破壞(欄位改名、`requires:` 邊移除、PRECHECK 語法變動) | CI run 變紅 | -| Drift 通知 | [`version-check.yml`](../.github/workflows/version-check.yml) 每週,把基準 vs 最新 npm / GitHub release 字串比對 | Pinned ≠ latest upstream | 開 / 更新 [labelled drift issue](https://github.com/JiangWay/openspec-schemas/issues?q=is%3Aopen+label%3Aupstream-version-check),由人類檢核(workflow 維持綠 — drift 是正常狀態,不是錯誤) | +| 結構性 | [`validate-schemas.yml`](../.github/workflows/validate-schemas.yml) 每次 push/PR | schema graph 結構性破壞(欄位改名、`requires:` 邊移除、PRECHECK 語法變動) | CI run 變紅 | +| 基準 drift | 手動 —— maintainer 定期把上面 pinned 基準對照 latest OpenSpec / Superpowers release | Pinned ≠ latest upstream | maintainer 更新基準 + 重新 attest(沒有自動 drift bot —— 已隨 fork 退役) | | 端對端 workflow | **未自動化** | Superpowers skill 內部行為改變(改名、改寫 prose 影響 PRECHECK 語意、傳遞依賴變動);OpenSpec 引擎語意微調 | drift issue 觸發時,人類讀 upstream release notes | 「基準日期」由 maintainer 手動重跑完整 cycle 確認沒退步後才推進。在那之前,日期代表的是人類聲明,不是自動測試通過。 diff --git a/superpowers-bridge/VERSION b/superpowers-bridge/VERSION index 3eefcb9..9084fa2 100644 --- a/superpowers-bridge/VERSION +++ b/superpowers-bridge/VERSION @@ -1 +1 @@ -1.0.0 +1.1.0 diff --git a/superpowers-bridge/schema.yaml b/superpowers-bridge/schema.yaml index 65e2ca1..1b0ff8d 100644 --- a/superpowers-bridge/schema.yaml +++ b/superpowers-bridge/schema.yaml @@ -12,7 +12,8 @@ description: > If your platform lacks subagent support, use spec-driven instead. Each artifact / apply step verifies its required skills before invoking and surfaces a clear error if any are missing. - brainstorm → proposal → specs → tasks → plan → verify → retrospective. + brainstorm → proposal → specs, with design branching from brainstorm + in parallel; specs + design → tasks → plan → verify → retrospective. design is required (reorganizes raw brainstorm output into structured Context / Goals / Decisions / Risks / Migration; referenced by tasks and plan for implementation guidance). @@ -81,6 +82,34 @@ artifacts: 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: design generates: design.md description: Technical design document with implementation details @@ -113,34 +142,6 @@ artifacts: 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 @@ -190,6 +191,10 @@ artifacts: 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. + + Note (Superpowers 6.x): writing-plans emits a "## Global + Constraints" block and per-task "Interfaces" blocks; the + implementer MUST honor both. requires: - tasks @@ -199,15 +204,21 @@ artifacts: template: verify.md instruction: | PRECHECK — implementation evidence: + (Substitute in the commands below with this + change's directory name before running them.) Before producing verify.md, run BOTH commands. If either returns 0, STOP and tell the user that apply phase has not yet produced reviewable changes. 1. Commit evidence (must return > 0): - git log --oneline $(git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD origin/master 2>/dev/null)..HEAD | wc -l + git log --oneline $(git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD origin/master 2>/dev/null || git merge-base HEAD origin/HEAD 2>/dev/null || git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null)..HEAD | wc -l 2. Task progress (must return > 0): - grep -c '^- \[x\]' openspec/changes//tasks.md + grep -cE '^\s*- \[x\]' openspec/changes//tasks.md + (This returns 0 only if the apply executor failed to tick + tasks.md as tasks cleared — see apply step 2's ticking rule; + a 0 here on a genuinely-complete apply is a bookkeeping miss, + not incomplete work. Tick the boxes, then re-run.) Only after BOTH return positive numbers, proceed to invoke the verification skill below. @@ -457,6 +468,11 @@ artifacts: requires: - verify +# v6 notes: subagent-driven-development (6.x) applies explicit per-dispatch +# model selection (the skill is model-agnostic — e.g. a fast, cheap model for +# mechanical steps, the most capable for reasoning) and keeps +# a durable .superpowers/sdd/ progress ledger for long runs. Both are handled +# by the executor automatically — no instruction here duplicates them. apply: requires: [plan] tracks: tasks.md @@ -501,8 +517,22 @@ apply: Tell the executor: - Read plan.md in this change directory for micro-tasks - - Update tasks.md checkboxes as coarse tasks complete + - Tick tasks.md checkboxes IN THE SAME bookkeeping message where + you append the SDD progress-ledger line for a cleared task: + when a task's review comes back clean, flip its `- [ ]` to + `- [x]` in openspec/changes//tasks.md AND append the + ledger line together. tasks.md is the committed source of + truth (it travels in the PR diff and gates verify); the ledger + is throwaway per-worktree scratch. Never leave tasks.md + all-unchecked — the verify PRECHECK below will falsely STOP. - Work within the created worktree + - STOP after the final whole-branch review passes. Do NOT invoke + superpowers:finishing-a-development-branch and do NOT remove or + clean up the worktree — this bridge runs the finish sequence + itself at apply step 6, and the worktree + SDD ledger must + survive for steps 3-5 (verify / retrospective / archive). + Return control to the apply controller after the final review; + report the commit range and the ledger path. IMPORTANT — transitive skill activation: subagent-driven-development internally enforces the @@ -511,11 +541,18 @@ apply: - **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. + - **superpowers:requesting-code-review** — invoked only for + the FINAL whole-branch review before apply concludes. + Per-task review is handled INSIDE subagent-driven-development + by its own merged task-reviewer prompt (spec compliance + + code quality), not by a separate skill invocation. + + NOTE: subagent-driven-development's own flow ends by invoking + finishing-a-development-branch + worktree cleanup; under THIS + bridge that terminal step is SUPPRESSED (see the executor + instruction above) because the bridge sequences finish itself + at apply step 6. There is no native flag to disable it, so the + suppression is by instruction. This schema does NOT support `superpowers:executing-plans` as a fallback for non-subagent platforms. Per its SKILL.md, @@ -554,14 +591,19 @@ apply: all 8 artifacts done, spec synced into main specs, change under archive/. - 6. **Completion (PR is the LAST step)**: + 6. **Completion (finish + push is the LAST automated step)**: After retrospective + archive are both done, use the Skill tool to invoke **superpowers:finishing-a-development-branch**. - - The branch's PR diff MUST contain the complete archived - cycle. If it doesn't (e.g., because retrospective or archive - was skipped), STOP and complete those first. - - This is the canonical opening sequence for the PR — do NOT - reorder. + In Superpowers v6 finishing presents merge / push / keep / discard + options; on the push option it only pushes the branch and does NOT + open a PR/MR for you (the `gh pr create` step was removed upstream). + Opening the MR/PR is a separate human step — on GitLab use + `glab`; do NOT auto-open or auto-merge. + + The pushed branch MUST contain the complete archived cycle + (all 8 artifacts, specs synced, change under archive/). If it + doesn't (e.g., retrospective or archive was skipped), STOP and + complete those first. + + This is the canonical finish sequence — do NOT reorder. diff --git a/superpowers-bridge/templates/adopters/CLAUDE.md.fragment.md b/superpowers-bridge/templates/adopters/CLAUDE.md.fragment.md index 960f1c7..bc0c8ad 100644 --- a/superpowers-bridge/templates/adopters/CLAUDE.md.fragment.md +++ b/superpowers-bridge/templates/adopters/CLAUDE.md.fragment.md @@ -4,7 +4,9 @@ ## Workflow routing (read on session start) -This repo uses [`superpowers-bridge`](https://github.com/JiangWay/openspec-schemas/tree/main/superpowers-bridge) to bridge OpenSpec and Superpowers. Integration rules (language, artifact paths, PRECHECK) follow that bridge's README; this section is the routing guidance for Claude. +This repo uses [`superpowers-bridge`](https://github.com/AdrianTheopold/openspec-schemas/tree/main/superpowers-bridge) to bridge OpenSpec and Superpowers. Integration rules (language, artifact paths, PRECHECK) follow that bridge's README; this section is the routing guidance for Claude. + +> **Prerequisite:** this schema's opsx flow requires OpenSpec's **expanded** workflow profile (run `openspec config profile`, select the full workflow set, then `openspec update`). The default **core** profile lacks `new/continue/ff/verify/bulk-archive/onboard` — the commands referenced below. ### Entry routing @@ -43,4 +45,4 @@ When all 5 hold → proactively suggest "ready to `/opsx:propose`?" — wait for - Promoting to opsx with unresolved blocking TBDs - Opening a change for bug fix / typo -Full detail: [superpowers-bridge README §Entry & exit gates](https://github.com/JiangWay/openspec-schemas/blob/main/superpowers-bridge/README.md#entry--exit-gates). +Full detail: [superpowers-bridge README §Entry & exit gates](https://github.com/AdrianTheopold/openspec-schemas/blob/main/superpowers-bridge/README.md#entry--exit-gates). diff --git a/superpowers-bridge/templates/adopters/CLAUDE.md.fragment.zh-TW.md b/superpowers-bridge/templates/adopters/CLAUDE.md.fragment.zh-TW.md index 81880e3..94e5307 100644 --- a/superpowers-bridge/templates/adopters/CLAUDE.md.fragment.zh-TW.md +++ b/superpowers-bridge/templates/adopters/CLAUDE.md.fragment.zh-TW.md @@ -4,7 +4,9 @@ ## 變更工作流(Claude Code 啟動先讀) -本 repo 採用 [`superpowers-bridge`](https://github.com/JiangWay/openspec-schemas/tree/main/superpowers-bridge) 銜接 OpenSpec 與 Superpowers。整合規則(語言、artifact 路徑、PRECHECK)以該 bridge README 為準;以下是給 Claude 的 routing 指引。 +本 repo 採用 [`superpowers-bridge`](https://github.com/AdrianTheopold/openspec-schemas/tree/main/superpowers-bridge) 銜接 OpenSpec 與 Superpowers。整合規則(語言、artifact 路徑、PRECHECK)以該 bridge README 為準;以下是給 Claude 的 routing 指引。 + +> **前置條件:** 本 schema 的 opsx 流程需要 OpenSpec 的**擴充(expanded)** workflow profile(執行 `openspec config profile`,選取完整 workflow 集,再跑 `openspec update`)。預設的**核心(core)** profile 缺少 `new/continue/ff/verify/bulk-archive/onboard` —— 也就是下面引用到的指令。 ### 入口分流 @@ -43,4 +45,4 @@ - TBD 沒收斂就升級到 opsx - 對 bug fix / typo 也建 change -詳細見 [superpowers-bridge README §進入與離開的判斷](https://github.com/JiangWay/openspec-schemas/blob/main/superpowers-bridge/README.zh-TW.md#進入與離開的判斷entry--exit-gates)。 +詳細見 [superpowers-bridge README §進入與離開的判斷](https://github.com/AdrianTheopold/openspec-schemas/blob/main/superpowers-bridge/README.zh-TW.md#進入與離開的判斷entry--exit-gates)。