# gm2

**Repository Path**: kakumo/gm2

## Basic Information

- **Project Name**: gm2
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-07
- **Last Updated**: 2026-07-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 开发流程规范

基于 **OpenSpec**（规范驱动）+ **Superpowers**（高效执行）+ **桥接插件 openspec-superpowers**（双向同步）的标准开发流程。

**OpenSpec 决定「做什么」，Superpowers 负责「高效地做」，桥接插件在两者间建立任务映射。**

---

## 环境配置（必读）

本流程由**三个组件**配合，需一次性配置、全局生效。

### 组件分工

| 组件 | 来源 | 作用 |
|------|------|------|
| openspec CLI | `@fission-ai/openspec` | 规范驱动核心，`init` 生成 5 个基础命令 + 5 个 skills |
| openspec-superpowers CLI | npm `openspec-superpowers@1.x` | 桥接工具，`npx` 生成 2 个桥接命令 + 2 个 skills |
| openspec-superpowers 插件 | GitHub `MerrillLi/openspec-superpowers@0.1.0` | opencode 运行时插件，提供 16 个全局 skills |

> ⚠️ **同名包陷阱**：npm registry 的 `openspec-superpowers@1.x` 是 CLI 工具（生成桥接命令），GitHub fork `MerrillLi/openspec-superpowers@0.1.0` 是 opencode 插件（运行时 skills）。两者**同名不同物**，缺一不可。

### 1. 安装 openspec CLI

```bash
npm install -g @fission-ai/openspec
openspec --version                    # 验证 ≥ 1.5.0
```

### 2. 安装 openspec-superpowers 插件（opencode 运行时）

插件必须位于 opencode 配置目录的 `node_modules` 下才能被加载。用**真实复制**（不用 `file:` 链接，避免切换 Node 版本失效）：

```bash
# 先装 fork 源到 npm 全局
npm install -g git+https://github.com/MerrillLi/openspec-superpowers.git

# 真实复制到 opencode 配置目录（Windows 用 robocopy）
robocopy "$(npm root -g)/openspec-superpowers" ~/.config/opencode/node_modules/openspec-superpowers /E
```

在 `~/.config/opencode/opencode.json` 启用：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["openspec-superpowers"]
}
```

验证：`~/.config/opencode/node_modules/openspec-superpowers/index.js` 存在，`skills/` 下有 13 个目录。

### 3. 生成并全局化 7 个 opsx 命令

在任意项目执行两步生成完整命令，再复制到全局：

```bash
# 在临时项目里生成完整的 7 命令 + 7 skills
openspec init --tools opencode
npx openspec-superpowers@1 --tools opencode     # 补 2 个桥接命令

# 复制 7 个命令到全局
mkdir -p ~/.config/opencode/commands
cp .opencode/commands/opsx-*.md ~/.config/opencode/commands/
```

### 4. 补全插件缺失的 3 个 skills

fork 插件 0.1.0 自带 13 个 skills，但缺 `openspec-write-plan`、`openspec-executing-plans`、`openspec-sync-specs`。把上一步生成的这 3 个 skill 目录复制进插件 skills 目录：

```bash
cp -r .opencode/skills/openspec-write-plan       ~/.config/opencode/node_modules/openspec-superpowers/skills/
cp -r .opencode/skills/openspec-executing-plans  ~/.config/opencode/node_modules/openspec-superpowers/skills/
cp -r .opencode/skills/openspec-sync-specs       ~/.config/opencode/node_modules/openspec-superpowers/skills/
```

完成后插件 skills 目录应有 **16 个**子目录。这 3 个 skill 与插件原有 skills 一起经 `config.skills.paths` 全局注册。

### 5. 新项目接入

新项目只需 openspec 工作目录，**不要**重复生成 `.opencode`（已全局化）：

```bash
openspec init --tools none    # 只建 openspec/ 结构
```

### 6. 配置验证

opencode **静默加载失败不报错**，配置后必须主动验证四项：

```bash
# ① 插件就位：index.js 存在 + 版本 0.1.0 + 真实目录（LinkType 为空）
test -f ~/.config/opencode/node_modules/openspec-superpowers/index.js && echo OK

