vibe-code-audit

Category: Tools & Productivity | Uploader: codesoda | Downloads: 0 | Version: v1.0（Latest）

Catalogue-first repo audit for vibe-coded systems. Use when Codex must run llmcc and agentroot, discover semantic duplication and architecture drift, and produce evidence-based refactor bundles with high-confidence findings. Supports progressive disclosure via references/core and stack-specific references/packs.

Changelog: Source: GitHub https://github.com/codesoda/vibe-code-audit

Directory Structure

Current level: vibe-code-audit/

📁 references/
- 📁 claude/
  - 📄 subagents-and-model-routing.md 3.9 KB
- 📁 core/
  - 📄 agent-roles.md 696 B
  - 📄 architecture.md 747 B
  - 📄 context-budget.md 1.0 KB
  - 📄 duplication.md 868 B
  - 📄 inventory.md 793 B
  - 📄 maintainability.md 717 B
  - 📄 output-schema.md 1.1 KB
  - 📄 pattern-mining.md 1.0 KB
  - 📄 prioritization.md 747 B
  - 📄 process.md 13.1 KB
  - 📄 risk.md 881 B
- 📁 packs/
  - 📄 node-express.md 748 B
  - 📄 rails.md 773 B
  - 📄 react-next.md 763 B
  - 📄 rust-backend.md 762 B
📁 scripts/
- 📄 build_derived_artifacts.sh 7.2 KB
- 📄 build_read_plan.sh 4.8 KB
- 📄 render_report_pdf.sh 6.8 KB
- 📄 render_system_map.sh 7.5 KB
- 📄 run_agentroot_embed.sh 7.9 KB
- 📄 run_index.sh 21.5 KB
📄 INSTALL_MANIFEST.txt 784 B
📄 REPORT_TEMPLATE.md 1.6 KB
📄 SKILL.md 12.0 KB

SKILL.md

