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

Output Rules

• Always print full absolute paths for all artifact references (plan files, review files, audit logs). This makes paths clickable in terminals like Warp. Use the resolved $PLANS_DIR value, never relative paths.

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

Resolve devkit paths (MUST be first action in Step 1):

Tool: Bash

# --- Devkit Path Resolution ---
DEVKIT_SCRIPTS="${CLAUDE_DEVKIT:-$HOME/.claude-devkit}/scripts"

# Source path resolution helper
if [ -f "$DEVKIT_SCRIPTS/resolve-project-dir.sh" ]; then
  . "$DEVKIT_SCRIPTS/resolve-project-dir.sh"
  DEVKIT_PROJECT_DIR_RESOLVED=$(resolve_devkit_project_dir) || {
    echo "Failed to resolve project directory" >&2; exit 1
  }
elif [ -n "${DEVKIT_PROJECT_DIR:-}" ]; then
  DEVKIT_PROJECT_DIR_RESOLVED="$DEVKIT_PROJECT_DIR"
else
  echo "WARNING: devkit is not installed. Using deprecated .devkit/ fallback." >&2
  DEVKIT_PROJECT_DIR_RESOLVED=".devkit"
fi

PLANS_DIR="$DEVKIT_PROJECT_DIR_RESOLVED/plans"
mkdir -p "$PLANS_DIR"
echo "Plans directory: $PLANS_DIR"

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_DIR/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.3.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 "$DEVKIT_SCRIPTS/emit-audit-event.sh" "$STATE_FILE" \
  "{\"event_type\":\"run_start\",\"scope\":\"${AUDIT_SCOPE:-unknown}\"}"

bash "$DEVKIT_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"