audit

Files (1)

• SKILL.md

SKILL.md (first lines)

> **Tool mapping (OpenCode):** This skill uses:
> - `question` tool for user prompts (not `AskUserQuestion`)
> - `task` tool for subagents (not `Agent` or `Task` subagent syntax)
> - `skill({ name: "..." })` to load other skills (not `Skill(skill="...", args="...")`)
> - `codegraph_explore`, `codegraph_search`, `codegraph_context` for codebase exploration (preferred)
> - `todowrite` for phase/progress tracking
> - `grep`, `glob`, `read`, `bash` as fallback when `.codegraph/` not initialized
>
> **Context rule:** This skill supersedes any prior skill instructions. Follow ONLY these instructions now. Read the user's goal and any mode/include/skip from the conversation context.

Read `mode=`, `include=`, and `skip=` from the conversation context. Default to the mode specified in this skill if not provided. If `skip=` is present, exclude those audits from the battery.

# Audit

A whole-codebase tech-debt sweep. The diff-scoped `simplify` and the per-concern `audit-*` / `harden-*` skills each cover a slice; this skill runs the full battery against the whole repo, deduplicates findings, and walks the user through fixes. It is heavier than `simplify` and slower than any single `audit-*` — invoke it deliberately.

---

## Phase 1 — Scope and confirm

Use `todowrite` to mark this phase as `in_progress`. Mark it `completed` when done.

1. Detect repo root, primary language(s), frameworks (TanStack/Next/Electron/etc.), and rough size: `git ls-files | wc -l`.
2. If the working tree is dirty, surface it: an audit on top of in-progress changes will tangle findings with WIP. Ask via `question`: "(s)tash and audit clean tree / (a)udit current state / (q)uit". Default `s`.
3. If the repo has >2000 source files, ask the user to narrow scope (a directory, a feature area, a route group) before running. A whole-monorepo audit produces noise instead of signal.
4. Announce the battery of audit skills that will run (Phase 4) so the user knows what's coming and can `skip=` any.

**Inputs accepted from caller (e.g., `ship`):**
- `scope=<path>` — narrow to a directory
- `skip=<csv>` — comma-separated list of audit skill names to skip
- `mode=fast|balanced|production` — `fast` runs only `simplify` + typecheck/lint; `balanced` adds the high-leverage audits; `production` runs everything. Default `balanced` when invoked directly; honor caller-supplied mode otherwise.

---

## Phase 2 — Architecture and data-flow map

Use `todowrite` to mark this phase as `in_progress`. Mark it `completed` when done.

**Prefer `codegraph_explore`** for tracing entry points, state stores, data-access modules, and call graphs. Use `codegraph_search` for finding symbols by name. Fall back to `grep` + `read` + `glob` only when `.codegraph/` is not initialized (mention the user can run `codegraph init -i`).

Before judging structure, understand it:

1. Identify app entry points, route/server boundaries, state stores, data-access modules, job/worker entry points, and external integration boundaries.
2. Trace the main data flow for 2–3 representative user actions: UI/input -> validation -> API/server function -> domain/use-case -> persistence/external service -> cache invalidation/refetch -> rendered state.
3. Name ownership boundaries: which modules own domain rules, persistence, UI composition, infrastructure concerns, and cross-cutting utilities.
4. Record architecture smells separately from code smells: mixed UI/data access, duplicate domain rules, unclear source of truth, circular dependencies, cross-layer imports, stale cache patterns, overgrown modules.
5. **Structural hygiene pass.** Walk the directory tree and flag layout rot — *don't* fix it here, just record findings for Phase 5:
   - Directories with mixed concerns (UI components next to data-access next to domain logic with no separation).
   - Files that have outgrown their location (a single 800-line file holding three unrelated features; a `utils.ts` that has become a junk drawer).
   - Naming drift (sibling files using inconsistent casing/conventions; "v2"/"new"/"old" suffixes that stuck around).
   - Misplaced files (tests not co-located with the convention; types floating in random folders; one-off scripts in `src/`).
   - Dead directories (empty folders, or folders whose last meaningful change is ancient and whose contents look orphaned).
   If layout issues are material, the Phase 5 report should call them out and recommend invoking `reorganize-files` as a follow-up — *after* the in-place fixes land, so the move diff isn't tangled with content changes.

Output a short architecture summary before running the audit battery. If you cannot name the data flow, keep exploring; otherwise the findings will be local observations without system context.

---

## Phase 3 — Baseline gates

Use `todowrite` to mark this phase as `in_progress`. Mark it `completed` when done.

Run first, in parallel via Bash:
- Project typecheck (e.g., `tsc --noEmit`, `pyright`, `cargo check`)
- Linter (e.g., `eslint`, `ruff`, `clippy`)
- Formatter check (no auto-fix yet)
- Test suite (smoke only — full run gated to Phase 7)

Baseline failures get fixed first. Stacking refactors on top of a red baseline buries the signal.

---

## Phase 4 — Parallel audit fan-out

Use `todowrite` to mark this phase as `in_progress`. Mark it `completed` when done.

