Vibe Skill

Purpose: Is this code ready to ship?

Three steps:

1. Complexity analysis — Find hotspots (radon, gocyclo)
2. Bug hunt audit — Systematic sweep for concrete bugs
3. 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 --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 &>/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:

1. Check: does this learning apply to the code under review? (answer yes/no)
2. If yes: include it as a

   known_risk

   in your review — state the pattern, what to look for, and whether the code exhibits it
3. 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

reviewers

plan_reviewers

skip_reviewers

skills/council/SKILL.md

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

git diff

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

Phases: Build → Types → Lint → Tests → Security → Diff Review.

Read

references/verification-report.md

After all phases complete, write the structured report to

.agents/council/YYYY-MM-DD-verification-<target>.md

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

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

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 <language>"

Interpret results:

Include complexity findings in council context.

Step 2.3: Load Domain-Specific Checklists

Detect code patterns in the target files and load matching domain-specific checklists from

standards/references/

sql-safety-checklist.md

database/sql

sqlalchemy

prisma

activerecord

gorm

knex

llm-trust-boundary-checklist.md

anthropic

openai

google.generativeai

*llm*

*prompt*

*completion*

race-condition-checklist.md

threading

asyncio

multiprocessing

sync.Mutex

concurrent.futures

codex-skill.md

skills-codex/

*codex*SKILL.md

convert.sh

skills-codex-overrides/

For each matched checklist, load it via the Read tool and include relevant items in the council packet as

context.domain_checklists

Skip silently if no patterns match. This step runs in both

--quick

Steps 2.4-2f, 2h, 3-3.6 (Deep Checks & Pre-Council Prep): Read

references/deep-checks.md

--quick

--quick

Compiled prevention inputs: Load

.agents/pre-mortem-checks/

.agents/planning-rules/

Step 2a: Prior Findings Check

Skip if

--quick

.agents/findings/registry.jsonl

Step 2b: Constraint Tests

Skip if

--quick

.agents/constraints/

Step 2c: Metadata Checks

Skip if

--quick

Step 2.5: OL Validation

Skip if

--quick

Step 2d: Knowledge Search

Skip if

--quick

ao lookup

Step 2e: Bug Hunt

Skip if

--quick

Step 2f: Codex Review

Skip if

--quick

--mixed

Step 3: Product Context

Skip if

--quick

PRODUCT.md

--preset

Step 2g: Test Pyramid Inventory (MANDATORY)

Assess test coverage against the test pyramid standard (the test pyramid standard (loaded via

/standards

Read

skills/vibe/references/test-pyramid-weighting.md

Test Pyramid Weighting: Weight test coverage by level: L0–L1 at 1x, L2 at 3x, L3+ at 5x. Unit-only coverage is a WARN signal, not a PASS. See

references/test-pyramid-weighting.md

Run even in

--quick

1. Identify changed modules from git diff or target scope

2. For each changed module, check coverage pyramid (L0–L3):

   • L0: Does a contract/spec enforcement test cover this module?
   • L1: Does a unit test file exist for this module?
   • L2: If module crosses boundaries, does an integration test exist?

3. For boundary-touching code, check bug-finding pyramid (BF1–BF5):

   • BF4 (Chaos): Do external call sites have failure injection tests?
   • BF1 (Property): Do data transformations have property tests?
   • BF2 (Golden): Do output generators have golden file tests?

4. Compute weighted pyramid score for changed code paths:

   Formula:

   weighted_score = (L0_count x 1 + L1_count x 1 + L2_count x 3 + L3_count x 5 + L4_count x 5) / max_possible
   

   Where

   max_possible = total_test_count x 5

   (the score if every test were L3+).

   Count tests at each level for changed code paths:

   • L0: Build/compile checks (weight 1)
   • L1: Unit tests (weight 1)
   • L2: Integration tests (weight 3)
   • L3: E2E/system tests (weight 5)
   • L4: Smoke/fresh-context tests (weight 5)

   Interpretation:

   • weighted_score >= 0.6

     — strong pyramid, L2+ tests present

   • 0.3 <= weighted_score < 0.6

     — acceptable, but recommend more integration tests

   • weighted_score < 0.3

     AND all tests are L0-L1 only — WARN: unit-only test coverage (feeds into vibe verdict as a WARN signal, not a separate gate)

   Satisfaction exposure: The

   weighted_score

   is also exposed as

   satisfaction_score

   (with source

   "test-pyramid-weighted"

   ) in the test_pyramid output block AND promoted to the top-level verdict JSON as

   satisfaction_score

   (verdict schema field,

   skills/council/schemas/verdict.json

   : number 0.0-1.0, "Probabilistic satisfaction score (0.0 = unsatisfied, 1.0 = fully satisfied). Optional — absent means not computed."). Downstream consumers (e.g.,

   /validation

   STEP 1.8 holdout evaluation) can use

   satisfaction_score

   as a normalized quality signal.

   Include in council packet and vibe report output:

   ## Test Pyramid Score
   | Level | Count | Weight | Contribution |
   |-------|-------|--------|--------------|
   | L0    | 2     | 1x     | 2            |
   | L1    | 8     | 1x     | 8            |
   | L2    | 0     | 3x     | 0            |
   | L3    | 0     | 5x     | 0            |
   | L4    | 0     | 5x     | 0            |
   | **Total** | **10** | | **10 / 50 = 0.20** |
   WARN: weighted_score 0.20 < 0.3 and all tests are L0-L1 only
   

5. Build coverage table and include in council packet as

   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"}
  },
  "weighted_score": 0.20,
  "satisfaction_score": 0.20,
  "satisfaction_source": "test-pyramid-weighted",
  "score_breakdown": {"L0": 2, "L1": 8, "L2": 0, "L3": 0, "L4": 0},
  "max_possible": 50,
  "warn_unit_only": true,
  "verdict": "WARN: weighted_score 0.20 < 0.3, all tests L0-L1 only"
}

