Agent-Skills.md

Agent Skills: Grove Audit

Unified codebase audit that launches 10 parallel micro-lane subagents to check compliance, security, and quality. Auto-fixes deterministic issues, reports everything else inline. Three modes — quick (branch diff), standard (changed packages), full (entire codebase).

UncategorizedID: autumnsgrove/groveengine/grove-audit

Repository

autumnsgrove/groveengine
AutumnsGroveLicense: NOASSERTION
5

Install this agent skill to your local

pnpm dlx add-skill https://github.com/AutumnsGrove/Lattice/tree/HEAD/.claude/skills/grove-audit

Skill Files

Browse the full folder contents for grove-audit.

Download Skill

Loading file tree…

.claude/skills/grove-audit/SKILL.md

Skill Metadata

Name
grove-audit
Description
Unified codebase audit that launches 10 parallel micro-lane subagents to check compliance, security, and quality. Auto-fixes deterministic issues, reports everything else inline. Three modes — quick (branch diff), standard (changed packages), full (entire codebase).

Grove Audit

A fleet of 10 narrow-scoped subagents, each checking one thing well. Deterministic violations get auto-fixed and committed. Judgment calls get reported inline with file:line evidence.

When to Activate

  • User says /grove-audit, /grove-audit quick, /grove-audit standard, or /grove-audit full
  • User asks for a comprehensive code review, compliance check, or codebase sweep
  • Before major merges or releases
  • After large refactors to catch regressions
  • During active development to sweep for legacy violations

Modes

| Mode | Scope | When to Use | |------|-------|-------------| | quick | Branch diff vs main | Iterative development, pre-commit check | | standard | Changed packages (git diff + affected deps) | Pre-merge, after refactors | | full | Entire codebase via Lumen + grep | Periodic sweeps, post-refactor cleanup, first-time audit |

Default when no mode specified: infer from context. On a feature branch with changes → standard. On main with no changes → full. User specified a scope → use that.

Protocol

SCOPE → DISCOVER → DISPATCH → COLLECT → FIX → REPORT
  ↓        ↓          ↓          ↓        ↓       ↓
 Mode    Files     10 agents   Results  Commit  Inline

Phase 1: SCOPE

Determine the audit mode and file set.

Quick mode:

git diff main...HEAD --name-only

Standard mode:

git diff main...HEAD --name-only
# Plus: identify affected packages from changed files
# Include downstream consumers of changed libs

Full mode:

  • No file filtering — each lane agent discovers its own targets via Lumen semantic search + grep/glob
  • Each agent gets the full codebase as its search space

Phase 2: DISCOVER

For quick/standard modes, build the file list and pass it to each agent. For full mode, each agent does its own discovery — this is the key advantage of full sweeps.

Lumen is the primary discovery tool. Each agent should query Lumen first to find files related to its concern, then use grep/glob to verify and catch stragglers. Agents have full access to all search tools — Lumen, grep, glob, find. No handicaps.

Phase 3: DISPATCH

Launch all 10 lane agents in parallel using the Agent tool. Each agent gets:

  1. Its lane reference doc (from references/)
  2. The mode and file scope (for quick/standard) or "full sweep" instruction
  3. Clear output format expectations

The 10 Lanes:

| # | Lane | Agent Type | Reference | Auto-Fix? | |---|------|------------|-----------|-----------| | 1 | Barrel Imports | sonnet-coder | references/barrel-imports.md | Yes | | 2 | Icon Gateway | sonnet-coder | references/icon-gateway.md | Yes | | 3 | CSRF / Fetch Safety | sonnet-coder | references/csrf-fetch.md | Yes | | 4 | Accent Tokens | sonnet-coder | references/accent-tokens.md | Yes | | 5 | Signpost Compliance | sonnet-coder | references/signpost.md | No | | 6 | SDK Boundaries | sonnet-coder | references/sdk-boundaries.md | No | | 7 | Data Primacy | sonnet-coder | references/data-primacy.md | No | | 8 | Type Safety | sonnet-coder | references/type-safety.md | No | | 9 | Security (STRIDE) | opus-coder | references/security.md | No | | 10 | Test Coverage | sonnet-coder | references/test-coverage.md | No |

Why opus for security only: STRIDE threat modeling requires deeper reasoning about attack surfaces and trust boundaries. The other lanes are pattern-matching tasks where sonnet excels.

Agent prompt template:

Each agent receives:

  1. The full content of its reference doc (read it and include it in the prompt)
  2. Mode + file scope
  3. Instructions to use Lumen (mcp__lumen__semantic_search) as primary discovery, supplemented by grep/glob
  4. Output format: structured findings list with file:line, severity, and fix description
  5. For auto-fix lanes (1-4): instructions to make the fixes directly
  6. For report lanes (5-10): read-only — return findings only

Phase 4: COLLECT

Wait for all 10 agents to complete. Gather their results.

Phase 5: FIX

For auto-fix lanes (1-4) that made changes:

  1. Review the changes each agent made (verify they're correct)
  2. Stage the fixed files
  3. Commit with a descriptive message:
git commit -m "$(cat <<'EOF'
fix(audit): auto-fix [barrel imports|icon gateway|CSRF fetch|accent tokens]

[Summary of what was fixed, e.g., "12 barrel imports converted to direct imports"]

Co-Authored-By: Claude (Grove Agent)
EOF
)"

