Skip to content

Commit 32acf4f

Browse files
moyaspacemoyaspace
committed
docs: split Problem section into three paragraphs for readability
1 parent 0501760 commit 32acf4f

6 files changed

Lines changed: 490 additions & 280 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
name: PR Check
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
check:
11+
strategy:
12+
matrix:
13+
os: [ubuntu-latest, windows-latest]
14+
runs-on: ${{ matrix.os }}
15+
16+
steps:
17+
- uses: actions/checkout@v4
18+
- uses: actions/setup-node@v4
19+
with:
20+
node-version: 18
21+
22+
# ── CLI 可用性 ──
23+
- name: CLI --help
24+
run: node bin/cli.js --help
25+
26+
- name: CLI --help (zh-CN)
27+
run: node bin/cli.js --lang zh-CN --help
28+
29+
- name: CLI create-project alias --help
30+
run: node bin/create-project.js --help
31+
32+
# ── Tarball 构建 ──
33+
- name: npm pack
34+
run: npm pack
35+
36+
# ── Tarball 内容完整性 ──
37+
- name: Verify tarball contents
38+
shell: bash
39+
run: |
40+
PACKAGE=$(ls *.tgz)
41+
echo "Tarball: $PACKAGE"
42+
errors=0
43+
44+
for file in \
45+
"package/bin/cli.js" \
46+
"package/bin/create-project.js" \
47+
"package/.gitattributes" \
48+
"package/package.json" \
49+
"package/template/AGENTS.md" \
50+
"package/template/openspec/schemas/superpowers-bridge-opencode/schema.yaml" \
51+
"package/template/skills.lock.json" \
52+
"package/template/_gitignore" \
53+
"package/template/.editorconfig" \
54+
"package/template/.gitattributes" \
55+
"package/scripts/setup.sh" \
56+
"package/scripts/setup.ps1" \
57+
"package/docs/QUICKSTART.md" \
58+
"package/LICENSE"; do
59+
if tar -tzf "$PACKAGE" 2>/dev/null | grep -q "$file"; then
60+
echo " ✅ $file"
61+
else
62+
echo " ❌ $file"
63+
errors=$((errors + 1))
64+
fi
65+
done
66+
67+
# 验证 template/.opencode/ 结构
68+
echo ""
69+
echo "--- template/.opencode/ structure ---"
70+
tar -tzf "$PACKAGE" | grep "package/template/\.opencode/" | head -5
71+
72+
if [ $errors -gt 0 ]; then
73+
echo ""
74+
echo "❌ $errors critical file(s) missing from tarball"
75+
exit 1
76+
fi
77+
echo ""
78+
echo "✅ All critical files present"
79+
80+
# ── CRLF 检查（仅 Linux，Windows 上 xxd 不可用）──
81+
- name: CRLF check (Linux)
82+
if: runner.os == 'Linux'
83+
shell: bash
84+
run: |
85+
PACKAGE=$(ls *.tgz)
86+
tar -xzf "$PACKAGE" -C /tmp package/scripts/setup.sh
87+
if xxd /tmp/package/scripts/setup.sh | head -1 | grep -q "0d 0a"; then
88+
echo "❌ scripts/setup.sh has CRLF — check .gitattributes"
89+
exit 1
90+
else
91+
echo "✅ scripts/setup.sh is LF only"
92+
fi

‎README.md‎

Lines changed: 77 additions & 136 deletions
Original file line numberDiff line numberDiff line change
@@ -1,190 +1,131 @@
1-
# openspec-superpowers-opencode (aka oso)
1+
# oso (openspec-superpowers-opencode)
22