Verdict rules:

• weighted_score < 0.3

  AND all tests L0-L1 only — WARN: unit-only coverage (include in council findings)
• Missing L1 on feature code — WARN (include in council findings)
• Missing L0 on spec-changing code — WARN
• Missing BF4 on boundary code — WARN (advisory, not blocking)
• All levels covered with

  weighted_score >= 0.6

  — no mention needed

When coverage gaps are found, run

/test <module>

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

Without spec — 2 independent judges (no perspectives):

/council validate <target>

2 independent judges (no perspective labels). Use

--deep

--quick

--mixed

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

--mixed

--preset=<name>

--explorers=N

--debate

--tier=<name>

/council

Step 5: Council Checks

Each judge reviews for:

Step 6: Interpret Verdict

Council Verdict:

Step 7: Write Vibe Report

Write to:

.agents/council/YYYY-MM-DD-vibe-<target>.md

date +%Y-%m-%d

Read

references/report-format.md

--deep

--sweep

Step 8: Report to User

Tell the user:

1. Complexity hotspots (if any)
2. Council verdict (PASS/WARN/FAIL)
3. Key concerns
4. Location of vibe report

Step 9: Record Ratchet Progress

After council verdict:

1. If verdict is PASS or WARN:
   • Run:

     ao ratchet record vibe --output "<report-path>" 2>/dev/null || true

   • Suggest: "Run /post-mortem to capture learnings and complete the cycle."
2. If verdict is FAIL:
   • Do 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.

Step 9.5: Feed Findings to Flywheel

If verdict is WARN or FAIL, persist reusable findings to

.agents/findings/registry.jsonl

Registry write rules:

• persist only reusable issues that should change future review or implementation behavior
• require

  dedup_key

  , provenance,

  pattern

  ,

  detection_question

  ,

  checklist_item

  ,

  applicable_when

  , and

  confidence

• applicable_when

  must use the controlled vocabulary from the finding-registry contract
• append or merge by

  dedup_key

• use the contract's temp-file-plus-rename atomic write rule

If a broader prose summary still helps, also write the existing anti-pattern learning file to

.agents/learnings/YYYY-MM-DD-vibe-<target>.md

After the registry update, if

hooks/finding-compiler.sh

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

Step 10: Test Bead Cleanup

After validation completes, clean up stale test beads (

bd list --status=open | grep -iE "test bead|test quest"

bd close

bd

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

Troubleshooting

pip install radon

go install github.com/fzipp/gocyclo/cmd/gocyclo@latest

.agents/council/<timestamp>-vibe-*.md

--mixed

--mixed

/vibe src/auth/

.agents/plans/

--deep

Write-Time Quality Hook

The

hooks/write-time-quality.sh

• Go: unchecked errors,

  fmt.Print

  in library code
• Python: bare

  except:

  ,

  eval

  /

  exec

  , missing type hints on public functions
• Shell: missing

  set -euo pipefail

  , unquoted variables

The hook is non-blocking (always exits 0) and outputs warnings via JSON. See references/write-time-quality.md for the full design.

See Also

• skills/council/SKILL.md

  — Multi-model validation council

• skills/complexity/SKILL.md

  — Standalone complexity analysis

• skills/bug-hunt/SKILL.md

  — Proactive code audit and bug investigation

• .agents/specs/conflict-resolution-algorithm.md

  — Conflict resolution between agent findings
• test — Test generation and coverage analysis
• perf — Performance profiling and benchmarking

Reference Documents

• references/deep-checks.md
• references/verification-report.md
• references/write-time-quality.md
• references/deep-audit-protocol.md
• references/examples.md
• references/go-patterns.md
• references/go-standards.md
• references/json-standards.md
• references/markdown-standards.md
• references/patterns.md
• references/python-standards.md
• references/report-format.md
• references/rust-standards.md
• references/shell-standards.md
• references/typescript-standards.md
• references/vibe-coding.md
• references/vibe-suppressions.md
• references/test-pyramid-weighting.md
• references/yaml-standards.md