project-vision-audit

A skill for AI agents (Claude Code, Codex, Cursor, OpenCode, +50 others) that audits whether a project's implementation actually matches its spec, vision, plan, or design.

Reads foundation docs → dispatches parallel verification agents → enforces verify-don't-assume on every claim → outputs a gap-matrix report (Done / Partial / Missing / Vision-Gap / Data-Gap). Hands off to superpowers:writing-plans for fixes.

Install

# Install to current project
npx skills add metkelhansen/project-vision-audit

# Install globally (available across all your projects)
npx skills add metkelhansen/project-vision-audit -g

# For Claude Code specifically
npx skills add metkelhansen/project-vision-audit -a claude-code -g

See the skills.sh CLI docs for all options.

Required Dependencies

This skill invokes other skills at runtime. Install these alongside for the audit to work:

# Required (CORE — used during audit):
npx skills add https://github.com/obra/superpowers --skill dispatching-parallel-agents -g
npx skills add https://github.com/obra/superpowers --skill verification-before-completion -g

# Recommended (HANDOFF — for fixing audit findings):
npx skills add https://github.com/obra/superpowers --skill writing-plans -g
npx skills add https://github.com/obra/superpowers --skill brainstorming -g
npx skills add https://github.com/obra/superpowers --skill using-git-worktrees -g
npx skills add https://github.com/obra/superpowers --skill test-driven-development -g
npx skills add https://github.com/obra/superpowers --skill executing-plans -g
npx skills add https://github.com/obra/superpowers --skill subagent-driven-development -g
npx skills add https://github.com/obra/superpowers --skill requesting-code-review -g
npx skills add https://github.com/obra/superpowers --skill receiving-code-review -g
npx skills add https://github.com/obra/superpowers --skill finishing-a-development-branch -g

# Optional (for finding-domain-specific handoffs):
npx skills add https://github.com/squirrelscan/skills --skill audit-website -g          # 230+ rules website audit
npx skills add https://github.com/leonxlnx/taste-skill --skill redesign-existing-projects -g  # Visual redesign audit

The audit will warn at runtime if a required dependency is missing.

Example: Trigger the Audit

In Claude Code, just ask your agent:

> Run a vision-audit on this project
> Audit this repo against the spec — where do we actually stand?
> Before deploy, check everything: spec match, data plausibility, ops gaps

The skill activates on these phrases (and similar). It will:

1. Detect foundation docs (vision/spec/plans/diagrams) automatically
2. Read git history + optional knowledge bases (Obsidian, Notion, custom paths)
3. Build a 30-50 row audit checklist adapted to your project
4. Dispatch 4-6 parallel verification agents (one per strand)
5. Aggregate findings into a gap-matrix report saved to docs/audits/YYYY-MM-DD-audit.md

What It Does

When you ask your agent to "audit", "review", or "check whether the project still matches the spec", this skill kicks in.

1. Finds foundation docs — vision, spec, plans, mockups, diagrams, README, CHANGELOG, optional Obsidian / Notion
2. Reads history — git log, daily notes, memory files
3. Builds a strand-checklist — generic A-I template (Vision-Match, Backend, DB, API, Frontend, Design, Plausibility, Ops, Mobile)
4. Dispatches parallel verification agents — one per strand
5. Each agent enforces verify-don't-assume — every claim needs file:line evidence or command output, no daily-note quotes accepted
6. Aggregates findings into a gap-matrix: ✅ Done / ⚠️ Partial / ❌ Missing / 🚫 Vision-Gap / 📭 Data-Gap
7. Saves report to <project>/docs/audits/YYYY-MM-DD-audit.md
8. Hands off to the appropriate fix-pipeline (superpowers:brainstorming → superpowers:writing-plans → ...)

Why It Exists

Specs drift. Daily notes lag. Memory becomes stale. Implementation diverges from vision over weeks.

Without a structured audit, you build on assumptions and ship the wrong thing.

This skill enforces: read source-of-truth, verify against reality, categorize the gap, propose the fix-handoff. Nothing more.

Hard Rules Baked In

• Karpathy-style code discipline — state assumptions explicitly, simplicity first, surgical changes, verifiable success criteria
• Verify-don't-assume — reality (code/DB/git/API) wins over docs (specs/notes/memory)
• Vision-vs-Implementation gap-matrix as the standard output

Compatible Agents

Per the skills.sh standard, this skill uses the universal SKILL.md format and works with:

• Claude Code (Anthropic)
• Codex (OpenAI)
• Cursor
• OpenCode
• GitHub Copilot
• Gemini CLI
• Cline
• And 50+ more agents

Files in This Repo

project-vision-audit/
├── SKILL.md                            # Main entry — workflow, hard rules, sub-skill refs
├── references/
│   ├── karpathy-discipline.md          # 4 code-discipline principles
│   ├── verify-not-assume.md            # The hard rule + verification patterns + sub-agent template
│   ├── audit-checklist-template.md     # A-I generic checklist (30-50 rows)
│   ├── report-template.md              # 6-section markdown skeleton for output
│   ├── handoff-flow.md                 # Full superpowers fix-pipeline diagram
│   └── domain-handoff-mapping.md       # Frontend/Backend/Mobile/etc. skills mapping
├── scripts/
│   └── find-foundation-docs.sh         # Auto-discovery of vision/spec/plan files
├── README.md                           # This file
├── INSTALL.md                          # Detailed install / update / troubleshooting
└── LICENSE                             # MIT

Optional Knowledge Bases

The skill works without any external tools, but integrates with these if you have them:

• Obsidian Vault — pass via --obsidian-vault <path> to the helper script
• Notion export — pass via --notion-export <path>
• Custom docs/history paths — set AUDIT_DOCS_DIR / AUDIT_HISTORY_DIR env vars
• Claude Code memory — auto-detected at ~/.claude/projects/

Sub-Skills It Uses

Required (during audit):

• superpowers:dispatching-parallel-agents — for the parallel verification pass
• superpowers:verification-before-completion — grounding for the verify rule

Optional handoff (after audit, when fixing findings):

• superpowers:brainstorming — for Scope-Gap findings
• superpowers:writing-plans — implementation plan
• superpowers:using-git-worktrees — isolated fix branch
• superpowers:test-driven-development — TDD for fixes
• superpowers:executing-plans / superpowers:subagent-driven-development — execute plan
• superpowers:requesting-code-review — second-pair-of-eyes
• superpowers:receiving-code-review — handle review feedback
• superpowers:finishing-a-development-branch — merge + cleanup

Roadmap

Future related skills planned:

• obsidian-vault-audit — vault hygiene + structure-drift detection
• homelab-deploy-check — pre-deploy verification for self-hosted infra
• youtube-channel-audit — analytics-driven channel review

License

MIT — see LICENSE

Author

Serkan Ipek — @metkelhansen

Built with assistance from Claude Sonnet/Opus.

---

Topics for discoverability: claude-code, claude-skills, agent-skills, audit, vision-audit, code-review, project-management, superpowers, verify-not-assume, karpathy-discipline, gap-analysis