agentfs-readme-audit

AgentFS README Audit

Semantic alignment check for ~/.agents/README.md against the actual state of the AgentFS USER scope. Designed to complement the deterministic README staleness check in pre-push-scan.sh.

Overview

Property	Value
Version	1.1
Trigger	Automatic during Guardrail #10 (Git Push Safety), or explicit
Scope	USER scope ~/.agents/README.md only
Dependencies	ls, grep, wc, cat — data gathering is deterministic
LLM required	Yes — alignment assessment is semantic

When This Runs

This skill activates in two scenarios:

1. During Pre-Push (Guardrail #10)

Run this skill when any agentfs files are staged:

• skills/, knowledge/, or AGENTS.md appear in git diff --cached --name-only
• pre-push-scan.sh emits README_AUDIT_REQUIRED in its output

README.md does not need to be staged — the audit compares the existing README against the staged changes to detect drift. If README.md is also staged, the audit additionally validates whether the in-progress README update is sufficient.

Flow:

git diff --cached --name-only
  └─ skills/ or knowledge/ or AGENTS.md staged?
       └─ YES → pre-push-scan.sh emits README_AUDIT_REQUIRED
                  └─ Agent runs this skill (semantic comparison)
                       └─ If aligned → proceed to push approval
                       └─ If drift detected → report specifics, recommend fixes
                            └─ User decides whether to fix before push
       └─ NO → skip skill entirely

2. Explicit Invocation

The user asks directly:

"audit readme" · "check readme alignment" · "readme drift"

Execution Steps

Step 1: Gather Actual State

Collect ground truth from the filesystem. All commands are deterministic — no LLM involvement yet.

# Skill count and list
ls -d ~/.agents/skills/*/SKILL.md 2>/dev/null | sed 's|.*/skills/||;s|/SKILL.md||' | sort > /tmp/readme-audit-skills.txt
SKILL_COUNT=$(wc -l < /tmp/readme-audit-skills.txt)

# Knowledge bundle count and list
ls -d ~/.agents/knowledge/*/index.md 2>/dev/null | sed 's|.*/knowledge/||;s|/index.md||' | sort > /tmp/readme-audit-knowledge.txt
KNOWLEDGE_COUNT=$(wc -l < /tmp/readme-audit-knowledge.txt)

# Skill categories (extract from skills/index.md)
grep '^|' ~/.agents/skills/index.md | grep -v '^| Name\|^|---' > /tmp/readme-audit-skill-index.txt

# Directory structure (top level)
tree -L 2 --dirsfirst -I '__pycache__|node_modules' ~/.agents/ > /tmp/readme-audit-tree.txt 2>/dev/null

# Guardrail list from seed template
grep -oP '### [0-9]+\. .+' ~/.agents/skills/agentfs-setup/scripts/seed-agents-md.sh > /tmp/readme-audit-guardrails.txt 2>/dev/null

# Template version
grep -oP 'version:\s*"\K[^"]+' ~/.agents/skills/agentfs-setup/SKILL.md > /tmp/readme-audit-template-version.txt 2>/dev/null