Skip to content

Add manus-planning skill and rebrand to superpowers-ng #255

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
OniReimu wants to merge 1 commit into from
Closed

Add manus-planning skill and rebrand to superpowers-ng #255

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 20 additions & 8 deletions .claude-plugin/plugin.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,25 @@
{
"name": "superpowers",
"description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
"version": "4.0.3",
"name": "superpowers-ng",
"description": "Enhanced fork of superpowers with Manus-style persistent planning for long-running tasks and context resets",
"version": "0.1.0",
"author": {
"name": "Jesse Vincent",
"email": "jesse@fsck.com"
"name": "OniReimu",
"url": "https://github.com/OniReimu"
},
"homepage": "https://github.com/obra/superpowers",
"repository": "https://github.com/obra/superpowers",
"homepage": "https://github.com/OniReimu/superpowers",
"repository": "https://github.com/OniReimu/superpowers",
"license": "MIT",
"keywords": ["skills", "tdd", "debugging", "collaboration", "best-practices", "workflows"]
"keywords": ["skills", "tdd", "debugging", "collaboration", "best-practices", "workflows", "manus", "planning", "persistent-memory"],
"credits": [
{
"name": "Jesse Vincent (obra)",
"role": "Original Superpowers author",
"url": "https://github.com/obra/superpowers"
},
{
"name": "Ahmad Othman Ammar Adi (OthmanAdi)",
"role": "Planning-with-files author",
"url": "https://github.com/OthmanAdi/planning-with-files"
}
]
}
179 changes: 108 additions & 71 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,45 +1,76 @@
# Superpowers
# Superpowers-NG (Next Generation)

