Imported from em-jones/staccato-toolkit (.agents/skills/auditor/SKILL.md). Install upstream with npx skills add em-jones/staccato-toolkit --skill auditor. Copyright stays with the author.

Skill: auditor

Run a continuous background audit loop. The loop has two cadences:

• Incremental (every 10 minutes): detect git changes since the last run; run only the audits that could be affected by those changes.
• Comprehensive (every hour): run the full technology audit regardless of git changes.

Emit a heartbeat on every iteration so the development-orchestrator can detect a dead auditor and restart it.

Heartbeat Protocol

The auditor writes a heartbeat file on every successful iteration. The development-orchestrator reads this file to determine whether the auditor is alive.

Heartbeat file location

.opencode/auditor/heartbeat.json

Heartbeat format

{
  "pid": <process-id>,
  "session": "<session-id>",
  "iteration": <integer>,
  "cadence": "incremental" | "comprehensive",
  "last_run_utc": "<ISO-8601-timestamp>",
  "next_run_utc": "<ISO-8601-timestamp>",
  "status": "alive" | "completing",
  "last_audit_summary": {
    "critical": <n>,
    "warning": <n>,
    "info": <n>,
    "changes_detected": ["<file>", ...]
  }
}

Writing the heartbeat

After every audit iteration (incremental or comprehensive), write the heartbeat:

mkdir -p .opencode/auditor
cat > .opencode/auditor/heartbeat.json <<EOF
{
  "pid": $$,
  "session": "<td-session-id>",
  "iteration": <n>,
  "cadence": "<cadence>",
  "last_run_utc": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "next_run_utc": "<computed>",
  "status": "alive",
  "last_audit_summary": {
    "critical": <n>,
    "warning": <n>,
    "info": <n>,
    "changes_detected": [<list>]
  }
}
EOF

The heartbeat file is gitignored (.opencode/auditor/ is in .gitignore) — do NOT commit it.

Startup

On launch, immediately:

1. Get or create the current td session:

   td usage 2>&1 | head -5

2. Write an initial heartbeat with status: "alive" and iteration: 0.

3. Record the current git commit as the baseline for incremental diffing:

   git rev-parse HEAD > .opencode/auditor/last-seen-commit

4. Announce startup:

   [auditor] started — session <id>, pid <pid>
   [auditor] incremental: every 10 min | comprehensive: every 1 hr
   [auditor] heartbeat: .opencode/auditor/heartbeat.json
   

5. Enter the main loop (see below).

Main Loop

loop forever:
  sleep 10 minutes

  if (elapsed since last comprehensive) >= 60 minutes:
    run comprehensive audit
    reset comprehensive timer
    reset incremental timer
  else:
    detect git changes since last-seen-commit
    if changes detected:
      run incremental audit for affected domains
    else:
      log "no changes detected — skipping incremental"

  write heartbeat
  update last-seen-commit to HEAD

Sleep implementation

Use a 10-minute sleep between iterations. Because agents don't have native sleep, simulate with repeated date comparisons anchored to wall-clock start time:

LOOP_START=$(date -u +%s)
TARGET=$((LOOP_START + 600))   # 600 seconds = 10 minutes
while [ $(date -u +%s) -lt $TARGET ]; do
  sleep 30
done

Use the same pattern scaled to 3600 seconds (1 hour) for the comprehensive cadence timer.

Detecting Git Changes (Incremental)

LAST=$(cat .opencode/auditor/last-seen-commit 2>/dev/null || echo "")
CURRENT=$(git rev-parse HEAD)

if [ "$LAST" = "$CURRENT" ]; then
  echo "no changes"
else
  git diff --name-only "$LAST" "$CURRENT" 2>/dev/null || git diff --name-only HEAD~1 HEAD
fi

Store results in a variable CHANGED_FILES.

Map changed files to affected audit domains

A single changed file may map to multiple domains. Collect the union of all domains from all changed files — that is the incremental audit scope for this iteration.

Incremental Audit

Run only the sub-audits relevant to the affected domains. For each domain in the scope:

go-libraries

Check all direct Go imports in changed .go files against the OpenSpec change registry:

# Extract imports from changed Go files
for f in $CHANGED_GO_FILES; do
  grep -E '"github\.com/[^"]+"' "$f" 2>/dev/null
done | sort -u

For each import, verify it appears in at least one design.md Technology Adoption table or has a usage rule at .opencode/rules/technologies/.

go-patterns

Scan changed Go files for pattern violations:

# Check for patterns that need usage rules
grep -E '(slog\.|log\.With|zap\.|logrus\.)' $CHANGED_GO_FILES 2>/dev/null
grep -E '(otel\.|opentelemetry|tracer\.|meter\.)' $CHANGED_GO_FILES 2>/dev/null

Cross-reference against .opencode/rules/patterns/ to confirm coverage.

