brooks-harness

brooks-lint — 维护工作流（编排器）

此技能用于编排 brooks-lint 仓库本身 的工作。它会运行一个按顺序执行的子 Agent 流水线：每个阶段都是在 .codex/agents/ 中定义的专用 Agent。 使用可用的 Codex 协作工具，并指定匹配的 Agent 角色；继承父级模型和权限。如果未加载自定义角色，请将其 TOML 文件中的 developer_instructions 传递给标准子 Agent。各阶段按顺序运行。每个编辑 Agent 都必须保留其他贡献者的更改，并且只能修改编排器分配给自己的文件。

流水线

[orchestrator]
   Phase 0  context check
   Phase 1  classify request → select stages
   Phase 2  run selected stages in order, with a QA loop-back:
            skill-author → eval-curator → consistency-qa ─(FAIL)→ back to author
                                              │ PASS
                                              ▼
                            trigger-boundary-auditor   (only if a description changed)
                                              ▼
                                      release-manager  (only if release requested)
   Phase 3  report + collect feedback

阶段 0 — 上下文检查

开始前，确定运行模式：

• _workspace/brooks-harness/ 存在 + 维护者要求重做之前运行的部分内容 → 部分重跑：仅调用受影响的阶段，沿用之前的记录。
• _workspace/brooks-harness/ 存在 + 收到新请求 → 新运行：将旧文件夹移至 _workspace/brooks-harness_prev/，然后从头开始。
• _workspace/brooks-harness/ 不存在 → 首次运行：创建该文件夹。

运行记录和 QA 报告存放在 _workspace/brooks-harness/ 下。真正的产物是仓库文件本身——Agent 直接编辑 skills/、evals/ 和清单；_workspace/ 仅保存本次运行的记录以及供审计使用的 PASS/FAIL 结论。

阶段 1 — 对请求分类

选择最精简的阶段组合。QA 阶段绝不跳过——每项更改都必须经过检查。

请求	author	eval	QA	trigger-audit	release
添加新技能	✓（通过 new-skill 脚手架）	✓	✓	✓	—
编辑技能 / 指南内容	✓	如果代码有更改	✓	如果 description 有更改	—
编辑 _shared/ 框架	✓	如果风险定义有更改	✓	—	—
Codex / 维护配置	—	—	✓	—	—
仅评测套件	—	✓	✓	—	—
修复触发描述	✓	—	✓	✓	—
发布	—	—	✓	—	✓
完整流程：更改 + 发布	✓	视需要	✓	如适用	✓

阶段 2 — 运行流水线

使用 Codex 协作工具，按顺序将选定阶段作为子 Agent 启动。向每个 Agent 传递 (a) 任务约定和 (b) 上一阶段的摘要。Agent 将摘要写入 _workspace/brooks-harness/；请在各阶段之间阅读这些摘要。

1. skill-author — 创建 / 编辑内容。对于全新技能，调用 new-skill 脚手架。返回已修改文件列表，以及与约定相关的决策（新的风险代码、新的步骤编号、更改后的 description 触发短语）。
2. eval-curator — 如果 skill-author 报告新增 / 更改了风险代码或模式，则添加成对的正常路径 + 误报场景，并运行 npm run evals。
3. consistency-qa（门禁 — 绝不跳过）— 运行 npm run validate + npm test + npm run evals，然后执行跨文档同步检查（清单、所有包含版本信息的文本文件、CHANGELOG、AGENTS/GEMINI 书籍计数、评测数量）。写入 PASS/FAIL 结论。若 FAIL：返回结论中指出的 Agent（author 或 eval-curator），修复后重新运行 QA。最多重复一次；如果仍未通过，则停止并向维护者报告。
4. trigger-boundary-auditor — 仅当 description 字段有更改时运行。以只读方式审查六个已发布技能的触发范围，检查误触发和路由冲突。呈报审查结果；若发现真实冲突，则返回 skill-author 处理。
5. release-manager — 仅在请求发布时运行，且必须在 QA 通过后运行。通过 release 技能创建发行版。

阶段 3 — 报告与反馈

报告：运行的阶段、修改的文件、QA 结论、触发审查结果（如有）以及发布 URL（如有）。然后邀请维护者提供反馈："结果、Agent 角色或流水线顺序方面，有什么需要调整的吗？" 将采纳的更改记录在 AGENTS.md 的工作流变更日志表中。

此执行框架强制执行的约定

• 继承当前 Codex 模型和权限；不要选择 Claude 模型。
• consistency-qa 必须是 general-purpose（它会运行 npm 脚本）；trigger-boundary-auditor 仅具备只读权限。
• 不创建命令封装器——Codex 会发现 .agents/skills/。
• 直接发布到 main 遵循 AGENTS.md。仅在收到请求时才提交、推送、打标签或发布。运行明确的 validate/test/evals 检查门；Claude 全局规则和钩子不会在 Codex 中执行。

错误处理

• 某个阶段首次失败后，会将错误作为输入重试一次；若再次失败，则停止流水线并向维护者报告（不得静默跳过）。
• QA FAIL 后绝不继续发布。
• 报告冲突数据时需注明来源，不得删除。
• 高风险 git 操作（--no-verify、--force、重写历史）需要维护者明确授权——release-manager 会停止并询问。

测试场景

**正常流程——“添加 brooks-security 技能”：**第 1 阶段选择 author+eval+QA+audit。 skill-author 运行 new-skill brooks-security，创建 SKILL.md（包含一个针对同类技能划分边界的 “Do NOT trigger for:” 条款）和指南；eval-curator 添加一个 S-code 正向场景和一个误报场景；consistency-qa 运行检查门 → PASS；trigger-boundary-auditor 确认不会与 brooks-review/audit 冲突。报告列出文件和 PASS。

**错误流程——QA 检测到图书数量不一致而 FAIL：**维护者添加第十三本书，但只编辑 source-coverage.md。consistency-qa 的跨文档检查发现 README 仍写着 “twelve” → FAIL，问题归因于 skill-author。协调器循环处理；skill-author 更新 README/AGENTS/GEMINI 中的措辞；QA 重新运行 → PASS。由于未请求发布，流水线在第 3 阶段结束。