Superpowers is a complete software development workflow for your coding agents, built on top of a set of composable "skills" and some initial instructions that make sure your agent uses them.
**Superpowers-NG** is an enhanced fork of [obra/superpowers](https://github.com/obra/superpowers) with integrated **Manus-style persistent planning** for complex, long-running tasks.

## How it works
## What's New in NG

It starts from the moment you fire up your coding agent. As soon as it sees that you're building something, it *doesn't* just jump into trying to write code. Instead, it steps back and asks you what you're really trying to do.
### Manus Planning: Persistent Memory Across Context Resets

Once it's teased a spec out of the conversation, it shows it to you in chunks short enough to actually read and digest.
The flagship feature is `manus-planning`, a file-based planning system that survives context resets and enables multi-session work.

After you've signed off on the design, your agent puts together an implementation plan that's clear enough for an enthusiastic junior engineer with poor taste, no judgement, no project context, and an aversion to testing to follow. It emphasizes true red/green TDD, YAGNI (You Aren't Gonna Need It), and DRY.
**Native vs Manus Planning:**

Next up, once you say "go", it launches a *subagent-driven-development* process, having agents work through each engineering task, inspecting and reviewing their work, and continuing forward. It's not uncommon for Claude to be able to work autonomously for a couple hours at a time without deviating from the plan you put together.
| Aspect | Native (Original) | Manus (New) |
|--------|-------------------|-------------|
| **Skills** | writing-plans + executing-plans | manus-planning |
| **Memory** | In-memory (TodoWrite) | Persistent files (`docs/manus/`) |
| **Best for** | Short tasks (<30 min), interactive development | Long autonomous runs, multi-session projects, >50 tool calls |
| **Progress tracking** | Lost on context reset | Survives context resets |
| **Research storage** | Embedded in conversation | Persistent `findings.md` |

There's a bunch more to it, but that's the core of the system. And because the skills trigger automatically, you don't need to do anything special. Your coding agent just has Superpowers.
**The 3 Files:**
- `task_plan.md` - Goal, 5 phases, decisions, errors
- `findings.md` - Requirements, research, resources (CRITICAL for visual/browser content)
- `progress.md` - Session log, test results, 5-question reboot check

**When to use Manus:**
- Tasks requiring >50 tool calls
- Multi-session projects spanning days
- Complex research with web searches/images
- When context might reset mid-task

## Sponsorship
**How it works:**
1. Create marker file `docs/manus/.active` to enable PreToolUse hooks
2. Hooks automatically show plan preview before Write/Edit/Bash operations
3. 2-Action Rule: Update `findings.md` after every 2 search/view operations
4. On completion: Remove marker, invoke `finishing-a-development-branch`

If Superpowers has helped you do stuff that makes money and you are so inclined, I'd greatly appreciate it if you'd consider [sponsoring my opensource work](https://github.com/sponsors/obra).
**Brainstorming integration:**
After design completion, brainstorming now offers both planning options. For Manus, design content is automatically copied into `findings.md`.

Thanks!
## How It Works (Original Superpowers)

- Jesse
Superpowers is a complete software development workflow for your coding agents, built on composable "skills" that trigger automatically.

When you start building something, your agent:
1. **Asks questions** to understand what you're really trying to do
2. **Shows the design** in digestible chunks for your approval
3. **Creates an implementation plan** clear enough for a junior engineer to follow
4. **Executes autonomously** through subagent-driven development

## Installation
The core philosophy: **Test-Driven Development**, **YAGNI**, **DRY**, and **systematic over ad-hoc**.

**Note:** Installation differs by platform. Claude Code has a built-in plugin system. Codex and OpenCode require manual setup.
## Installation

### Claude Code (via Plugin Marketplace)
**Note:** Installation instructions will be updated once the marketplace is configured.

In Claude Code, register the marketplace first:
### Claude Code (Planned)

```bash
/plugin marketplace add obra/superpowers-marketplace
# Will be available via marketplace:
/plugin marketplace add OniReimu/superpowers-ng-marketplace
/plugin install superpowers-ng@superpowers-ng-marketplace
```

Then install the plugin from this marketplace:
### Manual Installation (Current)

```bash
/plugin install superpowers@superpowers-marketplace
# Clone the repository
git clone https://github.com/OniReimu/superpowers.git
cd superpowers

# Install as a local plugin
# (Instructions TBD based on Claude Code local plugin support)
```

### Verify Installation
Expand All @@ -50,85 +81,79 @@ Check that commands appear:
/help
```

You should see:
```
# Should see:
# /superpowers:brainstorm - Interactive design refinement
# /superpowers:write-plan - Create implementation plan
# /superpowers:execute-plan - Execute plan in batches
```

### Codex

Tell Codex:

```
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md
/superpowers-ng:brainstorm - Interactive design refinement
/superpowers-ng:write-plan - Create implementation plan
/superpowers-ng:execute-plan - Execute plan in batches
/superpowers-ng:manus-plan - Start Manus-style persistent planning
```

**Detailed docs:** [docs/README.codex.md](docs/README.codex.md)

### OpenCode
## The Enhanced Workflow

Tell OpenCode:
1. **brainstorming** - Refines rough ideas, presents design in sections. Saves design document.

```
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md
```
2. **using-git-worktrees** - Creates isolated workspace on new branch.

**Detailed docs:** [docs/README.opencode.md](docs/README.opencode.md)
3. **Choose your planning system:**
- **Native:** `writing-plans` → `executing-plans` for short tasks
- **Manus:** `manus-planning` for complex/long-running tasks

## The Basic Workflow
4. **subagent-driven-development** or **executing-plans** - Implements with two-stage review or batch execution.

1. **brainstorming** - Activates before writing code. Refines rough ideas through questions, explores alternatives, presents design in sections for validation. Saves design document.
5. **test-driven-development** - Enforces RED-GREEN-REFACTOR cycle.

2. **using-git-worktrees** - Activates after design approval. Creates isolated workspace on new branch, runs project setup, verifies clean test baseline.
6. **requesting-code-review** - Reviews against plan between tasks.

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.
7. **finishing-a-development-branch** - Verifies tests, presents merge options.

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.

5. **test-driven-development** - Activates during implementation. Enforces RED-GREEN-REFACTOR: write failing test, watch it fail, write minimal code, watch it pass, commit. Deletes code written before tests.

6. **requesting-code-review** - Activates between tasks. Reviews against plan, reports issues by severity. Critical issues block progress.
## What's Inside

7. **finishing-a-development-branch** - Activates when tasks complete. Verifies tests, presents options (merge/PR/keep/discard), cleans up worktree.
### Planning Skills

**The agent checks for relevant skills before any task.** Mandatory workflows, not suggestions.
**Native Planning (Original)**
- **writing-plans** - Bite-sized implementation plans
- **executing-plans** - Batch execution with checkpoints

## What's Inside
**Manus Planning (New)**
- **manus-planning** - 5-phase workflow with persistent files
- Phase 1: Requirements & Discovery
- Phase 2: Planning & Structure
- Phase 3: Implementation
- Phase 4: Testing & Verification
- Phase 5: Delivery

### Skills Library
### Testing

**Testing**
- **test-driven-development** - RED-GREEN-REFACTOR cycle (includes testing anti-patterns reference)

**Debugging**
### Debugging

- **systematic-debugging** - 4-phase root cause process (includes root-cause-tracing, defense-in-depth, condition-based-waiting techniques)
- **verification-before-completion** - Ensure it's actually fixed

**Collaboration**
- **brainstorming** - Socratic design refinement
- **writing-plans** - Detailed implementation plans
- **executing-plans** - Batch execution with checkpoints
### Collaboration

- **brainstorming** - Socratic design refinement (enhanced with planning choice)
- **dispatching-parallel-agents** - Concurrent subagent workflows
- **requesting-code-review** - Pre-review checklist
- **receiving-code-review** - Responding to feedback
- **using-git-worktrees** - Parallel development branches
- **finishing-a-development-branch** - Merge/PR decision workflow
- **subagent-driven-development** - Fast iteration with two-stage review (spec compliance, then code quality)
- **subagent-driven-development** - Fast iteration with two-stage review

### Meta

**Meta**
- **writing-skills** - Create new skills following best practices (includes testing methodology)
- **using-superpowers** - Introduction to the skills system
- **writing-skills** - Create new skills following best practices
- **using-superpowers** - Introduction to the skills system (updated with planning guidance)

## Philosophy

- **Test-Driven Development** - Write tests first, always
- **Systematic over ad-hoc** - Process over guessing
- **Complexity reduction** - Simplicity as primary goal
- **Evidence over claims** - Verify before declaring success

Read more: [Superpowers for Claude Code](https://blog.fsck.com/2025/10/09/superpowers/)
- **Persistent memory** (New) - Filesystem as external memory for long tasks

## Contributing

Expand All @@ -141,19 +166,31 @@ 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

MIT License - see LICENSE file for details

## Support

- **Issues**: https://github.com/obra/superpowers/issues
- **Marketplace**: https://github.com/obra/superpowers-marketplace
- **Issues**: https://github.com/OniReimu/superpowers/issues
- **Original Superpowers**: https://github.com/obra/superpowers
- **Planning-with-files**: https://github.com/OthmanAdi/planning-with-files
Loading