sdd-project

sdd-project 是一个用于初始化或补全项目 SDD 治理结构的 npm CLI。

它的定位很克制：只负责把项目拉入 OpenSpec + Harness + Superpowers 的工作轨道，不负责后续具体业务开发。项目进入功能开发阶段后，继续使用 OpenSpec 原生命令、skills 和 rules。

核心理念

• OpenSpec：负责需求、proposal、design、tasks、spec delta 和后续 change 执行。
• Harness：负责强脚本化校验、gate、report、doctor，约束 AI coding 不要悄悄越界。
• Superpowers：负责 AI agent 的澄清、规划、审查、验证等工作纪律。
• sdd-project：只负责新项目初始化或现有项目规范补全。

安装

安装最新版本：

npm install -g @magic_csq/sdd-project@latest

安装指定版本：

npm install -g @magic_csq/[email protected]

安装完成后可以确认 CLI 是否可用：

sdd-project --help

让 Codex 显示对应命令

npm 安装只会安装终端命令 sdd-project，不会自动把 Codex 的 / 输入框命令注册进去。

要让 Codex 里出现对应入口，需要再执行：

sdd-project codex install

它会写入：

~/.codex/prompts/sdd-project-init.md
~/.codex/prompts/sdd-project-retrofit.md
~/.codex/skills/sdd-project/SKILL.md
~/.codex/rules/sdd-project.md

然后重启或刷新 Codex，在输入框输入 /，搜索：

prompts:sdd-project-init
prompts:sdd-project-retrofit

如果你使用自定义 Codex home：

sdd-project codex install --codex-home /path/to/.codex

如果需要覆盖已有文件：

sdd-project codex install --force

--force 常用于升级后刷新 Codex 入口描述。例如从旧版本升级后，希望 / 菜单里的说明变成中文，可以执行：

npm install -g @magic_csq/sdd-project@latest
sdd-project codex install --force

刷新后 Codex 中仍然显示稳定入口名：

prompts:sdd-project-init
prompts:sdd-project-retrofit

但它们的描述会显示为中文：

prompts:sdd-project-init      初始化一个符合 SDD / OpenSpec / Harness / Superpowers 思想的新项目
prompts:sdd-project-retrofit  为现有项目补全 SDD / OpenSpec / Harness / Superpowers 规范结构

新项目初始化

在项目根目录执行：

sdd-project init . "项目描述"

示例：

sdd-project init . "一个用于内容发布流程实验的 TypeScript 服务"

它会生成：

openspec/
  project.md
  changes/
  specs/
sdd/
  manifest.json
  gates.json
  context/
  evidence/
  harness/sdd.mjs
  handoff.md
.codex/
  prompts/
  skills/
  rules/

初始化后验证：

node sdd/harness/sdd.mjs validate

现有项目规范补全

在已有项目根目录执行：

sdd-project retrofit . "现有项目描述"

retrofit 会补齐缺失的治理结构，但会尽量保留已有文件。例如：

• 不覆盖已有 openspec/project.md
• 不覆盖已有 OpenSpec / opsx prompt
• 不主动重构业务代码

生成后的 Harness 命令

每个被初始化或补全的项目都会得到项目内 Harness：

node sdd/harness/sdd.mjs validate
node sdd/harness/sdd.mjs gate requirements
node sdd/harness/sdd.mjs gate design
node sdd/harness/sdd.mjs gate implementation
node sdd/harness/sdd.mjs gate verification
node sdd/harness/sdd.mjs report
node sdd/harness/sdd.mjs doctor

Harness 输出以中文为主，例如：

通过 validate
OpenSpec、SDD 上下文和 Harness 文件已存在。

为了兼容旧版本生成的项目，gate marker 会同时接受中文和英文标记；新生成的文档默认使用中文标记，例如 用户确认: true、验收标准:、不在范围:。

注意：这些是项目内 Harness 命令，不是 npm 包的顶层命令。npm 顶层命令只保留：

sdd-project init
sdd-project retrofit
sdd-project codex install

OpenSpec 与 Superpowers

sdd-project init / retrofit 默认会尝试安装或接入伴随工具：

• OpenSpec：npm install -g @fission-ai/openspec@latest
• Superpowers：克隆 https://github.com/obra/superpowers.git 到 .sdd/vendor/superpowers

如果你只是离线测试或不想自动安装：

sdd-project init . "项目描述" --no-install-tools
sdd-project retrofit . "项目描述" --no-install-tools

重要边界

sdd-project 不是 OpenSpec 的替代品。

它只做：

• 初始化项目治理结构
• 补齐现有项目缺失的 SDD 轨道
• 注册 Codex prompts / skill / rules
• 生成项目内 Harness

它不做：

• 业务功能实现
• bugfix
• 普通重构
• OpenSpec change apply/archive/sync
• 替代 OpenSpec commands、skills 或 rules

后续功能开发仍然应该使用 OpenSpec，例如：

prompts:opsx-propose
prompts:opsx-apply
prompts:opsx-archive
prompts:opsx-sync

私有仓库安装方式

如果你需要从 Gitee 私有仓库安装开发版，需要先配置 Gitee SSH 权限，然后：

npm install -g git+ssh://[email protected]/xhh936/sdd-project.git