本仓库实现一个通过 ChatGPT Pro Web 协作处理本地仓库的 Agent Skill。AGENTS.md 维护仓库级协作规则和权威文档导航;产品与 Skill 行为细节维护在对应权威文档中。
- 面向用户的用途、用法和边界:
README.md - 产品行为、权限、技术合同和验收:
docs/specs/*.md;创建或修订 Spec 时遵守define-product-specSkill - 跨规格或长期有效的架构决策:
docs/adr/adr-*.md;创建 ADR 时遵守create-architectural-decision-recordSkill - 决策问题 Spike:
docs/spikes/*.md;创建或执行时遵守create-spikeSkill - 代码规范:
CODE_STANDARD.md - 唯一仓库级开发流程合同:
WORKFLOW.md - 问题修复的最小、必要、可验证流程合同:
PROBLEM_FIXING.md
维护权威文档和指令时:
- 产品行为改变时更新 Spec。
- 仅影响一份 Spec 的选择保留在该 Spec 的“决策记录”;跨规格或长期有效的架构决策记录为 ADR。
- Spec 依赖 ADR 时引用它,不重复其完整理由、替代方案和后果。
- 文档引用 Skill 时,只说明适用场景和本仓库的额外约束;不得重复 Skill 已覆盖的命令、步骤或通用指令。
- 规范性指令只记录会改变执行者选择、动作或放行判断的约束;沿用既有默认行为或不采取额外动作时省略。
- Coordinator:local coordinating session;创建专用 Orca task worktree,通过 Orca Orchestrator 建立并监督 Run、Task 与 Dispatch,维护 writer ownership,并对 Spec 变化、候选验证、Review 和集成负责。
- Implementation writer:Orca supervised worker,默认 Agent 为
opencode;只写入 Orca Task 分配的 write scope,并交付对应 atomic commit。- 不得执行任何非项目脚本或可执行包,包括仓库、项目权威文档或配置未提供的
npx临时包、远程安装器和全局安装命令;确有必要时,必须先通过 Orca Orchestrator 向 Coordinator 说明目的、来源和副作用,并取得明确许可。
- 不得执行任何非项目脚本或可执行包,包括仓库、项目权威文档或配置未提供的
- Independent reviewer:Orca supervised worker,默认 Agent 为
codex;按WORKFLOW.md使用open-code-reviewSkill 只读 Review 最终 aggregate diff 并返回 findings。 - Orca Orchestrator:提供 Run、Task、Dispatch、Message 与可选 decision gate 的运行时生命周期和任务状态。
同一文件或共享状态范围同时只有一个 writer;只读调查可并行。
根据任务场景选择路由:
- 仓库开发
- 协作任务:用户明确要求 Orca task worktree,或任务需要 Implementation writer 或 Independent reviewer 时,按
WORKFLOW.md执行。 - 普通任务:其他仓库写入由当前 Agent 在当前 worktree 直接完成,并执行本文件的“自审”和“验证”。
- 协作任务:用户明确要求 Orca task worktree,或任务需要 Implementation writer 或 Independent reviewer 时,按
- 监督式协作:例如“把任务拆成 A、B、C,交给多个 Agent。”使用
orchestrationSkill。Coordinator 继续对执行过程和最终结果负责;Run、Task、Dispatch、消息、等待和 worker 操作直接遵守版本匹配的 Skill。 - 完整任务交接:例如“把这个任务交给另一个 Agent 完成,你不需要继续跟踪。”使用
orca-cliSkill。 - 普通 Orca 操作:例如“创建一个 Worktree”“在当前 Worktree 启动新 Agent”或“读取指定 Terminal 的输出。”使用
orca-cliSkill。 - 边界不明确:用户仅要求“交给另一个 Agent 或 Worktree”,但没有要求监督、等待或汇总结果时,按完整任务交接处理。
核心判断:任务转交后,当前 Agent 是否继续对执行过程和最终结果负责;继续负责时使用 orchestration,转移所有权或仅操作 Orca 资源时使用 orca-cli。
Coordinator 与 supervised worker 的关系不是 Git branch 关系。运行时协作遵守对应 Skill;仓库候选、验证、Review 和集成遵守 WORKFLOW.md。
- 新提交使用 Unicode Gitmoji,格式为
<gitmoji> (<scope>): <summary>;没有有意义的 scope 时省略(<scope>):。 - 每个提交只使用一个表示主要意图的 Gitmoji,不再叠加
feat:、fix:、docs:等类型前缀。 - 默认保持线性历史:任务分支在实施期间保持隔离;Coordinator 在该分支上同步目标分支,完成全量验证和 Review 后再执行 fast-forward 集成。
- 只有用户明确要求保留分支拓扑,或上游同步必须保留 merge 关系时,才能创建 merge commit。
- 创建 merge commit 时,在最终报告中说明原因。
开发流程的 task branch 隔离、目标分支同步、Review 和集成步骤以 WORKFLOW.md 为准。
新建面向 Agent 或开发者的规范、流程和操作手册类 .md 文件时,默认沿用 CODE_STANDARD.md 和 WORKFLOW.md 的结构:
- 文件顶部只使用一个
#标题。 - 标题后用一段简短导语说明用途、适用范围或触发条件。
- 主体使用连续编号的
## 1. ...章节;每节只承担一个读者任务。 - 平行规则使用项目符号;执行顺序会改变结果时使用编号。
- 文档包含执行、审查、验收或交付流程时,在末尾增加
## N. <阶段>前检查,使用- [ ]列出可判断的放行项。 - 检查项之后使用“最终判断”“最终报告”或“完成条件”收口,标题按文档用途选择。
现有格式合同优先。短说明、README、Spec 和 ADR 不需要机械补齐不适用章节。
任务完成前必须进行自审:
- 核对实现是否完整满足需求。
- 检查逻辑、边界条件、异常处理和安全风险。
- 确认代码符合项目现有结构、风格和约定。
- 避免无关改动、重复实现和过度设计。
- 执行适用的测试、构建、类型检查和静态检查。
- 检查最终改动,删除调试代码、临时内容和敏感信息。
- 不得将未执行的验证描述为已通过。
- 存在未验证项、已知限制或风险时,必须明确说明。
仅在实现、检查和验证均符合要求后,才能声明任务完成。
普通代码改动运行:
pnpm check