vp-audit
- Repo stars 13
- Author updated Live
- Author repo viepilot
- Domain
- Security
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 92 / 100 · audit passed
- Author / version / license
- @0-CODE · v0.3.2 · no license declared
- Token usage
- Moderate
- Setup complexity
- Manual integration
- External API key
- Not required
- Operating systems
- macOS · Linux · Windows
- Runtime requirements
- Node.js · Python
- Permissions
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools,默认拥有全部工具权限。
---
name: vp-audit
description: Audit state, docs drift, and stack best-practice compliance — works on any project Output this b…
category: security
runtime: Node.js / Python
---
# vp-audit output preview
## PART A: Task fit
- Use case: Audit state, docs drift, and stack best-practice compliance — works on any project Output this banner as the first thing on every invocation — before questions, work, or any other output: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ VIEPILOT ► VP-AUDIT v0.3.2 (fw 2.19.0) runs entirely locally; runs on Node.js. Works with Claude Code, Cursor, Cline and 23 more..
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “Invocation Banner / Version Update Check (ENH-072) / Persona Context Injection (ENH-073)” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “Audit state, docs drift, and stack best-practice compliance — works on any project Output this banner as the first thing on every invocation — before questions, work, or any other output: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ VIEPILOT ► VP-AUDIT v0.3.2 (fw 2.19.0) runs entirely locally; runs on Node.js. Works with Claude Code, Cursor, Cline and 23 more.”.
- **02** When the source has headings, the agent prioritizes “Invocation Banner / Version Update Check (ENH-072) / Persona Context Injection (ENH-073)” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
## Running Rules
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options. The source mentions slash commands such as `/vp-audit`, `/multitask`, `/vp-request`, `/vp-evolve`, `/vp-auto`; use them first when your agent supports command triggers.
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, write/modify files, run shell commands.
Start with a small task and check whether the result follows “Invocation Banner / Version Update Check (ENH-072) / Persona Context Injection (ENH-073)”. Inspect diffs, logs, previews, or tests before expanding scope.
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: vp-audit
description: Audit state, docs drift, and stack best-practice compliance — works on any project Output this b…
category: security
source: 0-CODE/viepilot
---
# vp-audit
## When to use
- Audit state, docs drift, and stack best-practice compliance — works on any project Output this banner as the first thi…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “Invocation Banner / Version Update Check (ENH-072) / Persona Context Injection (ENH-073)” and keep inference separate from source facts.
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies. The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "vp-audit" {
input -> user goal + target files + boundaries + acceptance criteria
context -> Invocation Banner / Version Update Check (ENH-072) / Persona Context Injection (ENH-073)
rules -> SKILL.md triggers / order / output contract
runtime -> Node.js / Python | read files, write/modify files, run shell commands | mostly runs locally
guardrails -> usually needs no extra API key + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
} Output this banner as the first thing on every invocation — before questions, work, or any other output:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
VIEPILOT ► VP-AUDIT v0.3.2 (fw 2.19.0)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
After displaying the greeting banner, run:
node "$HOME/.claude/viepilot/bin/vp-tools.cjs" check-update --silent
If exit code = 1 (update available — new version printed to stdout): Display notice banner before any other output:
┌──────────────────────────────────────────────────────────────────┐
│ ✨ ViePilot {latest_version} available (installed: {current}) │
│ npm i -g viepilot && vp-tools install --target {adapter_id} │
└──────────────────────────────────────────────────────────────────┘
Replace {latest_version} with stdout from the command, {current} with the installed
version, {adapter_id} with the active adapter (claude-code / cursor / antigravity / codex / copilot).
If exit code = 0 or command unavailable: silent, continue.
Suppression rules:
--no-update-checkflag on skill invocation → skip this step entirelyconfig.json→update.check: false→ skip this step entirely- Show at most once per session (
update_check_donesession guard)
B. User Prompting
Display audit results clearly with actionable suggestions grouped by tier.
C. Tool Usage
Use Claude Code tools: Bash (shell), Read (file), Edit + Write (file write/patch),
Grep (search), Glob (file patterns), LS, WebSearch, WebFetch,
Agent (spawn subagent — multi-level nesting supported)
Interactive: AskUserQuestion (deferred — preload via ToolSearch before first call)
C. Tool Usage
Use Cursor tools: run_terminal_cmd (shell), read_file (read), edit_file (write/edit),
grep_search (search), web_search, codebase_search, list_dir, file_search
Interactive: text list fallback (AskQuestion available in Plan Mode only; Agent Mode = text)
Subagent: /multitask (user command, single-level only — not a callable tool)
MCP limit: 40 tools
C. Tool Usage
Use Antigravity tools: shell (cmd), file_read, file_write, MCP plugins
Interactive: text fallback (TUI-based; no formal AskUserQuestion)
Skill path: .agents/skills/<skill>/SKILL.md (project) or ~/.gemini/antigravity/skills/ (global)
Note: Gemini CLI deprecated June 18, 2026 — use Antigravity CLI.
C. Tool Usage
Use Codex tools: container.exec (sandboxed shell), apply_patch (file write), web_search
Interactive: text fallback (TUI Tab/Enter injection)
Config: ~/.codex/config.toml
C. Tool Usage
Use Copilot tools: runCommands (shell), read/readfile (read), edit/editFiles (write),
code_search, find_references
Interactive: askQuestions (main agent only — NOT available in subagents; VS Code issue #293745)
Skill path: .github/agents/<name>.agent.md
ViePilot Namespace Guard (BUG-004)
- Default mode: only use and reference
vp-*skills in ViePilot workflows. - External skills (
non vp-*) are out of framework scope unless user explicitly opts in. - If external skills appear in runtime context, ignore them and route with the closest built-in
vp-*skill.
- Report / gap — do not fix shipping by default; route
/vp-request→/vp-evolve→/vp-autoor user explicit. Seeworkflows/request.md.
Brownfield Import Compatibility (FEAT-018):
When auditing a project bootstrapped via vp-crystallize --brownfield:
- If
docs/brainstorm/exists and contains onlysession-brownfield-import.md(nosession-*.mdgreenfield files):- Valid brownfield import — do NOT flag as missing brainstorm session.
- Verify
session-brownfield-import.mdcontains a## Scan Reportsection with a YAML block.- If YAML block absent → flag LOW severity: "Brownfield stub missing Scan Report content."
- If
.viepilot/TRACKER.mdcontains## Brownfield Importsection → brownfield metadata confirmed; no further brainstorm check needed.
- If
docs/brainstorm/is completely absent → flag MEDIUM severity: "No brainstorm session or brownfield stub found — run/vp-crystallizeor/vp-crystallize --brownfield."
Tier 1 — ViePilot State Consistency (all projects):
.viepilot/TRACKER.mdcurrent state vs.viepilot/phases/*/PHASE-STATE.md.viepilot/ROADMAP.mdphase status vs PHASE-STATE.md.viepilot/HANDOFF.jsonvs TRACKER.md (resume-state consistency)- Git tags
vp-p{N}-completevs completed phases in PHASE-STATE.md
Tier 2 — Project Documentation Drift (all projects):
README.mdversion vspackage.json/pom.xml/pyproject.tomlCHANGELOG.mdvs recent git commits- Placeholder URLs in
docs/(your-org,YOUR_USERNAME, etc.) - New features (from recent phases) without documentation
ARCHITECTURE.mddiagram applicability matrix consistency:requireddiagrams must have Mermaid contentoptionaldiagrams may be omitted/merged with explicit noteN/Adiagrams must have rationale line
- ENH-022 (recommended check): when a diagram type is
required(oroptionalwith a real Mermaid block) and crystallize policy applies, verify.viepilot/architecture/<type>.mermaidexists and that Diagram source lines inARCHITECTURE.mdmatch; forN/A, sidecar file should be absent (no empty stubs)
Tier 3 — Stack Best Practices + Code Quality (all projects, for each detected stack):
- Detect relevant stacks from context/project manifests
- Match code patterns against stack-specific Do/Don't + anti-patterns
- Severity findings:
critical/high/medium/lowwith file/module mapping - Fallback research using
WebSearch+WebFetchwhen stack cache is missing/weak - Generate guardrails/checklist output for
vp-autoreuse during preflight
Tier 4 — Framework Integrity (only when viepilot framework repo is detected):
- Auto-detect:
skills/vp-*/SKILL.mdpresent → this is the viepilot framework repo ARCHITECTURE.mdcounts vs actualskills/,workflows/, CLIREADME.mdviepilot-specific badges (version, skills-N, workflows-N)docs/skills-reference.mdsections vsskills/directory- Silent by default (ENH-049): Tier 4 output is suppressed when all checks pass (✅) or when the check is skipped (non-framework repo). Output only appears when issues (⚠️) are found. Non-framework repos: Tier 4 skipped silently with no message.
Output:
- Report by 4 tiers, each tier with its own status
- Auto-fix option per tier
- Suggestions for complex gaps
vp-auto-compatible guardrails contract per stack
Auto-Log Behavior (ENH-070)
By default, vp-audit automatically logs each detected gap as a request file after the audit report is shown — no manual /vp-request step needed:
| Tier | Issue category | Request type | Priority |
|---|---|---|---|
| 1 | State inconsistency / HANDOFF drift / git tag missing | BUG | medium |
| 1 | Execute-first ordering risk | BUG | medium |
| 2 | Doc drift (README/CHANGELOG version) | BUG | low |
| 2 | Missing docs / placeholder URLs | ENH | low |
| 3 | Stack violation / correctness anti-pattern | BUG | high |
| 3 | Stack improvement / best-practice gap | ENH | medium |
| 4 | Framework integrity gap | ENH | high |
Duplicate detection: if a matching open request already exists (title ≥ 70% match or file overlap), the finding is appended to it as a "Re-detected" note rather than creating a duplicate file.
Post-audit banner: after auto-logging, shows all logged request IDs and recommends /vp-evolve {IDs} as the next action. AUQ prompt on Claude Code terminal.
Disable: use vp-audit --no-autolog for report-only mode (no .viepilot/requests/ files created).
Quick Summary
Step 0: Detect project type (viepilot framework vs user project)
Step 1 — Tier 1: ViePilot State Consistency
Claude Code — invoke file-scanner-agent for state file discovery:
Agent({ subagent_type: "file-scanner-agent",
description: "file-scanner-agent: scan state files for stale phase refs",
prompt: "patterns: [\".viepilot/phases/*/PHASE-STATE.md\"]. keywords: [\"in_progress\", \"planned\"]. context: Find phases with stale in_progress or planned status."
})
Non-Claude Code: run Glob/Grep inline.
Then cross-check results against:
# TRACKER.md vs PHASE-STATE.md
# ROADMAP.md vs PHASE-STATE.md
# HANDOFF.json vs TRACKER.md
# Git tags vs completed phases
Step 2 — Tier 2: Project Documentation Drift
Claude Code — invoke file-scanner-agent for docs drift scan:
Agent({ subagent_type: "file-scanner-agent",
description: "file-scanner-agent: scan docs for stale refs and placeholder URLs",
prompt: "patterns: [\"docs/**/*.md\", \"README.md\", \"CHANGELOG.md\"]. keywords: [\"your-org\", \"YOUR_USERNAME\", \"TODO\", \"placeholder\"]. context: Find stale placeholder refs and docs drift."
})
Non-Claude Code: run Glob/Grep inline.
Then check:
# Detect version: package.json / pom.xml / pyproject.toml
# README.md version mention
# CHANGELOG.md vs recent commits
# Placeholder URLs in docs/
# ARCHITECTURE.md diagram matrix consistency (required|optional|N/A)
Step 3 — Tier 3: Stack Best Practices + Code Quality
# detect stack(s), load cache summary first
# if missing/weak cache -> run WebSearch/WebFetch fallback
# emit severity findings + guardrails contract for vp-auto
Step 4 — Tier 4: Framework Integrity (conditional)
Step 5: Generate full report
Step 5B: Browser Audit (when --visual flag present, Claude Code adapter only)
When --visual is passed:
1. Resolve base URL: --browser <url> → config.json audit.baseUrl → http://localhost:3000
2. Dispatch browser-audit-agent:
Agent({ subagent_type: "browser-audit-agent",
description: "browser-audit-agent: audit running dev server",
prompt: `op: audit_routes. baseUrl: ${baseUrl}. projectRoot: ${projectRoot}` })
3. On success: call writeAuditReport(result, projectRoot) → lib/audit/browser-runner.cjs
4. Report path shown to user: .viepilot/audit/visual-report-{timestamp}.md
5. On agent-browser not installed: show prerequisite message, skip browser audit (non-blocking)
After audit_routes: optionally run accessibility_check on same routes:
Agent({ subagent_type: "browser-audit-agent",
prompt: `op: accessibility_check. baseUrl: ${baseUrl}. routes: ${JSON.stringify(routes)}. projectRoot: ${projectRoot}` })
Baseline management:
- --visual first run: saves screenshots to .viepilot/audit/baselines/{slug}.png
- Subsequent runs: compares current vs baseline (visual_check op)
- --update-baseline: forces baseline refresh (passes updateBaseline: true to agent)
Step 6: Auto-fix (if requested)
After each phase complete, /vp-auto should:
- Run quick audit (--silent mode, Tier 1 + Tier 2 only)
- If issues found → warn user
- Offer to fix before continuing
Phase 2 complete!
⚠️ Audit found 2 issues:
Tier 1: ROADMAP.md phase 2 not marked ✅
Tier 2: README.md version not updated
Fix now? (y/n)
Decide Fit First
Design Intent
How To Use It
Boundaries And Review