Launch the applicable audit skills concurrently via `skill({ name: "..." })`, each scoped to the agreed Phase 1 scope (not just the diff). Pass `mode=audit` so each skill knows it's running repo-wide and should not auto-fix.

**Host-portability fallback.** If the `skill()` call is not available in the current session (Codex and other non-OpenCode hosts), Read each applicable skill's SKILL.md at `skills/<skill-name>/SKILL.md` and execute them sequentially in this turn, treating each as the next phase of work. Reviewer subagents (`reviewer-*`) still go through `task({ subagent_type: "general", ... })` — most CLIs that lack `skill()` still have a general-purpose agent primitive, and you can pass the reviewer's SKILL.md path to it. Surface the degradation up-front: tell the user "Skill tool unavailable — audits will run inline, sequentially, without subagent isolation." Inline sequential execution is slower and loses fan-out parallelism, but the findings are still produced.

**Always (every mode):**
- `skill({ name: "simplify" })` — DRY, magic numbers, naming, oversized files, parallel-enum drift, repeated literals (override default diff-only scope to Phase 1 scope)
- `skill({ name: "harden-types" })` — strip `any`, dangerous casts, missing return types, missing boundary validation

**Balanced and production:**
- **`reviewer-data-integrity`** — dispatch via `task({ subagent_type: "reviewer-data-integrity", description: "Audit data integrity", prompt: "Audit data integrity across the repo. Scope: <Phase 1 scope>. Return severity-ranked findings with file:line refs." })`.
- **`reviewer-error-boundaries`** — dispatch via `task({ subagent_type: "reviewer-error-boundaries", description: "Audit error boundaries", prompt: "Audit error boundaries across the repo. Scope: <Phase 1 scope>. Return severity-ranked findings with file:line refs." })`.
- **`reviewer-loading-states`** — dispatch via `task({ subagent_type: "reviewer-loading-states", description: "Audit loading states", prompt: "Audit loading states across the repo. Scope: <Phase 1 scope>. Return severity-ranked findings with file:line refs." })`.
- **`reviewer-contracts`** — dispatch via `task({ subagent_type: "reviewer-contracts", description: "Audit contracts", prompt: "Audit contracts across the repo. Scope: <Phase 1 scope>. Return severity-ranked findings with file:line refs." })`.
- **`reviewer-observability-coverage`** — dispatch via `task({ subagent_type: "reviewer-observability-coverage", description: "Audit observability coverage", prompt: "Audit observability coverage across the repo. Scope: <Phase 1 scope>. Return severity-ranked findings with file:line refs." })`.
- **`reviewer-perf`** — dispatch via `task({ subagent_type: "reviewer-perf", description: "Audit performance", prompt: "Audit performance across the repo. Scope: <Phase 1 scope>. Isolate the read-heavy perf audit. Return severity-ranked findings with file:line refs." })`. The `audit-perf` skill remains available as a manual entry point.

**Production only (additionally):**
- **`reviewer-security-regression`** — dispatch via `task({ subagent_type: "reviewer-security-regression", description: "Audit security regression", prompt: "Audit security regression across the repo. Scope: <Phase 1 scope>. Isolate the read-heavy security audit. Return severity-ranked findings with file:line refs." })`.
- **`reviewer-concurrency`** — dispatch via `task({ subagent_type: "reviewer-concurrency", description: "Audit concurrency", prompt: "Audit concurrency across the repo. Scope: <Phase 1 scope>. Return severity-ranked findings with file:line refs." })`.
- **`reviewer-client-bundle`** — dispatch via `task({ subagent_type: "reviewer-client-bundle", description: "Audit client bundle", prompt: "Audit client bundle across the repo. Scope: <Phase 1 scope>. Return severity-ranked findings with file:line refs." })`.
- **`reviewer-accessibility-regression`** — dispatch via `task({ subagent_type: "reviewer-accessibility-regression", description: "Audit accessibility regression", prompt: "Audit accessibility regression across the repo. Scope: <Phase 1 scope>. Return severity-ranked findings with file:line refs." })`.

**Stack-conditional (auto-include when the stack matches):**
- TanStack Start present → `skill({ name: "code-enforce-route-data" })`, `skill({ name: "code-enforce-layers" })`

Honor `skip=` from the caller. Do not run audits the user explicitly excluded.

---

## Phase 5 — Consolidate findings

Use `todowrite` to mark this phase as `in_progress`. Mark it `completed` when done.

Each audit returns a list. Merge into one report grouped by **severity** (critical / suggested / nit), then by **category**, then by **file**. Deduplicate findings that multiple audits flagged (e.g., a `Promise.all` miss flagged by both `audit-perf` and `simplify`) — keep one entry, cite both sources.

Print the architecture summary and consolidated report **before** applying anything. Format:

```
Architecture summary
  entry points: <routes/server/jobs>
  data flow:    <core path in one line>
  boundaries:   <what owns UI/domain/data/infrastructure>

From Acauhi99/opencode-agent-system, MIT.

More from Acauhi99/opencode-agent-system