npx skills add https://github.com/boshu2/agentops --skill vibe用途: 这段代码可以交付了吗?
三个步骤:
/vibe # 验证最近的更改
/vibe recent # 同上
/vibe src/auth/ # 验证特定路径
/vibe --quick recent # 快速内联检查,不生成代理
/vibe --structured recent # 6阶段验证报告(构建→类型→lint→测试→安全→差异)
/vibe --deep recent # 3个法官而非2个
/vibe --sweep recent # 深度审计:每个文件的探索者 + 委员会
/vibe --mixed recent # 跨供应商(Claude + Codex)
/vibe --preset=security-audit src/auth/ # 聚焦安全的审查
/vibe --explorers=2 recent # 带有探索者子代理的法官
/vibe --debate recent # 两轮对抗性审查
/vibe --tier=quality recent # 为委员会调用使用质量层级
在审查之前,从先前的代码审查和已知模式中提取相关的学习成果:
if command -v ao &>/dev/null; then
ao lookup --query "<target-scope> code review patterns" --limit 3 2>/dev/null || true
fi
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
将任何相关的先前发现(例如,相同文件中反复出现的问题、已知的反模式)作为审查的上下文纳入。
项目审查者配置: 如果 .agents/reviewer-config.md 存在,其完整配置(reviewers、plan_reviewers、skip_reviewers)将被传递给委员会用于法官选择。参见 skills/council/SKILL.md 步骤 1b。
在通过 git diff 扫描更改的文件之前,检查是否存在 crank 检查点:
if [ -f .agents/vibe-context/latest-crank-wave.json ]; then
echo "Crank checkpoint found — using files_changed from checkpoint"
FILES_CHANGED=$(jq -r '.files_changed[]' .agents/vibe-context/latest-crank-wave.json 2>/dev/null)
WAVE_COUNT=$(jq -r '.wave' .agents/vibe-context/latest-crank-wave.json 2>/dev/null)
echo "Wave $WAVE_COUNT checkpoint: $(echo "$FILES_CHANGED" | wc -l | tr -d ' ') files changed"
fi
当 crank 检查点可用时,使用其 files_changed 列表,而不是通过 git diff 重新检测。这确保 vibe 验证的正是 crank 修改过的文件。
如果提供了目标: 直接使用它。
如果没有目标或目标是 "recent": 从 git 自动检测:
# 检查最近的提交
git diff --name-only HEAD~3 2>/dev/null | head -20
如果未找到任何内容,则询问用户。
预检:如果未找到文件: 立即返回:"PASS(无更改需要审查)— 未检测到修改的文件。" 对于空文件列表,请勿生成代理。
如果设置了 --structured 标志,则运行 6 阶段机械验证流水线,而不是委员会流程。这会生成适合 PR 门禁和 CI 集成的机器可读验证报告。
阶段:构建 → 类型 → Lint → 测试 → 安全 → 差异审查。
阅读 references/verification-report.md 以获取完整的报告模板和每个阶段的命令。每个阶段都是快速失败 — 如果构建失败,则跳过剩余阶段并报告 NOT READY。
所有阶段完成后,将结构化报告写入 .agents/council/YYYY-MM-DD-verification-<target>.md 并向用户输出摘要表格。
何时使用: PR 门禁前、CI 集成、当您需要机械性的通过/失败而非基于判断的审查时。
如果设置了 --quick 标志,则跳过步骤 2a 到 2e 以及 2.5/2f/2g(先前发现检查、约束测试、元数据检查、OL 验证、codex 审查、知识搜索、bug 搜索、产品上下文),并直接跳转到步骤 4 进行内联委员会。步骤 2.3(领域检查清单)和 2.4(发现注册表检查)在快速模式下仍会运行 — 领域检查清单加载成本低且价值高,可复用的审查发现是必需的上下文。复杂度分析(步骤 2)仍会运行 — 它成本低且信息丰富。
原因: 步骤 2.5 和 2a–2g 增加了 30–90 秒的预处理时间,这些预处理为多法官委员会数据包提供输入。在 --quick 模式(单个内联代理)下,这些输入不值得花费成本 — 内联审查者直接读取文件。
检测语言并运行相应的工具:
对于 Python:
# 检查 radon 是否可用
mkdir -p .agents/council
echo "$(date -Iseconds) preflight: checking radon" >> .agents/council/preflight.log
if ! which radon >> .agents/council/preflight.log 2>&1; then
echo "⚠️ COMPLEXITY SKIPPED: radon not installed (pip install radon)"
# 在报告中记录复杂度分析被跳过
else
# 运行圈复杂度
radon cc <path> -a -s 2>/dev/null | head -30
# 运行可维护性指数
radon mi <path> -s 2>/dev/null | head -30
fi
对于 Go:
# 检查 gocyclo 是否可用
echo "$(date -Iseconds) preflight: checking gocyclo" >> .agents/council/preflight.log
if ! which gocyclo >> .agents/council/preflight.log 2>&1; then
echo "⚠️ COMPLEXITY SKIPPED: gocyclo not installed (go install github.com/fzipp/gocyclo/cmd/gocyclo@latest)"
# 在报告中记录复杂度分析被跳过
else
# 运行复杂度分析
gocyclo -over 10 <path> 2>/dev/null | head -30
fi
对于其他语言: 跳过复杂度分析并明确说明:"⚠️ COMPLEXITY SKIPPED: No analyzer for "
解释结果:
| 分数 | 评级 | 操作 |
|---|---|---|
| A (1-5) | 简单 | 良好 |
| B (6-10) | 中等 | 可以 |
| C (11-20) | 复杂 | 标记给委员会 |
| D (21-30) | 非常复杂 | 建议重构 |
| F (31+) | 不可测试 | 必须重构 |
将复杂度发现包含在委员会上下文中。
检测目标文件中的代码模式,并从 standards/references/ 加载匹配的领域特定检查清单:
| 触发条件 | 检查清单 | 检测 |
|---|---|---|
| SQL/ORM 代码 | sql-safety-checklist.md | 文件包含 SQL 查询、ORM 导入(database/sql、sqlalchemy、prisma、activerecord、gorm、knex),或更改集中的迁移文件 |
| LLM/AI 代码 | llm-trust-boundary-checklist.md | 文件导入 anthropic、openai、google.generativeai,或匹配 *llm*、*prompt*、*completion* 模式 |
| 并发代码 | race-condition-checklist.md | 文件使用 goroutines、threading、asyncio、multiprocessing、sync.Mutex、concurrent.futures 或共享文件 I/O 模式 |
| Codex 技能 | codex-skill.md | skills-codex/ 下的文件,或匹配 *codex*SKILL.md、convert.sh、skills-codex-overrides/ 或转换器脚本的文件 |
对于每个匹配的检查清单,通过 Read 工具加载它,并将相关项作为 context.domain_checklists 包含在委员会数据包中。可以同时加载多个检查清单。
如果没有匹配的模式,则静默跳过。此步骤在 --quick 和完整模式下都会运行(领域检查清单加载成本低且价值高)。
在读取 .agents/rpi/next-work.jsonl 之前,当存在时,从 .agents/pre-mortem-checks/*.md 和 .agents/planning-rules/*.md 加载编译的预防上下文。这是审查的主要可复用预防表面。
使用 docs/contracts/finding-compiler.md 和 docs/contracts/finding-registry.md 中跟踪的合约:
applicable_when 重叠、语言重叠、更改文件重叠和目标文本字面重叠进行排序/plan 和 /pre-mortem 一致;不要发明单独的仅用于审查的启发式方法.agents/findings/registry.jsonl将匹配的条目作为 known_risks / 检查清单上下文包含在委员会数据包中,包含:
idpatterndetection_questionchecklist_item如果 --quick 则跳过(参见步骤 1.5)。
读取 .agents/rpi/next-work.jsonl 并查找与目标区域匹配的未消耗的 severity=high 项。将它们作为 context.prior_findings 包含在委员会数据包中,以便法官拥有延续的上下文。
将这些高严重性队列项视为在早期发现/规划/事前检查中使用的同一排序数据包的一部分。审查阶段应继承并完善先前的发现上下文,而不是从头开始重新检索。
# 计算未消耗的高严重性项数量
if [ -f .agents/rpi/next-work.jsonl ] && command -v jq &>/dev/null; then
prior_count=$(jq -s '[.[] | select(.consumed == false) | .items[] | select(.severity == "high")] | length' \
.agents/rpi/next-work.jsonl 2>/dev/null || echo 0)
if [ "$prior_count" -gt 0 ]; then
echo "Prior findings: $prior_count unconsumed high-severity items from next-work.jsonl"
jq -s '[.[] | select(.consumed == false) | .items[] | select(.severity == "high")]' \
.agents/rpi/next-work.jsonl 2>/dev/null
fi
fi
如果找到未消耗的高严重性项,将它们包含在委员会数据包上下文中:
"prior_findings": {
"source": ".agents/rpi/next-work.jsonl",
"count": 3,
"items": [/* array of high-severity unconsumed items */]
}
跳过条件:
--quick 模式 → 跳过.agents/rpi/next-work.jsonl 不存在 → 静默跳过jq 不在 PATH 中 → 静默跳过prior_findings)如果 --quick 则跳过(参见步骤 1.5)。
如果项目有约束测试,在委员会之前运行它们:
# 检查是否存在约束测试(Olympus 模式)
if [ -d "internal/constraints" ] && ls internal/constraints/*_test.go &>/dev/null; then
echo "Running constraint tests..."
go test ./internal/constraints/ -run TestConstraint -v 2>&1
# 如果 FAIL → 将失败包含在委员会上下文中作为 CRITICAL 发现
# 如果 PASS → 在报告中注明 "N constraint tests passed"
fi
原因: 约束测试捕获机械性违规(幽灵引用、TOCTOU 竞争、入口点的死代码),这些是委员会法官会遗漏的。由 Argus 幽灵引用在 ol-571 中证明 — 委员会给出了 PASS,而约束测试捕获了它。
将约束测试结果包含在委员会数据包上下文中。失败的约束测试是 CRITICAL 发现,会覆盖委员会 PASS 的裁决。
如果 --quick 则跳过(参见步骤 1.5)。
在委员会之前运行机械检查 — 捕获 LLM 估计而非测量的错误:
git diff --name-only HEAD~3 中的每个路径必须在磁盘上存在wc -l 验证将失败包含在委员会数据包中作为 context.metadata_failures(机械发现)。如果全部通过,则在报告中注明。
如果 --quick 则跳过(参见步骤 1.5)。
守卫: 仅当 .ol/config.yaml 存在 且 which ol 成功时运行。否则静默跳过。
实现:
# 运行 ol-validate.sh
skills/vibe/scripts/ol-validate.sh
ol_exit_code=$?
case $ol_exit_code in
0)
# 通过:将验证报告包含在 vibe 输出中
echo "✅ Deterministic validation passed"
# 将报告部分附加到委员会上下文和 vibe 报告中
;;
1)
# 失败:中止 vibe,给出 FAIL 裁决
echo "❌ Deterministic validation FAILED"
echo "VIBE FAILED — Olympus Stage1 validation did not pass"
exit 1
;;
2)
# 跳过:注明并继续
echo "⚠️ OL validation skipped"
# 继续到委员会
;;
esac
行为:
--mixed 选择加入)除非传递了 --mixed,否则跳过。 如果 --quick 也跳过(参见步骤 1.5)。
Codex 审查是选择加入的,因为它增加了 30–60 秒的延迟和令牌成本。用户通过 --mixed 明确请求跨供应商输入。
echo "$(date -Iseconds) preflight: checking codex" >> .agents/council/preflight.log
if which codex >> .agents/council/preflight.log 2>&1; then
codex review --uncommitted > .agents/council/codex-review-pre.md 2>&1 && \
echo "Codex review complete — output at .agents/council/codex-review-pre.md" || \
echo "Codex review skipped (failed)"
else
echo "Codex review skipped (CLI not found)"
fi
如果输出存在,进行总结并包含在委员会数据包中(限制在 2000 字符以内以防止上下文膨胀):
"codex_review": {
"source": "codex review --uncommitted",
"content": "<first 2000 chars of .agents/council/codex-review-pre.md>"
}
重要: 原始的 codex 审查可能超过 50k+ 字符。在每个法官的数据包中包含完整文本会使令牌成本乘以 N 个法官。截断到前 2000 个字符(覆盖摘要和主要发现)。如果法官需要更多细节,可以从磁盘读取完整文件。
这为委员会法官提供了 Codex 生成的审查作为预先存在的上下文 — 廉价、快速、专注于差异。它不取代委员会判断;而是增强它。
跳过条件:
--mixed → 跳过(仅选择加入)codex review 失败 → 静默跳过,仅继续委员会如果 --quick 则跳过(参见步骤 1.5)。
if command -v ao &>/dev/null; then
ao search "code review findings <target>" 2>/dev/null | head -10
fi
如果 ao 返回此区域的先前代码审查模式,则将它们包含在委员会数据包上下文中。如果 ao 不可用或未返回结果,则静默跳过。
如果 --quick 则跳过(参见步骤 1.5)。
路径 A — 深度审计扫描(--deep 或 --sweep):
阅读 references/deep-audit-protocol.md 以获取完整协议。总结如下:
.agents/council/sweep-manifest.md 的扫描清单中原因: 通才法官表现出满足偏差 — 无论实际问题数量如何,他们在大约 10 个发现处停止。具有类别检查清单的每个文件探索者消除了这种偏差,并在一次扫描中发现 3 倍多的问题。
路径 B — 轻量级 Bug 搜索(默认,无 --deep/--sweep):
在委员会审查之前对目标文件运行主动的 bug 搜索:
/bug-hunt --audit <target>
如果 bug-hunt 产生发现,则将它们作为 context.bug_hunt 包含在委员会数据包中:
"bug_hunt": {
"source": "/bug-hunt --audit",
"findings_count": 3,
"high": 1,
"medium": 1,
"low": 1,
"summary": "<first 2000 chars of bug hunt report>"
}
原因: Bug 搜索捕获具体的行级错误(资源泄漏、截断错误、死代码),这些是委员会法官 — 进行整体审查时 — 经常遗漏的。
跳过条件(两条路径):
--quick 模式 → 跳过(快速路径)根据测试金字塔标准(通过 /standards 加载的测试金字塔标准)评估测试覆盖率。
即使在 --quick 模式下也运行 — 这成本低(文件存在性检查)且信号强。
context.test_pyramid 包含在委员会数据包中:"test_pyramid": {
"coverage": {
"L0": {"status": "pass", "files": ["test_spec_enforcement.py"]},
"L1": {"status": "pass", "files": ["test_module.py"]},
"L2": {"status": "gap", "reason": "crosses subsystem boundary, no integration test"}
},
"bug_finding": {
"BF4_chaos": {"status": "gap", "reason": "external API calls without failure injection"},
"BF1_property": {"status": "na", "reason": "no data transformations in scope"}
},
"verdict": "WARN: L2 and BF4 gaps on boundary code"
}
裁决规则:
如果 --quick 则跳过(参见步骤 1.5)。
if [ -f PRODUCT.md ]; then
# PRODUCT.md 存在 — 包含开发者体验视角
fi
当 PRODUCT.md 存在于项目根目录 且 用户未传递显式的 --preset 覆盖时:
PRODUCT.md 内容并通过 context.files 包含在委员会数据包中developer-experience 视角:
/council --preset=code-review --perspectives="developer-experience" validate <target>(3 位法官:2 位代码审查 + 1 位 DX)/council --perspectives="developer-experience" validate <target>(3 位法官:2 位独立 + 1 位 DX)DX 法官在一次审查中覆盖 api-clarity、error-experience 和 discoverability。--deep 时:每种模式增加 1 位法官(总共 4 位法官)。当 PRODUCT.md 存在 但 用户传递了显式的 --preset 时:跳过 DX 自动包含(用户的显式预设优先)。
当 PRODUCT.md 不存在时:继续到步骤 3,不变。
提示: 从
docs/PRODUCT-TEMPLATE.md创建PRODUCT.md以启用开发者体验感知的代码审查。
如果 --quick 则跳过(参见步骤 1.5)。
在调用委员会之前,尝试查找相关的规范/bead:
na-0042):bd show <id> 以获取规范ls .agents/plans/ | grep <target-keyword>git log --oneline | head -10 以查找相关的 bead 引用如果找到规范,将其包含在委员会数据包的 context.spec 字段中:
{
"spec": {
"source": "bead na-0042",
"content": "<the spec/bead description text>"
}
}
在调用委员会之前,从 references/vibe-suppressions.md 加载默认抑制列表,并从 .agents/vibe-suppressions.jsonl 加载任何项目级别的覆盖。抑制规则在裁决后应用,以将发现分类为 CRITICAL 与 INFORMATIONAL,并过滤已知的误报。完整模式列表请参见 references/vibe-suppressions.md。
当存在当前史诗的事前检查报告时,加载用于下游关联的预测 ID:
# 查找最近的事前检查报告
PM_REPORT=$(ls -t .agents/council/*pre-mortem*.md 2>/dev/null | head -1)
if [ -n "$PM_REPORT" ]; then
# 从 frontmatter 中提取预测 ID
PREDICTION_IDS=$(sed -n '/^prediction_ids:/,/^[^ -]/p' "$PM_REPORT" | grep '^\s*-' | sed 's/^\s*- //')
fi
对于每个 vibe 发现,检查它是否匹配事前检查预测:
predicted_by: pm-YYYYMMDD-NNN 标记发现predicted_by: none 标记发现(意外问题)将预测关联包含在 vibe 报告的发现表中。这为事后检查的预测准确性部分提供数据。如果不存在事前检查报告,则静默跳过。
Vibe 将模型成本层级传递给委员会用于所有验证调用。层级解析:
/vibe 上的显式 --tier=<name> 标志.agentops/config.yaml 中的 models.skill_overrides.vibe.agentops/config.yaml 中的 models.default_tierbalanced# 示例:强制所有 vibe 审查使用质量层级
models:
skill_overrides:
vibe: quality
找到规范时 — 使用代码审查预设:
/council --preset=code-review validate <target>
error-paths:追踪每个错误处理路径。什么未被捕获?什么静默失败?api-surface:审查每个公共接口。合约是否清晰?是否有破坏性更改?spec-compliance:将实现与规范进行比较。缺少什么?有什么分歧?规范内容被注入到委员会数据包上下文中,以便 spec-compliance 法官可以将实现与之比较。
没有规范时 — 2 位独立法官(无视角):
/council validate <target>
2 位独立法官(无视角标签)。对于高风险审查,使用 --deep 获得 3 位法官。使用 --quick(内联单代理检查)或 --mixed(与 Codex 跨供应商)进行覆盖。
委员会接收:
context.spec 中)--deep 或 --sweep 时,在 context.sweep_manifest 中 — 法官切换到裁决模式,参见 references/deep-audit-protocol.md)所有委员会标志都会传递:--quick(内联)、--mixed(跨供应商)、--preset=<name>(覆盖视角)、--explorers=N、--debate(对抗性 2 轮)、--tier=<name>(模型成本层级:quality/balanced/budget)。参见快速开始示例和 /council 文档。
每位法官审查以下方面:
| 方面 | 需要关注什么 |
|---|---|
| 正确性 | 代码是否如其声称的那样工作? |
| 安全性 | 注入、身份验证问题、密钥 |
| 边界情况 | 空值处理、边界、错误 |
| 质量 | 死代码、重复、清晰度 |
| 复杂度 | 高圈复杂度分数、深度嵌套 |
| 架构 | 耦合、抽象、模式 |
| 委员会裁决 | Vibe 结果 | 操作 |
|---|---|---|
| PASS | 可以交付 | 合并/部署 |
| WARN | 审查有顾虑 | 解决或接受风险 |
| FAIL | 尚未就绪 | 修复问题 |
写入到: .agents/council/YYYY-MM-DD-vibe-<target>.md(使用 date +%Y-%m-%d)
---
id: council-YYYY-MM-DD-vibe-<target-slug>
type: council
date: YYYY-MM-DD
---
# Vibe Report: <Target>
**Files Reviewed:** <count>
## Complexity Analysis
**Status:** ✅ Completed | ⚠️ Skipped (<reason>)
| File | Score | Rating | Notes |
|------|-------|--------|-------|
| src/auth.py | 15 | C | Consider breaking up |
| src/utils.py | 4 | A | Good |
**Hotspots:** <list files with C or worse>
**Skipped reason:** <if skipped, explain why - e.g., "radon not installed">
## Council Verdict: PASS / WARN / FAIL
| Judge | Verdict | Key Finding |
|-------|---------|-------------|
| Error-Paths | ... | ... (with spec — code-review preset) |
| API-Surface | ... | ... (with spec — code-review preset) |
| Spec-Compliance | ... | ... (with spec — code-review preset) |
| Judge 1 | ... | ... (no spec — 2 independent judges) |
| Judge 2 | ... | ... (no spec — 2 independent judges) |
| Judge 3 | ... | ... (no spec — 2 independent judges) |
## Shared Findings
- ...
## CRITICAL Findings (blocks ship)
- ... (findings that indicate correctness, security, or data-safety issues)
## INFORMATIONAL Findings (include in PR body)
- ... (style suggestions, minor improvements, suppressed/downgraded items)
## Concerns Raised
- ...
## All Findings
> Included when `--deep` or `--sweep` produces a sweep manifest. Lists ALL findings
> from explorer sweep + council adjudication. Grouped by category if >20 findings.
| # | File | Line | Category | Severity | Description | Source |
|---|------|------|----------|----------|-------------|--------|
| 1 | ... | ... | ... | ... | ... | sweep / council |
## Recommendation
<council recommendation>
## Decision
[ ] SHIP - Complexity acceptable, council passed
[ ] FIX - Address concerns before shipping
[ ] REFACTOR - High complexity, needs rework
告知用户:
委员会裁决后:
ao ratchet record vibe --output "<report-path>" 2>/dev/null || true不记录棘轮进度。
从委员会报告中提取所有发现,用于结构化的重试上下文(如果超过 20 个,按类别分组):
Read the council report. For each finding, format as:
FINDING: <description> | FIX: <fix or recommendation> | REF: <ref or location>
Fallback for v1 findings (no fix/why/ref fields):
fix = finding.fix || finding.recommendation || "No fix specified"
ref = finding.ref || finding.location || "No reference"
告诉用户修复问题并重新运行 /vibe,并将格式化的发现作为可操作的指导包含在内。
如果裁决是 WARN 或 FAIL,将可复用的发现持久化到 .agents/findings/registry.jsonl,并可选地将更广泛的叙述镜像到学习文件中。
注册表写入规则:
dedup_key、来源、pattern、detection_question、checklist_item、applicable_when 和 confidenceapplicable_when 必须使用来自发现注册表合约的受控词汇dedup_key 追加或合并如果更广泛的散文摘要仍有帮助,也将现有的反模式学习文件写入 .agents/learnings/YYYY-MM-DD-vibe-<target>.md。如果裁决是 PASS,则跳过两者。
注册表更新后,如果 hooks/finding-compiler.sh 存在,则运行:
bash hooks/finding-compiler.sh --quiet 2>/dev/null || true
这使同一会话的事后检查路径与最新的可复用发现保持同步。session-end-maintenance.sh 仍然是幂等的后备方案。
验证完成后,通过 bd close 清理过时的测试 bead(bd list --status=open | grep -iE "test bead|test quest"),以防止 bead 污染。如果 bd 不可用,则跳过。
/implement issue-123
│
▼
(coding, quick lint/test as you go)
│
▼
/vibe ← 您在此处
│
├── Complexity analysis (find hotspots)
├── Bug hunt audit (find concrete bugs)
└── Council validation (multi-model judgment)
│
├── PASS → ship it
├── WARN → review, then ship or fix
└── FAIL → fix, re-run /vibe
用户说: "对最近的更改进行快速验证。"
执行:
/vibe recent
/vibe recent
对最近的更改运行复杂度分析,然后委员会审查。
/vibe src/auth/
对 auth 目录进行复杂度分析 + 委员会审查。
/vibe --deep recent
复杂度分析 + 3 位法官进行彻底审查。
/vibe --mixed recent
复杂度分析 + Claude + Codex 法官。
更多示例
Purpose: Is this code ready to ship?
Three steps:
/vibe # validates recent changes
/vibe recent # same as above
/vibe src/auth/ # validates specific path
/vibe --quick recent # fast inline check, no agent spawning
/vibe --structured recent # 6-phase verification report (build→types→lint→tests→security→diff)
/vibe --deep recent # 3 judges instead of 2
/vibe --sweep recent # deep audit: per-file explorers + council
/vibe --mixed recent # cross-vendor (Claude + Codex)
/vibe --preset=security-audit src/auth/ # security-focused review
/vibe --explorers=2 recent # judges with explorer sub-agents
/vibe --debate recent # two-round adversarial review
/vibe --tier=quality recent # use quality tier for council calls
Before reviewing, pull relevant learnings from prior code reviews and known patterns:
if command -v ao &>/dev/null; then
ao lookup --query "<target-scope> code review patterns" --limit 3 2>/dev/null || true
fi
Incorporate any relevant prior findings (e.g., recurring issues in the same files, known anti-patterns) as context for the review.
Project reviewer config: If .agents/reviewer-config.md exists, its full config (reviewers, plan_reviewers, skip_reviewers) is passed to council for judge selection. See skills/council/SKILL.md Step 1b.
Before scanning for changed files via git diff, check if a crank checkpoint exists:
if [ -f .agents/vibe-context/latest-crank-wave.json ]; then
echo "Crank checkpoint found — using files_changed from checkpoint"
FILES_CHANGED=$(jq -r '.files_changed[]' .agents/vibe-context/latest-crank-wave.json 2>/dev/null)
WAVE_COUNT=$(jq -r '.wave' .agents/vibe-context/latest-crank-wave.json 2>/dev/null)
echo "Wave $WAVE_COUNT checkpoint: $(echo "$FILES_CHANGED" | wc -l | tr -d ' ') files changed"
fi
When a crank checkpoint is available, use its files_changed list instead of re-detecting via git diff. This ensures vibe validates exactly the files that crank modified.
If target provided: Use it directly.
If no target or "recent": Auto-detect from git:
# Check recent commits
git diff --name-only HEAD~3 2>/dev/null | head -20
If nothing found, ask user.
Pre-flight: If no files found: Return immediately with: "PASS (no changes to review) — no modified files detected." Do NOT spawn agents for empty file lists.
If--structured flag is set, run a 6-phase mechanical verification pipeline instead of the council flow. This produces a machine-readable verification report suitable for PR gates and CI integration.
Phases: Build → Types → Lint → Tests → Security → Diff Review.
Read references/verification-report.md for the full report template and per-phase commands. Each phase is fail-fast — if Build fails, skip remaining phases and report NOT READY.
After all phases complete, write the structured report to .agents/council/YYYY-MM-DD-verification-<target>.md and output the summary table to the user.
When to use: Pre-PR gate, CI integration, when you need a mechanical pass/fail rather than judgment-based review.
If--quick flag is set, skip Steps 2a through 2e plus 2.5/2f/2g (prior findings check, constraint tests, metadata checks, OL validation, codex review, knowledge search, bug hunt, product context) and jump directly to Step 4 with inline council. Steps 2.3 (domain checklists) and 2.4 (finding registry check) still run in quick mode — domain checklists are cheap to load and high-value, and reusable review findings are mandatory context. Complexity analysis (Step 2) still runs — it's cheap and informative.
Why: Steps 2.5 and 2a–2g add 30–90 seconds of pre-processing that feed multi-judge council packets. In --quick mode (single inline agent), these inputs aren't worth the cost — the inline reviewer reads files directly.
Detect language and run appropriate tool:
For Python:
# Check if radon is available
mkdir -p .agents/council
echo "$(date -Iseconds) preflight: checking radon" >> .agents/council/preflight.log
if ! which radon >> .agents/council/preflight.log 2>&1; then
echo "⚠️ COMPLEXITY SKIPPED: radon not installed (pip install radon)"
# Record in report that complexity was skipped
else
# Run cyclomatic complexity
radon cc <path> -a -s 2>/dev/null | head -30
# Run maintainability index
radon mi <path> -s 2>/dev/null | head -30
fi
For Go:
# Check if gocyclo is available
echo "$(date -Iseconds) preflight: checking gocyclo" >> .agents/council/preflight.log
if ! which gocyclo >> .agents/council/preflight.log 2>&1; then
echo "⚠️ COMPLEXITY SKIPPED: gocyclo not installed (go install github.com/fzipp/gocyclo/cmd/gocyclo@latest)"
# Record in report that complexity was skipped
else
# Run complexity analysis
gocyclo -over 10 <path> 2>/dev/null | head -30
fi
For other languages: Skip complexity with explicit note: "⚠️ COMPLEXITY SKIPPED: No analyzer for "
Interpret results:
| Score | Rating | Action |
|---|---|---|
| A (1-5) | Simple | Good |
| B (6-10) | Moderate | OK |
| C (11-20) | Complex | Flag for council |
| D (21-30) | Very complex | Recommend refactor |
| F (31+) | Untestable | Must refactor |
Include complexity findings in council context.
Detect code patterns in the target files and load matching domain-specific checklists from standards/references/:
| Trigger | Checklist | Detection |
|---|---|---|
| SQL/ORM code | sql-safety-checklist.md | Files contain SQL queries, ORM imports (database/sql, sqlalchemy, prisma, activerecord, gorm, knex), or migration files in changeset |
| LLM/AI code | llm-trust-boundary-checklist.md |
For each matched checklist, load it via the Read tool and include relevant items in the council packet as context.domain_checklists. Multiple checklists can be loaded simultaneously.
Skip silently if no patterns match. This step runs in both --quick and full modes (domain checklists are cheap to load and high-value).
Before reading .agents/rpi/next-work.jsonl, load compiled prevention context from .agents/pre-mortem-checks/*.md and .agents/planning-rules/*.md when they exist. This is the primary reusable-prevention surface for review.
Use the tracked contracts in docs/contracts/finding-compiler.md and docs/contracts/finding-registry.md:
applicable_when overlap, language overlap, changed-file overlap, and literal target-text overlap/plan and /pre-mortem; do not invent a separate review-only heuristic.agents/findings/registry.jsonlInclude matched entries in the council packet as known_risks / checklist context with:
idpatterndetection_questionchecklist_itemSkip if--quick (see Step 1.5).
Read .agents/rpi/next-work.jsonl and find unconsumed items with severity=high that match the target area. Include them in the council packet as context.prior_findings so judges have carry-forward context.
Treat these high-severity queue items as part of the same ranked packet used earlier in discovery/plan/pre-mortem. The review stage should inherit and refine prior findings context, not restart retrieval from scratch.
# Count unconsumed high-severity items
if [ -f .agents/rpi/next-work.jsonl ] && command -v jq &>/dev/null; then
prior_count=$(jq -s '[.[] | select(.consumed == false) | .items[] | select(.severity == "high")] | length' \
.agents/rpi/next-work.jsonl 2>/dev/null || echo 0)
if [ "$prior_count" -gt 0 ]; then
echo "Prior findings: $prior_count unconsumed high-severity items from next-work.jsonl"
jq -s '[.[] | select(.consumed == false) | .items[] | select(.severity == "high")]' \
.agents/rpi/next-work.jsonl 2>/dev/null
fi
fi
If unconsumed high-severity items are found, include them in the council packet context:
"prior_findings": {
"source": ".agents/rpi/next-work.jsonl",
"count": 3,
"items": [/* array of high-severity unconsumed items */]
}
Skip conditions:
--quick mode → skip.agents/rpi/next-work.jsonl does not exist → skip silentlyjq not on PATH → skip silentlyprior_findings to packet)Skip if--quick (see Step 1.5).
If the project has constraint tests, run them before council:
# Check if constraint tests exist (Olympus pattern)
if [ -d "internal/constraints" ] && ls internal/constraints/*_test.go &>/dev/null; then
echo "Running constraint tests..."
go test ./internal/constraints/ -run TestConstraint -v 2>&1
# If FAIL → include failures in council context as CRITICAL findings
# If PASS → note "N constraint tests passed" in report
fi
Why: Constraint tests catch mechanical violations (ghost references, TOCTOU races, dead code at entry points) that council judges miss. Proven by Argus ghost ref in ol-571 — council gave PASS while constraint test caught it.
Include constraint test results in the council packet context. Failed constraint tests are CRITICAL findings that override council PASS verdict.
Skip if--quick (see Step 1.5).
Run mechanical checks BEFORE council — catches errors LLMs estimate instead of measure:
git diff --name-only HEAD~3 must exist on diskwc -lInclude failures in council packet as context.metadata_failures (MECHANICAL findings). If all pass, note in report.
Skip if--quick (see Step 1.5).
Guard: Only run when .ol/config.yaml exists AND which ol succeeds. Skip silently otherwise.
Implementation:
# Run ol-validate.sh
skills/vibe/scripts/ol-validate.sh
ol_exit_code=$?
case $ol_exit_code in
0)
# Passed: include the validation report in vibe output
echo "✅ Deterministic validation passed"
# Append the report section to council context and vibe report
;;
1)
# Failed: abort vibe with FAIL verdict
echo "❌ Deterministic validation FAILED"
echo "VIBE FAILED — Olympus Stage1 validation did not pass"
exit 1
;;
2)
# Skipped: note and continue
echo "⚠️ OL validation skipped"
# Continue to council
;;
esac
Behavior:
--mixed)Skip unless--mixed is passed. Also skip if --quick (see Step 1.5).
Codex review is opt-in because it adds 30–60s latency and token cost. Users explicitly request cross-vendor input with --mixed.
echo "$(date -Iseconds) preflight: checking codex" >> .agents/council/preflight.log
if which codex >> .agents/council/preflight.log 2>&1; then
codex review --uncommitted > .agents/council/codex-review-pre.md 2>&1 && \
echo "Codex review complete — output at .agents/council/codex-review-pre.md" || \
echo "Codex review skipped (failed)"
else
echo "Codex review skipped (CLI not found)"
fi
If output exists , summarize and include in council packet (cap at 2000 chars to prevent context bloat):
"codex_review": {
"source": "codex review --uncommitted",
"content": "<first 2000 chars of .agents/council/codex-review-pre.md>"
}
IMPORTANT: The raw codex review can be 50k+ chars. Including the full text in every judge's packet multiplies token cost by N judges. Truncate to the first 2000 chars (covers the summary and top findings). Judges can read the full file from disk if they need more detail.
This gives council judges a Codex-generated review as pre-existing context — cheap, fast, diff-focused. It does NOT replace council judgment; it augments it.
Skip conditions:
--mixed not passed → skip (opt-in only)codex review fails → skip silently, proceed with council onlySkip if--quick (see Step 1.5).
if command -v ao &>/dev/null; then
ao search "code review findings <target>" 2>/dev/null | head -10
fi
If ao returns prior code review patterns for this area, include them in the council packet context. Skip silently if ao is unavailable or returns no results.
Skip if--quick (see Step 1.5).
Path A — Deep Audit Sweep (--deep or --sweep):
Read references/deep-audit-protocol.md for the full protocol. In summary:
.agents/council/sweep-manifest.mdWhy: Generalist judges exhibit satisfaction bias — they stop at ~10 findings regardless of actual issue count. Per-file explorers with category checklists eliminate this bias and find 3x more issues in a single pass.
Path B — Lightweight Bug Hunt (default, no--deep/--sweep):
Run a proactive bug hunt on the target files before council review:
/bug-hunt --audit <target>
If bug-hunt produces findings, include them in the council packet as context.bug_hunt:
"bug_hunt": {
"source": "/bug-hunt --audit",
"findings_count": 3,
"high": 1,
"medium": 1,
"low": 1,
"summary": "<first 2000 chars of bug hunt report>"
}
Why: Bug hunt catches concrete line-level bugs (resource leaks, truncation errors, dead code) that council judges — reviewing holistically — often miss.
Skip conditions (both paths):
--quick mode → skip (fast path)Assess test coverage against the test pyramid standard (the test pyramid standard (loaded via /standards)).
Run even in--quick mode — this is cheap (file existence checks) and high-signal.
context.test_pyramid:"test_pyramid": {
"coverage": {
"L0": {"status": "pass", "files": ["test_spec_enforcement.py"]},
"L1": {"status": "pass", "files": ["test_module.py"]},
"L2": {"status": "gap", "reason": "crosses subsystem boundary, no integration test"}
},
"bug_finding": {
"BF4_chaos": {"status": "gap", "reason": "external API calls without failure injection"},
"BF1_property": {"status": "na", "reason": "no data transformations in scope"}
},
"verdict": "WARN: L2 and BF4 gaps on boundary code"
}
Verdict rules:
Skip if--quick (see Step 1.5).
if [ -f PRODUCT.md ]; then
# PRODUCT.md exists — include developer-experience perspectives
fi
When PRODUCT.md exists in the project root AND the user did NOT pass an explicit --preset override:
PRODUCT.md content and include in the council packet via context.filesdeveloper-experience perspective to the council invocation:
/council --preset=code-review --perspectives="developer-experience" validate <target> (3 judges: 2 code-review + 1 DX)/council --perspectives="developer-experience" validate <target> (3 judges: 2 independent + 1 DX) The DX judge covers api-clarity, error-experience, and discoverability in a single review.--deep: adds 1 more judge per mode (4 judges total).When PRODUCT.md exists BUT the user passed an explicit --preset: skip DX auto-include (user's explicit preset takes precedence).
When PRODUCT.md does not exist: proceed to Step 3 unchanged.
Tip: Create
PRODUCT.mdfromdocs/PRODUCT-TEMPLATE.mdto enable developer-experience-aware code review.
Skip if--quick (see Step 1.5).
Before invoking council, try to find the relevant spec/bead:
na-0042): bd show <id> to get the specls .agents/plans/ | grep <target-keyword>git log --oneline | head -10 to find the relevant bead referenceIf a spec is found, include it in the council packet's context.spec field:
{
"spec": {
"source": "bead na-0042",
"content": "<the spec/bead description text>"
}
}
Before invoking council, load the default suppression list from references/vibe-suppressions.md and any project-level overrides from .agents/vibe-suppressions.jsonl. Suppressions are applied post-verdict to classify findings as CRITICAL vs INFORMATIONAL and to filter known false positives. See references/vibe-suppressions.md for the full pattern list.
When a pre-mortem report exists for the current epic, load prediction IDs for downstream correlation:
# Find the most recent pre-mortem report
PM_REPORT=$(ls -t .agents/council/*pre-mortem*.md 2>/dev/null | head -1)
if [ -n "$PM_REPORT" ]; then
# Extract prediction IDs from frontmatter
PREDICTION_IDS=$(sed -n '/^prediction_ids:/,/^[^ -]/p' "$PM_REPORT" | grep '^\s*-' | sed 's/^\s*- //')
fi
For each vibe finding, check if it matches a pre-mortem prediction:
predicted_by: pm-YYYYMMDD-NNNpredicted_by: none (surprise issue)Include the prediction correlation in the vibe report's findings table. This feeds the post-mortem's Prediction Accuracy section. Skip silently if no pre-mortem report exists.
Vibe passes the model cost tier through to council for all validation calls. Tier resolution:
--tier=<name> flag on /vibemodels.skill_overrides.vibe in .agentops/config.yamlmodels.default_tier in .agentops/config.yamlbalanced# Example: force quality tier for all vibe reviews
models:
skill_overrides:
vibe: quality
With spec found — use code-review preset:
/council --preset=code-review validate <target>
error-paths: Trace every error handling path. What's uncaught? What fails silently?api-surface: Review every public interface. Is the contract clear? Breaking changes?spec-compliance: Compare implementation against the spec. What's missing? What diverges?The spec content is injected into the council packet context so the spec-compliance judge can compare implementation against it.
Without spec — 2 independent judges (no perspectives):
/council validate <target>
2 independent judges (no perspective labels). Use --deep for 3 judges on high-stakes reviews. Override with --quick (inline single-agent check) or --mixed (cross-vendor with Codex).
Council receives:
context.spec)--deep or --sweep, in context.sweep_manifest — judges shift to adjudication mode, see references/deep-audit-protocol.md)All council flags pass through: --quick (inline), --mixed (cross-vendor), --preset=<name> (override perspectives), --explorers=N, --debate (adversarial 2-round), --tier=<name> (model cost tier: quality/balanced/budget). See Quick Start examples and /council docs.
Each judge reviews for:
| Aspect | What to Look For |
|---|---|
| Correctness | Does code do what it claims? |
| Security | Injection, auth issues, secrets |
| Edge Cases | Null handling, boundaries, errors |
| Quality | Dead code, duplication, clarity |
| Complexity | High cyclomatic scores, deep nesting |
| Architecture | Coupling, abstractions, patterns |
| Council Verdict | Vibe Result | Action |
|---|---|---|
| PASS | Ready to ship | Merge/deploy |
| WARN | Review concerns | Address or accept risk |
| FAIL | Not ready | Fix issues |
Write to: .agents/council/YYYY-MM-DD-vibe-<target>.md (use date +%Y-%m-%d)
---
id: council-YYYY-MM-DD-vibe-<target-slug>
type: council
date: YYYY-MM-DD
---
# Vibe Report: <Target>
**Files Reviewed:** <count>
## Complexity Analysis
**Status:** ✅ Completed | ⚠️ Skipped (<reason>)
| File | Score | Rating | Notes |
|------|-------|--------|-------|
| src/auth.py | 15 | C | Consider breaking up |
| src/utils.py | 4 | A | Good |
**Hotspots:** <list files with C or worse>
**Skipped reason:** <if skipped, explain why - e.g., "radon not installed">
## Council Verdict: PASS / WARN / FAIL
| Judge | Verdict | Key Finding |
|-------|---------|-------------|
| Error-Paths | ... | ... (with spec — code-review preset) |
| API-Surface | ... | ... (with spec — code-review preset) |
| Spec-Compliance | ... | ... (with spec — code-review preset) |
| Judge 1 | ... | ... (no spec — 2 independent judges) |
| Judge 2 | ... | ... (no spec — 2 independent judges) |
| Judge 3 | ... | ... (no spec — 2 independent judges) |
## Shared Findings
- ...
## CRITICAL Findings (blocks ship)
- ... (findings that indicate correctness, security, or data-safety issues)
## INFORMATIONAL Findings (include in PR body)
- ... (style suggestions, minor improvements, suppressed/downgraded items)
## Concerns Raised
- ...
## All Findings
> Included when `--deep` or `--sweep` produces a sweep manifest. Lists ALL findings
> from explorer sweep + council adjudication. Grouped by category if >20 findings.
| # | File | Line | Category | Severity | Description | Source |
|---|------|------|----------|----------|-------------|--------|
| 1 | ... | ... | ... | ... | ... | sweep / council |
## Recommendation
<council recommendation>
## Decision
[ ] SHIP - Complexity acceptable, council passed
[ ] FIX - Address concerns before shipping
[ ] REFACTOR - High complexity, needs rework
Tell the user:
After council verdict:
ao ratchet record vibe --output "<report-path>" 2>/dev/null || trueDo NOT record ratchet progress.
Extract ALL findings from the council report for structured retry context (group by category if >20):
Read the council report. For each finding, format as:
FINDING: <description> | FIX: <fix or recommendation> | REF: <ref or location>
Fallback for v1 findings (no fix/why/ref fields):
fix = finding.fix || finding.recommendation || "No fix specified"
ref = finding.ref || finding.location || "No reference"
Tell user to fix issues and re-run /vibe, including the formatted findings as actionable guidance.
If verdict is WARN or FAIL , persist reusable findings to .agents/findings/registry.jsonl and optionally mirror the broader narrative to a learning file.
Registry write rules:
dedup_key, provenance, pattern, detection_question, checklist_item, applicable_when, and confidenceapplicable_when must use the controlled vocabulary from the finding-registry contractdedup_keyIf a broader prose summary still helps, also write the existing anti-pattern learning file to .agents/learnings/YYYY-MM-DD-vibe-<target>.md. Skip both if verdict is PASS.
After the registry update, if hooks/finding-compiler.sh exists, run:
bash hooks/finding-compiler.sh --quiet 2>/dev/null || true
This keeps the same-session post-mortem path synchronized with the latest reusable findings. session-end-maintenance.sh remains the idempotent backstop.
After validation completes, clean up stale test beads (bd list --status=open | grep -iE "test bead|test quest") via bd close to prevent bead pollution. Skip if bd unavailable.
/implement issue-123
│
▼
(coding, quick lint/test as you go)
│
▼
/vibe ← You are here
│
├── Complexity analysis (find hotspots)
├── Bug hunt audit (find concrete bugs)
└── Council validation (multi-model judgment)
│
├── PASS → ship it
├── WARN → review, then ship or fix
└── FAIL → fix, re-run /vibe
User says: "Run a quick validation on the latest changes."
Do:
/vibe recent
/vibe recent
Runs complexity on recent changes, then council reviews.
/vibe src/auth/
Complexity + council on auth directory.
/vibe --deep recent
Complexity + 3 judges for thorough review.
/vibe --mixed recent
Complexity + Claude + Codex judges.
See references/examples.md for additional examples: security audit with spec compliance, developer-experience code review with PRODUCT.md, and fast inline checks.
| Problem | Cause | Solution |
|---|---|---|
| "COMPLEXITY SKIPPED: radon not installed" | Python complexity analyzer missing | Install with pip install radon or skip complexity (council still runs). |
| "COMPLEXITY SKIPPED: gocyclo not installed" | Go complexity analyzer missing | Install with go install github.com/fzipp/gocyclo/cmd/gocyclo@latest or skip. |
| Vibe returns PASS but constraint tests fail | Council LLMs miss mechanical violations | Check .agents/council/<timestamp>-vibe-*.md for constraint test results. Failed constraints override council PASS. Fix violations and re-run. |
| Codex review skipped | --mixed not passed, Codex CLI not on PATH, or no uncommitted changes | Codex review is opt-in — pass to enable. Also requires Codex CLI on PATH and uncommitted changes. |
The hooks/write-time-quality.sh PostToolUse hook runs automatically after every Write/Edit tool call, catching common anti-patterns at edit time rather than review time. It checks:
fmt.Print in library codeexcept:, eval/exec, missing type hints on public functionsset -euo pipefail, unquoted variablesThe hook is non-blocking (always exits 0) and outputs warnings via JSON. See references/write-time-quality.md for the full design.
skills/council/SKILL.md — Multi-model validation councilskills/complexity/SKILL.md — Standalone complexity analysisskills/bug-hunt/SKILL.md — Proactive code audit and bug investigation.agents/specs/conflict-resolution-algorithm.md — Conflict resolution between agent findingsWeekly Installs
274
Repository
GitHub Stars
220
First Seen
Feb 2, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
opencode271
codex269
github-copilot267
gemini-cli267
kimi-cli263
amp263
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
106,200 周安装
短视频脚本生成器 - 为YouTube Shorts/Reels创作病毒式个性驱动脚本,避免AI陈词滥调
270 周安装
客户成功管理全流程指南:从客户入职、健康度评分到留存策略
271 周安装
Claude Code技能智能路由器 - 分析需求推荐最佳开发技能工具
271 周安装
Apollo Kotlin:Android与JVM的强类型GraphQL客户端,支持Kotlin多平台
271 周安装
专业图表创建工具 - 支持Mermaid/PlantUML生成流程图、架构图、UML图
271 周安装
Voicebox 开源语音合成与克隆工具:本地化 TTS 工作室,替代 ElevenLabs
271 周安装
Files import anthropic, openai, google.generativeai, or match *llm*, *prompt*, *completion* patterns |
| Concurrent code | race-condition-checklist.md | Files use goroutines, threading, asyncio, multiprocessing, sync.Mutex, concurrent.futures, or shared file I/O patterns |
| Codex skills | codex-skill.md | Files under skills-codex/, or files matching *codex*SKILL.md, convert.sh, skills-codex-overrides/, or converter scripts |
--mixed| "No modified files detected" | Clean working tree, no recent commits | Make changes or specify target path explicitly: /vibe src/auth/. |
| Spec-compliance judge not spawned | No spec found in beads/plans | Reference bead ID in commit message or create plan doc in .agents/plans/. Without spec, vibe uses 2 independent judges (3 with --deep). |