Audit

/audit Workflow

Inputs

• Scope: $ARGUMENTS (optional: "plan", "code", "full")
  • plan: Audit a plan file before implementation
  • code: Audit recent uncommitted changes (default)
  • full: Full codebase scan

Role

You are the audit coordinator. You dispatch security, performance, and QA scans, then synthesize results into actionable reports. You do NOT fix issues yourself — you identify and report them with severity ratings.

Step 1 — Determine scope

Tool: Bash (direct — coordinator does this)

Run: git status --porcelain

Scope resolution:

• If $ARGUMENTS is empty:
  • If git status shows uncommitted changes: scope = "code"
  • Else: scope = "full"
• Else: scope = $ARGUMENTS

Validate scope is one of: plan, code, full. If not, stop with: "Invalid scope. Use: /audit [plan|code|full]"

Derive timestamp: [timestamp] = current ISO datetime (e.g., 2026-02-07T12-30-00)

Initialize audit logging:

Tool: Bash

# --- Audit Logging Setup ---
RUN_ID=$(date +%Y%m%d-%H%M%S)-$(cat /dev/urandom | LC_ALL=C tr -dc 'a-z0-9' | head -c 6)
AUDIT_LOG_DIR="./plans/audit-logs"
mkdir -p "$AUDIT_LOG_DIR"
AUDIT_LOG="$AUDIT_LOG_DIR/audit-${RUN_ID}.jsonl"
STATE_FILE=".audit-audit-state-${RUN_ID}.json"

python3 -c "
import json
state = {
    'run_id': '${RUN_ID}',
    'audit_log': '${AUDIT_LOG}',
    'skill': 'audit',
    'skill_version': '3.2.0',
    'security_maturity': 'advisory',
    'hmac_key': ''
}
with open('${STATE_FILE}', 'w') as f:
    json.dump(state, f)
print('Audit skill state file created: ${STATE_FILE}')
"

bash scripts/emit-audit-event.sh "$STATE_FILE" \
  "{\"event_type\":\"run_start\",\"scope\":\"${AUDIT_SCOPE:-unknown}\"}"

bash scripts/emit-audit-event.sh "$STATE_FILE" \
  '{"event_type":"step_start","step":"step_1_determine_scope","step_name":"Determine scope","agent_type":"coordinator"}'

echo "Audit skill log: $AUDIT_LOG"

Emit step_end for Step 1:

Tool: Bash

bash scripts/emit-audit-event.sh ".audit-audit-state-${RUN_ID}.json" \
  '{"event_type":"step_end","step":"step_1_determine_scope","step_name":"Determine scope","agent_type":"coordinator"}'

Step 2 — Security scan

Emit step_start for Step 2:

Tool: Bash

bash scripts/emit-audit-event.sh ".audit-audit-state-${RUN_ID}.json" \
  '{"event_type":"step_start","step":"step_2_security_scan","step_name":"Security scan","agent_type":"coordinator"}'

Secure-review composability check:

Tool: Glob

Glob for ~/.claude/skills/secure-review/SKILL.md

If found AND scope is NOT "plan":

• Output: "Using /secure-review for deep security analysis (composability mode)."
• Dispatch /secure-review instead of the built-in security scan.

Tool: Task, subagent_type=general-purpose, model=claude-opus-4-6

Prompt: "You are running a deep security review as part of the /audit workflow.

Read the secure-review skill definition at ~/.claude/skills/secure-review/SKILL.md. Execute its full scanning workflow (vulnerability, data flow, auth/authz scans).

Scope: [map audit scope to secure-review scope: 'code' -> 'changes', 'full' -> 'full']

Write your findings to ./plans/audit-[timestamp].security.md (use the audit naming convention, not the secure-review convention, so the synthesis step can find it).

Include the standard secure-review output: verdict, severity-rated findings, redacted secrets.

CRITICAL: Never include actual secret values. Redact to first 4 / last 4 characters."

Skip the existing built-in security scan below. Proceed to Step 3 (Performance scan).

