Audit

audit

Purpose

Comprehensive project health audit across 8 dimensions (7 project + 1 mesh analytics). Delegates security scanning to sentinel, dependency analysis to dependency-doctor, and code complexity to autopsy, then directly audits architecture, performance, infrastructure, and documentation. Applies framework-specific checks (React/Next.js, Node.js, Python, Go, Rust, React Native/Flutter) based on detected stack. Produces a consolidated health score and prioritized action plan saved to AUDIT-REPORT.md.

Triggers

• /rune audit — full 8-dimension project health audit
• /rune audit dx — DX Review Mode (Addy Osmani 8 principles, see below)
• User says "audit", "review project", "health check", "project assessment"
• User says "developer experience", "DX audit", "onboarding experience", "time to hello world"

Calls (outbound)

• scout (L2): Phase 0 — project structure and stack discovery
• dependency-doctor (L3): Phase 1 — vulnerability scan and outdated dependency check
• sentinel (L2): Phase 2 — security audit (OWASP Top 10, secrets, config)
• autopsy (L2): Phase 3 — code quality and complexity assessment
• improve-architecture (L2): Phase 3.5 — architecture sub-score (depth / leverage / locality across top modules)
• perf (L2): Phase 4 — performance regression check
• db (L2): Phase 5 — database health dimension (schema, migrations, indexes)
• journal (L3): record audit date, overall score, and verdict
• constraint-check (L3): audit HARD-GATE compliance across project skills
• sast (L3): Phase 2 — deep static analysis (Semgrep, Bandit, ESLint security rules)
• retro (L2): Phase 6 — engineering velocity and health dimension (rune:retro)
• browser-pilot (L3): DX Review Mode — real browser testing of docs, setup guides, error pages

Called By (inbound)

• cook (L1): pre-implementation audit gate
• launch (L1): pre-launch health check
• User: /rune audit direct invocation

Executable Instructions

Phase 0: Project Discovery

Call rune:scout for a full project map. Then use Read on:

• README.md, CLAUDE.md, CONTRIBUTING.md, .editorconfig (if they exist)

Determine:

• Language(s) and version(s)
• Framework(s) — determines which Framework-Specific Checks below apply
• Package manager, build tool(s), test framework(s), linter/formatter config
• Project type: API/backend | frontend/SPA | fullstack | CLI tool | library | mobile | infra/IaC
• Monorepo setup (workspaces, turborepo, nx, etc.)

Output before proceeding: Brief project profile, stack summary, and which Framework-Specific Checks will be applied.

Phase 0.5: Context-Building (Pure Understanding)

This phase is FORBIDDEN from producing findings. No BLOCKs, no WARNs, no issues. Context-building only. Rushed context = hallucinated vulnerabilities. Slow is fast.

For each critical module (entry points, auth, data layer, core business logic):

1. Read line-by-line. Note at minimum:

• 3 invariants: What MUST always be true for this code to work? (e.g., "user is authenticated before reaching this handler")
• 5 assumptions: What does this code assume about its inputs, environment, and callers?
• 3 risks: What could break if assumptions are violated?

1. Record findings as context notes — these feed into Phases 1-7, NOT into the final report directly

Why: Without this phase, the auditor pattern-matches against known vulnerability lists and hallucinates findings that don't exist in THIS specific codebase. The invariants + assumptions ground all later analysis in reality.

---

Phase 1: Dependency Audit

Delegate to dependency-doctor. The dependency-doctor report covers:

• Vulnerability scan (CVEs by severity)
• Outdated packages (patch / minor / major)
• Unused dependencies
• Dependency health score

Pass the full dependency-doctor report through to the final audit.

---

Phase 2: Security Audit

Delegate to sentinel. Request a full security scan covering:

• Hardcoded secrets, API keys, tokens, passwords in source code
• OWASP Top 10: injection, broken auth, sensitive data exposure, XSS, CSRF, insecure deserialization, broken access control
• Configuration security (debug mode in prod, CORS *, missing HTTP security headers)
• Input validation at API boundaries
• .gitignore coverage of sensitive files

Pass the full sentinel report through to the final audit.

---

Phase 3: Code Quality Audit

Delegate to autopsy for codebase health (complexity, coupling, hotspots, dead code, health score per module).

In addition, use Grep to find supplementary issues autopsy may not cover:

# console.log in production code
grep -r "console\.log" src/ --include="*.ts" --include="*.js" -l

# TypeScript any types
grep -r ": any" src/ --include="*.ts" -n

# Empty catch blocks
grep -rn "catch.*{" src/ --include="*.ts" --include="*.js" -A 1 | grep -E "^\s*}"

# Python print() in production
grep -r "^print(" . --include="*.py" -l

# Rust .unwrap() outside tests
grep -rn "\.unwrap()" src/ --include="*.rs"

Merge autopsy report + supplementary findings.

3.5 Zombie Code Detection

Identify code that is effectively dead but hasn't been formally removed. Zombie code increases surface area, confuses contributors, and accumulates security debt.

