openspec-superpowers-opencode (aka oso)

中文版 → docs/README.zh.md

CLI scaffold that bridges Superpowers + OpenSpec workflows into OpenCode.

• GitHub: https://github.com/moyaspace/openspec-superpowers-opencode
• npm: https://www.npmjs.com/package/@moyaspace/openspec-superpowers-opencode
• Author: rl [email protected]
• License: MIT

Features

| # | Feature | One-liner | |---|---------|-----------| | 1 | One-command init | openspec-superpowers-opencode init → deploy templates + config + first commit | | 2 | 12 OPSX commands | /opsx-ff → /opsx-apply → /opsx-finish covers the full change lifecycle | | 3 | Git worktree isolation | Each change lives in its own .worktrees/<name>/ dir and feature/<name> branch; main stays clean | | 4 | Layered architecture | Superpowers (HOW) → OpenSpec (WHAT) → Worktree (WHERE) → Commands (WHEN) | | 5 | Greenfield/brownfield | Auto-deploy on new projects; per-file overwrite prompts on existing ones | | 6 | Brownfield override system | BROWN_OVERRIDE_* env vars or interactive prompts control overwrite decisions | | 7 | Skill lock verification | SHA-256 hashes of upstream Superpowers skill files are validated on deploy | | 8 | Cross-platform + i18n | Windows (setup.ps1) / Linux (setup.sh), --lang zh-CN | zh-TW | en |

Detailed feature descriptions → docs/FEATURES.md.

Install

# From npm
npm install -g @moyaspace/openspec-superpowers-opencode

# From local tgz (offline/preview)
npm install -g ./<name>-<version>.tgz

# Verify
openspec-superpowers-opencode --help

Requirements: openspec CLI v1.3+, opencode CLI, git, Superpowers plugin.

Usage

# One-step init
mkdir my-project && cd my-project
openspec-superpowers-opencode init

# Or specify a target directory
openspec-superpowers-opencode init my-project

init automatically: deploys template files → git init → first commit.

Prerequisites

• openspec CLI v1.3+
• opencode CLI
• git
• Superpowers plugin installed

The setup script will check these automatically.

Using in OpenCode

Open the initialized project in OpenCode, then use the full workflow:

| Command | Description | |---------|-------------| | /opsx-ff <name> | Create a change and generate all artifacts | | /opsx-apply [name] | Get context, start implementation | | /opsx-verify | Verify implementation vs spec | | /opsx-finish [name] | Complete change (merge/cleanup) | | /opsx-archive | Archive completed changes |

Parallel changes

Each change is isolated in its own git worktree. AI handles all directory switching:

# Create two changes simultaneously
/opsx-ff feature-a        # → background: cd .worktrees/feature-a/ create artifacts → back to main
/opsx-ff feature-b        # → background: cd .worktrees/feature-b/ create artifacts → back to main

# Switch to feature-a (AI auto-cds)
/opsx-apply feature-a     # → background: cd .worktrees/feature-a/ code, commit
# ... write code ...

# Switch to feature-b (no need to finish feature-a first)
/opsx-apply feature-b     # → background: cd .worktrees/feature-b/ code, commit
# ... write code ...

# Finish independently
/opsx-finish feature-a    # → background: test → merge → cleanup worktree
/opsx-finish feature-b

| Concept | Description | |---------|-------------| | One worktree per change | .worktrees/<name>/ dir + feature/<name> branch, fully isolated | | Named switch | /opsx-apply <name>, /opsx-finish <name> targets the right worktree | | Omitting name | Auto-detected from .worktrees/; single → use it, multiple → AskUser | | Transparent directories | AI handles all cd, user only types command names | | Main stays clean | All artifacts and code stay in their worktrees |

Browsing worktree content manually

# List worktree directory
cd .worktrees/<name>
ls -la

# View change branch history
git log feature/<name>

# Back to project root
cd <project-root>

Usually not needed—editors can browse .worktrees/<name>/ directly.

CLI Commands

| Command | Description | |---------|-------------| | openspec-superpowers-opencode init | Initialize a project | | openspec-superpowers-opencode reset | Revert to uninitialized state (removes all installed files) | | openspec-superpowers-opencode dry-run | Preview changes | | openspec-superpowers-opencode ensure-worktree <name> | Ensure a worktree exists | | create-openspec-superpowers-opencode | Alias, equivalent to init |

Updating Project Templates

reset + init does NOT touch Superpowers skill files—those are managed by the Superpowers plugin itself. reset + init only redeploys packaged template files (AGENTS.md, schema.yaml, skills.lock.json, etc.).

Two types of updates:

| What updates | Action | Notes | |-------------|--------|-------| | Superpowers plugin | Nothing needed | Skills update themselves, paths usually unchanged | | This package (new version) | reset + init | Redeploy new templates, lock file, config |

After a new release:

npm update -g openspec-superpowers-opencode  # upgrade package
openspec-superpowers-opencode reset           # remove old config
openspec-superpowers-opencode init            # install new templates

skills.lock.json

skills.lock.json records SHA-256 hashes of 7 Superpowers skill files for integrity verification. It ships with this package, locking the tested-compatible Superpowers version.

If Superpowers updates and SHA-256 doesn't match, init shows a yellow WARNING. Non-blocking, workflow unaffected.

To clear the WARNING, wait for a new package release with updated hashes.

Related Docs

| Doc | Description | |-----|-------------| | Quick start | 10-minute first change: install → init → /opsx-ff → /opsx-apply → /opsx-finish | | How it works | Command execution chain from user input to artifact generation | | Features | CLI, OPSX commands, worktree isolation, layered architecture | | Worktree creation | Three-layer code-level guarantees for isolated worktrees | | Design decisions | ADRs: opencode.json location, brownfield-first, no-overwrite policy | | Implementation strategy | Deployment gate flow, four-dimension partitioning, mode behaviors | | Testing | 12-phase test suite | | Upstream schema reference | Original superpowers-bridge schema definition |

Local Development

# Test
node bin/cli.js init test-project

# Publish
npm publish