observability

Verify any new OTel instrumentation in changed files follows the span-instrumentation and trace-context-propagation rules:

cat .opencode/rules/patterns/observability/span-instrumentation.md 2>/dev/null | head -5

Flag any instrumentation that doesn't match the rule structure.

node-libraries / typescript-patterns

For changed package.json files, extract new direct dependencies and check coverage.

ci-cd / github-actions

For changed workflow files, verify they use only approved actions from the catalog:

cat .opencode/rules/patterns/actions/approved-actions-catalog.md 2>/dev/null
grep -rh "uses:" $CHANGED_WORKFLOW_FILES 2>/dev/null | sed 's/.*uses: //' | sort -u

container-images

For changed Dockerfiles/Containerfiles, verify base images comply with the base-images rule:

cat .opencode/rules/patterns/infrastructure/base-images.md 2>/dev/null | head -20
grep "^FROM" $CHANGED_CONTAINER_FILES 2>/dev/null

catalog

For changed .entities/*.yaml files, verify entity structure is valid (has required fields: apiVersion, kind, metadata.name, spec.type).

usage-rules

For changed .opencode/rules/** files, check they follow the rule template structure:

cat .opencode/rules/TEMPLATE.md 2>/dev/null | head -20

spec-coverage

For changed spec files, verify all requirements have corresponding td tasks:

# Check for requirements without task IDs in the spec
grep -E "^### Requirement:" $CHANGED_SPEC_FILES 2>/dev/null | grep -v "td-"

devbox-tools

For changed devbox.json, extract newly added packages and check catalog and usage rule coverage.

infrastructure

For changed YAML/YML files outside .github/, check for:

• Valid Kubernetes apiVersion patterns
• KubeVela component types against the known list

Comprehensive Audit

Run the full technology-audit skill logic (Steps 2–5 from that skill), but in read-only mode — do NOT create tasks or changes during the audit loop. Instead, write findings to the audit log file and create a summary in the heartbeat.

mkdir -p .opencode/auditor
AUDIT_LOG=".opencode/auditor/audit-$(date -u +%Y%m%dT%H%M%SZ).log"

Comprehensive scope

Run all domains:

• go-libraries, go-patterns, observability
• node-libraries, typescript-patterns
• ci-cd, github-actions
• container-images, base-images
• catalog, usage-rules, spec-coverage
• devbox-tools, infrastructure

Output format

Write to $AUDIT_LOG:

## Comprehensive Audit — <ISO-8601-timestamp>

### Critical Gaps 🔴
<list>

### Warning Gaps 🟡
<list>

### Info Gaps 🟢
<list>

### Fully Documented ✓
<list>

Also write a compact JSON summary to .opencode/auditor/latest-findings.json:

{
  "timestamp": "<ISO-8601>",
  "cadence": "comprehensive",
  "critical": <n>,
  "warning": <n>,
  "info": <n>,
  "gaps": [
    { "severity": "critical", "technology": "<name>", "category": "<cat>", "missing": ["change", "usage-rule"] },
    ...
  ]
}

Keep only the 10 most recent audit log files (prune older ones after writing):

ls -t .opencode/auditor/audit-*.log | tail -n +11 | xargs rm -f 2>/dev/null

Incremental Audit Output

For each affected domain that finds a gap, append to the current incremental log:

INCR_LOG=".opencode/auditor/incremental-$(date -u +%Y%m%dT%H%M%SZ).log"

Write findings in the same format as the comprehensive audit, scoped to the affected domains. Keep only the 20 most recent incremental log files.

Findings That Need Immediate Escalation

These findings are urgent enough that the auditor should create td tasks immediately rather than waiting for a human to review the audit log:

For all other gaps, log them and let humans triage via the audit log.

Graceful Shutdown

If the auditor receives a termination signal or is about to exit:

1. Write a final heartbeat with status: "completing".
2. Flush any open log files.
3. Exit cleanly.

trap 'write_final_heartbeat; exit 0' SIGTERM SIGINT

Guardrails

• Never commit heartbeat or log files — they live under .opencode/auditor/ which is in .gitignore paths
• Read-only by default — comprehensive audits do NOT create changes or tasks unless a finding meets the immediate-escalation criteria
• Incremental audits only look at the diff since the last seen commit — do not re-audit the entire repo on every 10-minute tick
• Heartbeat is mandatory — write it after every iteration, even if no changes were detected and no audit ran
• No duplicate tasks — before creating an escalation task, check for an open task with the same title:

  td ls --status open | grep "<title fragment>"

• Cadence discipline — the 10-minute incremental and 60-minute comprehensive timers are independent; a comprehensive run resets both timers

Base directory for this skill: file:///home/em/repos/oss/openspec-td/.opencode/skills/auditor Relative paths in this skill (e.g., scripts/, reference/) are relative to this base directory.