| Signal | Detection Method | Severity | |--------|-----------------|----------| | No commits in 6+ months | git log --since="6 months ago" -- returns empty | MEDIUM | | No test coverage | File not imported by any test file (Grep for filename in **/*.test.* / **/*.spec.*) | MEDIUM | | No owner | File not in CODEOWNERS, no author active in last 6 months | LOW | | Failing tests referencing the module | Test suite has skipped/failing tests for this module | HIGH | | Unpatched CVEs in dependencies only this module uses | Cross-reference dependency-doctor CVE list with per-file imports | HIGH | | Orphaned docs | README/docs reference files or APIs that no longer exist | LOW |

Zombie Code Verdict:

• 3+ signals on same file/module → flag as ZOMBIE in audit report
• Recommend: archive (move to _deprecated/), delete, or assign owner
• Do NOT auto-delete — present zombie list to user for decision

---

Phase 4: Architecture Audit

Use Read and Grep to evaluate structural health directly.

4.1 Project Structure

• Logical folder organization (business logic vs infrastructure vs presentation separated?)
• Circular dependencies between modules (A imports B, B imports A)
• Barrel file analysis (excessive re-exports causing bundle bloat)

4.2 Design Patterns & Principles

• Single Responsibility violations (route handlers with direct DB calls, fat controllers)
• Tight coupling between layers

// BAD — route handler directly coupled to database
app.get('/users/:id', async (req, res) => {
  const user = await db.query('SELECT * FROM users WHERE id = $1', [req.params.id]);
  res.json(user);
});
// GOOD — layered architecture
app.get('/users/:id', async (req, res) => {
  const user = await userService.getUser(req.params.id);
  res.json(user);
});

4.3 API Design (if applicable)

• Consistent naming conventions (camelCase vs snake_case in JSON responses)
• Correct HTTP method usage (GET reads, POST creates, PUT/PATCH updates, DELETE removes)
• Consistent error response format across endpoints
• Pagination on collection endpoints
• API versioning strategy

4.4 Database Patterns (if applicable)

• N+1 query patterns

// BAD — N+1
const users = await db.query('SELECT * FROM users');
for (const user of users) {
  user.posts = await db.query('SELECT * FROM posts WHERE user_id = $1', [user.id]);
}
// GOOD — single JOIN
const usersWithPosts = await db.query(`
  SELECT u.*, json_agg(p.*) as posts
  FROM users u LEFT JOIN posts p ON p.user_id = u.id
  GROUP BY u.id
`);

• Missing indexes (check schema/migrations for columns used in WHERE/JOIN)
• Missing LIMIT on user-facing queries

4.5 State Management (frontend only)

• Global state pollution (local state handled globally)
• Prop drilling (>3 levels deep — use Context or composition)
• Data fetching patterns (caching, deduplication, stale-while-revalidate)

---

Phase 5: Performance Audit

5.1 Build & Bundle (frontend)

• Tree-shaking effectiveness (importing entire libraries vs specific modules)

// BAD — imports entire library
import _ from 'lodash';
// GOOD — tree-shakeable import
import get from 'lodash/get';

• Code splitting / lazy loading for routes
• Large unoptimized assets

5.2 Runtime Performance

• Synchronous operations that should be async (file I/O, network calls)
• Memory leak patterns (event listeners not cleaned up, growing caches, unclosed streams)
• Expensive operations in hot paths

// BAD — regex compiled on every call
function validate(input: string) {
  return /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/.test(input);
}
// GOOD — compile once at module level
const EMAIL_REGEX = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
function validate(input: string) { return EMAIL_REGEX.test(input); }

5.3 Database & I/O

• Missing connection pooling
• Unbounded queries (no LIMIT on user-facing endpoints)
• Sequential I/O that could be parallel

// BAD — sequential when independent
const users = await fetchUsers();
const products = await fetchProducts();
// GOOD — parallel
const [users, products] = await Promise.all([fetchUsers(), fetchProducts()]);

---

Phase 6: Infrastructure & DevOps Audit

Use Glob and Read to check:

6.1 CI/CD Pipeline

• CI config exists (.github/workflows/, .gitlab-ci.yml, .circleci/, Jenkinsfile)
• Tests running in CI
• Linting enforced in CI
• Security scanning in pipeline (Dependabot, Snyk, CodeQL)

6.2 Environment Configuration

• .env.example exists with placeholder values (not real secrets)
• Environment variables validated at startup

// BAD — silently undefined
const port = process.env.PORT;
// GOOD — validate at startup
const port = process.env.PORT;
if (!port) throw new Error('PORT environment variable is required');

6.3 Containerization (if applicable)

• Dockerfile: multi-stage build, non-root user, minimal base image
• .dockerignore covers node_modules, .git, .env

6.4 Logging & Monitoring

• Structured logging (JSON format, not raw console.log)
• Error tracking integration (Sentry, Datadog, etc.)
• Health check endpoints (/health, /ready)
• No sensitive data in logs (passwords, tokens, PII)

---

Phase 7: Documentation Audit

