pre-publish-review

发布前审查——12 Agent 发布门禁

发布到 npm 前进行三层 Agent 审查。每一层都从不同角度进行审查，并将每项结果映射到下方的发布层。

层级	Agent	类型	检查内容
单项变更深度审查	最多 10 个	ultrabrain	分别审查每个逻辑变更组——正确性、边界情况、模式遵循情况
全面审查	1 个（+ 协调器 QA）	review-work	由审查协调器进行人工 QA，然后由一名门禁审查员全面审查目标符合度、代码质量、安全性，以及整个变更集是否遗漏了上下文
发布综合评估	1 个	oracle	整体发布就绪情况、版本升级、破坏性变更、部署风险

发布层级分类

每个阶段都会对以下各层的证据和风险进行分类：

发布层级	范围	必需的版本决策
omo pure components	核心包、MCP 包、共享技能、可复用脚本、平台二进制文件输入	评估适配器所使用的共享逻辑对补丁版本、次版本或主版本的影响。
omo opencode	根目录下的 oh-my-opencode / oh-my-openagent、src/、OpenCode 插件钩子/工具/CLI/配置/文档、.opencode/、.agents/	为 OpenCode/OpenAgent npm 发布确定 Semver 版本升级。
omo codex	packages/omo-codex、lazycodex-ai、Codex 插件元数据/钩子、捆绑的 MCP 运行时、code-yeongyu/lazycodex 市场载荷	确定 Codex 适配器版本升级、LazyCodex npm 发布风险，以及是否需要市场/GitHub 发布。

---

阶段 0：检测尚未发布的变更

首先运行 /get-unpublished-changes。这是变更情况的唯一可信来源，必须包含 omo pure components、omo opencode 和 omo codex 各层的版本建议。

skill(name="get-unpublished-changes")

此命令会自动：

• 检测已发布的 npm 版本与本地版本
• 列出上次发布以来的所有提交
• 读取实际差异（而不只是提交消息）来描述实际变更
• 按类型（feat/fix/refactor/docs）和范围对变更分组
• 识别破坏性变更
• 为各层推荐版本升级，并提供一个整体工作流版本升级建议

保存完整输出——它将直接用于阶段 1 的分组和所有 Agent 提示词。

然后收集 Agent 提示词所需的原始数据：

# Extract versions (already in /get-unpublished-changes output)
PUBLISHED=$(npm view oh-my-opencode version 2>/dev/null || echo "not published")
LOCAL=$(node -p "require('./package.json').version" 2>/dev/null || echo "unknown")

# Raw data for agents (diffs, file lists)
COMMITS=$(git log "v${PUBLISHED}"..HEAD --oneline 2>/dev/null || echo "no commits")
COMMIT_COUNT=$(echo "$COMMITS" | wc -l | tr -d ' ')
DIFF_STAT=$(git diff "v${PUBLISHED}"..HEAD --stat 2>/dev/null || echo "no diff")
CHANGED_FILES=$(git diff --name-only "v${PUBLISHED}"..HEAD 2>/dev/null || echo "none")
FILE_COUNT=$(echo "$CHANGED_FILES" | wc -l | tr -d ' ')

如果 PUBLISHED 为“未发布”，则这是首次发布——请改用完整的 Git 历史记录。

阶段 1：将变更解析为分组

以 /get-unpublished-changes 的输出作为起点——它已经按范围和类型进行了分组。

分组策略：

1. 从 /get-unpublished-changes 的分析结果开始，该结果已经按 feat/fix/refactor/docs 和范围进行了分类
2. 进一步按模块/领域拆分——涉及同一模块或功能领域的变更应归为一组
3. 目标为最多 10 组。如果提交少于 10 个，则每个提交单独成组。如果逻辑领域超过 10 个，则合并最小的组。
4. 对于每组，提取：
   • 组名：简短的描述性标签（例如，“agent-model-resolution”、“hook-system-refactor”）
   • 发布层级：omo pure components、omo opencode、omo codex
   • 提交：提交哈希和消息列表
   • 文件：此组中更改的文件
   • 差异：完整差异中相关的部分（git diff v${PUBLISHED}..HEAD -- {group files}）

---

阶段 2：启动所有 Agent

在单个轮次中启动所有 Agent。每个 Agent 都使用 run_in_background=true。不得按顺序逐个启动。