If not found OR scope is "plan":

• If not found: Output: "secure-review skill not deployed. Using built-in security scan."
• If scope is "plan": Output: "Scope is 'plan' — using built-in plan security analysis (secure-review scans code, not plans)."
• Continue with the existing built-in security scan (unchanged behavior below).

Pre-check: Glob for .claude/agents/security-analyst*.md

Tool: Glob (direct — coordinator does this)

Pattern: .claude/agents/security-analyst*.md

If found: "Using project-specific security-analyst for security scan" If not found: "No project-specific security-analyst found. Using generic Task subagent for security scan. For project-tailored scanning, generate one: gen-agent . --type security-analyst"

Tool: Task, subagent_type=general-purpose, model=claude-opus-4-6

If scope is "plan":

• If security-analyst agent found: Prompt: "Read .claude/agents/security-analyst*.md for your role context and scanning frameworks (STRIDE, OWASP Top 10, DREAD, compliance checklists). Then read the plan file at $ARGUMENTS (after 'plan' keyword). Analyze for security risks:

  • Authentication/authorization gaps
  • Data exposure risks
  • Input validation requirements
  • Cryptographic requirements
  • Secrets management

  Rate findings: Critical / High / Medium / Low. Write to ./plans/audit-[timestamp].security.md"

• If security-analyst agent not found: Prompt: "Read the plan file at $ARGUMENTS (after 'plan' keyword). Analyze for security risks:

  • Authentication/authorization gaps
  • Data exposure risks
  • Input validation requirements
  • Cryptographic requirements
  • Secrets management

  Rate findings: Critical / High / Medium / Low. Write to ./plans/audit-[timestamp].security.md"

If scope is "code":

• If security-analyst agent found: Prompt: "Read .claude/agents/security-analyst*.md for your role context and scanning frameworks (STRIDE, OWASP Top 10, DREAD, compliance checklists). Then scan uncommitted changes for:

  • SQL injection vulnerabilities
  • XSS vulnerabilities
  • Exposed secrets (API keys, passwords, tokens)
  • Authentication bypasses
  • Authorization gaps
  • OWASP Top 10 vulnerabilities
  • Dependency vulnerabilities

  Rate findings: Critical / High / Medium / Low. Write to ./plans/audit-[timestamp].security.md"

• If security-analyst agent not found: Prompt: "Scan uncommitted changes for:

  • SQL injection vulnerabilities
  • XSS vulnerabilities
  • Exposed secrets (API keys, passwords, tokens)
  • Authentication bypasses
  • Authorization gaps
  • OWASP Top 10 vulnerabilities
  • Dependency vulnerabilities

  Rate findings: Critical / High / Medium / Low. Write to ./plans/audit-[timestamp].security.md"

If scope is "full":

• If security-analyst agent found: Prompt: "Read .claude/agents/security-analyst*.md for your role context and scanning frameworks (STRIDE, OWASP Top 10, DREAD, compliance checklists). Then perform a full codebase security audit:

  • SQL injection, XSS, CSRF vulnerabilities
  • Exposed secrets in code and config files
  • Authentication and authorization implementation
  • Dependency vulnerabilities (check package manifests)
  • Insecure cryptography
  • OWASP Top 10 compliance

  Rate findings: Critical / High / Medium / Low. Write to ./plans/audit-[timestamp].security.md"

• If security-analyst agent not found: Prompt: "Full codebase security audit:

  • SQL injection, XSS, CSRF vulnerabilities
  • Exposed secrets in code and config files
  • Authentication and authorization implementation
  • Dependency vulnerabilities (check package manifests)
  • Insecure cryptography
  • OWASP Top 10 compliance

  Rate findings: Critical / High / Medium / Low. Write to ./plans/audit-[timestamp].security.md"

Emit step_end for Step 2:

Tool: Bash

bash scripts/emit-audit-event.sh ".audit-audit-state-${RUN_ID}.json" \
  '{"event_type":"step_end","step":"step_2_security_scan","step_name":"Security scan","agent_type":"coordinator"}'

