Imported from skaile-ai/ai-assets (skaile-development/skills/audit/SKILL.md). Install upstream with npx skills add skaile-ai/ai-assets --skill audit. Copyright stays with the author.

Audit — Monorepo Code Quality Audit

Overview

Three-phase structured code audit for the skaile-dev monorepo.

The build phase always runs first. If the build fails, sub-agents are skipped and the verdict is fail immediately.

When to Use

• Before committing a non-trivial change (scope=diff)
• Before opening a pull request (scope=package or diff with branch source)
• Before cutting a release (scope=full, called by release Phase 0)
• On-demand investigation of a suspected issue (scope=package)

When NOT to Use

• For quick diff review without build/test — use review instead
• For runtime user-journey validation — use test-e2e or verify-ui
• For documentation audit only — use doc --mode audit

ROLE Monorepo code quality auditor — verifies build and tests pass, then surfaces logic, security, and UI/UX issues via parallel sub-agent analysis. Produces a JSON artifact and a user-facing report.

READS ! ai-assets/skaile-development/references/audit_checklists.md ! ai-assets/skaile-development/references/test_stack_map.md ! /CLAUDE.md — for each affected package ? /REVIEW.md — repo-specific rules ? .github/workflows/*.yml — CI expectations to align with

WRITES _devlog/reports/audit-.json — structured result (always) _devlog/reports/audit-.md — human report (always)

MUST run build verification before dispatching sub-agents MUST stop immediately if build fails — do not waste tokens on sub-agents MUST read every affected package's CLAUDE.md before sub-agent dispatch MUST dispatch logic, security, UI/UX sub-agents in parallel (scope=package or full) MUST write both JSON and markdown artifacts before reporting MUST classify every finding by severity and map to audit_checklists.md category MUST skip findings already caught by Biome, ESLint, tsc, or bun audit NEVER modify any source files — audit is read-only NEVER mark as pass with any critical finding NEVER dispatch sub-agents if build or tests have already failed

EMIT [audit] started scope= target= run_id=

── Phase 1: Scope Resolution ─────────────────────────────────────

STEP 1: Resolve target packages IF scope = diff - diff_source = staged → $ git diff --cached --name-only - diff_source = last-commit → $ git diff HEAD~1..HEAD --name-only - diff_source = branch → $ git diff main...HEAD --name-only - Map file paths to package roots (use longest-prefix match against package.json locations) IF no affected packages → stop: "No changes to audit" IF scope = package - target input required - Validate: /package.json exists - Affected packages = [target] IF scope = full - Affected packages = every workspace in root package.json

STEP 2: Load context FOR EACH affected package: - Read /CLAUDE.md — note Tech Stack, Key Conventions, Environment Variables - Read /REVIEW.md if present — note repo-specific "always check" rules

• Read audit_checklists.md once
• Read test_stack_map.md once

EMIT [audit] context_loaded packages=

── Phase 2: Build Verification ──────────────────────────────────

STEP 3: Lint every affected package

• Use Biome for non-platform packages: bun x biome check <pkg-path>
• Use Prettier/ESLint for platform: check package scripts
• Record: lint. = pass | fail IF any lint fails
  • Set verdict = fail
  • Jump to STEP 9 (write artifacts with partial result)

STEP 4: Typecheck every affected package

• bun x tsc --noEmit -p <pkg>/tsconfig.json if tsconfig exists
• Or invoke package's typecheck script
• Record: typecheck. = pass | fail IF any typecheck fails
  • Set verdict = fail
  • Jump to STEP 9

STEP 5: Build every affected package that has a build script

• bun run build --filter <pkg> or per-package bun run build
• Skip packages without a build script (internal-library, types-only)
• Record: build. = pass | fail | skipped IF any build fails
  • Set verdict = fail
  • Jump to STEP 9

EMIT [audit] build_passed packages=

── Phase 3: Test Verification ───────────────────────────────────

STEP 6: Run tests per affected package FOR EACH affected package with a test configuration (from test_stack_map.md): - Execute the mapped run command - Capture: total, passed, failed, skipped, duration

• Run bun audit once for dependency vulnerabilities
• Record: tests., audit.vulnerabilities IF any tests fail
  • Set verdict = fail
  • Include failing test names in blocking_issues
  • Jump to STEP 9

EMIT [audit] tests_passed total=

── Phase 4: Parallel Sub-Agent Analysis ─────────────────────────

STEP 7: Dispatch three parallel sub-agents Only run this step when scope = package OR full. For scope = diff, skip to STEP 8 — the diff alone is lightweight enough for a single-pass review.

Sub-agent A — Logic & Runtime Auditor: Checklists: audit_checklists.md § A Scope: source files in affected packages (exclude tests, configs, generated) Must read: CLAUDE.md of each package first to understand conventions Return: JSON array of findings

Sub-agent B — Security Auditor: Checklists: audit_checklists.md § B Scope: source files + package.json + .env.example Also run: bun audit --json Return: JSON array of findings + dependency advisories

Sub-agent C — UI/UX Code Auditor: Checklists: audit_checklists.md § C Scope: frontend source files only (forge/**/app/, platform/frontend/src/, forge/common-ui/) Skip if no frontend files in scope Return: JSON array of findings

Wait for all three sub-agents to return before proceeding.

EMIT [audit] subagents_done critical= high= medium= low=

── Phase 5: Verdict & Artifacts ─────────────────────────────────

STEP 8: Synthesize findings

• Merge sub-agent JSON arrays
• Deduplicate by (file, line, category)
• Build blocking_issues = findings with severity in [critical, high]
• Determine verdict:
  • pass: build clean + tests pass + zero critical + zero high
  • warn: build clean + tests pass + only medium/low findings
  • fail: any build failure OR any test failure OR any critical finding

STEP 9: Write JSON artifact OUTPUT _devlog/reports/audit-.json { "run_id": "", "started_at": "", "finished_at": "", "scope": "", "target": [], "build": { "": { "lint": "...", "typecheck": "...", "build": "..." } }, "tests": { "": { "total": N, "passed": N, "failed": N } }, "dependency_vulnerabilities": [...], "findings": [ { "severity": "...", "category": "...", "file": "...", "line": N, "description": "...", "fix": "..." } ], "summary": { "critical": N, "high": N, "medium": N, "low": N }, "blocking_issues": [...], "verdict": "pass|warn|fail" }

STEP 10: Write markdown report OUTPUT _devlog/reports/audit-.md

Audit Report —

Scope: Target: Verdict:

Build

Tests

Findings

Critical (N)

• <file>:<line> [] Fix:

High (N)

...

Medium (N)

Low (N)

Dependency Advisories

...

STEP 11: Report to user [audit] scope= → Build: lint · types · build Tests: / Findings: critical · high · medium · low Full report: _devlog/reports/audit-.md

EMIT [audit] completed run_id= verdict=

CHECKLIST

• Build verified before sub-agent dispatch
• Tests verified before sub-agent dispatch
• Three sub-agents dispatched in parallel (scope=package or full)
• JSON and markdown artifacts written
• Every finding has severity, file, line, description, fix
• No files modified
• Verdict matches the rules

Integration

• Called by: implement (Phase 4b, scope=diff), release (Phase 0, scope=full), quality (umbrella)
• Calls: three parallel sub-agents for logic/security/UI-UX
• Reads: audit_checklists.md, test_stack_map.md, each <package>/CLAUDE.md
• Writes: _devlog/reports/audit-*.{json,md}