---
name: vibe-code-audit
description: Catalogue-first repo audit for vibe-coded systems. Use when Codex must run llmcc and agentroot, discover semantic duplication and architecture drift, and produce evidence-based refactor bundles with high-confidence findings. Supports progressive disclosure via references/core and stack-specific references/packs.
allowed-tools:
  - Bash(*run_index.sh*)
  - Bash(*build_derived_artifacts.sh*)
  - Bash(*build_read_plan.sh*)
  - Bash(*run_agentroot_embed.sh*)
  - Bash(*render_system_map.sh*)
  - Bash(*render_report_pdf.sh*)
  - Bash(llmcc *)
  - Bash(agentroot *)
  - Bash(rg *)
  - Bash(sed -n *)
  - Bash(cat *)
  - Read(vibe-code-audit/**)
  - Read
---

# Vibe Code Audit

Run a deterministic, read-only audit optimized for messy, organically grown codebases where the same intent is implemented multiple ways.

## Progressive Disclosure

Read only what is needed:

1. For normal runs, execute scripts first; avoid opening references before script execution.
2. Do not read `references/packs/*.md` in default flow.
3. Load `references/core/process.md` only when script fallback or troubleshooting is required.
4. Load `references/core/*.md` based on the active phase.
5. Load `references/packs/*.md` only when stack-specific behavior is ambiguous.
6. If running in Claude Code, load `references/claude/subagents-and-model-routing.md` only when setting up subagents/models.

Stack pack selection:

1. `Cargo.toml` -> `references/packs/rust-backend.md`
2. `package.json` + `tsconfig.json` + `next.config.*` -> `references/packs/react-next.md`
3. `package.json` + `express` usage -> `references/packs/node-express.md`
4. `Gemfile` + Rails markers -> `references/packs/rails.md`

If no pack matches, continue with core language-agnostic rules.

## Inputs

1. `repo_path` (default `.`)
2. Optional `output_dir` (if omitted, `run_index.sh` auto-creates `<repo_path>/vibe-code-audit/<UTC-timestamp>/`)
3. Optional focus areas: `duplication`, `risk`, `architecture`, `maintainability`
4. Optional budget mode: `fast`, `standard`, `deep` (default `standard`)
5. `skill_dir` (path to this installed skill directory; resolve from runtime context)

Budget behavior:

1. `fast`: prioritize top-central hotspots and strongest evidence.
2. `standard`: full V1 flow.
3. `deep`: broaden duplication and boundary analysis coverage.

## Output Location

Resolve output path at the beginning of the run:

1. Ask user where to write audit artifacts only if they care to customize location.
2. If no explicit output is provided, let `run_index.sh` choose the default path.
3. Do not run standalone timestamp shell commands to construct output paths.
4. Write index artifacts to `<output_dir>/audit_index/`.
5. Write final report to `<output_dir>/audit_report.md`.
6. Only create/overwrite files under `<output_dir>`.

## Guardrails

1. Stay read-only against source files.
2. Avoid destructive commands.
3. Avoid lint/style-only findings.
4. Avoid speculative findings.
5. Do not run full test suites unless user asks.

## Context Budget Rules

Prevent context-window failures during large-repo audits:

1. Do not read entire large source files by default.
2. Start with file discovery (`rg --files`) and targeted search (`rg <pattern>`).
3. Read only relevant slices around evidence (`sed -n start,endp`), not whole files.
4. If a file exceeds ~800 lines, read only targeted sections unless user explicitly asks for full-file review.
5. Avoid parallel bulk file reads across the whole repo.
6. Prefer artifact-driven analysis (`manifest`, `catalog`, `hotspots`, `dup_clusters`) over exhaustive raw-file ingestion.
7. Do not open raw `audit_index/llmcc/**/*.dot` files in normal flow; use `derived/hotspots.json` and catalog artifacts instead.
8. Never `Read` binary or generated graph/image files (`*.dot`, `*.png`, `*.jpg`, `*.jpeg`, `*.gif`, `*.pdf`).
9. If a required `Read` fails, retry that file sequentially; do not batch sibling `Read` calls until the missing-path issue is fixed.

## Claude Execution Mode

When running this skill via Claude Code:

1. Use subagents to keep main-thread context small.
2. Route by task complexity:
   - `haiku` for exploration and evidence lookup
   - `sonnet` for indexing orchestration, pattern mining, and synthesis
   - `opus` only for ambiguous high-severity adjudication
3. Use bounded objectives per subagent; avoid long multi-purpose prompts.
4. Follow `references/claude/subagents-and-model-routing.md`.

## Allowed Tools

Use only the following tool classes for this skill unless the user explicitly expands scope:

1. `Bash(<skill_dir>/scripts/run_index.sh ...)` for deterministic preflight + indexing.
2. `Bash(<skill_dir>/scripts/build_derived_artifacts.sh ...)` for deterministic `catalog/hotspots/dup_clusters` bootstrap.
3. `Bash(<skill_dir>/scripts/build_read_plan.sh ...)` for bounded evidence slice planning.
4. `Bash(<skill_dir>/scripts/run_agentroot_embed.sh ...)` only for embedding troubleshooting or manual embed reruns.
5. `Bash(<skill_dir>/scripts/render_report_pdf.sh ...)` for optional report PDF generation.
6. `Bash(<skill_dir>/scripts/render_system_map.sh ...)` for optional system map rendering.
7. `Bash(llmcc ...)` for structural graph generation and PageRank hotspot extraction.
8. `Bash(agentroot ...)` for hybrid indexing, lexical query, and semantic search.
9. `Read(vibe-code-audit/**)` for reading skill instructions, references, and templates.
10. `Read(<target-repo-files>)` for read-only audit evidence collection.

Do not run unrelated command families during the audit flow.

## Required Tools

Dependencies:
- `llmcc`
- `agentroot`

Optional PDF dependencies:
- `pandoc`
- one PDF engine (`tectonic`, `typst`, `xelatex`, `pdflatex`, `wkhtmltopdf`, or `weasyprint`)

Validation policy:

1. In normal flow, `run_index.sh` performs dependency validation.
2. Do not run standalone version checks before calling `run_index.sh`.
3. Run direct version checks only in manual fallback or troubleshooting mode.

## Tool Invocation Policy

Use deterministic command execution for indexing:

1. Resolve `skill_dir` first.
2. Execute a single Bash action:
   - `<skill_dir>/scripts/run_index.sh --repo <repo_path> --mode <budget_mode>`
   - In Claude Code, use a larger command timeout for indexing (`>=900000 ms` recommended) or run in background and poll task output.
3. If custom output is needed, pass `--output <output_dir>` to the same command.
4. `run_index.sh` auto-runs read-plan generation unless `--skip-read-plan` is used.
5. `run_index.sh` auto-runs derived artifact bootstrap (`catalog.json`, `hotspots.json`, `dup_clusters.md`).
6. Do not run separate preflight commands (`llmcc --version`, `agentroot --version`) outside scripts in normal flow.
7. Use direct `llmcc`/`agentroot` commands only if script execution is unavailable.
8. Do not run exploratory `llmcc --help` or `agentroot --help` during normal audit flow.
9. Use `--help` only as fallback when an expected command fails with an unknown command/flag error.
10. Run all index commands from the resolved `repo_path`.
11. Verify expected artifact files/directories after each indexing stage.
12. Read `<output_dir>/audit_index/manifest.json` before analysis and enforce:
   - `agentroot_document_count > 0`
   - `retrieval_query_ok == 1` or `retrieval_vsearch_ok == 1` or `retrieval_mode == "bm25-only"`
13. If `retrieval_mode` is `bm25-only`, continue in degraded mode (do not abort), but rely more on direct file evidence and explicit `rg` corroboration.
14. `run_index.sh` auto-embed is enabled by default; let it drive embedding via `run_agentroot_embed.sh` and avoid manual ad-hoc embed orchestration in normal flow. Use `VIBE_CODE_AUDIT_AGENTROOT_AUTO_EMBED=0` only when intentionally disabling embed attempts.
15. For embed troubleshooting, read manifest fields:
   - `agentroot_embed_attempted`
   - `agentroot_embed_ok`
   - `agentroot_embed_backend`
   - `agentroot_embed_utf8_panic`
16. Never use `grep -P` / `grep -oP`; use `rg` or portable `grep -E`/`grep -oE`.
17. Avoid `Read` on large generated artifacts (`*.dot`, huge logs, image files) unless recovery mode requires it.
18. `run_index.sh` already includes CLI-compatibility fallbacks; if it fails, rerun once and inspect its stderr instead of manually re-implementing indexing with many ad-hoc commands.
19. Do not compute hotspot LOC with overlapping glob patterns (for example `src/*.rs` + `src/**/*.rs`) because it double-counts files.
20. After writing `<output_dir>/audit_report.md`, run:
   - `<skill_dir>/scripts/render_report_pdf.sh --report <output_dir>/audit_report.md --map-mode crate`
21. `render_report_pdf.sh` attempts `render_system_map.sh` automatically first (non-fatal).
22. Treat system map and PDF export as optional:
   - if script output contains `SYSTEM_MAP_PATH=...`, reference the generated image
   - if script output contains `SYSTEM_MAP_SKIPPED=1`, continue without failing the audit
23. For PDF:
   - if script output contains `PDF_PATH=...`, reference the generated PDF
   - if script output contains `PDF_SKIPPED=1`, continue without failing the audit
   - if script output contains `PDF_NOTE=rendered_without_system_map`, mention PDF fallback behavior

## Required Outputs

Must produce:

1. `<output_dir>/audit_index/manifest.json`
2. `<output_dir>/audit_index/llmcc/` artifacts
3. `<output_dir>/audit_index/agentroot/` artifacts
4. `<output_dir>/audit_index/agentroot/status.json` (or equivalent status artifact)
5. `<output_dir>/audit_index/derived/catalog.json`
6. `<output_dir>/audit_index/derived/hotspots.json`
7. `<output_dir>/audit_index/derived/dup_clusters.md`
8. `<output_dir>/audit_index/derived/read_plan.tsv`
9. `<output_dir>/audit_index/derived/read_plan.md`
10. `<output_dir>/audit_report.md`

Optional output:

11. `<output_dir>/audit_report.pdf` (only when PDF tooling is available)
12. `<output_dir>/system_map.png` (only when Graphviz and a dot source are available)

## Execution Contract

Execute phases from `references/core/process.md` in order:

1. Phase 0: Scope and stack detection
2. Phase 1: Discovery and catalog-first indexing
3. Phase 2: Pattern mining for inconsistent implementations
4. Phase 3: Semantic duplication clustering
5. Phase 4: Architecture and boundaries audit
6. Phase 5: Risk audit
7. Phase 6: Maintainability and DX audit
8. Phase 7: Prioritization and refactor bundle synthesis
9. Phase 8: Optional system map rendering and PDF export

Use supporting references as needed:

1. `references/core/inventory.md`
2. `references/core/pattern-mining.md`
3. `references/core/duplication.md`
4. `references/core/architecture.md`
5. `references/core/risk.md`
6. `references/core/maintainability.md`
7. `references/core/prioritization.md`
8. `references/core/agent-roles.md`
9. `references/core/output-schema.md`
10. `references/core/context-budget.md`
11. `references/claude/subagents-and-model-routing.md`

## Findings Rules

1. Cap findings to top `10`.
2. Cap bundles to `3` to `8`.
3. Every finding must include evidence file paths.
4. Every finding must include severity, confidence, effort, and blast radius.
5. Apply severity-aware confidence thresholds:
   - `S0/S1`: keep only if confidence `>= 0.70`
   - `S2/S3`: keep only if confidence `>= 0.85`
6. Treat inconsistency as a risk multiplier.
7. If `manifest.retrieval_mode == "bm25-only"`, lower confidence for semantic-duplication claims unless corroborated by direct code evidence.

## Report Contract

Write `<output_dir>/audit_report.md` using this exact section order:

1. Executive Summary
2. System Map
3. Hotspots Overview
4. Pattern Inconsistencies
5. Duplication Clusters
6. Risk Findings
7. Refactor Bundles
8. Roadmap

If `./REPORT_TEMPLATE.md` exists in this skill directory, align headings and table layout to it.

Roadmap must include two lanes:

1. Quick Wins (1-3 days)
2. Deep Work (1-6 weeks)

## Definition of Done

Complete only when:

1. Required artifacts exist and are populated.
2. Retrieval validation succeeded (`agentroot_document_count > 0` and at least one retrieval check succeeded).
3. Findings are confidence-filtered and evidence-backed.
4. Refactor bundles are actionable and sequenced.
5. Report emphasizes consolidation leverage over issue count.

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

vibe-code-audit

Directory Structure

SKILL.md

Report

Notice