ADK Audit / Repo

Standalone task skill under the adk-audit category router. Inspects a checked-out repository across multiple dimensions in parallel and produces one consolidated report with severity-tiered findings, each anchored to a file path.

When to use

• Health check before a release or handoff.
• Pre-acquisition / pre-onboarding code review of a repo as a whole.
• Periodic hygiene audit (security, perf, deps, test coverage, architecture drift).
• The deliverable is a markdown audit report at .temp/reports/<slug>.md.

When NOT to use

• Single PR or local-branch review -> adk-review-pr / adk-review-local
• Single doc review -> adk-docs-review
• Deployed-website audit -> adk-audit-site
• Fixing the findings -> adk-build-feature / adk-build-refactor / adk-build-deps

Inputs

Input	Required	Notes
<repo path>	yes	Local checkout root (default: cwd)
<dimensions>	optional	Subset of: security, performance, quality, dependencies, tests, architecture (default: all)
<depth>	optional	quick / standard (default) / deep
<output path>	optional	Defaults to .temp/reports/audit-repo-<slug>-<date>.md
--auto	optional	Skip approval gates

Workflow

1. Confirm intent - restate repo, dimensions, depth, output. Approval gate unless --auto.
2. Inventory - capture: file tree summary, primary languages, frameworks, build tools, package managers, test frameworks, total LOC, recent commit cadence.
3. Run dimensions in parallel - each dimension produces its own findings list:
   • Security: secrets in git, dep advisories, auth/n+z patterns, SQL/HTML/XSS sinks, CORS, env handling.
   • Performance: hot paths, N+1, sync IO in async paths, large bundles, build cache hygiene.
   • Quality: linter/typechecker output, duplicated code (~5%+ duplicate threshold), cyclomatic hotspots, dead code.
   • Dependencies: outdated direct deps, deprecated packages, unused deps, license risks.
   • Tests: framework presence, coverage where measurable, test-to-code ratio per package, flaky markers.
   • Architecture: module boundaries, circular deps, layering violations, drift from documented architecture.
4. Aggregate - merge findings into one ordered list. Deduplicate. Group by dimension under each severity.
5. Validate - reread each finding against the code to confirm it is real. Drop low-evidence findings.
6. Report - findings-first markdown using the template below.

Severity ladder

Label	Audit meaning
Blocker	Security hole, data loss risk, broken contract. Fix before next release.
Critical	Strongly impacts users / operators (perf cliff, accessibility failure on a code surface, broken core flow).
Should Have	Meaningful quality gain; defer with justification.
May Have	Optional improvement.
Nitpick	Style or convention.
Question	Auditor cannot tell from outside; needs owner clarification.

Finding template

### [<Severity>] <One-line summary> (<dimension>)
- **File**: `path/to/file.ext:LINE-LINE` (or `manifest`, `lockfile`, `config`)
- **Issue**: <2-3 sentence explanation>
- **Evidence**: <quoted snippet, command output, or reproducible signal>
- **Suggested fix**: <concrete recommendation; route to `adk-build-*` if implementation is needed>
- **Why this severity**: <one sentence>

Report template

# Repo Audit: <repo name>

## Summary
- Inventory: <languages>, <frameworks>, <package managers>, ~<LOC>
- Dimensions audited: <list>
- Findings: <N> Blocker, <N> Critical, <N> Should Have, <N> May Have, <N> Nitpick, <N> Question

## Top Risks
1. <one-line top risk>
2. <one-line top risk>

## Findings

### Blockers
<finding blocks>

### Critical
<finding blocks>

### Should Have
<finding blocks>

### May Have
<finding blocks>

### Nitpicks
<finding blocks>

### Questions
<finding blocks>

## Per-Dimension Notes
<short per-dimension narrative for context the findings cannot carry>

## Out of Scope
- <items not audited and why>

## Recommended Next Steps
1. <fix Blockers via `adk-build-*` skills>
2. <follow-up audit in <area> after fixes>

Depth modes

Mode	Behavior
quick	One pass per dimension, ~30 minutes for a small repo, surface-level findings
standard	Default; deeper grep / read; runs available analyzers (linter, type checker, audit)
deep	All of standard + sample-based code review of hot files + per-package per-file metrics

Anti-patterns

• Findings without a file anchor.
• "Best practice" findings the codebase does not actually need.
• Mixing fixes into the audit. The audit reports; fixes happen via adk-build-*.
• Letting nitpicks bury Blockers in the summary.
• Padding the report with restated inventory text - inventory is at the top, once.
• Reporting "no findings" without listing what was inspected. Show the work.

