summaryrefslogtreecommitdiff
path: root/docs
AgeCommit message (Collapse)Author
2026-04-13fix: replace hardcoded /Users/jesse with generic placeholders (#858)Drew Ritter
2026-04-13docs: drop instruction file enumeration per PR #1121 reviewDrew Ritter
Jesse flagged that the verbose CLAUDE.md/AGENTS.md/GEMINI.md/.cursorrules enumeration (a) chews tokens, (b) confuses models that anchor on exact strings, and (c) is repeated DRY-violatingly across 3+ locations. Replace with abstract "your instructions" framing in four spots: - skills/using-git-worktrees/SKILL.md Step 0 → Step 1 transition - skills/using-git-worktrees/SKILL.md Step 1b Directory Selection - docs/superpowers/plans/2026-04-06-worktree-rototill.md (both mirror locations) Same intent, harness-agnostic phrasing, ~half the tokens. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-13docs: address PR #1121 review — respect user preference, drop y/nDrew Ritter
- Consent prompt: drop "(y/n)" and add escape valve for users who have already declared their worktree preference in global or project agent instruction files. - Directory selection: reorder to put declared user preference ahead of observed filesystem state, and reframe the default as "if no other guidance available". - Sandbox fallback: require explicitly informing the user that the sandbox blocked creation, not just "report accordingly". - writing-plans: fully qualify the superpowers:using-git-worktrees reference. - Plan doc: mirror the consent-prompt change. Step 1a native-tool framing and the helper-scripts suggestion are still outstanding — the first needs a benchmark re-run before softer phrasing can be adopted without regressing compliance; the second is exploratory and will get a thread reply. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-06docs: cross-platform validation on 5 harnesses (PRI-974)Drew Ritter
Tested on Gemini CLI (gemini -p) and Cursor Agent (cursor-agent -p): - Gemini: Step 0 detection 1/1, Step 1b fallback 1/1 - Cursor: Step 0 detection 1/1, Step 1b fallback 1/1 Both correctly identified no native agent-callable worktree tool, fell through to git worktree add, and performed safety verification. Both correctly detected existing worktrees and skipped creation. 5 of 6 harnesses now tested. Only OpenCode untested (no CLI access). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-06docs: honest cross-platform validation table in spec (PRI-974)Drew Ritter
Research confirmed Claude Code is currently the only harness with an agent-callable mid-session worktree tool. All others either create worktrees before the agent starts (Codex App, Gemini, Cursor) or have no native support (Codex CLI, OpenCode). Table now shows: what was actually tested (Claude Code 50/50, Codex CLI 6/6), what was simulated (Codex App 1/1), and what's untested (Gemini, Cursor, OpenCode). Step 1a is forward-compatible for when other harnesses add agent-callable tools. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-06docs: update spec with TDD findings on Step 1a (PRI-974)Drew Ritter
Step 1a's original "deliberately short, abstract" design was disproven by TDD (2/6 pass rate). Spec now documents the validated approach: explicit tool naming + consent bridge + red flag (50/50 pass rate). - Design Principles: updated to reflect explicit naming over abstraction - Step 1a: replaced abstract text with validated approach, added design note explaining the TDD revision and why file splitting was unnecessary - Risks: Step 1a risk marked RESOLVED with cross-platform validation table and residual risk note about upstream tool description dependency Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-06docs: add worktree rototill implementation plan (PRI-974)Drew Ritter
5 tasks: TDD gate for Step 1a, using-git-worktrees rewrite, finishing-a-development-branch rewrite, integration updates, end-to-end validation. Task 1 is a hard gate — if native tool preference fails RED/GREEN, stop and redesign. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-06docs: honest spec revisions after issue/PR deep diveDrew Ritter
- Step 1a is the load-bearing assumption, not just a risk — if it fails, the entire design needs rework. TDD validation must be first impl task. - #1009 resolution depends on Step 1a working, stated explicitly - #574 honestly deferred, not "partially addressed" - Add hooks symlink to Step 1b (PR #965 idea, prevents silent hook loss) - Add stale worktree pruning to Step 5 (PR #1072 idea, one-line self-heal) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-06docs: address SWE review feedback on worktree rototill specDrew Ritter
- Fix Bug #999 order: merge → verify → remove worktree → delete branch (avoids losing work if merge fails after worktree removal) - Add submodule guard to Step 0 detection (GIT_DIR != GIT_COMMON is also true in submodules) - Preserve global path (~/.config/superpowers/worktrees/) in detection for backward compatibility, just stop offering it to new users - Add step numbering note and implementation notes section - Expand provenance heuristic to cover global path and manual creation Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-06docs: add worktree rototill design spec (PRI-974)Drew Ritter
Design for detect-and-defer worktree support. Superpowers defers to native harness worktree systems when available, falls back to manual git worktree creation when not. Covers Phases 0-2: detection, consent, native tool preference, finishing state detection, and three bug fixes (#940, #999, #238). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-23docs: add implementation plan for Codex App compatibility (PRI-823)Drew Ritter
8 tasks covering: environment detection in using-git-worktrees, Step 1.5 + cleanup guard in finishing-a-development-branch, Integration line updates, codex-tools.md docs, automated tests, and final verification. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-23docs: add cleanup guard test (#5) and sandbox fallback test (#10) to specDrew Ritter
Both tests address real risk scenarios: - #5: cleanup guard bug would delete Codex App's own worktree (data loss) - #10: Local thread sandbox fallback needs manual Codex App validation Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-23docs: clarify executing-plans in What Does NOT Change sectionDrew Ritter
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-23docs: address team review feedback for PRI-823 specDrew Ritter
- Add commit SHA + data loss warning to handoff payload (HIGH) - Add explicit commit step before handoff (HIGH) - Remove misleading "mark as externally managed" from Path B - Add executing-plans 1-line edit (was missing) - Add branch name derivation rules - Add conditional UI language for non-App environments - Add sandbox fallback for permission errors - Add STOP directive after Step 0 reporting Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-23docs: address spec review feedback for PRI-823Drew Ritter
Fix three Important issues from spec review: - Clarify Step 1.5 placement relative to existing Steps 2/3 - Re-derive environment state at cleanup time instead of relying on earlier skill output - Acknowledge pre-existing Step 5 cleanup inconsistency Also: precise step references, exact codex-tools.md content, clearer Integration section update instructions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-23docs: add Codex App compatibility design spec (PRI-823)Drew Ritter
Design for making using-git-worktrees, finishing-a-development-branch, and subagent-driven-development skills work in the Codex App's sandboxed worktree environment. Read-only environment detection via git-dir vs git-common-dir comparison, ~48 lines across 4 files, zero breaking changes. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-16Merge pull request #749 from ynyyn/fix-codex-multi-agent-flagJesse Vincent
fix(docs): replace deprecated `collab` flag with `multi_agent` for Codex docs
2026-03-16Merge pull request #753 from obra/f/opencode-pluginJesse Vincent
Auto-register skills from plugin, simplify OpenCode install
2026-03-15Auto-register skills from plugin, simplify OpenCode install to one linejesse
The plugin's new `config` hook injects the skills directory into OpenCode's live config singleton, so skills are discovered automatically without symlinks or manual config edits. Installation is now just adding one line to opencode.json: "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"] Rewrote docs/README.opencode.md and .opencode/INSTALL.md to reflect the new approach, removing ~200 lines of platform-specific symlink instructions. Added migration notes for existing users. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-15fix(hooks): replace BASH_SOURCE with POSIX-safe $0jesse
Replace ${BASH_SOURCE[0]:-$0} with $0 in hooks/session-start and the polyglot-hooks docs example. BASH_SOURCE uses bash array syntax that causes 'Bad substitution' on systems where /bin/sh is dash (Ubuntu). Since session-start is always executed (never sourced), $0 and BASH_SOURCE give the same result. Tested on Linux (bash + dash) and Windows (Git Bash via CMD and direct). Based on #553, closes #553. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-16Fix deprecated collab flag in Codex docsynyyn
2026-03-11Add implementation plan for zero-dep brainstorm serverJesse Vincent
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-11Add design spec and tests for zero-dep brainstorm serverJesse Vincent
Replace vendored node_modules (714 files) with a single server.js using only Node built-ins. Spec covers WebSocket protocol, HTTP serving, file watching, and static file serving. Tests written before implementation (TDD). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-09fix(opencode): correct TodoWrite tool mapping to todowriteMatt Van Horn
TodoWrite maps to OpenCode's built-in `todowrite` tool, not `update_plan`. Verified against OpenCode source (packages/opencode/src/tool/todo.ts). Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
2026-03-06Replace 'For Claude' with 'For agentic workers' in plan headersJesse Vincent
2026-03-06docs: add document review system spec and planJesse Vincent
- Spec: docs/superpowers/specs/2026-01-22-document-review-system-design.md - Plan: docs/superpowers/plans/2026-01-22-document-review-system.md Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-03-06Add visual brainstorming implementation plan and refactor docsJesse Vincent
Implementation plan for the visual brainstorming companion, plus spec and plan for the subsequent browser-displays refactor. Co-Authored-By: Drew Ritter <drew@ritter.dev>
2026-03-06Add SUBAGENT-STOP gate to prevent subagent skill leakageDrew Ritter
Codex subagents inherit filesystem access and can discover superpowers skills via native discovery. Without guidance, they activate the 1% rule and invoke full skill workflows instead of executing their assigned task. - Add SUBAGENT-STOP block to using-superpowers that tells subagents to skip the skill and execute their dispatch prompt instead - Document collab feature requirement for Codex subagent skills
2026-02-05Add Windows uninstall instructions and expand migration stepsDrew Ritter
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-05Drop installer script and AGENTS.md gatekeeperDrew Ritter
Testing showed native skill discovery works without the AGENTS.md gatekeeper — using-superpowers bootstraps itself via SKILL.md frontmatter. Install is now just clone + symlink, driven by INSTALL.md. No Node.js dependency. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-05Polish docs from 5-agent reviewDrew Ritter
- INSTALL.md: add prerequisites, Windows note, verify step, clone deletion in uninstall - README.codex.md: fix Windows section (junctions not symlinks), add description field guidance, consistent terminology - install-codex.mjs: accurate link type labels (symlink vs junction) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-05Rewrite Codex docs for native skill discoveryDrew Ritter
Replaces bootstrap CLI references with native discovery flow. Install is now clone + run installer. Documents tool mappings, personal skills path, and Windows junction fallback. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-05Fix ~/ path expansion on Windows — use $HOME insteadDrew Ritter
PowerShell doesn't expand ~ when passed as an argument to node, causing MODULE_NOT_FOUND errors. $HOME expands correctly in both bash and PowerShell. Fixes #285 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-05Fix Windows/PowerShell invocation of superpowers-codexDrew Ritter
Windows doesn't respect shebangs, so directly invoking the extensionless superpowers-codex script triggers an "Open with" dialog. Prefix all invocations with `node` (harmless on Unix, required on Windows) and add a .cmd wrapper for manual invocation on Windows. Fixes #285, #243 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-01-25codex: clarify subagent tool mapping in bootstrapDaniel E.
2026-01-23fix(opencode): standardize on plugins/ directory per official docsJesse Vincent
OpenCode officially documents ~/.config/opencode/plugins/ (plural) as the plugin directory. Our docs previously used plugin/ (singular), which also works but caused confusion. Changes: - Renamed .opencode/plugin/ to .opencode/plugins/ in repo structure - Updated INSTALL.md to use plugins/ everywhere - Updated README.opencode.md (all platforms: Linux, macOS, Windows CMD, PowerShell, Git Bash) to use plugins/ - Updated test scripts to match Tested: Both singular and plural forms work, but we now match official docs. Fixes #343 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-23fix(opencode): update docs for native skills, fix symlink instructionsJesse Vincent
Issues addressed: - #342: INSTALL.md still referenced removed find_skills/use_skill tools - #339: Symlink instructions could fail if target already exists Changes: - INSTALL.md: Added missing skills symlink step, updated to native skill tool - INSTALL.md: Removed Node.js prerequisite (no longer needed) - README.opencode.md: Added explicit rm before ln -s (ln -sf doesn't remove dirs) - Both files: Use ln -s instead of ln -sf for clarity Note: #343 (plugin vs plugins folder name) not addressed in this commit Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-23feat(opencode): use native skills and fix agent reset bug (#226) (#330)Jesse Vincent
* fix use_skill agent context (#290) * fix: respect OPENCODE_CONFIG_DIR for personal skills lookup (#297) * fix: respect OPENCODE_CONFIG_DIR for personal skills lookup The plugin was hardcoded to look for personal skills in ~/.config/opencode/skills, ignoring users who set OPENCODE_CONFIG_DIR to a custom path (e.g., for dotfiles management). Now uses OPENCODE_CONFIG_DIR if set, falling back to the default path. * fix: update help text to use dynamic paths Use configDir and personalSkillsDir variables in help text so paths are accurate when OPENCODE_CONFIG_DIR is set. * fix: normalize OPENCODE_CONFIG_DIR before use Handle edge cases where the env var might be: - Empty or whitespace-only - Using ~ for home directory (common in .env files) - A relative path Now trims, expands ~, and resolves to absolute path. * feat(opencode): use native skills and fix agent reset bug (#226) - Replace custom use_skill/find_skills tools with OpenCode's native skill tool - Use experimental.chat.system.transform hook instead of session.prompt (fixes #226 agent reset on first message) - Symlink skills directory into ~/.config/opencode/skills/superpowers/ - Update installation docs with comprehensive Windows support: - Command Prompt, PowerShell, and Git Bash instructions - Proper symlink vs junction handling - Reinstall safety with cleanup steps - Verification commands for each shell * Add OpenCode native skills changes to release notes Documents: - Breaking change: switch to native skill tool - Fix for agent reset bug (#226) - Fix for Windows installation (#232) --------- Co-authored-by: Vinicius da Motta <viniciusmotta8@gmail.com> Co-authored-by: oribi <oribarilan@gmail.com>
2025-12-17Add comprehensive testing documentationJesse Vincent
Documents: - How to run integration tests - subagent-driven-development test details - Token analysis tool usage - Troubleshooting common issues - Writing new integration tests - Session transcript format
2025-12-17Add skills improvement plan from user feedbackJesse Vincent
Analyzed feedback from two Claude instances using superpowers in real development scenarios. Identified 8 core problems and proposed improvements organized by impact and risk. Key problems: - Configuration change verification gap (verify success not intent) - Background process accumulation across subagents - Context bloat in subagent prompts - Missing self-reflection before handoff - Mock-interface drift - Code reviewer file access issues - Skills not being read/enforced - Fix workflow latency Proposed improvements organized in 3 phases: - Phase 1: High-impact, low-risk (do first) - Phase 2: Moderate changes (test carefully) - Phase 3: Optimization (validate first) See plan for detailed analysis and open questions.
2025-12-01Add Windows support for plugin hooks (#134)Jesse Vincent
* feat: Add Windows support for session-start hook - Create polyglot session-start.cmd that works in both CMD and bash - Update hooks.json to use the .cmd polyglot launcher - Replace sed/awk with pure bash for JSON escaping (Windows compatibility) The polyglot script uses a heredoc trick: - CMD sees the @echo off block and runs bash.exe with cygpath conversion - Bash sees a heredoc and skips to the Unix section 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: Add execute permission to session-start.cmd for Unix 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * docs: Add comprehensive polyglot hooks documentation - Add docs/windows/polyglot-hooks.md explaining the cross-platform technique - Add reusable run-hook.cmd wrapper for parameterized hook execution - Document how the polyglot works in CMD vs bash - Include troubleshooting section and related GitHub issues 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * test: Add polyglot hook test script for macOS/Linux Run ./test-polyglot.sh from repo root to verify: - Required files exist with execute permissions - Simple wrapper (session-start.cmd) produces valid JSON - Parameterized wrapper (run-hook.cmd) works - Heredoc correctly skips CMD block on Unix 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: Use direct pipe to jq in test to avoid variable escaping issues 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor: Use single reusable run-hook.cmd for all hooks - Remove session-start.cmd in favor of run-hook.cmd - Update hooks.json to use: run-hook.cmd session-start.sh - Simplify test script to only test run-hook.cmd This makes it easy to add more hooks - just create the .sh file and add a line to hooks.json pointing to run-hook.cmd with the script name. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: Simplify run-hook.cmd CMD block Pass path directly to bash instead of using cygpath in a subshell. The complex quoting was causing issues on Windows. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * chore: Remove test-polyglot.sh Testing complete - polyglot hooks work on Windows and macOS. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>
2025-11-23docs: reorganize platform installation docs with inline quick-start and ↵Jesse Vincent
detailed guides
2025-11-22docs: add implementation planJesse Vincent
2025-11-22Add OpenCode support design documentJesse Vincent
- Native OpenCode plugin approach using their JavaScript plugin system - Shared core module (lib/skills-core.js) for code reuse with Codex - Custom tools: use_skill and find_skills - Session startup hook for automatic bootstrap - Three-phase implementation plan
2025-10-18Remove test design documentJesse Vincent
2025-10-18Add design document for format-on-save featureJesse Vincent