Vibe Skill Purpose: Is this code ready to ship? Three steps: Complexity analysis — Find hotspots (radon, gocyclo) Bug hunt audit — Systematic sweep for concrete bugs Council validation — Multi-model judgment Quick Start /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 --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
Execution Steps Crank Checkpoint Detection 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. Step 1: Determine Target 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. Step 1.5: Fast Path (--quick mode) 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. 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. Step 2: Run Complexity Analysis 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. Step 2.5: Prior Findings Check Skip 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.
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 silently jq not on PATH → skip silently No unconsumed high-severity items found → skip (do not add empty prior_findings to packet) Step 2a: Run Constraint Tests 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. Step 2b: Metadata Verification Checklist (MANDATORY) Skip if --quick (see Step 1.5). Run mechanical checks BEFORE council — catches errors LLMs estimate instead of measure: File existence — every path in git diff --name-only HEAD~3 must exist on disk Line counts — if a file claims "N lines", verify with wc -l Cross-references — internal markdown links resolve to existing files Diagram sanity — files with >3 ASCII boxes should have matching labels Include failures in council packet as context.metadata_failures (MECHANICAL findings). If all pass, note in report. Step 2c: Deterministic Validation (Olympus) 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: Exit 0 (passed): Include the validation report section in vibe output and council context. Proceed normally. Exit 1 (failed): Auto-FAIL the vibe. Do NOT proceed to council. Exit 2 (skipped): Note "OL validation skipped" in report. Proceed to council. Step 2d: Codex Review (opt-in via --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" : "
" } 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 CLI not on PATH → skip silently codex review fails → skip silently, proceed with council only No uncommitted changes → skip (nothing to review) Step 2e: Search Knowledge Flywheel Skip if --quick (see Step 1.5). if command -v ao &> /dev/null ; then ao search "code review findings " 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. Step 2f: Bug Hunt or Deep Audit Sweep 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: Chunk target files into batches of 3–5 (by line count — see protocol for rules) Dispatch up to 8 Explore agents in parallel, each with a mandatory 8-category checklist per file Merge all explorer findings into a sweep manifest at .agents/council/sweep-manifest.md Include sweep manifest in council packet (judges shift to adjudication mode — see Step 4) Why: 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
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" : " " } 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) No source files in target → skip (nothing to audit) Target is non-code (pure docs/config) → skip Step 2g: Check for Product Context 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:
- Read
- PRODUCT.md
- content and include in the council packet via
- context.files
- Add a single consolidated
- developer-experience
- perspective to the council invocation:
- With spec:
- /council --preset=code-review --perspectives="developer-experience" validate
- (3 judges: 2 code-review + 1 DX)
- Without spec:
- /council --perspectives="developer-experience" validate
- (3 judges: 2 independent + 1 DX)
- The DX judge covers api-clarity, error-experience, and discoverability in a single review.
- With
- --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.md
- from
- docs/PRODUCT-TEMPLATE.md
- to enable developer-experience-aware code review.
- Step 3: Load the Spec (New)
- Skip if
- --quick
- (see Step 1.5).
- Before invoking council, try to find the relevant spec/bead:
- If target looks like a bead ID
- (e.g.,
- na-0042
- ):
- bd show
- to get the spec
- Search for plan doc:
- ls .agents/plans/ | grep
- Check git log:
- git log --oneline | head -10
- to find the relevant bead reference
- If a spec is found, include it in the council packet's
- context.spec
- field:
- {
- "spec"
- :
- {
- "source"
- :
- "bead na-0042"
- ,
- "content"
- :
- "
" - }
- }
- Step 4: Run Council Validation
- With spec found — use code-review preset:
- /council --preset=code-review validate
- 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
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: Files to review Complexity hotspots (from Step 2) Git diff context Spec content (when found, in context.spec ) Sweep manifest (when --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= (override perspectives), --explorers=N , --debate (adversarial 2-round). See Quick Start examples and /council docs. Step 5: Council Checks 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 Step 6: Interpret Verdict Council Verdict Vibe Result Action PASS Ready to ship Merge/deploy WARN Review concerns Address or accept risk FAIL Not ready Fix issues Step 7: Write Vibe Report Write to: .agents/council/YYYY-MM-DD-vibe- .md (use date +%Y-%m-%d )
id : council - YYYY - MM - DD - vibe - <target - slug
type : council date : YYYY - MM - DD
Vibe Report:
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
...
Concerns Raised
...
All Findings
Included when
--deepor--sweepproduces a sweep manifest. Lists ALL findingsfrom 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
Step 8: Report to User
Tell the user:
Complexity hotspots (if any)
Council verdict (PASS/WARN/FAIL)
Key concerns
Location of vibe report
Step 9: Record Ratchet Progress
After council verdict:
If verdict is PASS or WARN:
Run:
ao ratchet record vibe --output "