Step 3 — Performance scan

Emit step_start for Step 3:

Tool: Bash

bash scripts/emit-audit-event.sh ".audit-audit-state-${RUN_ID}.json" \
  '{"event_type":"step_start","step":"step_3_performance_scan","step_name":"Performance scan","agent_type":"coordinator"}'

Tool: Task, subagent_type=general-purpose, model=claude-sonnet-4-6

If scope is "plan": Prompt: "Read the plan file at $ARGUMENTS (after 'plan' keyword). Analyze for performance risks:

• Algorithm complexity concerns
• Database query patterns
• Caching strategy
• Scalability bottlenecks

Rate findings: Critical / High / Medium / Low. Write to ./plans/audit-[timestamp].performance.md"

If scope is "code": Prompt: "Analyze uncommitted changes for:

• O(n²) or worse algorithms
• N+1 query patterns
• Missing database indexes
• Memory leaks
• Inefficient data structures
• Unnecessary I/O operations

Rate findings: Critical / High / Medium / Low. Write to ./plans/audit-[timestamp].performance.md"

If scope is "full": Prompt: "Full codebase performance audit:

• Algorithm complexity analysis
• Database query optimization opportunities
• Missing indexes
• Memory leak patterns
• Inefficient data structures
• I/O bottlenecks

Rate findings: Critical / High / Medium / Low. Write to ./plans/audit-[timestamp].performance.md"

Emit step_end for Step 3:

Tool: Bash

bash scripts/emit-audit-event.sh ".audit-audit-state-${RUN_ID}.json" \
  '{"event_type":"step_end","step":"step_3_performance_scan","step_name":"Performance scan","agent_type":"coordinator"}'

Step 4 — QA regression (conditional)

Trigger: Only run if scope is "code" or "full" (skip for "plan")

Emit step_start for Step 4:

Tool: Bash

bash scripts/emit-audit-event.sh ".audit-audit-state-${RUN_ID}.json" \
  '{"event_type":"step_start","step":"step_4_qa_regression","step_name":"QA regression","agent_type":"coordinator"}'

Pre-check: Verify qa-engineer agent exists

Tool: Glob (direct — coordinator does this)

Pattern: .claude/agents/qa-engineer*.md or .claude/agents/qa*.md

If no files match:

