SKILL.md

$27

/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

Execution Steps

Step 0: Load Prior Review Context

Before reviewing, pull relevant learnings from prior code reviews and known patterns:

if command -v ao &#x26;>/dev/null; then

    ao lookup --query "<target-scope> code review patterns" --limit 3 2>/dev/null || true

fi

Apply retrieved knowledge (mandatory when results returned):

If learnings or patterns are returned, do NOT just load them as passive context. For each returned item:

Check: does this learning apply to the code under review? (answer yes/no)

If yes: include it as a known_risk in your review — state the pattern, what to look for, and whether the code exhibits it

Cite the learning by filename in your review output when it influences a finding

After applying, record the citation:

ao metrics cite "<learning-path>" --type applied 2>/dev/null || true

Skip silently if ao is unavailable or returns no results.

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.

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.5a: Structured Verification Path (--structured mode)

**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.

Step 1.5: Fast Path (--quick mode)

**If --quick flag is set**, skip Steps 2a through 2e as heavy pre-processing, plus 2.5 and 2f, and jump to Step 4 with inline council after Steps 2.3, 2.4, 2g, and Step 3. Domain checklists, compiled-prevention loading, test-pyramid inventory, and inline product context are cheap and high-value, so they still run in quick mode. Complexity analysis (Step 2) still runs — it's cheap and informative.

Why: Steps 2.5 and 2a–2f add 30–90 seconds of pre-processing that mainly feed multi-judge council packets. In --quick mode (single inline agent), those inputs are not worth the cost, but test-pyramid and product-context checks still shape the inline review meaningfully.

Step 2: Run Complexity Analysis

Read references/complexity-analysis.md when you need the language-detection preflight, per-language analyzer commands (radon/gocyclo), and the score interpretation table. Filter by language present in the diff before running any analyzer.

Step 2.3: Load Domain-Specific Checklists

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

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

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).

Steps 2.4-2f, 2h, 3-3.6 (Deep Checks & Pre-Council Prep): Read references/deep-checks.md for compiled prevention, prior findings, pre-council deep analysis checks, product context, spec loading, suppressions, pre-mortem correlation, and model cost tiers. Loaded automatically unless --quick mode is set. In --quick mode, skip directly to Step 2g.

Compiled prevention inputs: Load .agents/pre-mortem-checks/ and .agents/planning-rules/ when available. These compiled artifacts contain known_risks from prior findings that inform the review — carry matched finding IDs into council context so judges can assess whether the flywheel prevented rediscovery.

Step 2a: Prior Findings Check

**Skip if --quick.** Load prior findings from .agents/findings/registry.jsonl.

Step 2b: Constraint Tests

**Skip if --quick.** Run compiled constraint tests from .agents/constraints/.

Step 2c: Metadata Checks

**Skip if --quick.** Verify file metadata consistency.

Step 2.5: OL Validation

**Skip if --quick.** Run organizational-lint checks.

Step 2d: Knowledge Search

**Skip if --quick.** Search for relevant prior learnings via ao lookup.

Step 2e: Bug Hunt or Deep Audit Sweep

**Skip if --quick.**

**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

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 the council packet so judges shift to adjudication mode

Why: Generalist judges exhibit satisfaction bias — they stop after a small number of findings regardless of actual issue count. Per-file explorers with category checklists reduce that bias and surface concrete line-level issues before council adjudication.

**Path B — Lightweight Bug Hunt (default, no --deep/--sweep):**

Run proactive bug-hunt audit on target files.

Step 2f: Codex Review

**Skip if --quick.** When --mixed is passed and Codex CLI is available, send the first 2000 chars of the diff to Codex for a parallel review. Cap input at 2000 chars to stay within Codex context budgets.

Step 3: Product Context

**Skip if --quick as a separate judge-fanout step.** When PRODUCT.md exists and the user did not pass an explicit --preset override, quick mode still loads DX expectations inline in the single-agent review. In non-quick modes, add a DX (developer experience) judge: 2 independent + 1 DX judge (3 judges total). The DX judge evaluates whether the code aligns with the product's stated personas and value propositions.

Step 2g: Test Pyramid Inventory (MANDATORY)

Read references/test-pyramid-inventory.md when you need the full inventory procedure: per-module L0–L3 coverage checks, BF1–BF5 boundary checks, the weighted_score formula, satisfaction-score exposure, the council-packet test_pyramid JSON shape, and verdict rules. Runs in both --quick and full modes — file existence checks are cheap. Weight L0–L1 at 1x, L2 at 3x, L3+ at 5x; weighted_score < 0.3 with L0–L1 only is a WARN.

Step 4: Run Council Validation

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:

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=<name> (override perspectives), --explorers=N, --debate (adversarial 2-round), --tier=<name> (model cost tier: quality/balanced/budget). 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:

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-<target>.md (use date +%Y-%m-%d)

Read references/report-format.md for the full vibe report markdown template. The report includes: complexity analysis, council verdict table, shared/critical/informational findings, all findings (when --deep/--sweep), recommendation, and decision checkboxes.

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 & Step 9.5: Feed Findings to Flywheel

Read references/post-verdict-actions.md when you need the PASS/WARN/FAIL ratchet recording rules, the failure-retry finding extraction format, and the .agents/findings/registry.jsonl write contract (dedup_key, applicable_when vocabulary, atomic-rename rule) plus the hooks/finding-compiler.sh follow-up.

Step 10: Test Bead Cleanup

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.

Integration with Workflow

/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

Examples

User says: "Run a quick validation on the latest changes."

Do:

/vibe recent

Validate Recent Changes

/vibe recent

Runs complexity on recent changes, then council reviews.

Validate Specific Directory

/vibe src/auth/

Complexity + council on auth directory.

Deep Review

/vibe --deep recent

Complexity + 3 judges for thorough review.

Cross-Vendor Consensus

/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.

Troubleshooting

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 --mixed to enable. Also requires Codex CLI on PATH and uncommitted changes.

"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).

Write-Time Quality Hook

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: