用途
spec-graph 面向项目规格文档（spec）的定位、阅读、创建、更新与校验。其核心理念是：规格是事实来源（ground truth）。规格描述架构、决策、契约与边界，即代码本身无法揭示的意图，应被视为权威依据。
主要能力
规格与图结构
- parent 链接形成镜像代码结构的层级：每个模块旁放置 SPEC.md（分形结构，包及其子目录各有一个），根文档放在仓库根目录。
- depends-on、references、implements 形成跨树的依赖层。
- Frontmatter 必填字段：id（唯一 slug）、type、title；可选：status（生命周期）、parent（单链接）、depends-on / references / implements（链接列表）、covers、tags。
- 文件 frontmatter 含 id 与 type 即视为规格。
- status 取值：draft（编写中）→ active（生效），以及 stale（与代码漂移）、done、deprecated。
- 类型：goal-and-requirements（产品目标与范围，图的根）、architecture-design（系统级拓扑与横切决策）、module-design（包或模块职责与边界）、submodule-design（包内目录级模块）、task-spec（临时工作文档，落地后移除）。
工具
读取类：
- spec_grep：在规格内搜索内容，可按元数据过滤。
- spec_get：获取规格的 frontmatter、解析后的链接及其路径，正文用常规 read 工具读取该路径。
- spec_graph：获取有界图切片——子树、祖先或某节点的邻居，可指定深度。
管理类：
- spec_create：新建规格，生成 frontmatter 与标题骨架。
- spec_update：更新 frontmatter（字段与链接），不触碰正文。
- spec_delete：删除规格。
- spec_validate：报告悬空链接、重复 id 与父级环。
正文使用常规 write/edit 工具撰写与编辑；spec 工具负责 frontmatter 与结构。
使用方式
- 定位：当规格管辖当前工作时，从已知根节点或正在修改的模块出发，用 spec_graph 查看邻域，用 spec_get 获取节点元数据，用 read 读取正文，用 spec_grep 按内容查找规格。
- 对齐：将改动与规格记录的决策和契约对照；若出现矛盾，先呈现并协调，而非静默偏离。
- 更新：当改动改变边界、契约或决策时，更新规格——用 spec_update 更新 frontmatter（含 status），用 edit 更新正文，新模块用 spec_create 创建。
- 检查：结构性变更后运行 spec_validate。
保持查找适度：规格是决策与边界的地图，代码确认实现；不改变任何已记录决策的局部修复、解释或检查，可只查看所需文件。
规格应精简：解释意图而非清单；只记录重要的边界与依赖边；每项事实只在一处出现，其他规格通过 id 链接引用；优先使用散文而非穷举表格，删去仅复述代码、文件名或兄弟规格的内容。
适用场景
适用于需要以文档形式记录架构决策、模块边界、契约与不变量，并让这些记录随代码改动同步维护的软件开发项目，尤其适合多模块、分形目录结构与存在跨模块依赖关系的代码库。
限制
规格是决策与边界的地图，代码才是实现的确证；若规格与代码漂移，将失去事实来源地位，因此改动越界或推翻决策时必须同步更新规格。task-spec 非持久，工作落地后应移除。平台支持范围、收费方式、安装命令等暂未提供。