docs: add PRD for native skills install/update#395
Conversation
📝 WalkthroughWalkthroughAdds a Product Requirements Document specifying an agent-driven native skills install/update design for Superpowers, covering scope, requirements, safety/gating rules, migration/deprecation, approach options, risks/mitigations, and success criteria. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Possibly related issues
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: 1
🤖 Fix all issues with AI agents
In `@docs/plans/2026-01-31-native-skills-install-prd.md`:
- Line 31: The two sentences "Platform intent: cross-platform support (macOS,
Linux, Windows)" and "A PowerShell-native path may be a documented TODO" are
ambiguous; update the document so it explicitly states whether Windows will be
supported at launch and how (e.g., "Windows supported via shell-based path: Git
Bash/WSL at launch; PowerShell-native support deferred to a future release" or
"PowerShell-native support included at launch"). Replace or augment the TODO
with a clear status, acceptance criteria, and a target milestone if deferred, so
readers know whether Windows native PowerShell support is included or postponed.
🧹 Nitpick comments (3)
docs/plans/2026-01-31-native-skills-install-prd.md (3)
43-48: Clarify how "Superpowers-owned" content is identified.The collision safety rules distinguish between "user-owned content," "symlink not clearly owned by Superpowers," and "symlink owned by Superpowers," but the mechanism for determining ownership is not specified. Consider adding a requirement that defines how the installer will identify Superpowers-owned symlinks (e.g., by target path convention, by metadata, by marker file).
📝 Suggested addition to clarify ownership determination
Add after line 48:
- A symlink owned by Superpowers may be replaced during reconciliation. +- Ownership determination: Superpowers-owned symlinks should be identified by [mechanism TBD: e.g., target path pointing to a known Superpowers repository location, marker file, or metadata]. - Updates and uninstall must be safe and deterministic: re-running install reconciles state; uninstall removes only Superpowers-owned skills and the gating rule.
18-18: Consider documenting rationale for full-library constraint.The requirement states "Full-library installation is required (partial installs are invalid because skills reference each other)." While the reasoning is mentioned, consider whether this constraint could be revisited in the future if a dependency graph is introduced. Documenting this as a current constraint with potential for future evolution (in the non-goals or a future work section) would clarify the design intent.
66-70: Define the transition period for Option B.Option B recommends a hybrid approach with "a defined period" for bootstrap CLI fallback, but the document does not specify the duration or criteria for ending the transition. Consider adding a concrete timeline (e.g., "6 months," "until v2.0," or "until 90% of active users migrate") or defining the success metrics that would trigger bootstrap deprecation.
📝 Suggested addition to specify transition period
Add after line 70 or in the Migration section:
Transition period: The bootstrap CLI will remain supported for [duration TBD: e.g., 6 months, or until 90% of active Codex users have migrated to the native path]. Deprecation will be announced [timeframe] in advance, with migration guides provided.
aryeko
changed the title
obra
added
codex
2 participants
Add a PRD proposing a native, agent‑driven open‑spec install/update path for Superpowers skills, with safe migration from the current bootstrap flow.
Motivation and Context
The current Codex integration relies on a bespoke bootstrap CLI + repo clone, creating a non‑native experience and added maintenance. Codex and other major platforms now support the
Agent Skills open spec and standard discovery locations. A native install path reduces per‑session overhead and install friction, and makes updates/uninstall deterministic.
Standardizing on the open‑spec path should benefit Gemini support as well (#128).
How Has This Been Tested?
Not applicable — documentation‑only PR (PRD proposal, no code changes).
Breaking Changes
None — proposal only, no behavior change yet.
Types of changes
Checklist
Additional context
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.