• Write note to ./plans/audit-[timestamp].qa.md:

  # QA Regression — Skipped
  
  **Status:** QA agent not found
  
  No qa-engineer agent found in `.claude/agents/`. Skipping regression tests.
  
  To enable QA regression tests, generate a QA agent:
  ```bash
  python3 ~/workspaces/claude-devkit/generators/generate_agents.py . --type qa-engineer
  

• Continue to Step 5 (do not block workflow).

If QA agent exists:

Tool: Task, subagent_type=general-purpose, model=claude-sonnet-4-6

Prompt: "You are running QA regression validation. Read the .claude/agents/ directory to find the qa-engineer agent. Follow that agent's testing standards.

Run the full test suite and analyze results.

Write ./plans/audit-[timestamp].qa.md with:

• Test results (passed/failed/skipped counts)
• Coverage delta (if measurable)
• Flaky tests (tests that fail intermittently)
• Missing test coverage (critical paths without tests)
• Test performance (slow tests > 1s)

If no test command is found or tests cannot run, document this limitation."

Emit step_end for Step 4:

Tool: Bash

bash scripts/emit-audit-event.sh ".audit-audit-state-${RUN_ID}.json" \
  '{"event_type":"step_end","step":"step_4_qa_regression","step_name":"QA regression","agent_type":"coordinator"}'

Step 5 — Synthesis

Emit step_start for Step 5:

Tool: Bash

bash scripts/emit-audit-event.sh ".audit-audit-state-${RUN_ID}.json" \
  '{"event_type":"step_start","step":"step_5_synthesis","step_name":"Synthesis","agent_type":"coordinator"}'

Tool: Read (direct — coordinator does this)

Read all audit reports:

• ./plans/audit-[timestamp].security.md
• ./plans/audit-[timestamp].performance.md
• ./plans/audit-[timestamp].qa.md (if exists)

Generate ./plans/audit-[timestamp].summary.md with this structure:

# Audit Summary — [scope] — [timestamp]

## Verdict
[PASS / PASS_WITH_NOTES / BLOCKED]

## Critical Findings
[Count: N]
- [Finding 1 from any report]
- [Finding 2 from any report]

## High Findings
[Count: N]
- [Finding 1 from any report]
- [Finding 2 from any report]

## Medium Findings
[Count: N]
(Summarize or list)

## Low Findings
[Count: N]
(Summarize or list)

## Risk Score
[1-10 scale]
- 1-3: Low risk (PASS)
- 4-6: Medium risk (PASS_WITH_NOTES)
- 7-10: High risk (BLOCKED)

## Action Items
(Prioritized list of what must be fixed)

1. [Critical item 1]
2. [Critical item 2]
3. [High item 1]
...

## Reports
- Security: ./plans/audit-[timestamp].security.md
- Performance: ./plans/audit-[timestamp].performance.md
- QA: ./plans/audit-[timestamp].qa.md (if run)

Verdict rules:

• BLOCKED: Any Critical findings OR 3+ High findings
• PASS_WITH_NOTES: 1-2 High findings OR 3+ Medium findings
• PASS: Only Medium/Low findings

Emit step_end for Step 5:

Tool: Bash

bash scripts/emit-audit-event.sh ".audit-audit-state-${RUN_ID}.json" \
  '{"event_type":"step_end","step":"step_5_synthesis","step_name":"Synthesis","agent_type":"coordinator"}'

Step 6 — Gate

Emit step_start for Step 6:

Tool: Bash

bash scripts/emit-audit-event.sh ".audit-audit-state-${RUN_ID}.json" \
  '{"event_type":"step_start","step":"step_6_gate","step_name":"Gate","agent_type":"coordinator"}'

Read ./plans/audit-[timestamp].summary.md and check verdict.

If BLOCKED: Output: "🚫 Audit BLOCKED — Critical security or performance issues found.

Summary: ./plans/audit-[timestamp].summary.md Action items must be resolved before proceeding.

Critical findings: [count] High findings: [count]"

If PASS_WITH_NOTES: Output: "⚠️ Audit PASS with notes — Review recommended but not blocking.

Summary: ./plans/audit-[timestamp].summary.md Consider addressing high-priority findings.

High findings: [count] Medium findings: [count]"

If PASS: Output: "✅ Audit PASS — No blocking issues found.

Summary: ./plans/audit-[timestamp].summary.md Only minor findings to consider.

Medium findings: [count] Low findings: [count]"

Emit verdict, run_end, and step_end for Step 6:

Tool: Bash

# AUDIT_FINAL_VERDICT: "PASS", "PASS_WITH_NOTES", or "BLOCKED"
bash scripts/emit-audit-event.sh ".audit-audit-state-${RUN_ID}.json" \
  "{\"event_type\":\"verdict\",\"step\":\"step_6_gate\",\"verdict\":\"${AUDIT_FINAL_VERDICT:-PASS}\",\"verdict_source\":\"synthesis\",\"agent_type\":\"coordinator\"}"

bash scripts/emit-audit-event.sh ".audit-audit-state-${RUN_ID}.json" \
  "{\"event_type\":\"run_end\",\"outcome\":\"${AUDIT_FINAL_VERDICT:-PASS}\",\"scope\":\"${AUDIT_SCOPE:-unknown}\"}"

bash scripts/emit-audit-event.sh ".audit-audit-state-${RUN_ID}.json" \
  '{"event_type":"step_end","step":"step_6_gate","step_name":"Gate","agent_type":"coordinator"}'

# Clean up state file
rm -f ".audit-audit-state-${RUN_ID}.json"
echo "Audit skill log complete: ./plans/audit-logs/audit-${RUN_ID}.jsonl"