@dalatindustries/superpowers/README.md

Enhanced Obra Superpowers integration for Roo Code - pass-through NPM package that always pulls latest upstream

# @dalatindustries/superpowers

**Enhanced Obra Superpowers integration for Roo Code**

A pass-through NPM package that installs [obra/superpowers](https://github.com/obra/superpowers) with adaptive enhancements for better Claude integration.

## What This Package Does

1. **Always Gets Latest** - Downloads fresh copy of obra/superpowers from GitHub on every install
2. **Adaptive Enhancements** - Applies improvements that work across upstream changes
3. **Zero Maintenance** - No fork to maintain, updates flow through automatically
4. **Graceful Degradation** - Core installation succeeds even if enhancements fail

## Installation

```bash
npm install @dalatindustries/superpowers
```

This will:
- Download latest obra/superpowers to `~/.roo/superpowers`
- Apply adaptive enhancements (if applicable)
- Create automatic backups

## Configuration

Add to your Roo Code configuration (`.roo/config.json`):

```json
{
  "skillsDirectory": "~/.roo/superpowers/skills",
  "modesDirectory": "~/.roo/superpowers/agents",
  "commandsDirectory": "~/.roo/superpowers/commands"
}
```

## Usage

### Update to Latest

Pull the latest obra/superpowers:

```bash
npm run update
```

### Repair Installation

If enhancements failed or installation is broken:

```bash
npm run repair
```

### Uninstall

Remove superpowers with optional backup:

```bash
npm run uninstall
```

## How It Works

### Pass-Through Architecture

Unlike traditional NPM packages, this is a **pass-through package**:

```
Traditional Package:        Pass-Through Package:
npm install                 npm install
    ↓                           ↓
install package code        download upstream (obra/superpowers)
    ↓                           ↓
done                        apply enhancements
                                ↓
                            done
```

**Benefits:**
- ✅ Always get latest upstream updates
- ✅ Zero maintenance burden
- ✅ Proper attribution to obra
- ✅ Minimal code to maintain

### Adaptive Enhancement System

Instead of fragile static patches, we use **dynamic detection and injection**:

```bash
# Static Patch (fragile)
patch -p1 < changes.patch  # Breaks when upstream changes

# Adaptive Enhancement (robust)
1. Detect current structure
2. Generate enhancement code
3. Inject at safe locations
4. Validate and rollback if needed
```

**How It Adapts:**

| Upstream Change | Impact | Reason |
|----------------|--------|--------|
| New skills added | ✅ None | Dynamic discovery |
| File renamed | ⚠️ Graceful skip | Detection handles missing files |
| Internals changed | ✅ None (95%) | Append-only injection |
| Structure changed | ⚠️ Graceful skip | Validation with rollback |
| File removed | ⚠️ Graceful skip | Core install proceeds |

### Error Handling

**Fail-Fast on Critical Errors:**
- Git not installed → Stop
- Network failure → Stop  
- Repository invalid → Stop

**Graceful Degradation on Enhancements:**
- Enhancement fails → Core install proceeds
- User notified → Can retry with `npm run repair`
- Automatic backups → Can always recover


## What Gets Enhanced

Currently enhancing **Option 1: Session Hook Improvements**

- Detects session hook location (`.roo/`, `.codex/`, root)
- Injects skill summary display code
- Shows Claude list of available skills on session start
- Future-proof: Adapts to upstream structure changes

**Note:** Current obra/superpowers doesn't include session hooks yet, so enhancements are skipped. Core installation still works perfectly - you get all 20+ skills ready to use.

## Files and Directories

```
~/.roo/
├── superpowers/              # Installed obra/superpowers
│   ├── skills/              # 20+ skills
│   ├── agents/              # Custom modes
│   ├── commands/            # Slash commands
│   └── .codex/              # Installation metadata
├── .backups/                # Automatic backups
│   └── superpowers-YYYYMMDD-HHMMSS/
└── .tmp/                    # Temporary clone location
```

## Troubleshooting

### Installation fails with git error

**Cause:** Git not installed or network issue

**Fix:**
```bash
# macOS
brew install git

# Verify
git --version
```

### Enhancement fails but install succeeded

**Cause:** Upstream structure changed

**Impact:** Core superpowers work, just no enhanced features

**Fix:**
```bash
npm run repair  # Retry enhancements
```

### Want to see previous installation

**Backups located at:** `~/.roo/.backups/superpowers-*`

**Restore:**
```bash
# List backups
ls -la ~/.roo/.backups/

# Restore specific backup
rm -rf ~/.roo/superpowers
mv ~/.roo/.backups/superpowers-20251123-154813 ~/.roo/superpowers
```

## Development

### Testing Adaptive System

```bash
# Test 1: Fresh install
npm install

# Test 2: Update
npm run update

# Test 3: Repair
npm run repair

# Test 4: Handles upstream changes
# (Manually modify ~/.roo/superpowers structure)
npm run repair
# Should adapt or skip gracefully
```

### Debug Mode

```bash
DEBUG=1 bash scripts/install.sh
```

## Contributing

This is a pass-through package for obra/superpowers. 

**For skill contributions:** Submit to [obra/superpowers](https://github.com/obra/superpowers)

**For enhancement improvements:** Submit PR to this repository

## License

MIT License - See [LICENSE](./LICENSE)

**Note:** This package distributes obra/superpowers, which has its own license. Check the [upstream repository](https://github.com/obra/superpowers) for details.

## Credits

- **obra** - Original superpowers creator and maintainer
- **Dalat Industries** - NPM packaging and adaptive enhancement system

## Links

- [obra/superpowers](https://github.com/obra/superpowers) - Upstream repository
- [Dalat Industries](https://dalatindustries.com) - Developer and maintainer
- [NPM Package](https://npmjs.com/package/@dalatindustries/superpowers)
- [Issue Tracker](https://github.com/dalatindustries/superpowers-npm/issues)

---

**Philosophy:** Better to have working core superpowers without enhancements than broken installation trying to be clever.