@lixin5257xxx/opsx-workflow

一键将 OpenSpec × Superpowers 两阶段工作流安装到任意前端项目，支持 Cursor、Claude Code、OpenClaw。

无需手工复制 .cursor/skills：运行安装器后自动完成：

1. 选择编辑器（Cursor / Claude Code / OpenClaw）
2. 选择项目目录
3. 写入 OPSX workflow（skills、slash 命令、规则）
4. 若无 openspec/ → 执行 openspec init
5. 检测 Superpowers（项目内 + 本机全局/插件）；若无则从 obra/superpowers 克隆，失败时按所选编辑器输出手动安装指引
6. 检测 Playwright E2E 环境：已有 @playwright/test + playwright.config + e2e/**/*.spec.ts + dev 脚本 → 直接复用；否则自动安装依赖、写入 playwright.config.ts、e2e/ 脚手架、e2e/e2e-scope.config.json（按 src/features 推断模块），并执行 playwright install chromium
7. 生成 .opsx/config.json、注入 package.json 脚本（含 opsx:assess-e2e、e2e、playwright:install）

快速开始

需要 Node.js 14+。

# 交互式安装（推荐）
npx @lixin5257xxx/opsx-workflow

# 非交互
npx @lixin5257xxx/opsx-workflow setup --editor cursor --project /path/to/app -y

# Claude Code
npx @lixin5257xxx/opsx-workflow setup --editor claude-code -y

# OpenClaw
npx @lixin5257xxx/opsx-workflow setup --editor openclaw -y

# 健康检查
npx @lixin5257xxx/opsx-workflow doctor --project .

安装后工作流（与 poquan-web 对齐）

| 入口 | 行为 | |------|------| | 自然语言描述需求（会改 src/ 或 e2e/） | 自动 Propose → Apply → opsx:delivery-pipeline（无需 slash） | | /opsx-propose | 仅提案，不自动 Apply | | /opsx-apply | 已有 change 上 TDD + 审查 + pipeline |

安装后写入 AGENTS.md（SSOT）、docs/agent-workflow.md、强制规则 opsx-mandatory-workflow.mdc（Cursor）/ .claude/rules/code-changes.md（Claude Code），以及 opsx:gate 提交门禁脚本。

强制 TDD（根源 + 门禁）

| 阶段 | 约束 | |------|------| | Propose | tasks.md 必须按 tdd-script/templates/tasks-tdd.md（Red/Green 交错，禁止末尾打包单测） | | Apply | 每条 Red/Green 用 tdd-evidence.sh <change> ... 留痕至 evidence/<change>/ | | Pipeline | assert-tdd-tasks-shape.sh + assert-tdd-evidence.sh + scoped unit（默认 change，非全量） |

逃生：OPSX_SKIP_TDD_TASKS_SHAPE=1 / OPSX_SKIP_TDD_EVIDENCE=1，或 tasks 首行 TDD_EXEMPT:。

详见安装后的 opsx-superpowers-workflow/SKILL.md。

选项

| 选项 | 说明 | |------|------| | --editor cursor\|claude-code\|openclaw | 指定编辑器 | | --project <path> | 项目根目录 | | -y, --yes | 跳过确认 | | --skip-openspec | 不运行 openspec init | | --skip-superpowers | 不安装 Superpowers（仍会检测是否已存在） | | --skip-e2e | 不检测/安装 Playwright E2E 脚手架 |

Monorepo（子目录安装）

若将 OPSX 装在 frontend/ 等子目录，而仓库根已有 OpenSpec 官方的 .cursor/commands，Cursor 会合并多份 /opsx-apply，Agent 可能误跟根目录简版。安装器在检测到上级存在 commands 目录时，会自动写入桥接的 opsx-apply.md、opsx-propose.md 及重写过技能路径的 .mdc 规则，强制指向子目录下的 opsx-superpowers-workflow。

更稳妥的做法：对单仓前端项目将 安装目标选为仓库根（--project <repo>），使 .cursor/ 与 openspec/、根 package.json 对齐。

本仓库为独立发版仓库。维护 bundle/ 时：

• 推荐：指向最新 poquan-web 后执行
  OPSX_POQUAN_ROOT=/path/to/poquan-web npm run sync-bundle
  会全量同步 OpenSpec / delivery / 专项 skills 与规则，并剔除 delivery reports/ 运行产物（仅保留 .gitkeep）。
• 独立仓库内：无 poquan 路径时仅从已提交的 bundle/ + workflow-source/ 增量刷新；首次需先有一次带 OPSX_POQUAN_ROOT 的完整同步。

# 在 packages/opsx-workflow 目录
OPSX_POQUAN_ROOT=/path/to/poquan-web npm run sync-bundle
npm run publish:pkg

详见仓库根 README.md。

目录结构（安装到目标项目）

.opsx/
  config.json       # 测试命令、dev URL、delivery skill 路径
  installed.json    # 安装记录
.cursor/            # 或 .claude/ / .agents/
  skills/           # OPSX + Superpowers + OpenSpec skills
  commands/         # opsx-*.md（Cursor / Claude Code）
  rules/            # opsx-workflow.mdc（Cursor）
AGENTS.md           # Claude Code / OpenClaw 工作流说明段落
openspec/           # openspec init 生成

许可证

MIT