oso (openspec-superpowers-opencode)

Bridges Superpowers + OpenSpec workflows into OpenCode with enforced worktree isolation.

If you find this useful, consider giving it a ⭐ on GitHub!

🌐 Read this in other languages: English | 中文

---

The Problem

Install OpenSpec and Superpowers separately, and you get two powerful but disconnected tools.

OpenSpec gives you artifact-driven development — brainstorm → specs → tasks → plan.

Superpowers gives you battle-tested methodologies — brainstorming, writing-plans, TDD.

But out of the box, they don't talk to each other. OpenSpec generates generic artifacts, Superpowers skills sit in a separate cache directory, and there's nothing connecting them into a unified workflow.

You can use both, but you'll spend more time stitching them together than actually building features.

And even if you do wire them up, you're still stuck with a single working tree — one change at a time. Want to add login and search simultaneously? Context collision, partial commits, reverting. You either wait, or you break things.

oso bridges the gap and adds isolation.

The oso Solution

oso is a CLI scaffold that does two things:

① Bridges OpenSpec + Superpowers — one command deploys the complete integration: schema, AGENTS.md, skill lock verification, 12 OPSX commands, all pre-configured and tested together.

② Enforces worktree isolation — every change gets its own git worktree. Parallel changes, zero conflicts.

          ┌─ .worktrees/feature-a/  (feature/feature-a branch)
main ─────┼─ .worktrees/feature-b/  (feature/feature-b branch)
          └─ .worktrees/feature-c/  (feature/feature-c branch)

# Create two changes simultaneously
/opsx-ff feature-a
/opsx-ff feature-b

# Work on feature-a
/opsx-apply feature-a     # AI auto-cds into .worktrees/feature-a/
# ... write code ...

# Switch to feature-b (no need to finish feature-a first)
/opsx-apply feature-b     # AI auto-cds into .worktrees/feature-b/
# ... write code ...

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

Quick Start

# 1. Install
npm install -g @moyaspace/openspec-superpowers-opencode

# 2. Init a project
mkdir my-project && cd my-project
openspec-superpowers-opencode init

# 3. Open in OpenCode, then use the workflow
/opsx-ff add-user-auth    # create change + generate artifacts
/opsx-apply               # AI implements in isolated worktree
/opsx-finish              # test → merge → cleanup

Features

#	Feature	One-liner
1	12 OPSX commands	/opsx-ff → /opsx-apply → /opsx-finish — full change lifecycle
2	Git worktree isolation	Each change in its own .worktrees/<name>/ dir + feature/<name> branch
3	One-command init	oso init → deploy templates + config + git init + first commit
4	Bridged OpenSpec + Superpowers	Pre-configured schema + skill mapping + lock verification, one-command deploy
5	Greenfield/brownfield	Auto-deploy on new projects; safe merge on existing ones
6	Cross-platform + i18n	Windows setup.ps1 / Linux setup.sh, --lang zh-CN | zh-TW | en
7	SHA-256 lock	Skill file integrity verified on deploy
8	Layered architecture	Superpowers (HOW) → OpenSpec (WHAT) → Worktree (WHERE) → Commands (WHEN)

Detailed features → docs/FEATURES.md

Documentation

Doc	Description
Quick start	10-minute first change
How it works	Command execution chain explained
Worktree creation	Three-layer code-level guarantees
Design decisions	ADRs: architecture tradeoffs
Testing	12-phase test suite
Why oso	Deep dive: 6 gaps between OpenSpec and Superpowers

Prerequisites

• Node.js >= 16 (recommended)
• openspec CLI v1.3+
• opencode CLI
• git
• Superpowers plugin

Setup script checks these automatically.

Local Development

node bin/cli.js init test-project   # test locally
npm publish                         # publish to npm

---

GitHub: https://github.com/moyaspace/openspec-superpowers-opencode
npm: https://www.npmjs.com/package/@moyaspace/openspec-superpowers-opencode
Author: rl robincn@gmail.com
License: MIT