Auditing Readme

Audit README

Scope: $ARGUMENTS

Audit README.md files against scope-specific best practices and report findings.

Phase 1: Detect Scope and Targets

Parse $ARGUMENTS:

• repo — audit README.md in the current directory
• repo <owner/repo> — audit a specific remote repo's README
• repos <owner/pattern> — batch audit multiple repos (e.g., repos qte77/gha-*)
• account <username> — audit a GitHub user profile README
• org <orgname> — audit an organization profile README

Workflow Mode (batch repos scope)

When scope is repos with more than ~3 targets and the Workflow tool is available, fan the audit out in parallel instead of looping turn-by-turn:

1. Resolve the glob to a concrete list: gh repo list <owner> --json nameWithOwner, filtered by pattern.

2. Drive the bundled workflow (its instruction to call Workflow is the opt-in — no ultracode needed):

   Workflow({
     scriptPath: "${CLAUDE_PLUGIN_ROOT}/workflows/audit-repos.js",
     args: { repos: ["owner/a", "owner/b"],
             skillPath: "${CLAUDE_PLUGIN_ROOT}/skills/auditing-readme/SKILL.md" }
   })
   

   args is delivered to the script as a JSON string (the script parses it). Alternatively pass { owner, pattern, skillPath } and let the workflow's Discover phase resolve the list.

3. Render the returned perRepo findings and consistency observations with the Phase 4 format.

Fall back to the inline Phases 2–4 (one repo at a time) when the Workflow tool is unavailable. The workflow's agents are read-only, so the only permission to pre-grant is the Workflow tool.

Phase 2: Fetch READMEs

• Local repos: read README.md directly
• Remote repos: gh api repos/<owner>/<repo>/contents/README.md --jq '.content' | base64 -d
• Account profiles: gh api repos/<user>/<user>/contents/README.md --jq '.content' | base64 -d
• Org profiles: try profile/README.md first, fall back to root README.md in .github repo

Phase 3: Run Checklist

Base Repo Checklist — qte77 doc-structure canon

Derives from the canon contract (SoT) — audit against it, never redefine it.

GHA Extension (if action.yml/action.yaml exists)

Account Profile Checklist

Organization Profile Checklist

Phase 4: Report

Output a findings table per target:

## <repo-name>

| # | Check | Level | Status | Notes |
|---|-------|-------|--------|-------|

Summary: X/Y required pass, Z/W recommended pass.

Batch Summary

| Repo | Required | Recommended | Top Issue |
|------|----------|-------------|-----------|

Consistency Checks (batch only)

• Section order matches the canon (Hero → Badges → What → How → Why → Refs → License → tail)?
• Badge order/colors consistent (License → Version → CI; static blue / native status)?
• Version badge linked to CHANGELOG.md (flag a bare ![Version](…))?
• Canon section names used (## What / ## How / ## Why / ## Refs, not ## Resources)?
• License format consistent (LICENSE not LICENSE.md)?

Rules

• Never modify files during an audit — read-only
• Report facts, not opinions
• Derive from the canon; never invent divergent structure — qte77/qte77 docs/doc-structure.md is authoritative
• License file MUST be LICENSE (not LICENSE.md) — flag as FAIL if .md variant used