Use Glob and Read to check:

7.1 Project Documentation

• README completeness: description, prerequisites, setup, usage, deployment, contributing
• API documentation (OpenAPI/Swagger spec, or documented endpoints)
• Can a new developer get running from README alone?
• Architecture Decision Records (ADRs) for non-obvious choices

7.2 Code Documentation

• Public API / exported functions documented
• Complex business logic with explanatory comments
• CHANGELOG.md maintained
• LICENSE file present

---

Framework-Specific Checks

Apply only if the framework was detected in Phase 0. Skip entirely if not relevant.

React / Next.js (detect: react or next in package.json)

• useEffect with missing dependencies (stale closures)
• State updates during render (infinite loop pattern)
• List items using index as key on reorderable lists
• Props drilled through 3+ levels
• Client-side hooks in Server Components (Next.js App Router)
• Components exceeding 200 JSX lines

Node.js / Express / Fastify (detect: express, fastify, koa, @nestjs/core)

• Missing rate limiting on public endpoints
• Missing request timeout configuration
• Error messages leaking internal details to clients
• Unbounded SELECT * without pagination
• Missing authentication middleware on protected routes
• Synchronous operations blocking the event loop

Python (Django / Flask / FastAPI) (detect: django, flask, fastapi in requirements)

• Django: missing permission_classes, DEBUG=True in production, missing CSRF middleware
• Flask: app.run(debug=True) without environment check
• FastAPI: missing Pydantic models for request/response
• Mutable default arguments (def func(items=[]))
• Missing type hints on public functions (if project uses mypy/pyright)

Go (detect: go.mod)

• Ignored errors (file, _ := os.Open(filename))
• Goroutine leaks (goroutines without cancellation context)
• Missing defer for resource cleanup (files, locks, connections)
• Race conditions (shared state without mutex or channels)

Rust (detect: Cargo.toml)

• .unwrap() / .expect() in non-test production code (use ? operator)
• unsafe blocks without safety comments

Mobile (React Native / Flutter) (detect: react-native in package.json or pubspec.yaml)

• FlatList without keyExtractor or getItemLayout
• Missing React.memo on list item components
• Flutter: missing const constructors, missing dispose() for controllers and streams

---

Phase 8: Mesh Analytics (H3 Intelligence)

Goal: Surface insights about skill usage, chain patterns, and mesh health from accumulated metrics.

Data source: .rune/metrics/ directory (populated by hooks automatically).

1. Check if .rune/metrics/ exists. If not, emit INFO: "No metrics data yet — run a few cook sessions first."
2. Read .rune/metrics/skills.json — extract per-skill invocation counts, last used dates
3. Read .rune/metrics/sessions.jsonl — extract session count, avg duration, avg tool calls
4. Read .rune/metrics/chains.jsonl — extract most common skill chains
5. Read .rune/metrics/routing-overrides.json (if exists) — list active routing overrides

Compute and report:

• Top 10 most-used skills (by total invocations)
• Unused skills (0 invocations across all tracked sessions) — potential dead nodes
• Most common skill chains (top 5 patterns from chains.jsonl)
• Average session stats (duration, tool calls, skill invocations)
• Active routing overrides and their application count
• Mesh density check: cross-reference invocation data with declared connections — skills that are declared as "Called By" but never actually invoked may indicate broken mesh paths

Propose routing overrides: If patterns suggest inefficiency (e.g., debug consistently called 3+ times in a chain for the same session), propose a new routing override for user approval.

Output as a section in the final audit report:

### Mesh Analytics
| Skill | Invocations | Last Used | Chains Containing |
|-------|-------------|-----------|-------------------|
| cook  | 47          | 2026-02-28| 34                |
| scout | 89          | 2026-02-28| 42                |
| ...   | ...         | ...       | ...               |

**Common Chains**:
1. cook → scout → plan → test → fix → quality → verify (34x)
2. debug → scout → fix → verification (12x)

**Session Stats**: 23 sessions, avg 35min, avg 52 tool calls
**Unused Skills**: [list or "none"]
**Routing Overrides**: [count] active

Shortcut: /rune metrics invokes ONLY this phase, not the full 7-phase audit.

---

---

DX Review Mode (Addy Osmani 8 Principles)

Triggered by /rune audit dx. Evaluates developer experience — how easy it is for a new contributor to understand, set up, use, and recover from mistakes in this project. Inspired by Addy Osmani's DX framework.

DX Review is a SEPARATE mode — it does NOT run the 8-phase health audit above. If the user wants both, run /rune audit then /rune audit dx separately.

DX Principle 1: Time to Hello World

Measure: How many steps from git clone to running the project?

1. Read README.md — extract setup instructions
2. Count discrete steps (clone, install, config, build, run)
3. Check: are ALL commands copy-pasteable? (no placeholders without explanation)
4.

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Rune-kit](https://github.com/Rune-kit)
- **Source:** [Rune-kit/rune](https://github.com/Rune-kit/rune)
- **License:** MIT

Install and usage instructions live in the source repository linked above.