Group related fixes into logical commits — one per auto-fix lane that had changes.

Phase 6: REPORT

Compile the inline report from all 10 lanes. Format:

================================================================================
 GROVE AUDIT REPORT
 Mode: [quick|standard|full] | Files scanned: N | Date: YYYY-MM-DD
================================================================================

AUTO-FIXED (committed)
--------------------------------------------------------------------------------
Lane 1 — Barrel Imports: N fixes applied
Lane 2 — Icon Gateway: N fixes applied
Lane 3 — CSRF / Fetch: N fixes applied
Lane 4 — Accent Tokens: N fixes applied

FINDINGS (requires manual attention)
--------------------------------------------------------------------------------

[CRITICAL] ──────────────────────────────────────
  1. [SDK Boundaries] libs/engine/src/lib/foo.ts:42
     Raw env.DB.prepare() — use GroveDatabase from @autumnsgrove/infra
  ...

[HIGH] ──────────────────────────────────────────
  ...

[MEDIUM] ────────────────────────────────────────
  ...

[LOW] ───────────────────────────────────────────
  ...

SUMMARY
--------------------------------------------------------------------------------
┌──────────────────────────┬────────┬───────┬──────────────┐
│ Lane                     │ Status │ Found │ Fixed        │
├──────────────────────────┼────────┼───────┼──────────────┤
│ 1. Barrel Imports        │ ✓ FIXED│   12  │ 12 auto-fix  │
│ 2. Icon Gateway          │ ✓ CLEAN│    0  │ —            │
│ 3. CSRF / Fetch          │ ✓ FIXED│    3  │ 3 auto-fix   │
│ 4. Accent Tokens         │ ✓ CLEAN│    0  │ —            │
│ 5. Signpost Compliance   │ ⚠ WARN │    5  │ manual       │
│ 6. SDK Boundaries        │ ✗ FAIL │    8  │ manual       │
│ 7. Data Primacy          │ ✓ PASS │    0  │ —            │
│ 8. Type Safety           │ ⚠ WARN │    2  │ manual       │
│ 9. Security (STRIDE)     │ ✓ PASS │    0  │ —            │
│ 10. Test Coverage        │ ⚠ WARN │    4  │ manual       │
└──────────────────────────┴────────┴───────┴──────────────┘

Total: 34 findings | 15 auto-fixed | 19 manual | 0 critical
================================================================================

Severity Classification

| Severity | Meaning | Examples | |----------|---------|---------| | CRITICAL | Exploitable vulnerability or data leak | Raw env.DB without tenant scoping, adminMessage in client response, timing-unsafe secret comparison | | HIGH | Architectural violation that compounds | Raw SDK bypass (env.DB, env.BUCKET), duplicated data sources, missing rate limiting on auth | | MEDIUM | Pattern violation, not dangerous | Barrel imports, bare Lucide icons, hardcoded accent colors, missing Signpost errors | | LOW | Style/hygiene, no functional impact | Missing tests for utilities, Svelte 5 store usage, stale TODO comments |

Agent Prompting Guide

When dispatching each lane agent, read the corresponding reference file and include its full content in the agent prompt. Structure each prompt as:

You are a focused code auditor for the Grove/Lattice monorepo.
Your ONLY job is: [lane description].

MODE: [quick|standard|full]
SCOPE: [file list for quick/standard, or "full codebase" for full]

RULES (from reference doc):
[paste full reference content]

DISCOVERY:
- Use mcp__lumen__semantic_search as your primary discovery tool
- Supplement with grep and glob for exact pattern matching
- For full mode: discover your own targets, don't wait for a file list

OUTPUT FORMAT:
Return a structured list of findings:
- file_path:line_number
- severity: CRITICAL | HIGH | MEDIUM | LOW
- description: what's wrong
- fix: what to do instead (or "auto-fixed" for lanes 1-4)

[For auto-fix lanes 1-4 only:]
AUTO-FIX: You MUST fix deterministic violations directly using Edit.
After fixing, report what you changed.

[For report lanes 5-10:]
READ-ONLY: Do NOT edit any files. Report findings only.

Suppression Comments

Each lane respects specific suppression comments. These are documented in the lane references:

| Lane | Suppression | Effect | |------|-------------|--------| | Barrel Imports | // barrel-ok | Skip this import | | Icon Gateway | // prism-ok | Allow bare Lucide import | | CSRF / Fetch | // csrf-ok | Allow bare fetch() | | Accent Tokens | // accent-ok | Allow hardcoded color | | SDK Boundaries | // boundary-ok | Allow raw binding | | Signpost | // error-ok | Allow bare throw/console |

What Grove Audit Does NOT Do

  • Run tests or type checks — use gw ci for that
  • Review prose or documentation — code patterns only
  • Judge style preferences — "I'd name this differently" is not a finding
  • Audit dependencies — use pnpm audit for that
  • Replace targeted skills — hawk-survey for deep security, deer-sense for a11y, etc.

Integration

Before audit: Ensure Lumen index is fresh (mcp__lumen__index_status) After audit: Use the report to prioritize manual fixes For auto-fixes: Review the committed changes with git diff HEAD~1 if desired