feat(schemas): add sdd-plus-superpowers — integrate Superpowers skills via custom schema (ref #780)#970
feat(schemas): add sdd-plus-superpowers — integrate Superpowers skills via custom schema (ref #780)#970JiangWay wants to merge 6 commits into
Conversation
…d INTEGRATION doc 新增 verify artifact + templates/verify.md 新增 INTEGRATION.md（七節 onboarding 文件） schema.yaml：apply executor 拆 2a/2b、design 變可選、顯式化 TDD/code-review 傳遞 templates/brainstorm.md：加 Alternatives Considered templates/proposal.md：加 Why 字數限制 + From/To 格式 templates/spec.md：展開 MODIFIED/REMOVED/RENAMED delta + archive 套用順序
|
Task completed. I'll start by reviewing the PR diff and understanding the codebase context. Powered by 1Code |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
✅ Files skipped from review due to trivial changes (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughAdds a new project-level OpenSpec schema "sdd-plus-superpowers" with integration docs and templates that wire OpenSpec artifact workflows to Superpowers execution skills via instruction-injected skill calls, defining artifact lifecycle (brainstorm → proposal → design/specs → tasks → plan → apply → verify) and detailed apply/verify orchestration. Changes
Sequence Diagram(s)sequenceDiagram
participant CLI as OpenSpec CLI
participant Schema as sdd-plus-superpowers/schema
participant Super as Superpowers (skills)
participant Git as Git Worktree/Repo
participant Subagent as Subagent Worker
CLI->>Schema: start/change lifecycle (/opsx:new / /opsx:continue / /opsx:apply)
Schema->>Super: invoke superpowers:brainstorm / superpowers:writing-plans / ...
Super-->>Schema: produce artifacts (brainstorm.md, plan.md, specs, ...)
Schema->>Git: pre-flight commit change dir & create worktree
Git->>Subagent: dispatch subagent-driven-development (TDD, per-task reviews)
Subagent-->>Git: commit/push implementation changes
CLI->>Schema: trigger verify (/opsx:verify / openspec-verify-change)
Schema->>Super: invoke superpowers:finishing-a-development-branch / executing-plans (or fallback)
Super-->>CLI: verification report and archive decision
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@schemas/sdd-plus-superpowers/INTEGRATION.md`:
- Around line 40-81: The fenced ASCII DAG in INTEGRATION.md opens with an
unlabeled code fence which triggers markdownlint MD040; update the opening fence
for the DAG block (the triple backticks immediately before the ASCII diagram) to
include a language tag such as "text" (i.e. change ``` to ```text) so the block
is explicitly labeled and the linter warning is resolved; ensure the closing
fence remains ``` unchanged.
In `@schemas/sdd-plus-superpowers/README.md`:
- Around line 83-88: The README flow lists /opsx:continue entries and currently
implies that "design" is mandatory; update the sequence text to indicate that
the "design" step is optional (e.g., add "(optional)" or "— optional" after the
`design` entry) so operators know it need not always be performed; modify the
lines containing the `/opsx:continue` entries (specifically the entry
referencing `design`) to include the optional marker and keep formatting
consistent with the surrounding entries.
- Around line 30-34: The fenced diagram block currently has no language tag;
update the code fence around the ASCII workflow (the triple-backtick block
containing "brainstorm ──→ proposal ──→ specs ──→ tasks ──→ plan ...") to
include a language identifier (e.g., change ``` to ```text) so the README.md
passes MD040 linting and renders consistently.
In `@schemas/sdd-plus-superpowers/schema.yaml`:
- Line 1: Normalize the schema file's line endings to LF by converting the file
that contains "name: sdd-plus-superpowers" to use Unix line endings (LF) instead
of CRLF; update the file's line endings (or add a .gitattributes entry for YAML
files to enforce eol=lf) and re-save/commit the file so yamllint no longer
reports "new-lines" errors.
In `@schemas/sdd-plus-superpowers/templates/verify.md`:
- Around line 19-21: The fenced code block in verify.md that contains "<貼上
openspec validate --all 的輸出摘要>" is missing a language identifier (causing
MD040); update the opening fence from ``` to ```text so the block reads as a
text/code block and tools render/lint it consistently, leaving the contained
output unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: d8537d19-e0ee-4ea1-b062-787422688d55
📒 Files selected for processing (10)
schemas/sdd-plus-superpowers/INTEGRATION.mdschemas/sdd-plus-superpowers/README.mdschemas/sdd-plus-superpowers/schema.yamlschemas/sdd-plus-superpowers/templates/brainstorm.mdschemas/sdd-plus-superpowers/templates/design.mdschemas/sdd-plus-superpowers/templates/plan.mdschemas/sdd-plus-superpowers/templates/proposal.mdschemas/sdd-plus-superpowers/templates/spec.mdschemas/sdd-plus-superpowers/templates/tasks.mdschemas/sdd-plus-superpowers/templates/verify.md
…ission-AI#970 - Convert schema.yaml to LF line endings (yamllint) - Add `text` language tag to ASCII DAG / placeholder code fences in README.md, INTEGRATION.md, and templates/verify.md (markdownlint MD040) - Mark `design` step as optional in README.md stepwise flow Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ive guidance Apply phase additions in schema.yaml: - Step 0 (Pre-flight): commit openspec/changes/<name>/ to current branch BEFORE creating the worktree. Prevents "untracked files would be overwritten by merge" errors when integrating the worktree back, and keeps planning-phase artifacts separate from implementation-phase commits. - Post-completion Recommended section: non-blocking guidance to produce retrospective.md before archive, with the six evidence- first sections (wins / misses / plan deviations / skill compliance / surprises / promote candidates). Mentions optional workflow-retrospective skill for automation, but works fine with manual authoring — no new skill dependency introduced. INTEGRATION.md updates: - Document section 3-0 (Pre-flight) with rationale - Document section 3-5 (Retrospective) as a recommended-but-non- blocking habit that raises the quality of every subsequent change Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
@JiangWay 文中提到: 请问如何能看出用的是2a还是2b呢? |
alfred-openspec
left a comment
alfred-openspec
left a comment
There was a problem hiding this comment.
Thanks for putting this together. I think the user need is real, but I would not merge this as a built-in schema in this form.
The strongest part of the PR is the product shape: using OpenSpec's schema mechanism is a cleaner integration point than trying to repackage /opsx:* as a Superpowers skill pack, and the brainstorm → proposal → specs → tasks → plan bridge maps the two systems pretty clearly.
My concern is that putting this under schemas/ makes OpenSpec own a third-party workflow integration with no compatibility boundary. The schema is tightly coupled to current Superpowers skill names and semantics (brainstorming, writing-plans, using-git-worktrees, subagent-driven-development, transitive TDD/code-review behavior, etc.), but there is no Superpowers version check, install check, capability detection, or fallback beyond prompt text. If Superpowers changes a skill name or behavior, OpenSpec would silently ship a stale built-in schema.
There is also a workflow-state mismatch around verify: it is modeled as an artifact with requires: [plan], but the instructions say it must only be produced after apply. The current artifact graph is filesystem/state based and will mark verify ready as soon as plan.md exists. That means the engine cannot enforce the timing rule, so this depends on the model obeying a paragraph of prompt text. That feels too fragile for a packaged workflow.
A smaller but still important issue: apply.instruction tells the agent to inspect git state and potentially create a commit before creating the worktree. That is a real repository side effect inside a schema instruction, and it is much more aggressive than OpenSpec's default apply guidance. I would not want that behavior bundled without a clearer product decision.
I would suggest one of two paths:
- Keep this as a community recipe / external package for now, linked from docs or the issue. It is useful as a proof point and gives Superpowers users something concrete.
- If we want this in core, first define the extension contract: version/capability detection for external skills, tests that load the schema and assert template presence/DAG/apply behavior, and a clearer stance on post-apply artifacts so
verifyis not just prompt-enforced.
So my recommendation is: great signal, probably not merge as a built-in schema yet. Use it to drive the broader "community workflow packs / schema distribution" direction rather than making OpenSpec maintain this exact Superpowers bridge in-tree.
|
Thanks for the thorough review. After sitting with your feedback, your concerns are valid and I agree the right move here is treating this as a community schema rather than pushing for built-in inclusion. Searching for precedent on how to do this well: github/spec-kit handles analogous third-party tool integrations via a community extension catalog, with bridges like RbBtSn0w/spec-kit-extensions/superpowers-bridge and WangX0111/superspec living in their own repos. I used that pattern as the reference solution and moved the schema out of OpenSpec core into: 👉 https://github.com/JiangWay/openspec-schemas/tree/main/superpowers-bridge Concrete responses to your three concerns (full rationale in the bridge README's "Six design touches" section): 3. Auto-commit (apply Step 0) — Removed entirely. Handling untracked change artifacts is the worktree skill's responsibility, not the schema's. Step 0 now performs a Superpowers skill availability check instead. 1. Strong coupling without capability detection — Each Superpowers invocation performs a PRECHECK. For `verify` and `retrospective`, the PRECHECK uses observable shell evidence (`git log`, `grep` on `tasks.md` / `verify.md`) — the LLM checks concrete runtime state rather than interpreting timing prose. 2. verify timing mismatch — Documented as a known limitation with a named migration target (a `post_apply` phase concept analogous to spec-kit's `after_implement` hook). The evidence-based PRECHECK above is the v1 mitigation. Will migrate to engine-native enforcement when/if OpenSpec adopts that mechanism. Closing this PR. Submitting a separate small docs-only PR with two changes:
Feel free to merge, partially merge (e.g. just the docs change without the README mention), or close that one independently — the external repo stands on its own either way. |
|
@brainwang 規則修了 —— v1 已直接移除 2b fallback,改成只支援 subagent 平台。 對
所以原本退到 2b 等於默默丟掉 Superpowers 整合的核心價值(TDD 紀律 + per-task review)。schema v1 在 apply Step 0 PRECHECK 直接擋下:
你不會再需要判斷 2a 還是 2b —— 通過 PRECHECK 就是 2a,沒通過就是 STOP。 詳細在新 repo: |
Evidence-first 6-section retrospective covering the brainstorm → plan → execute → response cycle that produced this repo. Wins: external-repo strategy worked, ate own dog food end-to-end, fact-check culture held under pressure, bilingual from start, atomic commits. Misses: 2b dead-code only caught by user, README/INTEGRATION 60% overlap not caught until audit, OAuth workflow scope blocked first push, T8 orphan heading, final code-reviewer hit Stream idle timeout. Plan deviations: pivoted from 'modify PR #970 in-place' to external repo + small docs PR; dropped 2b after fact-check; consolidated INTEGRATION into bridge README. Surprises: spec-kit ecosystem already had 2 superpowers bridges; executing-plans SKILL.md is dramatically thinner than subagent-driven-development; OAuth workflow scope is a real thing. Promote candidates: doc-overlap audit checklist, schema dead-code detection, fact-check-before-defending culture (already noted). Refs: - PR #970: Fission-AI/OpenSpec#970 - PR #1043: Fission-AI/OpenSpec#1043 - Issue #780: Fission-AI/OpenSpec#780
Adds a "Community Schemas" section to docs/customization.md cataloging community-maintained schema bundles distributed via standalone repositories. Modeled after github/spec-kit's community extension catalog (https://github.com/github/spec-kit/tree/main/extensions). The first entry is `superpowers-bridge` from JiangWay/openspec-schemas — born from the proposal in PR Fission-AI#970 and now maintained externally. Also adds a brief 4-line "Community schemas" introductory section in README.md (between Docs and Why OpenSpec) pointing readers to the catalog. Documentation only; no code or schema changes. Refs: Fission-AI#970 Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds a "Community Schemas" section to docs/customization.md cataloging community-maintained schema bundles distributed via standalone repositories. Modeled after github/spec-kit's community extension catalog (https://github.com/github/spec-kit/tree/main/extensions). The first entry is `superpowers-bridge` from JiangWay/openspec-schemas — born from the proposal in PR Fission-AI#970 and now maintained externally. Also adds a brief 4-line "Community schemas" introductory section in README.md (between Docs and Why OpenSpec) pointing readers to the catalog. Documentation only; no code or schema changes. Refs: Fission-AI#970 Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
3 participants
Context
This PR addresses #780 — the request to distribute OpenSpec as a Superpowers skill pack so that both frameworks can coexist without manual coordination.
In my comment on that issue I suggested that the cleanest path forward is not packaging one inside the other, but using OpenSpec's own project-level schema mechanism to wire Superpowers skills into the artifact lifecycle. I shared an early fork-based draft at that time:
This PR contributes the refined, upstream-ready version of that schema, with several corrections and additions made after real-world use.
Why a custom schema (instead of a skill pack)
Distributing OpenSpec as a Superpowers skill pack would require maintaining
/opsx:*commands in two places, and would blur the line between OpenSpec's CLI (which enforces artifact structure) and Superpowers' skill system (which is prompt-only). A custom schema is strictly better because:schemas/,--schema <name>at change creation, native validation).instruction:prompt layer.openspec schemas, which is exactly the discovery mechanism [Feature Request] Distribute OpenSpec as a Superpowers (obra/superpowers) skill pack #780 asks for.What this schema does
sdd-plus-superpowersextendsspec-drivenwith:superpowers:brainstorming, with output redirected into the change directory so both systems share a single source of truth instead of writing todocs/superpowers/....tasks.md(coarse checkboxes), aplan.mdartifact invokessuperpowers:writing-plansto decompose work into 2-5 minute TDD steps.using-git-worktrees→subagent-driven-development(with transitive TDD + code-review) →openspec-verify-change→finishing-a-development-branch.Artifact DAG
Two things worth flagging:
designis an optional leaf. Brainstorming may pre-filldesign.md, buttasks.requires: [specs]only — matching OpenSpec conventions that design docs exist only for non-trivial technical decisions.verify.requires: [plan]is structural. The instruction explicitly states verify MUST run on a completed implementation. The DAG edge exists soopenspec statuscan surface verification progress; the timing is intentional.Apply-phase integration
The 2a/2b split follows Superpowers' own guidance —
executing-plans/SKILL.mdstates "If subagents are available, usesuperpowers:subagent-driven-developmentinstead of this skill." On Claude Code, 2a is always the right path; 2b is documented only for constrained runtimes, with an explicit note that transitive TDD and code-review do not carry over under 2b (the author must invoke them manually).Changes since the draft linked in #780 (commit 6449135)
Reviewers who saw the original fork version will notice the following refinements:
verifyartifact +templates/verify.md— the original draft relied on a separate slash command; this version formalizes verification as an artifact soopenspec statuscan track it andopenspec validatecan check its structure.designdemoted to optional — originallytasks.requires: [specs, design]. Experience showeddesign.mdwas frequently empty for small changes, causing false incomplete-state signals. Nowtasks.requires: [specs]only.subagent-driven-development. This version documents the fallback and explicitly lists transitive skill activation for readability.proposal.md— Why-section character limits (50-1000), From/To format for behavioral changes.spec.md— MODIFIED / REMOVED / RENAMED delta sections with archive-time apply order notes.brainstorm.md— Alternatives Considered section (the original had only "Agreed Approach").INTEGRATION.md— onboarding reference covering integration nature, skill touchpoints, artifact DAG, full change lifecycle, CLI cheat sheet, and the five design decisions behind the schema. Intended for teams adopting this schema in their own repos.Compatibility
--schema sdd-plus-superpowersat/opsx:newtime.Testing
openspec validate --all --jsonpasses for sample changes authored under this schema./opsx:new --schema sdd-plus-superpowers→/opsx:continuethrough all 6 planning artifacts →/opsx:apply→/opsx:verify→/opsx:archive, producing a clean archived change with synced delta specs.Notes for reviewers
core/, CLI commands, or thespec-drivenschema.INTEGRATION.md§7 is deliberately a snapshot template (placeholders), not project-specific content — each adopting repo fills in its own capability list, CLI versions, and plugin versions.INTEGRATION.mdcan be moved todocs/instead of sitting alongside the schema — happy to relocate based on reviewer preference.Related
JiangWay/OpenSpec@6449135/schemas/sdd-plus-superpowersSummary by CodeRabbit
New Features
Documentation