# ② skills 数量为 16（13 原生 + 3 补充）
ls -d ~/.config/opencode/node_modules/openspec-superpowers/skills/*/ | wc -l   # 应为 16

# ③ 全局 commands 数量为 7
ls ~/.config/opencode/commands/opsx-*.md | wc -l   # 应为 7

# ④ openspec CLI 可用
openspec --version
```

四项全过则重启 opencode，`/opsx-*` 命令与 skills 全局可用。

---

## 流程总览

桥接插件在 OpenSpec 的 `propose` 与 `archive` 之间插入 `write-plan` 与 `executing-plans` 两个阶段：

```
explore ──► propose ──► write-plan ──► executing-plans ──► archive
                            │                │
                            │                ├─ test-driven-development（TDD 编码）
                            │                ├─ systematic-debugging（调试排错）
                            │                └─ 完成后自动回写 [x] 到 tasks.md
                            │
                            └─ 每个 Task 带 <!-- openspec-task: LABEL --> 注释
```

旁路命令：`/opsx-apply`（无计划直接实施）、`/opsx-sync`（仅同步 delta spec）。

---

## 命令速查

### Slash Commands（全局，任意项目可用）

| 命令 | 阶段 | 说明 |
|------|------|------|
| `/opsx-explore <idea>` | 探索 | 思考伙伴模式，澄清需求 |
| `/opsx-propose <requirement>` | 提案 | 一次性生成 proposal/design/tasks |
| `/opsx-write-plan <change>` | 计划 | tasks.md → Superpowers 实施计划，带映射注释 |
| `/opsx-executing-plans <change>` | 执行 | 按计划执行并回写 tasks.md |
| `/opsx-apply <change>` | 直接执行 | **无计划**时直接实施（旁路） |
| `/opsx-archive <change>` | 归档 | 同步 spec 并归档变更 |
| `/opsx-sync <change>` | 同步 | 仅同步 delta spec，不归档（旁路） |

### OpenSpec CLI

```bash
openspec validate [item]        # 校验变更/spec 合法性
openspec list                   # 列出所有变更
openspec list --specs           # 列出所有 spec
openspec status --change <name> # 查看变更的产物完成状态
openspec archive <change>       # 归档变更
```

### Skills（由插件全局注册，共 16 个）

**OpenSpec 工作流 skills（8）**

| Skill | 对应命令 / 触发时机 |
|-------|---------|
| `openspec-explore` | `/opsx-explore` 探索需求 |
| `openspec-propose` | `/opsx-propose` 生成提案 |
| `openspec-write-plan` | `/opsx-write-plan` 生成实施计划 |
| `openspec-executing-plans` | `/opsx-executing-plans` 执行计划 |
| `openspec-apply-change` | `/opsx-apply` 直接实施 |
| `openspec-archive-change` | `/opsx-archive` 归档变更 |
| `openspec-sync-specs` | `/opsx-sync` 同步 delta spec |
| `openspec-verify-change` | 验证变更产物 |

**Superpowers 工程技能（8）**

| Skill | 触发时机 |
|-------|---------|
| `test-driven-development` | 实现功能/bugfix 前 |
| `systematic-debugging` | 遇到 bug、测试失败时 |
| `subagent-driven-development` | 执行带独立任务的计划 |
| `verification-before-completion` | 声称完成前 |
| `finishing-a-development-branch` | 实现完成、测试通过后 |
| `dispatching-parallel-agents` | 并行多任务分派时 |
| `using-git-worktrees` | 隔离工作区时 |
| `using-openspec-superpowers` | 插件引导（自动注入，无需手动加载） |

---

## 双向同步机制

桥接插件通过 `<!-- openspec-task: LABEL -->` 注释建立 OpenSpec tasks 与实施计划 tasks 的双向映射：

```
OpenSpec tasks.md              实施计划
─────────────────              ──────────────────────
- [ ] 1.1 Create User    ←→   <!-- openspec-task: 1.1 -->
                              ### Task 1: Create User model
- [ ] 1.2 Signup API     ←→   <!-- openspec-task: 1.2 -->
                              ### Task 2: Implement signup
```

**同步规则**：一个 OpenSpec task 标记为 `[x]` 当且仅当**所有**映射到它的 plan tasks 都完成；部分完成仅报告进度。

---

## 完整 Demo：为博客添加邮件登录

### Step 1 — 探索（可选）

```
你: /opsx-explore 为博客添加用户登录功能
```

AI 会提出澄清问题、调研现有代码库、列出认证方案的选项。需求不够清晰时停留在探索阶段；足够清晰后进入提案。

> Tip：需求已经很清楚时可跳过此步，直接 `/opsx-propose`。

### Step 2 — 提案

```
你: /opsx-propose 为博客添加邮箱/密码登录，包含注册和登录...
```

OpenSpec 生成变更目录：

```
openspec/changes/add-user-login/
├── .openspec.yaml
├── proposal.md          ← 这是什么 & 为什么
├── design.md            ← 如何实现
├── tasks.md             ← 实施任务清单
└── specs/login/
    └── spec.md          ← 此变更引入的 spec 变更
```

校验：

```bash
openspec validate add-user-login
```

`tasks.md` 示例：

```markdown
## 1. 核心实现
- [ ] 1.1 创建 User 数据模型
- [ ] 1.2 实现注册 API
- [ ] 1.3 实现登录 API
- [ ] 1.4 创建登录页面
- [ ] 1.5 添加认证中间件
```

### Step 3 — 生成计划

```
你: /opsx-write-plan add-user-login
```

读取 OpenSpec 产物，生成 Superpowers 实施计划：

```
docs/superpowers/plans/2026-07-07-add-user-login.md
```

每个任务带映射注释：

```markdown
<!-- openspec-task: 1.1 -->
### Task 1: 创建 User 数据模型
Files: src/models/User.ts
Steps: ...
Verification: ...
Commit: ...

<!-- openspec-task: 1.2 -->
### Task 2: 实现注册 API
Files: src/routes/auth.ts
Steps: ...
```

生成后自动校验映射覆盖率（每个 OpenSpec task 都有对应的 plan task）。

### Step 4 — 执行

```
你: /opsx-executing-plans add-user-login
```

选择执行模式：

```
Plan: 2026-07-07-add-user-login.md
Tasks: 5

Execution options:
1. Subagent-Driven（推荐）— 每任务一个新 subagent + 任务间审查
2. Inline Execution      — 批量执行 + 检查点
```

逐任务执行（Subagent-Driven 模式内部会触发 `test-driven-development`、`systematic-debugging` 等 skills）。完成后自动同步 `tasks.md`：

```markdown
- [x] 1.1 创建 User 数据模型      ← 已完成
- [x] 1.2 实现注册 API            ← 已完成
- [ ] 1.3 实现登录 API            ← 进行中
- [ ] 1.4 创建登录页面
- [ ] 1.5 添加认证中间件
```

### Step 5 — 完成验证

执行 skill `verification-before-completion`：
- 运行 lint / typecheck / 测试
- 确认所有输出证据通过后才声称完成

### Step 6 — 分支收尾

执行 skill `finishing-a-development-branch`：
- 决定 merge / PR / cleanup

### Step 7 — 归档

```
你: /opsx-archive add-user-login
```

最终目录结构：

```
openspec/
├── changes/archive/2026-07-07-add-user-login/
│   ├── .openspec.yaml
│   ├── proposal.md
│   ├── design.md
│   ├── tasks.md
│   └── specs/login/spec.md
└── specs/login/
    └── spec.md          ← 主 spec（已同步）
```

归档前比对 delta spec 与主 spec，同步后移动到 `archive/`，工作区恢复干净。

---

## 模型路由建议

| 阶段 | 推荐模型强度 | 理由 |
|------|------------|------|
| 探索 / 提案 | 强推理 | 需求质量决定一切 |
| 计划生成 | 强推理 | 计划越详细，执行越稳 |
| 执行实施 | 中等即可 | 计划已详细 |
| 归档 | 强推理 | spec diff 需要精确 |

---

## 常见问题

### 新项目如何接入（全局化后）

无需 `openspec init --tools opencode`，用 `openspec init --tools none` 只建 `openspec/` 目录。commands/skills 已全局可用，不必每个项目重复生成 `.opencode`。

### 中断后续接

每个命令可通过 `<change-name>` 自动定位并恢复上下文，支持新会话续接、跨 IDE/模型并行：

```
/opsx-executing-plans add-user-login
```

### 节省 Token

用 `@file` 语法只加载必要文件，而非全部上下文：

```
/opsx-write-plan @openspec/changes/add-user-login/design.md @openspec/changes/add-user-login/tasks.md
```

### 无计划直接实施

若不想用 Superpowers 计划，可用 `/opsx-apply` 直接实施（旁路路径，不经 write-plan/executing-plans）。

### 改动不生效

插件、commands、skills 均在 **opencode 启动时加载**。任何配置变更后需**重启 opencode** 才能生效。

### 插件被误清理后恢复

若 `~/.config/opencode/node_modules/openspec-superpowers` 被清理（如 opencode 升级），用 robocopy 重新复制：

```bash
robocopy "$(npm root -g)/openspec-superpowers" ~/.config/opencode/node_modules/openspec-superpowers /E
```

然后按「环境配置 §4」补回 3 个 skills，重启 opencode。

---

## 经验与排坑

以下经验来自实际配置过程中的踩坑总结，配置前务必阅读。

### 坑 1：插件装在 npm 全局目录，opencode 静默不加载

`opencode.json` 里 `"plugin": ["openspec-superpowers"]` 按**包名**解析，只在 `~/.config/opencode/node_modules/` 查找。装在 npm 全局目录（`$(npm root -g)`）**不会被加载**，且 opencode **不报错**——表现是 commands/skills 全部缺失却找不到原因。

**正解**：插件必须真实存在于 `~/.config/opencode/node_modules/openspec-superpowers/`。判断是否加载成功，看 opencode 会话里 `skill` 工具是否列出 `openspec-*` 与 `test-driven-development` 等 skills。

### 坑 2：同名包陷阱——1.x CLI 与 0.1.0 插件是两个东西

npm registry 的 `openspec-superpowers@1.x` 是 CLI 工具（`generate.js` + `templates/`，生成桥接命令），GitHub fork `MerrillLi/openspec-superpowers@0.1.0` 是 opencode 插件（`index.js` + `skills/`，运行时技能）。两者**同名不同物，缺一不可**。

- `npm install openspec-superpowers`（不带版本）→ 装 1.x CLI，**不是插件**，opencode 加载会失败（无 `index.js` / `main` 字段）
- 插件必须从 GitHub fork 装：`npm install -g git+https://github.com/MerrillLi/openspec-superpowers.git`

判断方法：插件包 `package.json` 有 `"main": "./index.js"` 和 `skills/` 目录；CLI 工具只有 `cli.js` / `generate.js` / `templates/`。

### 坑 3：file: 安装创建 junction，切 Node 版本失效

`npm install file:...` 在 Windows 上创建的是 junction（符号链接），指向源目录。若源在 nvm 版本目录（如 `.../nvm/v24.13.0/node_modules/...`），**切换 Node 版本后链接失效**，插件再次消失。

**正解**：用 `robocopy` 真实复制，不依赖源路径。验证 `(Get-Item <path>).LinkType` 为空（PowerShell）即真实目录。

### 坑 4：fork 插件 0.1.0 缺 3 个 skills，需手动补

fork 插件自带 13 个 skills，但缺 `openspec-write-plan`、`openspec-executing-plans`、`openspec-sync-specs`。这 3 个由 `openspec init` / `npx openspec-superpowers@1` 生成在项目级 `.opencode/skills/`，需手动复制进插件 skills 目录才能全局生效（见「环境配置 §4」）。不补则 `/opsx-write-plan`、`/opsx-executing-plans` 命令虽在，对应 skill 却加载不到。

### 坑 5：用残缺配置硬凑流程，导致语义偏差

当命令/skills 缺失时，**不要**用现有 skill 替代缺失命令掩盖问题。例如用 `subagent-driven-development` 替代 `/opsx-write-plan` 是错的——前者是**执行** skill，后者是**计划生成**，语义完全不同。应按「环境配置」补全缺失组件，让标准流程完整可用。

### 坑 6：git+https 安装可能被重写为 SSH 失败

部分环境 git 配置会把 `https://github.com` 重写为 `ssh://git@github.com`，导致 `npm install git+https://...` 因 SSH 公钥权限失败。此时先 `npm install -g` 装到全局，再 `robocopy` 真实复制到 opencode 配置目录即可绕过。

### 坑 7：openspec init 只生成 5 命令，桥接命令需另跑 npx

`openspec init --tools opencode` 只生成 5 个基础命令（explore/propose/apply/archive/sync）。`/opsx-write-plan` 和 `/opsx-executing-plans` 这两个**桥接命令**由 `npx openspec-superpowers@1 --tools opencode` 额外生成。两步都跑才得到完整 7 命令。