3-
> **中文版 → [docs/README.zh.md](docs/README.zh.md)**
4-
5-
**CLI scaffold that bridges Superpowers + OpenSpec workflows into OpenCode.**
3+
> Bridges Superpowers + OpenSpec workflows into OpenCode with enforced worktree isolation.
64
5+
[![CI](https://img.shields.io/github/actions/workflow/status/moyaspace/openspec-superpowers-opencode/ci.yml?style=for-the-badge&logo=github&color=2ea44f)](https://github.com/moyaspace/openspec-superpowers-opencode/actions)
6+
[![GitHub last commit](https://img.shields.io/github/last-commit/moyaspace/openspec-superpowers-opencode?style=for-the-badge&logo=github&color=blue)](https://github.com/moyaspace/openspec-superpowers-opencode)
77
[![GitHub Stars](https://img.shields.io/github/stars/moyaspace/openspec-superpowers-opencode?style=for-the-badge&color=yellow&logo=github)](https://github.com/moyaspace/openspec-superpowers-opencode)
88
[![npm Version](https://img.shields.io/npm/v/@moyaspace/openspec-superpowers-opencode?style=for-the-badge&logo=npm&color=cb3837)](https://www.npmjs.com/package/@moyaspace/openspec-superpowers-opencode)
99
[![npm Weekly Downloads](https://img.shields.io/npm/dw/@moyaspace/openspec-superpowers-opencode?style=for-the-badge&logo=npm&color=cb3837)](https://www.npmjs.com/package/@moyaspace/openspec-superpowers-opencode)
10-
[![npm Monthly Downloads](https://img.shields.io/npm/dm/@moyaspace/openspec-superpowers-opencode?style=for-the-badge&logo=npm&color=cb3837)](https://www.npmjs.com/package/@moyaspace/openspec-superpowers-opencode)
10+
[![npm Monthly Downloads](https://img.shields.io/npm/dm/@moyaspace/openspec-superpowers-opencode?style-for-the-badge&logo=npm&color=cb3837)](https://www.npmjs.com/package/@moyaspace/openspec-superpowers-opencode)
1111
[![License](https://img.shields.io/github/license/moyaspace/openspec-superpowers-opencode?style=for-the-badge&color=blue)](https://github.com/moyaspace/openspec-superpowers-opencode)
1212

1313
> If you find this useful, consider giving it a ⭐ on GitHub!
1414
15-
- **GitHub**: `https://github.com/moyaspace/openspec-superpowers-opencode`
16-
- **npm**: `https://www.npmjs.com/package/@moyaspace/openspec-superpowers-opencode`
17-
- **Author**: rl <robincn@gmail.com>
18-
- **License**: MIT
19-
20-
## Features
21-
22-
| # | Feature | One-liner |
23-
|---|---------|-----------|
24-
| 1 | **One-command init** | `openspec-superpowers-opencode init` → deploy templates + config + first commit |
25-
| 2 | **12 OPSX commands** | `/opsx-ff` → `/opsx-apply` → `/opsx-finish` covers the full change lifecycle |
26-
| 3 | **Git worktree isolation** | Each change lives in its own `.worktrees/<name>/` dir and `feature/<name>` branch; main stays clean |
27-
| 4 | **Layered architecture** | Superpowers (HOW) → OpenSpec (WHAT) → Worktree (WHERE) → Commands (WHEN) |
28-
| 5 | **Greenfield/brownfield** | Auto-deploy on new projects; per-file overwrite prompts on existing ones |
29-
| 6 | **Brownfield override system** | `BROWN_OVERRIDE_*` env vars or interactive prompts control overwrite decisions |
30-
| 7 | **Skill lock verification** | SHA-256 hashes of upstream Superpowers skill files are validated on deploy |
31-
| 8 | **Cross-platform + i18n** | Windows (`setup.ps1`) / Linux (`setup.sh`), `--lang zh-CN | zh-TW | en` |
32-
33-
> Detailed feature descriptions → [docs/FEATURES.md](docs/FEATURES.md).
34-
35-
## Install
36-
37-
```bash
38-
# From npm
39-
npm install -g @moyaspace/openspec-superpowers-opencode
40-
41-
# From local tgz (offline/preview)
42-
npm install -g ./<name>-<version>.tgz
15+
---
4316

44-
# Verify
45-
openspec-superpowers-opencode --help
46-
```
17+
## The Problem
4718

48-
Requirements: `openspec` CLI v1.3+, `opencode` CLI, `git`, Superpowers plugin.
19+
Install **OpenSpec** and **Superpowers** separately, and you get two powerful but disconnected tools.
4920

50-
## Usage
21+
OpenSpec gives you artifact-driven development — brainstorm → specs → tasks → plan.
5122

52-
```powershell
53-
# One-step init
54-
mkdir my-project && cd my-project
55-
openspec-superpowers-opencode init
23+
Superpowers gives you battle-tested methodologies — brainstorming, writing-plans, TDD.
5624

57-
# Or specify a target directory
58-
openspec-superpowers-opencode init my-project
59-
```
25+
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.
6026

61-
`init` automatically: deploys template files → `git init` → first commit.
27+
You can use both, but you'll spend more time stitching them together than actually building features.
6228

63-
## Prerequisites
29+
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.
6430

65-
- `openspec` CLI v1.3+
66-
- `opencode` CLI
67-
- `git`
68-
- Superpowers plugin installed
31+
**oso bridges the gap and adds isolation.**
6932

70-
The setup script will check these automatically.
33+
## The oso Solution
7134

72-
## Using in OpenCode
35+
oso is a CLI scaffold that does two things:
7336

74-
Open the initialized project in OpenCode, then use the full workflow:
37+
**① Bridges OpenSpec + Superpowers** — one command deploys the complete integration: schema, AGENTS.md, skill lock verification, 12 OPSX commands, all pre-configured and tested together.
7538

76-
| Command | Description |
77-
|---------|-------------|
78-
| `/opsx-ff <name>` | Create a change and generate all artifacts |
79-
| `/opsx-apply [name]` | Get context, start implementation |
80-
| `/opsx-verify` | Verify implementation vs spec |
81-
| `/opsx-finish [name]` | Complete change (merge/cleanup) |
82-
| `/opsx-archive` | Archive completed changes |
39+
**② Enforces worktree isolation** — every change gets its own git worktree. Parallel changes, zero conflicts.
8340

84-
### Parallel changes
41+
```
42+
┌─ .worktrees/feature-a/ (feature/feature-a branch)
43+
main ─────┼─ .worktrees/feature-b/ (feature/feature-b branch)
44+
└─ .worktrees/feature-c/ (feature/feature-c branch)
45+
```
8546

86-
Each change is isolated in its own git worktree. AI handles all directory switching:
47+
<!-- TODO: 30s 终端录屏 GIF — 展示 /opsx-ff feature-a → /opsx-ff feature-b → 各自 apply，互不干扰 -->
8748

8849
```bash
8950
# Create two changes simultaneously
90-
/opsx-ff feature-a # → background: cd .worktrees/feature-a/ create artifacts → back to main
91-
/opsx-ff feature-b # → background: cd .worktrees/feature-b/ create artifacts → back to main
51+
/opsx-ff feature-a
52+
/opsx-ff feature-b
9253

93-
# Switch to feature-a (AI auto-cds)
94-
/opsx-apply feature-a # → background: cd .worktrees/feature-a/ code, commit
54+
# Work on feature-a
55+
/opsx-apply feature-a # AI auto-cds into .worktrees/feature-a/
9556
# ... write code ...
9657

9758
# Switch to feature-b (no need to finish feature-a first)
98-
/opsx-apply feature-b # → background: cd .worktrees/feature-b/ code, commit
59+
/opsx-apply feature-b # AI auto-cds into .worktrees/feature-b/
9960
# ... write code ...
10061

10162
# Finish independently
102-
/opsx-finish feature-a # → background: test → merge → cleanup worktree
63+
/opsx-finish feature-a # test → merge → cleanup
10364
/opsx-finish feature-b
10465
```
10566

106-
| Concept | Description |
107-
|---------|-------------|
108-
| One worktree per change | `.worktrees/<name>/` dir + `feature/<name>` branch, fully isolated |
109-
| Named switch | `/opsx-apply <name>`, `/opsx-finish <name>` targets the right worktree |
110-
| Omitting name | Auto-detected from `.worktrees/`; single → use it, multiple → AskUser |
111-
| Transparent directories | AI handles all `cd`, user only types command names |
112-
| Main stays clean | All artifacts and code stay in their worktrees |
113-
114-
### Browsing worktree content manually
67+
## Quick Start
11568

11669
```bash
117-
# List worktree directory
118-
cd .worktrees/<name>
119-
ls -la
70+
# 1. Install
71+
npm install -g @moyaspace/openspec-superpowers-opencode
12072

121-
# View change branch history
122-
git log feature/<name>
73+
# 2. Init a project
74+
mkdir my-project && cd my-project
75+
openspec-superpowers-opencode init
12376

124-
# Back to project root
125-
cd <project-root>
77+
# 3. Open in OpenCode, then use the workflow
78+
/opsx-ff add-user-auth # create change + generate artifacts
79+
/opsx-apply # AI implements in isolated worktree
80+
/opsx-finish # test → merge → cleanup
12681
```
12782

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

130-
## CLI Commands
96+
> Detailed features → [docs/FEATURES.md](docs/FEATURES.md)
13197
132-
| Command | Description |
133-
|---------|-------------|
134-
| `openspec-superpowers-opencode init` | Initialize a project |
135-
| `openspec-superpowers-opencode reset` | Revert to uninitialized state (removes all installed files) |
136-
| `openspec-superpowers-opencode dry-run` | Preview changes |
137-
| `openspec-superpowers-opencode ensure-worktree <name>` | Ensure a worktree exists |
138-
| `create-openspec-superpowers-opencode` | Alias, equivalent to init |
98+
## Documentation
13999

140-
## Updating Project Templates
100+
| Doc | Description |
101+
|-----|-------------|
102+
| [Quick start](docs/QUICKSTART.md) | 10-minute first change |
103+
| [How it works](docs/HOW-IT-WORKS.md) | Command execution chain explained |
104+
| [Worktree creation](docs/WORKTREE-CREATION.md) | Three-layer code-level guarantees |
105+
| [Design decisions](docs/DESIGN.md) | ADRs: architecture tradeoffs |
106+
| [Testing](docs/TESTING.md) | 12-phase test suite |
107+
| [Why oso](docs/WHY-OSO.md) | Deep dive: 6 gaps between OpenSpec and Superpowers |
141108

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

145-
Two types of updates:
111+
- Node.js >= 16 (recommended)
112+
- `openspec` CLI v1.3+
113+
- `opencode` CLI
114+
- `git`
115+
- Superpowers plugin
146116

147-
| What updates | Action | Notes |
148-
|-------------|--------|-------|
149-
| Superpowers plugin | **Nothing needed** | Skills update themselves, paths usually unchanged |
150-
| This package (new version) | `reset + init` | Redeploy new templates, lock file, config |
117+
Setup script checks these automatically.
151118

152-
After a new release:
119+
## Local Development
153120

154121
```bash
155-
npm update -g @moyaspace/openspec-superpowers-opencode # upgrade package
156-
openspec-superpowers-opencode reset # remove old config
157-
openspec-superpowers-opencode init # install new templates
122+
node bin/cli.js init test-project # test locally
123+
npm publish # publish to npm
158124
```
159125

160-
## skills.lock.json
161-
162-
`skills.lock.json` records SHA-256 hashes of 7 Superpowers skill files for integrity verification.
163-
It ships with this package, locking the **tested-compatible** Superpowers version.
164-
165-
If Superpowers updates and SHA-256 doesn't match, `init` shows a yellow WARNING. **Non-blocking, workflow unaffected.**
166-
167-
To clear the WARNING, wait for a new package release with updated hashes.
168-
169-
## Related Docs
170-
171-
| Doc | Description |
172-
|-----|-------------|
173-
| [Quick start](docs/QUICKSTART.md) | 10-minute first change: install → init → /opsx-ff → /opsx-apply → /opsx-finish |
174-
| [How it works](docs/HOW-IT-WORKS.md) | Command execution chain from user input to artifact generation |
175-
| [Features](docs/FEATURES.md) | CLI, OPSX commands, worktree isolation, layered architecture |
176-
| [Worktree creation](docs/WORKTREE-CREATION.md) | Three-layer code-level guarantees for isolated worktrees |
177-
| [Design decisions](docs/DESIGN.md) | ADRs: opencode.json location, brownfield-first, no-overwrite policy |
178-
| [Implementation strategy](docs/IMPLEMENTATION-STRATEGY.md) | Deployment gate flow, four-dimension partitioning, mode behaviors |
179-
| [Testing](docs/TEST.md) | 12-phase test suite |
180-
| [Upstream schema reference](docs/UPSTREAM-superpowers-bridge-schema-README.md) | Original superpowers-bridge schema definition |
181-
182-
## Local Development
183-
184-
```powershell
185-
# Test
186-
node bin/cli.js init test-project
126+
---
187127

188-
# Publish
189-
npm publish
190-
```
128+
**GitHub**: https://github.com/moyaspace/openspec-superpowers-opencode
129+
**npm**: https://www.npmjs.com/package/@moyaspace/openspec-superpowers-opencode
130+
**Author**: rl <robincn@gmail.com>
131+
**License**: MIT

0 commit comments

Comments
 (0)