SpecDo 是一个本地优先的 AI 开发工作流仓库，用来把四类东西放进同一套可交付结构里：
SuperSpec：负责 spec-driven 主流程和openspecCLIAGENTS：负责角色分工和多智能体协作素材SKILLS：负责开发、调试、评审、发版等执行方法CodeGraph：负责独立整理 CodeGraph 的定位、命令和基础用法
很多 AI 开发流程的问题，不在于模型不会写代码，而在于能力散落：
- spec 工具是一套
- agent 配置是一套
- skill 方法是一套
- 代码理解工具又是另一套
- 交付给别人时又缺统一目录和入口
结果通常是：
- 自己能用，别人接不住
- 当下能跑，长期不好维护
- 仓库里明明有能力，但没有清楚的接入路径
SpecDo 的做法不是再造一个平台，而是把执行核心、角色配置、技能方法和代码理解工具的独立说明整理到同一个仓库里，让这套东西更容易被复用、审查和持续维护。
SpecDo/
├── CodeGraph/ # CodeGraph 独立使用说明
├── SuperSpec/ # 执行核心与 CLI
├── AGENTS/ # agent 配置与角色目录
├── AGENTS.md # 仓库级协作契约
├── SKILLS/ # skill 方法论目录
├── LICENSE
└── README.md
这是执行核心，也是当前仓库里唯一需要正式构建的程序。
它基于 OpenSpec 整理而来，负责：
- 用 spec 驱动需求收敛
- 生成 change 工作目录
- 基于
tasks.md推进执行 - 支持 verify、sync、archive 等收尾动作
独立整理 codegraph 这个项目的用途和基础使用方式，适合：
- 想先搞清楚 CodeGraph 是干嘛的
- 想快速完成安装、初始化和常用命令上手
- 不想把 CodeGraph 的说明混进
SuperSpec或SKILLS叙事里
它负责的不是 spec 主流程，也不是 agent 或 skill 管理，而是另一层能力：
- 先给代码仓库建立索引
- 再按符号、文件、上下文、影响范围去理解项目
- 让 AI 不用每次都从头扫文件
可复用的 agent 角色目录，适合：
- 作为你本地工具的 agent 配置源
- 作为团队内部统一的角色库
- 继续筛选、替换和演进不同职责的 agent
可复用的 skill 目录，适合：
- 给 agent 或人工执行补稳定方法
- 为前后端开发、调试、测试、评审、发版等动作提供默认约束
- 作为团队内部的 skill 素材库
仓库根目录的协作契约文件，用来约束：
- 默认交付标准
- 子代理协作边界
- 测试与自检要求
- 文件与分支约束
- 最终责任
如果你准备把这个仓库交给别人一起维护，这个文件建议优先阅读。
在开始之前，最好先确认这几点：
- 你需要的是一套仓库级工作流，而不是单个命令行工具
- 你愿意在仓库里维护
AGENTS/和SKILLS/这类本地目录 - 你的 AI 编程工具支持，或至少能够兼容 repo-local agents / skills 这类接入方式
- 你接受这套仓库当前是“本地优先整合”，不是“一键托管平台”
如果你只想要一个轻量 CLI，或者完全不打算维护本地 agent / skill 目录，这个仓库通常会比你需要的更重。
下面这条路径的目标不是解释全部能力，而是先把最小闭环跑通。
cd SuperSpec
pnpm install
pnpm run build环境要求：
- Node.js
20.19.0或更高 pnpmgit
SuperSpec 当前暴露出来的命令名仍然是 openspec，不是 specdo。
npm link
openspec --help如果 openspec --help 能正常输出，说明执行核心已经能被当前终端识别。
切到任意测试项目目录：
openspec init
openspec update跑完后，你应该至少能看到项目里生成了 openspec/ 相关结构。
如果这一步能成功，说明 SuperSpec 这条主流程已经接上了。
初始化完成后，再回到这个仓库看两类可选资产：
AGENTS/：决定“谁来做”SKILLS/：决定“怎么做得更稳”
这两层不是 openspec init 自动安装到其他项目里的运行时代码，而是你可以继续挑选、复制、接入和维护的本地素材库。
如果你准备继续扩展这个仓库，建议顺手看一下根目录的 AGENTS.md。
它不是 agent 列表，而是这个仓库默认采用的协作和交付规则。
如果你的 AI 编程工具支持读取本地仓库、复制目录和调整工作区配置，可以直接把下面这段提示词丢给它：
请帮我把当前仓库中的 AI 工作流资产接入到我的本地开发环境中。
目标：
1. 接入 SuperSpec，确保我可以使用 openspec CLI。
2. 梳理并接入 AGENTS 目录中的智能体配置，让我后续可以按角色调用。
3. 梳理并接入 SKILLS 目录中的技能，使其成为本地可用的 skills 素材库。
4. 保留仓库原有目录结构，不要破坏上游内容。
5. 优先使用 repo-local 的接入方式；如果当前工具不支持，请明确说明替代方案。
请按下面顺序执行：
1. 检查当前工具支持哪些本地 agent / skill 接入方式。
2. 构建并验证 SuperSpec：
- 进入 SuperSpec
- 安装依赖
- 构建
- 如有需要，执行 npm link
- 验证 openspec --help
3. 读取 AGENTS/README.md 和 SKILLS/README.md，理解这两个目录的用途。
4. 将 AGENTS 和 SKILLS 以当前工具支持的方式接入；如果不能自动接入，就给出最小手工步骤。
5. 最后输出一份接入结果摘要：
- SuperSpec 是否可用
- 哪些 agents 已可直接使用
- 哪些 skills 已可直接使用
- 哪些部分仍需手工处理
- 后续建议先看哪些目录或文件
要求：
- 面向中文输出
- 不要假装已经接入成功，未完成的步骤必须明确标注
- 不要随意删除或改写仓库中的 agent 和 skill 内容
这段提示词适合用在“让 AI 先帮你把仓库接上环境”这个场景。如果你的工具不支持自动发现 repo-local agents / skills，它至少也能先帮你完成 SuperSpec 构建，并把剩余接入步骤整理出来。
可以把 SpecDo 理解成一条三段式工作流：
-
用
SuperSpec负责主流程
从需求、proposal、spec、design、tasks，一直到 apply、verify、archive。 -
用
AGENTS负责角色分工
例如把前端任务交给前端 agent，把评审任务交给 reviewer，把调试任务交给 debugger。 -
用
SKILLS负责执行约束
例如用test-driven-development控制实现节奏，用systematic-debugging约束排查过程，用release-management管发版收尾。
这三层不是互相替代，而是各自负责不同层次：
SuperSpec定义主流程AGENTS定义角色SKILLS定义方法
如果把 CodeGraph 也算进去，可以理解成四层分工：
CodeGraph负责代码理解SuperSpec负责主流程AGENTS负责角色SKILLS负责方法
假设你要做一个“增加暗色模式”的需求，可以按这个顺序理解：
- 用
openspec在业务项目里创建和推进 change - 在
tasks.md里写清任务目标、验证方式和 review focus - 把实现任务交给前端或全栈 agent
- 在实现前后套用
test-driven-development、webapp-testing、code-reviewer - 最后用 verify、sync、archive 收尾
这就是 SpecDo 的核心思路：
主流程由 SuperSpec 驱动，角色协作由 AGENTS 补齐，执行质量由 SKILLS 约束。
如果你第一次打开这个仓库，建议按这个顺序看：
- 先看 SuperSpec，确认主流程和 CLI 是不是你要的
- 再看 AGENTS，判断角色目录是否适合你的协作方式
- 再看 SKILLS，挑出你真会用到的方法目录
- 最后看 AGENTS.md，确认这套仓库默认的协作规则是否符合你的预期
SpecDo 解决的是“能力整理、目录组织和本地交付”问题，不解决所有外部工具自动兼容问题。
当前边界主要包括：
- 不保证所有 AI 工具都能直接识别
AGENTS/或SKILLS/ - 不负责替你托管远程服务或做平台级集成
- 不承诺所有目录都必须一键接入
AGENTS/和SKILLS/更偏本地可审计素材，而不是统一远程市场
使用这套仓库时，至少应遵守这些基本原则：
- 不提交密钥、令牌、私有配置
- 不默认信任新增第三方 skill 或 agent
- 先在低风险项目中验证，再带入正式环境
- 保持目录清洁，不把缓存、日志、临时产物提交进来
如果你准备继续扩展这个仓库，建议按层处理：
- 改
SuperSpec：表示你在改执行核心 - 改
AGENTS：表示你在改角色资产 - 改
SKILLS：表示你在改方法资产
尽量不要把三个层次的问题混进同一次改动里。如果是对外可见的行为变化，最好同时补文档和验证说明。