PRD: 双平台 Autopilot Toolkit Monorepo (dual-platform)

[MatthewYe]

Problem Statement

当前 opencode-toolbox 是一个仅支持 OpenCode 的插件。feat/dual-platform 分支尝试在一个包内同时支持 OpenCode 和 Codex，导致：

• autopilot orchestrator 逻辑在两套 prompt 模板（commands/autopilot.md vs skills/autopilot/SKILL.md）中手写重复，漂移风险高
• upstream skills 的分发策略混乱（symlink vs copy）
• agent 派发机制耦合平台工具语法（OpenCode task vs Codex spawn_agent）
• 单包结构难以扩展和维护

Solution

将项目重构为 monorepo 结构，共享核心逻辑和模板，各平台独立成包：

packages/
 core/ ← 共享逻辑 + upstream subtree + 模板文件
 opencode/ ← OpenCode plugin 包
 codex/ ← Codex plugin 包

autopilot orchestrator 的 prompt 模板采用分文件 + JSON manifest 方案，实现：

• 共享流程段为独立 markdown 文件
• 各平台的工具语法（dispatch/wait/shell）为平台特定文件
• manifest.json 声明拼接顺序
• 构建时自动生成各平台的最终 prompt
• LLM-powered lint 脚本检测两套产物的漂移

User Stories

1. 作为 autopilot 维护者，我希望能在一处修改共享流程逻辑，两套平台的 prompt 自动同步，避免手改两份文件
2. 作为 autopilot 维护者，我希望能用 lint 工具自动检测两份 prompt 产物的 drift
3. 作为 OpenCode 用户，插件安装和使用体验不变
4. 作为 Codex 用户，能够安装独立的 autopilot-toolkit-codex 包
5. 作为开发者，能在不影响当前 OpenCode 插件运行的情况下开发新版本（worktree 隔离）
6. 作为 contributor，能通过 manifest.json 理解 autopilot prompt 的组装结构

Implementation Decisions

1. Monorepo 结构

• 使用 bun workspaces，根 package.json 声明 workspaces: ["packages/*"]
• packages/core：private package，不发布。包含 shared.ts、upstream/ subtree、templates/
• packages/opencode：发布为 @matthewye/opencode-toolbox（后续可改名）。OpenCode plugin：config hook 注入 agent/command/skill
• packages/codex：发布为 @matthewye/autopilot-toolkit-codex。通过 plugin.json + .toml 注册

2. 模板方案

分文件 + JSON manifest，不使用自定义 include 语法。所有文件为纯 Markdown。

packages/core/templates/autopilot/
 manifest.json
 shared/ ← 平台无关的流程段
 opencode/ ← OpenCode 特定段
 codex/ ← Codex 特定段

manifest.json 结构：

{
 "opencode": ["shared/00-preamble.md", "opencode/01-target.md", ...],
 "codex": ["shared/00-preamble.md", "codex/01-target.md", ...]
}

3. 构建流程

1. build:core — 编译 packages/core/src/ → dist/
2. build:opencode — 读 manifest → 拼接 prompt；复制 skills；编译 TypeScript
3. build:codex — 读 manifest → 拼接 prompt；复制 skills；生成 .toml；编译

构建脚本：scripts/build-autopilot.ts

4. Lint 机制

scripts/lint-autopilot.ts — LLM 对比两份展开 prod，输出 drift report

5. Agent Prompt 模板化

implementer.md / reviewer.md 也标注平台差异，本期用简单方式

6. Upstream Skills 分发

• packages/core/upstream/ git subtree
• 构建时各平台包复制所需 skills
• 不再使用 symlink

7. Git Worktree 开发隔离

git worktree add ../opencode-toolbox-dev feat/dual-platform

8. 迁移路径

• 现有 OpenCode 用户更新包即可
• Codex 用户安装新包
• 包名变更放到后续

Testing Decisions

• 测试构建脚本输出正确性（snapshot/golden file）
• 测试模块：build-autopilot.ts、shared.ts
• 使用 bun test

Out of Scope

• 包名变更
• npm 发布流程
• Claude Code 适配
• Orchestrator 形态升级（形态 2/3）
• implementer.md / reviewer.md 完整 manifest 方案
• Codex 端本地 .scratch/ 模式适配

Further Notes

• 当前 feat/dual-platform 分支的 skills/autopilot/SKILL.md 和 commands/autopilot.md 是分解素材
• src/shared.ts 已在 feat/dual-platform 上提取，直接可用
• ADR 0002 可能受影响（subtree 路径变更）

[MatthewYe]

autopilot: 开始处理