diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index f09ebef0b..c072c77fd 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -9,7 +9,7 @@
{
"name": "superpowers",
"description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
- "version": "4.0.3",
+ "version": "4.3.0",
"source": "./",
"author": {
"name": "Jesse Vincent",
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 0e37c2c16..bfc13a0fd 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-ng",
+ "repository": "https://github.com/OniReimu/superpowers-ng",
"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/INSTALL.md b/.codex/INSTALL.md
index 1250f5e07..a096845c6 100644
--- a/.codex/INSTALL.md
+++ b/.codex/INSTALL.md
@@ -1,35 +1,72 @@
# Installing Superpowers for Codex
-Quick setup to enable superpowers skills in Codex.
+Enable superpowers skills in Codex via native skill discovery. Just clone and symlink.
+
+## Prerequisites
+
+- Git
## Installation
-1. **Clone superpowers repository**:
+1. **Clone the superpowers repository:**
+ ```bash
+ git clone https://github.com/OniReimu/superpowers-ng.git ~/.codex/superpowers
+ ```
+
+2. **Create the skills symlink:**
```bash
- mkdir -p ~/.codex/superpowers
- cd ~/.codex/superpowers
- git clone https://github.com/obra/superpowers.git .
+ mkdir -p ~/.agents/skills
+ ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers
+ ```
+
+ **Windows (PowerShell):**
+ ```powershell
+ New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
+ cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers\skills"
```
-2. **Create personal skills directory**:
+3. **Optional: Create project-local skills directory** (for per-project skills):
```bash
- mkdir -p ~/.codex/skills
+ mkdir -p .codex/skills
```
-3. **Update ~/.codex/AGENTS.md** to include this superpowers section:
- ```markdown
- ## Superpowers System
+4. **Restart Codex** (quit and relaunch the CLI) to discover the skills.
+
+## Migrating from old bootstrap
+
+If you installed superpowers before native skill discovery, you need to:
-
- You have superpowers. Superpowers teach you new skills and capabilities. RIGHT NOW run: `~/.codex/superpowers/.codex/superpowers-codex bootstrap` and follow the instructions it returns.
-
+1. **Update the repo:**
+ ```bash
+ cd ~/.codex/superpowers && git pull
```
-## Verification
+2. **Create the skills symlink** (step 2 above) — this is the new discovery mechanism.
+
+3. **Remove the old bootstrap block** from `~/.codex/AGENTS.md` — any block referencing `superpowers-codex bootstrap` is no longer needed.
+
+4. **Restart Codex.**
+
+## Verify
+
+```bash
+ls -la ~/.agents/skills/superpowers
+```
+
+You should see a symlink (or junction on Windows) pointing to your superpowers skills directory.
+
+## Updating
+
+```bash
+cd ~/.codex/superpowers && git pull
+```
+
+Skills update instantly through the symlink.
+
+## Uninstalling
-Test the installation:
```bash
-~/.codex/superpowers/.codex/superpowers-codex bootstrap
+rm ~/.agents/skills/superpowers
```
-You should see skill listings and bootstrap instructions. The system is now ready for use.
\ No newline at end of file
+Optionally delete the clone: `rm -rf ~/.codex/superpowers`.
diff --git a/.codex/superpowers-bootstrap.md b/.codex/superpowers-bootstrap.md
deleted file mode 100644
index 18fe657f0..000000000
--- a/.codex/superpowers-bootstrap.md
+++ /dev/null
@@ -1,33 +0,0 @@
-# Superpowers Bootstrap for Codex
-
-
-You have superpowers.
-
-**Tool for running skills:**
-- `~/.codex/superpowers/.codex/superpowers-codex use-skill `
-
-**Tool Mapping for Codex:**
-When skills reference tools you don't have, substitute your equivalent tools:
-- `TodoWrite` → `update_plan` (your planning/task tracking tool)
-- `Task` tool with subagents → Tell the user that subagents aren't available in Codex yet and you'll do the work the subagent would do
-- `Skill` tool → `~/.codex/superpowers/.codex/superpowers-codex use-skill` command (already available)
-- `Read`, `Write`, `Edit`, `Bash` → Use your native tools with similar functions
-
-**Skills naming:**
-- Superpowers skills: `superpowers:skill-name` (from ~/.codex/superpowers/skills/)
-- Personal skills: `skill-name` (from ~/.codex/skills/)
-- Personal skills override superpowers skills when names match
-
-**Critical Rules:**
-- Before ANY task, review the skills list (shown below)
-- If a relevant skill exists, you MUST use `~/.codex/superpowers/.codex/superpowers-codex use-skill` to load it
-- Announce: "I've read the [Skill Name] skill and I'm using it to [purpose]"
-- Skills with checklists require `update_plan` todos for each item
-- NEVER skip mandatory workflows (brainstorming before coding, TDD, systematic debugging)
-
-**Skills location:**
-- Superpowers skills: ~/.codex/superpowers/skills/
-- Personal skills: ~/.codex/skills/ (override superpowers when names match)
-
-IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
-
\ No newline at end of file
diff --git a/.codex/superpowers-codex b/.codex/superpowers-codex
deleted file mode 100755
index 1d9a0efb6..000000000
--- a/.codex/superpowers-codex
+++ /dev/null
@@ -1,267 +0,0 @@
-#!/usr/bin/env node
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const skillsCore = require('../lib/skills-core');
-
-// Paths
-const homeDir = os.homedir();
-const superpowersSkillsDir = path.join(homeDir, '.codex', 'superpowers', 'skills');
-const personalSkillsDir = path.join(homeDir, '.codex', 'skills');
-const bootstrapFile = path.join(homeDir, '.codex', 'superpowers', '.codex', 'superpowers-bootstrap.md');
-const superpowersRepoDir = path.join(homeDir, '.codex', 'superpowers');
-
-// Utility functions
-function printSkill(skillPath, sourceType) {
- const skillFile = path.join(skillPath, 'SKILL.md');
- const relPath = sourceType === 'personal'
- ? path.relative(personalSkillsDir, skillPath)
- : path.relative(superpowersSkillsDir, skillPath);
-
- // Print skill name with namespace
- 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
- }
-
- // Extract and print metadata
- const { name, description } = skillsCore.extractFrontmatter(skillFile);
-
- if (description) console.log(` ${description}`);
- console.log('');
-}
-
-// Commands
-function runFindSkills() {
- console.log('Available skills:');
- console.log('==================');
- console.log('');
-
- const foundSkills = new Set();
-
- // Find personal skills first (these take precedence)
- const personalSkills = skillsCore.findSkillsInDir(personalSkillsDir, 'personal', 2);
- for (const skill of personalSkills) {
- const relPath = path.relative(personalSkillsDir, skill.path);
- foundSkills.add(relPath);
- printSkill(skill.path, 'personal');
- }
-
- // Find superpowers skills (only if not already found in personal)
- const superpowersSkills = skillsCore.findSkillsInDir(superpowersSkillsDir, 'superpowers', 1);
- for (const skill of superpowersSkills) {
- const relPath = path.relative(superpowersSkillsDir, skill.path);
- if (!foundSkills.has(relPath)) {
- printSkill(skill.path, 'superpowers');
- }
- }
-
- console.log('Usage:');
- 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(' Personal skills: skill-name (from ~/.codex/skills/)');
- console.log(' Personal skills override superpowers skills when names match.');
- console.log('');
- console.log('Note: All skills are disclosed at session start via bootstrap.');
-}
-
-function runBootstrap() {
- console.log('# Superpowers Bootstrap for Codex');
- console.log('# ================================');
- console.log('');
-
- // Check for updates (with timeout protection)
- if (skillsCore.checkForUpdates(superpowersRepoDir)) {
- console.log('## Update Available');
- console.log('');
- console.log('⚠️ Your superpowers installation is behind the latest version.');
- console.log('To update, run: `cd ~/.codex/superpowers && git pull`');
- console.log('');
- console.log('---');
- console.log('');
- }
-
- // Show the bootstrap instructions
- if (fs.existsSync(bootstrapFile)) {
- console.log('## Bootstrap Instructions:');
- console.log('');
- try {
- const content = fs.readFileSync(bootstrapFile, 'utf8');
- console.log(content);
- } catch (error) {
- console.log(`Error reading bootstrap file: ${error.message}`);
- }
- console.log('');
- console.log('---');
- console.log('');
- }
-
- // Run find-skills to show available skills
- console.log('## Available Skills:');
- console.log('');
- runFindSkills();
-
- console.log('');
- console.log('---');
- console.log('');
-
- // Load the using-superpowers skill automatically
- console.log('## Auto-loading superpowers:using-superpowers skill:');
- console.log('');
- runUseSkill('superpowers:using-superpowers');
-
- console.log('');
- console.log('---');
- console.log('');
- console.log('# Bootstrap Complete!');
- console.log('# You now have access to all superpowers skills.');
- console.log('# Use "superpowers-codex use-skill " to load and apply skills.');
- console.log('# Remember: If a skill applies to your task, you MUST use it!');
-}
-
-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 brainstorming # Load personal skill (or superpowers if not found)');
- console.log(' superpowers-codex use-skill my-custom-skill # Load personal skill');
- return;
- }
-
- // Handle namespaced skill names
- let actualSkillPath;
- let forceSuperpowers = false;
-
- if (skillName.startsWith('superpowers:')) {
- // Remove the superpowers: namespace prefix
- actualSkillPath = skillName.substring('superpowers:'.length);
- forceSuperpowers = true;
- } else {
- actualSkillPath = skillName;
- }
-
- // Remove "skills/" prefix if present
- if (actualSkillPath.startsWith('skills/')) {
- actualSkillPath = actualSkillPath.substring('skills/'.length);
- }
-
- // Function to find skill file
- function findSkillFile(searchPath) {
- // Check for exact match with SKILL.md
- const skillMdPath = path.join(searchPath, 'SKILL.md');
- if (fs.existsSync(skillMdPath)) {
- return skillMdPath;
- }
-
- // Check for direct SKILL.md file
- if (searchPath.endsWith('SKILL.md') && fs.existsSync(searchPath)) {
- return searchPath;
- }
-
- return null;
- }
-
- let skillFile = null;
-
- // If superpowers: namespace was used, only check superpowers skills
- if (forceSuperpowers) {
- if (fs.existsSync(superpowersSkillsDir)) {
- const superpowersPath = path.join(superpowersSkillsDir, actualSkillPath);
- skillFile = findSkillFile(superpowersPath);
- }
- } else {
- // First check personal skills directory (takes precedence)
- if (fs.existsSync(personalSkillsDir)) {
- const personalPath = path.join(personalSkillsDir, actualSkillPath);
- skillFile = findSkillFile(personalPath);
- if (skillFile) {
- console.log(`# Loading personal skill: ${actualSkillPath}`);
- console.log(`# Source: ${skillFile}`);
- console.log('');
- }
- }
-
- // If not found in personal, check superpowers skills
- if (!skillFile && fs.existsSync(superpowersSkillsDir)) {
- const superpowersPath = path.join(superpowersSkillsDir, actualSkillPath);
- skillFile = findSkillFile(superpowersPath);
- if (skillFile) {
- console.log(`# Loading superpowers skill: superpowers:${actualSkillPath}`);
- console.log(`# Source: ${skillFile}`);
- console.log('');
- }
- }
- }
-
- // If still not found, error
- if (!skillFile) {
- console.log(`Error: Skill not found: ${actualSkillPath}`);
- console.log('');
- console.log('Available skills:');
- runFindSkills();
- return;
- }
-
- // Extract frontmatter and content using shared core functions
- let content, frontmatter;
- try {
- const fullContent = fs.readFileSync(skillFile, 'utf8');
- const { name, description } = skillsCore.extractFrontmatter(skillFile);
- content = skillsCore.stripFrontmatter(fullContent);
- frontmatter = { name, description };
- } catch (error) {
- console.log(`Error reading skill file: ${error.message}`);
- return;
- }
-
- // Display skill header with clean info
- const displayName = forceSuperpowers ? `superpowers:${actualSkillPath}` :
- (skillFile.includes(personalSkillsDir) ? actualSkillPath : `superpowers:${actualSkillPath}`);
-
- const skillDirectory = path.dirname(skillFile);
-
- console.log(`# ${frontmatter.name || displayName}`);
- if (frontmatter.description) {
- console.log(`# ${frontmatter.description}`);
- }
- console.log(`# Skill-specific tools and reference files live in ${skillDirectory}`);
- console.log('# ============================================');
- console.log('');
-
- // Display the skill content (without frontmatter)
- console.log(content);
-
-}
-
-// Main CLI
-const command = process.argv[2];
-const arg = process.argv[3];
-
-switch (command) {
- case 'bootstrap':
- runBootstrap();
- break;
- case 'use-skill':
- runUseSkill(arg);
- break;
- case 'find-skills':
- runFindSkills();
- break;
- default:
- console.log('Superpowers for Codex');
- console.log('Usage:');
- console.log(' superpowers-codex bootstrap # Run complete bootstrap with all skills');
- console.log(' superpowers-codex use-skill # Load a specific skill');
- console.log(' superpowers-codex find-skills # List all available skills');
- console.log('');
- console.log('Examples:');
- console.log(' superpowers-codex bootstrap');
- console.log(' superpowers-codex use-skill superpowers:brainstorming');
- console.log(' superpowers-codex use-skill my-custom-skill');
- break;
-}
diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json
new file mode 100644
index 000000000..448ba7cc6
--- /dev/null
+++ b/.cursor-plugin/plugin.json
@@ -0,0 +1,18 @@
+{
+ "name": "superpowers-ng",
+ "displayName": "Superpowers-NG",
+ "description": "Enhanced fork of superpowers with Manus-style persistent planning for long-running tasks and context resets",
+ "version": "4.3.0",
+ "author": {
+ "name": "OniReimu",
+ "url": "https://github.com/OniReimu"
+ },
+ "homepage": "https://github.com/OniReimu/superpowers-ng",
+ "repository": "https://github.com/OniReimu/superpowers-ng",
+ "license": "MIT",
+ "keywords": ["skills", "tdd", "debugging", "collaboration", "best-practices", "workflows"],
+ "skills": "./skills/",
+ "agents": "./agents/",
+ "commands": "./commands/",
+ "hooks": "./hooks/hooks.json"
+}
diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 000000000..7387a83b3
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,17 @@
+# Ensure shell scripts always have LF line endings
+*.sh text eol=lf
+
+# Ensure the polyglot wrapper keeps LF (it's parsed by both cmd and bash)
+*.cmd text eol=lf
+
+# Common text files
+*.md text eol=lf
+*.json text eol=lf
+*.js text eol=lf
+*.mjs text eol=lf
+*.ts text eol=lf
+
+# Explicitly mark binary files
+*.png binary
+*.jpg binary
+*.gif binary
diff --git a/.gitignore b/.gitignore
index 573cae048..8eb403136 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
.worktrees/
.private-journal/
.claude/
+**/CLAUDE.md
diff --git a/.opencode/INSTALL.md b/.opencode/INSTALL.md
index 925811542..537901eb6 100644
--- a/.opencode/INSTALL.md
+++ b/.opencode/INSTALL.md
@@ -3,16 +3,14 @@
## Prerequisites
- [OpenCode.ai](https://opencode.ai) installed
-- Node.js installed
- Git installed
## Installation Steps
-### 1. Install Superpowers
+### 1. Clone Superpowers
```bash
-mkdir -p ~/.config/opencode/superpowers
-git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers
+git clone https://github.com/OniReimu/superpowers-ng.git ~/.config/opencode/superpowers
```
### 2. Register the Plugin
@@ -20,32 +18,43 @@ git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers
Create a symlink so OpenCode discovers the plugin:
```bash
-mkdir -p ~/.config/opencode/plugin
-ln -sf ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js ~/.config/opencode/plugin/superpowers.js
+mkdir -p ~/.config/opencode/plugins
+rm -f ~/.config/opencode/plugins/superpowers.js
+ln -s ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js ~/.config/opencode/plugins/superpowers.js
```
-### 3. Restart OpenCode
+### 3. Symlink Skills
-Restart OpenCode. The plugin will automatically inject superpowers context via the chat.message hook.
+Create a symlink so OpenCode's native skill tool discovers superpowers skills:
-You should see superpowers is active when you ask "do you have superpowers?"
+```bash
+mkdir -p ~/.config/opencode/skills
+rm -rf ~/.config/opencode/skills/superpowers
+ln -s ~/.config/opencode/superpowers/skills ~/.config/opencode/skills/superpowers
+```
+
+### 4. Restart OpenCode
+
+Restart OpenCode. The plugin will automatically inject superpowers context.
+
+Verify by asking: "do you have superpowers?"
## Usage
### Finding Skills
-Use the `find_skills` tool to list all available skills:
+Use OpenCode's native `skill` tool to list available skills:
```
-use find_skills tool
+use skill tool to list skills
```
### Loading a Skill
-Use the `use_skill` tool to load a specific skill:
+Use OpenCode's native `skill` tool to load a specific skill:
```
-use use_skill tool with skill_name: "superpowers:brainstorming"
+use skill tool to load superpowers/brainstorming
```
### Personal Skills
@@ -69,36 +78,11 @@ description: Use when [condition] - [what it does]
[Your skill content here]
```
-Personal skills override superpowers skills with the same name.
-
### Project Skills
-Create project-specific skills in your OpenCode project:
-
-```bash
-# In your OpenCode project
-mkdir -p .opencode/skills/my-project-skill
-```
-
-Create `.opencode/skills/my-project-skill/SKILL.md`:
-
-```markdown
----
-name: my-project-skill
-description: Use when [condition] - [what it does]
----
-
-# My Project Skill
-
-[Your skill content here]
-```
-
-**Skill Priority:** Project skills override personal skills, which override superpowers skills.
+Create project-specific skills in `.opencode/skills/` within your project.
-**Skill Naming:**
-- `project:skill-name` - Force project skill lookup
-- `skill-name` - Searches project → personal → superpowers
-- `superpowers:skill-name` - Force superpowers skill lookup
+**Skill Priority:** Project skills > Personal skills > Superpowers skills
## Updating
@@ -111,25 +95,25 @@ git pull
### Plugin not loading
-1. Check plugin file exists: `ls ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js`
-2. Check OpenCode logs for errors
-3. Verify Node.js is installed: `node --version`
+1. Check plugin symlink: `ls -l ~/.config/opencode/plugins/superpowers.js`
+2. Check source exists: `ls ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js`
+3. Check OpenCode logs for errors
### Skills not found
-1. Verify skills directory exists: `ls ~/.config/opencode/superpowers/skills`
-2. Use `find_skills` tool to see what's discovered
-3. Check file structure: each skill should have a `SKILL.md` file
+1. Check skills symlink: `ls -l ~/.config/opencode/skills/superpowers`
+2. Verify it points to: `~/.config/opencode/superpowers/skills`
+3. Use `skill` tool to list what's discovered
-### Tool mapping issues
+### Tool mapping
-When a skill references a Claude Code tool you don't have:
-- `TodoWrite` → use `update_plan`
-- `Task` with subagents → use `@mention` syntax to invoke OpenCode subagents
-- `Skill` → use `use_skill` tool
-- File operations → use your native tools
+When skills reference Claude Code tools:
+- `TodoWrite` → `update_plan`
+- `Task` with subagents → `@mention` syntax
+- `Skill` tool → OpenCode's native `skill` tool
+- File operations → your native tools
## Getting Help
-- Report issues: https://github.com/obra/superpowers/issues
-- Documentation: https://github.com/obra/superpowers
+- Report issues: https://github.com/OniReimu/superpowers-ng/issues
+- Full documentation: https://github.com/OniReimu/superpowers-ng/blob/main/docs/README.opencode.md
diff --git a/.opencode/plugin/superpowers.js b/.opencode/plugin/superpowers.js
deleted file mode 100644
index c9a6e29ea..000000000
--- a/.opencode/plugin/superpowers.js
+++ /dev/null
@@ -1,215 +0,0 @@
-/**
- * Superpowers plugin for OpenCode.ai
- *
- * Provides custom tools for loading and discovering skills,
- * with prompt generation for agent configuration.
- */
-
-import path from 'path';
-import fs from 'fs';
-import os from 'os';
-import { fileURLToPath } from 'url';
-import { tool } from '@opencode-ai/plugin/tool';
-import * as skillsCore from '../../lib/skills-core.js';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
-export const SuperpowersPlugin = async ({ client, directory }) => {
- const homeDir = os.homedir();
- const projectSkillsDir = path.join(directory, '.opencode/skills');
- // Derive superpowers skills dir from plugin location (works for both symlinked and local installs)
- const superpowersSkillsDir = path.resolve(__dirname, '../../skills');
- const personalSkillsDir = path.join(homeDir, '.config/opencode/skills');
-
- // Helper to generate bootstrap content
- const getBootstrapContent = (compact = false) => {
- const usingSuperpowersPath = skillsCore.resolveSkillPath('using-superpowers', superpowersSkillsDir, personalSkillsDir);
- if (!usingSuperpowersPath) return null;
-
- const fullContent = fs.readFileSync(usingSuperpowersPath.skillFile, 'utf8');
- const content = skillsCore.stripFrontmatter(fullContent);
-
- const toolMapping = compact
- ? `**Tool Mapping:** TodoWrite->update_plan, Task->@mention, Skill->use_skill
-
-**Skills naming (priority order):** project: > personal > superpowers:`
- : `**Tool Mapping for OpenCode:**
-When skills reference tools you don't have, substitute OpenCode equivalents:
-- \`TodoWrite\` → \`update_plan\`
-- \`Task\` tool with subagents → Use OpenCode's subagent system (@mention)
-- \`Skill\` tool → \`use_skill\` custom tool
-- \`Read\`, \`Write\`, \`Edit\`, \`Bash\` → Your native tools
-
-**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\`
-- Project skills override personal, which override superpowers when names match`;
-
- return `
-You have superpowers.
-
-**IMPORTANT: The using-superpowers skill content is included below. It is ALREADY LOADED - you are currently following it. Do NOT use the use_skill tool to load "using-superpowers" - that would be redundant. Use use_skill only for OTHER skills.**
-
-${content}
-
-${toolMapping}
-`;
- };
-
- // Helper to inject bootstrap via session.prompt
- const injectBootstrap = async (sessionID, compact = false) => {
- const bootstrapContent = getBootstrapContent(compact);
- if (!bootstrapContent) return false;
-
- try {
- await client.session.prompt({
- path: { id: sessionID },
- body: {
- noReply: true,
- parts: [{ type: "text", text: bootstrapContent, synthetic: true }]
- }
- });
- return true;
- } catch (err) {
- return false;
- }
- };
-
- return {
- tool: {
- 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")')
- },
- execute: async (args, context) => {
- const { skill_name } = args;
-
- // Resolve with priority: project > personal > superpowers
- // Check for project: prefix first
- const forceProject = skill_name.startsWith('project:');
- const actualSkillName = forceProject ? skill_name.replace(/^project:/, '') : skill_name;
-
- let resolved = null;
-
- // Try project skills first (if project: prefix or no prefix)
- if (forceProject || !skill_name.startsWith('superpowers:')) {
- const projectPath = path.join(projectSkillsDir, actualSkillName);
- const projectSkillFile = path.join(projectPath, 'SKILL.md');
- if (fs.existsSync(projectSkillFile)) {
- resolved = {
- skillFile: projectSkillFile,
- sourceType: 'project',
- skillPath: actualSkillName
- };
- }
- }
-
- // Fall back to personal/superpowers resolution
- if (!resolved && !forceProject) {
- resolved = skillsCore.resolveSkillPath(skill_name, superpowersSkillsDir, personalSkillsDir);
- }
-
- if (!resolved) {
- return `Error: Skill "${skill_name}" not found.\n\nRun find_skills to see available skills.`;
- }
-
- const fullContent = fs.readFileSync(resolved.skillFile, 'utf8');
- const { name, description } = skillsCore.extractFrontmatter(resolved.skillFile);
- const content = skillsCore.stripFrontmatter(fullContent);
- const skillDirectory = path.dirname(resolved.skillFile);
-
- const skillHeader = `# ${name || skill_name}
-# ${description || ''}
-# Supporting tools and docs are in ${skillDirectory}
-# ============================================`;
-
- // Insert as user message with noReply for persistence across compaction
- try {
- await client.session.prompt({
- path: { id: context.sessionID },
- body: {
- noReply: true,
- parts: [
- { type: "text", text: `Loading skill: ${name || skill_name}`, synthetic: true },
- { type: "text", text: `${skillHeader}\n\n${content}`, synthetic: true }
- ]
- }
- });
- } catch (err) {
- // Fallback: return content directly if message insertion fails
- return `${skillHeader}\n\n${content}`;
- }
-
- return `Launching skill: ${name || skill_name}`;
- }
- }),
- find_skills: tool({
- description: 'List all available skills in the project, personal, and superpowers skill libraries.',
- args: {},
- execute: async (args, context) => {
- const projectSkills = skillsCore.findSkillsInDir(projectSkillsDir, 'project', 3);
- const personalSkills = skillsCore.findSkillsInDir(personalSkillsDir, 'personal', 3);
- const superpowersSkills = skillsCore.findSkillsInDir(superpowersSkillsDir, 'superpowers', 3);
-
- // Priority: project > personal > superpowers
- const allSkills = [...projectSkills, ...personalSkills, ...superpowersSkills];
-
- if (allSkills.length === 0) {
- return 'No skills found. Install superpowers skills to ~/.config/opencode/superpowers/skills/ or add project skills to .opencode/skills/';
- }
-
- let output = 'Available skills:\n\n';
-
- for (const skill of allSkills) {
- let namespace;
- switch (skill.sourceType) {
- case 'project':
- namespace = 'project:';
- break;
- case 'personal':
- namespace = '';
- break;
- default:
- namespace = 'superpowers:';
- }
- const skillName = skill.name || path.basename(skill.path);
-
- output += `${namespace}${skillName}\n`;
- if (skill.description) {
- output += ` ${skill.description}\n`;
- }
- output += ` Directory: ${skill.path}\n\n`;
- }
-
- return output;
- }
- })
- },
- event: async ({ event }) => {
- // Extract sessionID from various event structures
- const getSessionID = () => {
- return event.properties?.info?.id ||
- event.properties?.sessionID ||
- event.session?.id;
- };
-
- // Inject bootstrap at session creation (before first user message)
- if (event.type === 'session.created') {
- const sessionID = getSessionID();
- if (sessionID) {
- await injectBootstrap(sessionID, false);
- }
- }
-
- // Re-inject bootstrap after context compaction (compact version to save tokens)
- if (event.type === 'session.compacted') {
- const sessionID = getSessionID();
- if (sessionID) {
- await injectBootstrap(sessionID, true);
- }
- }
- }
- };
-};
diff --git a/.opencode/plugins/superpowers.js b/.opencode/plugins/superpowers.js
new file mode 100644
index 000000000..8ac993462
--- /dev/null
+++ b/.opencode/plugins/superpowers.js
@@ -0,0 +1,95 @@
+/**
+ * Superpowers plugin for OpenCode.ai
+ *
+ * Injects superpowers bootstrap context via system prompt transform.
+ * Skills are discovered via OpenCode's native skill tool from symlinked directory.
+ */
+
+import path from 'path';
+import fs from 'fs';
+import os from 'os';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Simple frontmatter extraction (avoid dependency on skills-core for bootstrap)
+const extractAndStripFrontmatter = (content) => {
+ const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+ if (!match) return { frontmatter: {}, content };
+
+ const frontmatterStr = match[1];
+ const body = match[2];
+ const frontmatter = {};
+
+ for (const line of frontmatterStr.split('\n')) {
+ const colonIdx = line.indexOf(':');
+ if (colonIdx > 0) {
+ const key = line.slice(0, colonIdx).trim();
+ const value = line.slice(colonIdx + 1).trim().replace(/^["']|["']$/g, '');
+ frontmatter[key] = value;
+ }
+ }
+
+ return { frontmatter, content: body };
+};
+
+// Normalize a path: trim whitespace, expand ~, resolve to absolute
+const normalizePath = (p, homeDir) => {
+ if (!p || typeof p !== 'string') return null;
+ let normalized = p.trim();
+ if (!normalized) return null;
+ if (normalized.startsWith('~/')) {
+ normalized = path.join(homeDir, normalized.slice(2));
+ } else if (normalized === '~') {
+ normalized = homeDir;
+ }
+ return path.resolve(normalized);
+};
+
+export const SuperpowersPlugin = async ({ client, directory }) => {
+ const homeDir = os.homedir();
+ const superpowersSkillsDir = path.resolve(__dirname, '../../skills');
+ const envConfigDir = normalizePath(process.env.OPENCODE_CONFIG_DIR, homeDir);
+ const configDir = envConfigDir || path.join(homeDir, '.config/opencode');
+
+ // Helper to generate bootstrap content
+ const getBootstrapContent = () => {
+ // Try to load using-superpowers skill
+ const skillPath = path.join(superpowersSkillsDir, 'using-superpowers', 'SKILL.md');
+ if (!fs.existsSync(skillPath)) return null;
+
+ const fullContent = fs.readFileSync(skillPath, 'utf8');
+ const { content } = extractAndStripFrontmatter(fullContent);
+
+ const toolMapping = `**Tool Mapping for OpenCode:**
+When skills reference tools you don't have, substitute OpenCode equivalents:
+- \`TodoWrite\` → \`update_plan\`
+- \`Task\` tool with subagents → Use OpenCode's subagent system (@mention)
+- \`Skill\` tool → OpenCode's native \`skill\` tool
+- \`Read\`, \`Write\`, \`Edit\`, \`Bash\` → Your native tools
+
+**Skills location:**
+Superpowers skills are in \`${configDir}/skills/superpowers/\`
+Use OpenCode's native \`skill\` tool to list and load skills.`;
+
+ return `
+You have superpowers.
+
+**IMPORTANT: The using-superpowers skill content is included below. It is ALREADY LOADED - you are currently following it. Do NOT use the skill tool to load "using-superpowers" again - that would be redundant.**
+
+${content}
+
+${toolMapping}
+`;
+ };
+
+ return {
+ // Use system prompt transform to inject bootstrap (fixes #226 agent reset bug)
+ 'experimental.chat.system.transform': async (_input, output) => {
+ const bootstrap = getBootstrapContent();
+ if (bootstrap) {
+ (output.system ||= []).push(bootstrap);
+ }
+ }
+ };
+};
diff --git a/README.md b/README.md
index 0e67aefcf..ef8c0c615 100644
--- a/README.md
+++ b/README.md
@@ -1,125 +1,157 @@
-# 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 differs by platform. Claude Code or Cursor have built-in plugin marketplaces. Codex and OpenCode require manual setup.
-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
-### Verify Installation
+# Install as a local plugin
+# (Instructions TBD based on Claude Code local plugin support)
+```
-Check that commands appear:
+### Cursor (via Plugin Marketplace)
-```bash
-/help
-```
+In Cursor Agent chat, install from marketplace:
-```
-# Should see:
-# /superpowers:brainstorm - Interactive design refinement
-# /superpowers:write-plan - Create implementation plan
-# /superpowers:execute-plan - Execute plan in batches
+```text
+/plugin-add superpowers-ng
```
### 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)
+See [docs/README.codex.md](docs/README.codex.md) for detailed instructions.
### OpenCode
-Tell OpenCode:
+See [docs/README.opencode.md](docs/README.opencode.md) for detailed instructions.
-```
-Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md
-```
+### Verify Installation
-**Detailed docs:** [docs/README.opencode.md](docs/README.opencode.md)
+Start a new session in your chosen platform and ask for something that should trigger a skill (for example, "help me plan this feature" or "let's debug this issue"). The agent should automatically invoke the relevant superpowers skill.
-## The Basic Workflow
+## The Enhanced Workflow
1. **brainstorming** - Activates before writing code. Refines rough ideas through questions, explores alternatives, presents design in sections for validation. Saves design document.
2. **using-git-worktrees** - Activates after design approval. Creates isolated workspace on new branch, runs project setup, verifies clean test baseline.
-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.
+3. **Choose your planning system:**
+ - **Native:** `writing-plans` → `executing-plans` for short tasks
+ - **Manus:** `manus-planning` for complex/long-running 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.
+4. **subagent-driven-development** or **executing-plans** - Dispatches fresh subagent per task with two-stage review (spec compliance, then code quality), or executes in batches with human checkpoints.
-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.
+5. **test-driven-development** - Enforces RED-GREEN-REFACTOR: write failing test, watch it fail, write minimal code, watch it pass, commit.
-6. **requesting-code-review** - Activates between tasks. Reviews against plan, reports issues by severity. Critical issues block progress.
+6. **requesting-code-review** - Reviews against plan, reports issues by severity. Critical issues block progress.
-7. **finishing-a-development-branch** - Activates when tasks complete. Verifies tests, presents options (merge/PR/keep/discard), cleans up worktree.
+7. **finishing-a-development-branch** - Verifies tests, presents options (merge/PR/keep/discard), cleans up worktree.
**The agent checks for relevant skills before any task.** Mandatory workflows, not suggestions.
## What's Inside
-### Skills Library
+### Planning Skills
+
+**Native Planning (Original)**
+- **writing-plans** - Bite-sized implementation plans
+- **executing-plans** - Batch execution with checkpoints
+
+**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
+
+### 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**
-- **writing-skills** - Create new skills following best practices (includes testing methodology)
-- **using-superpowers** - Introduction to the skills system
+### Meta
+
+- **writing-skills** - Create new skills following best practices
+- **using-superpowers** - Introduction to the skills system (updated with planning guidance)
## Philosophy
@@ -127,8 +159,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
-Read more: [Superpowers for Claude Code](https://blog.fsck.com/2025/10/09/superpowers/)
+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
+
+**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 +194,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 +219,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-ng/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..7c038ad5e 100644
--- a/RELEASE-NOTES.md
+++ b/RELEASE-NOTES.md
@@ -1,638 +1,353 @@
-# Superpowers Release Notes
+# Superpowers-NG Release Notes
-## v4.0.3 (2025-12-26)
+## Upstream v4.3.0 (2026-02-12)
-### 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)
+This fix should dramatically improve superpowers skills compliance and should reduce the chances of Claude entering its native plan mode unintentionally.
### 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)
+**Brainstorming skill now enforces its workflow instead of describing it**
----
+Models were skipping the design phase and jumping straight to implementation skills like frontend-design, or collapsing the entire brainstorming process into a single text block. The skill now uses hard gates, a mandatory checklist, and a graphviz process flow to enforce compliance:
-## v3.5.0 (2025-11-23)
+- ``: no implementation skills, code, or scaffolding until design is presented and user approves
+- Explicit checklist (6 items) that must be created as tasks and completed in order
+- Graphviz process flow with `writing-plans` as the only valid terminal state
+- Anti-pattern callout for "this is too simple to need a design" — the exact rationalization models use to skip the process
+- Design section sizing based on section complexity, not project complexity
-### Added
+**Using-superpowers workflow graph intercepts EnterPlanMode**
-- **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`)
+Added an `EnterPlanMode` intercept to the skill flow graph. When the model is about to enter Claude's native plan mode, it checks whether brainstorming has happened and routes through the brainstorming skill instead. Plan mode is never entered.
-### Changed
+### Fixed
-- **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
+**SessionStart hook now runs synchronously**
-- **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
+Changed `async: true` to `async: false` in hooks.json. When async, the hook could fail to complete before the model's first turn, meaning using-superpowers instructions weren't in context for the first message.
----
+## Upstream v4.2.0 (2026-02-05)
-## v3.4.1 (2025-10-31)
+### Breaking Changes
-### Improvements
+**Codex: Replaced bootstrap CLI with native skill discovery**
-- 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.
+The `superpowers-codex` bootstrap CLI, Windows `.cmd` wrapper, and related bootstrap content file have been removed. Codex now uses native skill discovery via `~/.agents/skills/superpowers/` symlink, so the old `use_skill`/`find_skills` CLI tools are no longer needed.
-## v3.4.0 (2025-10-30)
+Installation is now just clone + symlink (documented in INSTALL.md). No Node.js dependency required. The old `~/.codex/skills/` path is deprecated.
-### Improvements
+### Fixes
-- 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.
+**Windows: Fixed Claude Code 2.1.x hook execution (#331)**
-## v3.3.1 (2025-10-28)
+Claude Code 2.1.x changed how hooks execute on Windows: it now auto-detects `.sh` files in commands and prepends `bash`. This broke the polyglot wrapper pattern because `bash "run-hook.cmd" session-start.sh` tries to execute the `.cmd` file as a bash script.
-### Improvements
+Fix: hooks.json now calls session-start.sh directly. Claude Code 2.1.x handles the bash invocation automatically. Also added .gitattributes to enforce LF line endings for shell scripts (fixes CRLF issues on Windows checkout).
-- 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).
+**Windows: SessionStart hook runs async to prevent terminal freeze (#404, #413, #414, #419)**
-### Bug Fixes
+The synchronous SessionStart hook blocked the TUI from entering raw mode on Windows, freezing all keyboard input. Running the hook async prevents the freeze while still injecting superpowers context.
-- Clarified `writing-skills` guidance so it points to the correct agent-specific personal skill directories (`~/.claude/skills` for Claude Code, `~/.codex/skills` for Codex).
+**Windows: Fixed O(n^2) `escape_for_json` performance**
-## v3.3.0 (2025-10-28)
+The character-by-character loop using `${input:$i:1}` was O(n^2) in bash due to substring copy overhead. On Windows Git Bash this took 60+ seconds. Replaced with bash parameter substitution (`${s//old/new}`) which runs each pattern as a single C-level pass — 7x faster on macOS, dramatically faster on Windows.
-### New Features
+**Codex: Fixed Windows/PowerShell invocation (#285, #243)**
-**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
+- Windows doesn't respect shebangs, so directly invoking the extensionless `superpowers-codex` script triggered an "Open with" dialog. All invocations now prefixed with `node`.
+- Fixed `~/` path expansion on Windows — PowerShell doesn't expand `~` when passed as an argument to `node`. Changed to `$HOME` which expands correctly in both bash and PowerShell.
-**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"
+**Codex: Fixed path resolution in installer**
-### 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
+Used `fileURLToPath()` instead of manual URL pathname parsing to correctly handle paths with spaces and special characters on all platforms.
-**Note:** Codex support is experimental. The integration provides core superpowers functionality but may require refinement based on user feedback.
+**Codex: Fixed stale skills path in writing-skills**
-## v3.2.3 (2025-10-23)
+Updated `~/.codex/skills/` reference (deprecated) to `~/.agents/skills/` for native discovery.
### Improvements
-**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"
-
-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.
+**Worktree isolation now required before implementation**
-### Files Changed
-- Updated: `skills/using-superpowers/SKILL.md` - Changed tool references from Read to Skill
+Added `using-git-worktrees` as a required skill for both `subagent-driven-development` and `executing-plans`. Implementation workflows now explicitly require setting up an isolated worktree before starting work, preventing accidental work directly on main.
-## v3.2.2 (2025-10-21)
+**Main branch protection softened to require explicit consent**
-### Improvements
-
-**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
+Instead of prohibiting main branch work entirely, the skills now allow it with explicit user consent. More flexible while still ensuring users are aware of the implications.
-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.
+**Simplified installation verification**
-### Files Changed
-- Updated: `skills/using-superpowers/SKILL.md` - Added three layers of enforcement to prevent skill-skipping rationalization
+Removed `/help` command check and specific slash command list from verification steps. Skills are primarily invoked by describing what you want to do, not by running specific commands.
-## v3.2.1 (2025-10-20)
+**Codex: Clarified subagent tool mapping in bootstrap**
-### New Features
+Improved documentation of how Codex tools map to Claude Code equivalents for subagent workflows.
-**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
+### Tests
-### 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`
+- Added worktree requirement test for subagent-driven-development
+- Added main branch red flag warning test
+- Fixed case sensitivity in skill recognition test assertions
-## v3.2.0 (2025-10-18)
+---
-### New Features
+## Upstream v4.1.1 (2026-01-23)
-**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
+### Fixes
-### Breaking Changes
+**OpenCode: Standardized on `plugins/` directory per official docs (#343)**
-**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
+OpenCode's official documentation uses `~/.config/opencode/plugins/` (plural). Our docs previously used `plugin/` (singular). While OpenCode accepts both forms, we've standardized on the official convention to avoid confusion.
-### 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
+Changes:
+- Renamed `.opencode/plugin/` to `.opencode/plugins/` in repo structure
+- Updated all installation docs (INSTALL.md, README.opencode.md) across all platforms
+- Updated test scripts to match
-## v3.1.1 (2025-10-17)
+**OpenCode: Fixed symlink instructions (#339, #342)**
-### Bug Fixes
+- Added explicit `rm` before `ln -s` (fixes "file already exists" errors on reinstall)
+- Added missing skills symlink step that was absent from INSTALL.md
+- Updated from deprecated `use_skill`/`find_skills` to native `skill` tool references
-- **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)
+## Upstream v4.1.0 (2026-01-23)
### 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
+**OpenCode: Switched to native skills system**
-### 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
+Superpowers for OpenCode now uses OpenCode's native `skill` tool instead of custom `use_skill`/`find_skills` tools. This is a cleaner integration that works with OpenCode's built-in skill discovery.
-- **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
+**Migration required:** Skills must be symlinked to `~/.config/opencode/skills/superpowers/` (see updated installation docs).
-### 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
+### Fixes
-We now use Anthropic's first-party skills system!
+**OpenCode: Fixed agent reset on session start (#226)**
-## v2.0.2 (2025-10-12)
+The previous bootstrap injection method using `session.prompt({ noReply: true })` caused OpenCode to reset the selected agent to "build" on first message. Now uses `experimental.chat.system.transform` hook which modifies the system prompt directly without side effects.
-### Bug Fixes
+**OpenCode: Fixed Windows installation (#232)**
-- **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).
+- Removed dependency on `skills-core.js` (eliminates broken relative imports when file is copied instead of symlinked)
+- Added comprehensive Windows installation docs for cmd.exe, PowerShell, and Git Bash
+- Documented proper symlink vs junction usage for each platform
-## v2.0.1 (2025-10-12)
+**Claude Code: Fixed Windows hook execution for Claude Code 2.1.x**
-### Bug Fixes
+Claude Code 2.1.x changed how hooks execute on Windows: it now auto-detects `.sh` files in commands and prepends `bash `. This broke the polyglot wrapper pattern because `bash "run-hook.cmd" session-start.sh` tries to execute the .cmd file as a bash script.
-- **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
+Fix: hooks.json now calls session-start.sh directly. Claude Code 2.1.x handles the bash invocation automatically. Also added .gitattributes to enforce LF line endings for shell scripts (fixes CRLF issues on Windows checkout).
---
-# 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
+## v0.1.0 (2026-01-13)
-**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).
+**Initial release** of Superpowers-NG, an enhanced fork of [obra/superpowers](https://github.com/obra/superpowers) with Manus-style persistent planning and Ralph integration.
-**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
+### New Features
-### Skills Improvements
+#### 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.
-**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
+**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
-**writing-skills**
-- Cross-referencing guidance moved from using-skills
-- Added token efficiency section (word count targets)
-- Improved CSO (Claude Search Optimization) guidance
+**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)
-**sharing-skills**
-- Updated for new branch-and-PR workflow (v2.0.0)
-- Removed personal/core split references
+#### Brainstorming Enhancement
-**pulling-updates-from-skills-repository** (new)
-- Complete workflow for syncing with upstream
-- Replaces old "updating-skills" skill
+**Planning choice after design**
-### Tools Improvements
+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
-**find-skills**
-- Now outputs full paths with /SKILL.md suffix
-- Makes paths directly usable with Read tool
-- Updated help text
+When Manus is chosen, design document content is automatically copied into `findings.md` for persistent reference.
-**skill-run**
-- Moved from scripts/ to skills/using-skills/
-- Improved documentation
+**File:**
+- `skills/brainstorming/SKILL.md` - Updated "After the Design" section
-### Plugin Infrastructure
+#### Planning Guidance
-**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
+**Added planning approach comparison**
-**Environment Variables**
-- `SUPERPOWERS_SKILLS_ROOT` set to `~/.config/superpowers/skills`
-- Used consistently throughout all paths
+Updated `using-superpowers` skill with "Planning Approaches" section explaining when to use Native vs Manus planning:
-## Bug Fixes
+| 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 |
-- 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
+**File:**
+- `skills/using-superpowers/SKILL.md` - Added planning guidance section
-## Documentation
+#### Ralph Integration
-### 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
+**Seamless integration with Ralph autonomous loop framework**
-### Testing Documentation
-- Added comprehensive testing checklist (`docs/TESTING-CHECKLIST.md`)
-- Created local marketplace config for testing
-- Documented manual testing scenarios
+Added comprehensive support for using Superpowers-NG skills within [Ralph](https://github.com/frankbria/ralph-claude-code), the autonomous loop framework for Claude Code.
-## Technical Details
+**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
-### File Changes
+**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
-**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
+**Updated Files**:
+- `skills/brainstorming/SKILL.md` - Added Phase 0 (Check for Existing Design) with autonomous mode logic
+- `README.md` - Added "Integration with Ralph" section
-**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
+**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
-**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
+### Breaking Changes
-### 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-ng/compare/obra:main...OniReimu:main
+**Issues:** https://github.com/OniReimu/superpowers-ng/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..fd3dd7140 100644
--- a/docs/README.codex.md
+++ b/docs/README.codex.md
@@ -1,76 +1,95 @@
# Superpowers for Codex
-Complete guide for using Superpowers with OpenAI Codex.
+Guide for using Superpowers with OpenAI Codex via native skill discovery.
## Quick Install
Tell Codex:
```
-Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md
+Fetch and follow instructions from https://raw.githubusercontent.com/OniReimu/superpowers-ng/refs/heads/main/.codex/INSTALL.md
```
## Manual Installation
### Prerequisites
-- OpenAI Codex access
-- Shell access to install files
+- OpenAI Codex CLI
+- Git
-### Installation Steps
+### Steps
-#### 1. Clone Superpowers
+1. Clone the repo:
+ ```bash
+ git clone https://github.com/OniReimu/superpowers-ng.git ~/.codex/superpowers
+ ```
-```bash
-mkdir -p ~/.codex/superpowers
-git clone https://github.com/obra/superpowers.git ~/.codex/superpowers
-```
+2. Create the skills symlink:
+ ```bash
+ mkdir -p ~/.agents/skills
+ ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers
+ ```
-#### 2. Install Bootstrap
+3. Restart Codex.
-The bootstrap file is included in the repository at `.codex/superpowers-bootstrap.md`. Codex will automatically use it from the cloned location.
+### Windows
-#### 3. Verify Installation
+Use a junction instead of a symlink (works without Developer Mode):
-Tell Codex:
+```powershell
+New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
+cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers\skills"
+```
+
+## How It Works
+
+Codex has native skill discovery — it scans `~/.agents/skills/` at startup, parses SKILL.md frontmatter, and loads skills on demand. Superpowers skills are made visible through a single symlink:
```
-Run ~/.codex/superpowers/.codex/superpowers-codex find-skills to show available skills
+~/.agents/skills/superpowers/ → ~/.codex/superpowers/skills/
```
-You should see a list of available skills with descriptions.
+The `using-superpowers` skill is discovered automatically and enforces skill usage discipline — no additional configuration needed.
## Usage
-### Finding Skills
+Skills are discovered automatically. Codex activates them when:
+- You mention a skill by name (e.g., "use brainstorming")
+- The task matches a skill's description
+- The `using-superpowers` skill directs Codex to use one
-```
-Run ~/.codex/superpowers/.codex/superpowers-codex find-skills
-```
+### Project Skills
-### Loading a Skill
+Create project-specific skills in `.codex/skills/` within your project root:
-```
-Run ~/.codex/superpowers/.codex/superpowers-codex use-skill superpowers:brainstorming
+```bash
+mkdir -p .codex/skills/my-project-skill
```
-### Bootstrap All Skills
+Create `.codex/skills/my-project-skill/SKILL.md`:
-```
-Run ~/.codex/superpowers/.codex/superpowers-codex bootstrap
+```markdown
+---
+name: my-project-skill
+description: Use when [condition] - [what it does]
+---
+
+# My Project Skill
+
+[Your skill content here]
```
-This loads the complete bootstrap with all skill information.
+Project skills have the highest priority and override both personal and superpowers skills with the same name.
### Personal Skills
-Create your own skills in `~/.codex/skills/`:
+Create your own skills in `~/.agents/skills/`:
```bash
-mkdir -p ~/.codex/skills/my-skill
+mkdir -p ~/.agents/skills/my-skill
```
-Create `~/.codex/skills/my-skill/SKILL.md`:
+Create `~/.agents/skills/my-skill/SKILL.md`:
```markdown
---
@@ -83,71 +102,85 @@ description: Use when [condition] - [what it does]
[Your skill content here]
```
-Personal skills override superpowers skills with the same name.
-
-## Architecture
+The `description` field is how Codex decides when to activate a skill automatically — write it as a clear trigger condition.
-### Codex CLI Tool
+### Skill Priority
-**Location:** `~/.codex/superpowers/.codex/superpowers-codex`
+Skills are resolved with three-tier priority:
-A Node.js CLI script that provides three commands:
-- `bootstrap` - Load complete bootstrap with all skills
-- `use-skill ` - Load a specific skill
-- `find-skills` - List all available skills
-
-### Shared Core Module
-
-**Location:** `~/.codex/superpowers/lib/skills-core.js`
-
-The Codex implementation uses the shared `skills-core` module (ES module format) for skill discovery and parsing. This is the same module used by the OpenCode plugin, ensuring consistent behavior across platforms.
+1. **Project skills** (`.codex/skills/` in project root) - Highest priority
+2. **Personal skills** (`~/.agents/skills/`)
+3. **Superpowers skills** (`~/.agents/skills/superpowers/`) - via symlink
### Tool Mapping
Skills written for Claude Code are adapted for Codex with these mappings:
- `TodoWrite` → `update_plan`
-- `Task` with subagents → Tell user subagents aren't available, do work directly
-- `Skill` tool → `~/.codex/superpowers/.codex/superpowers-codex use-skill`
-- File operations → Native Codex tools
+- `Task` with subagents → `spawn_agent` + `wait` (or sequential if collab disabled)
+- `Skill` tool → native `$skill-name` mention
+- `Read`, `Write`, `Edit`, `Bash` → use native Codex equivalents
-## Updating
+## Manus Planning on Codex
-```bash
-cd ~/.codex/superpowers
-git pull
-```
+The `manus-planning` skill works on Codex with these considerations:
-## Troubleshooting
+- The 3-file system (`task_plan.md`, `findings.md`, `progress.md`) works identically
+- PreToolUse hooks via `docs/manus/.active` marker operate the same way
+- Use native file operations instead of Claude Code-specific tools
+- The archive system (`docs/manus/archive/`) is fully compatible
+- The 2-Action Rule (update `findings.md` after every 2 search/view operations) applies
+
+### Getting Started with Manus on Codex
-### Skills not found
+1. Ask Codex to "use manus-planning" or describe a complex task
+2. The skill creates the 3 files in `docs/manus/`
+3. The `.active` marker enables PreToolUse hook reminders
+4. Work persists across context resets and sessions
-1. Verify installation: `ls ~/.codex/superpowers/skills`
-2. Check CLI works: `~/.codex/superpowers/.codex/superpowers-codex find-skills`
-3. Verify skills have SKILL.md files
+## Ralph Integration on Codex
-### CLI script not executable
+When using Superpowers-NG with [Ralph](https://github.com/frankbria/ralph-claude-code):
+
+- Brainstorming Phase 0 (existing design detection) works natively
+- Manus planning files persist across Ralph loop resets
+- Skills are autonomous-mode aware — no user input needed in Ralph loops
+- Auto-resume via `.active` marker detection works with Ralph's `--continue` model
+
+## Updating
```bash
-chmod +x ~/.codex/superpowers/.codex/superpowers-codex
+cd ~/.codex/superpowers && git pull
```
-### Node.js errors
+Skills update instantly through the symlink.
-The CLI script requires Node.js. Verify:
+## Uninstalling
```bash
-node --version
+rm ~/.agents/skills/superpowers
```
-Should show v14 or higher (v18+ recommended for ES module support).
+**Windows (PowerShell):**
+```powershell
+Remove-Item "$env:USERPROFILE\.agents\skills\superpowers"
+```
-## Getting Help
+Optionally delete the clone: `rm -rf ~/.codex/superpowers` (Windows: `Remove-Item -Recurse -Force "$env:USERPROFILE\.codex\superpowers"`).
+
+## Troubleshooting
-- Report issues: https://github.com/obra/superpowers/issues
-- Main documentation: https://github.com/obra/superpowers
-- Blog post: https://blog.fsck.com/2025/10/27/skills-for-openai-codex/
+### Skills not showing up
-## Note
+1. Verify the symlink: `ls -la ~/.agents/skills/superpowers`
+2. Check skills exist: `ls ~/.codex/superpowers/skills`
+3. Restart Codex — skills are discovered at startup
+
+### Windows junction issues
+
+Junctions normally work without special permissions. If creation fails, try running PowerShell as administrator.
+
+## Getting Help
-Codex support is experimental and may require refinement based on user feedback. If you encounter issues, please report them on GitHub.
+- Report issues: https://github.com/OniReimu/superpowers-ng/issues
+- Main documentation: https://github.com/OniReimu/superpowers-ng
diff --git a/docs/README.opencode.md b/docs/README.opencode.md
index 122fe55ea..b6b7d1884 100644
--- a/docs/README.opencode.md
+++ b/docs/README.opencode.md
@@ -7,7 +7,7 @@ Complete guide for using Superpowers with [OpenCode.ai](https://opencode.ai).
Tell OpenCode:
```
-Clone https://github.com/obra/superpowers to ~/.config/opencode/superpowers, then create directory ~/.config/opencode/plugin, then symlink ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js to ~/.config/opencode/plugin/superpowers.js, then restart opencode.
+Clone https://github.com/OniReimu/superpowers-ng to ~/.config/opencode/superpowers, then create directory ~/.config/opencode/plugins, then symlink ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js to ~/.config/opencode/plugins/superpowers.js, then symlink ~/.config/opencode/superpowers/skills to ~/.config/opencode/skills/superpowers, then restart opencode.
```
## Manual Installation
@@ -15,59 +15,175 @@ Clone https://github.com/obra/superpowers to ~/.config/opencode/superpowers, the
### Prerequisites
- [OpenCode.ai](https://opencode.ai) installed
-- Node.js installed
- Git installed
-### Installation Steps
+### macOS / Linux
-#### 1. Install Superpowers
+```bash
+# 1. Install Superpowers (or update existing)
+if [ -d ~/.config/opencode/superpowers ]; then
+ cd ~/.config/opencode/superpowers && git pull
+else
+ git clone https://github.com/OniReimu/superpowers-ng.git ~/.config/opencode/superpowers
+fi
+
+# 2. Create directories
+mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills
+
+# 3. Remove old symlinks/directories if they exist
+rm -f ~/.config/opencode/plugins/superpowers.js
+rm -rf ~/.config/opencode/skills/superpowers
+
+# 4. Create symlinks
+ln -s ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js ~/.config/opencode/plugins/superpowers.js
+ln -s ~/.config/opencode/superpowers/skills ~/.config/opencode/skills/superpowers
+
+# 5. Restart OpenCode
+```
+
+#### Verify Installation
```bash
-mkdir -p ~/.config/opencode/superpowers
-git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers
+ls -l ~/.config/opencode/plugins/superpowers.js
+ls -l ~/.config/opencode/skills/superpowers
```
-#### 2. Register the Plugin
+Both should show symlinks pointing to the superpowers directory.
-OpenCode discovers plugins from `~/.config/opencode/plugin/`. Create a symlink:
+### Windows
-```bash
-mkdir -p ~/.config/opencode/plugin
-ln -sf ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js ~/.config/opencode/plugin/superpowers.js
+**Prerequisites:**
+- Git installed
+- Either **Developer Mode** enabled OR **Administrator privileges**
+ - Windows 10: Settings → Update & Security → For developers
+ - Windows 11: Settings → System → For developers
+
+Pick your shell below: [Command Prompt](#command-prompt) | [PowerShell](#powershell) | [Git Bash](#git-bash)
+
+#### Command Prompt
+
+Run as Administrator, or with Developer Mode enabled:
+
+```cmd
+:: 1. Install Superpowers
+git clone https://github.com/OniReimu/superpowers-ng.git "%USERPROFILE%\.config\opencode\superpowers"
+
+:: 2. Create directories
+mkdir "%USERPROFILE%\.config\opencode\plugins" 2>nul
+mkdir "%USERPROFILE%\.config\opencode\skills" 2>nul
+
+:: 3. Remove existing links (safe for reinstalls)
+del "%USERPROFILE%\.config\opencode\plugins\superpowers.js" 2>nul
+rmdir "%USERPROFILE%\.config\opencode\skills\superpowers" 2>nul
+
+:: 4. Create plugin symlink (requires Developer Mode or Admin)
+mklink "%USERPROFILE%\.config\opencode\plugins\superpowers.js" "%USERPROFILE%\.config\opencode\superpowers\.opencode\plugins\superpowers.js"
+
+:: 5. Create skills junction (works without special privileges)
+mklink /J "%USERPROFILE%\.config\opencode\skills\superpowers" "%USERPROFILE%\.config\opencode\superpowers\skills"
+
+:: 6. Restart OpenCode
```
-Alternatively, for project-local installation:
+#### PowerShell
+
+Run as Administrator, or with Developer Mode enabled:
+
+```powershell
+# 1. Install Superpowers
+git clone https://github.com/OniReimu/superpowers-ng.git "$env:USERPROFILE\.config\opencode\superpowers"
+
+# 2. Create directories
+New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode\plugins"
+New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode\skills"
+
+# 3. Remove existing links (safe for reinstalls)
+Remove-Item "$env:USERPROFILE\.config\opencode\plugins\superpowers.js" -Force -ErrorAction SilentlyContinue
+Remove-Item "$env:USERPROFILE\.config\opencode\skills\superpowers" -Force -ErrorAction SilentlyContinue
+
+# 4. Create plugin symlink (requires Developer Mode or Admin)
+New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.config\opencode\plugins\superpowers.js" -Target "$env:USERPROFILE\.config\opencode\superpowers\.opencode\plugins\superpowers.js"
+
+# 5. Create skills junction (works without special privileges)
+New-Item -ItemType Junction -Path "$env:USERPROFILE\.config\opencode\skills\superpowers" -Target "$env:USERPROFILE\.config\opencode\superpowers\skills"
+
+# 6. Restart OpenCode
+```
+
+#### Git Bash
+
+Note: Git Bash's native `ln` command copies files instead of creating symlinks. Use `cmd //c mklink` instead (the `//c` is Git Bash syntax for `/c`).
```bash
-# In your OpenCode project
-mkdir -p .opencode/plugin
-ln -sf ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js .opencode/plugin/superpowers.js
+# 1. Install Superpowers
+git clone https://github.com/OniReimu/superpowers-ng.git ~/.config/opencode/superpowers
+
+# 2. Create directories
+mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills
+
+# 3. Remove existing links (safe for reinstalls)
+rm -f ~/.config/opencode/plugins/superpowers.js 2>/dev/null
+rm -rf ~/.config/opencode/skills/superpowers 2>/dev/null
+
+# 4. Create plugin symlink (requires Developer Mode or Admin)
+cmd //c "mklink \"$(cygpath -w ~/.config/opencode/plugins/superpowers.js)\" \"$(cygpath -w ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js)\""
+
+# 5. Create skills junction (works without special privileges)
+cmd //c "mklink /J \"$(cygpath -w ~/.config/opencode/skills/superpowers)\" \"$(cygpath -w ~/.config/opencode/superpowers/skills)\""
+
+# 6. Restart OpenCode
+```
+
+#### WSL Users
+
+If running OpenCode inside WSL, use the [macOS / Linux](#macos--linux) instructions instead.
+
+#### Verify Installation
+
+**Command Prompt:**
+```cmd
+dir /AL "%USERPROFILE%\.config\opencode\plugins"
+dir /AL "%USERPROFILE%\.config\opencode\skills"
+```
+
+**PowerShell:**
+```powershell
+Get-ChildItem "$env:USERPROFILE\.config\opencode\plugins" | Where-Object { $_.LinkType }
+Get-ChildItem "$env:USERPROFILE\.config\opencode\skills" | Where-Object { $_.LinkType }
```
-#### 3. Restart OpenCode
+Look for `` or `` in the output.
+
+#### Troubleshooting Windows
+
+**"You do not have sufficient privilege" error:**
+- Enable Developer Mode in Windows Settings, OR
+- Right-click your terminal → "Run as Administrator"
-Restart OpenCode to load the plugin. Superpowers will automatically activate.
+**"Cannot create a file when that file already exists":**
+- Run the removal commands (step 3) first, then retry
+
+**Symlinks not working after git clone:**
+- Run `git config --global core.symlinks true` and re-clone
## Usage
### Finding Skills
-Use the `find_skills` tool to list all available skills:
+Use OpenCode's native `skill` tool to list all available skills:
```
-use find_skills tool
+use skill tool to list skills
```
### Loading a Skill
-Use the `use_skill` tool to load a specific skill:
+Use OpenCode's native `skill` tool to load a specific skill:
```
-use use_skill tool with skill_name: "superpowers:brainstorming"
+use skill tool to load superpowers-ng/brainstorming
```
-Skills are automatically inserted into the conversation and persist across context compaction.
-
### Personal Skills
Create your own skills in `~/.config/opencode/skills/`:
@@ -111,66 +227,53 @@ description: Use when [condition] - [what it does]
[Your skill content here]
```
-## Skill Priority
+## Skill Locations
-Skills are resolved with this priority order:
+OpenCode discovers skills from these locations:
1. **Project skills** (`.opencode/skills/`) - Highest priority
2. **Personal skills** (`~/.config/opencode/skills/`)
-3. **Superpowers skills** (`~/.config/opencode/superpowers/skills/`)
+3. **Superpowers skills** (`~/.config/opencode/skills/superpowers/`) - via symlink
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
### Automatic Context Injection
-The plugin automatically injects superpowers context via the chat.message hook on every session. No manual configuration needed.
-
-### Message Insertion Pattern
+The plugin automatically injects superpowers context via the `experimental.chat.system.transform` hook. This adds the "using-superpowers" skill content to the system prompt on every request.
-When you load a skill with `use_skill`, it's inserted as a user message with `noReply: true`. This ensures skills persist throughout long conversations, even when OpenCode compacts context.
+### Native Skills Integration
-### Compaction Resilience
-
-The plugin listens for `session.compacted` events and automatically re-injects the core superpowers bootstrap to maintain functionality after context compaction.
+Superpowers uses OpenCode's native `skill` tool for skill discovery and loading. Skills are symlinked into `~/.config/opencode/skills/superpowers/` so they appear alongside your personal and project skills.
### Tool Mapping
-Skills written for Claude Code are automatically adapted for OpenCode. The plugin provides mapping instructions:
+Skills written for Claude Code are automatically adapted for OpenCode. The bootstrap provides mapping instructions:
- `TodoWrite` → `update_plan`
- `Task` with subagents → OpenCode's `@mention` system
-- `Skill` tool → `use_skill` custom tool
+- `Skill` tool → OpenCode's native `skill` tool
- File operations → Native OpenCode tools
## Architecture
### Plugin Structure
-**Location:** `~/.config/opencode/superpowers/.opencode/plugin/superpowers.js`
+**Location:** `~/.config/opencode/superpowers/.opencode/plugins/superpowers.js`
**Components:**
-- Two custom tools: `use_skill`, `find_skills`
-- chat.message hook for initial context injection
-- event handler for session.compacted re-injection
-- Uses shared `lib/skills-core.js` module (also used by Codex)
-
-### Shared Core Module
+- `experimental.chat.system.transform` hook for bootstrap injection
+- Reads and injects the "using-superpowers" skill content
-**Location:** `~/.config/opencode/superpowers/lib/skills-core.js`
+### Skills
-**Functions:**
-- `extractFrontmatter()` - Parse skill metadata
-- `stripFrontmatter()` - Remove metadata from content
-- `findSkillsInDir()` - Recursive skill discovery
-- `resolveSkillPath()` - Skill resolution with shadowing
-- `checkForUpdates()` - Git update detection
+**Location:** `~/.config/opencode/skills/superpowers/` (symlink to `~/.config/opencode/superpowers/skills/`)
-This module is shared between OpenCode and Codex implementations for code reuse.
+Skills are discovered by OpenCode's native skill system. Each skill has a `SKILL.md` file with YAML frontmatter.
## Updating
@@ -185,50 +288,48 @@ Restart OpenCode to load the updates.
### Plugin not loading
-1. Check plugin file exists: `ls ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js`
-2. Check symlink: `ls -l ~/.config/opencode/plugin/superpowers.js`
+1. Check plugin exists: `ls ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js`
+2. Check symlink/junction: `ls -l ~/.config/opencode/plugins/` (macOS/Linux) or `dir /AL %USERPROFILE%\.config\opencode\plugins` (Windows)
3. Check OpenCode logs: `opencode run "test" --print-logs --log-level DEBUG`
-4. Look for: `service=plugin path=file:///.../superpowers.js loading plugin`
+4. Look for plugin loading message in logs
### Skills not found
-1. Verify skills directory: `ls ~/.config/opencode/superpowers/skills`
-2. Use `find_skills` tool to see what's discovered
-3. Check skill structure: each skill needs a `SKILL.md` file
+1. Verify skills symlink: `ls -l ~/.config/opencode/skills/superpowers` (should point to superpowers/skills/)
+2. Use OpenCode's `skill` tool to list available skills
+3. Check skill structure: each skill needs a `SKILL.md` file with valid frontmatter
-### Tools not working
+### Windows: Module not found error
-1. Verify plugin loaded: Check OpenCode logs for plugin loading message
-2. Check Node.js version: The plugin requires Node.js for ES modules
-3. Test plugin manually: `node --input-type=module -e "import('file://~/.config/opencode/plugin/superpowers.js').then(m => console.log(Object.keys(m)))"`
+If you see `Cannot find module` errors on Windows:
+- **Cause:** Git Bash `ln -sf` copies files instead of creating symlinks
+- **Fix:** Use `mklink /J` directory junctions instead (see Windows installation steps)
-### Context not injecting
+### Bootstrap not appearing
-1. Check if chat.message hook is working
-2. Verify using-superpowers skill exists
-3. Check OpenCode version (requires recent version with plugin support)
+1. Verify using-superpowers skill exists: `ls ~/.config/opencode/superpowers/skills/using-superpowers/SKILL.md`
+2. Check OpenCode version supports `experimental.chat.system.transform` hook
+3. Restart OpenCode after plugin changes
## Getting Help
-- Report issues: https://github.com/obra/superpowers/issues
-- Main documentation: https://github.com/obra/superpowers
+- Report issues: https://github.com/OniReimu/superpowers-ng/issues
+- Main documentation: https://github.com/OniReimu/superpowers-ng
- OpenCode docs: https://opencode.ai/docs/
## Testing
-The implementation includes an automated test suite at `tests/opencode/`:
+Verify your installation:
```bash
-# Run all tests
-./tests/opencode/run-tests.sh --integration --verbose
+# Check plugin loads
+opencode run --print-logs "hello" 2>&1 | grep -i superpowers
+
+# Check skills are discoverable
+opencode run "use skill tool to list all skills" 2>&1 | grep -i superpowers
-# Run specific test
-./tests/opencode/run-tests.sh --test test-tools.sh
+# Check bootstrap injection
+opencode run "what superpowers do you have?"
```
-Tests verify:
-- Plugin loading
-- Skills-core library functionality
-- Tool execution (use_skill, find_skills)
-- Skill priority resolution
-- Proper isolation with temp HOME
+The agent should mention having superpowers and be able to list skills from `superpowers/`.
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..9ad490d1b 100644
--- a/hooks/hooks.json
+++ b/hooks/hooks.json
@@ -6,7 +6,19 @@
"hooks": [
{
"type": "command",
- "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start.sh"
+ "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh",
+ "async": false
+ }
+ ]
+ }
+ ],
+ "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 < [args...]
REM The script should be in the same directory as this wrapper
diff --git a/hooks/session-start.sh b/hooks/session-start.sh
index f5d94497d..29b0c830c 100755
--- a/hooks/session-start.sh
+++ b/hooks/session-start.sh
@@ -17,34 +17,33 @@ fi
# Read using-superpowers content
using_superpowers_content=$(cat "${PLUGIN_ROOT}/skills/using-superpowers/SKILL.md" 2>&1 || echo "Error reading using-superpowers skill")
-# Escape outputs for JSON using pure bash
+# Escape string for JSON embedding using bash parameter substitution.
+# Each ${s//old/new} is a single C-level pass - orders of magnitude
+# faster than the character-by-character loop this replaces.
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"
+ local s="$1"
+ s="${s//\\/\\\\}"
+ s="${s//\"/\\\"}"
+ s="${s//$'\n'/\\n}"
+ s="${s//$'\r'/\\r}"
+ s="${s//$'\t'/\\t}"
+ printf '%s' "$s"
}
using_superpowers_escaped=$(escape_for_json "$using_superpowers_content")
warning_escaped=$(escape_for_json "$warning_message")
+session_context="\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"
-# Output context injection as JSON
+# Output context injection as JSON.
+# Keep both shapes for compatibility:
+# - Cursor hooks expect additional_context.
+# - Claude hooks expect hookSpecificOutput.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": "${session_context}"
}
}
EOF
diff --git a/lib/skills-core.js b/lib/skills-core.js
deleted file mode 100644
index 5e5bb7012..000000000
--- a/lib/skills-core.js
+++ /dev/null
@@ -1,208 +0,0 @@
-import fs from 'fs';
-import path from 'path';
-import { execSync } from 'child_process';
-
-/**
- * Extract YAML frontmatter from a skill file.
- * Current format:
- * ---
- * name: skill-name
- * description: Use when [condition] - [what it does]
- * ---
- *
- * @param {string} filePath - Path to SKILL.md file
- * @returns {{name: string, description: string}}
- */
-function extractFrontmatter(filePath) {
- try {
- const content = fs.readFileSync(filePath, 'utf8');
- const lines = content.split('\n');
-
- let inFrontmatter = false;
- let name = '';
- let description = '';
-
- for (const line of lines) {
- if (line.trim() === '---') {
- if (inFrontmatter) break;
- inFrontmatter = true;
- continue;
- }
-
- if (inFrontmatter) {
- const match = line.match(/^(\w+):\s*(.*)$/);
- if (match) {
- const [, key, value] = match;
- switch (key) {
- case 'name':
- name = value.trim();
- break;
- case 'description':
- description = value.trim();
- break;
- }
- }
- }
- }
-
- return { name, description };
- } catch (error) {
- return { name: '', description: '' };
- }
-}
-
-/**
- * Find all SKILL.md files in a directory recursively.
- *
- * @param {string} dir - Directory to search
- * @param {string} sourceType - 'personal' or 'superpowers' for namespacing
- * @param {number} maxDepth - Maximum recursion depth (default: 3)
- * @returns {Array<{path: string, name: string, description: string, sourceType: string}>}
- */
-function findSkillsInDir(dir, sourceType, maxDepth = 3) {
- const skills = [];
-
- if (!fs.existsSync(dir)) return skills;
-
- function recurse(currentDir, depth) {
- if (depth > maxDepth) return;
-
- const entries = fs.readdirSync(currentDir, { withFileTypes: true });
-
- for (const entry of entries) {
- const fullPath = path.join(currentDir, entry.name);
-
- if (entry.isDirectory()) {
- // Check for SKILL.md in this directory
- const skillFile = path.join(fullPath, 'SKILL.md');
- if (fs.existsSync(skillFile)) {
- const { name, description } = extractFrontmatter(skillFile);
- skills.push({
- path: fullPath,
- skillFile: skillFile,
- name: name || entry.name,
- description: description || '',
- sourceType: sourceType
- });
- }
-
- // Recurse into subdirectories
- recurse(fullPath, depth + 1);
- }
- }
- }
-
- recurse(dir, 0);
- return skills;
-}
-
-/**
- * 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} 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;
-
- // Try personal skills first (unless explicitly superpowers:)
- if (!forceSuperpowers && personalDir) {
- const personalPath = path.join(personalDir, actualSkillName);
- const personalSkillFile = path.join(personalPath, 'SKILL.md');
- if (fs.existsSync(personalSkillFile)) {
- return {
- skillFile: personalSkillFile,
- sourceType: 'personal',
- skillPath: actualSkillName
- };
- }
- }
-
- // Try superpowers skills
- if (superpowersDir) {
- const superpowersPath = path.join(superpowersDir, actualSkillName);
- const superpowersSkillFile = path.join(superpowersPath, 'SKILL.md');
- if (fs.existsSync(superpowersSkillFile)) {
- return {
- skillFile: superpowersSkillFile,
- sourceType: 'superpowers',
- skillPath: actualSkillName
- };
- }
- }
-
- return null;
-}
-
-/**
- * Check if a git repository has updates available.
- *
- * @param {string} repoDir - Path to git repository
- * @returns {boolean} - True if updates are available
- */
-function checkForUpdates(repoDir) {
- try {
- // Quick check with 3 second timeout to avoid delays if network is down
- const output = execSync('git fetch origin && git status --porcelain=v1 --branch', {
- cwd: repoDir,
- timeout: 3000,
- encoding: 'utf8',
- stdio: 'pipe'
- });
-
- // Parse git status output to see if we're behind
- const statusLines = output.split('\n');
- for (const line of statusLines) {
- if (line.startsWith('## ') && line.includes('[behind ')) {
- return true; // We're behind remote
- }
- }
- return false; // Up to date
- } catch (error) {
- // Network down, git error, timeout, etc. - don't block bootstrap
- return false;
- }
-}
-
-/**
- * Strip YAML frontmatter from skill content, returning just the content.
- *
- * @param {string} content - Full content including frontmatter
- * @returns {string} - Content without frontmatter
- */
-function stripFrontmatter(content) {
- const lines = content.split('\n');
- let inFrontmatter = false;
- let frontmatterEnded = false;
- const contentLines = [];
-
- for (const line of lines) {
- if (line.trim() === '---') {
- if (inFrontmatter) {
- frontmatterEnded = true;
- continue;
- }
- inFrontmatter = true;
- continue;
- }
-
- if (frontmatterEnded || !inFrontmatter) {
- contentLines.push(line);
- }
- }
-
- return contentLines.join('\n').trim();
-}
-
-export {
- extractFrontmatter,
- findSkillsInDir,
- resolveSkillPath,
- checkForUpdates,
- stripFrontmatter
-};
diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md
index 2fd19ba1e..fefa00de7 100644
--- a/skills/brainstorming/SKILL.md
+++ b/skills/brainstorming/SKILL.md
@@ -9,25 +9,96 @@ description: "You MUST use this before any creative work - creating features, bu
Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
-Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far.
+Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.
+
+
+Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
+
+
+## Anti-Pattern: "This Is Too Simple To Need A Design"
+
+Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
+
+## Checklist
+
+You MUST create a task for each of these items and complete them in order:
+
+1. **Check for existing design** — look for prior design docs before starting fresh
+2. **Explore project context** — check files, docs, recent commits
+3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
+4. **Propose 2-3 approaches** — with trade-offs and your recommendation
+5. **Present design** — in sections scaled to their complexity, get user approval after each section
+6. **Write design doc** — save to `docs/plans/YYYY-MM-DD--design.md` and commit
+7. **Transition to implementation** — choose planning system and invoke appropriate skill
+
+## Process Flow
+
+```dot
+digraph brainstorming {
+ "Check for existing design" [shape=box];
+ "Explore project context" [shape=box];
+ "Ask clarifying questions" [shape=box];
+ "Propose 2-3 approaches" [shape=box];
+ "Present design sections" [shape=box];
+ "User approves design?" [shape=diamond];
+ "Write design doc" [shape=box];
+ "Choose planning system" [shape=box];
+ "Invoke writing-plans skill" [shape=doublecircle];
+ "Invoke manus-planning skill" [shape=doublecircle];
+
+ "Check for existing design" -> "Explore project context";
+ "Explore project context" -> "Ask clarifying questions";
+ "Ask clarifying questions" -> "Propose 2-3 approaches";
+ "Propose 2-3 approaches" -> "Present design sections";
+ "Present design sections" -> "User approves design?";
+ "User approves design?" -> "Present design sections" [label="no, revise"];
+ "User approves design?" -> "Write design doc" [label="yes"];
+ "Write design doc" -> "Choose planning system";
+ "Choose planning system" -> "Invoke writing-plans skill" [label="native"];
+ "Choose planning system" -> "Invoke manus-planning skill" [label="manus"];
+}
+```
+
+**The terminal state is invoking a planning skill.** Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. The ONLY skills you invoke after brainstorming are writing-plans or manus-planning.
## 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
+- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
- Ask after each section whether it looks right so far
- Cover: architecture, components, data flow, error handling, testing
- Be ready to go back and clarify if something doesn't make sense
@@ -41,8 +112,20 @@ 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
+- Ask workspace preference:
+ 1. **Use a git worktree (recommended)** - isolated workspace
+ 2. **Work directly in this repo (no worktrees)** - faster, less isolation
+- Based on choice:
+ - **Worktree**: Use superpowers-ng:using-git-worktrees to create isolated workspace
+ - **Direct**: Ensure safe setup in current repo:
+ - Be on a feature branch (not main/master); if needed: `git checkout -b `
+ - Ensure clean working tree (`git status` clean) or stash/commit before proceeding
+- 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
@@ -50,5 +133,5 @@ Start by understanding the current project context, then ask questions one at a
- **Multiple choice preferred** - Easier to answer than open-ended when possible
- **YAGNI ruthlessly** - Remove unnecessary features from all designs
- **Explore alternatives** - Always propose 2-3 approaches before settling
-- **Incremental validation** - Present design in sections, validate each
+- **Incremental validation** - Present design, get approval before moving on
- **Be flexible** - Go back and clarify when something doesn't make sense
diff --git a/skills/executing-plans/SKILL.md b/skills/executing-plans/SKILL.md
index ca77290c8..45c056a6a 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
@@ -74,3 +74,11 @@ After all tasks complete and verified:
- Reference skills when plan says to
- Between batches: just report and wait
- Stop when blocked, don't guess
+- Never start implementation on main/master branch without explicit user consent
+
+## Integration
+
+**Required workflow skills:**
+- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
+- **superpowers:writing-plans** - Creates the plan this skill executes
+- **superpowers:finishing-a-development-branch** - Complete development after all tasks
diff --git a/skills/finishing-a-development-branch/SKILL.md b/skills/finishing-a-development-branch/SKILL.md
index c308b43b4..9da020854 100644
--- a/skills/finishing-a-development-branch/SKILL.md
+++ b/skills/finishing-a-development-branch/SKILL.md
@@ -9,7 +9,7 @@ description: Use when implementation is complete, all tests pass, and you need t
Guide completion of development work by presenting clear options and handling chosen workflow.
-**Core principle:** Verify tests → Present options → Execute choice → Clean up.
+**Core principle:** Verify tests → Present options → Execute choice → Clean up (if applicable).
**Announce at start:** "I'm using the finishing-a-development-branch skill to complete this work."
@@ -84,7 +84,7 @@ git merge
git branch -d
```
-Then: Cleanup worktree (Step 5)
+Then: Optional cleanup (Step 5)
#### Option 2: Push and Create PR
@@ -103,13 +103,13 @@ EOF
)"
```
-Then: Cleanup worktree (Step 5)
+Then: Optional cleanup (Step 5)
#### Option 3: Keep As-Is
-Report: "Keeping branch . Worktree preserved at ."
+Report: "Keeping branch as-is."
-**Don't cleanup worktree.**
+**Don't cleanup automatically.**
#### Option 4: Discard
@@ -118,7 +118,7 @@ Report: "Keeping branch . Worktree preserved at ."
This will permanently delete:
- Branch
- All commits:
-- Worktree at
+- Any associated worktree (if you created one)
Type 'discard' to confirm.
```
@@ -131,23 +131,23 @@ git checkout
git branch -D
```
-Then: Cleanup worktree (Step 5)
+Then: Optional cleanup (Step 5)
-### Step 5: Cleanup Worktree
+### Step 5: Optional Cleanup (Worktree Only)
-**For Options 1, 2, 4:**
+If you used a git worktree for this work, you may want to remove it now.
-Check if in worktree:
+Check if in a worktree:
```bash
git worktree list | grep $(git branch --show-current)
```
-If yes:
+If yes, and you want to remove it:
```bash
git worktree remove
```
-**For Option 3:** Keep worktree.
+If not in a worktree (direct-on-repo): nothing to clean up here.
## Quick Reference
@@ -170,7 +170,7 @@ git worktree remove
**Automatic worktree cleanup**
- **Problem:** Remove worktree when might need it (Option 2, 3)
-- **Fix:** Only cleanup for Options 1 and 4
+- **Fix:** Treat cleanup as optional; default is to keep the worktree for Options 2 & 3
**No confirmation for discard**
- **Problem:** Accidentally delete work
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..284157c51
--- /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 **optional cleanup** (worktree removal only if a worktree was used)
+
+---
+
+### 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..6ebec06f4 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";
}
```
@@ -199,6 +199,7 @@ Done!
## Red Flags
**Never:**
+- Start implementation on main/master branch without explicit user consent
- Skip reviews (spec compliance OR code quality)
- Proceed with unfixed issues
- Dispatch multiple implementation subagents in parallel (conflicts)
@@ -229,12 +230,13 @@ 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:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
+- **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-git-worktrees/SKILL.md b/skills/using-git-worktrees/SKILL.md
index 9d52d80cc..2bc992128 100644
--- a/skills/using-git-worktrees/SKILL.md
+++ b/skills/using-git-worktrees/SKILL.md
@@ -11,6 +11,10 @@ Git worktrees create isolated workspaces sharing the same repository, allowing w
**Core principle:** Systematic directory selection + safety verification = reliable isolation.
+**Opt-out (no worktrees):** If the user prefers to work directly in the repo, do **not** run this skill. Instead:
+- Work on a feature branch (not main/master)
+- Ensure clean working tree (`git status` clean) or stash/commit before starting
+
**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
## Directory Selection Process
@@ -210,8 +214,9 @@ Ready to implement auth feature
**Called by:**
- **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows
+- **subagent-driven-development** - REQUIRED before executing any tasks
+- **executing-plans** - REQUIRED before executing any tasks
- Any skill needing isolated workspace
**Pairs with:**
- **finishing-a-development-branch** - REQUIRED for cleanup after work complete
-- **executing-plans** or **subagent-driven-development** - Work happens in this worktree
diff --git a/skills/using-superpowers/SKILL.md b/skills/using-superpowers/SKILL.md
index 7867fcfc0..4dfa79c92 100644
--- a/skills/using-superpowers/SKILL.md
+++ b/skills/using-superpowers/SKILL.md
@@ -26,6 +26,9 @@ This is not negotiable. This is not optional. You cannot rationalize your way ou
```dot
digraph skill_flow {
"User message received" [shape=doublecircle];
+ "About to EnterPlanMode?" [shape=doublecircle];
+ "Already brainstormed?" [shape=diamond];
+ "Invoke brainstorming skill" [shape=box];
"Might any skill apply?" [shape=diamond];
"Invoke Skill tool" [shape=box];
"Announce: 'Using [skill] to [purpose]'" [shape=box];
@@ -34,6 +37,11 @@ digraph skill_flow {
"Follow skill exactly" [shape=box];
"Respond (including clarifications)" [shape=doublecircle];
+ "About to EnterPlanMode?" -> "Already brainstormed?";
+ "Already brainstormed?" -> "Invoke brainstorming skill" [label="no"];
+ "Already brainstormed?" -> "Might any skill apply?" [label="yes"];
+ "Invoke brainstorming skill" -> "Might any skill apply?";
+
"User message received" -> "Might any skill apply?";
"Might any skill apply?" -> "Invoke Skill tool" [label="yes, even 1%"];
"Might any skill apply?" -> "Respond (including clarifications)" [label="definitely not"];
@@ -82,6 +90,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..f121f678f 100644
--- a/skills/writing-plans/SKILL.md
+++ b/skills/writing-plans/SKILL.md
@@ -13,7 +13,13 @@ Assume they are a skilled developer, but know almost nothing about our toolset o
**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
-**Context:** This should be run in a dedicated worktree (created by brainstorming skill).
+**Context:** This can be run either:
+- **In a git worktree (recommended)** - isolated workspace (often created by brainstorming via `using-git-worktrees`)
+- **Directly in the repo (no worktrees)** - supported when the user prefers it
+
+**If working directly in the repo:** ensure a safe baseline before planning/execution:
+- Be on a feature branch (not main/master); if needed: `git checkout -b `
+- Ensure clean working tree (`git status` clean) or stash/commit before starting implementation
**Save plans to:** `docs/plans/YYYY-MM-DD-.md`
@@ -33,7 +39,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]
@@ -46,7 +52,7 @@ Assume they are a skilled developer, but know almost nothing about our toolset o
## Task Structure
-```markdown
+````markdown
### Task N: [Component Name]
**Files:**
@@ -85,7 +91,7 @@ Expected: PASS
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
```
-```
+````
## Remember
- Exact file paths always
@@ -107,10 +113,12 @@ 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
+- Guide them to open a new session in the chosen workspace:
+ - **If using worktrees:** open the session in the worktree path
+ - **If direct-on-repo:** open the session in the repo on the feature branch
+- **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..4f69fc42f 100644
--- a/skills/writing-skills/SKILL.md
+++ b/skills/writing-skills/SKILL.md
@@ -9,13 +9,13 @@ description: Use when creating new skills, editing existing skills, or verifying
**Writing skills IS Test-Driven Development applied to process documentation.**
-**Personal skills live in agent-specific directories (`~/.claude/skills` for Claude Code, `~/.codex/skills` for Codex)**
+**Personal skills live in agent-specific directories (`~/.claude/skills` for Claude Code, `~/.agents/skills/` for Codex)**
You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).
**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..7027ccc6e 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.
@@ -324,7 +324,7 @@ Before deploying skill, verify you followed RED-GREEN-REFACTOR:
- [ ] Added explicit counters for each loophole
- [ ] Updated rationalization table
- [ ] Updated red flags list
-- [ ] Updated description ith violation symptoms
+- [ ] Updated description with violation symptoms
- [ ] Re-tested - agent still complies
- [ ] Meta-tested to verify clarity
- [ ] Agent follows rule under maximum pressure
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/claude-code/test-subagent-driven-development.sh b/tests/claude-code/test-subagent-driven-development.sh
index 8edea06fa..20d8d4c7e 100755
--- a/tests/claude-code/test-subagent-driven-development.sh
+++ b/tests/claude-code/test-subagent-driven-development.sh
@@ -14,7 +14,7 @@ echo "Test 1: Skill loading..."
output=$(run_claude "What is the subagent-driven-development skill? Describe its key steps briefly." 30)
-if assert_contains "$output" "subagent-driven-development" "Skill is recognized"; then
+if assert_contains "$output" "subagent-driven-development\|Subagent-Driven Development\|Subagent Driven" "Skill is recognized"; then
: # pass
else
exit 1
@@ -136,4 +136,30 @@ fi
echo ""
+# Test 8: Verify worktree requirement
+echo "Test 8: Worktree requirement..."
+
+output=$(run_claude "What workflow skills are required before using subagent-driven-development? List any prerequisites or required skills." 30)
+
+if assert_contains "$output" "using-git-worktrees\|worktree" "Mentions worktree requirement"; then
+ : # pass
+else
+ exit 1
+fi
+
+echo ""
+
+# Test 9: Verify main branch warning
+echo "Test 9: Main branch red flag..."
+
+output=$(run_claude "In subagent-driven-development, is it okay to start implementation directly on the main branch?" 30)
+
+if assert_contains "$output" "worktree\|feature.*branch\|not.*main\|never.*main\|avoid.*main\|don't.*main\|consent\|permission" "Warns against main branch"; then
+ : # pass
+else
+ exit 1
+fi
+
+echo ""
+
echo "=== All subagent-driven-development skill tests passed ==="
diff --git a/tests/opencode/setup.sh b/tests/opencode/setup.sh
index 4aea82e0d..0defde2f0 100755
--- a/tests/opencode/setup.sh
+++ b/tests/opencode/setup.sh
@@ -18,13 +18,13 @@ cp -r "$REPO_ROOT/lib" "$HOME/.config/opencode/superpowers/"
cp -r "$REPO_ROOT/skills" "$HOME/.config/opencode/superpowers/"
# Copy plugin directory
-mkdir -p "$HOME/.config/opencode/superpowers/.opencode/plugin"
-cp "$REPO_ROOT/.opencode/plugin/superpowers.js" "$HOME/.config/opencode/superpowers/.opencode/plugin/"
+mkdir -p "$HOME/.config/opencode/superpowers/.opencode/plugins"
+cp "$REPO_ROOT/.opencode/plugins/superpowers.js" "$HOME/.config/opencode/superpowers/.opencode/plugins/"
# Register plugin via symlink
-mkdir -p "$HOME/.config/opencode/plugin"
-ln -sf "$HOME/.config/opencode/superpowers/.opencode/plugin/superpowers.js" \
- "$HOME/.config/opencode/plugin/superpowers.js"
+mkdir -p "$HOME/.config/opencode/plugins"
+ln -sf "$HOME/.config/opencode/superpowers/.opencode/plugins/superpowers.js" \
+ "$HOME/.config/opencode/plugins/superpowers.js"
# Create test skills in different locations for testing
@@ -57,8 +57,8 @@ PROJECT_SKILL_MARKER_67890
EOF
echo "Setup complete: $TEST_HOME"
-echo "Plugin installed to: $HOME/.config/opencode/superpowers/.opencode/plugin/superpowers.js"
-echo "Plugin registered at: $HOME/.config/opencode/plugin/superpowers.js"
+echo "Plugin installed to: $HOME/.config/opencode/superpowers/.opencode/plugins/superpowers.js"
+echo "Plugin registered at: $HOME/.config/opencode/plugins/superpowers.js"
echo "Test project at: $TEST_HOME/test-project"
# Helper function for cleanup (call from tests or trap)
diff --git a/tests/opencode/test-plugin-loading.sh b/tests/opencode/test-plugin-loading.sh
index 11ae02b72..052e9dee8 100755
--- a/tests/opencode/test-plugin-loading.sh
+++ b/tests/opencode/test-plugin-loading.sh
@@ -15,15 +15,15 @@ trap cleanup_test_env EXIT
# Test 1: Verify plugin file exists and is registered
echo "Test 1: Checking plugin registration..."
-if [ -L "$HOME/.config/opencode/plugin/superpowers.js" ]; then
+if [ -L "$HOME/.config/opencode/plugins/superpowers.js" ]; then
echo " [PASS] Plugin symlink exists"
else
- echo " [FAIL] Plugin symlink not found at $HOME/.config/opencode/plugin/superpowers.js"
+ echo " [FAIL] Plugin symlink not found at $HOME/.config/opencode/plugins/superpowers.js"
exit 1
fi
# Verify symlink target exists
-if [ -f "$(readlink -f "$HOME/.config/opencode/plugin/superpowers.js")" ]; then
+if [ -f "$(readlink -f "$HOME/.config/opencode/plugins/superpowers.js")" ]; then
echo " [PASS] Plugin symlink target exists"
else
echo " [FAIL] Plugin symlink target does not exist"
@@ -60,7 +60,7 @@ fi
# Test 5: Verify plugin JavaScript syntax (basic check)
echo "Test 5: Checking plugin JavaScript syntax..."
-plugin_file="$HOME/.config/opencode/superpowers/.opencode/plugin/superpowers.js"
+plugin_file="$HOME/.config/opencode/superpowers/.opencode/plugins/superpowers.js"
if node --check "$plugin_file" 2>/dev/null; then
echo " [PASS] Plugin JavaScript syntax is valid"
else
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..de92eeb13 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"
@@ -77,6 +77,7 @@ claude -p "$PROMPT" \
--plugin-dir "$PLUGIN_DIR" \
--dangerously-skip-permissions \
--output-format stream-json \
+ --verbose \
> "$LOG_FILE" 2>&1 || true
# Extract final stats
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"