diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 0e37c2c16..e1678e5c8 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,13 +1,25 @@ { - "name": "superpowers", - "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques", - "version": "4.0.3", + "name": "superpowers-ng", + "description": "Enhanced fork of superpowers with Manus-style persistent planning for long-running tasks and context resets", + "version": "0.1.0", "author": { - "name": "Jesse Vincent", - "email": "jesse@fsck.com" + "name": "OniReimu", + "url": "https://github.com/OniReimu" }, - "homepage": "https://github.com/obra/superpowers", - "repository": "https://github.com/obra/superpowers", + "homepage": "https://github.com/OniReimu/superpowers", + "repository": "https://github.com/OniReimu/superpowers", "license": "MIT", - "keywords": ["skills", "tdd", "debugging", "collaboration", "best-practices", "workflows"] + "keywords": ["skills", "tdd", "debugging", "collaboration", "best-practices", "workflows", "manus", "planning", "persistent-memory"], + "credits": [ + { + "name": "Jesse Vincent (obra)", + "role": "Original Superpowers author", + "url": "https://github.com/obra/superpowers" + }, + { + "name": "Ahmad Othman Ammar Adi (OthmanAdi)", + "role": "Planning-with-files author", + "url": "https://github.com/OthmanAdi/planning-with-files" + } + ] } diff --git a/.codex/superpowers-bootstrap.md b/.codex/superpowers-bootstrap.md index 18fe657f0..2a593b611 100644 --- a/.codex/superpowers-bootstrap.md +++ b/.codex/superpowers-bootstrap.md @@ -14,7 +14,7 @@ When skills reference tools you don't have, substitute your equivalent tools: - `Read`, `Write`, `Edit`, `Bash` → Use your native tools with similar functions **Skills naming:** -- Superpowers skills: `superpowers:skill-name` (from ~/.codex/superpowers/skills/) +- Superpowers skills: `superpowers-ng:skill-name` (from ~/.codex/superpowers/skills/) - Personal skills: `skill-name` (from ~/.codex/skills/) - Personal skills override superpowers skills when names match diff --git a/.codex/superpowers-codex b/.codex/superpowers-codex index 1d9a0efb6..7ab0f471f 100755 --- a/.codex/superpowers-codex +++ b/.codex/superpowers-codex @@ -23,7 +23,7 @@ function printSkill(skillPath, sourceType) { if (sourceType === 'personal') { console.log(relPath.replace(/\\/g, '/')); // Personal skills are not namespaced } else { - console.log(`superpowers:${relPath.replace(/\\/g, '/')}`); // Superpowers skills get superpowers namespace + console.log(`superpowers-ng:${relPath.replace(/\\/g, '/')}`); // Superpowers skills get superpowers-ng namespace } // Extract and print metadata @@ -62,7 +62,7 @@ function runFindSkills() { console.log(' superpowers-codex use-skill # Load a specific skill'); console.log(''); console.log('Skill naming:'); - console.log(' Superpowers skills: superpowers:skill-name (from ~/.codex/superpowers/skills/)'); + console.log(' Superpowers skills: superpowers-ng:skill-name (from ~/.codex/superpowers/skills/)'); console.log(' Personal skills: skill-name (from ~/.codex/skills/)'); console.log(' Personal skills override superpowers skills when names match.'); console.log(''); @@ -110,9 +110,9 @@ function runBootstrap() { console.log(''); // Load the using-superpowers skill automatically - console.log('## Auto-loading superpowers:using-superpowers skill:'); + console.log('## Auto-loading superpowers-ng:using-superpowers skill:'); console.log(''); - runUseSkill('superpowers:using-superpowers'); + runUseSkill('superpowers-ng:using-superpowers'); console.log(''); console.log('---'); @@ -127,7 +127,7 @@ function runUseSkill(skillName) { if (!skillName) { console.log('Usage: superpowers-codex use-skill '); console.log('Examples:'); - console.log(' superpowers-codex use-skill superpowers:brainstorming # Load superpowers skill'); + console.log(' superpowers-codex use-skill superpowers-ng:brainstorming # Load superpowers skill'); console.log(' superpowers-codex use-skill brainstorming # Load personal skill (or superpowers if not found)'); console.log(' superpowers-codex use-skill my-custom-skill # Load personal skill'); return; @@ -137,9 +137,9 @@ function runUseSkill(skillName) { let actualSkillPath; let forceSuperpowers = false; - if (skillName.startsWith('superpowers:')) { - // Remove the superpowers: namespace prefix - actualSkillPath = skillName.substring('superpowers:'.length); + if (skillName.startsWith('superpowers-ng:')) { + // Remove the superpowers-ng: namespace prefix + actualSkillPath = skillName.substring('superpowers-ng:'.length); forceSuperpowers = true; } else { actualSkillPath = skillName; @@ -191,7 +191,7 @@ function runUseSkill(skillName) { const superpowersPath = path.join(superpowersSkillsDir, actualSkillPath); skillFile = findSkillFile(superpowersPath); if (skillFile) { - console.log(`# Loading superpowers skill: superpowers:${actualSkillPath}`); + console.log(`# Loading superpowers skill: superpowers-ng:${actualSkillPath}`); console.log(`# Source: ${skillFile}`); console.log(''); } @@ -220,8 +220,8 @@ function runUseSkill(skillName) { } // Display skill header with clean info - const displayName = forceSuperpowers ? `superpowers:${actualSkillPath}` : - (skillFile.includes(personalSkillsDir) ? actualSkillPath : `superpowers:${actualSkillPath}`); + const displayName = forceSuperpowers ? `superpowers-ng:${actualSkillPath}` : + (skillFile.includes(personalSkillsDir) ? actualSkillPath : `superpowers-ng:${actualSkillPath}`); const skillDirectory = path.dirname(skillFile); @@ -261,7 +261,7 @@ switch (command) { console.log(''); console.log('Examples:'); console.log(' superpowers-codex bootstrap'); - console.log(' superpowers-codex use-skill superpowers:brainstorming'); + console.log(' superpowers-codex use-skill superpowers-ng:brainstorming'); console.log(' superpowers-codex use-skill my-custom-skill'); break; } diff --git a/.opencode/plugin/superpowers.js b/.opencode/plugin/superpowers.js index c9a6e29ea..171e5a687 100644 --- a/.opencode/plugin/superpowers.js +++ b/.opencode/plugin/superpowers.js @@ -32,7 +32,7 @@ export const SuperpowersPlugin = async ({ client, directory }) => { const toolMapping = compact ? `**Tool Mapping:** TodoWrite->update_plan, Task->@mention, Skill->use_skill -**Skills naming (priority order):** project: > personal > superpowers:` +**Skills naming (priority order):** project: > personal > superpowers-ng:` : `**Tool Mapping for OpenCode:** When skills reference tools you don't have, substitute OpenCode equivalents: - \`TodoWrite\` → \`update_plan\` @@ -43,7 +43,7 @@ When skills reference tools you don't have, substitute OpenCode equivalents: **Skills naming (priority order):** - Project skills: \`project:skill-name\` (in .opencode/skills/) - Personal skills: \`skill-name\` (in ~/.config/opencode/skills/) -- Superpowers skills: \`superpowers:skill-name\` +- Superpowers skills: \`superpowers-ng:skill-name\` - Project skills override personal, which override superpowers when names match`; return ` @@ -81,7 +81,7 @@ ${toolMapping} use_skill: tool({ description: 'Load and read a specific skill to guide your work. Skills contain proven workflows, mandatory processes, and expert techniques.', args: { - skill_name: tool.schema.string().describe('Name of the skill to load (e.g., "superpowers:brainstorming", "my-custom-skill", or "project:my-skill")') + skill_name: tool.schema.string().describe('Name of the skill to load (e.g., "superpowers-ng:brainstorming", "my-custom-skill", or "project:my-skill")') }, execute: async (args, context) => { const { skill_name } = args; @@ -94,7 +94,7 @@ ${toolMapping} let resolved = null; // Try project skills first (if project: prefix or no prefix) - if (forceProject || !skill_name.startsWith('superpowers:')) { + if (forceProject || !skill_name.startsWith('superpowers-ng:')) { const projectPath = path.join(projectSkillsDir, actualSkillName); const projectSkillFile = path.join(projectPath, 'SKILL.md'); if (fs.existsSync(projectSkillFile)) { @@ -172,7 +172,7 @@ ${toolMapping} namespace = ''; break; default: - namespace = 'superpowers:'; + namespace = 'superpowers-ng:'; } const skillName = skill.name || path.basename(skill.path); diff --git a/README.md b/README.md index 0e67aefcf..2ca372a42 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,76 @@ -# Superpowers +# Superpowers-NG (Next Generation) -Superpowers is a complete software development workflow for your coding agents, built on top of a set of composable "skills" and some initial instructions that make sure your agent uses them. +**Superpowers-NG** is an enhanced fork of [obra/superpowers](https://github.com/obra/superpowers) with integrated **Manus-style persistent planning** for complex, long-running tasks. -## How it works +## What's New in NG -It starts from the moment you fire up your coding agent. As soon as it sees that you're building something, it *doesn't* just jump into trying to write code. Instead, it steps back and asks you what you're really trying to do. +### Manus Planning: Persistent Memory Across Context Resets -Once it's teased a spec out of the conversation, it shows it to you in chunks short enough to actually read and digest. +The flagship feature is `manus-planning`, a file-based planning system that survives context resets and enables multi-session work. -After you've signed off on the design, your agent puts together an implementation plan that's clear enough for an enthusiastic junior engineer with poor taste, no judgement, no project context, and an aversion to testing to follow. It emphasizes true red/green TDD, YAGNI (You Aren't Gonna Need It), and DRY. +**Native vs Manus Planning:** -Next up, once you say "go", it launches a *subagent-driven-development* process, having agents work through each engineering task, inspecting and reviewing their work, and continuing forward. It's not uncommon for Claude to be able to work autonomously for a couple hours at a time without deviating from the plan you put together. +| Aspect | Native (Original) | Manus (New) | +|--------|-------------------|-------------| +| **Skills** | writing-plans + executing-plans | manus-planning | +| **Memory** | In-memory (TodoWrite) | Persistent files (`docs/manus/`) | +| **Best for** | Short tasks (<30 min), interactive development | Long autonomous runs, multi-session projects, >50 tool calls | +| **Progress tracking** | Lost on context reset | Survives context resets | +| **Research storage** | Embedded in conversation | Persistent `findings.md` | -There's a bunch more to it, but that's the core of the system. And because the skills trigger automatically, you don't need to do anything special. Your coding agent just has Superpowers. +**The 3 Files:** +- `task_plan.md` - Goal, 5 phases, decisions, errors +- `findings.md` - Requirements, research, resources (CRITICAL for visual/browser content) +- `progress.md` - Session log, test results, 5-question reboot check +**When to use Manus:** +- Tasks requiring >50 tool calls +- Multi-session projects spanning days +- Complex research with web searches/images +- When context might reset mid-task -## Sponsorship +**How it works:** +1. Create marker file `docs/manus/.active` to enable PreToolUse hooks +2. Hooks automatically show plan preview before Write/Edit/Bash operations +3. 2-Action Rule: Update `findings.md` after every 2 search/view operations +4. On completion: Remove marker, invoke `finishing-a-development-branch` -If Superpowers has helped you do stuff that makes money and you are so inclined, I'd greatly appreciate it if you'd consider [sponsoring my opensource work](https://github.com/sponsors/obra). +**Brainstorming integration:** +After design completion, brainstorming now offers both planning options. For Manus, design content is automatically copied into `findings.md`. -Thanks! +## How It Works (Original Superpowers) -- Jesse +Superpowers is a complete software development workflow for your coding agents, built on composable "skills" that trigger automatically. +When you start building something, your agent: +1. **Asks questions** to understand what you're really trying to do +2. **Shows the design** in digestible chunks for your approval +3. **Creates an implementation plan** clear enough for a junior engineer to follow +4. **Executes autonomously** through subagent-driven development -## Installation +The core philosophy: **Test-Driven Development**, **YAGNI**, **DRY**, and **systematic over ad-hoc**. -**Note:** Installation differs by platform. Claude Code has a built-in plugin system. Codex and OpenCode require manual setup. +## Installation -### Claude Code (via Plugin Marketplace) +**Note:** Installation instructions will be updated once the marketplace is configured. -In Claude Code, register the marketplace first: +### Claude Code (Planned) ```bash -/plugin marketplace add obra/superpowers-marketplace +# Will be available via marketplace: +/plugin marketplace add OniReimu/superpowers-ng-marketplace +/plugin install superpowers-ng@superpowers-ng-marketplace ``` -Then install the plugin from this marketplace: +### Manual Installation (Current) ```bash -/plugin install superpowers@superpowers-marketplace +# Clone the repository +git clone https://github.com/OniReimu/superpowers-ng.git +cd superpowers-ng + +# Install as a local plugin +# (Instructions TBD based on Claude Code local plugin support) ``` ### Verify Installation @@ -50,76 +81,71 @@ Check that commands appear: /help ``` +You should see: ``` -# Should see: -# /superpowers:brainstorm - Interactive design refinement -# /superpowers:write-plan - Create implementation plan -# /superpowers:execute-plan - Execute plan in batches +/superpowers-ng:brainstorm - Interactive design refinement +/superpowers-ng:write-plan - Create implementation plan +/superpowers-ng:execute-plan - Execute plan in batches +/superpowers-ng:manus-plan - Start Manus-style persistent planning ``` -### Codex - -Tell Codex: - -``` -Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md -``` - -**Detailed docs:** [docs/README.codex.md](docs/README.codex.md) - -### OpenCode +## The Enhanced Workflow -Tell OpenCode: +1. **brainstorming** - Refines rough ideas, presents design in sections. Saves design document. -``` -Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md -``` - -**Detailed docs:** [docs/README.opencode.md](docs/README.opencode.md) +2. **using-git-worktrees** - Creates isolated workspace on new branch. -## The Basic Workflow +3. **Choose your planning system:** + - **Native:** `writing-plans` → `executing-plans` for short tasks + - **Manus:** `manus-planning` for complex/long-running tasks -1. **brainstorming** - Activates before writing code. Refines rough ideas through questions, explores alternatives, presents design in sections for validation. Saves design document. +4. **subagent-driven-development** or **executing-plans** - Implements with two-stage review or batch execution. -2. **using-git-worktrees** - Activates after design approval. Creates isolated workspace on new branch, runs project setup, verifies clean test baseline. +5. **test-driven-development** - Enforces RED-GREEN-REFACTOR cycle. -3. **writing-plans** - Activates with approved design. Breaks work into bite-sized tasks (2-5 minutes each). Every task has exact file paths, complete code, verification steps. +6. **requesting-code-review** - Reviews against plan between tasks. -4. **subagent-driven-development** or **executing-plans** - Activates with plan. Dispatches fresh subagent per task with two-stage review (spec compliance, then code quality), or executes in batches with human checkpoints. +7. **finishing-a-development-branch** - Verifies tests, presents merge options. -5. **test-driven-development** - Activates during implementation. Enforces RED-GREEN-REFACTOR: write failing test, watch it fail, write minimal code, watch it pass, commit. Deletes code written before tests. - -6. **requesting-code-review** - Activates between tasks. Reviews against plan, reports issues by severity. Critical issues block progress. +## What's Inside -7. **finishing-a-development-branch** - Activates when tasks complete. Verifies tests, presents options (merge/PR/keep/discard), cleans up worktree. +### Planning Skills -**The agent checks for relevant skills before any task.** Mandatory workflows, not suggestions. +**Native Planning (Original)** +- **writing-plans** - Bite-sized implementation plans +- **executing-plans** - Batch execution with checkpoints -## What's Inside +**Manus Planning (New)** +- **manus-planning** - 5-phase workflow with persistent files + - Phase 1: Requirements & Discovery + - Phase 2: Planning & Structure + - Phase 3: Implementation + - Phase 4: Testing & Verification + - Phase 5: Delivery -### Skills Library +### Testing -**Testing** - **test-driven-development** - RED-GREEN-REFACTOR cycle (includes testing anti-patterns reference) -**Debugging** +### Debugging + - **systematic-debugging** - 4-phase root cause process (includes root-cause-tracing, defense-in-depth, condition-based-waiting techniques) - **verification-before-completion** - Ensure it's actually fixed -**Collaboration** -- **brainstorming** - Socratic design refinement -- **writing-plans** - Detailed implementation plans -- **executing-plans** - Batch execution with checkpoints +### Collaboration + +- **brainstorming** - Socratic design refinement (enhanced with planning choice) - **dispatching-parallel-agents** - Concurrent subagent workflows - **requesting-code-review** - Pre-review checklist - **receiving-code-review** - Responding to feedback - **using-git-worktrees** - Parallel development branches - **finishing-a-development-branch** - Merge/PR decision workflow -- **subagent-driven-development** - Fast iteration with two-stage review (spec compliance, then code quality) +- **subagent-driven-development** - Fast iteration with two-stage review + +### Meta -**Meta** -- **writing-skills** - Create new skills following best practices (includes testing methodology) -- **using-superpowers** - Introduction to the skills system +- **writing-skills** - Create new skills following best practices +- **using-superpowers** - Introduction to the skills system (updated with planning guidance) ## Philosophy @@ -127,8 +153,29 @@ Fetch and follow instructions from https://raw.githubusercontent.com/obra/superp - **Systematic over ad-hoc** - Process over guessing - **Complexity reduction** - Simplicity as primary goal - **Evidence over claims** - Verify before declaring success +- **Persistent memory** (New) - Filesystem as external memory for long tasks + +## Integration with Ralph + +Superpowers-NG works seamlessly with [Ralph](https://github.com/frankbria/ralph-claude-code), the autonomous loop framework for Claude Code. + +**Ralph provides**: Loop orchestration, session management, exit detection, rate limiting -Read more: [Superpowers for Claude Code](https://blog.fsck.com/2025/10/09/superpowers/) +**Superpowers-NG provides**: Development methodologies, TDD discipline, debugging workflows, persistent planning + +**Key features for Ralph users**: +- **brainstorming** now auto-detects existing designs and skips in subsequent loops +- **manus-planning** designed for multi-loop persistence with auto-resume +- **verification-before-completion** ensures evidence-based exit signals +- Skills are autonomous-mode aware (no waiting for user input) + +**Get started**: +```bash +# Copy enhanced PROMPT.md template to your Ralph project +cp docs/ralph-integration/PROMPT.template.md /path/to/ralph-project/PROMPT.md +``` + +See `docs/ralph-integration/README.md` for complete integration guide. ## Contributing @@ -141,13 +188,24 @@ Skills live directly in this repository. To contribute: See `skills/writing-skills/SKILL.md` for the complete guide. -## Updating +## Credits -Skills update automatically when you update the plugin: +### Original Authors -```bash -/plugin update superpowers -``` +- **Jesse Vincent (obra)** - [obra/superpowers](https://github.com/obra/superpowers) + - Original Superpowers framework and skills system + +- **Ahmad Othman Ammar Adi (OthmanAdi)** - [planning-with-files](https://github.com/OthmanAdi/planning-with-files) + - Manus-style 3-file planning pattern + +### Superpowers-NG + +- **OniReimu** - Integration and enhancement + +### Inspiration + +- Manus AI (acquired by Meta) - Context engineering principles +- [Superpowers blog post](https://blog.fsck.com/2025/10/09/superpowers/) ## License @@ -155,5 +213,6 @@ MIT License - see LICENSE file for details ## Support -- **Issues**: https://github.com/obra/superpowers/issues -- **Marketplace**: https://github.com/obra/superpowers-marketplace +- **Issues**: https://github.com/OniReimu/superpowers/issues +- **Original Superpowers**: https://github.com/obra/superpowers +- **Planning-with-files**: https://github.com/OthmanAdi/planning-with-files diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md index 5ab95451d..e9732e46d 100644 --- a/RELEASE-NOTES.md +++ b/RELEASE-NOTES.md @@ -1,638 +1,211 @@ -# Superpowers Release Notes +# Superpowers-NG Release Notes -## v4.0.3 (2025-12-26) +## v0.1.0 (2026-01-13) -### Improvements - -**Strengthened using-superpowers skill for explicit skill requests** - -Addressed a failure mode where Claude would skip invoking a skill even when the user explicitly requested it by name (e.g., "subagent-driven-development, please"). Claude would think "I know what that means" and start working directly instead of loading the skill. - -Changes: -- Updated "The Rule" to say "Invoke relevant or requested skills" instead of "Check for skills" - emphasizing active invocation over passive checking -- Added "BEFORE any response or action" - the original wording only mentioned "response" but Claude would sometimes take action without responding first -- Added reassurance that invoking a wrong skill is okay - reduces hesitation -- Added new red flag: "I know what that means" → Knowing the concept ≠ using the skill - -**Added explicit skill request tests** - -New test suite in `tests/explicit-skill-requests/` that verifies Claude correctly invokes skills when users request them by name. Includes single-turn and multi-turn test scenarios. - -## v4.0.2 (2025-12-23) - -### Fixes - -**Slash commands now user-only** - -Added `disable-model-invocation: true` to all three slash commands (`/brainstorm`, `/execute-plan`, `/write-plan`). Claude can no longer invoke these commands via the Skill tool—they're restricted to manual user invocation only. - -The underlying skills (`superpowers:brainstorming`, `superpowers:executing-plans`, `superpowers:writing-plans`) remain available for Claude to invoke autonomously. This change prevents confusion when Claude would invoke a command that just redirects to a skill anyway. - -## v4.0.1 (2025-12-23) - -### Fixes - -**Clarified how to access skills in Claude Code** - -Fixed a confusing pattern where Claude would invoke a skill via the Skill tool, then try to Read the skill file separately. The `using-superpowers` skill now explicitly states that the Skill tool loads skill content directly—no need to read files. - -- Added "How to Access Skills" section to `using-superpowers` -- Changed "read the skill" → "invoke the skill" in instructions -- Updated slash commands to use fully qualified skill names (e.g., `superpowers:brainstorming`) - -**Added GitHub thread reply guidance to receiving-code-review** (h/t @ralphbean) - -Added a note about replying to inline review comments in the original thread rather than as top-level PR comments. - -**Added automation-over-documentation guidance to writing-skills** (h/t @EthanJStark) - -Added guidance that mechanical constraints should be automated, not documented—save skills for judgment calls. - -## v4.0.0 (2025-12-17) - -### New Features - -**Two-stage code review in subagent-driven-development** - -Subagent workflows now use two separate review stages after each task: - -1. **Spec compliance review** - Skeptical reviewer verifies implementation matches spec exactly. Catches missing requirements AND over-building. Won't trust implementer's report—reads actual code. - -2. **Code quality review** - Only runs after spec compliance passes. Reviews for clean code, test coverage, maintainability. - -This catches the common failure mode where code is well-written but doesn't match what was requested. Reviews are loops, not one-shot: if reviewer finds issues, implementer fixes them, then reviewer checks again. - -Other subagent workflow improvements: -- Controller provides full task text to workers (not file references) -- Workers can ask clarifying questions before AND during work -- Self-review checklist before reporting completion -- Plan read once at start, extracted to TodoWrite - -New prompt templates in `skills/subagent-driven-development/`: -- `implementer-prompt.md` - Includes self-review checklist, encourages questions -- `spec-reviewer-prompt.md` - Skeptical verification against requirements -- `code-quality-reviewer-prompt.md` - Standard code review - -**Debugging techniques consolidated with tools** - -`systematic-debugging` now bundles supporting techniques and tools: -- `root-cause-tracing.md` - Trace bugs backward through call stack -- `defense-in-depth.md` - Add validation at multiple layers -- `condition-based-waiting.md` - Replace arbitrary timeouts with condition polling -- `find-polluter.sh` - Bisection script to find which test creates pollution -- `condition-based-waiting-example.ts` - Complete implementation from real debugging session - -**Testing anti-patterns reference** - -`test-driven-development` now includes `testing-anti-patterns.md` covering: -- Testing mock behavior instead of real behavior -- Adding test-only methods to production classes -- Mocking without understanding dependencies -- Incomplete mocks that hide structural assumptions - -**Skill test infrastructure** - -Three new test frameworks for validating skill behavior: - -`tests/skill-triggering/` - Validates skills trigger from naive prompts without explicit naming. Tests 6 skills to ensure descriptions alone are sufficient. - -`tests/claude-code/` - Integration tests using `claude -p` for headless testing. Verifies skill usage via session transcript (JSONL) analysis. Includes `analyze-token-usage.py` for cost tracking. - -`tests/subagent-driven-dev/` - End-to-end workflow validation with two complete test projects: -- `go-fractals/` - CLI tool with Sierpinski/Mandelbrot (10 tasks) -- `svelte-todo/` - CRUD app with localStorage and Playwright (12 tasks) - -### Major Changes - -**DOT flowcharts as executable specifications** - -Rewrote key skills using DOT/GraphViz flowcharts as the authoritative process definition. Prose becomes supporting content. - -**The Description Trap** (documented in `writing-skills`): Discovered that skill descriptions override flowchart content when descriptions contain workflow summaries. Claude follows the short description instead of reading the detailed flowchart. Fix: descriptions must be trigger-only ("Use when X") with no process details. - -**Skill priority in using-superpowers** - -When multiple skills apply, process skills (brainstorming, debugging) now explicitly come before implementation skills. "Build X" triggers brainstorming first, then domain skills. - -**brainstorming trigger strengthened** - -Description changed to imperative: "You MUST use this before any creative work—creating features, building components, adding functionality, or modifying behavior." - -### Breaking Changes - -**Skill consolidation** - Six standalone skills merged: -- `root-cause-tracing`, `defense-in-depth`, `condition-based-waiting` → bundled in `systematic-debugging/` -- `testing-skills-with-subagents` → bundled in `writing-skills/` -- `testing-anti-patterns` → bundled in `test-driven-development/` -- `sharing-skills` removed (obsolete) - -### Other Improvements - -- **render-graphs.js** - Tool to extract DOT diagrams from skills and render to SVG -- **Rationalizations table** in using-superpowers - Scannable format including new entries: "I need more context first", "Let me explore first", "This feels productive" -- **docs/testing.md** - Guide to testing skills with Claude Code integration tests - ---- - -## v3.6.2 (2025-12-03) - -### Fixed - -- **Linux Compatibility**: Fixed polyglot hook wrapper (`run-hook.cmd`) to use POSIX-compliant syntax - - Replaced bash-specific `${BASH_SOURCE[0]:-$0}` with standard `$0` on line 16 - - Resolves "Bad substitution" error on Ubuntu/Debian systems where `/bin/sh` is dash - - Fixes #141 - ---- - -## v3.5.1 (2025-11-24) - -### Changed - -- **OpenCode Bootstrap Refactor**: Switched from `chat.message` hook to `session.created` event for bootstrap injection - - Bootstrap now injects at session creation via `session.prompt()` with `noReply: true` - - Explicitly tells the model that using-superpowers is already loaded to prevent redundant skill loading - - Consolidated bootstrap content generation into shared `getBootstrapContent()` helper - - Cleaner single-implementation approach (removed fallback pattern) - ---- - -## v3.5.0 (2025-11-23) - -### Added - -- **OpenCode Support**: Native JavaScript plugin for OpenCode.ai - - Custom tools: `use_skill` and `find_skills` - - Message insertion pattern for skill persistence across context compaction - - Automatic context injection via chat.message hook - - Auto re-injection on session.compacted events - - Three-tier skill priority: project > personal > superpowers - - Project-local skills support (`.opencode/skills/`) - - Shared core module (`lib/skills-core.js`) for code reuse with Codex - - Automated test suite with proper isolation (`tests/opencode/`) - - Platform-specific documentation (`docs/README.opencode.md`, `docs/README.codex.md`) - -### Changed - -- **Refactored Codex Implementation**: Now uses shared `lib/skills-core.js` ES module - - Eliminates code duplication between Codex and OpenCode - - Single source of truth for skill discovery and parsing - - Codex successfully loads ES modules via Node.js interop - -- **Improved Documentation**: Rewrote README to explain problem/solution clearly - - Removed duplicate sections and conflicting information - - Added complete workflow description (brainstorm → plan → execute → finish) - - Simplified platform installation instructions - - Emphasized skill-checking protocol over automatic activation claims - ---- - -## v3.4.1 (2025-10-31) - -### Improvements - -- Optimized superpowers bootstrap to eliminate redundant skill execution. The `using-superpowers` skill content is now provided directly in session context, with clear guidance to use the Skill tool only for other skills. This reduces overhead and prevents the confusing loop where agents would execute `using-superpowers` manually despite already having the content from session start. - -## v3.4.0 (2025-10-30) - -### Improvements - -- Simplified `brainstorming` skill to return to original conversational vision. Removed heavyweight 6-phase process with formal checklists in favor of natural dialogue: ask questions one at a time, then present design in 200-300 word sections with validation. Keeps documentation and implementation handoff features. - -## v3.3.1 (2025-10-28) - -### Improvements - -- Updated `brainstorming` skill to require autonomous recon before questioning, encourage recommendation-driven decisions, and prevent agents from delegating prioritization back to humans. -- Applied writing clarity improvements to `brainstorming` skill following Strunk's "Elements of Style" principles (omitted needless words, converted negative to positive form, improved parallel construction). - -### Bug Fixes - -- Clarified `writing-skills` guidance so it points to the correct agent-specific personal skill directories (`~/.claude/skills` for Claude Code, `~/.codex/skills` for Codex). - -## v3.3.0 (2025-10-28) +**Initial release** of Superpowers-NG, an enhanced fork of [obra/superpowers](https://github.com/obra/superpowers) with Manus-style persistent planning and Ralph integration. ### New Features -**Experimental Codex Support** -- Added unified `superpowers-codex` script with bootstrap/use-skill/find-skills commands -- Cross-platform Node.js implementation (works on Windows, macOS, Linux) -- Namespaced skills: `superpowers:skill-name` for superpowers skills, `skill-name` for personal -- Personal skills override superpowers skills when names match -- Clean skill display: shows name/description without raw frontmatter -- Helpful context: shows supporting files directory for each skill -- Tool mapping for Codex: TodoWrite→update_plan, subagents→manual fallback, etc. -- Bootstrap integration with minimal AGENTS.md for automatic startup -- Complete installation guide and bootstrap instructions specific to Codex - -**Key differences from Claude Code integration:** -- Single unified script instead of separate tools -- Tool substitution system for Codex-specific equivalents -- Simplified subagent handling (manual work instead of delegation) -- Updated terminology: "Superpowers skills" instead of "Core skills" +#### Manus Planning System + +**File-based planning that survives context resets** + +Added `manus-planning` skill inspired by [planning-with-files](https://github.com/OthmanAdi/planning-with-files) by OthmanAdi. This enables long-running tasks that span multiple sessions or exceed 50 tool calls. -### Files Added -- `.codex/INSTALL.md` - Installation guide for Codex users -- `.codex/superpowers-bootstrap.md` - Bootstrap instructions with Codex adaptations -- `.codex/superpowers-codex` - Unified Node.js executable with all functionality +**The 3 Files** (`docs/manus/`): +- `task_plan.md` - Goal, 5 phases (Requirements → Planning → Implementation → Testing → Delivery), decisions table, errors log +- `findings.md` - Requirements, research, technical decisions, resources (critical for visual/browser content that doesn't persist in context) +- `progress.md` - Session log with timestamps, test results table, error log, 5-question reboot check for context resumption + +**Key Features:** +- **Persistent memory**: Files survive context resets, enabling work across multiple sessions +- **Automatic reminders**: PreToolUse hooks show plan preview before Write/Edit/Bash operations (when `.active` marker exists) +- **2-Action Rule**: After every 2 view/browser/search operations, update `findings.md` to preserve discoveries +- **Archive system**: Completed tasks auto-archive to `docs/manus/archive/YYYY-MM-DD-/`, new tasks get prompted (continue or start new) +- **5 Phases**: Structured workflow from Requirements through Delivery with status tracking -**Note:** Codex support is experimental. The integration provides core superpowers functionality but may require refinement based on user feedback. +**Files:** +- `skills/manus-planning/SKILL.md` - Main skill definition +- `skills/manus-planning/templates/task_plan.md` - Phase tracking template +- `skills/manus-planning/templates/findings.md` - Research storage template +- `skills/manus-planning/templates/progress.md` - Session log template +- `commands/manus-plan.md` - Slash command `/manus-plan` +- `hooks/manus-pretool.sh` - Conditional PreToolUse hook (only active when marker file exists) -## v3.2.3 (2025-10-23) +#### Brainstorming Enhancement -### Improvements +**Planning choice after design** -**Updated using-superpowers skill to use Skill tool instead of Read tool** -- Changed skill invocation instructions from Read tool to Skill tool -- Updated description: "using Read tool" → "using Skill tool" -- Updated step 3: "Use the Read tool" → "Use the Skill tool to read and run" -- Updated rationalization list: "Read the current version" → "Run the current version" +Updated `brainstorming` skill to present both planning options after design completion: +1. **Native planning** (writing-plans → executing-plans): Short tasks, interactive development +2. **Manus planning** (manus-planning): Long runs, multi-session projects -The Skill tool is the proper mechanism for invoking skills in Claude Code. This update corrects the bootstrap instructions to guide agents toward the correct tool. +When Manus is chosen, design document content is automatically copied into `findings.md` for persistent reference. -### Files Changed -- Updated: `skills/using-superpowers/SKILL.md` - Changed tool references from Read to Skill +**File:** +- `skills/brainstorming/SKILL.md` - Updated "After the Design" section -## v3.2.2 (2025-10-21) +#### Planning Guidance -### Improvements +**Added planning approach comparison** -**Strengthened using-superpowers skill against agent rationalization** -- Added EXTREMELY-IMPORTANT block with absolute language about mandatory skill checking - - "If even 1% chance a skill applies, you MUST read it" - - "You do not have a choice. You cannot rationalize your way out." -- Added MANDATORY FIRST RESPONSE PROTOCOL checklist - - 5-step process agents must complete before any response - - Explicit "responding without this = failure" consequence -- Added Common Rationalizations section with 8 specific evasion patterns - - "This is just a simple question" → WRONG - - "I can check files quickly" → WRONG - - "Let me gather information first" → WRONG - - Plus 5 more common patterns observed in agent behavior +Updated `using-superpowers` skill with "Planning Approaches" section explaining when to use Native vs Manus planning: -These changes address observed agent behavior where they rationalize around skill usage despite clear instructions. The forceful language and pre-emptive counter-arguments aim to make non-compliance harder. +| Approach | Skills | Best For | +|----------|--------|----------| +| **Native** | writing-plans + executing-plans | Short tasks (<30 min), interactive development with human checkpoints | +| **Manus** | manus-planning | Long autonomous runs, multi-session projects, tasks requiring >50 tool calls | -### Files Changed -- Updated: `skills/using-superpowers/SKILL.md` - Added three layers of enforcement to prevent skill-skipping rationalization +**File:** +- `skills/using-superpowers/SKILL.md` - Added planning guidance section -## v3.2.1 (2025-10-20) +#### Ralph Integration -### New Features +**Seamless integration with Ralph autonomous loop framework** -**Code reviewer agent now included in plugin** -- Added `superpowers:code-reviewer` agent to plugin's `agents/` directory -- Agent provides systematic code review against plans and coding standards -- Previously required users to have personal agent configuration -- All skill references updated to use namespaced `superpowers:code-reviewer` -- Fixes #55 +Added comprehensive support for using Superpowers-NG skills within [Ralph](https://github.com/frankbria/ralph-claude-code), the autonomous loop framework for Claude Code. -### Files Changed -- New: `agents/code-reviewer.md` - Agent definition with review checklist and output format -- Updated: `skills/requesting-code-review/SKILL.md` - References to `superpowers:code-reviewer` -- Updated: `skills/subagent-driven-development/SKILL.md` - References to `superpowers:code-reviewer` +**Key improvements**: +- **brainstorming** now checks for existing design files before starting + - Auto-detects `docs/plans/*-design.md`, `design.md`, or `docs/manus/findings.md` + - In autonomous mode (Ralph loops): automatically uses existing design and skips to implementation + - In interactive mode: offers choices (use existing, refine, start fresh) + - Prevents redundant brainstorming in subsequent Ralph loops +- **manus-planning** already compatible with Ralph's multi-session nature + - Persistent files survive loop resets + - Auto-resumes via `.active` marker detection + - Perfect for Ralph's `--continue` session model +- Phased brainstorming structure (Phase 0 → Phase 3) for clearer flow -## v3.2.0 (2025-10-18) +**Documentation**: +- `docs/ralph-integration/README.md` - Complete integration guide + - Architecture overview (Ralph vs Superpowers layers) + - Skill lifecycle in Ralph loops (once per task vs every loop) + - PROMPT.md structure and patterns + - File management strategy + - Common issues and solutions +- `docs/ralph-integration/PROMPT.template.md` - Ready-to-use PROMPT.md template + - **Ralph's official status block format** with all required fields: + - STATUS, TASKS_COMPLETED_THIS_LOOP, FILES_MODIFIED, TESTS_STATUS, WORK_TYPE, EXIT_SIGNAL, RECOMMENDATION + - **Concrete examples**: 5 detailed scenarios showing exact status emissions + - **Circuit breaker patterns**: Test-only loops, recurring errors, zero progress detection + - **Anti-patterns table**: 8 explicitly forbidden patterns (refactor working code, add unplanned features, etc.) + - **Exit criteria checklist**: 7-item checklist for when to set EXIT_SIGNAL: true + - Conditional skill invocation (check for existing artifacts) + - Autonomous mode behavior guidelines + - Phase-based workflow with Superpowers skills + - Customizable project context sections -### New Features +**Updated Files**: +- `skills/brainstorming/SKILL.md` - Added Phase 0 (Check for Existing Design) with autonomous mode logic +- `README.md` - Added "Integration with Ralph" section -**Design documentation in brainstorming workflow** -- Added Phase 4: Design Documentation to brainstorming skill -- Design documents now written to `docs/plans/YYYY-MM-DD--design.md` before implementation -- Restores functionality from original brainstorming command that was lost during skill conversion -- Documents written before worktree setup and implementation planning -- Tested with subagent to verify compliance under time pressure +**Benefits for Ralph users**: +- No duplicate work across loops (design once, implement across many loops) +- Persistent memory via manus-planning files +- TDD and debugging discipline maintained across sessions +- Evidence-based completion signals (verification-before-completion) +- Ready-to-use templates for quick setup + +### Technical Implementation + +#### Hooks System Enhancement + +**Conditional PreToolUse hook** + +Added PreToolUse hook to `hooks.json` that fires before Write/Edit/Bash operations: +- Only outputs when `docs/manus/.active` marker file exists +- Displays first 30 lines of `task_plan.md` as context reminder +- Outputs empty JSON `{}` when inactive (no interference with native planning) +- Cross-platform compatible (uses same `run-hook.cmd` wrapper as SessionStart) + +**Files:** +- `hooks/hooks.json` - Added PreToolUse matcher for Write|Edit|Bash +- `hooks/manus-pretool.sh` - Bash script with JSON escaping, checks marker file ### Breaking Changes -**Skill reference namespace standardization** -- All internal skill references now use `superpowers:` namespace prefix -- Updated format: `superpowers:test-driven-development` (previously just `test-driven-development`) -- Affects all REQUIRED SUB-SKILL, RECOMMENDED SUB-SKILL, and REQUIRED BACKGROUND references -- Aligns with how skills are invoked using the Skill tool -- Files updated: brainstorming, executing-plans, subagent-driven-development, systematic-debugging, testing-skills-with-subagents, writing-plans, writing-skills - -### Improvements - -**Design vs implementation plan naming** -- Design documents use `-design.md` suffix to prevent filename collisions -- Implementation plans continue using existing `YYYY-MM-DD-.md` format -- Both stored in `docs/plans/` directory with clear naming distinction - -## v3.1.1 (2025-10-17) - -### Bug Fixes - -- **Fixed command syntax in README** (#44) - Updated all command references to use correct namespaced syntax (`/superpowers:brainstorm` instead of `/brainstorm`). Plugin-provided commands are automatically namespaced by Claude Code to avoid conflicts between plugins. - -## v3.1.0 (2025-10-17) - -### Breaking Changes - -**Skill names standardized to lowercase** -- All skill frontmatter `name:` fields now use lowercase kebab-case matching directory names -- Examples: `brainstorming`, `test-driven-development`, `using-git-worktrees` -- All skill announcements and cross-references updated to lowercase format -- This ensures consistent naming across directory names, frontmatter, and documentation - -### New Features - -**Enhanced brainstorming skill** -- Added Quick Reference table showing phases, activities, and tool usage -- Added copyable workflow checklist for tracking progress -- Added decision flowchart for when to revisit earlier phases -- Added comprehensive AskUserQuestion tool guidance with concrete examples -- Added "Question Patterns" section explaining when to use structured vs open-ended questions -- Restructured Key Principles as scannable table - -**Anthropic best practices integration** -- Added `skills/writing-skills/anthropic-best-practices.md` - Official Anthropic skill authoring guide -- Referenced in writing-skills SKILL.md for comprehensive guidance -- Provides patterns for progressive disclosure, workflows, and evaluation - -### Improvements - -**Skill cross-reference clarity** -- All skill references now use explicit requirement markers: - - `**REQUIRED BACKGROUND:**` - Prerequisites you must understand - - `**REQUIRED SUB-SKILL:**` - Skills that must be used in workflow - - `**Complementary skills:**` - Optional but helpful related skills -- Removed old path format (`skills/collaboration/X` → just `X`) -- Updated Integration sections with categorized relationships (Required vs Complementary) -- Updated cross-reference documentation with best practices - -**Alignment with Anthropic best practices** -- Fixed description grammar and voice (fully third-person) -- Added Quick Reference tables for scanning -- Added workflow checklists Claude can copy and track -- Appropriate use of flowcharts for non-obvious decision points -- Improved scannable table formats -- All skills well under 500-line recommendation - -### Bug Fixes - -- **Re-added missing command redirects** - Restored `commands/brainstorm.md` and `commands/write-plan.md` that were accidentally removed in v3.0 migration -- Fixed `defense-in-depth` name mismatch (was `Defense-in-Depth-Validation`) -- Fixed `receiving-code-review` name mismatch (was `Code-Review-Reception`) -- Fixed `commands/brainstorm.md` reference to correct skill name -- Removed references to non-existent related skills - -### Documentation - -**writing-skills improvements** -- Updated cross-referencing guidance with explicit requirement markers -- Added reference to Anthropic's official best practices -- Improved examples showing proper skill reference format - -## v3.0.1 (2025-10-16) - -### Changes - -We now use Anthropic's first-party skills system! - -## v2.0.2 (2025-10-12) - -### Bug Fixes - -- **Fixed false warning when local skills repo is ahead of upstream** - The initialization script was incorrectly warning "New skills available from upstream" when the local repository had commits ahead of upstream. The logic now correctly distinguishes between three git states: local behind (should update), local ahead (no warning), and diverged (should warn). - -## v2.0.1 (2025-10-12) - -### Bug Fixes - -- **Fixed session-start hook execution in plugin context** (#8, PR #9) - The hook was failing silently with "Plugin hook error" preventing skills context from loading. Fixed by: - - Using `${BASH_SOURCE[0]:-$0}` fallback when BASH_SOURCE is unbound in Claude Code's execution context - - Adding `|| true` to handle empty grep results gracefully when filtering status flags - ---- - -# Superpowers v2.0.0 Release Notes - -## Overview - -Superpowers v2.0 makes skills more accessible, maintainable, and community-driven through a major architectural shift. - -The headline change is **skills repository separation**: all skills, scripts, and documentation have moved from the plugin into a dedicated repository ([obra/superpowers-skills](https://github.com/obra/superpowers-skills)). This transforms superpowers from a monolithic plugin into a lightweight shim that manages a local clone of the skills repository. Skills auto-update on session start. Users fork and contribute improvements via standard git workflows. The skills library versions independently from the plugin. - -Beyond infrastructure, this release adds nine new skills focused on problem-solving, research, and architecture. We rewrote the core **using-skills** documentation with imperative tone and clearer structure, making it easier for Claude to understand when and how to use skills. **find-skills** now outputs paths you can paste directly into the Read tool, eliminating friction in the skills discovery workflow. - -Users experience seamless operation: the plugin handles cloning, forking, and updating automatically. Contributors find the new architecture makes improving and sharing skills trivial. This release lays the foundation for skills to evolve rapidly as a community resource. - -## Breaking Changes - -### Skills Repository Separation - -**The biggest change:** Skills no longer live in the plugin. They've been moved to a separate repository at [obra/superpowers-skills](https://github.com/obra/superpowers-skills). - -**What this means for you:** - -- **First install:** Plugin automatically clones skills to `~/.config/superpowers/skills/` -- **Forking:** During setup, you'll be offered the option to fork the skills repo (if `gh` is installed) -- **Updates:** Skills auto-update on session start (fast-forward when possible) -- **Contributing:** Work on branches, commit locally, submit PRs to upstream -- **No more shadowing:** Old two-tier system (personal/core) replaced with single-repo branch workflow - -**Migration:** - -If you have an existing installation: -1. Your old `~/.config/superpowers/.git` will be backed up to `~/.config/superpowers/.git.bak` -2. Old skills will be backed up to `~/.config/superpowers/skills.bak` -3. Fresh clone of obra/superpowers-skills will be created at `~/.config/superpowers/skills/` - -### Removed Features - -- **Personal superpowers overlay system** - Replaced with git branch workflow -- **setup-personal-superpowers hook** - Replaced by initialize-skills.sh - -## New Features - -### Skills Repository Infrastructure - -**Automatic Clone & Setup** (`lib/initialize-skills.sh`) -- Clones obra/superpowers-skills on first run -- Offers fork creation if GitHub CLI is installed -- Sets up upstream/origin remotes correctly -- Handles migration from old installation - -**Auto-Update** -- Fetches from tracking remote on every session start -- Auto-merges with fast-forward when possible -- Notifies when manual sync needed (branch diverged) -- Uses pulling-updates-from-skills-repository skill for manual sync - -### New Skills - -**Problem-Solving Skills** (`skills/problem-solving/`) -- **collision-zone-thinking** - Force unrelated concepts together for emergent insights -- **inversion-exercise** - Flip assumptions to reveal hidden constraints -- **meta-pattern-recognition** - Spot universal principles across domains -- **scale-game** - Test at extremes to expose fundamental truths -- **simplification-cascades** - Find insights that eliminate multiple components -- **when-stuck** - Dispatch to right problem-solving technique - -**Research Skills** (`skills/research/`) -- **tracing-knowledge-lineages** - Understand how ideas evolved over time - -**Architecture Skills** (`skills/architecture/`) -- **preserving-productive-tensions** - Keep multiple valid approaches instead of forcing premature resolution - -### Skills Improvements - -**using-skills (formerly getting-started)** -- Renamed from getting-started to using-skills -- Complete rewrite with imperative tone (v4.0.0) -- Front-loaded critical rules -- Added "Why" explanations for all workflows -- Always includes /SKILL.md suffix in references -- Clearer distinction between rigid rules and flexible patterns - -**writing-skills** -- Cross-referencing guidance moved from using-skills -- Added token efficiency section (word count targets) -- Improved CSO (Claude Search Optimization) guidance - -**sharing-skills** -- Updated for new branch-and-PR workflow (v2.0.0) -- Removed personal/core split references - -**pulling-updates-from-skills-repository** (new) -- Complete workflow for syncing with upstream -- Replaces old "updating-skills" skill - -### Tools Improvements - -**find-skills** -- Now outputs full paths with /SKILL.md suffix -- Makes paths directly usable with Read tool -- Updated help text - -**skill-run** -- Moved from scripts/ to skills/using-skills/ -- Improved documentation - -### Plugin Infrastructure - -**Session Start Hook** -- Now loads from skills repository location -- Shows full skills list at session start -- Prints skills location info -- Shows update status (updated successfully / behind upstream) -- Moved "skills behind" warning to end of output - -**Environment Variables** -- `SUPERPOWERS_SKILLS_ROOT` set to `~/.config/superpowers/skills` -- Used consistently throughout all paths - -## Bug Fixes - -- Fixed duplicate upstream remote addition when forking -- Fixed find-skills double "skills/" prefix in output -- Removed obsolete setup-personal-superpowers call from session-start -- Fixed path references throughout hooks and commands - -## Documentation - -### README -- Updated for new skills repository architecture -- Prominent link to superpowers-skills repo -- Updated auto-update description -- Fixed skill names and references -- Updated Meta skills list - -### Testing Documentation -- Added comprehensive testing checklist (`docs/TESTING-CHECKLIST.md`) -- Created local marketplace config for testing -- Documented manual testing scenarios - -## Technical Details - -### File Changes - -**Added:** -- `lib/initialize-skills.sh` - Skills repo initialization and auto-update -- `docs/TESTING-CHECKLIST.md` - Manual testing scenarios -- `.claude-plugin/marketplace.json` - Local testing config - -**Removed:** -- `skills/` directory (82 files) - Now in obra/superpowers-skills -- `scripts/` directory - Now in obra/superpowers-skills/skills/using-skills/ -- `hooks/setup-personal-superpowers.sh` - Obsolete - -**Modified:** -- `hooks/session-start.sh` - Use skills from ~/.config/superpowers/skills -- `commands/brainstorm.md` - Updated paths to SUPERPOWERS_SKILLS_ROOT -- `commands/write-plan.md` - Updated paths to SUPERPOWERS_SKILLS_ROOT -- `commands/execute-plan.md` - Updated paths to SUPERPOWERS_SKILLS_ROOT -- `README.md` - Complete rewrite for new architecture - -### Commit History +**Plugin renamed to superpowers-ng** -This release includes: -- 20+ commits for skills repository separation -- PR #1: Amplifier-inspired problem-solving and research skills -- PR #2: Personal superpowers overlay system (later replaced) -- Multiple skill refinements and documentation improvements +This fork is distributed separately from original superpowers: +- Plugin name: `superpowers-ng` +- Repository: `OniReimu/superpowers` +- Version reset to v0.1.0 -## Upgrade Instructions +**File:** +- `.claude-plugin/plugin.json` - Updated name, version, author, repository, added credits -### Fresh Install +### Credits -```bash -# In Claude Code -/plugin marketplace add obra/superpowers-marketplace -/plugin install superpowers@superpowers-marketplace -``` +**Original Authors:** +- **Jesse Vincent (obra)** - [obra/superpowers](https://github.com/obra/superpowers) - Original Superpowers framework +- **Ahmad Othman Ammar Adi (OthmanAdi)** - [planning-with-files](https://github.com/OthmanAdi/planning-with-files) - Manus 3-file pattern -The plugin handles everything automatically. +**Superpowers-NG:** +- **OniReimu** - Integration and enhancement -### Upgrading from v1.x +**Inspiration:** +- Manus AI (acquired by Meta for $2B) - Context engineering principles codified in planning-with-files -1. **Backup your personal skills** (if you have any): - ```bash - cp -r ~/.config/superpowers/skills ~/superpowers-skills-backup - ``` +### Design Decisions -2. **Update the plugin:** - ```bash - /plugin update superpowers - ``` +**Separate planning systems (no cross-style switching)** +- Native and Manus use different file formats and hooks +- Users choose one at the start based on task complexity +- Prevents format conflicts and unexpected behavior -3. **On next session start:** - - Old installation will be backed up automatically - - Fresh skills repo will be cloned - - If you have GitHub CLI, you'll be offered the option to fork +**Marker file for conditional hooks** +- `.active` file enables/disables PreToolUse hooks +- Clean isolation: hooks don't fire for native planning +- Automatically removed on task completion -4. **Migrate personal skills** (if you had any): - - Create a branch in your local skills repo - - Copy your personal skills from backup - - Commit and push to your fork - - Consider contributing back via PR +**Archive approach for multi-task handling** +- Completed tasks (no `.active`): Auto-archive to `docs/manus/archive/YYYY-MM-DD-/` +- In-progress tasks (`.active` exists): Prompt user to continue or start new +- Preserves history while keeping active location predictable -## What's Next +**Design document integration** +- Brainstorming → Manus flow copies design content into `findings.md` +- Becomes part of persistent research storage +- Accessible across context resets -### For Users +### Known Limitations -- Explore the new problem-solving skills -- Try the branch-based workflow for skill improvements -- Contribute skills back to the community +**Installation requires manual setup** +- Marketplace integration pending +- Users must clone repository directly +- Will be resolved in future release -### For Contributors +**No cross-platform testing** +- Hook script tested on macOS only +- Should work on Linux/Windows (uses polyglot wrapper) +- Community testing needed -- Skills repository is now at https://github.com/obra/superpowers-skills -- Fork → Branch → PR workflow -- See skills/meta/writing-skills/SKILL.md for TDD approach to documentation +### Upgrade Path -## Known Issues +**For users of obra/superpowers:** +- Superpowers-NG is a separate fork, not a drop-in replacement +- Can install both plugins side-by-side +- Native planning workflows unchanged +- Manus planning is additive, opt-in feature -None at this time. +**For new users:** +- Start with either Native or Manus planning based on task +- Both workflows fully supported +- Brainstorming skill guides choice after design -## Credits +### What's Next -- Problem-solving skills inspired by Amplifier patterns -- Community contributions and feedback -- Extensive testing and iteration on skill effectiveness +**Planned enhancements:** +- Marketplace publication for easy installation +- Subagent handoff support (Task 8 from implementation plan) +- Template customization +- Cross-platform testing and validation +- Community feedback integration --- -**Full Changelog:** https://github.com/obra/superpowers/compare/dd013f6...main -**Skills Repository:** https://github.com/obra/superpowers-skills -**Issues:** https://github.com/obra/superpowers/issues +**Full Changelog:** https://github.com/OniReimu/superpowers/compare/obra:main...OniReimu:main +**Issues:** https://github.com/OniReimu/superpowers/issues +**Original Superpowers:** https://github.com/obra/superpowers +**Planning-with-files:** https://github.com/OthmanAdi/planning-with-files diff --git a/commands/brainstorm.md b/commands/brainstorm.md index 0fb3a8945..8dac06131 100644 --- a/commands/brainstorm.md +++ b/commands/brainstorm.md @@ -3,4 +3,4 @@ description: "You MUST use this before any creative work - creating features, bu disable-model-invocation: true --- -Invoke the superpowers:brainstorming skill and follow it exactly as presented to you +Invoke the superpowers-ng:brainstorming skill and follow it exactly as presented to you diff --git a/commands/execute-plan.md b/commands/execute-plan.md index c48f14005..58bfa2358 100644 --- a/commands/execute-plan.md +++ b/commands/execute-plan.md @@ -3,4 +3,4 @@ description: Execute plan in batches with review checkpoints disable-model-invocation: true --- -Invoke the superpowers:executing-plans skill and follow it exactly as presented to you +Invoke the superpowers-ng:executing-plans skill and follow it exactly as presented to you diff --git a/commands/manus-plan.md b/commands/manus-plan.md new file mode 100644 index 000000000..2aa25b645 --- /dev/null +++ b/commands/manus-plan.md @@ -0,0 +1,6 @@ +--- +description: Start Manus-style planning with persistent 3-file tracking for complex tasks +disable-model-invocation: true +--- + +Invoke the superpowers-ng:manus-planning skill and follow it exactly as presented to you diff --git a/commands/write-plan.md b/commands/write-plan.md index 12962fd78..39520def1 100644 --- a/commands/write-plan.md +++ b/commands/write-plan.md @@ -3,4 +3,4 @@ description: Create detailed implementation plan with bite-sized tasks disable-model-invocation: true --- -Invoke the superpowers:writing-plans skill and follow it exactly as presented to you +Invoke the superpowers-ng:writing-plans skill and follow it exactly as presented to you diff --git a/docs/README.codex.md b/docs/README.codex.md index e43004f42..ff76032f8 100644 --- a/docs/README.codex.md +++ b/docs/README.codex.md @@ -51,7 +51,7 @@ Run ~/.codex/superpowers/.codex/superpowers-codex find-skills ### Loading a Skill ``` -Run ~/.codex/superpowers/.codex/superpowers-codex use-skill superpowers:brainstorming +Run ~/.codex/superpowers/.codex/superpowers-codex use-skill superpowers-ng:brainstorming ``` ### Bootstrap All Skills diff --git a/docs/README.opencode.md b/docs/README.opencode.md index 122fe55ea..769a6ddc7 100644 --- a/docs/README.opencode.md +++ b/docs/README.opencode.md @@ -63,7 +63,7 @@ use find_skills tool Use the `use_skill` tool to load a specific skill: ``` -use use_skill tool with skill_name: "superpowers:brainstorming" +use use_skill tool with skill_name: "superpowers-ng:brainstorming" ``` Skills are automatically inserted into the conversation and persist across context compaction. @@ -122,7 +122,7 @@ Skills are resolved with this priority order: You can force resolution to a specific level: - `project:skill-name` - Force project skill - `skill-name` - Search project → personal → superpowers -- `superpowers:skill-name` - Force superpowers skill +- `superpowers-ng:skill-name` - Force superpowers skill ## Features diff --git a/docs/plans/2025-11-22-opencode-support-design.md b/docs/plans/2025-11-22-opencode-support-design.md index 144f1cea2..c43586812 100644 --- a/docs/plans/2025-11-22-opencode-support-design.md +++ b/docs/plans/2025-11-22-opencode-support-design.md @@ -80,7 +80,7 @@ Loads a specific skill's content into the conversation (equivalent to Claude's S name: 'use_skill', description: 'Load and read a specific skill to guide your work', schema: z.object({ - skill_name: z.string().describe('Name of skill (e.g., "superpowers:brainstorming")') + skill_name: z.string().describe('Name of skill (e.g., "superpowers-ng:brainstorming")') }), execute: async ({ skill_name }) => { const { skillPath, content, frontmatter } = resolveAndReadSkill(skill_name); diff --git a/docs/plans/2025-11-22-opencode-support-implementation.md b/docs/plans/2025-11-22-opencode-support-implementation.md index 1a7c1fb99..5f5ce7b50 100644 --- a/docs/plans/2025-11-22-opencode-support-implementation.md +++ b/docs/plans/2025-11-22-opencode-support-implementation.md @@ -1,6 +1,6 @@ # OpenCode Support Implementation Plan -> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers-ng:executing-plans to implement this plan task-by-task. **Goal:** Add full superpowers support for OpenCode.ai with a native JavaScript plugin that shares core functionality with the existing Codex implementation. @@ -191,17 +191,17 @@ Add before `module.exports`: * Resolve a skill name to its file path, handling shadowing * (personal skills override superpowers skills). * - * @param {string} skillName - Name like "superpowers:brainstorming" or "my-skill" + * @param {string} skillName - Name like "superpowers-ng:brainstorming" or "my-skill" * @param {string} superpowersDir - Path to superpowers skills directory * @param {string} personalDir - Path to personal skills directory * @returns {{skillFile: string, sourceType: string, skillPath: string} | null} */ function resolveSkillPath(skillName, superpowersDir, personalDir) { - // Strip superpowers: prefix if present - const forceSuperpowers = skillName.startsWith('superpowers:'); - const actualSkillName = forceSuperpowers ? skillName.replace(/^superpowers:/, '') : skillName; + // Strip superpowers-ng: prefix if present + const forceSuperpowers = skillName.startsWith('superpowers-ng:'); + const actualSkillName = forceSuperpowers ? skillName.replace(/^superpowers-ng:/, '') : skillName; - // Try personal skills first (unless explicitly superpowers:) + // Try personal skills first (unless explicitly superpowers-ng:) if (!forceSuperpowers && personalDir) { const personalPath = path.join(personalDir, actualSkillName); const personalSkillFile = path.join(personalPath, 'SKILL.md'); @@ -516,7 +516,7 @@ export const SuperpowersPlugin = async ({ project, client, $, directory, worktre name: 'use_skill', description: 'Load and read a specific skill to guide your work. Skills contain proven workflows, mandatory processes, and expert techniques.', schema: z.object({ - skill_name: z.string().describe('Name of the skill to load (e.g., "superpowers:brainstorming" or "my-custom-skill")') + skill_name: z.string().describe('Name of the skill to load (e.g., "superpowers-ng:brainstorming" or "my-custom-skill")') }), execute: async ({ skill_name }) => { // Resolve skill path (handles shadowing: personal > superpowers) @@ -623,7 +623,7 @@ Add after the use_skill tool definition, before closing the tools array: let output = 'Available skills:\n\n'; for (const skill of allSkills) { - const namespace = skill.sourceType === 'personal' ? '' : 'superpowers:'; + const namespace = skill.sourceType === 'personal' ? '' : 'superpowers-ng:'; const skillName = skill.name || path.basename(skill.path); output += `${namespace}${skillName}\n`; @@ -712,7 +712,7 @@ When skills reference tools you don't have, substitute OpenCode equivalents: - Utilities and helpers specific to that skill **Skills naming:** -- Superpowers skills: \`superpowers:skill-name\` (from ~/.config/opencode/superpowers/skills/) +- Superpowers skills: \`superpowers-ng:skill-name\` (from ~/.config/opencode/superpowers/skills/) - Personal skills: \`skill-name\` (from ~/.config/opencode/skills/) - Personal skills override superpowers skills when names match `; @@ -731,7 +731,7 @@ When skills reference tools you don't have, substitute OpenCode equivalents: context: ` You have superpowers. -**Below is the full content of your 'superpowers:using-superpowers' skill - your introduction to using skills. For all other skills, use the 'use_skill' tool:** +**Below is the full content of your 'superpowers-ng:using-superpowers' skill - your introduction to using skills. For all other skills, use the 'use_skill' tool:** ${usingSuperpowersContent} @@ -821,7 +821,7 @@ use find_skills tool Use the `use_skill` tool to load a specific skill: ``` -use use_skill tool with skill_name: "superpowers:brainstorming" +use use_skill tool with skill_name: "superpowers-ng:brainstorming" ``` ### Personal Skills @@ -991,7 +991,7 @@ Expected: Shows list of skills with names and descriptions **Step 2: Test use-skill command** -Run: `.codex/superpowers-codex use-skill superpowers:brainstorming | head -20` +Run: `.codex/superpowers-codex use-skill superpowers-ng:brainstorming | head -20` Expected: Shows brainstorming skill content **Step 3: Test bootstrap command** diff --git a/docs/plans/2025-11-28-skills-improvements-from-user-feedback.md b/docs/plans/2025-11-28-skills-improvements-from-user-feedback.md index 52a8b0ea9..c1d35532d 100644 --- a/docs/plans/2025-11-28-skills-improvements-from-user-feedback.md +++ b/docs/plans/2025-11-28-skills-improvements-from-user-feedback.md @@ -507,7 +507,7 @@ Directly addresses the failure pattern from feedback. BEFORE writing any tests: 1. Read testing-anti-patterns skill: - Use Skill tool: superpowers:testing-anti-patterns + Use Skill tool: superpowers-ng:testing-anti-patterns 2. Apply gate functions from that skill when: - Writing mocks diff --git a/docs/ralph-integration/PROMPT.template.md b/docs/ralph-integration/PROMPT.template.md new file mode 100644 index 000000000..4ef51a8c8 --- /dev/null +++ b/docs/ralph-integration/PROMPT.template.md @@ -0,0 +1,469 @@ +# Project Development Instructions + +> **Template**: Copy this to your Ralph project's PROMPT.md and customize the [PROJECT CONTEXT] section + +## Project Context + +[REPLACE THIS SECTION WITH YOUR PROJECT SPECIFICS] + +**Project Name**: [Your project name] + +**Goal**: [What you're building - one clear sentence] + +**Requirements**: +- [Key requirement 1] +- [Key requirement 2] +- [Key requirement 3] + +**Technical Stack**: [Languages, frameworks, tools] + +**Success Criteria**: [How do you know when this is done?] + +--- + +## Development Workflow + +You are working within the Ralph autonomous loop framework with Superpowers-NG skills for development best practices. + +### Phase 1: Design (Run Once) + +Check if `docs/plans/*-design.md` exists: + +**If NO design exists**: +- Use **superpowers-ng:brainstorming** to explore requirements and create design +- The skill will create `docs/plans/YYYY-MM-DD-topic-design.md` +- Brainstorming will automatically skip to implementation if design exists + +**If design exists**: +- Read it for context +- Skip brainstorming +- Proceed to Phase 2 + +### Phase 2: Planning (Run Once) + +Choose based on task complexity: + +**For long-running tasks (>50 tool calls, multi-session work)**: +- Use **superpowers-ng:manus-planning** +- Creates persistent files in `docs/manus/`: + - `task_plan.md` - 5-phase plan with goals and decisions + - `findings.md` - Research and requirements + - `progress.md` - Session log and test results + - `.active` - Marker file for active task +- **Auto-resumes**: If `docs/manus/.active` exists, manus-planning automatically continues from current phase + +**For shorter tasks (<30 min, interactive)**: +- Use **superpowers-ng:writing-plans** to create implementation plan +- Then use **superpowers-ng:executing-plans** to execute in batches + +**Recommended**: Use manus-planning for Ralph projects (designed for context resets and long runs) + +### Phase 3: Implementation (Every Loop) + +Focus on ONE task from `@fix_plan.md` per loop. + +**Core disciplines**: +- Use **superpowers-ng:test-driven-development** for ALL implementation + - Write failing test first + - Make it pass + - Refactor + - NO production code without a failing test first + +- Use **superpowers-ng:systematic-debugging** when bugs occur + - 4-phase root cause process + - No trial-and-error fixes + - Document resolution in progress.md + +**After completing a task**: +- Mark it complete in `@fix_plan.md`: `- [x] Task description` +- Update manus-planning progress (if using) +- Emit status (see Phase 4) + +### Phase 4: Completion + +Before claiming completion: + +1. Use **superpowers-ng:verification-before-completion** + - Run tests + - Verify output + - Gather evidence + - Only claim complete if evidence confirms it + +2. Check completion criteria: + - ALL tasks in `@fix_plan.md` marked `[x]` + - All Manus phases complete (if using manus-planning) + - Tests pass + - No blocking errors + +3. If complete: + - Remove `docs/manus/.active` marker (if exists) + - Emit EXIT_SIGNAL: true + +## Status Emission (REQUIRED) + +**CRITICAL**: At the end of EVERY response, you MUST emit this exact status block format: + +``` +---RALPH_STATUS--- +STATUS: IN_PROGRESS | COMPLETE | BLOCKED +TASKS_COMPLETED_THIS_LOOP: +FILES_MODIFIED: +TESTS_STATUS: PASSING | FAILING | NOT_RUN +WORK_TYPE: IMPLEMENTATION | TESTING | DOCUMENTATION | REFACTORING +EXIT_SIGNAL: false | true +RECOMMENDATION: +---END_RALPH_STATUS--- +``` + +**Field Descriptions**: +- **STATUS**: Current state of the project + - `IN_PROGRESS`: Actively working, more to do + - `COMPLETE`: All tasks done, ready for handoff + - `BLOCKED`: Cannot proceed (external dependency, repeated failures after 3+ attempts) +- **TASKS_COMPLETED_THIS_LOOP**: Number of tasks from @fix_plan.md marked complete this loop +- **FILES_MODIFIED**: Number of files changed this loop +- **TESTS_STATUS**: Result of test execution + - `PASSING`: All tests pass + - `FAILING`: One or more tests fail + - `NOT_RUN`: Tests haven't been executed yet +- **WORK_TYPE**: What you focused on this loop +- **EXIT_SIGNAL**: Set to `true` ONLY when all Phase 4 completion criteria met +- **RECOMMENDATION**: One-line summary of next action + +### Status Block Examples + +**Example 1: Active Development** +``` +---RALPH_STATUS--- +STATUS: IN_PROGRESS +TASKS_COMPLETED_THIS_LOOP: 2 +FILES_MODIFIED: 5 +TESTS_STATUS: PASSING +WORK_TYPE: IMPLEMENTATION +EXIT_SIGNAL: false +RECOMMENDATION: Continue with next priority task from @fix_plan.md +---END_RALPH_STATUS--- +``` + +**Example 2: Project Complete** +``` +---RALPH_STATUS--- +STATUS: COMPLETE +TASKS_COMPLETED_THIS_LOOP: 1 +FILES_MODIFIED: 1 +TESTS_STATUS: PASSING +WORK_TYPE: DOCUMENTATION +EXIT_SIGNAL: true +RECOMMENDATION: All requirements met, project ready for review +---END_RALPH_STATUS--- +``` + +**Example 3: Blocked State** +``` +---RALPH_STATUS--- +STATUS: BLOCKED +TASKS_COMPLETED_THIS_LOOP: 0 +FILES_MODIFIED: 0 +TESTS_STATUS: FAILING +WORK_TYPE: DEBUGGING +EXIT_SIGNAL: false +RECOMMENDATION: Need human help - same error for 3 loops +---END_RALPH_STATUS--- +``` + +## Autonomous Mode Behavior + +You are operating in autonomous mode (Ralph loops). This means: + +**DO**: +- Focus on ONE task from `@fix_plan.md` per loop +- Complete the task fully before ending response +- Use best judgment without waiting for user input +- Emit status block at the end of EVERY response +- Set STATUS: BLOCKED if truly stuck (external dependency, repeated failures) +- Follow Superpowers skills exactly as written + +**DON'T**: +- Wait for user input mid-task +- Ask clarifying questions (use best judgment based on context) +- Work on multiple tasks in a single loop +- Skip status emission +- Loop endlessly on errors (set BLOCKED after 3 attempts) + +## Circuit Breaker Patterns + +Ralph monitors for unproductive loops. These patterns trigger automatic intervention: + +### Pattern 1: Test-Only Loops +**Trigger**: 3 consecutive loops with WORK_TYPE: TESTING and TASKS_COMPLETED_THIS_LOOP: 0 + +**What this means**: Running tests repeatedly without implementing new features is busy work. + +**What to do**: +- If tests are passing and no new features needed: Set EXIT_SIGNAL: true +- If tests are failing: Fix the issue (WORK_TYPE: IMPLEMENTATION), don't just re-run tests +- If all tasks done but tests keep failing: Set STATUS: BLOCKED + +### Pattern 2: Recurring Errors +**Trigger**: 5 loops with identical errors in the same location + +**What this means**: Same approach keeps failing, need different strategy or human help. + +**What to do**: +- After 3 attempts with same error: Document in progress.md, try completely different approach +- After 5 attempts: Set STATUS: BLOCKED, RECOMMENDATION: "Need human help - [describe issue]" + +### Pattern 3: Zero Progress +**Trigger**: 3 consecutive loops with TASKS_COMPLETED_THIS_LOOP: 0 and STATUS: IN_PROGRESS + +**What this means**: Either working on wrong things or task is genuinely blocked. + +**What to do**: +- Review @fix_plan.md - are you working on the right task? +- If genuinely stuck: Set STATUS: BLOCKED with clear explanation + +## Anti-Patterns: What NOT to Do + +These are explicitly forbidden - Ralph will detect and stop these patterns: + +| Anti-Pattern | Why It's Wrong | What to Do Instead | +|--------------|---------------|-------------------| +| **Continue when EXIT_SIGNAL should be true** | Wastes tokens, adds unnecessary code | Check completion criteria, exit when done | +| **Refactor working code** | Changes code that already works | Only refactor if explicitly in @fix_plan.md | +| **Add features not in @fix_plan.md** | Scope creep, YAGNI violation | Stick to planned tasks only | +| **Run tests repeatedly without changes** | False sense of progress | Fix issues or move to next task | +| **Omit status block** | Ralph can't track progress | ALWAYS emit status block | +| **Add "nice to have" improvements** | Busy work when real work is done | Set EXIT_SIGNAL: true instead | +| **Write documentation when no code changed** | Filler work to avoid exiting | Exit if all tasks complete | +| **Optimize already-fast code** | Premature optimization | Focus on unfinished tasks | + +### When to Stop: Exit Criteria Checklist + +Before setting EXIT_SIGNAL: true, verify ALL conditions: + +- [ ] All tasks in @fix_plan.md marked `[x]` +- [ ] All tests passing (TESTS_STATUS: PASSING) +- [ ] No errors in last execution +- [ ] All specs/ requirements implemented +- [ ] Manus phases complete (if using manus-planning) +- [ ] No meaningful work remains +- [ ] Nothing "nice to have" remaining (YAGNI - we don't need it) + +**If even one checkbox is unchecked**: EXIT_SIGNAL: false + +**Quality over speed**: It's better to exit early and get human feedback than to continue with busy work. + +## Key Principles + +1. **Test-Driven Development** - NO code without failing test first +2. **ONE Task Per Loop** - Depth over breadth +3. **Evidence-Based Claims** - Verify before claiming success +4. **Persistent Memory** - Use manus-planning files for continuity +5. **Exit Responsibly** - EXIT_SIGNAL: true only when truly complete + +## File Management + +**Ralph files** (you manage): +- `@fix_plan.md` - Update as tasks complete +- `logs/ralph.log` - Optionally append significant events + +**Superpowers files** (created by skills): +- `docs/plans/*-design.md` - From brainstorming +- `docs/manus/task_plan.md` - From manus-planning +- `docs/manus/findings.md` - Research and decisions +- `docs/manus/progress.md` - Detailed session log +- `docs/manus/.active` - Marker for active task + +## Common Scenarios + +### Scenario 1: First Loop - No Artifacts + +**Actions**: +1. No design.md exists → Run **superpowers-ng:brainstorming** → Create `docs/plans/YYYY-MM-DD-topic-design.md` +2. No docs/manus/ exists → Start **superpowers-ng:manus-planning** → Create task_plan.md, findings.md, progress.md, .active +3. Work on first task from @fix_plan.md using **superpowers-ng:test-driven-development** +4. Mark task complete in @fix_plan.md: `- [x] Task description` + +**Status Emission**: +``` +---RALPH_STATUS--- +STATUS: IN_PROGRESS +TASKS_COMPLETED_THIS_LOOP: 1 +FILES_MODIFIED: 8 +TESTS_STATUS: PASSING +WORK_TYPE: IMPLEMENTATION +EXIT_SIGNAL: false +RECOMMENDATION: Continue with next task from @fix_plan.md +---END_RALPH_STATUS--- +``` + +### Scenario 2: Continuing Work + +**Actions**: +1. design.md exists → brainstorming auto-skips to implementation +2. .active exists → manus-planning auto-resumes from current phase +3. Continue next task from @fix_plan.md +4. Use **superpowers-ng:test-driven-development** for implementation + +**Status Emission**: +``` +---RALPH_STATUS--- +STATUS: IN_PROGRESS +TASKS_COMPLETED_THIS_LOOP: 2 +FILES_MODIFIED: 5 +TESTS_STATUS: PASSING +WORK_TYPE: IMPLEMENTATION +EXIT_SIGNAL: false +RECOMMENDATION: 3 tasks remaining in @fix_plan.md +---END_RALPH_STATUS--- +``` + +### Scenario 3: Hitting a Blocker + +**Actions**: +1. Attempted fix 3 times, same error occurs +2. Use **superpowers-ng:systematic-debugging** to diagnose +3. After 3 attempts still failing → Document in progress.md and task_plan.md +4. Set STATUS: BLOCKED + +**Status Emission**: +``` +---RALPH_STATUS--- +STATUS: BLOCKED +TASKS_COMPLETED_THIS_LOOP: 0 +FILES_MODIFIED: 0 +TESTS_STATUS: FAILING +WORK_TYPE: DEBUGGING +EXIT_SIGNAL: false +RECOMMENDATION: Need human help - database connection fails in test environment +---END_RALPH_STATUS--- +``` + +**Note**: Ralph's circuit breaker will detect BLOCKED status and stop the loop. + +### Scenario 4: All Tasks Complete + +**Actions**: +1. All @fix_plan.md tasks marked `[x]` +2. All manus phases complete +3. Run **superpowers-ng:verification-before-completion** +4. Tests pass (verified with evidence) +5. Remove .active marker: `rm docs/manus/.active` + +**Status Emission**: +``` +---RALPH_STATUS--- +STATUS: COMPLETE +TASKS_COMPLETED_THIS_LOOP: 1 +FILES_MODIFIED: 1 +TESTS_STATUS: PASSING +WORK_TYPE: DOCUMENTATION +EXIT_SIGNAL: true +RECOMMENDATION: All requirements met, project ready for review +---END_RALPH_STATUS--- +``` + +### Scenario 5: Test-Only Loop Detected (Anti-Pattern) + +**Situation**: Tests passing, no more work, but agent keeps running tests. + +**What NOT to do**: +``` +Loop N: Run tests → all pass → run tests again +Loop N+1: Run tests → all pass → run tests again +Loop N+2: Run tests → all pass → run tests again ← Circuit breaker triggers! +``` + +**What TO do**: +``` +Loop N: Run tests → all pass → Check @fix_plan.md → All tasks [x] → EXIT_SIGNAL: true +``` + +**Correct Status Emission**: +``` +---RALPH_STATUS--- +STATUS: COMPLETE +TASKS_COMPLETED_THIS_LOOP: 0 +FILES_MODIFIED: 0 +TESTS_STATUS: PASSING +WORK_TYPE: TESTING +EXIT_SIGNAL: true +RECOMMENDATION: All tasks complete, no further work needed +---END_RALPH_STATUS--- +``` + +## Build & Test Instructions + +[CUSTOMIZE THIS SECTION FOR YOUR PROJECT] + +**How to run tests**: +```bash +# Add your test command +npm test +# or +pytest +# or +cargo test +``` + +**How to build**: +```bash +# Add your build command +npm run build +# or +cargo build --release +``` + +**How to run**: +```bash +# Add your run command +npm start +# or +./target/release/your-binary +``` + +## Additional Context + +[ADD ANY PROJECT-SPECIFIC CONTEXT HERE] +- API documentation links +- Architecture decisions +- Coding conventions +- Performance requirements +- Security considerations + +--- + +## Remember (Critical Reminders) + +**Status Emission**: +- **ALWAYS** emit `---RALPH_STATUS---` block at end of EVERY response +- Use Ralph's official format (STATUS, TASKS_COMPLETED_THIS_LOOP, FILES_MODIFIED, etc.) +- Never skip status block - Ralph depends on it for loop control + +**ONE Task Per Loop**: +- Focus on single task from @fix_plan.md +- Depth over breadth +- Mark complete when done: `- [x] Task` + +**Know When to Exit**: +- EXIT_SIGNAL: true ONLY when ALL completion criteria met +- Don't continue with busy work (refactoring, documentation, optimization) +- Quality over quantity - exit early is better than wasted loops + +**Use Superpowers Skills**: +- **superpowers-ng:brainstorming** (checks for existing design) +- **superpowers-ng:manus-planning** (persistent, auto-resumes) +- **superpowers-ng:test-driven-development** (RED-GREEN-REFACTOR) +- **superpowers-ng:systematic-debugging** (root cause analysis) +- **superpowers-ng:verification-before-completion** (evidence-based) + +**Circuit Breakers**: +- 3 test-only loops → Exit +- 5 identical errors → BLOCKED +- 3 loops no progress → BLOCKED +- Don't fight the circuit breaker - it's protecting you + +**Autonomous Mode**: +- Use best judgment, don't wait for user input +- Set BLOCKED when truly stuck +- Document blockers clearly in RECOMMENDATION diff --git a/docs/ralph-integration/README.md b/docs/ralph-integration/README.md new file mode 100644 index 000000000..afde789a5 --- /dev/null +++ b/docs/ralph-integration/README.md @@ -0,0 +1,295 @@ +# Using Superpowers-NG with Ralph + +This guide explains how to use Superpowers-NG skills within the [Ralph autonomous loop framework](https://github.com/frankbria/ralph-claude-code). + +## Overview + +**Ralph** provides the autonomous loop orchestration (session management, exit detection, rate limiting). + +**Superpowers-NG** provides development methodologies and best practices (TDD, debugging, planning). + +They work at different layers and complement each other perfectly. + +## Architecture + +``` +Ralph (External Shell Orchestration) + ├── Loop management & continuation (--continue) + ├── Exit signal detection + ├── Rate limiting & circuit breakers + └── Task list (@fix_plan.md) + │ + └── Claude Code (Internal Skills) + └── Superpowers-NG + ├── test-driven-development + ├── systematic-debugging + ├── manus-planning + └── brainstorming +``` + +## Quick Start + +### 1. Install Both Systems + +```bash +# Install Ralph +git clone https://github.com/frankbria/ralph-claude-code.git +cd ralph-claude-code +./install.sh + +# Install Superpowers-NG as Claude Code plugin +/plugin marketplace add https://github.com/OniReimu/superpowers-ng +/plugin install superpowers-ng@superpowers-ng-marketplace +``` + +### 2. Create Ralph Project with Superpowers + +```bash +# Create project +ralph-setup my-project +cd my-project + +# Copy Superpowers-enhanced PROMPT.md +cp /path/to/superpowers-ng/docs/ralph-integration/PROMPT.template.md PROMPT.md + +# Edit PROMPT.md with your project specifics +# The template already includes Superpowers skill references + +# Run Ralph +ralph --monitor +``` + +## How Skills Work in Ralph Loops + +Ralph runs the same PROMPT.md every loop using `--continue` for session continuity. Skills need to be aware of existing artifacts. + +### Skill Lifecycle in Ralph + +| Skill | Frequency | Condition | Notes | +|-------|-----------|-----------|-------| +| **brainstorming** | Once per task | Only if design.md missing | Auto-skips if design exists | +| **manus-planning** | Started once, continues | Checks for docs/manus/.active | Resumes automatically | +| **writing-plans** | Once per task | Only if plan.md missing | For shorter tasks | +| **executing-plans** | Every loop | Reads existing plan.md | Batch execution | +| **test-driven-development** | Every loop | Always | Core discipline | +| **systematic-debugging** | As needed | When bugs occur | Root cause analysis | +| **verification-before-completion** | Before exit | Claims complete | Evidence-based | + +### Example: Typical Ralph Loop Flow + +``` +Loop 1 (Session 1): + - No design.md → Run brainstorming → Create design.md + - No docs/manus/ → Start manus-planning → Create task_plan.md + - Work on Phase 1 + - Emit status: IN_PROGRESS + +Loop 2 (Session 2, --continue): + - design.md exists → Skip brainstorming + - docs/manus/ + .active exists → Resume manus-planning + - Continue Phase 2 + - Emit status: IN_PROGRESS + +Loop 3 (Session 3, --continue): + - Continue Phase 3 + - Fix bugs using systematic-debugging + - Emit status: IN_PROGRESS + +Final Loop: + - All phases complete + - verification-before-completion checks tests + - Remove .active marker + - Emit status: COMPLETE, EXIT_SIGNAL: true +``` + +## Recommended Skills for Ralph + +### Essential (Use in PROMPT.md) + +1. **manus-planning** - Perfect for Ralph's multi-session nature + - Persistent files survive context resets + - 5-phase structure maps well to long tasks + - Auto-resumes via .active marker + +2. **test-driven-development** - Maintains quality across loops + - RED-GREEN-REFACTOR cycle + - Prevents rationalizations + - Works every loop + +3. **systematic-debugging** - For when things break + - 4-phase root cause process + - Better than trial-and-error + - Saves loop iterations + +4. **verification-before-completion** - Before emitting EXIT_SIGNAL + - Evidence-based claims only + - Prevents premature completion + - Critical for autonomous operation + +### Optional (Conditional Use) + +5. **brainstorming** - Once at start if design needed + - Now checks for existing design + - Auto-skips in subsequent loops + - Use conditionally in PROMPT.md + +6. **using-git-worktrees** - If working on feature branches + - Isolates work + - Clean separation + - Pairs with finishing-a-development-branch + +## PROMPT.md Structure + +See `PROMPT.template.md` for a complete example. Key patterns: + +### Conditional Skill Invocation + +```markdown +# Design Phase (run once) +If docs/plans/*-design.md DOESN'T exist: + - Use superpowers-ng:brainstorming + +# Implementation Phase (every loop) +Use superpowers-ng:manus-planning (auto-resumes if docs/manus/ exists) +Use superpowers-ng:test-driven-development for all code +``` + +### Status Emission + +Ralph needs status at the end of every response: + +```markdown +## Status Format + +At the end of EVERY response, emit: + +---RALPH_STATUS--- +WORK_TYPE: IMPLEMENTATION | TESTING | DOCUMENTATION | REFACTORING +STATUS: IN_PROGRESS | COMPLETE | BLOCKED | NOT_RUN +PROGRESS: [What was accomplished this loop] +REMAINING: [Tasks left in @fix_plan.md] +EXIT_SIGNAL: true | false +---END_STATUS--- + +EXIT_SIGNAL = true ONLY when: +- All tasks in @fix_plan.md complete +- All Manus phases complete (if using manus-planning) +- Tests pass (verified via verification-before-completion) +``` + +## File Management + +### Ralph's Files + +- `@fix_plan.md` - Task checklist (Ralph's source of truth) +- `PROMPT.md` - Development instructions (includes skill references) +- `@AGENT.md` - Build/run instructions +- `logs/ralph.log` - Execution history + +### Superpowers Files + +- `docs/plans/YYYY-MM-DD-topic-design.md` - Design documents (from brainstorming) +- `docs/manus/task_plan.md` - 5-phase plan (from manus-planning) +- `docs/manus/findings.md` - Research and requirements +- `docs/manus/progress.md` - Session log and test results +- `docs/manus/.active` - Marker for active manus task + +### Sync Strategy + +Keep both systems updated: + +| Action | Update Ralph | Update Superpowers | +|--------|--------------|-------------------| +| Complete task | Mark `[x]` in @fix_plan.md | Mark phase complete in task_plan.md | +| Log progress | Append to logs/ralph.log | Append to progress.md | +| Design complete | N/A | Write to docs/plans/ | + +## Common Issues + +### Issue: Brainstorming runs every loop + +**Solution**: Updated in v0.1.0. Brainstorming now checks for existing design.md and auto-skips in autonomous mode. + +### Issue: Losing context between loops + +**Solution**: Use manus-planning instead of writing-plans/executing-plans. Manus files persist across loops. + +### Issue: Ralph exits too early + +**Solution**: Ensure PROMPT.md clearly defines EXIT_SIGNAL conditions. Use verification-before-completion before claiming done. + +### Issue: Skills expect user interaction + +**Solution**: Most skills now detect autonomous mode. If issues persist, adjust PROMPT.md to guide autonomous behavior. + +## Advanced: Custom PROMPT.md Patterns + +### Pattern: Conditional Planning + +```markdown +# Choose planning system based on task complexity + +If task requires >50 tool calls OR spans multiple sessions: + - Use superpowers-ng:manus-planning +Else: + - Use superpowers-ng:writing-plans + superpowers-ng:executing-plans +``` + +### Pattern: Phased Approach + +```markdown +# Phase-based workflow + +Phase 1 - Design (once): + - Check for design.md + - If missing: superpowers-ng:brainstorming + +Phase 2 - Planning (once): + - superpowers-ng:manus-planning or writing-plans + +Phase 3 - Implementation (every loop): + - superpowers-ng:test-driven-development + - Update @fix_plan.md as tasks complete + +Phase 4 - Completion: + - superpowers-ng:verification-before-completion + - Emit EXIT_SIGNAL: true +``` + +## Testing Your Integration + +1. **Create test project**: + ```bash + ralph-setup test-superpowers + cd test-superpowers + cp /path/to/PROMPT.template.md PROMPT.md + ``` + +2. **Add simple task to @fix_plan.md**: + ```markdown + - [ ] Create hello world function with tests + ``` + +3. **Run Ralph with monitoring**: + ```bash + ralph --monitor + ``` + +4. **Verify behavior**: + - Loop 1: Should run brainstorming, create design.md + - Loop 2: Should skip brainstorming, resume manus-planning + - Final: Should emit EXIT_SIGNAL: true when complete + +## Resources + +- **Ralph**: https://github.com/frankbria/ralph-claude-code +- **Superpowers-NG**: https://github.com/OniReimu/superpowers-ng +- **Template**: See `PROMPT.template.md` in this directory +- **Issues**: Report integration issues at https://github.com/OniReimu/superpowers-ng/issues + +## Contributing + +Found a better integration pattern? Please share: +1. Test it with Ralph +2. Document the approach +3. Submit a PR with your improved PROMPT.template.md diff --git a/hooks/hooks.json b/hooks/hooks.json index d1745650c..83b7b0a70 100644 --- a/hooks/hooks.json +++ b/hooks/hooks.json @@ -10,6 +10,17 @@ } ] } + ], + "PreToolUse": [ + { + "matcher": "Write|Edit|Bash", + "hooks": [ + { + "type": "command", + "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" manus-pretool.sh" + } + ] + } ] } } diff --git a/hooks/manus-pretool.sh b/hooks/manus-pretool.sh new file mode 100755 index 000000000..82aad24cd --- /dev/null +++ b/hooks/manus-pretool.sh @@ -0,0 +1,55 @@ +#!/usr/bin/env bash +# PreToolUse hook for manus-planning skill +# Only outputs reminder if manus-planning is active (marker file exists) + +set -euo pipefail + +# Get the working directory (where the user's project is) +# The hook runs from the plugin directory, so we need to find the actual working directory +WORKING_DIR="${PWD}" + +MARKER_FILE="${WORKING_DIR}/docs/manus/.active" +PLAN_FILE="${WORKING_DIR}/docs/manus/task_plan.md" + +# Check if manus-planning is active +if [ ! -f "$MARKER_FILE" ] || [ ! -f "$PLAN_FILE" ]; then + # Not active - output empty JSON, hook passes silently + echo '{}' + exit 0 +fi + +# Manus planning is active - read and output plan preview + +# Escape content for JSON using pure bash +escape_for_json() { + local input="$1" + local output="" + local i char + for (( i=0; i<${#input}; i++ )); do + char="${input:$i:1}" + case "$char" in + $'\\') output+='\\';; + '"') output+='\"';; + $'\n') output+='\n';; + $'\r') output+='\r';; + $'\t') output+='\t';; + *) output+="$char";; + esac + done + printf '%s' "$output" +} + +# Read first 30 lines of task_plan.md +plan_preview=$(head -30 "$PLAN_FILE" 2>/dev/null || echo "Error reading plan file") +plan_escaped=$(escape_for_json "$plan_preview") + +# Output as additionalContext +cat <\nYou have superpowers.\n\n**Below is the full content of your 'superpowers:using-superpowers' skill - your introduction to using skills. For all other skills, use the 'Skill' tool:**\n\n${using_superpowers_escaped}\n\n${warning_escaped}\n" + "additionalContext": "\nYou have superpowers.\n\n**Below is the full content of your 'superpowers-ng:using-superpowers' skill - your introduction to using skills. For all other skills, use the 'Skill' tool:**\n\n${using_superpowers_escaped}\n\n${warning_escaped}\n" } } EOF diff --git a/lib/skills-core.js b/lib/skills-core.js index 5e5bb7012..7d37e0516 100644 --- a/lib/skills-core.js +++ b/lib/skills-core.js @@ -100,17 +100,17 @@ function findSkillsInDir(dir, sourceType, maxDepth = 3) { * Resolve a skill name to its file path, handling shadowing * (personal skills override superpowers skills). * - * @param {string} skillName - Name like "superpowers:brainstorming" or "my-skill" + * @param {string} skillName - Name like "superpowers-ng:brainstorming" or "my-skill" * @param {string} superpowersDir - Path to superpowers skills directory * @param {string} personalDir - Path to personal skills directory * @returns {{skillFile: string, sourceType: string, skillPath: string} | null} */ function resolveSkillPath(skillName, superpowersDir, personalDir) { - // Strip superpowers: prefix if present - const forceSuperpowers = skillName.startsWith('superpowers:'); - const actualSkillName = forceSuperpowers ? skillName.replace(/^superpowers:/, '') : skillName; + // Strip superpowers-ng: prefix if present + const forceSuperpowers = skillName.startsWith('superpowers-ng:'); + const actualSkillName = forceSuperpowers ? skillName.replace(/^superpowers-ng:/, '') : skillName; - // Try personal skills first (unless explicitly superpowers:) + // Try personal skills first (unless explicitly superpowers-ng:) if (!forceSuperpowers && personalDir) { const personalPath = path.join(personalDir, actualSkillName); const personalSkillFile = path.join(personalPath, 'SKILL.md'); diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md index 2fd19ba1e..781621ba1 100644 --- a/skills/brainstorming/SKILL.md +++ b/skills/brainstorming/SKILL.md @@ -13,19 +13,40 @@ Start by understanding the current project context, then ask questions one at a ## The Process -**Understanding the idea:** +**Phase 0: Check for Existing Design** + +Before starting brainstorming, check for existing design files: +- `docs/plans/*-design.md` (typical location) +- `design.md` (root directory) +- `docs/design.md` (alternate location) +- `docs/manus/findings.md` (if manus-planning was used, check "## Design Document" section) + +If design exists: +- Read the existing design +- Announce: "Found existing design at [path]" +- **Interactive mode**: Ask "Should I: 1) Use existing design and proceed to implementation 2) Refine/update it 3) Start fresh design" +- **Autonomous mode** (e.g., Ralph loops): Automatically use existing design and skip to "After the Design" → Implementation phase +- Based on choice/mode: + - **Option 1 / Autonomous**: Skip to "After the Design" → Implementation phase + - **Option 2**: Load existing design, ask targeted refinement questions + - **Option 3**: Archive old design, proceed with fresh brainstorming + +If no design exists: +- Continue with Phase 1 (Understanding the idea) + +**Phase 1: Understanding the idea** - Check out the current project state first (files, docs, recent commits) - Ask questions one at a time to refine the idea - Prefer multiple choice questions when possible, but open-ended is fine too - Only one question per message - if a topic needs more exploration, break it into multiple questions - Focus on understanding: purpose, constraints, success criteria -**Exploring approaches:** +**Phase 2: Exploring approaches** - Propose 2-3 different approaches with trade-offs - Present options conversationally with your recommendation and reasoning - Lead with your recommended option and explain why -**Presenting the design:** +**Phase 3: Presenting the design** - Once you believe you understand what you're building, present the design - Break it into sections of 200-300 words - Ask after each section whether it looks right so far @@ -41,8 +62,13 @@ Start by understanding the current project context, then ask questions one at a **Implementation (if continuing):** - Ask: "Ready to set up for implementation?" -- Use superpowers:using-git-worktrees to create isolated workspace -- Use superpowers:writing-plans to create detailed implementation plan +- Use superpowers-ng:using-git-worktrees to create isolated workspace +- Present planning options: + 1. **Native planning** (writing-plans + executing-plans): Best for short tasks (<30 min), interactive development with human checkpoints + 2. **Manus planning** (manus-planning): Best for long autonomous runs, multi-session projects, tasks requiring persistent memory across context resets +- Based on choice: + - **Native**: Use superpowers-ng:writing-plans to create detailed implementation plan + - **Manus**: Use superpowers-ng:manus-planning (the design document content will be automatically copied into `docs/manus/findings.md` under "## Design Document" section) ## Key Principles diff --git a/skills/executing-plans/SKILL.md b/skills/executing-plans/SKILL.md index ca77290c8..67d303505 100644 --- a/skills/executing-plans/SKILL.md +++ b/skills/executing-plans/SKILL.md @@ -46,7 +46,7 @@ Based on feedback: After all tasks complete and verified: - Announce: "I'm using the finishing-a-development-branch skill to complete this work." -- **REQUIRED SUB-SKILL:** Use superpowers:finishing-a-development-branch +- **REQUIRED SUB-SKILL:** Use superpowers-ng:finishing-a-development-branch - Follow that skill to verify tests, present options, execute choice ## When to Stop and Ask for Help diff --git a/skills/manus-planning/SKILL.md b/skills/manus-planning/SKILL.md new file mode 100644 index 000000000..0fd48d84d --- /dev/null +++ b/skills/manus-planning/SKILL.md @@ -0,0 +1,290 @@ +--- +name: manus-planning +description: Use for complex multi-step tasks requiring persistent memory across context resets, long autonomous runs, or multi-session projects +--- + +# Manus-Style Planning + +## Overview + +Persistent file-based planning for complex tasks. Uses 3 markdown files as external memory that survives context resets, enabling work on tasks that span many tool calls or multiple sessions. + +**Based on:** [planning-with-files](https://github.com/OthmanAdi/planning-with-files) by OthmanAdi + +**Announce at start:** "I'm using the manus-planning skill for persistent tracking." + +**Files location:** `docs/manus/` (tracked in git) + +**When to use this vs native planning:** +- **Native (writing-plans + executing-plans):** Short tasks (<30 min), interactive development with human checkpoints +- **Manus (this skill):** Long autonomous runs, multi-session projects, tasks requiring >50 tool calls + +## The 3 Files + +| File | Purpose | Update Frequency | +|------|---------|------------------| +| `task_plan.md` | Goal, phases, decisions, errors | Before major decisions | +| `findings.md` | Research, requirements, resources | After every 2 search/view operations | +| `progress.md` | Session log, test results, detailed actions | After completing actions | + +## Phase 0: Initialization + +### Existing Task Detection + +Before creating files, check for existing manus task: + +**Case A: No `docs/manus/task_plan.md` exists** +- Fresh start, proceed to file creation + +**Case B: `task_plan.md` exists but NO `.active` marker** +- Previous task was completed +- Auto-archive: Move files to `docs/manus/archive/YYYY-MM-DD-/` +- Log: "Archived completed task to docs/manus/archive/..." +- Proceed to file creation + +**Case C: `task_plan.md` exists AND `.active` marker exists** +- Active task in progress +- **Ask user:** + ``` + There's an active manus task: "[goal from task_plan.md]" + Current phase: [X of 5] + + Is your request: + 1. A continuation of this task (resume where you left off) + 2. A new separate task (archives existing task) + ``` +- If continuation: Skip to Phase 1 (resume work) +- If new task: Archive existing files, then proceed to file creation + +### File Creation + +1. Create `docs/manus/` directory if not exists +2. Create the 3 files from templates (see File Formats below) +3. **If coming from brainstorming:** Copy design document content into `findings.md` under "## Design Document" section +4. Create marker file `docs/manus/.active` (empty file to enable hooks) + +## Phases 1-5: Core Work + +### Phase 1: Requirements & Discovery +- Understand user needs +- Gather information about the codebase +- Document requirements in `findings.md` +- Update `task_plan.md` with refined goal + +### Phase 2: Planning & Structure +- Decide technical approach +- Document decisions in `task_plan.md` Decisions table +- Break work into actionable steps + +### Phase 3: Implementation +- Build the solution +- Can invoke other skills (TDD, debugging, code-review) +- Log actions in `progress.md` +- Log errors in both `task_plan.md` and `progress.md` + +### Phase 4: Testing & Verification +- Run tests, verify functionality +- Document test results in `progress.md` +- Fix any issues found + +### Phase 5: Delivery +- Final review +- Clean up code +- Prepare for handoff + +## Core Rules + +### Rule 1: Plan First +Never begin complex work without `task_plan.md` in place. + +### Rule 2: The 2-Action Rule +After every 2 view/browser/search operations, IMMEDIATELY update `findings.md` with key discoveries. Visual and search results don't persist in context - save them to files. + +### Rule 3: Read Before Deciding +Before major decisions or file modifications, re-read `task_plan.md` to maintain goal focus. The PreToolUse hook helps with this automatically. + +### Rule 4: Update After Acts +After completing actions: +- Mark phase status in `task_plan.md` +- Log action details in `progress.md` +- Note any files modified + +### Rule 5: Log All Errors +Every error goes into: +- `task_plan.md` Errors Encountered section (with resolution) +- `progress.md` Error Log (with timestamp and details) + +## Completion + +When all 5 phases are complete: + +1. Mark all phases as `complete` in `task_plan.md` +2. **Remove marker file:** Delete `docs/manus/.active` +3. **Announce:** "I'm using the finishing-a-development-branch skill to complete this work." +4. **REQUIRED SUB-SKILL:** Use superpowers-ng:finishing-a-development-branch + +## File Formats + +### task_plan.md + +```markdown +# [Task Name] + +**Goal:** [One clear sentence - your north star] + +**Current Phase:** [1-5] - [Phase Name] + +## Phases + +### Phase 1: Requirements & Discovery +- [ ] Understand user requirements +- [ ] Explore relevant codebase areas +- [ ] Document findings + +**Status:** pending | in_progress | complete + +### Phase 2: Planning & Structure +- [ ] Decide technical approach +- [ ] Document key decisions +- [ ] Break into actionable steps + +**Status:** pending | in_progress | complete + +### Phase 3: Implementation +- [ ] [Specific implementation tasks] + +**Status:** pending | in_progress | complete + +### Phase 4: Testing & Verification +- [ ] Run tests +- [ ] Verify functionality +- [ ] Fix issues + +**Status:** pending | in_progress | complete + +### Phase 5: Delivery +- [ ] Final review +- [ ] Clean up +- [ ] Handoff + +**Status:** pending | in_progress | complete + +## Key Questions +- [Important questions to answer during the task] + +## Decisions Made + +| Decision | Rationale | Date | +|----------|-----------|------| +| | | | + +## Errors Encountered + +| Error | Attempts | Resolution | +|-------|----------|------------| +| | | | + +## Notes +- Remember to update phase status as you progress +- Re-read this file before major decisions +- Log all errors for future reference +``` + +### findings.md + +```markdown +# Findings + +## Requirements +[What the user requested - specific requirements] + +## Design Document +[If coming from brainstorming, design content goes here] + +## Research Findings +[Key discoveries from exploration, web searches, documentation] + +## Technical Decisions +[Architecture and implementation choices with reasoning] + +## Issues Encountered +[Problems and their resolutions - broader than coding errors] + +## Resources +- [Useful URLs] +- [File paths] +- [API references] +- [Documentation links] + +## Visual/Browser Findings +[CRITICAL: Information learned from images, PDFs, browser results - this content doesn't persist in context, save it here immediately] +``` + +### progress.md + +```markdown +# Progress Log + +## Session: [Date] + +### Phase 1: Requirements & Discovery +**Status:** pending | in_progress | complete +**Started:** [timestamp] + +**Actions:** +- [What was done] + +**Files Modified:** +- [List of files] + +### Phase 2: Planning & Structure +**Status:** pending | in_progress | complete +**Started:** [timestamp] + +**Actions:** +- [What was done] + +**Files Modified:** +- [List of files] + +[Continue for each phase...] + +## Test Results + +| Test | Expected | Actual | Pass/Fail | +|------|----------|--------|-----------| +| | | | | + +## Error Log + +| Timestamp | Error | Resolution | +|-----------|-------|------------| +| | | | + +## 5-Question Reboot Check +Use these questions to resume after context reset: + +1. **Where am I?** [Current phase] +2. **Where am I going?** [Remaining phases] +3. **What's the goal?** [From task_plan.md] +4. **What have I learned?** [Key findings] +5. **What have I done?** [Completed actions] +``` + +## Context Reset Recovery + +If context is cleared or compacted mid-task: + +1. Read `docs/manus/task_plan.md` for goal and current phase +2. Read `docs/manus/progress.md` for what's been done +3. Read `docs/manus/findings.md` for research and decisions +4. Answer the 5-Question Reboot Check +5. Resume from current phase + +## Remember + +- Files are your external memory - use them +- Update frequently, not in batches +- The 2-Action Rule prevents losing research +- PreToolUse hook reminds you of the plan automatically +- Stop and ask when blocked, don't guess diff --git a/skills/manus-planning/examples.md b/skills/manus-planning/examples.md new file mode 100644 index 000000000..e3a33b90c --- /dev/null +++ b/skills/manus-planning/examples.md @@ -0,0 +1,443 @@ +# Manus Planning Examples + +This document demonstrates planning patterns for managing multi-step tasks through persistent file-based workflows in **Superpowers-NG**. + +## Core Pattern + +All examples follow the 3-file pattern under `docs/manus/`: +- `task_plan.md` — Goal, phases, decisions, errors +- `findings.md` — Research, requirements, resources +- `progress.md` — Session log, test results, detailed actions +- `.active` — Marker file that enables pre-tool reminder hook + +## Examples + +### Example 1: Greenfield Feature Build - CLI Todo App + +**User request:** "Build a simple command-line todo app in Python that can add, list, and delete tasks." + +This lightweight walkthrough shows how the 3 files evolve together during a real task. + +#### Phase 0: Initialization + +Create the Manus planning files under `docs/manus/` and enable the marker file: +- `docs/manus/task_plan.md` +- `docs/manus/findings.md` +- `docs/manus/progress.md` +- `docs/manus/.active` + +At this point, the pre-tool hook should start reminding you to review the plan before actions. + +#### Phase 1: Requirements & Discovery + +**docs/manus/findings.md** (requirements captured) + +```md +# Findings + +## Requirements +- Python CLI application +- Commands: add, list, delete +- Tasks persist between runs (file-based storage) +- Keep it simple (stdlib preferred) + +## Research Findings +- Python stdlib: argparse for CLI +- JSON file storage is good enough for a small example +``` + +**docs/manus/task_plan.md** (phase stays in_progress) + +```md +# CLI Todo App (Python) + +**Goal:** Implement a Python CLI todo app with add/list/delete and persistence. + +**Current Phase:** 1 - Requirements & Discovery + +### Phase 1: Requirements & Discovery +- [x] Understand user requirements +- [x] Identify persistence requirement (tasks survive restart) +- [x] Document findings + +**Status:** in_progress +``` + +**docs/manus/progress.md** (log actions taken) + +```md +# Progress Log + +## Session: 2026-01-13 + +### Phase 1: Requirements & Discovery +**Status:** in_progress +**Started:** 2026-01-13 14:05 + +**Actions:** +- Captured requirements in findings.md +- Confirmed persistence requirement and likely storage format +``` + +#### Phase 2: Planning & Structure + +In Phase 2 you make and record the key technical decisions, then break work into concrete steps. + +**docs/manus/task_plan.md** (phase 1 complete, phase 2 in_progress) + +```md +**Current Phase:** 2 - Planning & Structure + +### Phase 1: Requirements & Discovery +... +**Status:** complete + +### Phase 2: Planning & Structure +- [ ] Decide technical approach +- [ ] Document key decisions +- [ ] Break into actionable steps + +**Status:** in_progress + +## Decisions Made +| Decision | Rationale | Date | +|----------|-----------|------| +| Use `argparse` subcommands | Clear CLI UX, stdlib | 2026-01-13 | +| Store tasks in `todos.json` | Simple persistence, debuggable | 2026-01-13 | +``` + +**docs/manus/findings.md** (decision rationale stays easy to find) + +```md +## Technical Decisions +- CLI: `argparse` with subcommands (`add`, `list`, `delete`) +- Storage: `todos.json` in the project root (or configurable path) +``` + +#### Phase 3: Implementation + +Implementation work happens here, but the key Manus behavior is that you keep `progress.md` up to date and record any mistakes. + +**docs/manus/progress.md** (files modified and errors logged) + +```md +### Phase 3: Implementation +**Status:** in_progress +**Started:** 2026-01-13 15:10 + +**Actions:** +- Implemented `add` command and JSON persistence +- Implemented `list` command + +**Files Modified:** +- `todo.py` +- `todos.json` (created during manual testing) + +## Error Log +| Timestamp | Error | Resolution | +|-----------|-------|------------| +| 2026-01-13 15:22 | JSON decode error on empty file | Treat empty/missing file as `[]` | +``` + +#### Phase 4: Testing & Verification + +Record how you verified the behavior, not just that you "tested it". + +**docs/manus/progress.md** (test results table filled) + +```md +## Test Results + +| Test | Expected | Actual | Pass/Fail | +|------|----------|--------|-----------| +| Add task | Task persisted to JSON | OK | Pass | +| List tasks | Shows all tasks | OK | Pass | +| Delete task | Removes correct entry | OK | Pass | +``` + +#### Phase 5: Delivery + +Final sanity pass: update `task_plan.md` phases to `complete`, then: + +1. **Remove marker file:** Delete `docs/manus/.active` +2. **Use finishing-a-development-branch skill:** + ``` + I'm using the finishing-a-development-branch skill to complete this work. + ``` +3. The skill will verify tests, present options (merge locally, create PR, keep as-is, discard), and handle worktree cleanup + +--- + +### Example 2: Bug Fix with Root Cause Analysis + +**User request:** "Users can't log in - fix the authentication bug." + +This example shows tracking decisions and errors during debugging. + +#### Phase 1: Requirements & Discovery + +**docs/manus/findings.md** + +```md +# Findings + +## Requirements +- Fix login authentication issue +- Users report "Invalid credentials" even with correct password +- Reproduce the bug first + +## Research Findings +- Bug occurs only for users created after 2026-01-10 +- Authentication uses JWT tokens +- Password hashing: bcrypt +``` + +**docs/manus/task_plan.md** + +```md +# Fix Login Authentication Bug + +**Goal:** Identify and fix authentication failure for new users. + +**Current Phase:** 1 - Requirements & Discovery + +### Phase 1: Requirements & Discovery +- [x] Reproduce the bug +- [x] Identify affected user cohort +- [x] Review authentication flow + +**Status:** complete + +## Key Questions +- Why only users created after 2026-01-10? +- What changed in user creation around that date? +``` + +#### Phase 2: Planning & Structure + +**docs/manus/task_plan.md** + +```md +**Current Phase:** 2 - Planning & Structure + +### Phase 2: Planning & Structure +- [x] Identify root cause +- [x] Plan the fix +- [ ] Document decision + +**Status:** in_progress + +## Decisions Made +| Decision | Rationale | Date | +|----------|-----------|------| +| Root cause: bcrypt salt rounds changed from 10 to 12 | Config change didn't update password validation logic | 2026-01-13 | +| Fix: Update validation to detect salt rounds from hash | Backwards compatible with old users | 2026-01-13 | +``` + +#### Phase 3: Implementation + +**docs/manus/progress.md** + +```md +### Phase 3: Implementation +**Status:** complete +**Started:** 2026-01-13 16:15 + +**Actions:** +- Modified auth/password.js to auto-detect salt rounds from hash +- Updated tests to cover both old and new users + +**Files Modified:** +- `auth/password.js` +- `tests/auth.test.js` + +## Error Log +| Timestamp | Error | Resolution | +|-----------|-------|------------| +| 2026-01-13 16:22 | Test suite failed: missing mock data | Added user fixtures for both salt configurations | +``` + +#### Phase 5: Delivery + +All phases marked `complete`, `.active` file removed, `finishing-a-development-branch` skill invoked. + +--- + +### Example 3: Research Task Pattern + +**User request:** "Research the benefits of morning exercise and create a summary document." + +This demonstrates the **four-loop workflow**: plan → research → synthesize → deliver. + +#### The Read-Before-Decide Pattern + +For research tasks, periodically refresh context by re-reading your task plan. This enables coherent management of complex tasks across ~50 tool calls without losing sight of objectives. + +**Loop structure:** +1. Read `task_plan.md` to refresh goal +2. Execute 2-3 research operations +3. Update `findings.md` immediately (Rule 2: The 2-Action Rule) +4. Return to step 1 + +#### Phase 1: Requirements & Discovery + +**docs/manus/task_plan.md** + +```md +# Morning Exercise Research + +**Goal:** Research benefits of morning exercise and create a summary document. + +**Current Phase:** 1 - Requirements & Discovery + +### Phase 1: Requirements & Discovery +- [x] Clarify scope (scientific studies vs anecdotal) +- [x] Identify key research areas + +**Status:** complete +``` + +#### Phase 2: Planning & Structure + +**docs/manus/task_plan.md** + +```md +### Phase 2: Planning & Structure +- [x] Break into research areas: cardiovascular, cognitive, metabolic +- [x] Plan document structure + +**Status:** complete + +## Key Questions +- What time counts as "morning"? +- Compare morning vs evening exercise benefits? +``` + +#### Phase 3: Implementation (Research) + +**docs/manus/findings.md** (updated after every 2 search operations) + +```md +# Findings + +## Research Findings + +### Cardiovascular Benefits +- Study (2024): Morning exercise (6-8am) shows 15% improvement in blood pressure regulation +- Fasting morning cardio increases fat oxidation by 20% + +### Cognitive Benefits +- Morning exercise boosts alertness and focus for 4-6 hours post-workout +- Releases BDNF (brain-derived neurotrophic factor) + +### Metabolic Benefits +- Morning exercise kickstarts metabolism for the day +- Better insulin sensitivity throughout the day + +## Visual/Browser Findings +[Screenshot notes from medical research papers] +``` + +**Key behavior:** Update `findings.md` immediately after research operations - visual and search results don't persist in context. + +#### Phase 4: Testing & Verification + +For research tasks, verification means: +- Cross-reference sources +- Verify all key questions answered +- Check document completeness + +#### Phase 5: Delivery + +Deliverable: `morning-exercise-benefits.md` + +Remove `.active`, invoke `finishing-a-development-branch` for final handling. + +--- + +### Example 4: Error Recovery Pattern + +This shows the CORRECT way to handle errors vs the WRONG way. + +#### ❌ WRONG: Silent Retries Without Documentation + +```md +# What NOT to do + +## Progress Log +**Actions:** +- Tried to implement feature +- It worked + +[No mention of 3 failed attempts, workarounds, or what was learned] +``` + +**Problem:** Next time you encounter the same error, you won't remember the solution. + +#### ✅ CORRECT: Document Everything + +**docs/manus/task_plan.md** + +```md +## Errors Encountered + +| Error | Attempts | Resolution | +|-------|----------|------------| +| `EACCES` permission denied | 3 | Needed to run with sudo - added to docs | +| Test timeout on CI | 2 | Increased Jest timeout from 5s to 10s | +``` + +**docs/manus/progress.md** + +```md +## Error Log + +| Timestamp | Error | Resolution | +|-----------|-------|------------| +| 2026-01-13 14:22 | EACCES writing to /usr/local | Changed install path to ~/.local | +| 2026-01-13 14:35 | Jest timeout | Updated jest.config.js timeout | +``` + +**Benefit:** Both files now contain the institutional memory. If context resets or another agent encounters the same issue, the solution is documented. + +--- + +## Key Patterns Summary + +### 1. The 2-Action Rule +After every 2 view/browser/search operations, IMMEDIATELY update `findings.md`. Visual and search results don't persist in context - save them to files. + +### 2. Read Before Deciding +Before major decisions or file modifications, re-read `task_plan.md` to maintain goal focus. The PreToolUse hook helps with this automatically. + +### 3. Error Logging +Every error goes into BOTH: +- `task_plan.md` Errors Encountered section (with resolution) +- `progress.md` Error Log (with timestamp and details) + +### 4. Phase Completion +Mark phases complete in real-time, not in batches. When all 5 phases are complete: +1. Remove `docs/manus/.active` +2. Invoke `finishing-a-development-branch` skill + +### 5. Superpowers-NG Integration +Manus planning integrates with the broader superpowers ecosystem: +- Can invoke other skills during Phase 3 (TDD, debugging, code-review) +- Completion flows through `finishing-a-development-branch` +- Manual control over phase progression (no automatic enforcement) + +--- + +## Superpowers-NG vs Upstream Differences + +**Upstream (planning-with-files):** +- Uses Stop hook with automatic completion verification +- Prevents stopping until all phases complete +- Standalone workflow + +**Superpowers-NG (manus-planning):** +- Manual phase completion +- Integrates with `finishing-a-development-branch` for final delivery +- Part of larger skills ecosystem +- More flexible control over completion timing +- Pre-tool reminder hook keeps plan visible without enforcement diff --git a/skills/manus-planning/templates/findings.md b/skills/manus-planning/templates/findings.md new file mode 100644 index 000000000..9b9c07281 --- /dev/null +++ b/skills/manus-planning/templates/findings.md @@ -0,0 +1,25 @@ +# Findings + +## Requirements +[What the user requested - document specific requirements here] + +## Design Document +[If coming from brainstorming, the design content will be copied here] + +## Research Findings +[Key discoveries from exploration, web searches, documentation] + +## Technical Decisions +[Architecture and implementation choices with reasoning] + +## Issues Encountered +[Problems discovered and their resolutions - broader challenges beyond coding errors] + +## Resources +- [Useful URLs] +- [File paths] +- [API references] +- [Documentation links] + +## Visual/Browser Findings +[CRITICAL: Information learned from images, PDFs, browser results - this content doesn't persist in context, save it here immediately after viewing] diff --git a/skills/manus-planning/templates/progress.md b/skills/manus-planning/templates/progress.md new file mode 100644 index 000000000..b89bc633d --- /dev/null +++ b/skills/manus-planning/templates/progress.md @@ -0,0 +1,84 @@ +# Progress Log + +## Session: [Date] + +### Phase 1: Requirements & Discovery +**Status:** in_progress +**Started:** [timestamp] + +**Actions:** +- [What was done] + +**Files Modified:** +- [List of files] + +--- + +### Phase 2: Planning & Structure +**Status:** pending +**Started:** + +**Actions:** +- + +**Files Modified:** +- + +--- + +### Phase 3: Implementation +**Status:** pending +**Started:** + +**Actions:** +- + +**Files Modified:** +- + +--- + +### Phase 4: Testing & Verification +**Status:** pending +**Started:** + +**Actions:** +- + +**Files Modified:** +- + +--- + +### Phase 5: Delivery +**Status:** pending +**Started:** + +**Actions:** +- + +**Files Modified:** +- + +--- + +## Test Results + +| Test | Expected | Actual | Pass/Fail | +|------|----------|--------|-----------| +| | | | | + +## Error Log + +| Timestamp | Error | Resolution | +|-----------|-------|------------| +| | | | + +## 5-Question Reboot Check +Use these questions to resume after context reset: + +1. **Where am I?** Phase 1 - Requirements & Discovery +2. **Where am I going?** Phases 2-5 remaining +3. **What's the goal?** [Copy from task_plan.md] +4. **What have I learned?** [Key findings so far] +5. **What have I done?** [Completed actions] diff --git a/skills/manus-planning/templates/task_plan.md b/skills/manus-planning/templates/task_plan.md new file mode 100644 index 000000000..81175890a --- /dev/null +++ b/skills/manus-planning/templates/task_plan.md @@ -0,0 +1,60 @@ +# [Task Name] + +**Goal:** [One clear sentence - your north star] + +**Current Phase:** 1 - Requirements & Discovery + +## Phases + +### Phase 1: Requirements & Discovery +- [ ] Understand user requirements +- [ ] Explore relevant codebase areas +- [ ] Document findings + +**Status:** in_progress + +### Phase 2: Planning & Structure +- [ ] Decide technical approach +- [ ] Document key decisions +- [ ] Break into actionable steps + +**Status:** pending + +### Phase 3: Implementation +- [ ] [Specific implementation tasks - fill in during Phase 2] + +**Status:** pending + +### Phase 4: Testing & Verification +- [ ] Run tests +- [ ] Verify functionality +- [ ] Fix issues + +**Status:** pending + +### Phase 5: Delivery +- [ ] Final review +- [ ] Clean up +- [ ] Handoff + +**Status:** pending + +## Key Questions +- [Important questions to answer during the task] + +## Decisions Made + +| Decision | Rationale | Date | +|----------|-----------|------| +| | | | + +## Errors Encountered + +| Error | Attempts | Resolution | +|-------|----------|------------| +| | | | + +## Notes +- Remember to update phase status as you progress +- Re-read this file before major decisions +- Log all errors for future reference diff --git a/skills/requesting-code-review/SKILL.md b/skills/requesting-code-review/SKILL.md index f0e33952c..5127e919c 100644 --- a/skills/requesting-code-review/SKILL.md +++ b/skills/requesting-code-review/SKILL.md @@ -5,7 +5,7 @@ description: Use when completing tasks, implementing major features, or before m # Requesting Code Review -Dispatch superpowers:code-reviewer subagent to catch issues before they cascade. +Dispatch superpowers-ng:code-reviewer subagent to catch issues before they cascade. **Core principle:** Review early, review often. @@ -31,7 +31,7 @@ HEAD_SHA=$(git rev-parse HEAD) **2. Dispatch code-reviewer subagent:** -Use Task tool with superpowers:code-reviewer type, fill template at `code-reviewer.md` +Use Task tool with superpowers-ng:code-reviewer type, fill template at `code-reviewer.md` **Placeholders:** - `{WHAT_WAS_IMPLEMENTED}` - What you just built @@ -56,7 +56,7 @@ You: Let me request code review before proceeding. BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}') HEAD_SHA=$(git rev-parse HEAD) -[Dispatch superpowers:code-reviewer subagent] +[Dispatch superpowers-ng:code-reviewer subagent] WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index PLAN_OR_REQUIREMENTS: Task 2 from docs/plans/deployment-plan.md BASE_SHA: a7981ec diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md index a9a94547a..facb40e61 100644 --- a/skills/subagent-driven-development/SKILL.md +++ b/skills/subagent-driven-development/SKILL.md @@ -59,7 +59,7 @@ digraph process { "Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box]; "More tasks remain?" [shape=diamond]; "Dispatch final code reviewer subagent for entire implementation" [shape=box]; - "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen]; + "Use superpowers-ng:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen]; "Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Dispatch implementer subagent (./implementer-prompt.md)"; "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?"; @@ -78,7 +78,7 @@ digraph process { "Mark task complete in TodoWrite" -> "More tasks remain?"; "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"]; "More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"]; - "Dispatch final code reviewer subagent for entire implementation" -> "Use superpowers:finishing-a-development-branch"; + "Dispatch final code reviewer subagent for entire implementation" -> "Use superpowers-ng:finishing-a-development-branch"; } ``` @@ -229,12 +229,12 @@ Done! ## Integration **Required workflow skills:** -- **superpowers:writing-plans** - Creates the plan this skill executes -- **superpowers:requesting-code-review** - Code review template for reviewer subagents -- **superpowers:finishing-a-development-branch** - Complete development after all tasks +- **superpowers-ng:writing-plans** - Creates the plan this skill executes +- **superpowers-ng:requesting-code-review** - Code review template for reviewer subagents +- **superpowers-ng:finishing-a-development-branch** - Complete development after all tasks **Subagents should use:** -- **superpowers:test-driven-development** - Subagents follow TDD for each task +- **superpowers-ng:test-driven-development** - Subagents follow TDD for each task **Alternative workflow:** -- **superpowers:executing-plans** - Use for parallel session instead of same-session execution +- **superpowers-ng:executing-plans** - Use for parallel session instead of same-session execution diff --git a/skills/subagent-driven-development/code-quality-reviewer-prompt.md b/skills/subagent-driven-development/code-quality-reviewer-prompt.md index d029ea299..e0cb4e7cc 100644 --- a/skills/subagent-driven-development/code-quality-reviewer-prompt.md +++ b/skills/subagent-driven-development/code-quality-reviewer-prompt.md @@ -7,7 +7,7 @@ Use this template when dispatching a code quality reviewer subagent. **Only dispatch after spec compliance review passes.** ``` -Task tool (superpowers:code-reviewer): +Task tool (superpowers-ng:code-reviewer): Use template at requesting-code-review/code-reviewer.md WHAT_WAS_IMPLEMENTED: [from implementer's report] diff --git a/skills/systematic-debugging/SKILL.md b/skills/systematic-debugging/SKILL.md index 111d2a98c..c8de4c1e3 100644 --- a/skills/systematic-debugging/SKILL.md +++ b/skills/systematic-debugging/SKILL.md @@ -176,7 +176,7 @@ You MUST complete each phase before proceeding to the next. - Automated test if possible - One-off test script if no framework - MUST have before fixing - - Use the `superpowers:test-driven-development` skill for writing proper failing tests + - Use the `superpowers-ng:test-driven-development` skill for writing proper failing tests 2. **Implement Single Fix** - Address the root cause identified @@ -284,8 +284,8 @@ These techniques are part of systematic debugging and available in this director - **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling **Related skills:** -- **superpowers:test-driven-development** - For creating failing test case (Phase 4, Step 1) -- **superpowers:verification-before-completion** - Verify fix worked before claiming success +- **superpowers-ng:test-driven-development** - For creating failing test case (Phase 4, Step 1) +- **superpowers-ng:verification-before-completion** - Verify fix worked before claiming success ## Real-World Impact diff --git a/skills/using-superpowers/SKILL.md b/skills/using-superpowers/SKILL.md index 7867fcfc0..1f94e82a0 100644 --- a/skills/using-superpowers/SKILL.md +++ b/skills/using-superpowers/SKILL.md @@ -82,6 +82,19 @@ When multiple skills could apply, use this order: The skill itself tells you which. +## Planning Approaches + +Two planning systems exist—choose based on task complexity: + +| Approach | Skills | Best For | +|----------|--------|----------| +| **Native** | writing-plans + executing-plans | Short tasks (<30 min), interactive development with human checkpoints | +| **Manus** | manus-planning | Long autonomous runs, multi-session projects, tasks requiring >50 tool calls | + +**Key difference:** Native uses in-memory TodoWrite for progress. Manus uses persistent files (`docs/manus/`) that survive context resets. + +**When unsure:** If the task feels complex or might span multiple sessions, prefer Manus. + ## User Instructions Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows. diff --git a/skills/writing-plans/SKILL.md b/skills/writing-plans/SKILL.md index 448ca3193..bf8d87a64 100644 --- a/skills/writing-plans/SKILL.md +++ b/skills/writing-plans/SKILL.md @@ -33,7 +33,7 @@ Assume they are a skilled developer, but know almost nothing about our toolset o ```markdown # [Feature Name] Implementation Plan -> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers-ng:executing-plans to implement this plan task-by-task. **Goal:** [One sentence describing what this builds] @@ -107,10 +107,10 @@ After saving the plan, offer execution choice: **Which approach?"** **If Subagent-Driven chosen:** -- **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development +- **REQUIRED SUB-SKILL:** Use superpowers-ng:subagent-driven-development - Stay in this session - Fresh subagent per task + code review **If Parallel Session chosen:** - Guide them to open new session in worktree -- **REQUIRED SUB-SKILL:** New session uses superpowers:executing-plans +- **REQUIRED SUB-SKILL:** New session uses superpowers-ng:executing-plans diff --git a/skills/writing-skills/SKILL.md b/skills/writing-skills/SKILL.md index c60f18a4e..f2479079a 100644 --- a/skills/writing-skills/SKILL.md +++ b/skills/writing-skills/SKILL.md @@ -15,7 +15,7 @@ You write test cases (pressure scenarios with subagents), watch them fail (basel **Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing. -**REQUIRED BACKGROUND:** You MUST understand superpowers:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation. +**REQUIRED BACKGROUND:** You MUST understand superpowers-ng:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation. **Official guidance:** For Anthropic's official skill authoring best practices, see anthropic-best-practices.md. This document provides additional patterns and guidelines that complement the TDD-focused approach in this skill. @@ -280,8 +280,8 @@ wc -w skills/path/SKILL.md **When writing documentation that references other skills:** Use skill name only, with explicit requirement markers: -- ✅ Good: `**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development` -- ✅ Good: `**REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debugging` +- ✅ Good: `**REQUIRED SUB-SKILL:** Use superpowers-ng:test-driven-development` +- ✅ Good: `**REQUIRED BACKGROUND:** You MUST understand superpowers-ng:systematic-debugging` - ❌ Bad: `See skills/testing/test-driven-development` (unclear if required) - ❌ Bad: `@skills/testing/test-driven-development/SKILL.md` (force-loads, burns context) @@ -390,7 +390,7 @@ Edit skill without testing? Same violation. - Don't "adapt" while running tests - Delete means delete -**REQUIRED BACKGROUND:** The superpowers:test-driven-development skill explains why this matters. Same principles apply to documentation. +**REQUIRED BACKGROUND:** The superpowers-ng:test-driven-development skill explains why this matters. Same principles apply to documentation. ## Testing All Skill Types diff --git a/skills/writing-skills/testing-skills-with-subagents.md b/skills/writing-skills/testing-skills-with-subagents.md index 9b12f3bb8..6b4d33a7a 100644 --- a/skills/writing-skills/testing-skills-with-subagents.md +++ b/skills/writing-skills/testing-skills-with-subagents.md @@ -10,7 +10,7 @@ You run scenarios without the skill (RED - watch agent fail), write skill addres **Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill prevents the right failures. -**REQUIRED BACKGROUND:** You MUST understand superpowers:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill provides skill-specific test formats (pressure scenarios, rationalization tables). +**REQUIRED BACKGROUND:** You MUST understand superpowers-ng:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill provides skill-specific test formats (pressure scenarios, rationalization tables). **Complete worked example:** See examples/CLAUDE_MD_TESTING.md for a full test campaign testing CLAUDE.md documentation variants. diff --git a/tests/claude-code/README.md b/tests/claude-code/README.md index e53647ba1..28466d599 100644 --- a/tests/claude-code/README.md +++ b/tests/claude-code/README.md @@ -10,6 +10,8 @@ This test suite verifies that skills are loaded correctly and Claude follows the - Claude Code CLI installed and in PATH (`claude --version` should work) - Local superpowers plugin installed (see main README for installation) +- Optional: `timeout` command for integration tests (install with `brew install coreutils` on macOS) + - Integration tests will skip gracefully if timeout is not available ## Running Tests @@ -18,7 +20,7 @@ This test suite verifies that skills are loaded correctly and Claude follows the ./run-skill-tests.sh ``` -### Run integration tests (slow, 10-30 minutes): +### Run integration tests (slow, 10-15 minutes): ```bash ./run-skill-tests.sh --integration ``` @@ -47,6 +49,11 @@ Common functions for skills testing: - `assert_not_contains output pattern name` - Verify pattern absent - `assert_count output pattern count name` - Verify exact count - `assert_order output pattern_a pattern_b name` - Verify order +- `assert_file_exists file name` - Verify file exists +- `assert_file_contains file pattern name` - Verify file contains pattern +- `assert_valid_json json name` - Verify valid JSON string +- `extract_ralph_status output` - Extract Ralph status block +- `verify_ralph_status_block status name` - Verify Ralph status format - `create_test_project` - Create temp test directory - `create_test_plan project_dir` - Create sample plan file @@ -92,6 +99,20 @@ Tests skill content and requirements (~2 minutes): - Review loops documented - Task context provision documented +#### test-manus-pretool-hook.sh +Unit test for manus pretool hook (~1 second): +- Verifies hook outputs valid JSON when inactive +- Verifies hook outputs empty JSON when no .active marker +- Verifies hook emits reminder when .active exists +- Verifies reminder includes plan preview + +#### test-ralph-status-blocks.sh +Unit test for Ralph status block parsing (~1 second): +- Verifies status block extraction from output +- Verifies all required fields present +- Verifies enum values are valid +- Verifies field format correctness + ### Integration Tests (use --integration flag) #### test-subagent-driven-development-integration.sh @@ -115,6 +136,44 @@ Full workflow execution test (~10-30 minutes): - Subagents follow the skill correctly - Final code is functional and tested +#### test-manus-resume-integration.sh +Manus planning session resume test (~4-6 minutes): +- Session 1: Starts manus-planning task, creates files +- Session 2: Resumes task in new session +- Verifies: + - Manus files created (task_plan.md, findings.md, progress.md) + - .active marker controls behavior + - Session resume works across invocations + - .active removed on completion + +#### test-ralph-status-emission-integration.sh +Ralph status block emission test (~2-3 minutes): +- Creates Ralph project with simple task +- Executes task with Ralph-style prompt +- Verifies: + - Status block emitted at end + - All required fields present + - Field values are valid + +#### test-manus-ralph-combined-integration.sh +Combined manus + Ralph workflow test (~2-3 minutes): +- Creates Ralph project +- Starts manus-planning in Ralph loop +- Verifies: + - Manus files created + - Status block emitted + - EXIT_SIGNAL stays false while manus active + - Both systems work together + +### Slim Test Suite + +The new manus/Ralph tests form a slim test suite targeting ~10-15 minutes total runtime: +- 2 fast unit tests (< 1 minute total) +- 3 focused integration tests (10-12 minutes total) +- Tests core superpowers-ng differentiators: + - Manus-styled planning with session persistence + - Ralph loop integration with status blocks + ## Adding New Tests 1. Create new test file: `test-.sh` diff --git a/tests/claude-code/run-skill-tests.sh b/tests/claude-code/run-skill-tests.sh index 3e339fd3d..d37bbefb0 100755 --- a/tests/claude-code/run-skill-tests.sh +++ b/tests/claude-code/run-skill-tests.sh @@ -53,14 +53,19 @@ while [[ $# -gt 0 ]]; do echo " --verbose, -v Show verbose output" echo " --test, -t NAME Run only the specified test" echo " --timeout SECONDS Set timeout per test (default: 300)" - echo " --integration, -i Run integration tests (slow, 10-30 min)" + echo " --integration, -i Run integration tests (slow, 10-15 min)" echo " --help, -h Show this help" echo "" echo "Tests:" - echo " test-subagent-driven-development.sh Test skill loading and requirements" + echo " test-subagent-driven-development.sh Test skill loading and requirements" + echo " test-manus-pretool-hook.sh Test manus pretool hook unit" + echo " test-ralph-status-blocks.sh Test ralph status block parsing" echo "" echo "Integration Tests (use --integration):" echo " test-subagent-driven-development-integration.sh Full workflow execution" + echo " test-manus-resume-integration.sh Manus resume across sessions" + echo " test-ralph-status-emission-integration.sh Ralph status block emission" + echo " test-manus-ralph-combined-integration.sh Manus + Ralph combined" exit 0 ;; *) @@ -74,11 +79,16 @@ done # List of skill tests to run (fast unit tests) tests=( "test-subagent-driven-development.sh" + "test-manus-pretool-hook.sh" + "test-ralph-status-blocks.sh" ) # Integration tests (slow, full execution) integration_tests=( "test-subagent-driven-development-integration.sh" + "test-manus-resume-integration.sh" + "test-ralph-status-emission-integration.sh" + "test-manus-ralph-combined-integration.sh" ) # Add integration tests if requested @@ -117,8 +127,17 @@ for test in "${tests[@]}"; do start_time=$(date +%s) + # Check if timeout command is available + if command -v timeout >/dev/null 2>&1; then + TIMEOUT_CMD="timeout $TIMEOUT" + elif command -v gtimeout >/dev/null 2>&1; then + TIMEOUT_CMD="gtimeout $TIMEOUT" + else + TIMEOUT_CMD="" + fi + if [ "$VERBOSE" = true ]; then - if timeout "$TIMEOUT" bash "$test_path"; then + if $TIMEOUT_CMD bash "$test_path"; then end_time=$(date +%s) duration=$((end_time - start_time)) echo "" @@ -138,7 +157,7 @@ for test in "${tests[@]}"; do fi else # Capture output for non-verbose mode - if output=$(timeout "$TIMEOUT" bash "$test_path" 2>&1); then + if output=$($TIMEOUT_CMD bash "$test_path" 2>&1); then end_time=$(date +%s) duration=$((end_time - start_time)) echo " [PASS] (${duration}s)" @@ -173,7 +192,7 @@ echo " Skipped: $skipped" echo "" if [ "$RUN_INTEGRATION" = false ] && [ ${#integration_tests[@]} -gt 0 ]; then - echo "Note: Integration tests were not run (they take 10-30 minutes)." + echo "Note: Integration tests were not run (they take 10-15 minutes)." echo "Use --integration flag to run full workflow execution tests." echo "" fi diff --git a/tests/claude-code/test-helpers.sh b/tests/claude-code/test-helpers.sh index 16518fdaa..b2ccdbc0c 100755 --- a/tests/claude-code/test-helpers.sh +++ b/tests/claude-code/test-helpers.sh @@ -191,12 +191,92 @@ EOF echo "$plan_file" } +# Check if a file exists +# Usage: assert_file_exists "/path" "test name" +assert_file_exists() { + local file="$1" + local test_name="${2:-test}" + if [ -f "$file" ]; then + echo " [PASS] $test_name" + return 0 + else + echo " [FAIL] $test_name" + echo " Missing file: $file" + return 1 + fi +} + +# Check if file contains a pattern +# Usage: assert_file_contains "/path" "pattern" "test name" +assert_file_contains() { + local file="$1" + local pattern="$2" + local test_name="${3:-test}" + if grep -q "$pattern" "$file"; then + echo " [PASS] $test_name" + return 0 + else + echo " [FAIL] $test_name" + echo " Expected to find: $pattern" + echo " In file: $file" + return 1 + fi +} + +# Validate JSON string +# Usage: assert_valid_json "{...}" "test name" +assert_valid_json() { + local json="$1" + local test_name="${2:-test}" + if echo "$json" | python3 -c 'import json, sys; json.load(sys.stdin)' 2>/dev/null; then + echo " [PASS] $test_name" + return 0 + else + echo " [FAIL] $test_name" + echo " Invalid JSON" + return 1 + fi +} + +# Extract Ralph status block from output +# Usage: extract_ralph_status "output" +extract_ralph_status() { + echo "$1" | sed -n '/---RALPH_STATUS---/,/---END_RALPH_STATUS---/p' +} + +# Verify Ralph status block fields and enums +# Usage: verify_ralph_status_block "status_block" "test name" +verify_ralph_status_block() { + local status="$1" + local test_name="${2:-test}" + + echo "$status" | grep -q "STATUS: " || { echo " [FAIL] $test_name (missing STATUS)"; return 1; } + echo "$status" | grep -q "TASKS_COMPLETED_THIS_LOOP: " || { echo " [FAIL] $test_name (missing TASKS_COMPLETED_THIS_LOOP)"; return 1; } + echo "$status" | grep -q "FILES_MODIFIED: " || { echo " [FAIL] $test_name (missing FILES_MODIFIED)"; return 1; } + echo "$status" | grep -q "TESTS_STATUS: " || { echo " [FAIL] $test_name (missing TESTS_STATUS)"; return 1; } + echo "$status" | grep -q "WORK_TYPE: " || { echo " [FAIL] $test_name (missing WORK_TYPE)"; return 1; } + echo "$status" | grep -q "EXIT_SIGNAL: " || { echo " [FAIL] $test_name (missing EXIT_SIGNAL)"; return 1; } + echo "$status" | grep -q "RECOMMENDATION: " || { echo " [FAIL] $test_name (missing RECOMMENDATION)"; return 1; } + + echo "$status" | grep -Eq "STATUS: (IN_PROGRESS|COMPLETE|BLOCKED)" || { echo " [FAIL] $test_name (bad STATUS)"; return 1; } + echo "$status" | grep -Eq "TESTS_STATUS: (PASSING|FAILING|NOT_RUN)" || { echo " [FAIL] $test_name (bad TESTS_STATUS)"; return 1; } + echo "$status" | grep -Eq "WORK_TYPE: (IMPLEMENTATION|TESTING|DOCUMENTATION|REFACTORING)" || { echo " [FAIL] $test_name (bad WORK_TYPE)"; return 1; } + echo "$status" | grep -Eq "EXIT_SIGNAL: (true|false)" || { echo " [FAIL] $test_name (bad EXIT_SIGNAL)"; return 1; } + + echo " [PASS] $test_name" +} + # Export functions for use in tests export -f run_claude export -f assert_contains export -f assert_not_contains export -f assert_count export -f assert_order +export -f assert_file_exists +export -f assert_file_contains +export -f assert_valid_json +export -f extract_ralph_status +export -f verify_ralph_status_block export -f create_test_project export -f cleanup_test_project export -f create_test_plan diff --git a/tests/claude-code/test-manus-pretool-hook.sh b/tests/claude-code/test-manus-pretool-hook.sh new file mode 100755 index 000000000..085dc4f3b --- /dev/null +++ b/tests/claude-code/test-manus-pretool-hook.sh @@ -0,0 +1,32 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +source "$SCRIPT_DIR/test-helpers.sh" + +echo "=== Test: manus pretool hook ===" + +TEST_PROJECT=$(create_test_project) +trap "cleanup_test_project $TEST_PROJECT" EXIT + +# Case 1: No .active -> empty JSON +output=$(cd "$TEST_PROJECT" && "$SCRIPT_DIR/../../hooks/manus-pretool.sh") +assert_valid_json "$output" "Hook outputs valid JSON when inactive" +assert_contains "$output" "{}" "Hook outputs empty JSON when inactive" + +# Case 2: .active + task_plan.md -> reminder JSON +mkdir -p "$TEST_PROJECT/docs/manus" +cat > "$TEST_PROJECT/docs/manus/task_plan.md" <<'PLAN' +# Task Plan + +## Goal +Test hook output. +PLAN + +touch "$TEST_PROJECT/docs/manus/.active" + +output_active=$(cd "$TEST_PROJECT" && "$SCRIPT_DIR/../../hooks/manus-pretool.sh") +assert_valid_json "$output_active" "Hook outputs valid JSON when active" +assert_contains "$output_active" "Manus Planning Reminder" "Hook emits reminder content" + +echo "=== All tests passed ===" diff --git a/tests/claude-code/test-manus-ralph-combined-integration.sh b/tests/claude-code/test-manus-ralph-combined-integration.sh new file mode 100755 index 000000000..1f69851b0 --- /dev/null +++ b/tests/claude-code/test-manus-ralph-combined-integration.sh @@ -0,0 +1,91 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +source "$SCRIPT_DIR/test-helpers.sh" + +echo "=== Integration Test: manus + ralph combined ===" + +TEST_PROJECT=$(create_test_project) +trap "cleanup_test_project $TEST_PROJECT" EXIT + +mkdir -p "$TEST_PROJECT/docs" +cd "$TEST_PROJECT" + +git init --quiet +git config user.email "test@test.com" +git config user.name "Test User" +git commit --allow-empty -m "init" --quiet + +# Pre-create manus files to simulate active manus planning +mkdir -p "$TEST_PROJECT/docs/manus" +cat > "$TEST_PROJECT/docs/manus/task_plan.md" <<'EOF' +# Test Task Plan + +## Goal +Create docs/combined.txt with "ok" + +## Current Phase +Phase 1 (in progress) + +## Phases +### Phase 1: Initial Setup +**Status**: in_progress +EOF + +cat > "$TEST_PROJECT/docs/manus/findings.md" <<'EOF' +# Findings +Simple test task +EOF + +cat > "$TEST_PROJECT/docs/manus/progress.md" <<'EOF' +# Progress +Planning started +EOF + +touch "$TEST_PROJECT/docs/manus/.active" + +cat > "$TEST_PROJECT/@fix_plan.md" <<'EOF' +- [ ] Create docs/combined.txt with "ok" +EOF + +cat > "$TEST_PROJECT/PROMPT.md" <<'EOF' +You are running in a Ralph loop with Superpowers-NG. + +docs/manus/.active exists, which means manus planning is active. +Complete the simple task from @fix_plan.md. + +At the end of your response, emit this status block format: + +---RALPH_STATUS--- +STATUS: IN_PROGRESS +TASKS_COMPLETED_THIS_LOOP: 1 +FILES_MODIFIED: 1 +TESTS_STATUS: NOT_RUN +WORK_TYPE: IMPLEMENTATION +EXIT_SIGNAL: false +RECOMMENDATION: Task completed, manus still active, continue in next loop +---END_RALPH_STATUS--- + +IMPORTANT: Keep EXIT_SIGNAL: false because docs/manus/.active exists +EOF + +PROMPT="Change to directory $TEST_PROJECT and follow PROMPT.md exactly." + +# Run with timeout fallback +if command -v timeout >/dev/null 2>&1; then + cd "$SCRIPT_DIR/../.." && timeout 180 claude -p "$PROMPT" --allowed-tools=all --add-dir "$TEST_PROJECT" --permission-mode bypassPermissions > "$TEST_PROJECT/out.txt" 2>&1 || true +elif command -v gtimeout >/dev/null 2>&1; then + cd "$SCRIPT_DIR/../.." && gtimeout 180 claude -p "$PROMPT" --allowed-tools=all --add-dir "$TEST_PROJECT" --permission-mode bypassPermissions > "$TEST_PROJECT/out.txt" 2>&1 || true +else + echo " [SKIP] timeout command not available - install coreutils (brew install coreutils)" + exit 0 +fi + +assert_file_exists "$TEST_PROJECT/docs/manus/.active" "manus .active created" + +status=$(extract_ralph_status "$(cat "$TEST_PROJECT/out.txt")") +verify_ralph_status_block "$status" "Status block emitted" +assert_contains "$status" "EXIT_SIGNAL: false" "EXIT_SIGNAL stays false while manus active" + +echo "=== All tests passed ===" diff --git a/tests/claude-code/test-manus-resume-integration.sh b/tests/claude-code/test-manus-resume-integration.sh new file mode 100755 index 000000000..ac57e6027 --- /dev/null +++ b/tests/claude-code/test-manus-resume-integration.sh @@ -0,0 +1,95 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +source "$SCRIPT_DIR/test-helpers.sh" + +echo "=== Integration Test: manus resume ===" + +TEST_PROJECT=$(create_test_project) +trap "cleanup_test_project $TEST_PROJECT" EXIT + +# Session 1: Create manus files (simulating manus-planning start) +cd "$TEST_PROJECT" +mkdir -p docs/manus + +git init --quiet +git config user.email "test@test.com" +git config user.name "Test User" +git commit --allow-empty -m "init" --quiet + +# Create manus files as if manus-planning was started +cat > "$TEST_PROJECT/docs/manus/task_plan.md" <<'EOF' +# Create docs/note.txt + +## Goal +Create a simple file docs/note.txt with the content "ok" + +## Current Phase +Phase 1: Initial Setup + +## Phases +### Phase 1: Initial Setup +**Status**: in_progress +**Tasks**: +- Create docs directory if needed +- Create note.txt with "ok" + +### Phase 2: Verification +**Status**: pending +**Tasks**: +- Verify file exists +- Verify content is correct + +### Phase 3-5: Not applicable for simple task +EOF + +cat > "$TEST_PROJECT/docs/manus/findings.md" <<'EOF' +# Findings + +## Requirements +- Create docs/note.txt with "ok" +EOF + +cat > "$TEST_PROJECT/docs/manus/progress.md" <<'EOF' +# Progress + +## Session 1 +Started planning. Ready for implementation. +EOF + +touch "$TEST_PROJECT/docs/manus/.active" + +# Verify session 1 setup +assert_file_exists "$TEST_PROJECT/docs/manus/task_plan.md" "task_plan.md created" +assert_file_exists "$TEST_PROJECT/docs/manus/findings.md" "findings.md created" +assert_file_exists "$TEST_PROJECT/docs/manus/progress.md" "progress.md created" +assert_file_exists "$TEST_PROJECT/docs/manus/.active" ".active created" + +# Session 2: Claude resumes and completes the task +PROMPT_2="Change to directory $TEST_PROJECT. + +You will find manus planning files in docs/manus/. Read them to understand the task. +Complete Phase 1 by creating docs/note.txt with 'ok'. +Then mark the task complete and remove docs/manus/.active marker." + +if command -v timeout >/dev/null 2>&1; then + cd "$SCRIPT_DIR/../.." && timeout 180 claude -p "$PROMPT_2" --allowed-tools=all --add-dir "$TEST_PROJECT" --permission-mode bypassPermissions > "$TEST_PROJECT/out2.txt" 2>&1 || true +elif command -v gtimeout >/dev/null 2>&1; then + cd "$SCRIPT_DIR/../.." && gtimeout 180 claude -p "$PROMPT_2" --allowed-tools=all --add-dir "$TEST_PROJECT" --permission-mode bypassPermissions > "$TEST_PROJECT/out2.txt" 2>&1 || true +else + echo " [SKIP] timeout command not available" + exit 0 +fi + +# Verify session 2 results +assert_file_exists "$TEST_PROJECT/docs/note.txt" "task completed" + +if [ -f "$TEST_PROJECT/docs/manus/.active" ]; then + echo " [FAIL] .active still present after completion" + exit 1 +else + echo " [PASS] .active removed after completion" +fi + +echo "=== All tests passed ===" diff --git a/tests/claude-code/test-ralph-status-blocks.sh b/tests/claude-code/test-ralph-status-blocks.sh new file mode 100755 index 000000000..d81e39e33 --- /dev/null +++ b/tests/claude-code/test-ralph-status-blocks.sh @@ -0,0 +1,16 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +source "$SCRIPT_DIR/test-helpers.sh" + +echo "=== Test: Ralph status block parsing ===" + +sample=$'Output text\n---RALPH_STATUS---\nSTATUS: IN_PROGRESS\nTASKS_COMPLETED_THIS_LOOP: 1\nFILES_MODIFIED: 2\nTESTS_STATUS: NOT_RUN\nWORK_TYPE: DOCUMENTATION\nEXIT_SIGNAL: false\nRECOMMENDATION: Continue with next task\n---END_RALPH_STATUS---\n' + +status=$(extract_ralph_status "$sample") +verify_ralph_status_block "$status" "Status block fields + enums" + +assert_contains "$status" "STATUS: IN_PROGRESS" "Status value present" + +echo "=== All tests passed ===" diff --git a/tests/claude-code/test-ralph-status-emission-integration.sh b/tests/claude-code/test-ralph-status-emission-integration.sh new file mode 100755 index 000000000..60ce55ced --- /dev/null +++ b/tests/claude-code/test-ralph-status-emission-integration.sh @@ -0,0 +1,59 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +source "$SCRIPT_DIR/test-helpers.sh" + +echo "=== Integration Test: Ralph status emission ===" + +TEST_PROJECT=$(create_test_project) +trap "cleanup_test_project $TEST_PROJECT" EXIT + +mkdir -p "$TEST_PROJECT/docs" +cd "$TEST_PROJECT" + +git init --quiet +git config user.email "test@test.com" +git config user.name "Test User" +git commit --allow-empty -m "init" --quiet + +cat > "$TEST_PROJECT/@fix_plan.md" <<'EOF' +- [ ] Create docs/hello.txt with the word "hi" +EOF + +cat > "$TEST_PROJECT/PROMPT.md" <<'EOF' +You are running in a Ralph loop with Superpowers-NG. + +Tasks are in @fix_plan.md. Complete the task. + +At the end of your response, emit this exact status block format: + +---RALPH_STATUS--- +STATUS: IN_PROGRESS +TASKS_COMPLETED_THIS_LOOP: 1 +FILES_MODIFIED: 1 +TESTS_STATUS: NOT_RUN +WORK_TYPE: IMPLEMENTATION +EXIT_SIGNAL: false +RECOMMENDATION: Task completed successfully +---END_RALPH_STATUS--- + +(Adjust values based on actual work done) +EOF + +PROMPT="Change to directory $TEST_PROJECT and follow PROMPT.md exactly." + +# Run with timeout fallback +if command -v timeout >/dev/null 2>&1; then + cd "$SCRIPT_DIR/../.." && timeout 180 claude -p "$PROMPT" --allowed-tools=all --add-dir "$TEST_PROJECT" --permission-mode bypassPermissions > "$TEST_PROJECT/out.txt" 2>&1 || true +elif command -v gtimeout >/dev/null 2>&1; then + cd "$SCRIPT_DIR/../.." && gtimeout 180 claude -p "$PROMPT" --allowed-tools=all --add-dir "$TEST_PROJECT" --permission-mode bypassPermissions > "$TEST_PROJECT/out.txt" 2>&1 || true +else + echo " [SKIP] timeout command not available - install coreutils (brew install coreutils)" + exit 0 +fi + +status=$(extract_ralph_status "$(cat "$TEST_PROJECT/out.txt")") +verify_ralph_status_block "$status" "Status block emitted" + +echo "=== All tests passed ===" diff --git a/tests/claude-code/test-subagent-driven-development-integration.sh b/tests/claude-code/test-subagent-driven-development-integration.sh index ddb0c12fc..866dbdde2 100755 --- a/tests/claude-code/test-subagent-driven-development-integration.sh +++ b/tests/claude-code/test-subagent-driven-development-integration.sh @@ -186,7 +186,7 @@ echo "" # Test 1: Skill was invoked echo "Test 1: Skill tool invoked..." -if grep -q '"name":"Skill".*"skill":"superpowers:subagent-driven-development"' "$SESSION_FILE"; then +if grep -q '"name":"Skill".*"skill":"superpowers-ng:subagent-driven-development"' "$SESSION_FILE"; then echo " [PASS] subagent-driven-development skill was invoked" else echo " [FAIL] Skill was not invoked" diff --git a/tests/opencode/test-priority.sh b/tests/opencode/test-priority.sh index 1c36fa33f..c5e194fc1 100755 --- a/tests/opencode/test-priority.sh +++ b/tests/opencode/test-priority.sh @@ -151,12 +151,12 @@ else echo "$output" | grep -i "priority\|project\|personal" | head -10 fi -# Test 4: Test explicit superpowers: prefix bypasses priority +# Test 4: Test explicit superpowers-ng: prefix bypasses priority echo "" -echo "Test 4: Testing superpowers: prefix forces superpowers version..." +echo "Test 4: Testing superpowers-ng: prefix forces superpowers version..." cd "$TEST_HOME/test-project" -output=$(timeout 60s opencode run --print-logs "Use the use_skill tool to load superpowers:priority-test specifically. Show me the exact content including any PRIORITY_MARKER text." 2>&1) || { +output=$(timeout 60s opencode run --print-logs "Use the use_skill tool to load superpowers-ng:priority-test specifically. Show me the exact content including any PRIORITY_MARKER text." 2>&1) || { exit_code=$? if [ $exit_code -eq 124 ]; then echo " [FAIL] OpenCode timed out after 60s" @@ -165,9 +165,9 @@ output=$(timeout 60s opencode run --print-logs "Use the use_skill tool to load s } if echo "$output" | grep -qi "PRIORITY_MARKER_SUPERPOWERS_VERSION"; then - echo " [PASS] superpowers: prefix correctly forces superpowers version" + echo " [PASS] superpowers-ng: prefix correctly forces superpowers version" elif echo "$output" | grep -qi "PRIORITY_MARKER_PROJECT_VERSION\|PRIORITY_MARKER_PERSONAL_VERSION"; then - echo " [FAIL] superpowers: prefix did not force superpowers version" + echo " [FAIL] superpowers-ng: prefix did not force superpowers version" exit 1 else echo " [WARN] Could not verify priority marker in output" diff --git a/tests/opencode/test-skills-core.sh b/tests/opencode/test-skills-core.sh index b058d5fd5..89ec307ef 100755 --- a/tests/opencode/test-skills-core.sh +++ b/tests/opencode/test-skills-core.sh @@ -283,8 +283,8 @@ const fs = require('fs'); const path = require('path'); function resolveSkillPath(skillName, superpowersDir, personalDir) { - const forceSuperpowers = skillName.startsWith('superpowers:'); - const actualSkillName = forceSuperpowers ? skillName.replace(/^superpowers:/, '') : skillName; + const forceSuperpowers = skillName.startsWith('superpowers-ng:'); + const actualSkillName = forceSuperpowers ? skillName.replace(/^superpowers-ng:/, '') : skillName; if (!forceSuperpowers && personalDir) { const personalPath = path.join(personalDir, actualSkillName); @@ -320,8 +320,8 @@ const personalDir = '$TEST_HOME/personal-skills'; const shared = resolveSkillPath('shared-skill', superpowersDir, personalDir); console.log('SHARED:', JSON.stringify(shared)); -// Test 2: superpowers: prefix should force superpowers -const forced = resolveSkillPath('superpowers:shared-skill', superpowersDir, personalDir); +// Test 2: superpowers-ng: prefix should force superpowers +const forced = resolveSkillPath('superpowers-ng:shared-skill', superpowersDir, personalDir); console.log('FORCED:', JSON.stringify(forced)); // Test 3: Unique skill should resolve to superpowers @@ -342,9 +342,9 @@ else fi if echo "$result" | grep -q 'FORCED:.*"sourceType":"superpowers"'; then - echo " [PASS] superpowers: prefix forces superpowers resolution" + echo " [PASS] superpowers-ng: prefix forces superpowers resolution" else - echo " [FAIL] superpowers: prefix not working" + echo " [FAIL] superpowers-ng: prefix not working" exit 1 fi diff --git a/tests/opencode/test-tools.sh b/tests/opencode/test-tools.sh index e4590fea7..518254c03 100755 --- a/tests/opencode/test-tools.sh +++ b/tests/opencode/test-tools.sh @@ -36,7 +36,7 @@ output=$(timeout 60s opencode run --print-logs "Use the find_skills tool to list } # Check for expected patterns in output -if echo "$output" | grep -qi "superpowers:brainstorming\|superpowers:using-superpowers\|Available skills"; then +if echo "$output" | grep -qi "superpowers-ng:brainstorming\|superpowers-ng:using-superpowers\|Available skills"; then echo " [PASS] find_skills tool discovered superpowers skills" else echo " [FAIL] find_skills did not return expected skills" @@ -76,12 +76,12 @@ else exit 1 fi -# Test 3: Test use_skill with superpowers: prefix +# Test 3: Test use_skill with superpowers-ng: prefix echo "" -echo "Test 3: Testing use_skill with superpowers: prefix..." -echo " Running opencode with superpowers:brainstorming skill..." +echo "Test 3: Testing use_skill with superpowers-ng: prefix..." +echo " Running opencode with superpowers-ng:brainstorming skill..." -output=$(timeout 60s opencode run --print-logs "Use the use_skill tool to load superpowers:brainstorming and tell me the first few lines of what you received." 2>&1) || { +output=$(timeout 60s opencode run --print-logs "Use the use_skill tool to load superpowers-ng:brainstorming and tell me the first few lines of what you received." 2>&1) || { exit_code=$? if [ $exit_code -eq 124 ]; then echo " [FAIL] OpenCode timed out after 60s" @@ -92,9 +92,9 @@ output=$(timeout 60s opencode run --print-logs "Use the use_skill tool to load s # Check for expected content from brainstorming skill if echo "$output" | grep -qi "brainstorming\|Launching skill\|skill.*loaded"; then - echo " [PASS] use_skill loaded superpowers:brainstorming skill" + echo " [PASS] use_skill loaded superpowers-ng:brainstorming skill" else - echo " [FAIL] use_skill did not load superpowers:brainstorming correctly" + echo " [FAIL] use_skill did not load superpowers-ng:brainstorming correctly" echo " Output was:" echo "$output" | head -50 exit 1 diff --git a/tests/subagent-driven-dev/go-fractals/plan.md b/tests/subagent-driven-dev/go-fractals/plan.md index 9875ab5f2..0bc3fd4b8 100644 --- a/tests/subagent-driven-dev/go-fractals/plan.md +++ b/tests/subagent-driven-dev/go-fractals/plan.md @@ -1,6 +1,6 @@ # Go Fractals CLI - Implementation Plan -Execute this plan using the `superpowers:subagent-driven-development` skill. +Execute this plan using the `superpowers-ng:subagent-driven-development` skill. ## Context diff --git a/tests/subagent-driven-dev/go-fractals/scaffold.sh b/tests/subagent-driven-dev/go-fractals/scaffold.sh index d11ea74df..69695600b 100755 --- a/tests/subagent-driven-dev/go-fractals/scaffold.sh +++ b/tests/subagent-driven-dev/go-fractals/scaffold.sh @@ -42,4 +42,4 @@ git commit -m "Initial project setup with design and plan" echo "Scaffolded Go Fractals project at: $TARGET_DIR" echo "" echo "To run the test:" -echo " claude -p \"Execute this plan using superpowers:subagent-driven-development. Plan: $TARGET_DIR/plan.md\" --plugin-dir /path/to/superpowers" +echo " claude -p \"Execute this plan using superpowers-ng:subagent-driven-development. Plan: $TARGET_DIR/plan.md\" --plugin-dir /path/to/superpowers" diff --git a/tests/subagent-driven-dev/run-test.sh b/tests/subagent-driven-dev/run-test.sh index b4fcc9328..4400eaef9 100755 --- a/tests/subagent-driven-dev/run-test.sh +++ b/tests/subagent-driven-dev/run-test.sh @@ -60,7 +60,7 @@ echo "" # Prepare the prompt PLAN_PATH="$OUTPUT_DIR/project/plan.md" -PROMPT="Execute this plan using superpowers:subagent-driven-development. The plan is at: $PLAN_PATH" +PROMPT="Execute this plan using superpowers-ng:subagent-driven-development. The plan is at: $PLAN_PATH" # Run Claude with JSON output for token tracking LOG_FILE="$OUTPUT_DIR/claude-output.json" diff --git a/tests/subagent-driven-dev/svelte-todo/plan.md b/tests/subagent-driven-dev/svelte-todo/plan.md index f4e555b30..89006c0a6 100644 --- a/tests/subagent-driven-dev/svelte-todo/plan.md +++ b/tests/subagent-driven-dev/svelte-todo/plan.md @@ -1,6 +1,6 @@ # Svelte Todo List - Implementation Plan -Execute this plan using the `superpowers:subagent-driven-development` skill. +Execute this plan using the `superpowers-ng:subagent-driven-development` skill. ## Context diff --git a/tests/subagent-driven-dev/svelte-todo/scaffold.sh b/tests/subagent-driven-dev/svelte-todo/scaffold.sh index f58129da6..bd0592222 100755 --- a/tests/subagent-driven-dev/svelte-todo/scaffold.sh +++ b/tests/subagent-driven-dev/svelte-todo/scaffold.sh @@ -43,4 +43,4 @@ git commit -m "Initial project setup with design and plan" echo "Scaffolded Svelte Todo project at: $TARGET_DIR" echo "" echo "To run the test:" -echo " claude -p \"Execute this plan using superpowers:subagent-driven-development. Plan: $TARGET_DIR/plan.md\" --plugin-dir /path/to/superpowers" +echo " claude -p \"Execute this plan using superpowers-ng:subagent-driven-development. Plan: $TARGET_DIR/plan.md\" --plugin-dir /path/to/superpowers"