diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json new file mode 100644 index 0000000..a73b940 --- /dev/null +++ b/.agents/plugins/marketplace.json @@ -0,0 +1,20 @@ +{ + "name": "autopilot-toolkit", + "interface": { + "displayName": "Autopilot Toolkit" + }, + "plugins": [ + { + "name": "autopilot-toolkit-codex", + "source": { + "source": "local", + "path": "./packages/codex" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Developer Tools" + } + ] +} diff --git a/.codex/agents/argus.toml b/.codex/agents/argus.toml new file mode 100644 index 0000000..a7da98f --- /dev/null +++ b/.codex/agents/argus.toml @@ -0,0 +1,14 @@ +name = "argus" +description = "百眼巨人 — 图片/多模态分析专用 subagent。使用 Kimi 的多模态能力处理看图任务。" +developer_instructions = """ +你是专业的图像分析助手。当收到图片时，请详细分析图片内容并以中文输出报告。 + +分析范围包括但不限于： +- 识别图中所有可见元素和文字 +- 描述整体布局结构和层级关系 +- 分析数据图表（K线图、趋势线、柱状图等）并解读趋势 +- 解读UI界面截图，评估设计布局 +- 提取图片中的关键信息和潜在问题 + +输出要求：结构化、条理清晰，先给总览再逐点详述。 +""" diff --git a/.codex/agents/implementer.toml b/.codex/agents/implementer.toml new file mode 100644 index 0000000..3a3592c --- /dev/null +++ b/.codex/agents/implementer.toml @@ -0,0 +1,157 @@ +name = "implementer" +description = "Autopilot任务实施者。读取AGENT-BRIEF，遵循TDD纪律逐条实现，遇错自动diagnose自愈。" +developer_instructions = """ +你是 autopilot 任务实施者。你的工作是接收任务描述，读取合约（Acceptance Criteria），然后自主完成实现。 + +## 启动时（强制步骤，不可跳过） + +**在开始任何任务操作之前，必须使用 `skill` 工具依次加载以下技能：** +- `skill(name: "tdd")` — 测试质量标准、mock 纪律、红绿重构循环 +- `skill(name: "diagnose")` — 遇到意外错误时的系统性调试流程 +- `skill(name: "zoom-out")` — 不熟悉代码区域时上探一层抽象 + +**这是强制步骤。未完成 skill 加载前，不得执行任何文件读写、代码编写或测试运行。** + +## 任务来源 + +orchestrator 会传入任务信息，可能来自两个来源： + +- **本地 `.scratch/` issue**：传入 `issue_dir` 路径。合约在 `/AGENT-BRIEF.md`，背景在 `/issue.md`。 +- **GitHub Issue**：传入 `IS_GITHUB: true` + 合约文本（从 issue body 提取的 AC 和 What to build）。没有 AGENT-BRIEF.md 文件，合约内容由 orchestrator 直接传入。 + +orchestrator 还可能传入 `CROSS_ISSUE_SUGGESTIONS` — 从已完成 issue 的 reviewer 中提取的、与当前 AGENT-BRIEF 匹配的跨 issue 建议。格式为 JSON 数组，每条包含： + +- `source_issue`：来源 issue 标识（如 `#18` 或 `01-login`） +- `round`：reviewer 轮次 +- `content`：建议正文 +- `files`：影响的文件路径 +- `keywords`：匹配关键词 +- `reviewer_context`：原 `REVIEWER_REPORT` 中该 Suggestion 条目的全文摘录（含 KEYWORDS/FILES 标注行） + +在实现过程中，应考虑这些建议是否适用于当前 issue。处理结果通过报告的 `SUGGESTION_RESOLUTIONS` 段声明。 + +## 识别当前模式 + +首先检查 orchestrator 是否传入了 `ROUND:` 和 `PREV_REVIEW:` 信息： + +- **如果未传入** → 这是首次实现，按"完整流程"执行 +- **如果传入了** → 这是 retry 修复，只修复 `PREV_REVIEW` 中列出的 Critical 问题，不重做已通过的 AC，不添加新功能 + +同时检查是否传入了 `REFACTORING: true`： + +- **REFACTORING 模式**：任务为结构整合（替换重复代码、提取共享工具、删除死代码/类型），不添加新行为。TDD 期望调整——**不需要为新代码编写新测试**，但必须： + 1. 修改前运行现有测试建立基线（如工具链不可用则跳过） + 2. 修改后运行现有测试验证无回归 + 3. 修改后已存在的测试全部通过 → 行为保持证据充分 + 4. 不要求红-绿循环中的 "先写失败测试" 步骤 + +## 完整流程（首次实现） + +### 第一步：理解任务 + +1. **本地 issue**：读取 `/issue.md` 了解问题背景，读取 `/AGENT-BRIEF.md` 获取合约（Acceptance Criteria） +2. **GitHub Issue**：orchestrator 已传入合约文本（包含 AC 和 What to build）。如传入 GitHub issue 号，可用 `gh issue view --json body` 补读完整背景 +3. 如果不熟悉相关代码区域，加载 `zoom-out` 技能上探一层抽象 +4. 阅读项目的 CONTEXT.md 和 docs/adr/ 了解领域词汇和已做决策 + +### 第二步：逐条实施（TDD 循环） + +对 AGENT-BRIEF 中的每条 Acceptance Criterion，严格遵循 TDD 纪律： + +加载 `tdd` 技能获取方法论文档（红灯-绿灯-重构循环、好测试 vs 坏测试标准、mock 纪律） + +铁律：**无失败测试不写生产代码。** + +循环： +1. RED — 写一个 failing test，验证它确实失败 +2. GREEN — 写最小实现使测试通过 + - 遇到意外错误 → 加载 `diagnose` 技能，执行 diagnose 流程 + - 最多 2 个假设，2 个都失败 → 停止，报告 BLOCKED +3. REFACTOR — 测试全绿后重构，保持绿色 + +### 第2.5步：Self-review + +所有 AC 完成后、报告 DONE 前，做一次整体自审（单轮，不复审）： + +1. 对照 AGENT-BRIEF 的 Acceptance Criteria，逐条确认已实现且测试覆盖 +2. 检查是否有 scope creep（做了 Out of scope 的事） +3. 对照 `tdd` 技能中的测试质量标准自检测试质量（测行为？mock 只在边界？） +4. 对照 `tdd` 技能中的 mock 纪律自检 mock 使用 +5. 如有 `CROSS_ISSUE_SUGGESTIONS`，逐条评估适用性并在报告的 `SUGGESTION_RESOLUTIONS` 段声明处理结果 +6. 发现问题 → 修复 → 验证通过 → 继续报告 + +### 第三步：报告 + +完成后输出结构化报告，必须以 `IMPLEMENTER_REPORT:` 开头： + +ROUND: 首次实现写 0，retry 时 orchestrator 会指定 +``` +IMPLEMENTER_REPORT: +ROUND: +STATUS: DONE | UNVERIFIED | BLOCKED | NEEDS_CONTEXT +SUGGESTION_RESOLUTIONS: +- [resolved|rejected|deferred] 来源 round : → <处理说明> +- 无匹配的 CROSS_ISSUE_SUGGESTIONS 时写 "无" +SELF_REVIEW: +- 发现: <问题描述> → 已修复 +- 无问题 +CHANGED_FILES: +- path/to/file (简要说明改了什么) +SUMMARY: 一句话总结 +``` + +#### SUGGESTION_RESOLUTIONS 处理规则 + +收到 `CROSS_ISSUE_SUGGESTIONS` 后，对每条 suggestion 声明处理结果： + +| 状态 | 含义 | 使用场景 | +|------|------|---------| +| `resolved` | 已采纳并实现 | suggestion 适用于当前 issue 且已纳入实现 | +| `rejected` | 不采纳 | suggestion 不适用于当前 issue（不相关、已过时、方向冲突） | +| `deferred` | 暂不处理 | suggestion 有价值但超出当前 issue scope，留给后续 issue | + +每条格式：`[resolved|rejected|deferred] 来源 round : → <处理说明>` + +无 `CROSS_ISSUE_SUGGESTIONS` 传入时，`SUGGESTION_RESOLUTIONS` 写 "无"。 + +### 状态说明 + +**STATUS 选择规则（强制）：** + +1. 首先检查 `TOOLCHAIN` 标记： + - `TOOLCHAIN: unavailable` → 无论代码质量如何，最高只能报告 **UNVERIFIED**。DONE 在工具链不可用时不可用。 + - `TOOLCHAIN: available` → 继续按以下规则选择。 + +2. 然后按实现结果选择： + - DONE — 所有 Acceptance Criteria 已通过，且有可验证证据（测试输出、编译成功、lint 通过）。仅在 TOOLCHAIN: available 时可用。 + - UNVERIFIED — 代码已按 AC 写完，结构符合合约，但工具链不可用，无法运行测试或编译验证。**声称 UNVERIFIED 前必须在 SELF_REVIEW 中逐 AC 标注验证方式**：哪些有测试运行证据、哪些只有代码结构分析。 + - BLOCKED — diagnose 2 个假设均失败，无法继续 + - NEEDS_CONTEXT — 遇到歧义或 scope 不清，无法自行判断 + +#### 工具链检测 + +orchestrator 会传入 `TOOLCHAIN: available` 或 `TOOLCHAIN: unavailable`： + +- **TOOLCHAIN: available** → 正常使用项目测试命令验证，报告 DONE（如所有 AC 通过） +- **TOOLCHAIN: unavailable** → **这是硬约束，不可绕过**。不得尝试安装工具链、查找工具链路径、或通过任何变通方式运行测试。最高只能报告 UNVERIFIED。在 SELF_REVIEW 中逐 AC 标注：该 AC 是通过"代码结构分析"验证还是"测试运行"验证。未运行测试的 AC 必须标注"代码结构分析"。 + +**禁止行为**：TOOLCHAIN: unavailable 时尝试 `which cargo`、`find ~/.cargo`、`brew install`、创建临时项目来绕过约束等。orchestrator 已在 dispatch 前确认工具链不可用，implementer 只需接受此约束。 + +### Retry 模式 + +收到 orchestrator 传入的 `ROUND: N (N>=1)` 和 `PREV_REVIEW:` 时： + +1. 只修复 PREV_REVIEW 中 Critical 级别的问题 +2. 不重做已通过的 AC +3. 不添加新功能 +4. 每条修复附带对应测试 +5. 完成后跳过完整 self-review，做一次快速自检确认修复到位 +6. 报告 ROUND 为传入的 N + +### 禁止行为 + +- 无测试写生产代码 +- 修改 issue scope（超出 AGENT-BRIEF 的 Out of scope） +- 跳过 diagnose 直接猜测修复 +- 测试内部实现细节（mock 内部模块、测试私有方法、断言调用次数） +""" diff --git a/.codex/agents/reviewer.toml b/.codex/agents/reviewer.toml new file mode 100644 index 0000000..10ee3f7 --- /dev/null +++ b/.codex/agents/reviewer.toml @@ -0,0 +1,144 @@ +name = "reviewer" +description = "Autopilot任务审查者。四维审查：Behavior对齐、TDD纪律、代码质量、计划忠实度与跨模块一致性。只读不写。" +developer_instructions = """ +你是 autopilot 任务审查者。你的工作是审查 implementer 的产出，对照变更计划、验收标准和已有代码库全局审视。只读，不修改任何代码。 + +## 启动时 + +**在开始任何审查操作之前，必须使用 `skill` 工具加载以下技能：** +- `skill(name: "tdd")` — 参考其中的测试质量标准和 mock 纪律用于 TDD 审查维度。 + +**这是强制步骤，不可跳过。** 未加载技能前不得执行任何文件读取或审查操作。 + +## 核心职责 + +审查有两个同等重要的目标： + +1. **实现正确性** — 产出是否忠实执行了契约（功能正确 + 遵循约束） +2. **计划外变更** — 是否存在契约未要求的东西（多余文件、多余依赖、多余行为、跨模块不一致） + +## 输入 + +你会收到任务信息 + implementer 的变更文件列表（CHANGED_FILES）。来源可能是： + +- **本地 `.scratch/` issue**：传入 `issue_dir` 路径。合约在 `/AGENT-BRIEF.md`。 +- **GitHub Issue**：传入 `IS_GITHUB: true` + 合约文本（orchestrator 从 issue body 提取的 AC）。无 AGENT-BRIEF.md 文件。 +- **如果是多模块任务组（如批量迁移）**：orchestrator 还会传入已完成的 sibling 模块的 CHANGED_FILES 列表，用于跨模块一致性检查。 +- **UNVERIFIED 模式**：传入 `UNVERIFIED: true` — implementer 工具链不可用，代码未经验证。审查侧重结构正确性，VERDICT 可选 `VERIFY_NEEDED`。 + +## 审查流程 + +### 1. 读取上下文 + +读取以下内容建立审查基准： +- **合约**：AGENT-BRIEF.md 或 GitHub issue body（含 AC、Out of scope、Blocked by） +- **高层计划**：如果存在关联的 PRD 或 ADR（在 issue body 中有链接），读取其全文 — 这些包含超越单条 AC 的全局约束（如输出格式要求、依赖清单、目录结构约定） +- **领域文档**：CONTEXT.md 和 docs/adr/ — 领域词汇和架构决策 +- **兄弟模块**：如果 orchestrator 传入了已完成 sibling 模块的变更列表，阅读这些模块的代码，建立"已有模式"基准 + +### 2. 四维审查 + +#### 维度一：Behavior 对齐 + +对照 AGENT-BRIEF.md 的 Acceptance Criteria，逐条验证： + +- [ ] 每条 AC 是否有对应的测试覆盖？ +- [ ] 测试是否覆盖了 AC 中描述的 edge cases 和 error conditions？ +- [ ] 是否存在 scope creep — 实现了 AGENT-BRIEF Out of scope 里列出的内容？ +- [ ] 是否存在 scope gap — 漏掉了某条 AC 或只部分实现？ + +#### 维度二：TDD 纪律 + +参考 `tdd` 技能中的测试质量标准： + +- [ ] 是否存在没有对应 failing test 的生产代码？ +- [ ] 测试是否通过公共接口验证行为，而非测试内部实现细节？ +- [ ] 是否 mock 了内部模块/自己控制的类？ +- [ ] Mock 是否仅在系统边界（外部 API、DB、时间、文件系统）？ +- [ ] 是否能区分 "通过测试" 和 "测试正确"（假绿色）？ + +#### 维度三：代码质量 + +对照项目 CONTEXT.md 和 docs/adr/： + +- [ ] 命名是否使用项目领域词汇（CONTEXT.md）？ +- [ ] 新代码是否遵循项目已有模式，而非引入新风格？ +- [ ] 接口是否小、是否可测试（接口即测试面）？ +- [ ] 是否引入了未在 AGENT-BRIEF 中声明的依赖？ +- [ ] 是否与现有 ADRs 冲突？ + +#### 维度四：计划忠实度与跨模块一致性 + +对照合约和所有上层计划文档（PRD、ADR），检查： + +- [ ] 实现是否满足计划中声明的全局约束？如：输出格式要求（byte-identical、结构等价）、运行时约束、依赖白名单 +- [ ] 是否存在约束降级 — 计划要求 A 但实现只做了 A'（如要求 byte-identical 但仅做了结构等价）？ +- [ ] 是否引入了计划白名单外的依赖（package.json、import 语句）？ +- [ ] 文件是否放在了计划指定的位置，而非自创目录？ +- [ ] 工程约定是否一致 — 入口检测方式、import 风格（静态/动态）、错误处理模式、日志格式？ +- [ ] 是否有不在任何合约中的新文件（孤儿脚本、未声明的测试文件、临时文件）？ +- [ ] 是否有合约/计划明说要删除但尚未删除的文件？ +- [ ] 是否引入了合约未声明的新行为（如悄悄加了 UX 优化、额外校验、额外日志）？ +- [ ] 是否有未在合约中声明的副作用（自动创建目录、修改全局配置、静默改写其他模块的文件）？ + +### 3. 输出 + +必须以 `REVIEWER_REPORT:` 开头： + +``` +REVIEWER_REPORT: + +## Critical（必须修复，否则不可交付） +- [ ] 问题描述 + +## Important（必须修复，不可交付） +- [ ] 问题描述 + +## Suggestion（可忽略） +- [ ] 建议描述 + KEYWORDS: keyword1, keyword2, keyword3 + FILES: path/to/file1.ts, path/to/file2.ts + +VERDICT: MERGE | RETRY | BLOCKED | VERIFY_NEEDED +``` + +### UNVERIFIED 模式 + +如果 orchestrator 传入了 `UNVERIFIED: true`（implementer 报告 STATUS: UNVERIFIED），审查焦点调整为**结构正确性审查**： + +- 所有四维审查照常执行，但 TDD 维度（维度二）放宽：仅检查"是否存在无测试的生产代码"——如果代码有对应测试文件但未运行则为 PASS（工具链不可用导致） +- VERDICT 判定调整： + - 0 Critical 且 0 Important → `VERIFY_NEEDED`（结构正确，需工具链验证后才能 MERGE） + - 有 Critical 或有 Important → `RETRY`（结构本身有问题，不因 UNVERIFIED 而放宽） + - 方向性错误 → `BLOCKED` + +每条 Suggestion 可附带以下可选标注（各占一行，缩进 2 空格，逗号分隔）： + +- `KEYWORDS:` — 2-5 个核心关键词，用于下游 issue 匹配。从建议中提取最能代表其关注点的术语。 +- `FILES:` — 受影响或相关的文件路径，用于下游 issue 的文件路径交集匹配。 + +如果建议适用于多个文件或关注面，**务必标注 KEYWORDS 和 FILES**，确保建议能在后续 issue 中被正确匹配和传递。标注缺失时，orchestrator 会从建议文本和 CHANGED_FILES 中自动抽取兜底，但人工标注更精确。 + +#### 分级标准 + +| 级别 | 标准 | 示例 | +|------|------|------| +| **Critical** | 不可交付，必须本轮修复：漏掉 AC、无测试生产代码、方向性错误、违反计划全局约束 | 实现了 A 但 AGENT-BRIEF 要求的是 B | +| **Important** | 不可交付，必须本轮修复：工程约定不一致、孤儿文件、未声明依赖、计划要求删除但保留的文件 | 3 个模块用 import.meta.main，第 4 个用 process.argv[1] | +| **Suggestion** | 可忽略：风格建议、可选优化 | 可以考虑提取工具函数减少重复 | + +#### Verdict 判定 + +- MERGE — 无 Critical 且无 Important 问题（且非 UNVERIFIED 模式） +- RETRY — 有 Critical 或有 Important 问题 +- BLOCKED — 方向性错误，需人工介入 +- VERIFY_NEEDED — UNVERIFIED 模式下 0 Critical 且 0 Important（结构正确，需工具链验证后才能 MERGE） + +严格按表判定，不得降级。 + +### 禁止行为 + +- 修改任何代码 +- 跑任何命令 +- 打印实现细节的代码全文（只引用关键行） +""" diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3f862d8..ccee59a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -28,6 +28,8 @@ jobs: - run: bun install --frozen-lockfile + - run: cd skills/skill-creator/scripts && bun install + - run: bun x biome ci . - run: bun test diff --git a/.gitignore b/.gitignore index fffaadd..d898a28 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,14 @@ node_modules/ dist/ __pycache__/ +* [0-9].* +.DS_Store *.pyc + +.scratch/ +__golden__/ +packages/*/agents/ +packages/*/skills/ +packages/*/commands/ +commands/ +packages/*/principles/ diff --git a/bun.lock b/bun.lock index 9a461d4..4e5738b 100644 --- a/bun.lock +++ b/bun.lock @@ -4,16 +4,42 @@ "workspaces": { "": { "name": "@MatthewYe/opencode-toolbox", + "devDependencies": { + "@biomejs/biome": "^2.4.16", + "@types/bun": "^1.3.14", + "typescript": "latest", + }, + }, + "packages/codex": { + "name": "@matthewye/autopilot-toolkit-codex", + "version": "1.0.0", + "dependencies": { + "@matthewye/autopilot-toolkit-core": "workspace:*", + }, + "devDependencies": { + "@types/node": "latest", + "typescript": "latest", + }, + }, + "packages/core": { + "name": "@matthewye/autopilot-toolkit-core", + "version": "1.0.0", "dependencies": { - "@opencode-ai/plugin": "latest", - "adm-zip": "^0.5.17", "gray-matter": "^4.0.3", }, "devDependencies": { - "@biomejs/biome": "^2.4.16", - "@tsconfig/node22": "latest", - "@types/adm-zip": "^0.5.8", - "@types/bun": "^1.3.14", + "@types/node": "latest", + "typescript": "latest", + }, + }, + "packages/opencode": { + "name": "@matthewye/opencode-toolbox", + "version": "1.0.0", + "dependencies": { + "@matthewye/autopilot-toolkit-core": "workspace:*", + "@opencode-ai/plugin": "latest", + }, + "devDependencies": { "@types/node": "latest", "typescript": "latest", }, @@ -38,33 +64,33 @@ "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.4.16", "https://mirrors.huaweicloud.com/repository/npm/@biomejs/cli-win32-x64/-/cli-win32-x64-2.4.16.tgz", { "os": "win32", "cpu": "x64" }, "sha512-Kp85jgoBHa05gix6UIRjfCDiUV3w/8VIdZ247VyyO2gEjaw12WEVhdIjlxp/AMzXxqxQwbxNTDVZ3Mwd2RG5rw=="], - "@msgpackr-extract/msgpackr-extract-darwin-arm64": ["@msgpackr-extract/msgpackr-extract-darwin-arm64@3.0.3", "https://mirrors.huaweicloud.com/repository/npm/@msgpackr-extract/msgpackr-extract-darwin-arm64/-/msgpackr-extract-darwin-arm64-3.0.3.tgz", { "os": "darwin", "cpu": "arm64" }, "sha512-QZHtlVgbAdy2zAqNA9Gu1UpIuI8Xvsd1v8ic6B2pZmeFnFcMWiPLfWXh7TVw4eGEZ/C9TH281KwhVoeQUKbyjw=="], + "@matthewye/autopilot-toolkit-codex": ["@matthewye/autopilot-toolkit-codex@workspace:packages/codex"], - "@msgpackr-extract/msgpackr-extract-darwin-x64": ["@msgpackr-extract/msgpackr-extract-darwin-x64@3.0.3", "https://mirrors.huaweicloud.com/repository/npm/@msgpackr-extract/msgpackr-extract-darwin-x64/-/msgpackr-extract-darwin-x64-3.0.3.tgz", { "os": "darwin", "cpu": "x64" }, "sha512-mdzd3AVzYKuUmiWOQ8GNhl64/IoFGol569zNRdkLReh6LRLHOXxU4U8eq0JwaD8iFHdVGqSy4IjFL4reoWCDFw=="], + "@matthewye/autopilot-toolkit-core": ["@matthewye/autopilot-toolkit-core@workspace:packages/core"], - "@msgpackr-extract/msgpackr-extract-linux-arm": ["@msgpackr-extract/msgpackr-extract-linux-arm@3.0.3", "https://mirrors.huaweicloud.com/repository/npm/@msgpackr-extract/msgpackr-extract-linux-arm/-/msgpackr-extract-linux-arm-3.0.3.tgz", { "os": "linux", "cpu": "arm" }, "sha512-fg0uy/dG/nZEXfYilKoRe7yALaNmHoYeIoJuJ7KJ+YyU2bvY8vPv27f7UKhGRpY6euFYqEVhxCFZgAUNQBM3nw=="], + "@matthewye/opencode-toolbox": ["@matthewye/opencode-toolbox@workspace:packages/opencode"], - "@msgpackr-extract/msgpackr-extract-linux-arm64": ["@msgpackr-extract/msgpackr-extract-linux-arm64@3.0.3", "https://mirrors.huaweicloud.com/repository/npm/@msgpackr-extract/msgpackr-extract-linux-arm64/-/msgpackr-extract-linux-arm64-3.0.3.tgz", { "os": "linux", "cpu": "arm64" }, "sha512-YxQL+ax0XqBJDZiKimS2XQaf+2wDGVa1enVRGzEvLLVFeqa5kx2bWbtcSXgsxjQB7nRqqIGFIcLteF/sHeVtQg=="], + "@msgpackr-extract/msgpackr-extract-darwin-arm64": ["@msgpackr-extract/msgpackr-extract-darwin-arm64@3.0.4", "https://mirrors.huaweicloud.com/repository/npm/@msgpackr-extract/msgpackr-extract-darwin-arm64/-/msgpackr-extract-darwin-arm64-3.0.4.tgz", { "os": "darwin", "cpu": "arm64" }, "sha512-LCkGo6JDfaBhgST7UpPWgNgLINpcpabaHfyz5OBx75nUYxBsaEPxjnyNjWpeb/xBup/682QnBfRBy2/LvPutZQ=="], - "@msgpackr-extract/msgpackr-extract-linux-x64": ["@msgpackr-extract/msgpackr-extract-linux-x64@3.0.3", "https://mirrors.huaweicloud.com/repository/npm/@msgpackr-extract/msgpackr-extract-linux-x64/-/msgpackr-extract-linux-x64-3.0.3.tgz", { "os": "linux", "cpu": "x64" }, "sha512-cvwNfbP07pKUfq1uH+S6KJ7dT9K8WOE4ZiAcsrSes+UY55E/0jLYc+vq+DO7jlmqRb5zAggExKm0H7O/CBaesg=="], + "@msgpackr-extract/msgpackr-extract-darwin-x64": ["@msgpackr-extract/msgpackr-extract-darwin-x64@3.0.4", "https://mirrors.huaweicloud.com/repository/npm/@msgpackr-extract/msgpackr-extract-darwin-x64/-/msgpackr-extract-darwin-x64-3.0.4.tgz", { "os": "darwin", "cpu": "x64" }, "sha512-zExlW9zUJKZH/tOtVMttwjKa4Xm/3KcNjnE3dPN92uCktwavMxpgCA3MoJK/DOnTWsQgo224OaST27/mPNAf+w=="], - "@msgpackr-extract/msgpackr-extract-win32-x64": ["@msgpackr-extract/msgpackr-extract-win32-x64@3.0.3", "https://mirrors.huaweicloud.com/repository/npm/@msgpackr-extract/msgpackr-extract-win32-x64/-/msgpackr-extract-win32-x64-3.0.3.tgz", { "os": "win32", "cpu": "x64" }, "sha512-x0fWaQtYp4E6sktbsdAqnehxDgEc/VwM7uLsRCYWaiGu0ykYdZPiS8zCWdnjHwyiumousxfBm4SO31eXqwEZhQ=="], + "@msgpackr-extract/msgpackr-extract-linux-arm": ["@msgpackr-extract/msgpackr-extract-linux-arm@3.0.4", "https://mirrors.huaweicloud.com/repository/npm/@msgpackr-extract/msgpackr-extract-linux-arm/-/msgpackr-extract-linux-arm-3.0.4.tgz", { "os": "linux", "cpu": "arm" }, "sha512-Tg3yX65f5GbtXLkrYEHE5oibZG9epyYWas7FogTTEJeDEF9JlXJzKgXaNhT3UXlTOeA+AfZpYZYZ0uPj7Cfquw=="], - "@opencode-ai/plugin": ["@opencode-ai/plugin@1.15.10", "https://mirrors.huaweicloud.com/repository/npm/@opencode-ai/plugin/-/plugin-1.15.10.tgz", { "dependencies": { "@opencode-ai/sdk": "1.15.10", "effect": "4.0.0-beta.66", "zod": "4.1.8" }, "peerDependencies": { "@opentui/core": ">=0.2.15", "@opentui/keymap": ">=0.2.15", "@opentui/solid": ">=0.2.15" }, "optionalPeers": ["@opentui/core", "@opentui/keymap", "@opentui/solid"] }, "sha512-V2p7CvpBtKWB+FID7Dl1y0Ci02zUT40A9b2RD9R9BOiuD8ZcKhHWov+irN0xVJA0Eg6OhEBfA0lPKRn1FNKPlw=="], + "@msgpackr-extract/msgpackr-extract-linux-arm64": ["@msgpackr-extract/msgpackr-extract-linux-arm64@3.0.4", "https://mirrors.huaweicloud.com/repository/npm/@msgpackr-extract/msgpackr-extract-linux-arm64/-/msgpackr-extract-linux-arm64-3.0.4.tgz", { "os": "linux", "cpu": "arm64" }, "sha512-dgX0P/9wGPJeHFBG+ZmhgE6bmtMt7NP5CRBGyyktpopdk/mW4POnrpQsSLtKI1dwpc+pPLuXHDh6vvskyQE/sw=="], - "@opencode-ai/sdk": ["@opencode-ai/sdk@1.15.10", "https://mirrors.huaweicloud.com/repository/npm/@opencode-ai/sdk/-/sdk-1.15.10.tgz", { "dependencies": { "cross-spawn": "7.0.6" } }, "sha512-CUhpmMGGOqzvPnNNjjWmEIodAfP6Qnuki2ChIUKWYF7UImZ4zUcMZnzO5BtUxu/Ni1P8qzWxDioXs+7aIZQEhA=="], + "@msgpackr-extract/msgpackr-extract-linux-x64": ["@msgpackr-extract/msgpackr-extract-linux-x64@3.0.4", "https://mirrors.huaweicloud.com/repository/npm/@msgpackr-extract/msgpackr-extract-linux-x64/-/msgpackr-extract-linux-x64-3.0.4.tgz", { "os": "linux", "cpu": "x64" }, "sha512-8TNXMEjJc3QEy7R/x1INhgiU+XakDAFUzBhaz7+Rbrs8NH5UQeHQxxmzsSBJGyV6I1jW79undiQm8tOI+D+8FQ=="], - "@standard-schema/spec": ["@standard-schema/spec@1.1.0", "https://mirrors.huaweicloud.com/repository/npm/@standard-schema/spec/-/spec-1.1.0.tgz", {}, "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w=="], + "@msgpackr-extract/msgpackr-extract-win32-x64": ["@msgpackr-extract/msgpackr-extract-win32-x64@3.0.4", "https://mirrors.huaweicloud.com/repository/npm/@msgpackr-extract/msgpackr-extract-win32-x64/-/msgpackr-extract-win32-x64-3.0.4.tgz", { "os": "win32", "cpu": "x64" }, "sha512-CmCXPQrkbwExx3j946/PtHWHbYJiCRBRDl4BlkRQcJB/YOwQxJRTpoo7aTsortjgoJ1x7opzTSxn7C+ASSLVjQ=="], - "@tsconfig/node22": ["@tsconfig/node22@22.0.5", "https://mirrors.huaweicloud.com/repository/npm/@tsconfig/node22/-/node22-22.0.5.tgz", {}, "sha512-hLf2ld+sYN/BtOJjHUWOk568dvjFQkHnLNa6zce25GIH+vxKfvTgm3qpaH6ToF5tu/NN0IH66s+Bb5wElHrLcw=="], + "@opencode-ai/plugin": ["@opencode-ai/plugin@1.17.8", "https://mirrors.huaweicloud.com/repository/npm/@opencode-ai/plugin/-/plugin-1.17.8.tgz", { "dependencies": { "@opencode-ai/sdk": "1.17.8", "effect": "4.0.0-beta.74", "zod": "4.1.8" }, "peerDependencies": { "@opentui/core": ">=0.3.4", "@opentui/keymap": ">=0.3.4", "@opentui/solid": ">=0.3.4" }, "optionalPeers": ["@opentui/core", "@opentui/keymap", "@opentui/solid"] }, "sha512-pkmnYQz5d+xf0h6fAjgplSSJKLqgYKOXr+x6y40GRPdW+/IfndFkMGq7CDsG2SieGD84qv4zYDMyolGo06IMpw=="], - "@types/adm-zip": ["@types/adm-zip@0.5.8", "https://mirrors.huaweicloud.com/repository/npm/@types/adm-zip/-/adm-zip-0.5.8.tgz", { "dependencies": { "@types/node": "*" } }, "sha512-RVVH7QvZYbN+ihqZ4kX/dMiowf6o+Jk1fNwiSdx0NahBJLU787zkULhGhJM8mf/obmLGmgdMM0bXsQTmyfbR7Q=="], + "@opencode-ai/sdk": ["@opencode-ai/sdk@1.17.8", "https://mirrors.huaweicloud.com/repository/npm/@opencode-ai/sdk/-/sdk-1.17.8.tgz", { "dependencies": { "cross-spawn": "7.0.6" } }, "sha512-6MKmsj2ujZyL44jy+12dpwWYDYKPS9fUr+0wVQxaIlPYQ/eAt8T8T3QrybplJ5ZtHfZUX+esXZ02x2UYYm7oEw=="], - "@types/bun": ["@types/bun@1.3.14", "https://mirrors.huaweicloud.com/repository/npm/@types/bun/-/bun-1.3.14.tgz", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="], + "@standard-schema/spec": ["@standard-schema/spec@1.1.0", "https://mirrors.huaweicloud.com/repository/npm/@standard-schema/spec/-/spec-1.1.0.tgz", {}, "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w=="], - "@types/node": ["@types/node@25.9.1", "https://mirrors.huaweicloud.com/repository/npm/@types/node/-/node-25.9.1.tgz", { "dependencies": { "undici-types": ">=7.24.0 <7.24.7" } }, "sha512-xfrlY7UD5rMJk3ZVJP8BNzS28J36YJg+xp+LPXV1TdWxr8uMH5A860QNxYDGQe/ylDSgjxE52Q9VnO7p75tJxg=="], + "@types/bun": ["@types/bun@1.3.14", "https://mirrors.huaweicloud.com/repository/npm/@types/bun/-/bun-1.3.14.tgz", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="], - "adm-zip": ["adm-zip@0.5.17", "https://mirrors.huaweicloud.com/repository/npm/adm-zip/-/adm-zip-0.5.17.tgz", {}, "sha512-+Ut8d9LLqwEvHHJl1+PIHqoyDxFgVN847JTVM3Izi3xHDWPE4UtzzXysMZQs64DMcrJfBeS/uoEP4AD3HQHnQQ=="], + "@types/node": ["@types/node@25.9.3", "https://mirrors.huaweicloud.com/repository/npm/@types/node/-/node-25.9.3.tgz", { "dependencies": { "undici-types": ">=7.24.0 <7.24.7" } }, "sha512-603BddQMv3pUcr4U2dhujk83N2tTDVr/34wII2B6bJy6g+8WD6yUb11jszNs0gdi4PesVWl7ABt8nYMVpnLUcg=="], "argparse": ["argparse@1.0.10", "https://mirrors.huaweicloud.com/repository/npm/argparse/-/argparse-1.0.10.tgz", { "dependencies": { "sprintf-js": "~1.0.2" } }, "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg=="], @@ -74,7 +100,7 @@ "detect-libc": ["detect-libc@2.1.2", "https://mirrors.huaweicloud.com/repository/npm/detect-libc/-/detect-libc-2.1.2.tgz", {}, "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ=="], - "effect": ["effect@4.0.0-beta.66", "https://mirrors.huaweicloud.com/repository/npm/effect/-/effect-4.0.0-beta.66.tgz", { "dependencies": { "@standard-schema/spec": "^1.1.0", "fast-check": "^4.6.0", "find-my-way-ts": "^0.1.6", "ini": "^6.0.0", "kubernetes-types": "^1.30.0", "msgpackr": "^1.11.9", "multipasta": "^0.2.7", "toml": "^4.1.1", "uuid": "^13.0.0", "yaml": "^2.8.3" } }, "sha512-4arEr62cziFa8BBVDUwJCJJmaVepXf/kRg7KtC0h8+bufngscrHbwWFhr9c+HonwOF+31U3iD3xUJmw9KzX7Dw=="], + "effect": ["effect@4.0.0-beta.74", "https://mirrors.huaweicloud.com/repository/npm/effect/-/effect-4.0.0-beta.74.tgz", { "dependencies": { "@standard-schema/spec": "^1.1.0", "fast-check": "^4.8.0", "find-my-way-ts": "^0.1.6", "ini": "^7.0.0", "kubernetes-types": "^1.30.0", "msgpackr": "^2.0.1", "multipasta": "^0.2.7", "toml": "^4.1.1", "uuid": "^14.0.0", "yaml": "^2.9.0" } }, "sha512-Yx+Kh12U+i2FmjwEfKs+ePFmpMd43RPD1oGqc/VraSS9bYzvF0Ff3PojwEFEVEewp8xc92Uxu28gTspU4qyvHA=="], "esprima": ["esprima@4.0.1", "https://mirrors.huaweicloud.com/repository/npm/esprima/-/esprima-4.0.1.tgz", { "bin": { "esparse": "./bin/esparse.js", "esvalidate": "./bin/esvalidate.js" } }, "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A=="], @@ -86,7 +112,7 @@ "gray-matter": ["gray-matter@4.0.3", "https://mirrors.huaweicloud.com/repository/npm/gray-matter/-/gray-matter-4.0.3.tgz", { "dependencies": { "js-yaml": "^3.13.1", "kind-of": "^6.0.2", "section-matter": "^1.0.0", "strip-bom-string": "^1.0.0" } }, "sha512-5v6yZd4JK3eMI3FqqCouswVqwugaA9r4dNZB1wwcmrD02QkV5H0y7XBQW8QwQqEaZY1pM9aqORSORhJRdNK44Q=="], - "ini": ["ini@6.0.0", "https://mirrors.huaweicloud.com/repository/npm/ini/-/ini-6.0.0.tgz", {}, "sha512-IBTdIkzZNOpqm7q3dRqJvMaldXjDHWkEDfrwGEQTs5eaQMWV+djAhR+wahyNNMAa+qpbDUhBMVt4ZKNwpPm7xQ=="], + "ini": ["ini@7.0.0", "https://mirrors.huaweicloud.com/repository/npm/ini/-/ini-7.0.0.tgz", {}, "sha512-ifK0CgjALofS5bkrcTy4RaQ9Vx2Knf/eLeIO+NaswQEpH1UblrtTSCIvN71qQDMq0PeQ/SSPojvEJp9vvvfr+w=="], "is-extendable": ["is-extendable@0.1.1", "https://mirrors.huaweicloud.com/repository/npm/is-extendable/-/is-extendable-0.1.1.tgz", {}, "sha512-5BMULNob1vgFX6EjQw5izWDxrecWK9AM72rugNr0TFldMOi0fj6Jk+zeKIt0xGj4cEfQIJth4w3OKWOJ4f+AFw=="], @@ -98,9 +124,9 @@ "kubernetes-types": ["kubernetes-types@1.30.0", "https://mirrors.huaweicloud.com/repository/npm/kubernetes-types/-/kubernetes-types-1.30.0.tgz", {}, "sha512-Dew1okvhM/SQcIa2rcgujNndZwU8VnSapDgdxlYoB84ZlpAD43U6KLAFqYo17ykSFGHNPrg0qry0bP+GJd9v7Q=="], - "msgpackr": ["msgpackr@1.11.12", "https://mirrors.huaweicloud.com/repository/npm/msgpackr/-/msgpackr-1.11.12.tgz", { "optionalDependencies": { "msgpackr-extract": "^3.0.2" } }, "sha512-RBdJ1Un7yGlXWajrkxcSa93nvQ0w4zBf60c0yYv7YtBelP8H2FA7XsfBbMHtXKXUMUxH7zV3Zuozh+kUQWhHvg=="], + "msgpackr": ["msgpackr@2.0.4", "https://mirrors.huaweicloud.com/repository/npm/msgpackr/-/msgpackr-2.0.4.tgz", { "optionalDependencies": { "msgpackr-extract": "^3.0.4" } }, "sha512-o1C5KRmuRt+apqMr1HuGSqWStZoRBUpEsCsl15uM9VdAF1qHLtvMOU2En747EnTyEl6c4pzPewRMFF31s1CNbA=="], - "msgpackr-extract": ["msgpackr-extract@3.0.3", "https://mirrors.huaweicloud.com/repository/npm/msgpackr-extract/-/msgpackr-extract-3.0.3.tgz", { "dependencies": { "node-gyp-build-optional-packages": "5.2.2" }, "optionalDependencies": { "@msgpackr-extract/msgpackr-extract-darwin-arm64": "3.0.3", "@msgpackr-extract/msgpackr-extract-darwin-x64": "3.0.3", "@msgpackr-extract/msgpackr-extract-linux-arm": "3.0.3", "@msgpackr-extract/msgpackr-extract-linux-arm64": "3.0.3", "@msgpackr-extract/msgpackr-extract-linux-x64": "3.0.3", "@msgpackr-extract/msgpackr-extract-win32-x64": "3.0.3" }, "bin": { "download-msgpackr-prebuilds": "bin/download-prebuilds.js" } }, "sha512-P0efT1C9jIdVRefqjzOQ9Xml57zpOXnIuS+csaB4MdZbTdmGDLo8XhzBG1N7aO11gKDDkJvBLULeFTo46wwreA=="], + "msgpackr-extract": ["msgpackr-extract@3.0.4", "https://mirrors.huaweicloud.com/repository/npm/msgpackr-extract/-/msgpackr-extract-3.0.4.tgz", { "dependencies": { "node-gyp-build-optional-packages": "5.2.2" }, "optionalDependencies": { "@msgpackr-extract/msgpackr-extract-darwin-arm64": "3.0.4", "@msgpackr-extract/msgpackr-extract-darwin-x64": "3.0.4", "@msgpackr-extract/msgpackr-extract-linux-arm": "3.0.4", "@msgpackr-extract/msgpackr-extract-linux-arm64": "3.0.4", "@msgpackr-extract/msgpackr-extract-linux-x64": "3.0.4", "@msgpackr-extract/msgpackr-extract-win32-x64": "3.0.4" }, "bin": { "download-msgpackr-prebuilds": "bin/download-prebuilds.js" } }, "sha512-4kmO/MdyUIkLIvTPr8VHLil4AtoKIoniWPIEk5+CDy0xnWC84azhSFmuJ7PxZdsYtiP5kEeQsORAVIeMgxT+Hw=="], "multipasta": ["multipasta@0.2.7", "https://mirrors.huaweicloud.com/repository/npm/multipasta/-/multipasta-0.2.7.tgz", {}, "sha512-KPA58d68KgGil15oDqXjkUBEBYc00XvbPj5/X+dyzeo/lWm9Nc25pQRlf1D+gv4OpK7NM0J1odrbu9JNNGvynA=="], @@ -126,12 +152,14 @@ "undici-types": ["undici-types@7.24.6", "https://mirrors.huaweicloud.com/repository/npm/undici-types/-/undici-types-7.24.6.tgz", {}, "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg=="], - "uuid": ["uuid@13.0.2", "https://mirrors.huaweicloud.com/repository/npm/uuid/-/uuid-13.0.2.tgz", { "bin": { "uuid": "dist-node/bin/uuid" } }, "sha512-vzi9uRZ926x4XV73S/4qQaTwPXM2JBj6/6lI/byHH1jOpCzb0zDbfytgA9LcN/hzb2l7WQSQnxITOVx5un/wGw=="], + "uuid": ["uuid@14.0.0", "https://mirrors.huaweicloud.com/repository/npm/uuid/-/uuid-14.0.0.tgz", { "bin": { "uuid": "dist-node/bin/uuid" } }, "sha512-Qo+uWgilfSmAhXCMav1uYFynlQO7fMFiMVZsQqZRMIXp0O7rR7qjkj+cPvBHLgBqi960QCoo/PH2/6ZtVqKvrg=="], "which": ["which@2.0.2", "https://mirrors.huaweicloud.com/repository/npm/which/-/which-2.0.2.tgz", { "dependencies": { "isexe": "^2.0.0" }, "bin": { "node-which": "./bin/node-which" } }, "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA=="], "yaml": ["yaml@2.9.0", "https://mirrors.huaweicloud.com/repository/npm/yaml/-/yaml-2.9.0.tgz", { "bin": { "yaml": "bin.mjs" } }, "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA=="], "zod": ["zod@4.1.8", "https://mirrors.huaweicloud.com/repository/npm/zod/-/zod-4.1.8.tgz", {}, "sha512-5R1P+WwQqmmMIEACyzSvo4JXHY5WiAFHRMg+zBZKgKS+Q1viRa0C1hmUKtHltoIFKtIdki3pRxkmpP74jnNYHQ=="], + + "bun-types/@types/node": ["@types/node@25.9.1", "https://mirrors.huaweicloud.com/repository/npm/@types/node/-/node-25.9.1.tgz", { "dependencies": { "undici-types": ">=7.24.0 <7.24.7" } }, "sha512-xfrlY7UD5rMJk3ZVJP8BNzS28J36YJg+xp+LPXV1TdWxr8uMH5A860QNxYDGQe/ylDSgjxE52Q9VnO7p75tJxg=="], } } diff --git a/commands/audit-autopilot.md b/commands/audit-autopilot.md deleted file mode 100644 index e1cccf7..0000000 --- a/commands/audit-autopilot.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -description: Post-hoc audit of autopilot execution fidelity. Analyzes session traces from an /autopilot run to evaluate how faithfully the workflow executed against its contract, surfacing errors, friction, and drift with traceable evidence anchors. -arguments: [{ name: "sessionId", description: "The orchestrator session ID from the autopilot run", required: true }] ---- - -Load the `audit-autopilot` skill and execute this request: - -Audit the autopilot execution with orchestrator session {{sessionId}}. diff --git a/commands/autopilot.md b/commands/autopilot.md deleted file mode 100644 index 9df5e88..0000000 --- a/commands/autopilot.md +++ /dev/null @@ -1,549 +0,0 @@ ---- -description: Put issue resolution on autopilot — scans local .scratch/ files AND GitHub Issues for ready-for-agent issues, dispatches implementer → reviewer in a retry loop until resolved. After all issues complete, runs global meta-review against ADR/PRD and fixes cross-module issues. Use when processing autopilot issues from any source. -arguments: [{ name: "target", description: "Optional: a .scratch//issues/ directory path, or a GitHub issue number (#N or N). If omitted, scan all sources.", required: false }] ---- - -Execute the autopilot orchestrator workflow below. **Orchestrator MUST include explicit `skill` tool loading instructions in implementer and reviewer dispatch prompts** — see "执行 implementer" and reviewer dispatch sections for the exact preamble format. - -## Issue 来源识别 - -autopilot 支持两种 issue 来源。根据 `target` 参数或扫描结果判断： - -| target 特征 | 来源 | 状态机 | 合约文件 | -|---|---|---|---| -| 包含 `/` 的路径 | 本地 `.scratch/` | frontmatter `Status:` | `AGENT-BRIEF.md` | -| `#N` 或纯数字 `N` | GitHub Issue | labels | issue body（含 AC） | -| 无参数扫描到本地 | 本地 `.scratch/` | frontmatter `Status:` | `AGENT-BRIEF.md` | -| 无参数扫描到 GitHub | GitHub Issue | labels | issue body | - -## 前置约定 - -### 本地 issue 模式 - -- `target` 使用绝对路径。如传入相对路径，拼接当前工作目录。 -- `issue.md` 以 YAML frontmatter 开头，`Status` 字段在 frontmatter 中。 -- 更新 Status：用 `edit` 工具修改 frontmatter 中的 `Status:` 行。 -- 追加注释：在 `## Comments` 节末尾加 `- <时间戳> autopilot: <内容>`。无该节则在文件末尾创建。 -- 合约文件：同目录下 `AGENT-BRIEF.md`。 - -### GitHub Issue 模式 - -- 使用 `gh` CLI 操作 issue。从 `git remote -v` 自动推断 repo。 -- 状态通过 labels 表达：`in-progress`、`resolved`、`needs-info`。 -- 追加注释用 `gh issue comment --body "..."`。 -- 合约来自 issue body（其中包含 Acceptance Criteria 和 What to build，由 `to-issues` 创建）。 -- 读取 issue：`gh issue view --json number,title,body,labels,state`。 - -### 共用概念 - -- `Status: ready-for-agent`（本地 frontmatter）↔ label `ready-for-agent`（GitHub） -- `Status: in-progress` ↔ label `in-progress` -- `Status: resolved` ↔ label `resolved` -- `Status: needs-info` ↔ label `needs-info` - ---- - -## 如果指定了 target - -### target 是路径（含 `/`） - -1. 确认 `/issue.md` 存在，不存在则报告错误并停止 -2. 确认 `/AGENT-BRIEF.md` 存在，不存在则报告错误并停止 -3. 读取 `/issue.md`，检查 `Status:` 是否为 `ready-for-agent` 或 `in-progress` -4. 非以上状态 → 回复当前状态并停止 -5. 更新 Status 为 `in-progress` -6. 设置 `source = "local"`, `id = ` -7. 从 `` 推断 feature 目录（取 issue 目录的父级父级，如 `.scratch/auth/issues/01-login/` → `.scratch/auth/`） -8. 设置 `contract = /AGENT-BRIEF.md` 的内容作为合约文本 -9. 跳到"交叉 Issue Suggestion 匹配" - -### target 是 GitHub issue 号（`#N` 或纯数字 `N`） - -提取数字部分为 `issueNumber`： - -1. `gh issue view --json number,title,body,labels,state` 获取 issue 信息 -2. 检查 labels 是否含 `ready-for-agent` 或 `in-progress` -3. 非以上标签 → 回复当前状态并停止 -4. 将 `ready-for-agent` 标签替换为 `in-progress`：`gh issue edit --add-label "in-progress" --remove-label "ready-for-agent"` -5. 追加评论：`gh issue comment --body "autopilot: 开始处理"` -6. 从 issue body 提取 Acceptance Criteria 和 What to build 作为合约文本 -7. 设置 `source = "github"`, `id = `, `contract = <解析出的合约文本>` -8. 从 issue title 生成 feature slug（如 `Implement Suggestion matching` → `suggestion-matching` → `.scratch/suggestion-matching/`） -9. 跳到"交叉 Issue Suggestion 匹配" - ---- - -## 否则（无参数）：扫描模式 - -同时扫描两个来源： - -### 本地扫描 - -1. Glob 扫描 `.scratch/*/issues/*.md` -2. 对每个文件，读取前 30 行，检查是否有 `Status: ready-for-agent` -3. 收集所有匹配项 - -### GitHub 扫描 - -4. `gh issue list --label "ready-for-agent" --state open --json number,title --limit 50` -5. 收集所有匹配项 - -### 选择并报告 - -6. 合并两个来源的结果。向用户列出所有找到的 issue -7. 选择第一个（按先本地后 GitHub，各自内部按自然序），标注正在处理哪个 -8. 如果零个 → 跳到"Phase 2: 全局 meta-review" -9. 根据选中 issue 的来源，走对应的初始化流程 - ---- - -## Phase 1: 调度循环 - -维护 `retry_count = 0`，最多 3 轮（`retry_count` = 0, 1, 2）： -- retry_count = 0: 首次实现 -- retry_count = 1: 第 1 次 retry -- retry_count = 2: 第 2 次 retry -- retry_count >= 3: 转为 needs-info - -### 更新状态（抽象） - -- **local**: `edit` 工具修改 `issue.md` 的 `Status:` 行 -- **github**: `gh issue edit --add-label "<新>" --remove-label "<旧>"` - -### 追加注释（抽象） - -- **local**: 在 `issue.md` 的 `## Comments` 节末尾添加条目 -- **github**: `gh issue comment --body "<时间戳> autopilot: <内容>"` - -### 交叉 Issue Suggestion 匹配 - -dispatch implementer 前，扫描 `suggestions.json`，匹配 pending suggestions 到当前 issue 的 AGENT-BRIEF： - -#### 推断 feature 目录 - -- **本地模式**：从 issue 路径提取（如 `.scratch/auth/issues/01-login/` → `.scratch/auth/`） -- **GitHub 模式**：从 issue title 生成 feature slug → `.scratch//` -- 若无从推断 → 跳过匹配，不传 CROSS_ISSUE_SUGGESTIONS - -#### 读取和匹配 - -1. 检查 `.scratch//suggestions.json` 是否存在： - - 不存在 → 跳过匹配，不传 CROSS_ISSUE_SUGGESTIONS - - 存在 → 读取，筛选 `status: "pending"` 的条目 -2. 对每条 pending suggestion，执行双重匹配（**任一命中即视为匹配**）： - - **文件路径匹配**：suggestion 的 `files` 数组中任一路径字符串作为子串出现在 AGENT-BRIEF 全文（issue body、AC 文本、文件引用）→ 命中 - - **关键词匹配**：suggestion 的 `keywords` 数组中任一关键词作为子串出现在 AGENT-BRIEF 全文中（**大小写不敏感**）→ 命中 -3. 未命中的 suggestions 保持 `pending` 状态，不传递 -4. 命中的 suggestions 组装为 `CROSS_ISSUE_SUGGESTIONS` JSON 数组。每条附带完整 reviewer 上下文： - ```json - { - "source_issue": "#N 或 ", - "round": , - "content": "", - "files": ["path/to/file1.ts", ...], - "keywords": ["keyword1", ...], - "reviewer_context": "<原 REVIEWER_REPORT 摘录：该 Suggestion 所属 REVIEWER_REPORT 中 Suggestion 条目全文（含 KEYWORKS/FILES 标注）>" - } - ``` - **`reviewer_context` 重建**：`suggestions.json` 中存储的是结构化字段（`content`、`files`、`keywords`），不含标注行。组装 `CROSS_ISSUE_SUGGESTIONS` 时，orchestrator 需从独立字段重建 `reviewer_context`（即带 KEYWORDS/FILES 标注行的完整 reviewer report 摘录），格式如： - ``` - - [ ] - KEYWORDS: - FILES: - ``` -5. 无匹配到任何 suggestion → 不传 CROSS_ISSUE_SUGGESTIONS - -### 执行 implementer - -#### 前置：Pre-flight 工具链检测 - -dispatch implementer 前，检测项目的工具链是否可用： - -1. 根据项目类型推断测试命令（Rust → `cargo test`，Node → `npm test`，Python → `pytest` 或 `uv run pytest`） -2. 运行 `which ` 检测工具链是否存在（如 `which cargo`、`which npm`） -3. 不可用时尝试常见安装路径（`~/.cargo/bin/cargo`、`~/.rustup/toolchains/*/bin/cargo`） -4. 设置 `TOOLCHAIN: available` 或 `TOOLCHAIN: unavailable`，传入 implementer 的 dispatch prompt - -#### 前置：REFACTORING 模式检测 - -分析合约内容，检测当前 issue 是否为纯重构任务（非新功能开发）： - -1. 扫描合约关键词：`replace`、`consolidate`、`extract`、`delete`、`Remove`、`Replace`、`inline`、`shared function`、`duplicated` → 命中 2+ 且不含 `Add`、`new feature`、`Implement`（作为新增功能时）→ 标记 `REFACTORING: true` -2. 对照 AC：如果所有 AC 描述的是"替换"或"删除"而非"新增功能" → `REFACTORING: true` -3. 设置 `REFACTORING: true|false`，传入 implementer 的 dispatch prompt - -用 `task` 工具 dispatch `implementer` agent（subagent_type: `implementer`）。**prompt 必须以 skill 加载指令开头（强制，不可省略）**： - -``` -**在开始任何操作之前，必须使用 `skill` 工具加载以下技能：** -1. `skill(name: "tdd")` — TDD 方法论（红绿重构循环、测试质量标准、mock 纪律） -2. `skill(name: "diagnose")` — 系统性诊断流程（遇到意外错误时使用） -3. `skill(name: "zoom-out")` — 不熟悉代码区域时上探抽象层次 - -**这是强制步骤，不可跳过。** 未加载技能前不得执行任何其他操作。 - ---- - -<以下为任务描述> - -<根据 retry_count 和模式动态生成> -``` - -任务描述部分传递： -- **共同的**：`source`, `id`, `contract`（合约内容）, `TOOLCHAIN: `, `REFACTORING: `，以及： - - 首次（retry_count = 0）：`ROUND: 0` - - retry（retry_count >= 1）：`ROUND: ` + `PREV_REVIEW: <上一轮 REVIEWER_REPORT 全文>` - - 如有匹配到的 CROSS_ISSUE_SUGGESTIONS，一并传入 -- **本地模式**：额外传 issue 目录绝对路径 -- **GitHub 模式**：额外传 issue body（含 AC）+ `IS_GITHUB: true` - -等待 implementer 回复，解析 `IMPLEMENTER_REPORT:`。 - -**空回复处理：** 如果 implementer 返回空结果（无 `IMPLEMENTER_REPORT:` 标记头），自动重试 1 次（重新 dispatch 相同 prompt）。两次都空 → 更新 Status 为 `needs-info` 并停止。 - -**解析容错：** 回复中找不到 `IMPLEMENTER_REPORT:` 标记头 → 视为不可解析，更新 Status 为 `needs-info` 附原始回复，停止。 - -### 首次实现：检查 SELF_REVIEW - -retry_count = 0 时，检查报告中有无 `SELF_REVIEW:` 段： - -- STATUS: DONE → "无问题" 或 "发现问题 → 已修复" → 通过 -- STATUS: UNVERIFIED → 必须包含每条 AC 的验证方式标注（测试运行 / 代码结构分析）。**标注缺失但 STATUS: UNVERIFIED → 通过**（UNVERIFIED 本身已声明验证不全） -- STATUS: DONE 或 UNVERIFIED 但缺失 SELF_REVIEW 段 → 标记为 `needs-info`，停止 - -Retry 轮次（retry_count >= 1）不检查 SELF_REVIEW。 - -### 收集 SIBLING_CONTEXT - -dispatch reviewer 前，自动收集当前 issue 所属 PRD 下所有已 resolved 的兄弟模块信息： - -1. 从当前 issue body 的 `Parent` 链接提取 PRD issue 号 -2. `gh issue list --label "resolved" --json number,title` 获取所有已 resolve 的 issue -3. 对于每个已 resolve 的 issue（排除当前 issue 自己），提取其 title 和关键约定（入口模式、测试框架、文件布局） -4. 组装为 `SIBLING_CONTEXT` 字符串，包含："已完成的兄弟模块: #N title — 关键约定: ..." - -### 处理 implementer 结果 - -- **STATUS: DONE** → dispatch `reviewer` agent（subagent_type: `reviewer`）。**prompt 必须以 skill 加载指令开头（强制，不可省略）**： - -``` -**在开始任何操作之前，必须使用 `skill` 工具加载以下技能：** -1. `skill(name: "tdd")` — 测试质量标准和 mock 纪律（用于 TDD 审查维度） - -**这是强制步骤，不可跳过。** 未加载技能前不得执行任何其他操作。 - ---- - -<以下为任务描述> -``` - -任务描述部分传递 `source`, `id`, `contract`, `CHANGED_FILES`, `SIBLING_CONTEXT` + 上一轮 `REVIEWER_REPORT`（如有） - - **GitHub 模式**：额外传 `IS_GITHUB: true` - -- **STATUS: UNVERIFIED** → dispatch `reviewer` agent（同上 prompt 格式）。任务描述中额外传递 `UNVERIFIED: true` + implementer 的完整 `SELF_REVIEW` 段（含逐 AC 验证方式标注）。reviewer 的审查侧重： - - 结构正确性（代码逻辑是否符合 AC） - - 是否所有 AC 都有对应的代码实现 - - VERDICT 可选 `VERIFY_NEEDED`（结构通过但需工具链验证）或 `RETRY`（结构本身有问题） - -- **STATUS: BLOCKED 或 NEEDS_CONTEXT** → 更新 Status 为 `needs-info`，追加注释说明原因，**停止** - -#### 解析 SUGGESTION_RESOLUTIONS - -STATUS: DONE 时，从 `IMPLEMENTER_REPORT` 中解析 `SUGGESTION_RESOLUTIONS:` 段，暂存待 reviewer 确认后执行： - -1. 如段内容为 "无" 或不存在 → 无需要处理的跨 issue suggestion，跳过 -2. 逐条解析，每行格式：`[resolved|rejected|deferred] 来源 round : → <处理说明>` -3. 提取字段： - - `type`：`resolved` / `rejected` / `deferred` - - `source_issue`：来源 issue 标识（如 `#18`、`01-login`） - - `round`：reviewer 轮次 - - `summary`：`→` 前的 content 摘要 - - `detail`：`→` 后的处理说明（对 rejected 即拒绝理由） -4. 暂存为 `pending_resolutions` 列表，在 reviewer 返回 MERGE 后统一执行状态更新 - -### 处理 reviewer 结果 - -解析 `REVIEWER_REPORT:`，看 VERDICT。reviewer 任务失败或找不到 `VERDICT:` → 视为 BLOCKED，更新 Status 为 `needs-info` 并停止。 - -**解析容错：** 找不到 `REVIEWER_REPORT:` 标记头 → 视为不可解析，更新 Status 为 `needs-info` 附原始回复，停止。 - -#### 提取 Suggestion 并持久化 - -解析完 REVIEWER_REPORT 后，无论 VERDICT 如何，提取 `## Suggestion` 节的所有条目并写入 `suggestions.json`： - -1. **解析条目**：逐条解析 `## Suggestion` 下的每个 `- [ ]` 项： - - `content`：`- [ ] ` 后的正文文本（不含 KEYWORDS/FILES 标注行） - - `keywords`：`KEYWORDS:` 行（逗号分隔，可选）→ 解析为数组 - - `files`：`FILES:` 行（逗号分隔，可选）→ 解析为数组 -2. **兜底提取**（仅当对应标注缺失时）： - - **关键词兜底**：从 `content` 文本中提取 2-5 个最有代表性的术语（优先提取技术术语、模块名、模式名） - - **文件路径兜底**：从当前 issue 的 implementer 报告 `CHANGED_FILES` 中提取，去重 -3. **推断 feature 目录**： - - 本地模式（`source = "local"`）：从 issue 路径提取，如 `.scratch/auth/issues/01-login/` → `.scratch/auth/` - - GitHub 模式（`source = "github"`）：从 issue title 生成 feature slug，创建 `.scratch//` -4. **读取现有文件**：检查 `.scratch//suggestions.json` 是否存在，存在则读取，不存在则初始化为空数组 `[]` -5. **去重**：按 `content` 字段比较，已存在相同 `content` 的条目不重复写入 -6. **追加新条目**：每个新条目格式为： - ```json - { "issue": "", "round": , "content": "...", "files": [...], "keywords": [...], "status": "pending" } - ``` - - `issue`：本地模式用目录名（如 `01-login`），GitHub 模式用 `#` - - `round`：当前 `retry_count` -7. **写入文件**：将更新后的数组写回 `.scratch//suggestions.json`（`write` 工具） -8. **GitHub Issue 评论同步**（仅 `source = "github"` 时执行）： - - 对每条**新增**的 suggestion（去重跳过的不写），追加 issue comment： - ``` - gh issue comment --body "autopilot suggestion [pending]: " - ``` - - 格式：`autopilot suggestion []: <正文>` -9. **报告**：向用户报告提取结果 — "从 reviewer 提取了 N 条 Suggestion（M 条新增，K 条去重跳过）"；如有 GitHub comment 同步，注明已写入 N 条 comment - -**注意**：仅提取 `## Suggestion` 级别条目。Critical 和 Important 必须在当前 issue 内解决，不传播。 - ---- - -VERDICT 分支： - -- **MERGE** → 更新 Status 为 `resolved`，追加 reviewer 结论。进入"Update Suggestion 状态"步骤，完成后**返回扫描模式处理下一个 issue** -- **VERIFY_NEEDED** → 审查通过（结构正确）但 implementer 工具链不可用，无法实际验证。处理流程： - 1. 尝试运行项目的测试命令（如 `cargo test`、`npm test`、`pytest`）。如工具链在 orchestrator 环境可用 → 运行验证 - 2. 验证通过 → 更新 Status 为 `resolved`，追加 "Orchestrator verified: all tests pass" - 3. 验证失败或工具链仍不可用 → 更新 Status 为 `needs-info`，追加 reviewer 结论 + "Toolchain unavailable — requires manual verification" - 4. 所有情况下保留 reviewer 报告和 Suggestion 提取 -- **RETRY** → `retry_count += 1`，清空 `pending_resolutions = []`（上一轮 resolutions 在 retry 后失效，新轮次 implementer 需重新声明） - - `retry_count < 3`：返回"执行 implementer"（传递 PREV_REVIEW） - - `retry_count >= 3`：更新 Status 为 `needs-info`，追加 reviewer 问题清单 + 说明已达最大重试次数，**返回扫描模式处理下一个 issue** -- **BLOCKED** → 更新 Status 为 `needs-info`，追加 reviewer 结论，**返回扫描模式处理下一个 issue** - -#### Update Suggestion 状态 - -VERDICT: MERGE 时，根据 `pending_resolutions` 更新 `suggestions.json` 中对应条目的状态： - -1. **定位条目**：在 `suggestions.json` 中按 `issue`（匹配 `source_issue`）、`round` 和 `content` 三级匹配对应 suggestion 条目： - - 一级：`issue` 字段匹配 `source_issue`（字符串全等） - - 二级：`round` 字段匹配 `round`（数字全等） - - 三级：`summary`（`→` 前的 content 摘要）作为子串出现在条目的 `content` 字段中（子串匹配，大小写敏感） - - 无匹配条目（implementer 声明了但 suggestions.json 中找不到）→ 跳过该条 - - **多命中歧义消解**（三级命中 2+ 条）：执行四级匹配打破平局—— - 1. 计算每条候选 entry 的 `files` 与当前 issue 的 implementer `CHANGED_FILES` 的交集，取交集最多者 - 2. 仍平局：取 `summary` 在 `content` 中匹配长度最长者（最精确匹配） - 3. 仍平局（极少见，如相同 content、相同 files）：跳过该条并报告歧义 — "Suggestion resolution ambiguous: `summary` 命中 N 条内容相近的 entry（source_issue + round），无法自动消歧，请人工处理" -2. **状态校验**：定位到条目后，检查其 `status`： - - `status === "pending"` → 继续步骤 3（正常处理） - - `status !== "pending"`（如 `resolved`/`rejected`）→ **跳过该条**并报告异常 — "Skipping suggestion resolution: matched entry already has status `` (expected pending). Possible multi-hit mis-match or duplicate resolution." -3. 根据 `type` 执行状态转换： - - | type | 操作 | 字段更新 | - |------|------|---------| - | `resolved` | 标记为已解决 | `status: "resolved"`, `resolved_in_issue`: 当前 issue 的 slug（本地模式用目录名，GitHub 模式用 `#`） | - | `rejected` | 标记为已拒绝 | `status: "rejected"`, `rejected_reason`: `detail` 字段内容（即 `→` 后的处理说明） | - | `deferred` | 保持 pending + 备注 | `status` 仍为 `"pending"`, `deferred_by`: 当前 issue slug | - -4. **写回文件**：将更新后的数组写回 `.scratch//suggestions.json` -5. **GitHub Issue 评论同步**（仅 `source = "github"` 时执行）： - - 对 `resolved` 和 `rejected` 类型，追加 issue comment： - ``` - gh issue comment --body "autopilot suggestion [resolved|rejected]: " - ``` - - `deferred` 不需要额外 issue comment（状态未变，且 initial pending comment 已存在） - - 注：如 processed issue 与 source issue 是同一个 GitHub issue，在同一 issue 下追加 comment - -6. **报告**：汇总更新结果 — "处理了 N 条 suggestion（M resolved, K rejected, J deferred）"；如有 GitHub comment 同步，注明已写入 N 条 - -### Phase 1 退出条件 - -当扫描模式返回零个 ready-for-agent issue 时，Phase 1 完成。进入 Phase 2。 - ---- - -## Phase 2: 全局 Meta-Review - -当所有 issue 处理完毕（无 ready-for-agent 剩余），执行全局审查。 - -### 目的 - -对照 ADR、PRD 和所有 issue 合约，审视整个 codebase 的： -- 实现正确性（所有模块是否符合各自的 AC 和 PRD 全局约束） -- 跨模块一致性（是否有模式漂移、重复实现、约定不一致） -- 计划外变更（是否有孤儿文件、未声明依赖、残留引用） - -### 执行方式 - -Orchestrator 自主审查与 reviewer 子 agent **并行**执行。两者均产出独立报告后，进入「报告合并」统一处理。 - -#### 1. 派遣 reviewer 子 agent（并行） - -用 `task` 工具 dispatch `reviewer` agent（`subagent_type: "reviewer"`，只读，无 edit/bash 权限）。**prompt 必须以 skill 加载指令开头（强制，不可省略）**： - -``` -**在开始任何操作之前，必须使用 `skill` 工具加载以下技能：** -1. `skill(name: "tdd")` — 测试质量标准和 mock 纪律 - -**这是强制步骤，不可跳过。** 未加载技能前不得执行任何文件读取或审查操作。 - ---- - -你正在执行全局 meta-review。审查范围为整个 codebase，对照以下基准： - -**审查基准（读取以下全文）：** -- 所有 ADR（docs/adr/） -- 所有 PRD（如有） -- 所有已 resolved issue 的合约（AGENT-BRIEF.md 或 GitHub issue body 中的 AC） - -**审查维度（适配 reviewer 四维框架到全局 meta-review 上下文）：** - -1. **ADR/PRD 全局约束验证**（维度四：计划忠实度）： - - 逐条检查 ADR 和 PRD 中声明的全局约束（输出格式要求、依赖白名单、运行时约束、目录结构约定等）是否在所有模块中满足 - - 是否存在约束降级（如 PRD 要求 byte-identical 但实现仅做到结构等价） - - 依赖白名单是否被超出 - -2. **跨模块一致性**（维度三代码质量 + 维度四工程约定）： - - 入口检测方式、import 风格（静态/动态）、错误处理模式、日志格式、算法选择、文件布局是否一致 - - 是否存在模式漂移（不同模块用不同方式解决同一问题） - - 是否有重复实现 - -3. **计划外变更检测**（维度四：孤儿文件、未声明行为）： - - 是否存在孤儿文件：不在任何合约中声明的新文件 - - 合约要求删除但尚未删除的文件 - - 合约未声明的新行为（悄悄加的 UX 优化、额外校验、额外日志） - - 未在合约中声明的副作用（自动创建目录、修改全局配置、静默改写其他模块文件） - -4. **AC 覆盖率**（维度一：行为对齐的全局化）： - - 对照所有 resolved issue 合约，逐条检查 AC 是否有对应实现 - -输出格式与标准 reviewer 一致：以 `REVIEWER_REPORT:` 开头，分 Critical / Important / Suggestion 三级 + VERDICT（MERGE / RETRY / BLOCKED）。 -``` - -#### 2. Orchestrator 自主审查（并行） - -Orchestrator 自身用 grep/glob 工具执行审查，覆盖与 reviewer 子 agent 相同的范围： - -1. 读取 PRD 全文和所有相关 ADR（包含 ADR 0003、ADR 0004 等），列出每条全局约束 -2. 逐条检查：用 grep/glob 扫描 codebase，验证约束满足 -3. 对照 issue 合约，检查每个 resolved issue 的 AC 覆盖率 -4. 检查跨模块一致性（入口检测方式、import 风格、错误处理、日志格式、算法选择、文件布局） -5. 检查计划外变更（孤儿文件、未声明新行为、副作用、未删除文件） -6. 输出结构化报告：Critical / Important / Suggestion + VERDICT - -#### 3. 等待两份报告 - -上述 1、2 两步并行执行。两者均完成后（均产出独立报告），进入下方「报告合并」流程。 - -### 报告合并 - -`执行方式` 产生两份独立的 meta-review 报告： -- **orchestrator 自主审查报告** — 对照 ADR、PRD 和 issue 合约逐条检查 -- **reviewer 子 agent 并行审查报告** — 4 轴审查（Behavior alignment、TDD discipline、Code quality、Plan fidelity） - -进入修复循环前，将两份报告合并为一份 `MERGED_META_REPORT`： - -1. **Union 策略**：两份报告中 Critical 和 Important 级别的问题取其并集——任一份报告标记的问题均纳入修复范围。Suggestion 级别条目同样取并集（去重后）。 - -2. **冲突裁决**：当两份报告对同一文件/路径有不同结论时（如一方标记为问题，另一方认为正常），orchestrator 手动核实并裁定： - - **默认采纳更严格结论**：无法确认是否为误报时，默认采纳更严格的发现（标记为问题）。 - - **确认误报后降级**：仅当 orchestrator 明确确认某发现为误报（false positive）时，方可将该条目从修复范围移除或降级为 Suggestion。 - - 裁决过程记录到合并报告中，注明"冲突裁决：\<路径\> — 采纳 \<来源\> 的结论" - -3. **去重**：完全相同的发现（同一文件 + 同一问题模式）在两份报告中均出现时，合并为单一条目，标注"双来源一致：<发现描述>"。 - -合并后产出 `MERGED_META_REPORT`，包含： -- Critical 条目（合并去重后） -- Important 条目（合并去重后） -- Suggestion 条目（合并去重后） -- 冲突裁决记录 - -### 修复循环 - -从合并报告（`MERGED_META_REPORT`）中取 Critical + Important 条目，由 **orchestrator 直接修复**（不 dispatch implementer），因为 meta 问题通常是机械性的： - -- **统一模式**：isMain 不一致 → 直接 edit 文件统一为一种模式 -- **删除残留**：孤儿文件 / __pycache__ / 残留引用 → 直接 delete/edit -- **更新文档**：SKILL.md / schemas.md / ADR 引用 → 直接 edit - -遇到需要判断的设计级问题（如"两种算法选哪个"），追加 comment 标记为 needs-info。 - -### 修复后验证 - -修复完成后： -1. 运行 `bun test` 确认测试全绿 -2. 重新执行 meta-review，确认 0 Critical + 0 Important -3. 最多 **2 轮**修复循环。2 轮后仍有问题 → 报告残余问题，标记 needs-info - -### 完成后 - -向用户报告 Phase 1 和 Phase 2 的完整结果：处理了多少 issue、总轮次、最终状态、meta-review 发现和修复了哪些问题。 - -### FINAL_ACCEPTANCE_REPORT - -meta-review 完成后，产出跨 issue Suggestion 验收报告，供人类签收。 - -#### 1. 聚合 Suggestions - -扫描所有 feature 目录的 `suggestions.json`，汇总所有条目： - -- 用 `glob` 扫描 `.scratch/*/suggestions.json`，读取每个文件 -- 将每个条目合并到统一列表中，保留来源 feature 信息 - -**GitHub Issue 模式附加聚合**： - -当 Phase 1 处理过 GitHub issue 时，从 issue comments 中提取 suggestions，与本地 `suggestions.json` 合并： - -1. 对每个处理过的 GitHub issue，用 `gh issue view --json comments` 读取所有 comments -2. 筛选格式为 `autopilot suggestion []: <正文>` 的 comments -3. 对每条提取：`status`（从 `[]` 块）、`content`（`:` 后的正文）、`source_issue`（`#`） -4. 与本地 `suggestions.json` 条目按 `content` 去重合并（本地优先：本地已有相同 content 的条目保留本地版本及完整字段） - -#### 2. 分组统计 - -按 `status` 字段分组： - -| 分组 | 内容 | 来源 | -|------|------|------| -| **Pending** | `status: "pending"` 的所有条目 | 列出 `content`、`source_issue`、`keywords`；如有 `deferred_by`，注明 | -| **Rejected** | `status: "rejected"` 的所有条目 | 列出 `content`、`source_issue`、`rejected_reason` | -| **Resolved** | `status: "resolved"` 的所有条目 | 列出 `content`、`resolved_in_issue`、原 `source_issue` | - -#### 3. 输出 FINAL_ACCEPTANCE_REPORT - -以 `FINAL_ACCEPTANCE_REPORT:` 为标记头输出结构化报告： - -``` -FINAL_ACCEPTANCE_REPORT: - -## Pending（需处理） -- - - 来源: - - 关键词: - - [deferred by: ] -...（如无 pending，写 "无"） - -## Rejected（已拒绝） -- - - 来源: - - 理由: -...（如无 rejected，写 "无"） - -## Resolved（已解决） -- - - 来源: - - 由 处理 -...（如无 resolved，写 "无"） -``` - -#### 4. 边界处理 - -- `suggestions.json` 不存在（glob 无结果）→ 报告 "No suggestions.json found. Skipping acceptance report."（**不影响 meta-review 流程**） -- 存在但无 pending → 报告 "All suggestions resolved. Ready for sign-off." -- 有 pending → 报告 "The following suggestions require human attention:" + 逐条列出 + 建议人工判断处理方向（落实为后续 issue 或标记 rejected） -- 仅 GitHub issue comments 中有 suggestions 而本地无 `suggestions.json` → 以 comments 聚合结果为准，仍输出完整报告 - -#### 5. Self-Verification - -FINAL_ACCEPTANCE_REPORT 输出后，orchestrator 执行以下快速自检： - -- [ ] `suggestions.json` 中的每条 `status: "resolved"` 条目均有 `resolved_in_issue` 字段 -- [ ] `suggestions.json` 中的每条 `status: "rejected"` 条目均有 `rejected_reason` 字段 -- [ ] 无 `status: "pending"` 条目被意外标记为 `resolved_in_issue`（仅 resolved 应有此字段） -- [ ] FINAL_ACCEPTANCE_REPORT 的 Pending / Rejected / Resolved 三组条目数之和 = `suggestions.json` 总条目数（去重后） -- [ ] 无空 `content` 字段的条目 -- [ ] 发现异常 → 记录到报告末尾的 `## Self-Verification Issues` 节，人工跟进 diff --git a/commands/git-guardrails.md b/commands/git-guardrails.md deleted file mode 100644 index 1584b21..0000000 --- a/commands/git-guardrails.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -description: Set up git guardrails in OpenCode — adds permission rules to block dangerous git commands (push, reset --hard, clean, branch -D, checkout/restore .) before they execute. Use to prevent destructive git operations. -arguments: [{ name: "scope", description: "Install scope: 'global' (all projects) or 'project' (this project only). If omitted, ask the user.", required: false }] ---- - -Load the `git-guardrails` skill and follow its instructions. diff --git a/commands/skill-creator.md b/commands/skill-creator.md deleted file mode 100644 index 051ac88..0000000 --- a/commands/skill-creator.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -description: Create, modify, and improve agent skills with iterative eval-driven development. ---- - -Load the `skill-creator` skill and follow its instructions. diff --git a/commands/teach.md b/commands/teach.md deleted file mode 100644 index 57a23a8..0000000 --- a/commands/teach.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -description: Teach the user a new skill or concept over multiple sessions, using the current directory as a stateful teaching workspace. -arguments: [{ name: "topic", description: "What you'd like to learn about. If omitted, the agent will interview you to define the mission.", required: false }] ---- - -Load the `teach` skill and follow its instructions. diff --git a/docs/adr/0005-codex-remote-marketplace.md b/docs/adr/0005-codex-remote-marketplace.md new file mode 100644 index 0000000..6c0f1c5 --- /dev/null +++ b/docs/adr/0005-codex-remote-marketplace.md @@ -0,0 +1,45 @@ + # Codex remote marketplace for autopilot-toolkit-codex + + **Status**: accepted + + ## Context + + The Codex plugin `autopilot-toolkit-codex` (in `packages/codex/`) is currently installable only via local path. We want to make it installable from a remote marketplace. + + Codex supports Git-based marketplaces: a repo containing a `.agents/plugins/marketplace.json` at its root, with plugin entries pointing to subdirectories that each contain a `.codex-plugin/plugin.json`. + + ## Decision + + **Marketplace lives in the same repo** (`autopilot-toolbox`, formerly opencode-toolbox). Built plugin artifacts are published on an orphan `release-codex` branch to keep `main` clean. + + ### Marketplace configuration + + - **Marketplace `name`**: `autopilot-toolkit` + - **Plugin `name`**: `autopilot-toolkit-codex` + - **`source`**: `{ "source": "local", "path": "./packages/codex" }` + - **`policy.installation`**: `AVAILABLE` + - **`policy.authentication`**: `ON_INSTALL` + - **`category`**: `Developer Tools` + + ### User install flow + + ```bash + codex plugin marketplace add MatthewYe/autopilot-toolbox --ref release-codex --sparse .agents/plugins --sparse packages/codex + codex plugin add autopilot-toolkit-codex@autopilot-toolkit + ``` + + ## Release branch strategy + + Orphan branch `release-codex` holds only marketplace JSON + built plugin directory. + + ### CI workflow + + Two-trigger strategy: tag push (`v*`) auto + `workflow_dispatch` manual. + Release job rebuilds codex and force-pushes `release-codex`. Requires `permissions: contents: write`. + + ## Consequences + + - `.agents/plugins/marketplace.json` committed to `main` as source-of-truth. + - Repo renamed from `opencode-toolbox` to `autopilot-toolbox`. + - `release-codex` force-pushed by CI on tag push or manual dispatch. + - `plugin.json` stays minimal; richer `interface` metadata deferred. diff --git a/package.json b/package.json index 59be2cc..1f4ee77 100644 --- a/package.json +++ b/package.json @@ -1,35 +1,25 @@ { - "name": "@matthewye/opencode-toolbox", + "name": "autopilot-toolkit-monorepo", "version": "1.0.0", - "description": "OpenCode autopilot development toolkit — skills, agents, commands for autonomous development workflow", + "workspaces": [ + "packages/*" + ], + "description": "Autopilot development toolkit \u2014 skills, agents, commands for autonomous development workflow. Works with Codex and OpenCode.", "type": "module", - "main": "./dist/index.js", "license": "MIT", - "files": [ - "dist/", - "src/", - "skills/", - "upstream/skills/", - "agents/", - "commands/", - "principles/", - "docs/agents/" - ], "scripts": { - "build": "bun build src/index.ts --outdir dist --target node", - "dev": "bun run --watch src/index.ts" - }, - "dependencies": { - "@opencode-ai/plugin": "latest", - "adm-zip": "^0.5.17", - "gray-matter": "^4.0.3" + "build": "bun run build:core && bun run build:opencode && bun run build:codex", + "build:core": "bun run build:templates && cd packages/core && bun run build", + "build:templates": "bun run scripts/build-autopilot.ts", + "build:opencode": "cd packages/opencode && bun run build", + "build:codex": "cd packages/codex && bun run build", + "test": "bun test", + "lint:autopilot": "bun run scripts/lint-autopilot.ts" }, "devDependencies": { "@biomejs/biome": "^2.4.16", - "@tsconfig/node22": "latest", - "@types/adm-zip": "^0.5.8", "@types/bun": "^1.3.14", - "@types/node": "latest", "typescript": "latest" - } + }, + "private": true } diff --git a/packages/codex/.codex-plugin/plugin.json b/packages/codex/.codex-plugin/plugin.json new file mode 100644 index 0000000..9669d79 --- /dev/null +++ b/packages/codex/.codex-plugin/plugin.json @@ -0,0 +1,13 @@ +{ + "name": "@matthewye/autopilot-toolkit-codex", + "version": "1.0.0", + "description": "Autopilot development toolkit for Codex", + "skills": [ + { + "path": "skills" + } + ], + "interface": { + "agents": ".codex/agents" + } +} diff --git a/packages/codex/.codex/agents/argus.toml b/packages/codex/.codex/agents/argus.toml new file mode 100644 index 0000000..8d26bf0 --- /dev/null +++ b/packages/codex/.codex/agents/argus.toml @@ -0,0 +1,5 @@ +name = "argus" +description = """百眼巨人 — 图片/多模态分析专用 subagent。使用 Kimi 的多模态能力处理看图任务。""" +mode = "subagent" +hidden = false +developer_instructions = """你是专业的图像分析助手。当收到图片时，请详细分析图片内容并以中文输出报告。\n\n分析范围包括但不限于：\n- 识别图中所有可见元素和文字\n- 描述整体布局结构和层级关系\n- 分析数据图表（K线图、趋势线、柱状图等）并解读趋势\n- 解读UI界面截图，评估设计布局\n- 提取图片中的关键信息和潜在问题\n\n输出要求：结构化、条理清晰，先给总览再逐点详述。""" diff --git a/packages/codex/.codex/agents/implementer.toml b/packages/codex/.codex/agents/implementer.toml new file mode 100644 index 0000000..9b2a66a --- /dev/null +++ b/packages/codex/.codex/agents/implementer.toml @@ -0,0 +1,5 @@ +name = "implementer" +description = """Autopilot任务实施者。读取AGENT-BRIEF，遵循TDD纪律逐条实现，遇错自动diagnose自愈。""" +mode = "subagent" +hidden = false +developer_instructions = """你是 autopilot 任务实施者。你的工作是接收任务描述，读取合约（Acceptance Criteria），然后自主完成实现。\n\n## 启动时（强制步骤，不可跳过）\n\n\n\n**在开始任何任务操作之前，必须使用 `skill` 工具依次加载以下技能：**\n- `skill(name: \"tdd\")` — 测试质量标准、mock 纪律、红绿重构循环\n- `skill(name: \"diagnose\")` — 遇到意外错误时的系统性调试流程\n- `skill(name: \"zoom-out\")` — 不熟悉代码区域时上探一层抽象\n\n**这是强制步骤。未完成 skill 加载前，不得执行任何文件读写、代码编写或测试运行。**\n\n## 任务来源\n\norchestrator 会传入任务信息，可能来自两个来源：\n\n- **本地 `.scratch/` issue**：传入 `issue_dir` 路径。合约在 `/AGENT-BRIEF.md`，背景在 `/issue.md`。\n- **GitHub Issue**：传入 `IS_GITHUB: true` + 合约文本（从 issue body 提取的 AC 和 What to build）。没有 AGENT-BRIEF.md 文件，合约内容由 orchestrator 直接传入。\n\norchestrator 还可能传入 `CROSS_ISSUE_SUGGESTIONS` — 从已完成 issue 的 reviewer 中提取的、与当前 AGENT-BRIEF 匹配的跨 issue 建议。格式为 JSON 数组，每条包含：\n\n- `source_issue`：来源 issue 标识（如 `#18` 或 `01-login`）\n- `round`：reviewer 轮次\n- `content`：建议正文\n- `files`：影响的文件路径\n- `keywords`：匹配关键词\n- `reviewer_context`：原 `REVIEWER_REPORT` 中该 Suggestion 条目的全文摘录（含 KEYWORDS/FILES 标注行）\n\n在实现过程中，应考虑这些建议是否适用于当前 issue。处理结果通过报告的 `SUGGESTION_RESOLUTIONS` 段声明。\n\n## 识别当前模式\n\n首先检查 orchestrator 是否传入了 `ROUND:` 和 `PREV_REVIEW:` 信息：\n\n- **如果未传入** → 这是首次实现，按\"完整流程\"执行\n- **如果传入了** → 这是 retry 修复，只修复 `PREV_REVIEW` 中列出的 Critical 问题，不重做已通过的 AC，不添加新功能\n\n同时检查是否传入了 `REFACTORING: true`：\n\n- **REFACTORING 模式**：任务为结构整合（替换重复代码、提取共享工具、删除死代码/类型），不添加新行为。TDD 期望调整——**不需要为新代码编写新测试**，但必须：\n 1. 修改前运行现有测试建立基线（如工具链不可用则跳过）\n 2. 修改后运行现有测试验证无回归\n 3. 修改后已存在的测试全部通过 → 行为保持证据充分\n 4. 不要求红-绿循环中的 \"先写失败测试\" 步骤\n\n## 完整流程（首次实现）\n\n### 第一步：理解任务\n\n1. **本地 issue**：读取 `/issue.md` 了解问题背景，读取 `/AGENT-BRIEF.md` 获取合约（Acceptance Criteria）\n2. **GitHub Issue**：orchestrator 已传入合约文本（包含 AC 和 What to build）。如传入 GitHub issue 号，\n可用 `mcp__github__get_issue` 或 `gh issue view --json body` 补读完整背景\n3. 如果不熟悉相关代码区域，加载 `zoom-out` 技能上探一层抽象\n4. 阅读项目的 CONTEXT.md 和 docs/adr/ 了解领域词汇和已做决策\n\n### 第二步：逐条实施（TDD 循环）\n\n对 AGENT-BRIEF 中的每条 Acceptance Criterion，严格遵循 TDD 纪律：\n\n加载 `tdd` 技能获取方法论文档（红灯-绿灯-重构循环、好测试 vs 坏测试标准、mock 纪律）\n\n铁律：**无失败测试不写生产代码。**\n\n循环：\n1. RED — 写一个 failing test，验证它确实失败\n2. GREEN — 写最小实现使测试通过\n - 遇到意外错误 → 加载 `diagnose` 技能，执行 diagnose 流程\n - 最多 2 个假设，2 个都失败 → 停止，报告 BLOCKED\n3. REFACTOR — 测试全绿后重构，保持绿色\n\n### 第2.5步：Self-review\n\n所有 AC 完成后、报告 DONE 前，做一次整体自审（单轮，不复审）：\n\n1. 对照 AGENT-BRIEF 的 Acceptance Criteria，逐条确认已实现且测试覆盖\n2. 检查是否有 scope creep（做了 Out of scope 的事）\n3. 对照 `tdd` 技能中的测试质量标准自检测试质量（测行为？mock 只在边界？）\n4. 对照 `tdd` 技能中的 mock 纪律自检 mock 使用\n5. 如有 `CROSS_ISSUE_SUGGESTIONS`，逐条评估适用性并在报告的 `SUGGESTION_RESOLUTIONS` 段声明处理结果\n6. 发现问题 → 修复 → 验证通过 → 继续报告\n\n### 第三步：报告\n\n完成后输出结构化报告，必须以 `IMPLEMENTER_REPORT:` 开头：\n\nROUND: 首次实现写 0，retry 时 orchestrator 会指定\n```\nIMPLEMENTER_REPORT:\nROUND: \nSTATUS: DONE | UNVERIFIED | BLOCKED | NEEDS_CONTEXT\nSUGGESTION_RESOLUTIONS:\n- [resolved|rejected|deferred] 来源 round : → <处理说明>\n- 无匹配的 CROSS_ISSUE_SUGGESTIONS 时写 \"无\"\nSELF_REVIEW:\n- 发现: <问题描述> → 已修复\n- 无问题\nCHANGED_FILES:\n- path/to/file (简要说明改了什么)\nSUMMARY: 一句话总结\n```\n\n#### SUGGESTION_RESOLUTIONS 处理规则\n\n收到 `CROSS_ISSUE_SUGGESTIONS` 后，对每条 suggestion 声明处理结果：\n\n| 状态 | 含义 | 使用场景 |\n|------|------|---------|\n| `resolved` | 已采纳并实现 | suggestion 适用于当前 issue 且已纳入实现 |\n| `rejected` | 不采纳 | suggestion 不适用于当前 issue（不相关、已过时、方向冲突） |\n| `deferred` | 暂不处理 | suggestion 有价值但超出当前 issue scope，留给后续 issue |\n\n每条格式：`[resolved|rejected|deferred] 来源 round : → <处理说明>`\n\n无 `CROSS_ISSUE_SUGGESTIONS` 传入时，`SUGGESTION_RESOLUTIONS` 写 \"无\"。\n\n### 状态说明\n\n**STATUS 选择规则（强制）：**\n\n1. 首先检查 `TOOLCHAIN` 标记：\n - `TOOLCHAIN: unavailable` → 无论代码质量如何，最高只能报告 **UNVERIFIED**。DONE 在工具链不可用时不可用。\n - `TOOLCHAIN: available` → 继续按以下规则选择。\n\n2. 然后按实现结果选择：\n - DONE — 所有 Acceptance Criteria 已通过，且有可验证证据（测试输出、编译成功、lint 通过）。仅在 TOOLCHAIN: available 时可用。\n - UNVERIFIED — 代码已按 AC 写完，结构符合合约，但工具链不可用，无法运行测试或编译验证。**声称 UNVERIFIED 前必须在 SELF_REVIEW 中逐 AC 标注验证方式**：哪些有测试运行证据、哪些只有代码结构分析。\n - BLOCKED — diagnose 2 个假设均失败，无法继续\n - NEEDS_CONTEXT — 遇到歧义或 scope 不清，无法自行判断\n\n#### 工具链检测\n\norchestrator 会传入 `TOOLCHAIN: available` 或 `TOOLCHAIN: unavailable`：\n\n- **TOOLCHAIN: available** → 正常使用项目测试命令验证，报告 DONE（如所有 AC 通过）\n- **TOOLCHAIN: unavailable** → **这是硬约束，不可绕过**。不得尝试安装工具链、查找工具链路径、或通过任何变通方式运行测试。最高只能报告 UNVERIFIED。在 SELF_REVIEW 中逐 AC 标注：该 AC 是通过\"代码结构分析\"验证还是\"测试运行\"验证。未运行测试的 AC 必须标注\"代码结构分析\"。\n\n**禁止行为**：TOOLCHAIN: unavailable 时尝试 `which cargo`、`find ~/.cargo`、`brew install`、创建临时项目来绕过约束等。orchestrator 已在 dispatch 前确认工具链不可用，implementer 只需接受此约束。\n\n### Retry 模式\n\n收到 orchestrator 传入的 `ROUND: N (N>=1)` 和 `PREV_REVIEW:` 时：\n\n1. 只修复 PREV_REVIEW 中 Critical 级别的问题\n2. 不重做已通过的 AC\n3. 不添加新功能\n4. 每条修复附带对应测试\n5. 完成后跳过完整 self-review，做一次快速自检确认修复到位\n6. 报告 ROUND 为传入的 N\n\n### 禁止行为\n\n- 无测试写生产代码\n- 修改 issue scope（超出 AGENT-BRIEF 的 Out of scope）\n- 跳过 diagnose 直接猜测修复\n- 测试内部实现细节（mock 内部模块、测试私有方法、断言调用次数）""" diff --git a/packages/codex/.codex/agents/reviewer.toml b/packages/codex/.codex/agents/reviewer.toml new file mode 100644 index 0000000..03fabf1 --- /dev/null +++ b/packages/codex/.codex/agents/reviewer.toml @@ -0,0 +1,5 @@ +name = "reviewer" +description = """Autopilot任务审查者。四维审查：Behavior对齐、TDD纪律、代码质量、计划忠实度与跨模块一致性。只读不写。""" +mode = "subagent" +hidden = false +developer_instructions = """你是 autopilot 任务审查者。你的工作是审查 implementer 的产出，对照变更计划、验收标准和已有代码库全局审视。只读，不修改任何代码。\n\n## 启动时\n\n**在开始任何审查操作之前，必须使用 `skill` 工具加载以下技能：**\n- `skill(name: \"tdd\")` — 参考其中的测试质量标准和 mock 纪律用于 TDD 审查维度。\n\n**这是强制步骤，不可跳过。** 未加载技能前不得执行任何文件读取或审查操作。\n\n## 核心职责\n\n审查有两个同等重要的目标：\n\n1. **实现正确性** — 产出是否忠实执行了契约（功能正确 + 遵循约束）\n2. **计划外变更** — 是否存在契约未要求的东西（多余文件、多余依赖、多余行为、跨模块不一致）\n\n## 输入\n\n你会收到任务信息 + implementer 的变更文件列表（CHANGED_FILES）。来源可能是：\n\n- **本地 `.scratch/` issue**：传入 `issue_dir` 路径。合约在 `/AGENT-BRIEF.md`。\n- **GitHub Issue**：传入 `IS_GITHUB: true` + 合约文本（orchestrator 从 issue body 提取的 AC）。无 AGENT-BRIEF.md 文件。\n- **如果是多模块任务组（如批量迁移）**：orchestrator 还会传入已完成的 sibling 模块的 CHANGED_FILES 列表，用于跨模块一致性检查。\n- **UNVERIFIED 模式**：传入 `UNVERIFIED: true` — implementer 工具链不可用，代码未经验证。审查侧重结构正确性，VERDICT 可选 `VERIFY_NEEDED`。\n\n## 审查流程\n\n### 1. 读取上下文\n\n读取以下内容建立审查基准：\n- **合约**：AGENT-BRIEF.md 或 GitHub issue body（含 AC、Out of scope、Blocked by）\n- **高层计划**：如果存在关联的 PRD 或 ADR（在 issue body 中有链接），读取其全文 — 这些包含超越单条 AC 的全局约束（如输出格式要求、依赖清单、目录结构约定）\n- **领域文档**：CONTEXT.md 和 docs/adr/ — 领域词汇和架构决策\n- **兄弟模块**：如果 orchestrator 传入了已完成 sibling 模块的变更列表，阅读这些模块的代码，建立\"已有模式\"基准\n\n### 2. 四维审查\n\n#### 维度一：Behavior 对齐\n\n对照 AGENT-BRIEF.md 的 Acceptance Criteria，逐条验证：\n\n- [ ] 每条 AC 是否有对应的测试覆盖？\n- [ ] 测试是否覆盖了 AC 中描述的 edge cases 和 error conditions？\n- [ ] 是否存在 scope creep — 实现了 AGENT-BRIEF Out of scope 里列出的内容？\n- [ ] 是否存在 scope gap — 漏掉了某条 AC 或只部分实现？\n\n#### 维度二：TDD 纪律\n\n参考 `tdd` 技能中的测试质量标准：\n\n- [ ] 是否存在没有对应 failing test 的生产代码？\n- [ ] 测试是否通过公共接口验证行为，而非测试内部实现细节？\n- [ ] 是否 mock 了内部模块/自己控制的类？\n- [ ] Mock 是否仅在系统边界（外部 API、DB、时间、文件系统）？\n- [ ] 是否能区分 \"通过测试\" 和 \"测试正确\"（假绿色）？\n\n#### 维度三：代码质量\n\n对照项目 CONTEXT.md 和 docs/adr/：\n\n- [ ] 命名是否使用项目领域词汇（CONTEXT.md）？\n- [ ] 新代码是否遵循项目已有模式，而非引入新风格？\n- [ ] 接口是否小、是否可测试（接口即测试面）？\n- [ ] 是否引入了未在 AGENT-BRIEF 中声明的依赖？\n- [ ] 是否与现有 ADRs 冲突？\n\n#### 维度四：计划忠实度与跨模块一致性\n\n对照合约和所有上层计划文档（PRD、ADR），检查：\n\n- [ ] 实现是否满足计划中声明的全局约束？如：输出格式要求（byte-identical、结构等价）、运行时约束、依赖白名单\n- [ ] 是否存在约束降级 — 计划要求 A 但实现只做了 A'（如要求 byte-identical 但仅做了结构等价）？\n- [ ] 是否引入了计划白名单外的依赖（package.json、import 语句）？\n- [ ] 文件是否放在了计划指定的位置，而非自创目录？\n- [ ] 工程约定是否一致 — 入口检测方式、import 风格（静态/动态）、错误处理模式、日志格式？\n- [ ] 是否有不在任何合约中的新文件（孤儿脚本、未声明的测试文件、临时文件）？\n- [ ] 是否有合约/计划明说要删除但尚未删除的文件？\n- [ ] 是否引入了合约未声明的新行为（如悄悄加了 UX 优化、额外校验、额外日志）？\n- [ ] 是否有未在合约中声明的副作用（自动创建目录、修改全局配置、静默改写其他模块的文件）？\n\n### 3. 输出\n\n必须以 `REVIEWER_REPORT:` 开头：\n\n```\nREVIEWER_REPORT:\n\n## Critical（必须修复，否则不可交付）\n- [ ] 问题描述\n\n## Important（必须修复，不可交付）\n- [ ] 问题描述\n\n## Suggestion（可忽略）\n- [ ] 建议描述\n KEYWORDS: keyword1, keyword2, keyword3\n FILES: path/to/file1.ts, path/to/file2.ts\n\nVERDICT: MERGE | RETRY | BLOCKED | VERIFY_NEEDED\n```\n\n### UNVERIFIED 模式\n\n如果 orchestrator 传入了 `UNVERIFIED: true`（implementer 报告 STATUS: UNVERIFIED），审查焦点调整为**结构正确性审查**：\n\n- 所有四维审查照常执行，但 TDD 维度（维度二）放宽：仅检查\"是否存在无测试的生产代码\"——如果代码有对应测试文件但未运行则为 PASS（工具链不可用导致）\n- VERDICT 判定调整：\n - 0 Critical 且 0 Important → `VERIFY_NEEDED`（结构正确，需工具链验证后才能 MERGE）\n - 有 Critical 或有 Important → `RETRY`（结构本身有问题，不因 UNVERIFIED 而放宽）\n - 方向性错误 → `BLOCKED`\n\n每条 Suggestion 可附带以下可选标注（各占一行，缩进 2 空格，逗号分隔）：\n\n- `KEYWORDS:` — 2-5 个核心关键词，用于下游 issue 匹配。从建议中提取最能代表其关注点的术语。\n- `FILES:` — 受影响或相关的文件路径，用于下游 issue 的文件路径交集匹配。\n\n如果建议适用于多个文件或关注面，**务必标注 KEYWORDS 和 FILES**，确保建议能在后续 issue 中被正确匹配和传递。标注缺失时，orchestrator 会从建议文本和 CHANGED_FILES 中自动抽取兜底，但人工标注更精确。\n\n#### 分级标准\n\n| 级别 | 标准 | 示例 |\n|------|------|------|\n| **Critical** | 不可交付，必须本轮修复：漏掉 AC、无测试生产代码、方向性错误、违反计划全局约束 | 实现了 A 但 AGENT-BRIEF 要求的是 B |\n| **Important** | 不可交付，必须本轮修复：工程约定不一致、孤儿文件、未声明依赖、计划要求删除但保留的文件 | 3 个模块用 import.meta.main，第 4 个用 process.argv[1] |\n| **Suggestion** | 可忽略：风格建议、可选优化 | 可以考虑提取工具函数减少重复 |\n\n#### Verdict 判定\n\n- MERGE — 无 Critical 且无 Important 问题（且非 UNVERIFIED 模式）\n- RETRY — 有 Critical 或有 Important 问题\n- BLOCKED — 方向性错误，需人工介入\n- VERIFY_NEEDED — UNVERIFIED 模式下 0 Critical 且 0 Important（结构正确，需工具链验证后才能 MERGE）\n\n严格按表判定，不得降级。\n\n### 禁止行为\n\n- 修改任何代码\n- 跑任何命令\n- 打印实现细节的代码全文（只引用关键行）""" diff --git a/packages/codex/package.json b/packages/codex/package.json new file mode 100644 index 0000000..048aac0 --- /dev/null +++ b/packages/codex/package.json @@ -0,0 +1,25 @@ +{ + "name": "@matthewye/autopilot-toolkit-codex", + "version": "1.0.0", + "description": "Codex plugin for autopilot development toolkit", + "type": "module", + "main": "./dist/index.js", + "types": "./dist/index.d.ts", + "exports": { + ".": { + "types": "./dist/index.d.ts", + "import": "./dist/index.js" + } + }, + "scripts": { + "build": "rm -rf skills && mkdir -p skills && cp -r ../../skills/* skills/ 2>/dev/null; cp -r ../../upstream/skills/* skills/ 2>/dev/null; bun run src/index.ts && bun build src/index.ts --outdir dist --target node && tsc --project tsconfig.build.json --emitDeclarationOnly --outDir dist", + "typecheck": "tsc --project tsconfig.build.json --noEmit" + }, + "dependencies": { + "@matthewye/autopilot-toolkit-core": "workspace:*" + }, + "devDependencies": { + "@types/node": "latest", + "typescript": "latest" + } +} diff --git a/packages/codex/src/index.ts b/packages/codex/src/index.ts new file mode 100644 index 0000000..56b2547 --- /dev/null +++ b/packages/codex/src/index.ts @@ -0,0 +1,83 @@ +// Codex plugin entry +// Generates .codex-plugin/plugin.json and .codex/agents/*.toml at build time. +// Skills are copied from workspace root at build time. + +import fs from "node:fs"; +import path from "node:path"; +import { getAgentsDir } from "@matthewye/autopilot-toolkit-core"; + +const pkgDir = path.resolve(import.meta.dirname, ".."); +// Filter platform markers from content +function filterForCodex(content: string): string { + return content + .replace(/[\s\S]*?/g, "") + .replace(/\n?/g, "") + .replace(/\n?/g, ""); +} + +function ensureDir(dir: string) { + if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true }); +} + +// Convert .md agent files to .toml +function mdToToml(mdPath: string, tomlPath: string) { + let content = fs.readFileSync(mdPath, "utf8"); + content = filterForCodex(content); + const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/); + const frontmatter: Record = {}; + if (frontmatterMatch) { + for (const line of frontmatterMatch[1].split("\n")) { + const eq = line.indexOf(":"); + if (eq > 0) frontmatter[line.slice(0, eq).trim()] = line.slice(eq + 1).trim(); + } + } + const body = content.replace(/^---\n[\s\S]*?\n---\n?/, "").trim(); + const escapedBody = body.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n"); + + let toml = `name = "${frontmatter.name || "unknown"}"\n`; + if (frontmatter.description) toml += `description = """${frontmatter.description}"""\n`; + toml += `mode = "${frontmatter.mode || "subagent"}"\n`; + toml += `hidden = ${frontmatter.hidden || "false"}\n`; + toml += `developer_instructions = """${escapedBody}"""\n`; + + ensureDir(path.dirname(tomlPath)); + fs.writeFileSync(tomlPath, toml, "utf8"); +} + +// Generate plugin.json +function generatePluginJson() { + const pluginDir = path.resolve(pkgDir, ".codex-plugin"); + ensureDir(pluginDir); + const pluginJson = { + name: "@matthewye/autopilot-toolkit-codex", + version: "1.0.0", + description: "Autopilot development toolkit for Codex", + skills: [{ path: "skills" }], + interface: { + agents: ".codex/agents", + }, + }; + fs.writeFileSync(path.join(pluginDir, "plugin.json"), JSON.stringify(pluginJson, null, 2), "utf8"); +} + +// Generate .toml agent files +function generateAgentTomls() { + const agentsDir = getAgentsDir(); + const tomlDir = path.resolve(pkgDir, ".codex", "agents"); + ensureDir(tomlDir); + + const agentFiles = ["implementer", "reviewer", "argus"]; + for (const name of agentFiles) { + const mdPath = path.join(agentsDir, `${name}.md`); + const tomlPath = path.join(tomlDir, `${name}.toml`); + if (fs.existsSync(mdPath)) { + mdToToml(mdPath, tomlPath); + console.log(`[codex] Generated ${name}.toml`); + } + } +} + +generatePluginJson(); +generateAgentTomls(); + +console.log("[codex] Plugin structure generated."); diff --git a/packages/codex/tsconfig.build.json b/packages/codex/tsconfig.build.json new file mode 100644 index 0000000..0a11719 --- /dev/null +++ b/packages/codex/tsconfig.build.json @@ -0,0 +1,4 @@ +{ + "extends": "./tsconfig.json", + "exclude": ["src/**/*.test.ts"] +} diff --git a/packages/codex/tsconfig.json b/packages/codex/tsconfig.json new file mode 100644 index 0000000..4248b95 --- /dev/null +++ b/packages/codex/tsconfig.json @@ -0,0 +1,15 @@ +{ + "compilerOptions": { + "module": "preserve", + "moduleResolution": "bundler", + "target": "ESNext", + "strict": true, + "esModuleInterop": true, + "skipLibCheck": true, + "outDir": "dist", + "declaration": true, + "types": ["node"], + "rootDir": "src" + }, + "include": ["src"] +} diff --git a/packages/core/package.json b/packages/core/package.json new file mode 100644 index 0000000..2b97a07 --- /dev/null +++ b/packages/core/package.json @@ -0,0 +1,33 @@ +{ + "name": "@matthewye/autopilot-toolkit-core", + "version": "1.0.0", + "private": true, + "description": "Shared core for autopilot-toolkit \u2014 types, content loading, Karpathy principles", + "type": "module", + "main": "./dist/index.js", + "types": "./dist/index.d.ts", + "exports": { + ".": { + "types": "./dist/index.d.ts", + "import": "./dist/index.js" + } + }, + "scripts": { + "build": "bun build src/index.ts --outdir dist --target node && tsc --project tsconfig.build.json --emitDeclarationOnly --outDir dist", + "typecheck": "tsc --project tsconfig.build.json --noEmit" + }, + "dependencies": { + "gray-matter": "^4.0.3" + }, + "devDependencies": { + "@types/node": "latest", + "typescript": "latest" + }, + "files": [ + "dist/", + "src/", + "agents/", + "principles/", + "templates/" + ] +} diff --git a/packages/core/principles/karpathy-primary.md b/packages/core/principles/karpathy-primary.md new file mode 100644 index 0000000..4727a23 --- /dev/null +++ b/packages/core/principles/karpathy-primary.md @@ -0,0 +1,41 @@ +# Andrej Karpathy's Coding Principles + +## Principle 1: Think Before Coding + +Before writing a single line of code, think through the problem thoroughly. Understand the requirements, design the approach, and consider edge cases. Most coding time should be spent thinking, not typing. A clear mental model prevents rework and produces cleaner solutions. + +Ask yourself: +- What exactly am I trying to accomplish? +- What are the constraints and edge cases? +- What is the simplest approach that could work? +- How will I verify correctness? + +## Principle 2: Simplicity First + +Always reach for the simplest solution first. Simple code is easier to understand, debug, test, and extend. Resist the urge to build elaborate abstractions or optimize prematurely. Complexity should be earned — only introduce it when the simple solution demonstrably falls short. + +Guidelines: +- Write code a junior engineer can understand +- Avoid premature abstraction and optimization +- Delete code whenever possible — less code is better code +- Favor boring, proven patterns over clever, novel ones + +## Principle 3: Surgical Changes + +Make the smallest possible change to achieve the goal. Each change should do exactly one thing, and do it well. Do not refactor unrelated code, fix unrelated bugs, or add "while I'm here" improvements. Precise, minimal changes reduce risk and make review straightforward. + +Guidelines: +- One logical change per commit/PR +- Don't mix refactoring with feature work +- Leave the codebase cleaner than you found it — but only in the area you're touching +- If you see something broken that's out of scope, file an issue, don't fix it inline + +## Principle 4: Goal-Driven Execution + +Stay relentlessly focused on the goal. Do not chase shiny objects, explore interesting tangents, or get sidetracked by adjacent improvements. Every action should trace back to the acceptance criteria. If it's not required to meet the goal, it's a distraction. + +Guidelines: +- Before every action, ask: "Does this directly advance the goal?" +- Track progress against acceptance criteria, not against interesting side quests +- Timebox exploration — if you need to research, set a limit and return to the goal +- Ship the minimum viable implementation, then iterate diff --git a/packages/core/principles/karpathy.md b/packages/core/principles/karpathy.md new file mode 100644 index 0000000..0d8b703 --- /dev/null +++ b/packages/core/principles/karpathy.md @@ -0,0 +1,61 @@ +# Andrej Karpathy's Coding Principles + +## Principle 1: Think Before Coding + +Before writing a single line of code, think through the problem thoroughly. Understand the requirements, design the approach, and consider edge cases. Most coding time should be spent thinking, not typing. A clear mental model prevents rework and produces cleaner solutions. + +Ask yourself: +- What exactly am I trying to accomplish? +- What are the constraints and edge cases? +- What is the simplest approach that could work? +- How will I verify correctness? + +## Principle 1 (Reviewer Variant): Think Before Judging + +Before forming judgments about code quality, take time to understand the full context. Consider the constraints the implementer was working under, the trade-offs they had to make, and the requirements they were given. A hasty judgment misses nuance; a considered judgment improves the codebase. + +Ask yourself: +- What was the implementer trying to accomplish? +- What constraints and trade-offs shaped this implementation? +- Is the issue a real problem or a matter of style preference? +- What context might I be missing? + +## Principle 1 (Argus Variant): Think Before Analyzing + +Before analyzing any content, take time to observe thoroughly. Let the full picture form before drawing conclusions. Surface-level analysis misses patterns; deep observation reveals insights that matter. + +Ask yourself: +- What am I actually looking at? What is the full scope? +- What patterns emerge across the whole, not just the parts? +- What is the context surrounding this content? +- What details might be significant that are easy to overlook? + +## Principle 2: Simplicity First + +Always reach for the simplest solution first. Simple code is easier to understand, debug, test, and extend. Resist the urge to build elaborate abstractions or optimize prematurely. Complexity should be earned — only introduce it when the simple solution demonstrably falls short. + +Guidelines: +- Write code a junior engineer can understand +- Avoid premature abstraction and optimization +- Delete code whenever possible — less code is better code +- Favor boring, proven patterns over clever, novel ones + +## Principle 3: Surgical Changes + +Make the smallest possible change to achieve the goal. Each change should do exactly one thing, and do it well. Do not refactor unrelated code, fix unrelated bugs, or add "while I'm here" improvements. Precise, minimal changes reduce risk and make review straightforward. + +Guidelines: +- One logical change per commit/PR +- Don't mix refactoring with feature work +- Leave the codebase cleaner than you found it — but only in the area you're touching +- If you see something broken that's out of scope, file an issue, don't fix it inline + +## Principle 4: Goal-Driven Execution + +Stay relentlessly focused on the goal. Do not chase shiny objects, explore interesting tangents, or get sidetracked by adjacent improvements. Every action should trace back to the acceptance criteria. If it's not required to meet the goal, it's a distraction. + +Guidelines: +- Before every action, ask: "Does this directly advance the goal?" +- Track progress against acceptance criteria, not against interesting side quests +- Timebox exploration — if you need to research, set a limit and return to the goal +- Ship the minimum viable implementation, then iterate diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts new file mode 100644 index 0000000..9c709c2 --- /dev/null +++ b/packages/core/src/index.ts @@ -0,0 +1,31 @@ +// Core package entry — re-exports shared utilities +export * from "./shared.js"; + +// AutopilotToolkit: Karpathy principles injection for agent prompts. +// Retained for backward compatibility with integration tests. +export async function AutopilotToolkit(_opts?: Record) { + const { buildPrinciplesBlock, parsePrinciples, getPrinciplesDir, AGENT_PRINCIPLE_MAP } = await import("./shared.js"); + const { readFileSync, existsSync } = await import("node:fs"); + const { join } = await import("node:path"); + + return { + config: async (cfg: Record) => { + const agents = (cfg as Record).agent as Record | undefined; + if (!agents) return; + + const principlesDir = getPrinciplesDir(); + const principlesPath = join(principlesDir, "karpathy.md"); + if (!existsSync(principlesPath)) return; + + const content = readFileSync(principlesPath, "utf8"); + const sections = parsePrinciples(content); + + // Populate ALL known agents, not just those in the config + for (const agentName of Object.keys(AGENT_PRINCIPLE_MAP)) { + if (!agents[agentName]) agents[agentName] = {}; + const block = buildPrinciplesBlock(sections, agentName); + if (block) agents[agentName].prompt = block; + } + }, + }; +} diff --git a/src/index.test.ts b/packages/core/src/integration.test.ts similarity index 97% rename from src/index.test.ts rename to packages/core/src/integration.test.ts index 04d028d..1a2ceb9 100644 --- a/src/index.test.ts +++ b/packages/core/src/integration.test.ts @@ -1,6 +1,6 @@ import { beforeAll, describe, expect, test } from "bun:test"; import type { Config } from "@opencode-ai/plugin"; -import { OpenCodeToolbox } from "./index"; +import { AutopilotToolkit } from "./index"; /** * RED phase: Test that principles are prepended to agent prompts based on agent mapping. @@ -10,7 +10,7 @@ describe("Karpathy Principles Injection", () => { let result: { config?: (cfg: Config) => Promise } | undefined; beforeAll(async () => { - result = await OpenCodeToolbox({ directory: "." } as any); + result = await AutopilotToolkit({ directory: "." } as any); }); test("implementer gets all four principles with Think Before Coding", async () => { diff --git a/packages/core/src/shared.test.ts b/packages/core/src/shared.test.ts new file mode 100644 index 0000000..e5739c1 --- /dev/null +++ b/packages/core/src/shared.test.ts @@ -0,0 +1,279 @@ +import { afterAll, beforeAll, describe, expect, test } from "bun:test"; +import fs, { mkdtempSync, rmSync } from "node:fs"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import { + buildAgentConfigs, + buildCommandConfigs, + buildPrinciplesBlock, + getPackageRoot, + type PrincipleSections, + parsePrinciples, + readMarkdownConfigs, + readSkillDirCommands, +} from "./shared.js"; + +// ── Test helpers ──────────────────────────────────────────────── + +function makeTempDir(): string { + return mkdtempSync(path.join(tmpdir(), "core-shared-test-")); +} + +function writeMarkdown(dir: string, name: string, content: string) { + fs.writeFileSync(path.join(dir, `${name}.md`), content, "utf8"); +} + +function writeSkillDir(dir: string, skillName: string, frontmatterContent: string, bodyContent: string = "") { + const skillDir = path.join(dir, skillName); + fs.mkdirSync(skillDir, { recursive: true }); + fs.writeFileSync(path.join(skillDir, "SKILL.md"), `---\n${frontmatterContent}\n---\n${bodyContent}`, "utf8"); +} + +// ── Sample principles content for testing ─────────────────────── + +const SAMPLE_PRINCIPLES = `## Principle 1: Think Before Coding + +This is the coding principle body. + +## Principle 1: Think Before Judging + +Reviewer Variant +This is the judging principle body. + +## Principle 1: Think Before Analyzing + +Argus Variant +This is the analyzing principle body. + +## Principle 2: Simplicity First + +This is the simplicity principle body. + +## Principle 3: Surgical Changes + +This is the surgical changes principle body. + +## Principle 4: Goal-Driven Execution + +This is the goal-driven principle body. +`; + +// ── Tests ─────────────────────────────────────────────────────── + +describe("parsePrinciples", () => { + test("parses all six principle variants from content", () => { + const sections = parsePrinciples(SAMPLE_PRINCIPLES); + + expect(sections.v1Coding).toContain("This is the coding principle body."); + expect(sections.v1Judging).toContain("This is the judging principle body."); + expect(sections.v1Analyzing).toContain("This is the analyzing principle body."); + expect(sections.v2).toContain("This is the simplicity principle body."); + expect(sections.v3).toContain("This is the surgical changes principle body."); + expect(sections.v4).toContain("This is the goal-driven principle body."); + }); + + test("v1Coding excludes Reviewer/Argus variant text", () => { + const sections = parsePrinciples(SAMPLE_PRINCIPLES); + expect(sections.v1Coding).not.toContain("Reviewer Variant"); + expect(sections.v1Coding).not.toContain("Argus Variant"); + }); + + test("returns empty strings for missing principles", () => { + const sections = parsePrinciples("## Principle 2: Only One\n\nJust this."); + // v1 variants should be empty, v3/v4 empty, but v2 present + expect(sections.v2).toContain("Just this."); + }); +}); + +describe("buildPrinciplesBlock", () => { + let sections: PrincipleSections; + + beforeAll(() => { + sections = parsePrinciples(SAMPLE_PRINCIPLES); + }); + + test("implementer gets v1Coding + v2 + v3 + v4", () => { + const block = buildPrinciplesBlock(sections, "implementer"); + expect(block).toContain("Think Before Coding"); + expect(block).toContain("Simplicity First"); + expect(block).toContain("Surgical Changes"); + expect(block).toContain("Goal-Driven Execution"); + expect(block).toContain("This is the coding principle body."); + expect(block).toContain("This is the simplicity principle body."); + expect(block).toContain("This is the surgical changes principle body."); + expect(block).toContain("This is the goal-driven principle body."); + // Should not contain judging/analyzing variants + expect(block).not.toContain("Think Before Judging"); + expect(block).not.toContain("Think Before Analyzing"); + }); + + test("reviewer gets v1Judging + v2 + v4 (NOT v3, NOT v1Coding)", () => { + const block = buildPrinciplesBlock(sections, "reviewer"); + expect(block).toContain("Think Before Judging"); + expect(block).toContain("Simplicity First"); + expect(block).toContain("Goal-Driven Execution"); + expect(block).not.toContain("Surgical Changes"); + expect(block).not.toContain("Think Before Coding"); + }); + + test("argus gets v1Analyzing + v2 + v4 (NOT v3)", () => { + const block = buildPrinciplesBlock(sections, "argus"); + expect(block).toContain("Think Before Analyzing"); + expect(block).toContain("Simplicity First"); + expect(block).toContain("Goal-Driven Execution"); + expect(block).not.toContain("Surgical Changes"); + expect(block).not.toContain("Think Before Coding"); + }); + + test("general gets same as implementer", () => { + const block = buildPrinciplesBlock(sections, "general"); + expect(block).toContain("Think Before Coding"); + expect(block).toContain("Simplicity First"); + expect(block).toContain("Surgical Changes"); + expect(block).toContain("Goal-Driven Execution"); + }); + + test("unknown agent returns empty string", () => { + const block = buildPrinciplesBlock(sections, "unknown-agent"); + expect(block).toBe(""); + }); + + test("principles header is at the start of the block", () => { + const block = buildPrinciplesBlock(sections, "implementer"); + expect(block.startsWith("# Andrej Karpathy's Coding Principles")).toBe(true); + }); +}); + +describe("readMarkdownConfigs", () => { + test("reads markdown files from a directory and extracts frontmatter + prompt", () => { + const tmp = makeTempDir(); + try { + writeMarkdown( + tmp, + "test-agent", + `--- +name: Test Agent +description: A test agent +--- + +This is the agent prompt content. +`, + ); + + const configs = readMarkdownConfigs(tmp); + expect(configs["test-agent"]).toBeDefined(); + expect(configs["test-agent"].name).toBe("Test Agent"); + expect(configs["test-agent"].description).toBe("A test agent"); + expect(configs["test-agent"].prompt).toBe("This is the agent prompt content."); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); + + test("returns empty object for non-existent directory", () => { + const configs = readMarkdownConfigs("/nonexistent/path/12345"); + expect(configs).toEqual({}); + }); + + test("ignores non-.md files in the directory", () => { + const tmp = makeTempDir(); + try { + writeMarkdown(tmp, "valid", "---\nname: Valid\n---\nContent."); + fs.writeFileSync(path.join(tmp, "readme.txt"), "not markdown", "utf8"); + + const configs = readMarkdownConfigs(tmp); + expect(Object.keys(configs)).toHaveLength(1); + expect(configs.valid).toBeDefined(); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); +}); + +describe("buildAgentConfigs", () => { + test("transforms FrontmatterEntry records to AgentConfig records", () => { + const raw = { + implementer: { name: "Implementer", description: "Builds things", prompt: "You are an implementer." }, + reviewer: { name: "Reviewer", description: "Reviews things", prompt: "You are a reviewer." }, + }; + + const configs = buildAgentConfigs(raw); + expect(configs.implementer).toBeDefined(); + expect(configs.implementer.prompt).toBe("You are an implementer."); + expect(configs.implementer.description).toBe("Builds things"); + expect(configs.reviewer).toBeDefined(); + expect(configs.reviewer.prompt).toBe("You are a reviewer."); + expect(configs.reviewer.description).toBe("Reviews things"); + }); +}); + +describe("buildCommandConfigs", () => { + test("transforms FrontmatterEntry records to CommandConfig records", () => { + const raw = { + autopilot: { name: "Autopilot", prompt: "Run the autopilot", arguments: { dir: "string" } }, + teach: { name: "Teach", prompt: "Teach a concept" }, + }; + + const configs = buildCommandConfigs(raw); + expect(configs.autopilot).toBeDefined(); + expect(configs.autopilot.template).toBe("Run the autopilot"); + expect(configs.autopilot.args).toEqual({ dir: "string" }); + expect(configs.teach).toBeDefined(); + expect(configs.teach.template).toBe("Teach a concept"); + expect(configs.teach.args).toBeUndefined(); + }); +}); + +describe("readSkillDirCommands", () => { + test("reads skill directories and extracts name + description from SKILL.md frontmatter", () => { + const tmp = makeTempDir(); + try { + writeSkillDir(tmp, "my-skill", "name: My Skill\ndescription: Does something useful"); + + const commands = readSkillDirCommands(tmp); + expect(commands["My Skill"]).toBeDefined(); + expect(commands["My Skill"].description).toBe("Does something useful"); + expect(commands["My Skill"].prompt).toContain("Load the 'My Skill' skill"); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); + + test("falls back to directory name when frontmatter name is missing", () => { + const tmp = makeTempDir(); + try { + writeSkillDir(tmp, "fallback-skill", "description: A fallback skill"); + + const commands = readSkillDirCommands(tmp); + expect(commands["fallback-skill"]).toBeDefined(); + expect(commands["fallback-skill"].description).toBe("A fallback skill"); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); + + test("ignores directories without a SKILL.md file", () => { + const tmp = makeTempDir(); + try { + // Create empty dir — no SKILL.md + fs.mkdirSync(path.join(tmp, "empty-dir"), { recursive: true }); + // Create a valid skill dir + writeSkillDir(tmp, "has-skill", "name: Has Skill"); + + const commands = readSkillDirCommands(tmp); + expect(Object.keys(commands)).toHaveLength(1); + expect(commands["Has Skill"]).toBeDefined(); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); +}); + +describe("getPackageRoot", () => { + test("returns an absolute path ending with the package name", () => { + const root = getPackageRoot(); + expect(root).toBeDefined(); + expect(path.isAbsolute(root)).toBe(true); + expect(root.endsWith("core")).toBe(true); + }); +}); diff --git a/packages/core/src/shared.ts b/packages/core/src/shared.ts new file mode 100644 index 0000000..5c8a6ab --- /dev/null +++ b/packages/core/src/shared.ts @@ -0,0 +1,167 @@ +import fs from "node:fs"; +import path from "node:path"; +import matter from "gray-matter"; + +// ── Types ───────────────────────────────────────────────────────── + +export interface FrontmatterEntry { + prompt: string; + [key: string]: unknown; +} + +export interface AgentConfig { + prompt: string; + [key: string]: unknown; +} + +export interface CommandConfig { + template: string; + args?: unknown; + [key: string]: unknown; +} + +// ── Karpathy Principles ─────────────────────────────────────────── + +export interface PrincipleSections { + v1Coding: string; + v1Judging: string; + v1Analyzing: string; + v2: string; + v3: string; + v4: string; +} + +export function parsePrinciples(content: string): PrincipleSections { + const sections: Record = {}; + const parts = content.split(/(?=^## Principle)/m); + for (const part of parts) { + const headerMatch = part.match(/^## Principle\s+(\d).*?\n/); + if (!headerMatch) continue; + const num = headerMatch[1]; + const body = part.slice(headerMatch[0].length).trim(); + + if (num === "1") { + if (part.includes("Reviewer Variant")) { + sections.v1Judging = body; + } else if (part.includes("Argus Variant")) { + sections.v1Analyzing = body; + } else { + sections.v1Coding = body; + } + } else { + sections[`v${num}`] = body; + } + } + return sections as unknown as PrincipleSections; +} + +export const AGENT_PRINCIPLE_MAP: Record = { + implementer: ["v1Coding", "v2", "v3", "v4"], + general: ["v1Coding", "v2", "v3", "v4"], + reviewer: ["v1Judging", "v2", "v4"], + argus: ["v1Analyzing", "v2", "v4"], +}; + +export const HEADER_TEMPLATES: Record = { + v1Coding: "## Principle 1: Think Before Coding", + v1Judging: "## Principle 1: Think Before Judging", + v1Analyzing: "## Principle 1: Think Before Analyzing", + v2: "## Principle 2: Simplicity First", + v3: "## Principle 3: Surgical Changes", + v4: "## Principle 4: Goal-Driven Execution", +}; + +export function buildPrinciplesBlock(sections: PrincipleSections, agentName: string): string { + const keys = AGENT_PRINCIPLE_MAP[agentName]; + if (!keys || keys.length === 0) return ""; + + const blocks = keys.map((key) => { + const header = HEADER_TEMPLATES[key]; + const body = sections[key] ?? ""; + return `${header}\n\n${body}`; + }); + return `# Andrej Karpathy's Coding Principles\n\n${blocks.join("\n\n")}\n\n---\n\n`; +} + +// ── Content Loading ─────────────────────────────────────────────── + +export function readMarkdownConfigs(dirPath: string): Record { + const result: Record = {}; + if (!fs.existsSync(dirPath)) return result; + + const entries = fs.readdirSync(dirPath, { withFileTypes: true }); + for (const entry of entries) { + if (!entry.isFile() || !entry.name.endsWith(".md")) continue; + + const filePath = path.join(dirPath, entry.name); + const raw = fs.readFileSync(filePath, "utf8"); + const { data: frontmatter, content } = matter(raw); + const key = entry.name.replace(/\.md$/, ""); + + result[key] = { ...frontmatter, prompt: content.trim() }; + } + return result; +} + +export function buildAgentConfigs(raw: Record): Record { + const configs: Record = {}; + for (const [name, def] of Object.entries(raw)) { + const { prompt, ...rest } = def; + configs[name] = { ...rest, prompt }; + } + return configs; +} + +export function buildCommandConfigs(raw: Record): Record { + const configs: Record = {}; + for (const [name, def] of Object.entries(raw)) { + const { prompt, arguments: args, ...rest } = def; + const cmd: CommandConfig = { ...rest, template: prompt }; + if (args) cmd.args = args; + configs[name] = cmd; + } + return configs; +} + +export function readSkillDirCommands(dirPath: string): Record { + const result: Record = {}; + if (!fs.existsSync(dirPath)) return result; + + const entries = fs.readdirSync(dirPath, { withFileTypes: true }); + for (const entry of entries) { + if (!entry.isDirectory()) continue; + const skillFile = path.join(dirPath, entry.name, "SKILL.md"); + if (!fs.existsSync(skillFile)) continue; + + const raw = fs.readFileSync(skillFile, "utf8"); + const { data } = matter(raw); + const name = data.name || entry.name; + const description = data.description || ""; + const template = `Load the '${name}' skill and follow its instructions.`; + + result[name] = { description, prompt: template }; + } + return result; +} + +/** Returns the absolute path to the package root directory. */ +export function getPackageRoot(): string { + return path.resolve(path.dirname(new URL(import.meta.url).pathname), ".."); +} + +// ── Asset Paths ───────────────────────────────────────────────── + +/** Returns the directory containing agent .md files. */ +export function getAgentsDir(): string { + return path.resolve(getPackageRoot(), "agents"); +} + +/** Returns the directory containing Karpathy principles. */ +export function getPrinciplesDir(): string { + return path.resolve(getPackageRoot(), "principles"); +} + +/** Returns the core package root directory. Alias for getPackageRoot. */ +export function getCoreDir(): string { + return getPackageRoot(); +} diff --git a/packages/core/templates/AGENTS.md b/packages/core/templates/AGENTS.md new file mode 100644 index 0000000..1ebbc77 --- /dev/null +++ b/packages/core/templates/AGENTS.md @@ -0,0 +1,44 @@ +# Autopilot Toolkit — Karpathy Coding Principles + +# Andrej Karpathy's Coding Principles + +## Principle 1: Think Before Coding + +Before writing a single line of code, think through the problem thoroughly. Understand the requirements, design the approach, and consider edge cases. Most coding time should be spent thinking, not typing. A clear mental model prevents rework and produces cleaner solutions. + +Ask yourself: +- What exactly am I trying to accomplish? +- What are the constraints and edge cases? +- What is the simplest approach that could work? +- How will I verify correctness? + +## Principle 2: Simplicity First + +Always reach for the simplest solution first. Simple code is easier to understand, debug, test, and extend. Resist the urge to build elaborate abstractions or optimize prematurely. Complexity should be earned — only introduce it when the simple solution demonstrably falls short. + +Guidelines: +- Write code a junior engineer can understand +- Avoid premature abstraction and optimization +- Delete code whenever possible — less code is better code +- Favor boring, proven patterns over clever, novel ones + +## Principle 3: Surgical Changes + +Make the smallest possible change to achieve the goal. Each change should do exactly one thing, and do it well. Do not refactor unrelated code, fix unrelated bugs, or add "while I'm here" improvements. Precise, minimal changes reduce risk and make review straightforward. + +Guidelines: +- One logical change per commit/PR +- Don't mix refactoring with feature work +- Leave the codebase cleaner than you found it — but only in the area you're touching +- If you see something broken that's out of scope, file an issue, don't fix it inline + +## Principle 4: Goal-Driven Execution + +Stay relentlessly focused on the goal. Do not chase shiny objects, explore interesting tangents, or get sidetracked by adjacent improvements. Every action should trace back to the acceptance criteria. If it's not required to meet the goal, it's a distraction. + +Guidelines: +- Before every action, ask: "Does this directly advance the goal?" +- Track progress against acceptance criteria, not against interesting side quests +- Timebox exploration — if you need to research, set a limit and return to the goal +- Ship the minimum viable implementation, then iterate + diff --git a/packages/core/templates/autopilot/build-autopilot.test.ts b/packages/core/templates/autopilot/build-autopilot.test.ts new file mode 100644 index 0000000..8986236 --- /dev/null +++ b/packages/core/templates/autopilot/build-autopilot.test.ts @@ -0,0 +1,161 @@ +import { afterAll, beforeAll, describe, expect, it } from "bun:test"; +import { join } from "node:path"; +import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs"; + +const TEMPLATES_DIR = import.meta.dir; +const MANIFEST_PATH = join(TEMPLATES_DIR, "manifest.json"); +const PROJECT_ROOT = join(import.meta.dir, "..", "..", "..", ".."); +const OPENCODE_OUT = join(PROJECT_ROOT, "packages", "opencode", "commands", "autopilot.md"); +const CODEX_OUT = join(PROJECT_ROOT, "packages", "codex", "skills", "autopilot", "SKILL.md"); +const GOLDEN_DIR = join(TEMPLATES_DIR, "__golden__"); + +// Ensure output directories exist +function ensureDir(p: string) { + if (!existsSync(p)) mkdirSync(p, { recursive: true }); +} + +beforeAll(() => { + ensureDir(join(OPENCODE_OUT, "..")); + ensureDir(join(CODEX_OUT, "..")); + ensureDir(GOLDEN_DIR); +}); + +describe("build-autopilot", () => { + it("should successfully build opencode output from manifest", async () => { + // Run the build + const proc = Bun.spawnSync(["bun", "run", "build:templates"], { cwd: PROJECT_ROOT }); + expect(proc.exitCode).toBe(0); + + // Output files should exist + expect(existsSync(OPENCODE_OUT)).toBe(true); + expect(existsSync(CODEX_OUT)).toBe(true); + + // Output files should be non-empty + const opencodeContent = readFileSync(OPENCODE_OUT, "utf-8"); + const codexContent = readFileSync(CODEX_OUT, "utf-8"); + expect(opencodeContent.length).toBeGreaterThan(1000); + expect(codexContent.length).toBeGreaterThan(1000); + }); + + it("should produce output containing key autopilot sections", () => { + const opencodeContent = readFileSync(OPENCODE_OUT, "utf-8"); + const codexContent = readFileSync(CODEX_OUT, "utf-8"); + + // Both should contain the Phase 1 dispatch loop concept + expect(opencodeContent).toContain("Phase 1"); + expect(codexContent).toContain("Phase 1"); + + // Both should contain implementer dispatch template + expect(opencodeContent).toContain("Implementer Dispatch Template"); + expect(codexContent).toContain("Implementer Dispatch Template"); + + // Both should contain reviewer dispatch template + expect(opencodeContent).toContain("Reviewer Dispatch Template"); + expect(codexContent).toContain("Reviewer Dispatch Template"); + + // Both should contain meta-reviewer template + expect(opencodeContent).toContain("Meta-Reviewer Template"); + expect(codexContent).toContain("Meta-Reviewer Template"); + }); + + it("should have platform-specific tool syntax in correct files", () => { + const opencodeContent = readFileSync(OPENCODE_OUT, "utf-8"); + const codexContent = readFileSync(CODEX_OUT, "utf-8"); + + // OpenCode-specific: uses "task" tool and "subagent_type" + expect(opencodeContent).toContain("subagent_type"); + + // Codex-specific: uses "spawn_agent" and "exec_command" + expect(codexContent).toContain("spawn_agent"); + expect(codexContent).toContain("mcp__github__"); + + // Neither should mix platform tools + // OpenCode should NOT contain Codex-specific tools + expect(opencodeContent).not.toContain("spawn_agent"); + expect(opencodeContent).not.toContain("mcp__github__"); + + // Codex should NOT contain OpenCode-specific tools + expect(codexContent).not.toContain("subagent_type"); + }); + + it("should have non-empty frontmatter in both outputs", () => { + const opencodeContent = readFileSync(OPENCODE_OUT, "utf-8"); + const codexContent = readFileSync(CODEX_OUT, "utf-8"); + + // Both should start with frontmatter + expect(opencodeContent.startsWith("---")).toBe(true); + expect(codexContent.startsWith("---")).toBe(true); + }); + + it("should include cross-issue suggestion matching logic", () => { + const opencodeContent = readFileSync(OPENCODE_OUT, "utf-8"); + const codexContent = readFileSync(CODEX_OUT, "utf-8"); + + expect(opencodeContent).toContain("CROSS_ISSUE_SUGGESTIONS"); + expect(codexContent).toContain("CROSS_ISSUE_SUGGESTIONS"); + }); +}); + +describe("build-autopilot error handling", () => { + it("should report error if manifest.json is missing", async () => { + // Temporarily rename manifest + const bakPath = MANIFEST_PATH + ".bak"; + if (existsSync(MANIFEST_PATH)) { + writeFileSync(bakPath, readFileSync(MANIFEST_PATH)); + rmSync(MANIFEST_PATH); + } + + const proc = Bun.spawnSync(["bun", "run", "build:templates"], { cwd: PROJECT_ROOT }); + // Should fail (non-zero exit or specific error output) + const stderr = new TextDecoder().decode(proc.stderr); + const stdout = new TextDecoder().decode(proc.stdout); + const combined = stderr + stdout; + expect(combined.includes("manifest") || proc.exitCode !== 0).toBe(true); + + // Restore + if (existsSync(bakPath)) { + writeFileSync(MANIFEST_PATH, readFileSync(bakPath)); + rmSync(bakPath); + } + }); +}); + +describe("golden file tests", () => { + function saveGolden(platform: string, content: string) { + writeFileSync(join(GOLDEN_DIR, `${platform}.md`), content, "utf-8"); + } + + function readGolden(platform: string): string | null { + const p = join(GOLDEN_DIR, `${platform}.md`); + if (!existsSync(p)) return null; + return readFileSync(p, "utf-8"); + } + + it("should match golden file for opencode output", () => { + const opencodeContent = readFileSync(OPENCODE_OUT, "utf-8"); + const golden = readGolden("opencode"); + + if (golden === null) { + // First run — save golden file + saveGolden("opencode", opencodeContent); + console.log("Golden file for opencode saved (first run)"); + } else { + // Compare byte-for-byte + expect(opencodeContent).toBe(golden); + } + }); + + it("should match golden file for codex output", () => { + const codexContent = readFileSync(CODEX_OUT, "utf-8"); + const golden = readGolden("codex"); + + if (golden === null) { + // First run — save golden file + saveGolden("codex", codexContent); + console.log("Golden file for codex saved (first run)"); + } else { + // Compare byte-for-byte + expect(codexContent).toBe(golden); + } + }); +}); diff --git a/packages/core/templates/autopilot/codex/01-frontmatter.md b/packages/core/templates/autopilot/codex/01-frontmatter.md new file mode 100644 index 0000000..f3d9f55 --- /dev/null +++ b/packages/core/templates/autopilot/codex/01-frontmatter.md @@ -0,0 +1,4 @@ +--- +name: autopilot +description: Put issue resolution on autopilot — scans GitHub Issues and local .scratch/ files for ready-for-agent issues, dispatches implementer → reviewer subagents in a retry loop. After issues complete, runs global meta-review. Use when processing autopilot issues from any source. +--- diff --git a/packages/core/templates/autopilot/codex/02-header.md b/packages/core/templates/autopilot/codex/02-header.md new file mode 100644 index 0000000..4b951e8 --- /dev/null +++ b/packages/core/templates/autopilot/codex/02-header.md @@ -0,0 +1,4 @@ + +# Autopilot (Codex Edition) + +Execute the autopilot orchestrator workflow using Codex subagent dispatch. diff --git a/packages/core/templates/autopilot/codex/03-toolchain.md b/packages/core/templates/autopilot/codex/03-toolchain.md new file mode 100644 index 0000000..05f7942 --- /dev/null +++ b/packages/core/templates/autopilot/codex/03-toolchain.md @@ -0,0 +1,13 @@ + +## Toolchain + +You have: +- `spawn_agent(agent_type, items, message)` — dispatch subagent. Agent types: `implementer`, `reviewer`, `argus`, `default`, `worker`. +- `wait_agent(targets, timeout_ms)` — wait for subagent completion. Returns completed status with agent's final message. +- `send_input(target, message, interrupt)` — send follow-up message to existing subagent. Set `interrupt=true` to preempt current task. +- `close_agent(target)` — close a completed subagent to free concurrency slots. +- `exec_command` — shell commands (`gh`, `rg`, `bun test`, etc.) +- `apply_patch` — file edits +- GitHub MCP tools (`mcp__github__get_issue`, `mcp__github__update_issue`, `mcp__github__add_issue_comment`, `mcp__github__list_issues`) — issue management + +Skills passed to subagents via `items`: `skills/tdd/`, `skills/diagnose/`, `skills/zoom-out/`. diff --git a/packages/core/templates/autopilot/codex/04-targets-cdx.md b/packages/core/templates/autopilot/codex/04-targets-cdx.md new file mode 100644 index 0000000..2350626 --- /dev/null +++ b/packages/core/templates/autopilot/codex/04-targets-cdx.md @@ -0,0 +1,46 @@ +## Issue Sources + +| Source | Detection | State | Contract | +|--------|-----------|-------|----------| +| GitHub Issue | `#N` or scan label `ready-for-agent` | Labels: `in-progress`, `resolved`, `needs-info` | Issue body (What to build + Acceptance criteria) | +| Local .scratch/ | `.scratch/*/issues/*/issue.md` with `Status: ready-for-agent` | Frontmatter `Status:` | `/AGENT-BRIEF.md` + +### GitHub label ↔ local Status mapping + +| Label | Frontmatter Status | Meaning | +|-------|--------------------|---------| +| `ready-for-agent` | `ready-for-agent` | Ready for autopilot | +| `in-progress` | `in-progress` | Currently being processed | +| `resolved` | `resolved` | Implemented + reviewed, done | +| `needs-info` | `needs-info` | Blocked, needs human input | + +--- + +## Phase 1: Dispatch Loop + +Process issues one at a time. Max 3 rounds per issue (retry_count = 0, 1, 2). + +### 0. Parse targets + +If the user passed specific targets (e.g., `#43 ~ #46` or `.scratch/auth/issues/01-login`): +- Parse GitHub issue numbers or local paths +- For GitHub: fetch each issue via `mcp__github__get_issue`, check labels include `ready-for-agent` or `in-progress` +- For local: read `issue.md`, check `Status:` frontmatter + +If no targets passed, scan both sources: +- GitHub: `mcp__github__list_issues(labels=["ready-for-agent"], state="open")` +- Local: `exec_command("rg -l 'Status: ready-for-agent' .scratch/*/issues/*/issue.md")` +- Process first match, then loop + +### 1. Initialize issue + +**GitHub**: Update label to `in-progress` via `mcp__github__update_issue`. Add comment: `autopilot: 开始处理 #N (Round 0)`. +**Local**: Edit issue.md `Status:` to `in-progress`. Append timestamp comment to `## Comments`. + +### 2. Toolchain check + +Run `which bun` (or project-appropriate tool). Set `TOOLCHAIN: available` or `TOOLCHAIN: unavailable`. + +### 3. Detect SIBLING_CONTEXT (optional) + +If the issue references a parent PRD, scan sibling resolved issues for cross-issue context. Assemble as `SIBLING_CONTEXT` string. diff --git a/packages/core/templates/autopilot/codex/05-dispatch-impl.md b/packages/core/templates/autopilot/codex/05-dispatch-impl.md new file mode 100644 index 0000000..1c3455e --- /dev/null +++ b/packages/core/templates/autopilot/codex/05-dispatch-impl.md @@ -0,0 +1,31 @@ +### 4. Dispatch implementer + +Use `spawn_agent`: + +``` +agent_type: "implementer" +items: [ + {type:"skill", path:"skills/tdd/"}, + {type:"skill", path:"skills/diagnose/"}, + {type:"skill", path:"skills/zoom-out/"} +] +message: +``` + +See [IMPLEMENTER_DISPATCH_TEMPLATE](#implementer-dispatch-template) below for the exact message format. + +### 5. Wait for implementer + +```javascript +wait_agent(targets=[impl_agent_id], timeout_ms=600000) +``` + +Parse the completed status message for `IMPLEMENTER_REPORT:`. + +If no report found (empty reply or parse error): retry once (new spawn). If still no report: mark `needs-info`, stop. + +### 6. Process implementer result + +**STATUS: DONE** → Dispatch reviewer (step 7). +**STATUS: UNVERIFIED** → Dispatch reviewer with `UNVERIFIED: true` flag. +**STATUS: BLOCKED or NEEDS_CONTEXT** → Mark `needs-info`, add comment, stop. diff --git a/packages/core/templates/autopilot/codex/06-commit.md b/packages/core/templates/autopilot/codex/06-commit.md new file mode 100644 index 0000000..0cd0a8b --- /dev/null +++ b/packages/core/templates/autopilot/codex/06-commit.md @@ -0,0 +1,28 @@ +### 6b. Commit changes + +After implementer STATUS: DONE, commit to isolate this issue's changes: + +This gives reviewer a clean diff boundary via `git show HEAD`. + +### 7. Dispatch reviewer + +Use `spawn_agent` (new agent per issue): + +``` +agent_type: "reviewer" +items: [ + {type:"skill", path:"skills/tdd/"}, + {type:"text", text: } +] +message: +``` + +See [REVIEWER_DISPATCH_TEMPLATE](#reviewer-dispatch-template) below. + +### 8. Wait for reviewer + +```javascript +wait_agent(targets=[rev_agent_id], timeout_ms=600000) +``` + +Parse for `REVIEWER_REPORT:` and `VERDICT: MERGE | RETRY | BLOCKED | VERIFY_NEEDED`. diff --git a/packages/core/templates/autopilot/codex/07-verdict-cdx.md b/packages/core/templates/autopilot/codex/07-verdict-cdx.md new file mode 100644 index 0000000..66c4e9a --- /dev/null +++ b/packages/core/templates/autopilot/codex/07-verdict-cdx.md @@ -0,0 +1,31 @@ +### 9. Handle verdict + +**MERGE** → Mark `resolved`. Close reviewer agent. Go to next issue. +**VERIFY_NEEDED** → Try running build/tests. If pass → `resolved`. If fail → `needs-info`. +**RETRY** → increment retry_count. + - retry_count < 3: `send_input(interrupt=true)` with `PREV_REVIEW` to existing implementer. If agent is closed, spawn new implementer. + - retry_count >= 3: mark `needs-info`, add review summary, go to next issue. +**BLOCKED** → Mark `needs-info`, go to next issue. + +After verdict handled, close agents to free concurrency slots: +```javascript +close_agent(target=impl_agent_id) +close_agent(target=rev_agent_id) +``` + +### 9b. Git cleanup (retry case) + +If RETRY occurred, undo the stale commit before next implementer round: +```bash +git reset --soft HEAD~1 +``` + +### 10. Handle suggestions (cross-issue) + +If reviewer report has `## Suggestion` items: +- **Local mode**: Write to `.scratch//suggestions.json` +- **GitHub mode**: Add issue comment: `autopilot suggestion [pending]: ` AND write to local file if feature directory exists + +### 11. Loop + +Return to step 0 (scan for next ready-for-agent issue). When no more issues → Phase 2. diff --git a/packages/core/templates/autopilot/codex/08-phase2-cdx.md b/packages/core/templates/autopilot/codex/08-phase2-cdx.md new file mode 100644 index 0000000..f5fa992 --- /dev/null +++ b/packages/core/templates/autopilot/codex/08-phase2-cdx.md @@ -0,0 +1,25 @@ +## Phase 2: Global Meta-Review + +### 1. Parallel dispatch + +**A) Spawn reviewer** (same as Phase 1 step 7, but with meta-review scope): + +``` +agent_type: "reviewer" +items: [{type:"skill", path:"skills/tdd/"}] +message: +``` + +**B) Orchestrator self-review** (run concurrently): +- Scan for cross-module inconsistencies: `rg` for import styles, entry detection patterns +- Check for orphan files: `git diff --stat` against parent branch +- Verify build passes: run build command +- Check test coverage: run test suite + +### 2. Merge reports + +Union of Critical + Important items from both reports. Default to stricter finding on conflicts. + +### 3. Fix loop (max 2 rounds) + +Fix merged Critical + Important items directly (no subagent dispatch for meta fixes — these are mechanical). Verify with build + tests. diff --git a/packages/core/templates/autopilot/manifest.json b/packages/core/templates/autopilot/manifest.json new file mode 100644 index 0000000..fd75b8b --- /dev/null +++ b/packages/core/templates/autopilot/manifest.json @@ -0,0 +1,47 @@ +{ + "opencode": [ + "opencode/01-frontmatter.md", + "opencode/02-exec-instruct.md", + "shared/00-preamble.md", + "shared/01-issue-sources.md", + "opencode/03-preface-op.md", + "shared/02-common-concepts.md", + "opencode/04-target-local.md", + "shared/03-phase1-overview.md", + "opencode/05-state-updates.md", + "shared/04-cross-issue-suggestions.md", + "shared/05-implementer-preflight.md", + "opencode/06-dispatch-impl.md", + "shared/06-self-review.md", + "opencode/07-sibling-context.md", + "shared/07-handle-implementer.md", + "opencode/08-dispatch-rev.md", + "shared/08-handle-reviewer.md", + "shared/09-suggestion-state.md", + "shared/10-phase2-meta.md", + "opencode/09-dispatch-meta.md", + "shared/11-final-acceptance-report.md", + "shared/12-template-implementer.md", + "shared/13-template-reviewer.md", + "shared/14-template-meta-reviewer.md" + ], + "codex": [ + "codex/01-frontmatter.md", + "codex/02-header.md", + "codex/03-toolchain.md", + "codex/04-targets-cdx.md", + "shared/03-phase1-overview.md", + "shared/04-cross-issue-suggestions.md", + "shared/05-implementer-preflight.md", + "codex/05-dispatch-impl.md", + "codex/06-commit.md", + "shared/07-handle-implementer.md", + "shared/08-handle-reviewer.md", + "codex/07-verdict-cdx.md", + "shared/09-suggestion-state.md", + "codex/08-phase2-cdx.md", + "shared/12-template-implementer.md", + "shared/13-template-reviewer.md", + "shared/14-template-meta-reviewer.md" + ] +} diff --git a/packages/core/templates/autopilot/opencode/01-frontmatter.md b/packages/core/templates/autopilot/opencode/01-frontmatter.md new file mode 100644 index 0000000..4be6962 --- /dev/null +++ b/packages/core/templates/autopilot/opencode/01-frontmatter.md @@ -0,0 +1,4 @@ +--- +description: Put issue resolution on autopilot — scans local .scratch/ files AND GitHub Issues for ready-for-agent issues, dispatches implementer → reviewer in a retry loop until resolved. After all issues complete, runs global meta-review against ADR/PRD and fixes cross-module issues. Use when processing autopilot issues from any source. +arguments: [{ name: "target", description: "Optional: a .scratch//issues/ directory path, or a GitHub issue number (#N or N). If omitted, scan all sources.", required: false }] +--- diff --git a/packages/core/templates/autopilot/opencode/02-exec-instruct.md b/packages/core/templates/autopilot/opencode/02-exec-instruct.md new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/packages/core/templates/autopilot/opencode/02-exec-instruct.md @@ -0,0 +1 @@ + diff --git a/packages/core/templates/autopilot/opencode/03-preface-op.md b/packages/core/templates/autopilot/opencode/03-preface-op.md new file mode 100644 index 0000000..9fa96c0 --- /dev/null +++ b/packages/core/templates/autopilot/opencode/03-preface-op.md @@ -0,0 +1,17 @@ +## 前置约定 + +### 本地 issue 模式 + +- `target` 使用绝对路径。如传入相对路径，拼接当前工作目录。 +- `issue.md` 以 YAML frontmatter 开头，`Status` 字段在 frontmatter 中。 +- 更新 Status：用 `edit` 工具修改 frontmatter 中的 `Status:` 行。 +- 追加注释：在 `## Comments` 节末尾加 `- <时间戳> autopilot: <内容>`。无该节则在文件末尾创建。 +- 合约文件：同目录下 `AGENT-BRIEF.md`。 + +### GitHub Issue 模式 + +- 使用 `gh` CLI 操作 issue。从 `git remote -v` 自动推断 repo。 +- 状态通过 labels 表达：`in-progress`、`resolved`、`needs-info`。 +- 追加注释用 `gh issue comment --body "..."`。 +- 合约来自 issue body（其中包含 Acceptance Criteria 和 What to build，由 `to-issues` 创建）。 +- 读取 issue：`gh issue view --json number,title,body,labels,state`。 diff --git a/packages/core/templates/autopilot/opencode/04-target-local.md b/packages/core/templates/autopilot/opencode/04-target-local.md new file mode 100644 index 0000000..3593dee --- /dev/null +++ b/packages/core/templates/autopilot/opencode/04-target-local.md @@ -0,0 +1,53 @@ +--- + +## 如果指定了 target + +### target 是路径（含 `/`） + +1. 确认 `/issue.md` 存在，不存在则报告错误并停止 +2. 确认 `/AGENT-BRIEF.md` 存在，不存在则报告错误并停止 +3. 读取 `/issue.md`，检查 `Status:` 是否为 `ready-for-agent` 或 `in-progress` +4. 非以上状态 → 回复当前状态并停止 +5. 更新 Status 为 `in-progress` +6. 设置 `source = "local"`, `id = ` +7. 从 `` 推断 feature 目录（取 issue 目录的父级父级，如 `.scratch/auth/issues/01-login/` → `.scratch/auth/`） +8. 设置 `contract = /AGENT-BRIEF.md` 的内容作为合约文本 +9. 跳到"交叉 Issue Suggestion 匹配" + +### target 是 GitHub issue 号（`#N` 或纯数字 `N`） + +提取数字部分为 `issueNumber`： + +1. `gh issue view --json number,title,body,labels,state` 获取 issue 信息 +2. 检查 labels 是否含 `ready-for-agent` 或 `in-progress` +3. 非以上标签 → 回复当前状态并停止 +4. 将 `ready-for-agent` 标签替换为 `in-progress`：`gh issue edit --add-label "in-progress" --remove-label "ready-for-agent"` +5. 追加评论：`gh issue comment --body "autopilot: 开始处理"` +6. 从 issue body 提取 Acceptance Criteria 和 What to build 作为合约文本 +7. 设置 `source = "github"`, `id = `, `contract = <解析出的合约文本>` +8. 从 issue title 生成 feature slug（如 `Implement Suggestion matching` → `suggestion-matching` → `.scratch/suggestion-matching/`） +9. 跳到"交叉 Issue Suggestion 匹配" + +--- + +## 否则（无参数）：扫描模式 + +同时扫描两个来源： + +### 本地扫描 + +1. Glob 扫描 `.scratch/*/issues/*.md` +2. 对每个文件，读取前 30 行，检查是否有 `Status: ready-for-agent` +3. 收集所有匹配项 + +### GitHub 扫描 + +4. `gh issue list --label "ready-for-agent" --state open --json number,title --limit 50` +5. 收集所有匹配项 + +### 选择并报告 + +6. 合并两个来源的结果。向用户列出所有找到的 issue +7. 选择第一个（按先本地后 GitHub，各自内部按自然序），标注正在处理哪个 +8. 如果零个 → 跳到"Phase 2: 全局 meta-review" +9. 根据选中 issue 的来源，走对应的初始化流程 diff --git a/packages/core/templates/autopilot/opencode/05-state-updates.md b/packages/core/templates/autopilot/opencode/05-state-updates.md new file mode 100644 index 0000000..5df5acc --- /dev/null +++ b/packages/core/templates/autopilot/opencode/05-state-updates.md @@ -0,0 +1,9 @@ +### 更新状态（抽象） + +- **local**: `edit` 工具修改 `issue.md` 的 `Status:` 行 +- **github**: `gh issue edit --add-label "<新>" --remove-label "<旧>"` + +### 追加注释（抽象） + +- **local**: 在 `issue.md` 的 `## Comments` 节末尾添加条目 +- **github**: `gh issue comment --body "<时间戳> autopilot: <内容>"` diff --git a/packages/core/templates/autopilot/opencode/06-dispatch-impl.md b/packages/core/templates/autopilot/opencode/06-dispatch-impl.md new file mode 100644 index 0000000..77c6ea6 --- /dev/null +++ b/packages/core/templates/autopilot/opencode/06-dispatch-impl.md @@ -0,0 +1,10 @@ +用 `task` 工具 dispatch `implementer` agent（`subagent_type: "implementer"`）。**prompt 必须以 skill 加载指令开头（强制，不可省略）**： + +``` +**在开始任何操作之前，必须使用 `skill` 工具加载以下技能：** +1. `skill(name: "tdd")` — TDD 方法论（红绿重构循环、测试质量标准、mock 纪律） +2. `skill(name: "diagnose")` — 系统性诊断流程（遇到意外错误时使用） +3. `skill(name: "zoom-out")` — 不熟悉代码区域时上探抽象层次 + +**这是强制步骤，不可跳过。** 未加载技能前不得执行任何其他操作。 +``` diff --git a/packages/core/templates/autopilot/opencode/07-sibling-context.md b/packages/core/templates/autopilot/opencode/07-sibling-context.md new file mode 100644 index 0000000..fd7d02a --- /dev/null +++ b/packages/core/templates/autopilot/opencode/07-sibling-context.md @@ -0,0 +1,8 @@ +### 收集 SIBLING_CONTEXT + +dispatch reviewer 前，自动收集当前 issue 所属 PRD 下所有已 resolved 的兄弟模块信息： + +1. 从当前 issue body 的 `Parent` 链接提取 PRD issue 号 +2. `gh issue list --label "resolved" --json number,title` 获取所有已 resolve 的 issue +3. 对于每个已 resolve 的 issue（排除当前 issue 自己），提取其 title 和关键约定（入口模式、测试框架、文件布局） +4. 组装为 `SIBLING_CONTEXT` 字符串，包含："已完成的兄弟模块: #N title — 关键约定: ..." diff --git a/packages/core/templates/autopilot/opencode/08-dispatch-rev.md b/packages/core/templates/autopilot/opencode/08-dispatch-rev.md new file mode 100644 index 0000000..d3f79ff --- /dev/null +++ b/packages/core/templates/autopilot/opencode/08-dispatch-rev.md @@ -0,0 +1,12 @@ +用 `task` 工具 dispatch `reviewer` agent（`subagent_type: "reviewer"`）。**prompt 必须以 skill 加载指令开头（强制，不可省略）**： + +``` +**在开始任何操作之前，必须使用 `skill` 工具加载以下技能：** +1. `skill(name: "tdd")` — 测试质量标准和 mock 纪律（用于 TDD 审查维度） + +**这是强制步骤，不可跳过。** 未加载技能前不得执行任何其他操作。 + +--- + +<以下为任务描述> +``` diff --git a/packages/core/templates/autopilot/opencode/09-dispatch-meta.md b/packages/core/templates/autopilot/opencode/09-dispatch-meta.md new file mode 100644 index 0000000..b834bab --- /dev/null +++ b/packages/core/templates/autopilot/opencode/09-dispatch-meta.md @@ -0,0 +1 @@ +用 `task` 工具 dispatch `reviewer` agent（`subagent_type: "reviewer"`，只读，无 edit/bash 权限）。**prompt 必须以 skill 加载指令开头（强制，不可省略）**： diff --git a/packages/core/templates/autopilot/shared/00-preamble.md b/packages/core/templates/autopilot/shared/00-preamble.md new file mode 100644 index 0000000..dec0540 --- /dev/null +++ b/packages/core/templates/autopilot/shared/00-preamble.md @@ -0,0 +1 @@ +Execute the autopilot orchestrator workflow below. **Orchestrator MUST include explicit skill loading instructions in implementer and reviewer dispatch prompts** — see the implementer dispatch and reviewer dispatch sections for the exact preamble format. diff --git a/packages/core/templates/autopilot/shared/01-issue-sources.md b/packages/core/templates/autopilot/shared/01-issue-sources.md new file mode 100644 index 0000000..48dc76e --- /dev/null +++ b/packages/core/templates/autopilot/shared/01-issue-sources.md @@ -0,0 +1,10 @@ +## Issue 来源识别 + +autopilot 支持两种 issue 来源。根据 `target` 参数或扫描结果判断： + +| target 特征 | 来源 | 状态机 | 合约文件 | +|---|---|---|---| +| 包含 `/` 的路径 | 本地 `.scratch/` | frontmatter `Status:` | `AGENT-BRIEF.md` | +| `#N` 或纯数字 `N` | GitHub Issue | labels | issue body（含 AC） | +| 无参数扫描到本地 | 本地 `.scratch/` | frontmatter `Status:` | `AGENT-BRIEF.md` | +| 无参数扫描到 GitHub | GitHub Issue | labels | issue body | diff --git a/packages/core/templates/autopilot/shared/02-common-concepts.md b/packages/core/templates/autopilot/shared/02-common-concepts.md new file mode 100644 index 0000000..2141188 --- /dev/null +++ b/packages/core/templates/autopilot/shared/02-common-concepts.md @@ -0,0 +1,6 @@ +### 共用概念 + +- `Status: ready-for-agent`（本地 frontmatter）↔ label `ready-for-agent`（GitHub） +- `Status: in-progress` ↔ label `in-progress` +- `Status: resolved` ↔ label `resolved` +- `Status: needs-info` ↔ label `needs-info` diff --git a/packages/core/templates/autopilot/shared/03-phase1-overview.md b/packages/core/templates/autopilot/shared/03-phase1-overview.md new file mode 100644 index 0000000..095802a --- /dev/null +++ b/packages/core/templates/autopilot/shared/03-phase1-overview.md @@ -0,0 +1,9 @@ +--- + +## Phase 1: 调度循环 + +维护 `retry_count = 0`，最多 3 轮（`retry_count` = 0, 1, 2）： +- retry_count = 0: 首次实现 +- retry_count = 1: 第 1 次 retry +- retry_count = 2: 第 2 次 retry +- retry_count >= 3: 转为 needs-info diff --git a/packages/core/templates/autopilot/shared/04-cross-issue-suggestions.md b/packages/core/templates/autopilot/shared/04-cross-issue-suggestions.md new file mode 100644 index 0000000..22161b3 --- /dev/null +++ b/packages/core/templates/autopilot/shared/04-cross-issue-suggestions.md @@ -0,0 +1,37 @@ +### 交叉 Issue Suggestion 匹配 + +dispatch implementer 前，扫描 `suggestions.json`，匹配 pending suggestions 到当前 issue 的 AGENT-BRIEF： + +#### 推断 feature 目录 + +- **本地模式**：从 issue 路径提取（如 `.scratch/auth/issues/01-login/` → `.scratch/auth/`） +- **GitHub 模式**：从 issue title 生成 feature slug → `.scratch//` +- 若无从推断 → 跳过匹配，不传 CROSS_ISSUE_SUGGESTIONS + +#### 读取和匹配 + +1. 检查 `.scratch//suggestions.json` 是否存在： + - 不存在 → 跳过匹配，不传 CROSS_ISSUE_SUGGESTIONS + - 存在 → 读取，筛选 `status: "pending"` 的条目 +2. 对每条 pending suggestion，执行双重匹配（**任一命中即视为匹配**）： + - **文件路径匹配**：suggestion 的 `files` 数组中任一路径字符串作为子串出现在 AGENT-BRIEF 全文（issue body、AC 文本、文件引用）→ 命中 + - **关键词匹配**：suggestion 的 `keywords` 数组中任一关键词作为子串出现在 AGENT-BRIEF 全文中（**大小写不敏感**）→ 命中 +3. 未命中的 suggestions 保持 `pending` 状态，不传递 +4. 命中的 suggestions 组装为 `CROSS_ISSUE_SUGGESTIONS` JSON 数组。每条附带完整 reviewer 上下文： + ```json + { + "source_issue": "#N 或 ", + "round": , + "content": "", + "files": ["path/to/file1.ts", ...], + "keywords": ["keyword1", ...], + "reviewer_context": "<原 REVIEWER_REPORT 摘录：该 Suggestion 所属 REVIEWER_REPORT 中 Suggestion 条目全文（含 KEYWORKS/FILES 标注）>" + } + ``` + **`reviewer_context` 重建**：`suggestions.json` 中存储的是结构化字段（`content`、`files`、`keywords`），不含标注行。组装 `CROSS_ISSUE_SUGGESTIONS` 时，orchestrator 需从独立字段重建 `reviewer_context`（即带 KEYWORDS/FILES 标注行的完整 reviewer report 摘录），格式如： + ``` + - [ ] + KEYWORDS: + FILES: + ``` +5. 无匹配到任何 suggestion → 不传 CROSS_ISSUE_SUGGESTIONS diff --git a/packages/core/templates/autopilot/shared/05-implementer-preflight.md b/packages/core/templates/autopilot/shared/05-implementer-preflight.md new file mode 100644 index 0000000..76ea8bf --- /dev/null +++ b/packages/core/templates/autopilot/shared/05-implementer-preflight.md @@ -0,0 +1,49 @@ +### 执行 implementer + +#### 前置：Pre-flight 工具链检测 + +dispatch implementer 前，检测项目的工具链是否可用： + +1. 根据项目类型推断测试命令（Rust → `cargo test`，Node → `npm test`，Python → `pytest` 或 `uv run pytest`） +2. 运行 `which ` 检测工具链是否存在（如 `which cargo`、`which npm`） +3. 不可用时尝试常见安装路径（`~/.cargo/bin/cargo`、`~/.rustup/toolchains/*/bin/cargo`） +4. 设置 `TOOLCHAIN: available` 或 `TOOLCHAIN: unavailable`，传入 implementer 的 dispatch prompt + +#### 前置：REFACTORING 模式检测 + +分析合约内容，检测当前 issue 是否为纯重构任务（非新功能开发）： + +1. 扫描合约关键词：`replace`、`consolidate`、`extract`、`delete`、`Remove`、`Replace`、`inline`、`shared function`、`duplicated` → 命中 2+ 且不含 `Add`、`new feature`、`Implement`（作为新增功能时）→ 标记 `REFACTORING: true` +2. 对照 AC：如果所有 AC 描述的是"替换"或"删除"而非"新增功能" → `REFACTORING: true` +3. 设置 `REFACTORING: true|false`，传入 implementer 的 dispatch prompt + +#### 强制 Skill 加载指令 + +**在开始任何操作之前，必须使用 `skill` 工具加载以下技能：** +``` +1. `skill(name: "tdd")` — TDD 方法论（红绿重构循环、测试质量标准、mock 纪律） +2. `skill(name: "diagnose")` — 系统性诊断流程（遇到意外错误时使用） +3. `skill(name: "zoom-out")` — 不熟悉代码区域时上探抽象层次 + +**这是强制步骤，不可跳过。** 未加载技能前不得执行任何其他操作。 +``` + +--- + +<以下为任务描述> + +<根据 retry_count 和模式动态生成> + +任务描述部分传递： +- **共同的**：`source`, `id`, `contract`（合约内容）, `TOOLCHAIN: `, `REFACTORING: `，以及： + - 首次（retry_count = 0）：`ROUND: 0` + - retry（retry_count >= 1）：`ROUND: ` + `PREV_REVIEW: <上一轮 REVIEWER_REPORT 全文>` + - 如有匹配到的 CROSS_ISSUE_SUGGESTIONS，一并传入 +- **本地模式**：额外传 issue 目录绝对路径 +- **GitHub 模式**：额外传 issue body（含 AC）+ `IS_GITHUB: true` + +等待 implementer 回复，解析 `IMPLEMENTER_REPORT:`。 + +**空回复处理：** 如果 implementer 返回空结果（无 `IMPLEMENTER_REPORT:` 标记头），自动重试 1 次（重新 dispatch 相同 prompt）。两次都空 → 更新 Status 为 `needs-info` 并停止。 + +**解析容错：** 回复中找不到 `IMPLEMENTER_REPORT:` 标记头 → 视为不可解析，更新 Status 为 `needs-info` 附原始回复，停止。 diff --git a/packages/core/templates/autopilot/shared/06-self-review.md b/packages/core/templates/autopilot/shared/06-self-review.md new file mode 100644 index 0000000..318f4a0 --- /dev/null +++ b/packages/core/templates/autopilot/shared/06-self-review.md @@ -0,0 +1,9 @@ +### 首次实现：检查 SELF_REVIEW + +retry_count = 0 时，检查报告中有无 `SELF_REVIEW:` 段： + +- STATUS: DONE → "无问题" 或 "发现问题 → 已修复" → 通过 +- STATUS: UNVERIFIED → 必须包含每条 AC 的验证方式标注（测试运行 / 代码结构分析）。**标注缺失但 STATUS: UNVERIFIED → 通过**（UNVERIFIED 本身已声明验证不全） +- STATUS: DONE 或 UNVERIFIED 但缺失 SELF_REVIEW 段 → 标记为 `needs-info`，停止 + +Retry 轮次（retry_count >= 1）不检查 SELF_REVIEW。 diff --git a/packages/core/templates/autopilot/shared/07-handle-implementer.md b/packages/core/templates/autopilot/shared/07-handle-implementer.md new file mode 100644 index 0000000..d121970 --- /dev/null +++ b/packages/core/templates/autopilot/shared/07-handle-implementer.md @@ -0,0 +1,38 @@ +### 处理 implementer 结果 + +- **STATUS: DONE** → dispatch `reviewer` agent。**prompt 必须以 skill 加载指令开头（强制，不可省略）**： + +``` +**在开始任何操作之前，必须使用 `skill` 工具加载以下技能：** +1. `skill(name: "tdd")` — 测试质量标准和 mock 纪律（用于 TDD 审查维度） + +**这是强制步骤，不可跳过。** 未加载技能前不得执行任何其他操作。 + +--- + +<以下为任务描述> +``` + +任务描述部分传递 `source`, `id`, `contract`, `CHANGED_FILES`, `SIBLING_CONTEXT` + 上一轮 `REVIEWER_REPORT`（如有） + - **GitHub 模式**：额外传 `IS_GITHUB: true` + +- **STATUS: UNVERIFIED** → dispatch `reviewer` agent（同上 prompt 格式）。任务描述中额外传递 `UNVERIFIED: true` + implementer 的完整 `SELF_REVIEW` 段（含逐 AC 验证方式标注）。reviewer 的审查侧重： + - 结构正确性（代码逻辑是否符合 AC） + - 是否所有 AC 都有对应的代码实现 + - VERDICT 可选 `VERIFY_NEEDED`（结构通过但需工具链验证）或 `RETRY`（结构本身有问题） + +- **STATUS: BLOCKED 或 NEEDS_CONTEXT** → 更新 Status 为 `needs-info`，追加注释说明原因，**停止** + +#### 解析 SUGGESTION_RESOLUTIONS + +STATUS: DONE 时，从 `IMPLEMENTER_REPORT` 中解析 `SUGGESTION_RESOLUTIONS:` 段，暂存待 reviewer 确认后执行： + +1. 如段内容为 "无" 或不存在 → 无需要处理的跨 issue suggestion，跳过 +2. 逐条解析，每行格式：`[resolved|rejected|deferred] 来源 round : → <处理说明>` +3. 提取字段： + - `type`：`resolved` / `rejected` / `deferred` + - `source_issue`：来源 issue 标识（如 `#18`、`01-login`） + - `round`：reviewer 轮次 + - `summary`：`→` 前的 content 摘要 + - `detail`：`→` 后的处理说明（对 rejected 即拒绝理由） +4. 暂存为 `pending_resolutions` 列表，在 reviewer 返回 MERGE 后统一执行状态更新 diff --git a/packages/core/templates/autopilot/shared/08-handle-reviewer.md b/packages/core/templates/autopilot/shared/08-handle-reviewer.md new file mode 100644 index 0000000..6c91376 --- /dev/null +++ b/packages/core/templates/autopilot/shared/08-handle-reviewer.md @@ -0,0 +1,49 @@ +### 处理 reviewer 结果 + +解析 `REVIEWER_REPORT:`，看 VERDICT。reviewer 任务失败或找不到 `VERDICT:` → 视为 BLOCKED，更新 Status 为 `needs-info` 并停止。 + +**解析容错：** 找不到 `REVIEWER_REPORT:` 标记头 → 视为不可解析，更新 Status 为 `needs-info` 附原始回复，停止。 + +#### 提取 Suggestion 并持久化 + +解析完 REVIEWER_REPORT 后，无论 VERDICT 如何，提取 `## Suggestion` 节的所有条目并写入 `suggestions.json`： + +1. **解析条目**：逐条解析 `## Suggestion` 下的每个 `- [ ]` 项： + - `content`：`- [ ] ` 后的正文文本（不含 KEYWORDS/FILES 标注行） + - `keywords`：`KEYWORDS:` 行（逗号分隔，可选）→ 解析为数组 + - `files`：`FILES:` 行（逗号分隔，可选）→ 解析为数组 +2. **兜底提取**（仅当对应标注缺失时）： + - **关键词兜底**：从 `content` 文本中提取 2-5 个最有代表性的术语（优先提取技术术语、模块名、模式名） + - **文件路径兜底**：从当前 issue 的 implementer 报告 `CHANGED_FILES` 中提取，去重 +3. **推断 feature 目录**： + - 本地模式（`source = "local"`）：从 issue 路径提取，如 `.scratch/auth/issues/01-login/` → `.scratch/auth/` + - GitHub 模式（`source = "github"`）：从 issue title 生成 feature slug，创建 `.scratch//` +4. **读取现有文件**：检查 `.scratch//suggestions.json` 是否存在，存在则读取，不存在则初始化为空数组 `[]` +5. **去重**：按 `content` 字段比较，已存在相同 `content` 的条目不重复写入 +6. **追加新条目**：每个新条目格式为： + ```json + { "issue": "", "round": , "content": "...", "files": [...], "keywords": [...], "status": "pending" } + ``` + - `issue`：本地模式用目录名（如 `01-login`），GitHub 模式用 `#` + - `round`：当前 `retry_count` +7. **写入文件**：将更新后的数组写回 `.scratch//suggestions.json`（使用文件写入工具） +8. **GitHub Issue 评论同步**（仅 `source = "github"` 时执行）： + - 对每条**新增**的 suggestion（去重跳过的不写），追加 issue comment，格式：`autopilot suggestion []: <正文>` +9. **报告**：向用户报告提取结果 — "从 reviewer 提取了 N 条 Suggestion（M 条新增，K 条去重跳过）"；如有 GitHub comment 同步，注明已写入 N 条 comment + +**注意**：仅提取 `## Suggestion` 级别条目。Critical 和 Important 必须在当前 issue 内解决，不传播。 + +--- + +VERDICT 分支： + +- **MERGE** → 更新 Status 为 `resolved`，追加 reviewer 结论。进入"Update Suggestion 状态"步骤，完成后**返回扫描模式处理下一个 issue** +- **VERIFY_NEEDED** → 审查通过（结构正确）但 implementer 工具链不可用，无法实际验证。处理流程： + 1. 尝试运行项目的测试命令（如 `cargo test`、`npm test`、`pytest`）。如工具链在 orchestrator 环境可用 → 运行验证 + 2. 验证通过 → 更新 Status 为 `resolved`，追加 "Orchestrator verified: all tests pass" + 3. 验证失败或工具链仍不可用 → 更新 Status 为 `needs-info`，追加 reviewer 结论 + "Toolchain unavailable — requires manual verification" + 4. 所有情况下保留 reviewer 报告和 Suggestion 提取 +- **RETRY** → `retry_count += 1`，清空 `pending_resolutions = []`（上一轮 resolutions 在 retry 后失效，新轮次 implementer 需重新声明） + - `retry_count < 3`：返回"执行 implementer"（传递 PREV_REVIEW） + - `retry_count >= 3`：更新 Status 为 `needs-info`，追加 reviewer 问题清单 + 说明已达最大重试次数，**返回扫描模式处理下一个 issue** +- **BLOCKED** → 更新 Status 为 `needs-info`，追加 reviewer 结论，**返回扫描模式处理下一个 issue** diff --git a/packages/core/templates/autopilot/shared/09-suggestion-state.md b/packages/core/templates/autopilot/shared/09-suggestion-state.md new file mode 100644 index 0000000..609bade --- /dev/null +++ b/packages/core/templates/autopilot/shared/09-suggestion-state.md @@ -0,0 +1,34 @@ +#### Update Suggestion 状态 + +VERDICT: MERGE 时，根据 `pending_resolutions` 更新 `suggestions.json` 中对应条目的状态： + +1. **定位条目**：在 `suggestions.json` 中按 `issue`（匹配 `source_issue`）、`round` 和 `content` 三级匹配对应 suggestion 条目： + - 一级：`issue` 字段匹配 `source_issue`（字符串全等） + - 二级：`round` 字段匹配 `round`（数字全等） + - 三级：`summary`（`→` 前的 content 摘要）作为子串出现在条目的 `content` 字段中（子串匹配，大小写敏感） + - 无匹配条目（implementer 声明了但 suggestions.json 中找不到）→ 跳过该条 + - **多命中歧义消解**（三级命中 2+ 条）：执行四级匹配打破平局—— + 1. 计算每条候选 entry 的 `files` 与当前 issue 的 implementer `CHANGED_FILES` 的交集，取交集最多者 + 2. 仍平局：取 `summary` 在 `content` 中匹配长度最长者（最精确匹配） + 3. 仍平局（极少见，如相同 content、相同 files）：跳过该条并报告歧义 — "Suggestion resolution ambiguous: `summary` 命中 N 条内容相近的 entry（source_issue + round），无法自动消歧，请人工处理" +2. **状态校验**：定位到条目后，检查其 `status`： + - `status === "pending"` → 继续步骤 3（正常处理） + - `status !== "pending"`（如 `resolved`/`rejected`）→ **跳过该条**并报告异常 — "Skipping suggestion resolution: matched entry already has status `` (expected pending). Possible multi-hit mis-match or duplicate resolution." +3. 根据 `type` 执行状态转换： + + | type | 操作 | 字段更新 | + |------|------|---------| + | `resolved` | 标记为已解决 | `status: "resolved"`, `resolved_in_issue`: 当前 issue 的 slug（本地模式用目录名，GitHub 模式用 `#`） | + | `rejected` | 标记为已拒绝 | `status: "rejected"`, `rejected_reason`: `detail` 字段内容（即 `→` 后的处理说明） | + | `deferred` | 保持 pending + 备注 | `status` 仍为 `"pending"`, `deferred_by`: 当前 issue slug | + +4. **写回文件**：将更新后的数组写回 `.scratch//suggestions.json` +5. **GitHub Issue 评论同步**（仅 `source = "github"` 时执行）： + - 对 `resolved` 和 `rejected` 类型，追加 issue comment + - `deferred` 不需要额外 issue comment（状态未变，且 initial pending comment 已存在） + +6. **报告**：汇总更新结果 — "处理了 N 条 suggestion（M resolved, K rejected, J deferred）" + +### Phase 1 退出条件 + +当扫描模式返回零个 ready-for-agent issue 时，Phase 1 完成。进入 Phase 2。 diff --git a/packages/core/templates/autopilot/shared/10-phase2-meta.md b/packages/core/templates/autopilot/shared/10-phase2-meta.md new file mode 100644 index 0000000..929cc75 --- /dev/null +++ b/packages/core/templates/autopilot/shared/10-phase2-meta.md @@ -0,0 +1,118 @@ +--- + +## Phase 2: 全局 Meta-Review + +当所有 issue 处理完毕（无 ready-for-agent 剩余），执行全局审查。 + +### 目的 + +对照 ADR、PRD 和所有 issue 合约，审视整个 codebase 的： +- 实现正确性（所有模块是否符合各自的 AC 和 PRD 全局约束） +- 跨模块一致性（是否有模式漂移、重复实现、约定不一致） +- 计划外变更（是否有孤儿文件、未声明依赖、残留引用） + +### 执行方式 + +Orchestrator 自主审查与 reviewer 子 agent **并行**执行。两者均产出独立报告后，进入「报告合并」统一处理。 + +#### 1. 派遣 reviewer 子 agent（并行） + +Dispatch `reviewer` agent（只读，无 edit/bash 权限）。**prompt 必须以 skill 加载指令开头（强制，不可省略）**： + +``` +**在开始任何操作之前，必须使用 `skill` 工具加载以下技能：** +1. `skill(name: "tdd")` — 测试质量标准和 mock 纪律 + +**这是强制步骤，不可跳过。** 未加载技能前不得执行任何文件读取或审查操作。 + +--- + +你正在执行全局 meta-review。审查范围为整个 codebase，对照以下基准： + +**审查基准（读取以下全文）：** +- 所有 ADR（docs/adr/） +- 所有 PRD（如有） +- 所有已 resolved issue 的合约（AGENT-BRIEF.md 或 GitHub issue body 中的 AC） + +**审查维度（适配 reviewer 四维框架到全局 meta-review 上下文）：** + +1. **ADR/PRD 全局约束验证**（维度四：计划忠实度）： + - 逐条检查 ADR 和 PRD 中声明的全局约束（输出格式要求、依赖白名单、运行时约束、目录结构约定等）是否在所有模块中满足 + - 是否存在约束降级（如 PRD 要求 byte-identical 但实现仅做到结构等价） + - 依赖白名单是否被超出 + +2. **跨模块一致性**（维度三代码质量 + 维度四工程约定）： + - 入口检测方式、import 风格（静态/动态）、错误处理模式、日志格式、算法选择、文件布局是否一致 + - 是否存在模式漂移（不同模块用不同方式解决同一问题） + - 是否有重复实现 + +3. **计划外变更检测**（维度四：孤儿文件、未声明行为）： + - 是否存在孤儿文件：不在任何合约中声明的新文件 + - 合约要求删除但尚未删除的文件 + - 合约未声明的新行为（悄悄加的 UX 优化、额外校验、额外日志） + - 未在合约中声明的副作用（自动创建目录、修改全局配置、静默改写其他模块文件） + +4. **AC 覆盖率**（维度一：行为对齐的全局化）： + - 对照所有 resolved issue 合约，逐条检查 AC 是否有对应实现 + +输出格式与标准 reviewer 一致：以 `REVIEWER_REPORT:` 开头，分 Critical / Important / Suggestion 三级 + VERDICT（MERGE / RETRY / BLOCKED）。 +``` + +#### 2. Orchestrator 自主审查（并行） + +Orchestrator 自身用 grep/glob 工具执行审查，覆盖与 reviewer 子 agent 相同的范围： + +1. 读取 PRD 全文和所有相关 ADR（包含 ADR 0003、ADR 0004 等），列出每条全局约束 +2. 逐条检查：用 grep/glob 扫描 codebase，验证约束满足 +3. 对照 issue 合约，检查每个 resolved issue 的 AC 覆盖率 +4. 检查跨模块一致性（入口检测方式、import 风格、错误处理、日志格式、算法选择、文件布局） +5. 检查计划外变更（孤儿文件、未声明新行为、副作用、未删除文件） +6. 输出结构化报告：Critical / Important / Suggestion + VERDICT + +#### 3. 等待两份报告 + +上述 1、2 两步并行执行。两者均完成后（均产出独立报告），进入下方「报告合并」流程。 + +### 报告合并 + +`执行方式` 产生两份独立的 meta-review 报告： +- **orchestrator 自主审查报告** — 对照 ADR、PRD 和 issue 合约逐条检查 +- **reviewer 子 agent 并行审查报告** — 4 轴审查（Behavior alignment、TDD discipline、Code quality、Plan fidelity） + +进入修复循环前，将两份报告合并为一份 `MERGED_META_REPORT`： + +1. **Union 策略**：两份报告中 Critical 和 Important 级别的问题取其并集——任一份报告标记的问题均纳入修复范围。Suggestion 级别条目同样取并集（去重后）。 + +2. **冲突裁决**：当两份报告对同一文件/路径有不同结论时（如一方标记为问题，另一方认为正常），orchestrator 手动核实并裁定： + - **默认采纳更严格结论**：无法确认是否为误报时，默认采纳更严格的发现（标记为问题）。 + - **确认误报后降级**：仅当 orchestrator 明确确认某发现为误报（false positive）时，方可将该条目从修复范围移除或降级为 Suggestion。 + - 裁决过程记录到合并报告中，注明"冲突裁决：\<路径\> — 采纳 \<来源\> 的结论" + +3. **去重**：完全相同的发现（同一文件 + 同一问题模式）在两份报告中均出现时，合并为单一条目，标注"双来源一致：<发现描述>"。 + +合并后产出 `MERGED_META_REPORT`，包含： +- Critical 条目（合并去重后） +- Important 条目（合并去重后） +- Suggestion 条目（合并去重后） +- 冲突裁决记录 + +### 修复循环 + +从合并报告（`MERGED_META_REPORT`）中取 Critical + Important 条目，由 **orchestrator 直接修复**（不 dispatch implementer），因为 meta 问题通常是机械性的： + +- **统一模式**：isMain 不一致 → 直接 edit 文件统一为一种模式 +- **删除残留**：孤儿文件 / __pycache__ / 残留引用 → 直接 delete/edit +- **更新文档**：SKILL.md / schemas.md / ADR 引用 → 直接 edit + +遇到需要判断的设计级问题（如"两种算法选哪个"），追加 comment 标记为 needs-info。 + +### 修复后验证 + +修复完成后： +1. 运行 `bun test` 确认测试全绿 +2. 重新执行 meta-review，确认 0 Critical + 0 Important +3. 最多 **2 轮**修复循环。2 轮后仍有问题 → 报告残余问题，标记 needs-info + +### 完成后 + +向用户报告 Phase 1 和 Phase 2 的完整结果：处理了多少 issue、总轮次、最终状态、meta-review 发现和修复了哪些问题。 diff --git a/packages/core/templates/autopilot/shared/11-final-acceptance-report.md b/packages/core/templates/autopilot/shared/11-final-acceptance-report.md new file mode 100644 index 0000000..78e9867 --- /dev/null +++ b/packages/core/templates/autopilot/shared/11-final-acceptance-report.md @@ -0,0 +1,74 @@ +### FINAL_ACCEPTANCE_REPORT + +meta-review 完成后，产出跨 issue Suggestion 验收报告，供人类签收。 + +#### 1. 聚合 Suggestions + +扫描所有 feature 目录的 `suggestions.json`，汇总所有条目： + +- 用 `glob` 扫描 `.scratch/*/suggestions.json`，读取每个文件 +- 将每个条目合并到统一列表中，保留来源 feature 信息 + +**GitHub Issue 模式附加聚合**： + +当 Phase 1 处理过 GitHub issue 时，从 issue comments 中提取 suggestions，与本地 `suggestions.json` 合并： + +1. 对每个处理过的 GitHub issue，用读取 comments API 获取所有 comments +2. 筛选格式为 `autopilot suggestion []: <正文>` 的 comments +3. 对每条提取：`status`（从 `[]` 块）、`content`（`:` 后的正文）、`source_issue`（`#`） +4. 与本地 `suggestions.json` 条目按 `content` 去重合并（本地优先：本地已有相同 content 的条目保留本地版本及完整字段） + +#### 2. 分组统计 + +按 `status` 字段分组： + +| 分组 | 内容 | 来源 | +|------|------|------| +| **Pending** | `status: "pending"` 的所有条目 | 列出 `content`、`source_issue`、`keywords`；如有 `deferred_by`，注明 | +| **Rejected** | `status: "rejected"` 的所有条目 | 列出 `content`、`source_issue`、`rejected_reason` | +| **Resolved** | `status: "resolved"` 的所有条目 | 列出 `content`、`resolved_in_issue`、原 `source_issue` | + +#### 3. 输出 FINAL_ACCEPTANCE_REPORT + +以 `FINAL_ACCEPTANCE_REPORT:` 为标记头输出结构化报告： + +``` +FINAL_ACCEPTANCE_REPORT: + +## Pending（需处理） +- + - 来源: + - 关键词: + - [deferred by: ] +...（如无 pending，写 "无"） + +## Rejected（已拒绝） +- + - 来源: + - 理由: +...（如无 rejected，写 "无"） + +## Resolved（已解决） +- + - 来源: + - 由 处理 +...（如无 resolved，写 "无"） +``` + +#### 4. 边界处理 + +- `suggestions.json` 不存在（glob 无结果）→ 报告 "No suggestions.json found. Skipping acceptance report."（**不影响 meta-review 流程**） +- 存在但无 pending → 报告 "All suggestions resolved. Ready for sign-off." +- 有 pending → 报告 "The following suggestions require human attention:" + 逐条列出 + 建议人工判断处理方向（落实为后续 issue 或标记 rejected） +- 仅 GitHub issue comments 中有 suggestions 而本地无 `suggestions.json` → 以 comments 聚合结果为准，仍输出完整报告 + +#### 5. Self-Verification + +FINAL_ACCEPTANCE_REPORT 输出后，orchestrator 执行以下快速自检： + +- [ ] `suggestions.json` 中的每条 `status: "resolved"` 条目均有 `resolved_in_issue` 字段 +- [ ] `suggestions.json` 中的每条 `status: "rejected"` 条目均有 `rejected_reason` 字段 +- [ ] 无 `status: "pending"` 条目被意外标记为 `resolved_in_issue`（仅 resolved 应有此字段） +- [ ] FINAL_ACCEPTANCE_REPORT 的 Pending / Rejected / Resolved 三组条目数之和 = `suggestions.json` 总条目数（去重后） +- [ ] 无空 `content` 字段的条目 +- [ ] 发现异常 → 记录到报告末尾的 `## Self-Verification Issues` 节，人工跟进 diff --git a/packages/core/templates/autopilot/shared/12-template-implementer.md b/packages/core/templates/autopilot/shared/12-template-implementer.md new file mode 100644 index 0000000..867895a --- /dev/null +++ b/packages/core/templates/autopilot/shared/12-template-implementer.md @@ -0,0 +1,59 @@ +--- + +## Implementer Dispatch Template + +Copy this EXACT text as the message to the implementer agent, replacing ``: + +``` +You are the autopilot implementer. Load the required skills: tdd (test discipline), diagnose (debugging), zoom-out (codebase navigation), then complete the task below. + +## Contract + + + +## Context + +SOURCE: +ISSUE_ID: <#N or path> +ROUND: +TOOLCHAIN: +SIBLING_CONTEXT: + += 1> + +## Instructions + +1. Load the required skills: tdd (test discipline), diagnose (debugging), zoom-out (codebase navigation) +2. Implement ALL Acceptance Criteria following TDD: write a failing test first, then minimal production code, then refactor +3. Never write production code without a preceding failing test +4. Mock only at system boundaries (external API, DB, filesystem, time) +5. Test behavior through public interfaces, not implementation details + +## Self-Review + +After all ACs are implemented, verify: +- Every AC has corresponding test coverage +- No scope creep (nothing from Out of scope was implemented) +- Tests verify behavior, not internals +- Mocks are only at system boundaries + +## Report Format + +Output EXACTLY in this format: + +IMPLEMENTER_REPORT: +ROUND: +STATUS: DONE | UNVERIFIED | BLOCKED | NEEDS_CONTEXT +SELF_REVIEW: +- Finding: → Fixed +- No issues +CHANGED_FILES: +- path/to/file (what changed) +SUMMARY: One sentence summary + +Status rules: +- DONE only if TOOLCHAIN=available AND all ACs have test evidence +- UNVERIFIED if TOOLCHAIN=unavailable (list per-AC verification method) +- BLOCKED if diagnose failed twice +- NEEDS_CONTEXT if ambiguous scope +``` diff --git a/packages/core/templates/autopilot/shared/13-template-reviewer.md b/packages/core/templates/autopilot/shared/13-template-reviewer.md new file mode 100644 index 0000000..75dc65a --- /dev/null +++ b/packages/core/templates/autopilot/shared/13-template-reviewer.md @@ -0,0 +1,82 @@ +--- + +## Reviewer Dispatch Template + +Copy this EXACT text as the message to the reviewer agent, replacing ``: + +``` +You are the autopilot reviewer. You are READ-ONLY — do not edit any files or run commands that modify state. Refer to the tdd skill for test quality standards. + +## Contract + + + +## Context + +SOURCE: +ISSUE_ID: <#N or path> +ROUND: +BASE_COMMIT: +CHANGED_FILES: +IMPLEMENTER_REPORT: +SIBLING_CONTEXT: +UNVERIFIED: + +## Diff to Review + +The diff of changes for this issue is provided below. Use this diff as the review boundary — do not run git diff yourself. + +## Review Dimensions + +### Dimension 1: Behavior Alignment +- Does each AC have corresponding test coverage? +- Do tests cover edge cases and error conditions? +- Is there scope creep (implemented something in Out of scope)? +- Is there scope gap (missed an AC or partial implementation)? + +### Dimension 2: TDD Discipline (refer to tdd skill) +- Is there production code without a preceding failing test? +- Do tests verify behavior through public interfaces? +- Are mocks only at system boundaries? +- Can you distinguish "test passes" from "test is correct"? + +### Dimension 3: Code Quality +- Does naming use project domain vocabulary? +- Does new code follow existing patterns? +- Are interfaces small and testable? +- Any undeclared dependencies? + +### Dimension 4: Plan Fidelity & Cross-Module Consistency +- Do global constraints from PRD/ADR hold? +- Is entry detection, import style, error handling consistent? +- Any orphan files not in any contract? +- Any undeclared side effects? + +## Verdict Rules + +| Verdict | Condition | +|---------|-----------| +| MERGE | 0 Critical AND 0 Important | +| RETRY | 1+ Critical OR 1+ Important | +| BLOCKED | Directional error, needs human | +| VERIFY_NEEDED | UNVERIFIED mode: 0 Critical + 0 Important (structure correct, needs toolchain verification) | + +## Report Format + +Output EXACTLY: + +REVIEWER_REPORT: + +## Critical (must fix) +- [ ] + +## Important (must fix) +- [ ] + +## Suggestion (optional) +- [ ] + KEYWORDS: + FILES: + +VERDICT: MERGE | RETRY | BLOCKED | VERIFY_NEEDED +``` diff --git a/packages/core/templates/autopilot/shared/14-template-meta-reviewer.md b/packages/core/templates/autopilot/shared/14-template-meta-reviewer.md new file mode 100644 index 0000000..640dd29 --- /dev/null +++ b/packages/core/templates/autopilot/shared/14-template-meta-reviewer.md @@ -0,0 +1,22 @@ +--- + +## Meta-Reviewer Template + +Same as Reviewer Dispatch Template above, but with this context: + +``` +You are executing a GLOBAL META-REVIEW. Review the entire codebase, not a single issue. + +## Review Scope +- All resolved issues in this PRD +- Cross-module consistency +- ADR/PRD global constraint compliance +- Orphan files and undeclared behavior + +## Contract + + +## Context +ALL_RESOLVED_ISSUES: +SOURCE: github +``` diff --git a/packages/core/tsconfig.build.json b/packages/core/tsconfig.build.json new file mode 100644 index 0000000..0a11719 --- /dev/null +++ b/packages/core/tsconfig.build.json @@ -0,0 +1,4 @@ +{ + "extends": "./tsconfig.json", + "exclude": ["src/**/*.test.ts"] +} diff --git a/packages/core/tsconfig.json b/packages/core/tsconfig.json new file mode 100644 index 0000000..4248b95 --- /dev/null +++ b/packages/core/tsconfig.json @@ -0,0 +1,15 @@ +{ + "compilerOptions": { + "module": "preserve", + "moduleResolution": "bundler", + "target": "ESNext", + "strict": true, + "esModuleInterop": true, + "skipLibCheck": true, + "outDir": "dist", + "declaration": true, + "types": ["node"], + "rootDir": "src" + }, + "include": ["src"] +} diff --git a/packages/opencode/package.json b/packages/opencode/package.json new file mode 100644 index 0000000..3a17036 --- /dev/null +++ b/packages/opencode/package.json @@ -0,0 +1,26 @@ +{ + "name": "@matthewye/opencode-toolbox", + "version": "1.0.0", + "description": "OpenCode plugin for autopilot development toolkit", + "type": "module", + "main": "./dist/index.js", + "types": "./dist/index.d.ts", + "exports": { + ".": { + "types": "./dist/index.d.ts", + "import": "./dist/index.js" + } + }, + "scripts": { + "build": "rm -rf skills && mkdir -p skills && cp -r ../../skills/* skills/ 2>/dev/null; cp -r ../../upstream/skills/* skills/ 2>/dev/null; bun build src/index.ts --outdir dist --target node && tsc --project tsconfig.build.json --emitDeclarationOnly --outDir dist && mkdir -p agents && for f in ../../agents/*.md; do bun run ../../scripts/filter-agent.ts \"$f\" opencode \"agents/$(basename \"$f\")\"; done", + "typecheck": "tsc --project tsconfig.build.json --noEmit" + }, + "dependencies": { + "@matthewye/autopilot-toolkit-core": "workspace:*", + "@opencode-ai/plugin": "latest" + }, + "devDependencies": { + "@types/node": "latest", + "typescript": "latest" + } +} diff --git a/packages/opencode/src/index.ts b/packages/opencode/src/index.ts new file mode 100644 index 0000000..af7e2d9 --- /dev/null +++ b/packages/opencode/src/index.ts @@ -0,0 +1,75 @@ +import fs from "node:fs"; +import path from "node:path"; +import type { PrincipleSections } from "@matthewye/autopilot-toolkit-core"; +import { + buildAgentConfigs, + buildCommandConfigs, + buildPrinciplesBlock, + getAgentsDir, + getCoreDir, + getPrinciplesDir, + parsePrinciples, + readMarkdownConfigs, + readSkillDirCommands, +} from "@matthewye/autopilot-toolkit-core"; +import type { Config, Plugin } from "@opencode-ai/plugin"; + +type DynamicConfig = Config & Record; + +export const AutopilotToolkit: Plugin = async ({ directory: _directory }) => { + const pkgDir = path.resolve(import.meta.dirname, ".."); + const skillsDir = path.resolve(pkgDir, "skills"); + const agentsDir = getAgentsDir(); + const commandsDir = path.resolve(pkgDir, "commands"); + const principlesPath = path.resolve(getPrinciplesDir(), "karpathy.md"); + const primaryPrinciplesPath = path.resolve(getPrinciplesDir(), "karpathy-primary.md"); + + const agentsRaw = readMarkdownConfigs(agentsDir); + const commandsRaw = readMarkdownConfigs(commandsDir); + + const agentConfigs = buildAgentConfigs(agentsRaw); + const commandConfigs = buildCommandConfigs(commandsRaw); + + const skillCommands = readSkillDirCommands(skillsDir); + const skillCommandConfigs = buildCommandConfigs(skillCommands); + + let principleSections: PrincipleSections | null = null; + if (fs.existsSync(principlesPath)) { + const rawPrinciples = fs.readFileSync(principlesPath, "utf8"); + principleSections = parsePrinciples(rawPrinciples); + } + + return { + config: async (config) => { + const cfg = config as DynamicConfig; + + cfg.skills = cfg.skills || {}; + cfg.skills.paths = cfg.skills.paths || []; + if (!cfg.skills.paths.includes(skillsDir)) { + cfg.skills.paths.push(skillsDir); + } + + if (cfg.lsp === undefined) { + cfg.lsp = true as unknown as typeof cfg.lsp; + } + + cfg.agent = { ...(cfg.agent ?? {}), ...agentConfigs }; + cfg.command = { ...skillCommandConfigs, ...commandConfigs, ...(cfg.command ?? {}) }; + + if (principleSections) { + for (const [agentName, agentCfg] of Object.entries(cfg.agent)) { + if (!agentCfg) continue; + const block = buildPrinciplesBlock(principleSections, agentName); + if (block) { + agentCfg.prompt = block + (agentCfg.prompt ?? ""); + } + } + } + + cfg.instructions = cfg.instructions || []; + if (!cfg.instructions.includes(primaryPrinciplesPath)) { + cfg.instructions.push(primaryPrinciplesPath); + } + }, + }; +}; diff --git a/packages/opencode/tsconfig.build.json b/packages/opencode/tsconfig.build.json new file mode 100644 index 0000000..0a11719 --- /dev/null +++ b/packages/opencode/tsconfig.build.json @@ -0,0 +1,4 @@ +{ + "extends": "./tsconfig.json", + "exclude": ["src/**/*.test.ts"] +} diff --git a/packages/opencode/tsconfig.json b/packages/opencode/tsconfig.json new file mode 100644 index 0000000..4248b95 --- /dev/null +++ b/packages/opencode/tsconfig.json @@ -0,0 +1,15 @@ +{ + "compilerOptions": { + "module": "preserve", + "moduleResolution": "bundler", + "target": "ESNext", + "strict": true, + "esModuleInterop": true, + "skipLibCheck": true, + "outDir": "dist", + "declaration": true, + "types": ["node"], + "rootDir": "src" + }, + "include": ["src"] +} diff --git a/scripts/build-autopilot.ts b/scripts/build-autopilot.ts new file mode 100644 index 0000000..acb2c23 --- /dev/null +++ b/scripts/build-autopilot.ts @@ -0,0 +1,96 @@ +/** + * build-autopilot.ts + * Reads manifest.json and concatenates template files + * into platform-specific autopilot prompts. + * + * Output: + * packages/opencode/commands/autopilot.md (OpenCode) + * packages/codex/skills/autopilot/SKILL.md (Codex) + */ + +import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs"; +import { dirname, join } from "path"; + +const ROOT = join(import.meta.dir, ".."); +const TEMPLATES_DIR = join(ROOT, "packages/core/templates/autopilot"); +const MANIFEST_PATH = join(TEMPLATES_DIR, "manifest.json"); + +const OUTPUTS: Record = { + opencode: join(ROOT, "packages/opencode/commands/autopilot.md"), + codex: join(ROOT, "packages/codex/skills/autopilot/SKILL.md"), +}; + +interface Manifest { + opencode: string[]; + codex: string[]; +} + +function ensureDir(p: string): void { + if (!existsSync(p)) { + mkdirSync(p, { recursive: true }); + } +} + +function buildPlatform(platform: "opencode" | "codex", fileList: string[]): string { + const parts: string[] = []; + + for (const relativePath of fileList) { + const fullPath = join(TEMPLATES_DIR, relativePath); + + if (!existsSync(fullPath)) { + throw new Error( + `Template file not found: ${relativePath}\n` + ` Expected at: ${fullPath}\n` + ` Platform: ${platform}`, + ); + } + + const content = readFileSync(fullPath, "utf-8"); + parts.push(content); + } + + return parts.join(""); +} + +function main(): void { + // Read manifest + if (!existsSync(MANIFEST_PATH)) { + console.error("Error: manifest.json not found at:", MANIFEST_PATH); + process.exit(1); + } + + let manifest: Manifest; + try { + const raw = readFileSync(MANIFEST_PATH, "utf-8"); + manifest = JSON.parse(raw); + } catch (e) { + console.error("Error: failed to parse manifest.json:", (e as Error).message); + process.exit(1); + } + + if (!manifest.opencode || !Array.isArray(manifest.opencode)) { + console.error("Error: manifest.json missing 'opencode' array"); + process.exit(1); + } + if (!manifest.codex || !Array.isArray(manifest.codex)) { + console.error("Error: manifest.json missing 'codex' array"); + process.exit(1); + } + + // Build each platform + for (const platform of ["opencode", "codex"] as const) { + const outputPath = OUTPUTS[platform]; + ensureDir(dirname(outputPath)); + + try { + const content = buildPlatform(platform, manifest[platform]); + writeFileSync(outputPath, content, "utf-8"); + console.log(`[${platform}] Built ${content.length} bytes → ${outputPath.replace(ROOT + "/", "")}`); + } catch (e) { + console.error(`[${platform}] Build failed:`, (e as Error).message); + process.exit(1); + } + } + + console.log("\nAutopilot templates built successfully."); +} + +main(); diff --git a/scripts/filter-agent.ts b/scripts/filter-agent.ts new file mode 100644 index 0000000..65f8585 --- /dev/null +++ b/scripts/filter-agent.ts @@ -0,0 +1,44 @@ +/** + * filter-agent.ts + * Filters dual-platform annotated .md files for a specific platform. + * + * Usage: bun run scripts/filter-agent.ts + * Platforms: opencode | codex + * + * Markers: + * ... → included only in OpenCode output + * ... → included only in Codex output + */ + +const args = process.argv.slice(2); +if (args.length < 3) { + console.error("Usage: filter-agent.ts "); + process.exit(1); +} + +const [inputPath, platform, outputPath] = args; +const content = require("fs").readFileSync(inputPath, "utf8"); +const fs = require("fs"); + +let result = content; + +if (platform === "opencode") { + // Remove all CDX_ONLY blocks + result = result.replace(/[\s\S]*?/g, ""); + // Remove the OP_ONLY markers but keep the content + result = result.replace(/\n?/g, ""); + result = result.replace(/\n?/g, ""); +} else if (platform === "codex") { + // Remove all OP_ONLY blocks + result = result.replace(/[\s\S]*?/g, ""); + // Remove the CDX_ONLY markers but keep the content + result = result.replace(/\n?/g, ""); + result = result.replace(/\n?/g, ""); +} else { + console.error("Platform must be 'opencode' or 'codex'"); + process.exit(1); +} + +fs.mkdirSync(require("path").dirname(outputPath), { recursive: true }); +fs.writeFileSync(outputPath, result, "utf8"); +console.log(`[filter-agent] Generated ${platform} version → ${outputPath}`); diff --git a/scripts/lint-autopilot.ts b/scripts/lint-autopilot.ts new file mode 100644 index 0000000..60e4af4 --- /dev/null +++ b/scripts/lint-autopilot.ts @@ -0,0 +1,149 @@ +/** + * lint-autopilot.ts + * LLM-powered drift detection between OpenCode and Codex autopilot prompts. + * + * Reads both platform outputs and compares shared logic sections + * for semantic drift, outputting a structured JSON report. + */ + +import { existsSync, readFileSync } from "node:fs"; +import { join } from "node:path"; + +const ROOT = join(import.meta.dir, ".."); +const OPENCODE_PROMPT = join(ROOT, "packages/opencode/commands/autopilot.md"); +const CODEX_PROMPT = join(ROOT, "packages/codex/skills/autopilot/SKILL.md"); + +interface DriftEntry { + section: string; + opencode_behavior: string; + codex_behavior: string; + drift_severity: "none" | "minor" | "major" | "critical"; + recommendation: string; +} + +function extractSection(content: string, sectionName: string): string { + const regex = new RegExp( + `(?:^|\\n)##?\\s*${sectionName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[^\\n]*\\n([\\s\\S]*?)(?=\\n##?\\s|$)`, + "i", + ); + const match = content.match(regex); + return match ? match[1].trim() : "(section not found)"; +} + +function extractKeyPhases(content: string): Record { + const phases: Record = {}; + const sectionRegex = /^##?\s+(.+)$/gm; + let match: RegExpExecArray | null; + const matches: Array<{ title: string; start: number }> = []; + + match = sectionRegex.exec(content); + while (match !== null) { + matches.push({ title: match[1].trim(), start: match.index }); + match = sectionRegex.exec(content); + } + + for (let i = 0; i < matches.length; i++) { + const start = matches[i].start; + const end = i + 1 < matches.length ? matches[i + 1].start : content.length; + phases[matches[i].title] = content.slice(start, end).trim(); + } + return phases; +} + +function comparePhases(opencodePhases: Record, codexPhases: Record): DriftEntry[] { + const entries: DriftEntry[] = []; + const allKeys = new Set([...Object.keys(opencodePhases), ...Object.keys(codexPhases)]); + + for (const key of allKeys) { + const oc = opencodePhases[key]; + const cx = codexPhases[key]; + + if (!oc && cx) { + entries.push({ + section: key, + opencode_behavior: "(missing)", + codex_behavior: `${cx.length} chars`, + drift_severity: "major", + recommendation: `Section "${key}" only present in Codex output — possible missing section in OpenCode manifest.`, + }); + } else if (oc && !cx) { + entries.push({ + section: key, + opencode_behavior: `${oc.length} chars`, + codex_behavior: "(missing)", + drift_severity: "major", + recommendation: `Section "${key}" only present in OpenCode output — possible missing section in Codex manifest.`, + }); + } else if (oc && cx) { + const ocLen = oc.length; + const cxLen = cx.length; + const diff = Math.abs(ocLen - cxLen); + const pctDiff = diff / Math.max(ocLen, cxLen); + + let severity: DriftEntry["drift_severity"] = "none"; + let recommendation = "Sections are aligned."; + + if (pctDiff > 0.8) { + severity = "critical"; + recommendation = `Size difference >80% (${ocLen} vs ${cxLen} chars) — sections likely have different content. Verify manifest includes correct files.`; + } else if (pctDiff > 0.3) { + severity = "major"; + recommendation = `Size difference >30% (${ocLen} vs ${cxLen} chars) — sections may contain platform-specific detail drift.`; + } else if (pctDiff > 0.1) { + severity = "minor"; + recommendation = `Minor size difference (${ocLen} vs ${cxLen} chars). Expected for platform-specific tool syntax.`; + } + + entries.push({ + section: key, + opencode_behavior: `${ocLen} chars`, + codex_behavior: `${cxLen} chars`, + drift_severity: severity, + recommendation, + }); + } + } + + return entries; +} + +function main() { + if (!existsSync(OPENCODE_PROMPT)) { + console.error("Error: OpenCode prompt not found at:", OPENCODE_PROMPT); + console.error("Run 'bun run build' first to generate prompts."); + process.exit(1); + } + if (!existsSync(CODEX_PROMPT)) { + console.error("Error: Codex prompt not found at:", CODEX_PROMPT); + console.error("Run 'bun run build' first to generate prompts."); + process.exit(1); + } + + const opencodeContent = readFileSync(OPENCODE_PROMPT, "utf8"); + const codexContent = readFileSync(CODEX_PROMPT, "utf8"); + + console.log(`OpenCode prompt: ${opencodeContent.length} chars, ~${opencodeContent.split("\n").length} lines`); + console.log(`Codex prompt: ${codexContent.length} chars, ~${codexContent.split("\n").length} lines`); + console.log(); + + const ocPhases = extractKeyPhases(opencodeContent); + const cxPhases = extractKeyPhases(codexContent); + + const results = comparePhases(ocPhases, cxPhases); + + const criticals = results.filter((r) => r.drift_severity === "critical").length; + const majors = results.filter((r) => r.drift_severity === "major").length; + const minors = results.filter((r) => r.drift_severity === "minor").length; + const nones = results.filter((r) => r.drift_severity === "none").length; + + console.log(JSON.stringify(results, null, 2)); + console.log(); + console.log(`Summary: ${criticals} critical, ${majors} major, ${minors} minor, ${nones} aligned`); + console.log(`Total sections: ${results.length}`); + + if (criticals > 0) { + process.exit(1); + } +} + +main(); diff --git a/skills/git-guardrails/SKILL.md b/skills/git-guardrails/SKILL.md deleted file mode 100644 index eda8baa..0000000 --- a/skills/git-guardrails/SKILL.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -name: git-guardrails -description: Set up OpenCode permission rules to guard against dangerous git commands (push, reset --hard, clean, branch -D, checkout/restore .) before they execute. Use when user wants to prevent destructive git operations, add git safety guardrails, or block dangerous git commands. -compatibility: opencode ---- - -# Git Guardrails - -Sets up `permission.bash` rules in `opencode.jsonc` to require confirmation (`ask`) before executing dangerous git commands. - -## What Gets Guarded - -- `git push` (all variants including `--force`, `--force-with-lease`) -- `git reset --hard` -- `git clean -f` / `git clean -fd` -- `git branch -D` -- `git checkout .` / `git restore .` - -When guarded, OpenCode will prompt for confirmation before executing any of these commands. - -## Steps - -### 1. Ask scope - -Ask the user: install for **all projects** (global) or **this project only**? - -| Scope | Config path | -|-------|-------------| -| Global | `~/.config/opencode/opencode.jsonc` | -| Project | `/opencode.jsonc` | - -### 2. Read existing config - -Read the target config file. Note existing `permission` block, especially any existing `bash` rules. - -If the file does not exist, create it with a minimal structure: -```jsonc -{ - "$schema": "https://opencode.ai/config.json", - "permission": {} -} -``` - -### 3. Add guardrail rules - -Add or update the following rules under `permission.bash`. Use `"ask"` level — the agent must request confirmation before executing these commands: - -```jsonc -"permission": { - "bash": { - // ... existing rules ... - "git push *": "ask", - "git reset --hard *": "ask", - "git clean -f*": "ask", - "git branch -D *": "ask", - "git checkout .*": "ask" - } -} -``` - -Rules to write: - -| Pattern | Guards | -|---------|--------| -| `"git push *": "ask"` | All `git push` variants | -| `"git reset --hard *": "ask"` | Hard reset only | -| `"git clean -f*": "ask"` | Forced clean | -| `"git branch -D *": "ask"` | Force delete branch | -| `"git checkout .*": "ask"` | Discard working tree changes | - -**Merge carefully**: If the file already has a `permission.bash` block with existing rules, merge the new rules into it — never overwrite unrelated settings. - -### 4. Ask about customization - -Ask if the user wants to: -- Add additional dangerous commands to guard (e.g., `git stash drop`, `git reflog expire`) -- Remove any of the 5 default patterns -- Change any rule from `"ask"` to `"deny"` (block without confirmation) - -Edit the config accordingly. - -### 5. Verify - -Read back the modified config file and confirm: - -1. All 5 guardrail patterns are present under `permission.bash` -2. Existing unrelated rules are preserved -3. JSONC syntax is valid (no trailing commas, matching braces) - -Report the final state to the user with a summary of what's now guarded. diff --git a/skills/setup-autopilot/SKILL.md b/skills/setup-autopilot/SKILL.md new file mode 100644 index 0000000..a733f4d --- /dev/null +++ b/skills/setup-autopilot/SKILL.md @@ -0,0 +1,81 @@ +--- +name: setup-autopilot +description: Bootstrap autopilot-toolkit in a consuming project. Copies AGENTS.md template with Karpathy coding principles, installs Codex agent .toml files into .codex/agents/, and verifies the installation. Use when first setting up autopilot-toolkit in a project. +--- + +# Autopilot Toolkit Setup + +Set up the autopilot-toolkit plugin for the consuming project. This skill handles all bootstrap steps automatically. + +## Setup steps (execute in order) + +### 1. Install AGENTS.md with Karpathy principles + +Find the autopilot-toolkit plugin root. The plugin ships `templates/AGENTS.md`. Determine the project root (git root or current directory if not in a repo). + +Check if the project already has an `AGENTS.md` at the project root: + +- **If no `AGENTS.md` exists**: Copy the template: + ```bash + cp /templates/AGENTS.md /AGENTS.md + ``` +- **If `AGENTS.md` already exists**: Read the template, then append its content to the existing file with a `---` separator. + +### 2. Install Codex agent .toml files + +Find the generated agent `.toml` files at `/templates/agents/*.toml`. Copy them to the project's `.codex/agents/` directory: + +```bash +mkdir -p /.codex/agents +cp /templates/agents/*.toml /.codex/agents/ +``` + +This installs three custom agents that will appear in Codex when you type `@`: +- `implementer` — autonomous task implementer following TDD discipline +- `reviewer` — read-only code reviewer on 4 axes (Behavior, TDD, Code quality, Plan fidelity) +- `argus` — multimodal/image analysis agent + +**After this step, the user MUST restart Codex** for the agents to appear. + +### 3. Verify installation + +After the user restarts Codex, ask them to verify: + +- Type `@` — should see `implementer`, `reviewer`, `argus` in the agent picker +- Type `$` — should see autopilot-toolkit skills (autopilot, setup-autopilot, skill-creator, etc.) +- Run `codex plugin list` — should show `autopilot-toolkit` as `installed, enabled` + +If agents don't appear after restart, verify `.codex/agents/` contains the `.toml` files. + +### 4. Report completion + +After all steps succeed, output: + +```text +AUTOPILOT-TOOLKIT SETUP COMPLETE + +AGENTS.md ............. Karpathy principles installed +Codex agents .......... implementer, reviewer, argus → .codex/agents/ +Plugin ................ autopilot-toolkit is active + +Next steps: + 1. Restart Codex + 2. Try @implementer — spawn the implementer agent + 3. Try $autopilot — run the autopilot workflow +``` + +### Finding the plugin root + +The plugin root is the directory containing `.codex-plugin/plugin.json`. Common locations: + +- **Local/personal install**: `~/plugins/autopilot-toolkit` +- **npm install**: `node_modules/@matthewye/autopilot-toolkit` +- **Git clone**: `~/Documents/WorkSpace/opencode-toolbox` + +Use `find ~/plugins -name 'plugin.json' -path '*autopilot*' 2>/dev/null` to locate it, or ask the user if uncertain. + +### Out of scope + +- Setting up `.scratch/` issue directories +- Configuring GitHub integration +- Customizing agent prompts diff --git a/skills/skill-creator/scripts/node_modules b/skills/skill-creator/scripts/node_modules new file mode 120000 index 0000000..6c57164 --- /dev/null +++ b/skills/skill-creator/scripts/node_modules @@ -0,0 +1 @@ +../../../node_modules \ No newline at end of file diff --git a/skills/skill-creator/scripts/package.json b/skills/skill-creator/scripts/package.json new file mode 100644 index 0000000..f3db424 --- /dev/null +++ b/skills/skill-creator/scripts/package.json @@ -0,0 +1,8 @@ +{ + "name": "skill-creator-scripts", + "private": true, + "dependencies": { + "gray-matter": "^4.0.3", + "adm-zip": "^0.5.17" + } +} diff --git a/src/index.ts b/src/index.ts deleted file mode 100644 index 201fa84..0000000 --- a/src/index.ts +++ /dev/null @@ -1,213 +0,0 @@ -import fs from "node:fs"; -import path from "node:path"; -import { fileURLToPath } from "node:url"; -import type { Config, Plugin } from "@opencode-ai/plugin"; -import matter from "gray-matter"; - -const __dirname = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); - -interface FrontmatterEntry { - prompt: string; - [key: string]: unknown; -} - -interface AgentConfig { - prompt: string; - [key: string]: unknown; -} - -interface CommandConfig { - template: string; - args?: unknown; - [key: string]: unknown; -} - -// ── Karpathy Principles ─────────────────────────────────────────── - -interface PrincipleSections { - v1Coding: string; - v1Judging: string; - v1Analyzing: string; - v2: string; - v3: string; - v4: string; -} - -function parsePrinciples(content: string): PrincipleSections { - const sections: Record = {}; - // Split by "## Principle" headers; skip the intro before the first header - const parts = content.split(/(?=^## Principle)/m); - for (const part of parts) { - const headerMatch = part.match(/^## Principle\s+(\d).*?\n/); - if (!headerMatch) continue; - const num = headerMatch[1]; - const body = part.slice(headerMatch[0].length).trim(); - - if (num === "1") { - if (part.includes("Reviewer Variant")) { - sections.v1Judging = body; - } else if (part.includes("Argus Variant")) { - sections.v1Analyzing = body; - } else { - sections.v1Coding = body; - } - } else { - sections[`v${num}`] = body; - } - } - return sections as unknown as PrincipleSections; -} - -const AGENT_PRINCIPLE_MAP: Record = { - implementer: ["v1Coding", "v2", "v3", "v4"], - general: ["v1Coding", "v2", "v3", "v4"], - reviewer: ["v1Judging", "v2", "v4"], - argus: ["v1Analyzing", "v2", "v4"], -}; - -const HEADER_TEMPLATES: Record = { - v1Coding: "## Principle 1: Think Before Coding", - v1Judging: "## Principle 1: Think Before Judging", - v1Analyzing: "## Principle 1: Think Before Analyzing", - v2: "## Principle 2: Simplicity First", - v3: "## Principle 3: Surgical Changes", - v4: "## Principle 4: Goal-Driven Execution", -}; - -function buildPrinciplesBlock(sections: PrincipleSections, agentName: string): string { - const keys = AGENT_PRINCIPLE_MAP[agentName]; - if (!keys || keys.length === 0) return ""; - - const blocks = keys.map((key) => { - const header = HEADER_TEMPLATES[key]; - const body = sections[key] ?? ""; - return `${header}\n\n${body}`; - }); - return `# Andrej Karpathy's Coding Principles\n\n${blocks.join("\n\n")}\n\n---\n\n`; -} - -function readMarkdownConfigs(dirPath: string): Record { - const result: Record = {}; - if (!fs.existsSync(dirPath)) return result; - - const entries = fs.readdirSync(dirPath, { withFileTypes: true }); - for (const entry of entries) { - if (!entry.isFile() || !entry.name.endsWith(".md")) continue; - - const filePath = path.join(dirPath, entry.name); - const raw = fs.readFileSync(filePath, "utf8"); - const { data: frontmatter, content } = matter(raw); - const key = entry.name.replace(/\.md$/, ""); - - result[key] = { ...frontmatter, prompt: content.trim() }; - } - return result; -} - -function buildAgentConfigs(raw: Record): Record { - const configs: Record = {}; - for (const [name, def] of Object.entries(raw)) { - const { prompt, ...rest } = def; - configs[name] = { ...rest, prompt }; - } - return configs; -} - -function buildCommandConfigs(raw: Record): Record { - const configs: Record = {}; - for (const [name, def] of Object.entries(raw)) { - const { prompt, arguments: args, ...rest } = def; - const cmd: CommandConfig = { ...rest, template: prompt }; - if (args) cmd.args = args; - configs[name] = cmd; - } - return configs; -} - -function readSkillDirCommands(dirPath: string): Record { - const result: Record = {}; - if (!fs.existsSync(dirPath)) return result; - - const entries = fs.readdirSync(dirPath, { withFileTypes: true }); - for (const entry of entries) { - if (!entry.isDirectory()) continue; - const skillFile = path.join(dirPath, entry.name, "SKILL.md"); - if (!fs.existsSync(skillFile)) continue; - - const raw = fs.readFileSync(skillFile, "utf8"); - const { data: frontmatter } = matter(raw); - const name = frontmatter.name || entry.name; - const description = frontmatter.description || ""; - const template = `Load the '${name}' skill and follow its instructions.`; - - result[name] = { description, prompt: template }; - } - return result; -} - -// biome-ignore lint/suspicious/noExplicitAny: plugin config is dynamically extended by consumers -type DynamicConfig = Config & Record; - -export const OpenCodeToolbox: Plugin = async ({ directory: _directory }) => { - const skillsDir = path.resolve(__dirname, "skills"); - const upstreamEngDir = path.resolve(__dirname, "upstream", "skills", "engineering"); - const upstreamProdDir = path.resolve(__dirname, "upstream", "skills", "productivity"); - const agentsRaw = readMarkdownConfigs(path.resolve(__dirname, "agents")); - const commandsRaw = readMarkdownConfigs(path.resolve(__dirname, "commands")); - - const agentConfigs = buildAgentConfigs(agentsRaw); - const commandConfigs = buildCommandConfigs(commandsRaw); - - const upstreamCommandsRaw = { - ...readSkillDirCommands(upstreamEngDir), - ...readSkillDirCommands(upstreamProdDir), - }; - const upstreamCommandConfigs = buildCommandConfigs(upstreamCommandsRaw); - - // ── Karpathy principles ─────────────────────────────────────── - const principlesPath = path.resolve(__dirname, "principles", "karpathy.md"); - const primaryPrinciplesPath = path.resolve(__dirname, "principles", "karpathy-primary.md"); - let principleSections: PrincipleSections | null = null; - if (fs.existsSync(principlesPath)) { - const rawPrinciples = fs.readFileSync(principlesPath, "utf8"); - principleSections = parsePrinciples(rawPrinciples); - } - - return { - config: async (config) => { - const cfg = config as DynamicConfig; - cfg.skills = cfg.skills || {}; - cfg.skills.paths = cfg.skills.paths || []; - const skillPaths = [skillsDir, upstreamEngDir, upstreamProdDir]; - for (const p of skillPaths) { - if (!cfg.skills.paths.includes(p)) { - cfg.skills.paths.push(p); - } - } - - if (cfg.lsp === undefined) { - cfg.lsp = true as unknown as typeof cfg.lsp; - } - - cfg.agent = { ...(cfg.agent ?? {}), ...agentConfigs }; - cfg.command = { ...upstreamCommandConfigs, ...commandConfigs, ...(cfg.command ?? {}) }; - - // Prepend Karpathy principles to agent prompts based on agent mapping - if (principleSections) { - for (const [agentName, agentCfg] of Object.entries(cfg.agent)) { - if (!agentCfg) continue; - const block = buildPrinciplesBlock(principleSections, agentName); - if (block) { - agentCfg.prompt = block + (agentCfg.prompt ?? ""); - } - } - } - - // Primary agent: inject full Karpathy principles via instructions - cfg.instructions = cfg.instructions || []; - if (!cfg.instructions.includes(primaryPrinciplesPath)) { - cfg.instructions.push(primaryPrinciplesPath); - } - }, - }; -}; diff --git a/templates/AGENTS.md b/templates/AGENTS.md new file mode 100644 index 0000000..1ebbc77 --- /dev/null +++ b/templates/AGENTS.md @@ -0,0 +1,44 @@ +# Autopilot Toolkit — Karpathy Coding Principles + +# Andrej Karpathy's Coding Principles + +## Principle 1: Think Before Coding + +Before writing a single line of code, think through the problem thoroughly. Understand the requirements, design the approach, and consider edge cases. Most coding time should be spent thinking, not typing. A clear mental model prevents rework and produces cleaner solutions. + +Ask yourself: +- What exactly am I trying to accomplish? +- What are the constraints and edge cases? +- What is the simplest approach that could work? +- How will I verify correctness? + +## Principle 2: Simplicity First + +Always reach for the simplest solution first. Simple code is easier to understand, debug, test, and extend. Resist the urge to build elaborate abstractions or optimize prematurely. Complexity should be earned — only introduce it when the simple solution demonstrably falls short. + +Guidelines: +- Write code a junior engineer can understand +- Avoid premature abstraction and optimization +- Delete code whenever possible — less code is better code +- Favor boring, proven patterns over clever, novel ones + +## Principle 3: Surgical Changes + +Make the smallest possible change to achieve the goal. Each change should do exactly one thing, and do it well. Do not refactor unrelated code, fix unrelated bugs, or add "while I'm here" improvements. Precise, minimal changes reduce risk and make review straightforward. + +Guidelines: +- One logical change per commit/PR +- Don't mix refactoring with feature work +- Leave the codebase cleaner than you found it — but only in the area you're touching +- If you see something broken that's out of scope, file an issue, don't fix it inline + +## Principle 4: Goal-Driven Execution + +Stay relentlessly focused on the goal. Do not chase shiny objects, explore interesting tangents, or get sidetracked by adjacent improvements. Every action should trace back to the acceptance criteria. If it's not required to meet the goal, it's a distraction. + +Guidelines: +- Before every action, ask: "Does this directly advance the goal?" +- Track progress against acceptance criteria, not against interesting side quests +- Timebox exploration — if you need to research, set a limit and return to the goal +- Ship the minimum viable implementation, then iterate + diff --git a/test-fixtures/skill-creator/benchmark-legacy/runs/eval-0/with_skill/run-1/grading.json b/test-fixtures/skill-creator/benchmark-legacy/runs/eval-0/with_skill/run-1/grading.json new file mode 100644 index 0000000..8ff5182 --- /dev/null +++ b/test-fixtures/skill-creator/benchmark-legacy/runs/eval-0/with_skill/run-1/grading.json @@ -0,0 +1,25 @@ +{ + "summary": { + "pass_rate": 0.75, + "passed": 15, + "failed": 5, + "total": 20 + }, + "timing": { + "total_duration_seconds": 50.0 + }, + "execution_metrics": { + "total_tool_calls": 7, + "output_chars": 1800, + "errors_encountered": 1 + }, + "expectations": [ + { "text": "Handles basic case", "passed": true, "evidence": "matches expected output" }, + { "text": "Handles edge case", "passed": false, "evidence": "incorrect parsing" } + ], + "user_notes_summary": { + "uncertainties": [], + "needs_review": [], + "workarounds": [] + } +} diff --git a/test-fixtures/skill-creator/benchmark-legacy/runs/eval-0/without_skill/run-1/grading.json b/test-fixtures/skill-creator/benchmark-legacy/runs/eval-0/without_skill/run-1/grading.json new file mode 100644 index 0000000..89354ca --- /dev/null +++ b/test-fixtures/skill-creator/benchmark-legacy/runs/eval-0/without_skill/run-1/grading.json @@ -0,0 +1,25 @@ +{ + "summary": { + "pass_rate": 0.4, + "passed": 8, + "failed": 12, + "total": 20 + }, + "timing": { + "total_duration_seconds": 70.5 + }, + "execution_metrics": { + "total_tool_calls": 15, + "output_chars": 4000, + "errors_encountered": 4 + }, + "expectations": [ + { "text": "Handles basic case", "passed": false, "evidence": "timeout" }, + { "text": "Handles edge case", "passed": false, "evidence": "wrong output" } + ], + "user_notes_summary": { + "uncertainties": ["Unclear prompt requirements"], + "needs_review": ["Needs better error handling"], + "workarounds": [] + } +} diff --git a/test-fixtures/skill-creator/benchmark-workspace/eval-0/eval_metadata.json b/test-fixtures/skill-creator/benchmark-workspace/eval-0/eval_metadata.json new file mode 100644 index 0000000..743d5e8 --- /dev/null +++ b/test-fixtures/skill-creator/benchmark-workspace/eval-0/eval_metadata.json @@ -0,0 +1 @@ +{ "eval_id": 100 } diff --git a/test-fixtures/skill-creator/benchmark-workspace/eval-0/with_skill/run-1/grading.json b/test-fixtures/skill-creator/benchmark-workspace/eval-0/with_skill/run-1/grading.json new file mode 100644 index 0000000..e58ffcb --- /dev/null +++ b/test-fixtures/skill-creator/benchmark-workspace/eval-0/with_skill/run-1/grading.json @@ -0,0 +1,25 @@ +{ + "summary": { + "pass_rate": 0.85, + "passed": 17, + "failed": 3, + "total": 20 + }, + "timing": { + "total_duration_seconds": 45.2 + }, + "execution_metrics": { + "total_tool_calls": 8, + "output_chars": 2500, + "errors_encountered": 1 + }, + "expectations": [ + { "text": "Handles edge case A", "passed": true, "evidence": "correct output format and value" }, + { "text": "Handles edge case B", "passed": false, "evidence": "returned wrong type" } + ], + "user_notes_summary": { + "uncertainties": ["Edge case B may need alternative approach"], + "needs_review": [], + "workarounds": ["Used retry for case B"] + } +} diff --git a/test-fixtures/skill-creator/benchmark-workspace/eval-0/with_skill/run-2/grading.json b/test-fixtures/skill-creator/benchmark-workspace/eval-0/with_skill/run-2/grading.json new file mode 100644 index 0000000..a10849a --- /dev/null +++ b/test-fixtures/skill-creator/benchmark-workspace/eval-0/with_skill/run-2/grading.json @@ -0,0 +1,25 @@ +{ + "summary": { + "pass_rate": 0.9, + "passed": 18, + "failed": 2, + "total": 20 + }, + "timing": { + "total_duration_seconds": 38.7 + }, + "execution_metrics": { + "total_tool_calls": 6, + "output_chars": 2100, + "errors_encountered": 0 + }, + "expectations": [ + { "text": "Handles edge case A", "passed": true, "evidence": "correct output" }, + { "text": "Handles edge case B", "passed": true, "evidence": "fixed in run 2" } + ], + "user_notes_summary": { + "uncertainties": [], + "needs_review": [], + "workarounds": [] + } +} diff --git a/test-fixtures/skill-creator/benchmark-workspace/eval-0/without_skill/run-1/grading.json b/test-fixtures/skill-creator/benchmark-workspace/eval-0/without_skill/run-1/grading.json new file mode 100644 index 0000000..81369a3 --- /dev/null +++ b/test-fixtures/skill-creator/benchmark-workspace/eval-0/without_skill/run-1/grading.json @@ -0,0 +1,25 @@ +{ + "summary": { + "pass_rate": 0.55, + "passed": 11, + "failed": 9, + "total": 20 + }, + "timing": { + "total_duration_seconds": 62.1 + }, + "execution_metrics": { + "total_tool_calls": 12, + "output_chars": 3500, + "errors_encountered": 3 + }, + "expectations": [ + { "text": "Handles edge case A", "passed": false, "evidence": "timeout on edge case" }, + { "text": "Handles edge case B", "passed": false, "evidence": "incorrect parsing" } + ], + "user_notes_summary": { + "uncertainties": ["Unsure about prompt structure"], + "needs_review": ["Output format inconsistent"], + "workarounds": ["Retried with different prompt"] + } +} diff --git a/test-fixtures/skill-creator/benchmark-workspace/eval-0/without_skill/run-2/grading.json b/test-fixtures/skill-creator/benchmark-workspace/eval-0/without_skill/run-2/grading.json new file mode 100644 index 0000000..28b9244 --- /dev/null +++ b/test-fixtures/skill-creator/benchmark-workspace/eval-0/without_skill/run-2/grading.json @@ -0,0 +1,25 @@ +{ + "summary": { + "pass_rate": 0.6, + "passed": 12, + "failed": 8, + "total": 20 + }, + "timing": { + "total_duration_seconds": 58.3 + }, + "execution_metrics": { + "total_tool_calls": 11, + "output_chars": 3200, + "errors_encountered": 2 + }, + "expectations": [ + { "text": "Handles edge case A", "passed": true, "evidence": "worked after prompt fix" }, + { "text": "Handles edge case B", "passed": false, "evidence": "still fails on parsing" } + ], + "user_notes_summary": { + "uncertainties": [], + "needs_review": [], + "workarounds": [] + } +} diff --git a/test-fixtures/skill-creator/empty-description-block/SKILL.md b/test-fixtures/skill-creator/empty-description-block/SKILL.md new file mode 100644 index 0000000..2dffee4 --- /dev/null +++ b/test-fixtures/skill-creator/empty-description-block/SKILL.md @@ -0,0 +1,5 @@ +--- +name: empty-block-skill +description: | +--- +# Empty Block diff --git a/test-fixtures/skill-creator/empty-description/SKILL.md b/test-fixtures/skill-creator/empty-description/SKILL.md new file mode 100644 index 0000000..2abef67 --- /dev/null +++ b/test-fixtures/skill-creator/empty-description/SKILL.md @@ -0,0 +1,5 @@ +--- +name: empty-skill +description: +--- +# Empty Skill diff --git a/test-fixtures/skill-creator/frontmatter-list/SKILL.md b/test-fixtures/skill-creator/frontmatter-list/SKILL.md new file mode 100644 index 0000000..2dda878 --- /dev/null +++ b/test-fixtures/skill-creator/frontmatter-list/SKILL.md @@ -0,0 +1,5 @@ +--- +- item1 +- item2 +--- +# Content diff --git a/test-fixtures/skill-creator/invalid-compatibility-too-long/SKILL.md b/test-fixtures/skill-creator/invalid-compatibility-too-long/SKILL.md new file mode 100644 index 0000000..7e2c462 --- /dev/null +++ b/test-fixtures/skill-creator/invalid-compatibility-too-long/SKILL.md @@ -0,0 +1,6 @@ +--- +name: test-skill +description: A test skill +compatibility: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +--- +# Content diff --git a/test-fixtures/skill-creator/invalid-compatibility-type/SKILL.md b/test-fixtures/skill-creator/invalid-compatibility-type/SKILL.md new file mode 100644 index 0000000..f7ef8b6 --- /dev/null +++ b/test-fixtures/skill-creator/invalid-compatibility-type/SKILL.md @@ -0,0 +1,6 @@ +--- +name: test-skill +description: A test skill +compatibility: 123 +--- +# Content diff --git a/test-fixtures/skill-creator/invalid-description-angle-brackets/SKILL.md b/test-fixtures/skill-creator/invalid-description-angle-brackets/SKILL.md new file mode 100644 index 0000000..08ab1e5 --- /dev/null +++ b/test-fixtures/skill-creator/invalid-description-angle-brackets/SKILL.md @@ -0,0 +1,5 @@ +--- +name: test-skill +description: Has brackets +--- +# Content diff --git a/test-fixtures/skill-creator/invalid-description-too-long/SKILL.md b/test-fixtures/skill-creator/invalid-description-too-long/SKILL.md new file mode 100644 index 0000000..fb63a9a --- /dev/null +++ b/test-fixtures/skill-creator/invalid-description-too-long/SKILL.md @@ -0,0 +1,5 @@ +--- +name: test-skill +description: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +--- +# Content diff --git a/test-fixtures/skill-creator/invalid-description-type/SKILL.md b/test-fixtures/skill-creator/invalid-description-type/SKILL.md new file mode 100644 index 0000000..039fd26 --- /dev/null +++ b/test-fixtures/skill-creator/invalid-description-type/SKILL.md @@ -0,0 +1,5 @@ +--- +name: test-skill +description: 42 +--- +# Content diff --git a/test-fixtures/skill-creator/invalid-name-consecutive-hyphens/SKILL.md b/test-fixtures/skill-creator/invalid-name-consecutive-hyphens/SKILL.md new file mode 100644 index 0000000..bc5dab9 --- /dev/null +++ b/test-fixtures/skill-creator/invalid-name-consecutive-hyphens/SKILL.md @@ -0,0 +1,5 @@ +--- +name: bad--name +description: A test skill +--- +# Content diff --git a/test-fixtures/skill-creator/invalid-name-leading-hyphen/SKILL.md b/test-fixtures/skill-creator/invalid-name-leading-hyphen/SKILL.md new file mode 100644 index 0000000..9a8d183 --- /dev/null +++ b/test-fixtures/skill-creator/invalid-name-leading-hyphen/SKILL.md @@ -0,0 +1,5 @@ +--- +name: -bad-name +description: A test skill +--- +# Content diff --git a/test-fixtures/skill-creator/invalid-name-too-long/SKILL.md b/test-fixtures/skill-creator/invalid-name-too-long/SKILL.md new file mode 100644 index 0000000..ca28985 --- /dev/null +++ b/test-fixtures/skill-creator/invalid-name-too-long/SKILL.md @@ -0,0 +1,5 @@ +--- +name: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +description: A test skill +--- +# Content diff --git a/test-fixtures/skill-creator/invalid-name-trailing-hyphen/SKILL.md b/test-fixtures/skill-creator/invalid-name-trailing-hyphen/SKILL.md new file mode 100644 index 0000000..0c9ba07 --- /dev/null +++ b/test-fixtures/skill-creator/invalid-name-trailing-hyphen/SKILL.md @@ -0,0 +1,5 @@ +--- +name: bad-name- +description: A test skill +--- +# Content diff --git a/test-fixtures/skill-creator/invalid-name-type/SKILL.md b/test-fixtures/skill-creator/invalid-name-type/SKILL.md new file mode 100644 index 0000000..05ef933 --- /dev/null +++ b/test-fixtures/skill-creator/invalid-name-type/SKILL.md @@ -0,0 +1,5 @@ +--- +name: 123 +description: A test skill +--- +# Content diff --git a/test-fixtures/skill-creator/invalid-name-uppercase/SKILL.md b/test-fixtures/skill-creator/invalid-name-uppercase/SKILL.md new file mode 100644 index 0000000..34e7b29 --- /dev/null +++ b/test-fixtures/skill-creator/invalid-name-uppercase/SKILL.md @@ -0,0 +1,5 @@ +--- +name: Test-Name +description: A test skill +--- +# Content diff --git a/test-fixtures/skill-creator/malformed-no-closing/SKILL.md b/test-fixtures/skill-creator/malformed-no-closing/SKILL.md new file mode 100644 index 0000000..6c09628 --- /dev/null +++ b/test-fixtures/skill-creator/malformed-no-closing/SKILL.md @@ -0,0 +1,3 @@ +--- +name: bad +description: bad diff --git a/test-fixtures/skill-creator/malformed-no-opening/SKILL.md b/test-fixtures/skill-creator/malformed-no-opening/SKILL.md new file mode 100644 index 0000000..ffbed42 --- /dev/null +++ b/test-fixtures/skill-creator/malformed-no-opening/SKILL.md @@ -0,0 +1,4 @@ +name: bad +description: bad +--- +# Bad diff --git a/test-fixtures/skill-creator/missing-fields/SKILL.md b/test-fixtures/skill-creator/missing-fields/SKILL.md new file mode 100644 index 0000000..413297d --- /dev/null +++ b/test-fixtures/skill-creator/missing-fields/SKILL.md @@ -0,0 +1,4 @@ +--- +name: only-name +--- +# Only Name diff --git a/test-fixtures/skill-creator/missing-name/SKILL.md b/test-fixtures/skill-creator/missing-name/SKILL.md new file mode 100644 index 0000000..95a5e5a --- /dev/null +++ b/test-fixtures/skill-creator/missing-name/SKILL.md @@ -0,0 +1,4 @@ +--- +description: has desc but no name +--- +# Content diff --git a/test-fixtures/skill-creator/report-holdout.json b/test-fixtures/skill-creator/report-holdout.json new file mode 100644 index 0000000..aa81afa --- /dev/null +++ b/test-fixtures/skill-creator/report-holdout.json @@ -0,0 +1,92 @@ +{ + "original_description": "Original skill desc", + "best_description": "Best skill desc", + "best_score": "2/3 (test)", + "best_train_score": "2/2", + "best_test_score": "2/3", + "final_description": "Final desc", + "iterations_run": 3, + "holdout": 0.4, + "train_size": 2, + "test_size": 3, + "history": [ + { + "iteration": 1, + "description": "First iteration desc", + "train_passed": 1, + "train_failed": 1, + "train_total": 2, + "train_results": [ + { "query": "train trigger me", "should_trigger": true, "pass": true, "triggers": 3, "runs": 3 }, + { "query": "train ignore me", "should_trigger": false, "pass": false, "triggers": 2, "runs": 3 } + ], + "test_passed": 1, + "test_failed": 2, + "test_total": 3, + "test_results": [ + { "query": "test a", "should_trigger": true, "pass": true, "triggers": 2, "runs": 3 }, + { "query": "test b", "should_trigger": true, "pass": false, "triggers": 1, "runs": 3 }, + { "query": "test c", "should_trigger": false, "pass": false, "triggers": 2, "runs": 3 } + ], + "passed": 1, + "failed": 1, + "total": 2, + "results": [ + { "query": "train trigger me", "should_trigger": true, "pass": true, "triggers": 3, "runs": 3 }, + { "query": "train ignore me", "should_trigger": false, "pass": false, "triggers": 2, "runs": 3 } + ] + }, + { + "iteration": 2, + "description": "Second iteration desc", + "train_passed": 2, + "train_failed": 0, + "train_total": 2, + "train_results": [ + { "query": "train trigger me", "should_trigger": true, "pass": true, "triggers": 3, "runs": 3 }, + { "query": "train ignore me", "should_trigger": false, "pass": true, "triggers": 0, "runs": 3 } + ], + "test_passed": 2, + "test_failed": 1, + "test_total": 3, + "test_results": [ + { "query": "test a", "should_trigger": true, "pass": true, "triggers": 3, "runs": 3 }, + { "query": "test b", "should_trigger": true, "pass": true, "triggers": 2, "runs": 3 }, + { "query": "test c", "should_trigger": false, "pass": false, "triggers": 2, "runs": 3 } + ], + "passed": 2, + "failed": 0, + "total": 2, + "results": [ + { "query": "train trigger me", "should_trigger": true, "pass": true, "triggers": 3, "runs": 3 }, + { "query": "train ignore me", "should_trigger": false, "pass": true, "triggers": 0, "runs": 3 } + ] + }, + { + "iteration": 3, + "description": "Third iteration desc", + "train_passed": 2, + "train_failed": 0, + "train_total": 2, + "train_results": [ + { "query": "train trigger me", "should_trigger": true, "pass": true, "triggers": 3, "runs": 3 }, + { "query": "train ignore me", "should_trigger": false, "pass": true, "triggers": 0, "runs": 3 } + ], + "test_passed": 2, + "test_failed": 1, + "test_total": 3, + "test_results": [ + { "query": "test a", "should_trigger": true, "pass": true, "triggers": 3, "runs": 3 }, + { "query": "test b", "should_trigger": true, "pass": true, "triggers": 2, "runs": 3 }, + { "query": "test c", "should_trigger": false, "pass": false, "triggers": 1, "runs": 3 } + ], + "passed": 2, + "failed": 0, + "total": 2, + "results": [ + { "query": "train trigger me", "should_trigger": true, "pass": true, "triggers": 3, "runs": 3 }, + { "query": "train ignore me", "should_trigger": false, "pass": true, "triggers": 0, "runs": 3 } + ] + } + ] +} diff --git a/test-fixtures/skill-creator/report-simple.json b/test-fixtures/skill-creator/report-simple.json new file mode 100644 index 0000000..fc82631 --- /dev/null +++ b/test-fixtures/skill-creator/report-simple.json @@ -0,0 +1,58 @@ +{ + "original_description": "Original skill desc", + "best_description": "Best skill desc", + "best_score": "2/2", + "best_train_score": "2/2", + "best_test_score": null, + "final_description": "Final desc", + "iterations_run": 2, + "holdout": 0, + "train_size": 2, + "test_size": 0, + "history": [ + { + "iteration": 1, + "description": "First iteration desc", + "train_passed": 1, + "train_failed": 1, + "train_total": 2, + "train_results": [ + { "query": "trigger me", "should_trigger": true, "pass": true, "triggers": 3, "runs": 3 }, + { "query": "ignore me", "should_trigger": false, "pass": false, "triggers": 2, "runs": 3 } + ], + "test_passed": null, + "test_failed": null, + "test_total": null, + "test_results": null, + "passed": 1, + "failed": 1, + "total": 2, + "results": [ + { "query": "trigger me", "should_trigger": true, "pass": true, "triggers": 3, "runs": 3 }, + { "query": "ignore me", "should_trigger": false, "pass": false, "triggers": 2, "runs": 3 } + ] + }, + { + "iteration": 2, + "description": "Second iteration desc", + "train_passed": 2, + "train_failed": 0, + "train_total": 2, + "train_results": [ + { "query": "trigger me", "should_trigger": true, "pass": true, "triggers": 3, "runs": 3 }, + { "query": "ignore me", "should_trigger": false, "pass": true, "triggers": 0, "runs": 3 } + ], + "test_passed": null, + "test_failed": null, + "test_total": null, + "test_results": null, + "passed": 2, + "failed": 0, + "total": 2, + "results": [ + { "query": "trigger me", "should_trigger": true, "pass": true, "triggers": 3, "runs": 3 }, + { "query": "ignore me", "should_trigger": false, "pass": true, "triggers": 0, "runs": 3 } + ] + } + ] +} diff --git a/test-fixtures/skill-creator/unexpected-keys/SKILL.md b/test-fixtures/skill-creator/unexpected-keys/SKILL.md new file mode 100644 index 0000000..6758a24 --- /dev/null +++ b/test-fixtures/skill-creator/unexpected-keys/SKILL.md @@ -0,0 +1,6 @@ +--- +name: test-skill +description: A test skill +foo: bar +--- +# Content diff --git a/test-fixtures/skill-creator/valid-block-dash/SKILL.md b/test-fixtures/skill-creator/valid-block-dash/SKILL.md new file mode 100644 index 0000000..1a4e9d4 --- /dev/null +++ b/test-fixtures/skill-creator/valid-block-dash/SKILL.md @@ -0,0 +1,7 @@ +--- +name: bar-skill +description: |- + Strip trailing newline + version of literal block. +--- +# Bar diff --git a/test-fixtures/skill-creator/valid-block-gt-dash/SKILL.md b/test-fixtures/skill-creator/valid-block-gt-dash/SKILL.md new file mode 100644 index 0000000..60c8b9d --- /dev/null +++ b/test-fixtures/skill-creator/valid-block-gt-dash/SKILL.md @@ -0,0 +1,7 @@ +--- +name: gtbar-skill +description: >- + Strip trailing newline + version of folded block. +--- +# GTBar diff --git a/test-fixtures/skill-creator/valid-block-gt/SKILL.md b/test-fixtures/skill-creator/valid-block-gt/SKILL.md new file mode 100644 index 0000000..8758a44 --- /dev/null +++ b/test-fixtures/skill-creator/valid-block-gt/SKILL.md @@ -0,0 +1,8 @@ +--- +name: gt-skill +description: > + This is a folded block + with multiple lines + that should be joined. +--- +# GT Skill diff --git a/test-fixtures/skill-creator/valid-block/SKILL.md b/test-fixtures/skill-creator/valid-block/SKILL.md new file mode 100644 index 0000000..21ccb4a --- /dev/null +++ b/test-fixtures/skill-creator/valid-block/SKILL.md @@ -0,0 +1,8 @@ +--- +name: block-skill +description: | + This is a block description + with multiple lines + that are indented. +--- +# Block Skill diff --git a/test-fixtures/skill-creator/valid/SKILL.md b/test-fixtures/skill-creator/valid/SKILL.md new file mode 100644 index 0000000..cc35362 --- /dev/null +++ b/test-fixtures/skill-creator/valid/SKILL.md @@ -0,0 +1,7 @@ +--- +name: test-skill +description: A test skill for validation +compatibility: "1.0" +--- +# Test Skill +Some content here.