qte77/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

| # | Check | Level | Pass Condition | |---|-------|-------|----------------| | R1 | Title | required | H1 heading exists, matches repo name | | R2 | Description | required | Non-empty text within 3 lines of H1 | | R3 | Version badge | recommended | ![Version] badge present | | R3b | Standard badge set | recommended | For GHA repos: version, license, CI status, CodeFactor, CodeQL, Dependabot, ruff/pytest or BATS (applicable subset) | | R4 | Install/Usage | required | Section with heading containing "install", "usage", "quick start", or "getting started" | | R5 | License | required | Section containing "license" with link to LICENSE (not LICENSE.md) | | R6 | Internal links valid | required | All [text](relative-path) links resolve to existing files | | R7 | LICENSE file name | required | License file must be named LICENSE (not LICENSE.md) |

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

| # | Check | Level | Pass Condition | |---|-------|-------|----------------| | G1 | Inputs table | required | Markdown table under heading containing "input" | | G2 | Outputs table | required | Markdown table or "no outputs" statement | | G3 | Usage YAML | required | Fenced yaml block with uses: | | G4 | What it does | required | Section with numbered steps | | G5 | Input column order | recommended | Name, Required, Default, Description |

Account Profile Checklist

| # | Check | Level | Pass Condition | |---|-------|-------|----------------| | A1 | Tagline | required | Non-empty text within 5 lines of first heading | | A2 | Current focus | recommended | Section describing current work | | A3 | Featured projects | recommended | 3+ repository links with descriptions | | A4 | Not stale | required | Updated within 6 months | | A5 | Scannability | recommended | Under 500 words |

Organization Profile Checklist

| # | Check | Level | Pass Condition | |---|-------|-------|----------------| | O1 | File location | required | README at .github/profile/README.md | | O2 | Mission | required | Single-sentence purpose within 3 lines of H1 | | O3 | Activities | required | Description of what the org does | | O4 | Projects | recommended | Links to key repos, grouped by domain | | O5 | CTA | required | "Get involved" section with actionable links | | O6 | Length | recommended | 150-400 words |

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)

• Input table column order consistent?
• Badge style/placement consistent?
• Section naming consistent?
• License format consistent (LICENSE not LICENSE.md)?

Rules

• Never modify files during an audit — read-only
• Report facts, not opinions
• License file MUST be LICENSE (not LICENSE.md) — flag as FAIL if .md variant used