层级 1：Ultrabrain 单项变更分析（最多 10 个）

针对每个变更组，启动一个 ultrabrain Agent。每个 Agent 只获取其对应部分的差异，而不是完整变更集。

task(
  category="ultrabrain",
  model="gpt-5.6-sol",
  run_in_background=true,
  load_skills=[],
  description="Deep analysis: {GROUP_NAME}",
  prompt="""
<review_type>PER-CHANGE DEEP ANALYSIS</review_type>
<change_group>{GROUP_NAME}</change_group>

<project>oh-my-opencode (npm package)</project>
<published_version>{PUBLISHED}</published_version>
<target_version>{LOCAL}</target_version>

<commits>
{GROUP_COMMITS — hash and message for each commit in this group}
</commits>

<changed_files>
{GROUP_FILES — files changed in this group}
</changed_files>

<diff>
{GROUP_DIFF — only the diff for this group's files}
</diff>

<file_contents>
{Read and include full content of each changed file in this group}
</file_contents>

You are reviewing a specific subset of changes heading into an npm release. Focus exclusively on THIS change group. Other groups are reviewed by parallel agents.

ANALYSIS CHECKLIST:

1. **Intent Clarity**: What is this change trying to do? Is the intent clear from the code and commit messages? If you have to guess, that's a finding.

2. **Correctness**: Trace through the logic for 3+ scenarios. Does the code actually do what it claims? Off-by-one errors, null handling, async edge cases, resource cleanup.

3. **Breaking Changes**: Does this change alter any public API, config format, CLI behavior, or hook contract? If yes, is it backward compatible? Would existing users be surprised?

4. **Pattern Adherence**: Does the new code follow the established patterns visible in the existing file contents? New patterns where old ones exist = finding.

5. **Edge Cases**: What inputs or conditions would break this? Empty arrays, undefined values, concurrent calls, very large inputs, missing config fields.

6. **Error Handling**: Are errors properly caught and propagated? No empty catch blocks? No swallowed promises?

7. **Type Safety**: Any `as any`, `@ts-ignore`, `@ts-expect-error`? Loose typing where strict is possible?

8. **Test Coverage**: Are the behavioral changes covered by tests? Are the tests meaningful or just coverage padding?

9. **Side Effects**: Could this change break something in a different module? Check imports and exports — who depends on what changed?

10. **Release Risk**: On a scale of SAFE / CAUTION / RISKY — how confident are you this change won't cause issues in production?

OUTPUT FORMAT:
<group_name>{GROUP_NAME}</group_name>
<verdict>PASS or FAIL</verdict>
<risk>SAFE / CAUTION / RISKY</risk>
<summary>2-3 sentence assessment of this change group</summary>
<has_breaking_changes>YES or NO</has_breaking_changes>
<breaking_change_details>If YES, describe what breaks and for whom</breaking_change_details>
<findings>
  For each finding:
  - [CRITICAL/MAJOR/MINOR] Category: Description
  - File: path (line range)
  - Evidence: specific code reference
  - Suggestion: how to fix
</findings>
<blocking_issues>Issues that MUST be fixed before publish. Empty if PASS.</blocking_issues>
""")

第 2 层：通过 /review-work 进行全面审查（单一把关审查员）

启动一个加载 /review-work 技能的子 Agent。review-work 技能会在实际界面上执行手动 QA，然后启动一位把关审查员（oracle），审核目标合规性、代码质量、安全性、遗漏的上下文以及 QA 证据。只有 QA 矩阵无问题且审查结果为 APPROVE，审查才算通过。

task(
  category="unspecified-high",
  model="gpt-5.6-sol",
  run_in_background=true,
  load_skills=["review-work"],
  description="Run /review-work on all unpublished changes",
  prompt="""
Run /review-work on the unpublished changes between v{PUBLISHED} and HEAD.

GOAL: Review all changes heading into npm publish of oh-my-opencode. These changes span {COMMIT_COUNT} commits across {FILE_COUNT} files.

CONSTRAINTS:
- This is a plugin published to npm — public API stability matters
- TypeScript strict mode, Bun runtime
- No `as any`, `@ts-ignore`, `@ts-expect-error`
- Factory pattern (createXXX) for tools, hooks, agents
- kebab-case files, barrel exports, no catch-all files

BACKGROUND: Pre-publish review of oh-my-opencode, an OpenCode plugin with 1268 TypeScript files, 160k LOC. Changes since v{PUBLISHED} are about to be published.

The diff base is: git diff v{PUBLISHED}..HEAD

Follow the /review-work skill flow exactly — run the manual QA phase, launch the gate reviewer, and collect its verdict. Do NOT skip the QA phase or the reviewer.
""")

