openspec-starter

OpenSpec 项目初始化工具，提供语言模板自动合并和 AI Agent Skill 安装能力。

背景

在不同语言的项目中使用 OpenSpec，每次都需要手动调整 openspec/config.yaml——不同语言有不同的构建工具、编码规范和上下文要求，重复配置既繁琐又容易遗漏。

openspec-starter 的核心思路是：把语言相关的配置抽成全局模板，一次设置，所有项目复用。 初始化时选择当前项目的开发语言，工具自动将对应模板合并进 OpenSpec 配置，省去手动填写的步骤。模板存储在本机全局目录，可随时编辑，升级工具不会覆盖你的自定义内容。

除此之外，初始化时还会自动安装两个 AI Skill：

• create-projectmap — 为整个仓库生成结构化的项目知识地图，描述业务定位、模块关系、关键流程和外部依赖。
• create-codemap — 为指定功能模块生成功能级代码地图，包含调用链路、核心对象和风险点。

有了这两张地图，AI 在开发过程中可以直接查阅，而不需要反复检索源码，响应更准确，上下文更聚焦。

前置要求

• Node.js >= 18
• npm

安装

npm install -g openspec-starter

命令

openspec-starter init

在当前目录初始化 OpenSpec 项目，执行流程：

1. 从交互式欢迎界面选择开发语言
2. 若未安装 @fission-ai/openspec，自动安装
3. 执行 openspec init（选择 AI 工具、生成配置文件）
4. 将语言模板合并到 openspec/config.yaml
5. 安装 create-codemap 和 create-projectmap Skill

openspec-starter init

支持的语言： Java、Golang、Python、TypeScript、Rust、C#、PHP

openspec-starter template

列出所有语言模板，展示 context 预览和规则数量。

openspec-starter template

openspec-starter template <lang>

交互式编辑指定语言的全局模板，修改内容保存到 ~/.openspec-starter/templates/<lang>.yaml，下次 init 时生效。

openspec-starter template java
openspec-starter template typescript

可编辑的字段：

| 字段 | 说明 | |------|------| | schema | OpenSpec schema 类型，如 spec-driven | | context | 注入 AI Agent 系统提示的自由文本 | | rules | 按 artifact 追加的规则列表 |

openspec-starter update

将 openspec-starter 和 @fission-ai/openspec 同时更新到最新版本。

openspec-starter update

全局模板

默认模板随包内置，首次运行时复制到：

~/.openspec-starter/templates/
├── java.yaml
├── golang.yaml
├── python.yaml
├── typescript.yaml
├── rust.yaml
├── csharp.yaml
└── php.yaml

可通过 openspec-starter template <lang> 编辑，也可直接修改 YAML 文件。更新工具不会覆盖已有模板，只补全缺失的文件。

已安装的 Skill

执行 init 后，会安装以下两个 Skill：

| Skill | 说明 | |-------|------| | create-codemap | 从源码生成功能模块级代码知识地图（CodeMap），包含完整调用链路、核心对象、风险点和排查建议 | | create-projectmap | 从源码生成仓库级代码地图（ProjectMap），描述业务定位、模块结构、运行单元、关键流程和外部依赖 |

使用示例：

/create-projectmap
/create-codemap <模块名>

模板合并策略

将语言模板应用到已有的 openspec/config.yaml 时，采用追加合并，不覆盖已有内容：

| 字段类型 | 合并行为 | |----------|----------| | context（字符串） | 追加到现有内容之后 | | rules（数组） | 数组合并，保留已有条目，追加新条目 | | 标量字段（如 schema） | 已存在则跳过 | | 新字段 | 直接添加 |

在已有项目上重复执行 init 是安全的，不会丢失任何已有配置。

License

MIT