用途
spec 用于管理协议级规格——即定义系统必须做什么的「契约」。它把需求抽象在协议/标准层面，是代码实现所遵循的唯一来源。规格分为两类：外部规格（需要实现的标准，如 LEAF spec、OAuth、OpenAPI）与自编规格（项目自己定义的协议）。spec 不是功能拆解或 epic，而是需求契约本身。
主要能力
- 查看规格状态：
/spec显示当前项目规格状态，包括规格来源（外部 URL 或自编）、最后更新/同步时间、各章节实现状态、以及各章节关联的 TASK。 - 导入外部规格：
/spec --import <url>从 GitHub 或原始 URL 克隆/获取规格文件，复制到spaces/[project]/docs/specs/，并生成README.md（含来源 URL、版本、最后同步日期、合规检查清单），还可基于规格章节建议初始 TASK。 - 创建协议规格：
/spec --init以对话方式创建项目自编规格，依次询问系统做什么、参与者、核心操作、API 边界、数据模型，输出包含 Overview、Actors、Core Operations、API Specification、Data Models、Required Features、Test Criteria 的规格文档。 - 同步上游：
/spec --sync将导入的规格与上游同步。 - 查看章节：
/spec --section <name>显示规格的特定章节。 - 合规追踪：在规格文档内以需求为粒度使用状态标记（✅ 已实现并可用、🚧 进行中、⏳ 未开始）追踪，
/complete命令在工作完成时更新这些标记，无需引用私有 TASK 即可获得细粒度可见性。
文件结构
规格与代码同仓存放，位于 spaces/[project]/docs/specs/，与 ADR（架构决策）共同放在 docs/ 下。规格之所以与代码同仓：规格是代码要履行的契约，开发者需要与实际实现并列查看，规格与代码变更可形成原子提交。TASK 文件位于 ideas/[project]/issues/，通过 implements: docs/specs/required-features.md#authentication 之类的 frontmatter 链接到所实现的规格章节。
使用方式
完整工作流为：
/spec --init 或 --import # 定义要构建什么
↓
/issue # 创建实现规格章节的工作项
↓
/plan # 拆解实现
↓
/implement # 对照规格构建
↓
/complete # 验证规格合规
创建 TASK 时，/issue 会询问「这个实现对应哪个规格章节？（或填 'none' 表示独立任务）」。相关命令还有 /validate-spec（对照规格检查实现）与 /project-status（查看规格合规总览）。
适用场景
- 实现外部标准的项目（例如 leaf-nextjs-convex 实现 LEAF spec）；
- 需要自编协议规格的项目（例如 coordinatr）；
- 希望在需求层面而非私有 TASK 层面追踪实现进度的团队。
限制与注意事项
- 自编规格应具体、定义边界、包含测试标准、进行版本管理并保持稳定，避免模糊规格导致模糊实现。
- 规格版本管理与 ADR 不同：ADR 不可变，变更需新建替代文档；规格就地编辑，是不断演进的活契约，采用 frontmatter 语义化版本（如
version: 1.0.0）、git 历史、git 标签（如git tag spec-v1.0.0）与 CHANGELOG 记录变更。版本号规则：补丁（1.0.1）为笔误或澄清、无行为变化；次版本（1.1.0）为向后兼容的新可选功能；主版本（2.0.0）为破坏性变更或移除需求。 - 关于收费、价格、支持平台或实际使用效果等事实，资料中暂未提供。