第 3 层：Oracle 发布综合评估（1 个 Agent）

oracle 会掌握全貌——所有提交、完整的 diff 统计信息以及变更文件列表，并给出最终的发布就绪度评估。

task(
  subagent_type="oracle",
  model="gpt-5.6-sol",
  run_in_background=true,
  load_skills=[],
  description="Oracle: overall release synthesis and version bump recommendation",
  prompt="""
<review_type>RELEASE SYNTHESIS — OVERALL ASSESSMENT</review_type>

<project>oh-my-opencode (npm package)</project>
<published_version>{PUBLISHED}</published_version>
<local_version>{LOCAL}</local_version>

<all_commits>
{ALL COMMITS since published version — hash, message, author, date}
</all_commits>

<diff_stat>
{DIFF_STAT — files changed, insertions, deletions}
</diff_stat>

<changed_files>
{CHANGED_FILES — full list of modified file paths}
</changed_files>

<full_diff>
{FULL_DIFF — the complete git diff between published version and HEAD}
</full_diff>

<file_contents>
{Read and include full content of KEY changed files — focus on public API surfaces, config schemas, agent definitions, hook registrations, tool registrations}
</file_contents>

You are the final gate before an npm publish. 10 ultrabrain agents are reviewing individual changes and the review-work gate reviewer is doing the holistic review. Your job is the bird's-eye view that those focused reviews might miss.

SYNTHESIS CHECKLIST:

1. **Release Coherence**: Do these changes tell a coherent story? Or is this a grab-bag of unrelated changes that should be split into multiple releases?

2. **Version Bump**: Based on semver:
   - PATCH: Bug fixes only, no behavior changes
   - MINOR: New features, backward-compatible changes
   - MAJOR: Breaking changes to public API, config format, or behavior
   Recommend the correct bump for each release layer and the overall workflow with specific justification.

3. **Breaking Changes Audit**: Exhaustively list every change that could break existing users. Check:
   - Config schema changes (new required fields, removed fields, renamed fields)
   - Agent behavior changes (different prompts, different model routing)
   - Hook contract changes (new parameters, removed hooks, renamed hooks)
   - Tool interface changes (new required params, different return types)
   - CLI changes (new commands, changed flags, different output)
   - Skill format changes (SKILL.md schema changes)

4. **Migration Requirements**: If there are breaking changes, what migration steps do users need? Is there auto-migration in place?

5. **Dependency Changes**: New dependencies added? Dependencies removed? Version bumps? Any supply chain risk?

6. **Changelog Draft**: Write a draft changelog entry grouped by:
   - feat: New features
   - fix: Bug fixes
   - refactor: Internal changes (no user impact)
   - breaking: Breaking changes with migration instructions
   - docs: Documentation changes

7. **Deployment Risk Assessment**:
   - SAFE: Routine changes, well-tested, low risk
   - CAUTION: Significant changes but manageable risk
   - RISKY: Large surface area changes, insufficient testing, or breaking changes without migration
   - BLOCK: Critical issues found, do NOT publish

8. **Post-Publish Monitoring**: What should be monitored after publish? Error rates, specific features, user feedback channels.

OUTPUT FORMAT:
<verdict>SAFE / CAUTION / RISKY / BLOCK</verdict>
<recommended_version_bump>PATCH / MINOR / MAJOR</recommended_version_bump>
<layer_specific_version_bump>omo pure components: PATCH/MINOR/MAJOR; omo opencode: PATCH/MINOR/MAJOR; omo codex: PATCH/MINOR/MAJOR</layer_specific_version_bump>
<version_bump_justification>Why this bump level</version_bump_justification>
<release_coherence>Assessment of whether changes belong in one release</release_coherence>
<breaking_changes>
  Exhaustive list, or "None" if none.
  For each:
  - What changed
  - Who is affected
  - Migration steps
</breaking_changes>
<changelog_draft>
  Ready-to-use changelog entry
</changelog_draft>
<deployment_risk>
  Overall risk assessment with specific concerns
</deployment_risk>
<monitoring_recommendations>
  What to watch after publish
</monitoring_recommendations>
<blocking_issues>Issues that MUST be fixed before publish. Empty if SAFE.</blocking_issues>
""")