Examples

adk-audit-repo --dimensions security,dependencies --depth standard

adk-audit-repo /path/to/repo --depth deep --output .temp/reports/audit-repo-acme-2026-04.md

Clarifying questions (default-ask)

When running without --auto, the skill asks these questions in order, one at a time. Under --auto, the skill picks the safest option for each (see references/clarifying-questions.md) and reports the choices.

1. Which dimensions to audit (security / performance / quality / dependencies / tests / architecture / all)? — How to pick: All for new audits. Narrow when re-auditing a specific area or under time pressure.
2. Depth: quick / standard / deep? — How to pick: Quick = surface scan, ~30 min. Standard = run available analyzers (linter/typechecker/audit). Deep = sample-based code review of hot files + per-package metrics.
3. Are there extra repos to clone for cross-repo context (mono-repo subprojects, shared libs)? — How to pick: Pass URLs or paths. Each gets its own findings section in the report.

Default report: Top-of-file summary (counts per severity, top 3 risks) + severity-grouped findings + per-dimension notes + out-of-scope.

Detailed report (on request or --verbose): Add: file tree + LOC/language inventory, every analyzer command + output, suppressed findings list with reason, recommended fix order with effort estimate.

Artifact: audit-report — Markdown report.

Artifact path: .temp/reports/audit-repo-<slug>-<date>.md (raw analyzer output in .temp/notes/audit-<slug>/<dimension>.txt)

Pass extra repos via --repo <url-or-path> (repeatable). URLs are cloned into .temp/reference-repos/<owner>__<repo>/; paths are read in place. Each repo is processed independently and findings/citations are tagged with the repo of origin. See references/multi-repo.md for full handling.

Clarifying questions (default-ask)

When running without --auto, the skill asks these questions in order, one at a time. Under --auto, the skill picks the safest option for each (see references/clarifying-questions.md) and reports the choices.

1. Which dimensions to audit (security / performance / quality / dependencies / tests / architecture / all)? — How to pick: All for new audits. Narrow when re-auditing a specific area or under time pressure.
2. Depth: quick / standard / deep? — How to pick: Quick = surface scan, ~30 min. Standard = run available analyzers (linter/typechecker/audit). Deep = sample-based code review of hot files + per-package metrics.
3. Are there extra repos to clone for cross-repo context (mono-repo subprojects, shared libs)? — How to pick: Pass URLs or paths. Each gets its own findings section in the report.

Default vs detailed output

Default report: Top-of-file summary (counts per severity, top 3 risks) + severity-grouped findings + per-dimension notes + out-of-scope.

Detailed report (on request or --verbose): Add: file tree + LOC/language inventory, every analyzer command + output, suppressed findings list with reason, recommended fix order with effort estimate.

Artifact: audit-report — Markdown report.

Artifact path: .temp/reports/audit-repo-<slug>-<date>.md (raw analyzer output in .temp/notes/audit-<slug>/<dimension>.txt)

Multi-repo context

Pass extra repos via --repo <url-or-path> (repeatable). URLs are cloned into .temp/reference-repos/<owner>__<repo>/; paths are read in place. Each repo is processed independently and findings/citations are tagged with the repo of origin. See references/multi-repo.md for full handling.

<!-- adk:references:start -->

References shipped with this skill

These files live in references/ next to this SKILL.md. Read them when the skill activates; they are inlined here so the skill is fully self-contained (no cross-skill or shared sources).

File	Purpose
references/anti-patterns.md	Things to avoid when running this skill.
references/artifact-format.md	The deliverable's format and where it lives (.temp/ contract).
references/clarifying-questions.md	The default-ask questions for this skill, with how-to-pick rubrics.
references/constitution.md	Non-negotiable rules and working/communication discipline.
references/interaction-contract.md	Default-ask, explained-options, --auto contract every skill must follow.
references/multi-repo.md	How to consume context from extra cloned or local-path repos.
references/output-format.md	Default vs detailed report shapes; severity labels; verbosity rules.
references/persona.md	The agent persona that drives this skill.
references/research-protocol.md	Source ordering, stop conditions, evidence buckets, citation discipline.
references/review-comment-format.md	Standard finding format with stable IDs and severities.
references/working-artifacts.md	Legacy: superseded by artifact-format.md; kept for back-compat.

<!-- adk:references:end -->