An agentic skills framework & software development methodology that works.
Add testing documentation and local marketplace config
Jesse Vincentb063888520cd
diff --git a/docs/RELEASE-NOTES-v2.0.0.md b/docs/RELEASE-NOTES-v2.0.0.mdnew file mode 100644index 000000000..e51fa1f26--- /dev/null+++ b/docs/RELEASE-NOTES-v2.0.0.md@@ -0,0 +1,180 @@+# Superpowers v2.0.0 Release Notes++## Breaking Changes++This is a **major architectural change** that separates skills from the plugin into a standalone repository.++### What Changed++**Skills Repository Separation:**+- All skills and scripts have been extracted to a new repository: [obra/superpowers-skills](https://github.com/obra/superpowers-skills)+- The plugin is now a minimal shim that clones and manages the skills repository+- Skills are installed to `~/.config/superpowers/skills/` instead of being bundled with the plugin+- Users can now fork the skills repository and contribute improvements back to the community++**Environment Variable Change:**+- `CLAUDE_PLUGIN_ROOT` has been replaced with `SUPERPOWERS_SKILLS_ROOT`+- **Action Required:** If you have any custom skills or scripts that reference `${CLAUDE_PLUGIN_ROOT}`, you must update them to use `${SUPERPOWERS_SKILLS_ROOT}`++## Migration++**Automatic Migration:**+The plugin automatically handles migration from previous installations:+- On first run with v2.0.0, the initialization script detects old installations+- Your old `.git` directory is backed up to `.git.bak`+- Your old `skills/` directory is backed up to `skills.bak` (in case you have custom modifications)+- The new skills repository is cloned to `~/.config/superpowers/skills/`++**What You Need To Do:**+1. Update the plugin to v2.0.0+2. Start a new Claude Code session - the migration happens automatically+3. If you had custom skills in the old location, you'll find them in `~/.config/superpowers/skills.bak`+4. Move any custom skills to the new skills repository structure++## Fork Workflow++The new architecture enables a community-driven workflow for skill development:++### Contributing Skills++1. **During Initial Setup:**+ - If you have GitHub CLI (`gh`) installed, you'll be prompted to fork the skills repository+ - Forking allows you to push changes and submit pull requests++2. **Making Contributions:**+ ```bash+ cd ~/.config/superpowers/skills+ # Make your changes to skills+ git add .+ git commit -m "Describe your changes"+ git push origin main # Push to your fork+ # Create PR via GitHub web UI or gh CLI+ ```++3. **Syncing Upstream:**+ - The plugin checks for upstream updates on each session start+ - When updates are available, you'll see: "⚠️ New skills available from upstream"+ - Use the `pulling-updates-from-skills-repository` skill to sync your local repository++### If You Didn't Fork Initially++You can fork the repository manually later:+```bash+cd ~/.config/superpowers/skills+gh repo fork obra/superpowers-skills --remote=true+git remote add upstream https://github.com/obra/superpowers-skills.git+```++## New Skills++**pulling-updates-from-skills-repository:**+- Syncs your local skills repository with upstream changes+- Handles stashing/unstashing of uncommitted work+- Helps resolve merge conflicts+- Preserves your local modifications++## Installation++### New Installation+1. Install the superpowers plugin v2.0.0+2. Start a Claude Code session+3. The skills repository is automatically cloned to `~/.config/superpowers/skills/`+4. Optionally fork the repository when prompted (requires GitHub CLI)++### Updating From Previous Version+1. Update the plugin to v2.0.0+2. Start a Claude Code session - migration happens automatically+3. Check `~/.config/superpowers/skills.bak` for any custom skills you had+4. Migrate custom skills to the new repository structure++## Architecture Details++**Plugin Responsibilities:**+- Clone the skills repository on first run+- Check for upstream updates on session start+- Set the `SUPERPOWERS_SKILLS_ROOT` environment variable+- Register hooks that load skills from the local repository+- Notify users when upstream updates are available++**Skills Repository Responsibilities:**+- Contain all skills, scripts, and documentation+- Accept community contributions via pull requests+- Maintain independent versioning+- Enable users to customize and extend skills locally++**Benefits:**+- Skills can be updated independently of the plugin+- Community can contribute skills without plugin repository access+- Users can experiment with skills in a standard git workflow+- Easier to maintain and version control skills separately+- Clear separation of concerns between plugin infrastructure and skill content++## File Structure Changes++**Old Structure (bundled with plugin):**+```+superpowers/+├── skills/+│ ├── getting-started/+│ └── ...+└── scripts/+ ├── find-skills+ └── skill-run+```++**New Structure (separate repository):**+```+~/.config/superpowers/skills/ (cloned from obra/superpowers-skills)+└── skills/+ ├── using-skills/+ │ ├── find-skills+ │ ├── skill-run+ │ └── SKILL.md+ ├── meta/+ │ └── pulling-updates-from-skills-repository/+ └── ...+```++## Troubleshooting++**Skills repository not cloning:**+- Check your internet connection+- Verify Git is installed and accessible+- Try cloning manually: `git clone https://github.com/obra/superpowers-skills.git ~/.config/superpowers/skills`++**Custom skills not working:**+- Update path references from `${CLAUDE_PLUGIN_ROOT}` to `${SUPERPOWERS_SKILLS_ROOT}`+- Ensure scripts are executable: `chmod +x your-script.sh`+- Check that skills are in the correct directory structure++**Merge conflicts when updating:**+- Use the `pulling-updates-from-skills-repository` skill - it helps resolve conflicts+- Or manually resolve: `cd ~/.config/superpowers/skills && git status`++**Fork not created:**+- Install GitHub CLI: `brew install gh` (macOS) or see [GitHub CLI installation](https://cli.github.com/)+- Authenticate: `gh auth login`+- Fork manually: `gh repo fork obra/superpowers-skills --remote=true`++## Links++- **Skills Repository:** https://github.com/obra/superpowers-skills+- **Plugin Repository:** https://github.com/obra/superpowers+- **Skills Repository v1.0.0:** https://github.com/obra/superpowers-skills/releases/tag/v1.0.0+- **Report Issues:** https://github.com/obra/superpowers/issues++## Credits++This architectural change enables the superpowers community to collaboratively improve and extend skills. Thank you to all future contributors!++---++**For Plugin Developers:**++If you're building tools that interact with superpowers:+- Use `SUPERPOWERS_SKILLS_ROOT` environment variable to locate skills+- Default location: `~/.config/superpowers/skills/`+- Skills repository: https://github.com/obra/superpowers-skills+- Tool paths:+ - find-skills: `${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/find-skills`+ - skill-run: `${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/skill-run`