---

第 3 阶段：收集结果

随着 Agent 完成工作（系统通知），通过 background_output(task_id="...") 收集结果。

在表格中跟踪完成情况：

#	Agent	类型	状态	结论
1-10	Ultrabrain: {group_name}	ultrabrain	待处理	—
11	Review-Work Coordinator	unspecified-high	待处理	—
12	Release Synthesis Oracle	oracle	待处理	—

在所有 Agent 完成之前，不要提交最终报告。

---

第 4 阶段：最终结论

<verdict_logic>

BLOCK，如果：

• Oracle 的结论为 BLOCK
• 任一 ultrabrain 发现了 CRITICAL 级阻塞问题
• Review-work 在任何 MAIN Agent 上未能通过

RISKY，如果：

• Oracle 的结论为 RISKY
• 多个 ultrabrain 返回 CAUTION 或 FAIL
• Review-work 虽然通过，但发现了重大问题

CAUTION，如果：

• Oracle 的结论为 CAUTION
• 少数 ultrabrain 标记了轻微问题
• Review-work 顺利通过

SAFE，如果：

• Oracle 的结论为 SAFE
• 所有 ultrabrain 均通过
• Review-work 通过

</verdict_logic>

整理最终报告：

# Pre-Publish Review — oh-my-opencode

## Release: v{PUBLISHED} -> v{LOCAL}
**Commits:** {COMMIT_COUNT} | **Files Changed:** {FILE_COUNT} | **Agents:** {AGENT_COUNT}

---

## Overall Verdict: SAFE / CAUTION / RISKY / BLOCK

## Recommended Version Bump: PATCH / MINOR / MAJOR
{Justification from Oracle}

## Layer-specific Version Recommendation

| Layer | Recommendation | Reason |
|---|---|---|
| omo pure components | PATCH/MINOR/MAJOR | ... |
| omo opencode | PATCH/MINOR/MAJOR | ... |
| omo codex | PATCH/MINOR/MAJOR | ... |

---

## Per-Change Analysis (Ultrabrains)

| # | Change Group | Verdict | Risk | Breaking? | Blocking Issues |
|---|-------------|---------|------|-----------|-----------------|
| 1 | {name} | PASS/FAIL | SAFE/CAUTION/RISKY | YES/NO | {count or "none"} |
| ... | ... | ... | ... | ... | ... |

### Blocking Issues from Per-Change Analysis
{Aggregated from all ultrabrains — deduplicated}

---

## Holistic Review (Review-Work)

| # | Review Area | Verdict | Confidence |
|---|------------|---------|------------|
| 1 | Manual QA (orchestrator, real surface) | PASS/FAIL | - |
| 2 | Gate Review (goal, code quality, security, context, QA audit) | APPROVE/REJECT | HIGH/MED/LOW |

### Blocking Issues from Holistic Review
{Aggregated from review-work}

---

## Release Synthesis (Oracle)

### Breaking Changes
{From Oracle — exhaustive list or "None"}

### Changelog Draft
{From Oracle — ready to use}

### Deployment Risk
{From Oracle — specific concerns}

### Post-Publish Monitoring
{From Oracle — what to watch}

---

## All Blocking Issues (Prioritized)
{Deduplicated, merged from all three layers, ordered by severity}

## Recommendations
{If BLOCK/RISKY: exactly what to fix, in priority order}
{If CAUTION: suggestions worth considering before publish}
{If SAFE: non-blocking improvements for future}

---

反模式

违规行为	严重程度
未等待所有 Agent 完成就发布	CRITICAL
按顺序而非并行方式启动 ultrabrain	CRITICAL
对任何 Agent 使用 run_in_background=false	CRITICAL
跳过 Oracle 综合评估	HIGH
未读取 Oracle 所需的文件内容（它无法读取文件）	HIGH
将所有变更集中给 1-2 个 ultrabrain，而不是分散处理	HIGH
在所有 Agent 完成前给出结论	HIGH
未在 ultrabrain 提示词中包含 diff	MAJOR