lindoelio/spec-driven-steroids/agent-work-auditor

agent-work-auditor

A unified, modular auditing framework for AI agent workflows. Provides adversarial audits designed to find gaps and block premature approval. Every audit must switch the agent from author mode to critic mode and force specific, named weaknesses to be surfaced.

Activation

Load this skill when:

• User asks to audit code, a PR, or a change set
• Spec-driven Code Review requires auditing
• User mentions "are you sure?" after producing work
• User wants verification of completeness or correctness

Three-Layer Architecture

Layer 1: Core (Always Active)

Universal dimensions evaluated for every audit:

Layer 2: Change-Type Modules (Per-Invocation)

Loaded based on detected change type:

Layer 3: Context Extensions (Auto-Detected)

Activated when relevant context is detected:

• spec-driven — When .specs/ or spec artifacts found
• (Extensible for future context types)

Invocation

Input Parameters

Invocation Patterns

# Explicit type
"Audit this PR using agent-work-auditor, type:feat"
 
# Quick check
"Quick audit on these changes"
 
# Spec-driven (auto-loads spec-driven extension)
"Validate the spec implementation"
 
# Combined types
"Audit this refactor+fix"

Audit Workflow

1. DETECT change type
   └─ Explicit tag → Branch scan → Commit scan → Heuristic → Fallback
 
2. DETECT artifact type
   └─ code | specification | design | tasks | mixed
 
3. GATHER context
   └─ Style guide, conventions, project docs
 
4. ACTIVATE layers
   └─ Core (always) → Type module → Extensions (if detected)
 
5. EVALUATE dimensions
   └─ Universal (7) → Type-specific → Extension-specific
 
6. CLASSIFY findings
   └─ Severity (blocking, warning, info)
   └─ Fixability (direct-fix, author-required, informational)
 
7. SELF-FIX LOOP
   └─ Pass 1: Apply direct-fix → Re-review
   └─ Pass 2: Apply direct-fix → Re-review
   └─ Escalate remaining to author-required
 
8. OUTPUT
   └─ Markdown report + JSON (machine consumption)

Finding Classification

Severity Axis

Fixability Axis

Prefixes

• No prefix for blocking findings
• Nit: for non-blocking polish suggestions
• Mentoring: for educational comments

Self-Fix Loop

1. For each direct-fix finding:

• Apply the fix autonomously
• Re-review to verify no new issues
• If new blocking issues: rollback, mark author-required

1. Max 3 passes to prevent infinite loops

1. After max passes, escalate remaining direct-fix to author-required

Output Format

Markdown Report

# Audit Report — {change-type}
 
**Artifact:** {path}
**Timestamp:** {ISO-8601}
**Verdict:** Approve | Request Changes | Approval with Notes
 
## Summary
{2-3 sentence assessment}
 
## Direct Fixes Applied
| Finding | Fix Applied | Status |
|---------|-------------|--------|
| ... | ... | fixed |
 
## Blocking Findings
| Finding | Decision Needed | Status |
|---------|---------------|--------|
| ... | ... | pending |
 
## Nit Findings
| Finding | Suggestion | Status |
|---------|------------|--------|
| ... | ... | fixed |
 
## Traceability Matrix (spec-driven only)
| REQ | DES | TASK | Coverage |
|-----|-----|------|----------|

JSON Output

{
  "artifact": "{path}",
  "changeType": "{type}",
  "timestamp": "{ISO-8601}",
  "verdict": "Approve | Request Changes | Approval with Notes",
  "dimensions": {
    "{dimension}": {
      "score": 1-5,
      "findings": []
    }
  },
  "findings": [
    {
      "severity": "blocking | warning | info",
      "fixability": "direct-fix | author-required | informational",
      "title": "...",
      "description": "...",
      "fix": "...",
      "status": "fixed | pending | escalated"
    }
  ],
  "summary": "..."
}

Verdict Rules

• Approve — No blocking findings remain.
• Approval with Notes — No blocking findings, non-blocking concerns documented.
• Request Changes — Blocking findings remain.

Context Detection

Detection happens in priority order:

1. Explicit config (auditor.json) — apply configured defaults
2. Directory scan (.specs/) — auto-load spec-driven extension
3. File scan (requirements.md, design.md, tasks.md) — auto-load spec-driven
4. Package scan (package.json, Cargo.toml) — domain inference
5. Fallback — general-purpose audit

Portability

• Zero external dependencies
• Works standalone in any project
• Optional auditor.json for configuration

Reference Loading

Load reference files on demand:

Migration Auditing

When migrate type is detected:

1. Phase 0 (Gating): Codebase Inventory must complete before requirements
2. Eight Dimensions: DIM-1 through DIM-8 with 1-5 scoring
3. Prove-It Challenges: Agent must demonstrate comprehension
4. Approval Threshold: ALL 8 dimensions must score 5+ (any <5 blocks)

See references/migration/ for detailed migration auditing.