Skip to content

urmzd/dotfiles / dot_agents/skills/align-readmes

align-readmes

Unverified

Audit and converge README.md across every local urmzd/* checkout so the fleet reads as one product: skip archived repos, flag renamed repos and stale identities, score each README against write-readme, then fix in priority order. Use when the user asks to consolidate, unify, standardize, or audit READMEs across repos, or after a rename wave. Do NOT use for a single repo's README (use write-readme), prose cleanup alone (use clean-docs), or whole-repo convention drift (use sync-ecosystem).

Align READMEs

One fleet, one voice. This skill owns the cross-repo loop. It does not own README rules: those live in write-readme (structure) and clean-docs (prose). Never restate them here.

Usage: /align-readmes [root] (default root: ~/github)

1. Triage before touching anything

Run the bundled audit. It is read-only.

bash "${CLAUDE_SKILL_DIR:-$HOME/.agents/skills/align-readmes}/scripts/audit-readmes.sh" ~/github

Act on the status and identity columns first:

ValueMeaningAction
ARCHIVEDRead-only on GitHubSkip. Never edit. List it in the report so the user can delete the local checkout.
MISSINGRemote repo deleted or inaccessibleSkip. Ask the user.
no-remoteLocal-only directorySkip unless the user names it.
dir-is:<name>Repo was renamed, folder was notUse <name> in every README edit. Do not rename the folder without asking.
stale-remote:<o/r>Remote URL predates a renameReport git remote set-url origin fix. Do not run it unasked.

Also verify against GitHub, not memory: renames happen in waves and recall goes stale.

gh repo list urmzd --limit 300 --json name,isArchived --jq '.[] | select(.isArchived) | .name'

2. Score the active set

Remaining columns map to write-readme rules:

ColumnRule ownerPass
hdrwrite-readme: Centered Header3
badgeswrite-readme: Badges1 to 4
em_dashclean-docs0
treewrite-readme: No Project Structure0
toc_neededwrite-readme: ToC (300+ lines)ok or -
quick_startwrite-readme: Quick Startok
skill_2ndwrite-readme: Agent Skill positionok, or no when the repo has no skills/
license_lastwrite-readme: Section Orderok

The script is a fast filter, not the verdict. Read each failing README before editing.

Exempt: the urmzd profile repo is a GitHub profile page, not a project README. Skip header, Quick Start, and section-order rules for it.

3. Unify, do not merely comply

Compliance per repo is not enough. Check the fleet for shared identity:

  • Names. Every cross-repo link and mention uses the current GitHub name (gh repo view resolves redirects). Grep all READMEs for each old name from step 1.
  • Shared phrasing. Sections that exist in many repos (Agent Skill, License, Installation via install.sh) use the exact template wording from write-readme. Divergent copies are drift.
  • Related section. When repos form a family (agent platform, release tooling), each README links its siblings with the same one-line descriptions. Take the description from gh repo view --json description, so GitHub stays the single source.
  • Descriptions. The README one-liner matches the GitHub repo description. Report mismatches; fix with update-repo-meta only when the user approves.

Do not create a shared README include file or a central docs repo. Each README must stand alone on GitHub.

4. Fix in priority order

Fix one repo per commit. Order:

  1. Stale names and broken cross-links (users hit dead links)
  2. Missing Quick Start or header (first-impression failures)
  3. Directory trees, misplaced Agent Skill, section order
  4. Em dashes and prose (run clean-docs)

For each repo, apply write-readme, then run fsrc if the README has markers. Commit with ship as docs(readme): align with fleet standard. Do not push unless asked.

5. Report

## README Alignment: <date>

Skipped (archived): <repos>
Identity drift: <dir -> github name>, <stale remotes>

| Repo | Failing checks | Fixed |
|------|----------------|-------|

Fleet issues: <cross-repo naming, phrasing, Related-section gaps>

Gotchas

  • gh repo view <old-name> silently returns the new repo. Compare nameWithOwner to detect renames; the script does this.
  • Edit this skill in the chezmoi source (dot_agents/skills/align-readmes), then chezmoi apply. Deployed copies are overwritten.
  • If a rule in the audit table changes, change it in write-readme first, then update the script check. The script follows the skill, never the reverse.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 193kUpdated Claude CodeCodexVerifiedInstall