feat: weekly readme-refresh agent for org meta-repo READMEs - #1062
Conversation
Adds a scheduled Claude agent that keeps the four org "meta-repo" READMEs accurate from live org state and opens a human-reviewed PR per repo: - .github/profile/README.md (public org profile) - .github/README.md (repo landing page — was missing) - .github-private/README.md (repo landing page) - .github-private/profile/README.md (member-only org profile — was missing) Modeled on the existing standards-sync.yml + release-notes.sh pattern: - readme-refresh.yml: weekly cron + workflow_dispatch (dry_run input), shared claude-CLI install/cache block, CLAUDE_CODE_OAUTH_TOKEN + DON_PETRY_BOT_GH_PAT, concurrency guard. - aw-readme-refresh.sh: gathers an authoritative facts bundle (live gh repo list, standards docs, agent frontmatter, framework VENDOR.md) so the model never invents names; generates content-only via sentinel markers; enforces markdownlint line length with one corrective regeneration; opens/updates one rolling PR (chore/readme-refresh) per repo. Preserves curated prose — only adds missing repos, fixes stale languages, and corrects agent/framework lists. Flags repos with empty GitHub descriptions in the PR body. DRY_RUN supported. - prompts/aw/readme-refresh.md: per-target prompt with preserve-curated / add-missing / flag-empty rules and marker-delimited output. - AGENTS.md: documents readme-refresh.yml as a repo-specific workflow exception. Verified: shellcheck --severity=warning -x clean; end-to-end dry-run generates all four READMEs; markdownlint passes against both repos' configs. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VAsu1rBxAkMnAqFZaWKV6t
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
Warning Review limit reached
Next review available in: 34 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughAdds a new scheduled GitHub Actions workflow (readme-refresh.yml) that runs a bash script (aw-readme-refresh.sh) using a Claude CLI-driven prompt template (readme-refresh.md) to regenerate org README files and open PRs. Includes an AGENTS.md exception entry, Bats helper tests, and lint workflow updates. ChangesREADME Refresh Automation
Estimated code review effort: 4 (Complex) | ~60 minutes Sequence Diagram(s)sequenceDiagram
participant Scheduler
participant GitHubActions
participant Script as aw-readme-refresh.sh
participant GH as GitHub CLI/API
participant Claude
Scheduler->>GitHubActions: Weekly cron / workflow_dispatch
GitHubActions->>GitHubActions: Checkout, setup Node, cache/install claude-code CLI
GitHubActions->>Script: Run with GH_TOKEN, DRY_RUN
Script->>GH: gather_facts (repos, standards docs)
Script->>Script: render_prompt (facts + current content)
Script->>Claude: generate README body
Claude-->>Script: marker-delimited output
Script->>Script: validate/trim/check overlong lines
Script->>GH: commit, push branch, create/update PR
Possibly related PRs
Suggested labels: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Dev-Lead — review-changes (no-changes)No changes were needed for this PR. |
|
Advisory bots were rate-limited; auto-approval is withheld until they recover. pr-review-sweep will re-review this PR after 2026-07-03T21:33:57Z. |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a weekly automated README Refresh workflow, adding a Bash script (scripts/aw-readme-refresh.sh) and a prompt template (prompts/aw/readme-refresh.md) to regenerate the organization's meta-repo READMEs using Claude based on live state. The review feedback focuses on improving the robustness of the Bash script under set -euo pipefail. Key recommendations include guarding command substitutions to prevent premature exits, validating positional parameters to avoid unbound variable errors, refining the SKIP check to prevent false positives on multi-line outputs, and using safe navigation in jq queries to handle null or missing properties gracefully.
There was a problem hiding this comment.
Pull request overview
Adds a new scheduled automation in .github-private that generates “meta-repo” README updates for both .github and .github-private from live org state, then opens/updates rolling PRs for human review.
Changes:
- Introduces a weekly
readme-refreshGitHub Actions workflow (with manualdry_run) to run the refresh. - Adds
scripts/aw-readme-refresh.shto assemble an authoritative facts bundle, invoke Claude with strict markers/rules, and open/update PRs per target repo. - Adds a dedicated prompt template and documents the workflow as a repo-specific exception in
AGENTS.md.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
.github/workflows/readme-refresh.yml |
New weekly + manual workflow to run the README refresh automation. |
scripts/aw-readme-refresh.sh |
New orchestration script: gathers facts, generates README bodies, and opens/updates rolling PRs. |
prompts/aw/readme-refresh.md |
Prompt template enforcing “facts-injected, curated-prose-preserved” regeneration rules and marker-delimited output. |
AGENTS.md |
Documents readme-refresh.yml as a repo-specific workflow exception (template-drift safe). |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Dev-Lead — fix-reviews (applied)Changes committed and pushed. |
Dev-Lead — waiting on PR blockers (intent: review-changes)PR: #1062 |
|
Note @don-petry I reviewed this PR and no code changes were needed, but it still has blocking checks or reviews (failing or cancelled checks, or changes-requested reviews), so I cannot mark it done yet. I'll re-check automatically. |
There was a problem hiding this comment.
Actionable comments posted: 7
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/workflows/readme-refresh.yml:
- Around line 34-35: The workflow variable fallback for CLAUDE_CODE_VERSION is
not actually pinned, so the cache and behavior remain non-reproducible; update
the readme-refresh workflow to default this value to a known-good fixed version
instead of latest. Make the same change anywhere the same version pattern is
used, and keep the intent aligned with the docs-health-check.yml reference so
the extract_readme step and related CLI behavior stay stable across runs.
- Line 29: The workflow job timeout is too low for the retry behavior in
scripts/aw-readme-refresh.sh, so the readme refresh can be killed before
completing all targets. Update the timeout-minutes setting in the readme refresh
job to match the worst-case runtime, or reduce ACTION_TIMEOUT_SEC and/or retries
in the script so the job budget aligns with generate_content processing across
both repos and files.
- Around line 38-39: Disable credential persistence in the Checkout agent repo
step by setting the checkout action’s persist-credentials behavior to false;
update the existing actions/checkout usage in the readme-refresh workflow so the
default GITHUB_TOKEN is not stored in git config, since later writes already use
DON_PETRY_BOT_GH_PAT through explicit http.extraHeader. Locate this in the
Checkout agent repo step and keep the rest of the workflow unchanged.
In `@scripts/aw-readme-refresh.sh`:
- Around line 226-247: The SKIP handling in the retry loop does not actually
retry for new/empty targets, so a literal SKIP on the first attempt falls
through and is misclassified as invalid. In the while loop in
aw-readme-refresh.sh, update the `attempt == 1` SKIP branch to skip the normal
extraction/validation path and continue the loop after logging the rejection,
using the existing `generate_content`, `extract_readme`, `valid_content`, and
`overlong_lines` flow. Ensure new/empty targets only accept real content and
that the retry path is explicit rather than silently breaking with
`__INVALID__`.
- Around line 340-352: The README refresh flow in aw-readme-refresh.sh has no
isolation between the two process_repo calls, so a failure in the .github run
aborts before .github-private is attempted. Update the top-level invocation
around process_repo so each repo target is wrapped with explicit error handling
(for example via if/|| guards) and the script logs the failure while continuing
to the next target. Keep the behavior localized to the process_repo calls and
preserve the existing set -euo pipefail safety elsewhere.
- Around line 61-63: The repo facts collection in gh repo list is capped at 100,
which can silently omit repositories from larger orgs. Update the repo_json
gathering logic in the aw-readme-refresh.sh script to fetch all repositories for
the org instead of relying on the fixed limit, and keep the existing
sort_by(.name) jq handling and fallback behavior intact so the facts bundle
remains complete.
- Around line 133-139: The generate_content() helper currently suppresses all
Claude stderr, which hides auth/API/model failures and makes empty output
indistinguishable from a real no-op. Update the claude --print invocation in
generate_content() to preserve or capture stderr and surface it through the
script’s logging path, while keeping the timeout and prompt_file stdin behavior
intact. Use generate_content and the claude call site as the main anchors when
adjusting the error handling so unattended cron failures are diagnosable.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: abcc0057-947d-46c6-a66e-46e5fda2bca0
📒 Files selected for processing (6)
.github/workflows/lint.yml.github/workflows/readme-refresh.ymlAGENTS.mdprompts/aw/readme-refresh.mdscripts/aw-readme-refresh.shtests/test_readme_refresh_helpers.bats
Dev-Lead — fix-reviews (applied)Changes committed and pushed. |
Dev-Lead — waiting on PR blockers (intent: review-changes)PR: #1062 |
|
Note @don-petry I reviewed this PR and no code changes were needed, but it still has blocking checks or reviews (failing or cancelled checks, or changes-requested reviews), so I cannot mark it done yet. I'll re-check automatically. |
Dev-Lead — review-changes (no-changes)No changes were needed for this PR. |
|
donpetry-bot
left a comment
donpetry-bot
left a comment
There was a problem hiding this comment.
Automated review — APPROVED ✓
Risk: MEDIUM
Reviewed commit: fce70c92e6eafb58183c2ccd66fd3d2f96242819
Review mode: triage-approved (single reviewer)
Summary
Adds a weekly scheduled README-refresh agent (workflow + orchestration script + prompt + 20 bats tests) that regenerates four org meta-repo READMEs from live org state and opens one rolling, human-reviewed PR per repo. Triage cleared this as low-risk; confirmation review concurs with approval, classifying it MEDIUM (new non-trivial automation consuming a write-scoped bot PAT) — with a security posture that is solid throughout.
Linked issue analysis
No linked issues. The PR body substantively documents motivation (README drift: nonexistent frameworks listed, missing repos/agents) and design rationale (facts injected, prose curated), so no gap against a tracked issue.
Findings
Blocking: none.
- Workflow security (verified):
permissions: contents: read; actions SHA-pinned to the same pins used across 31 existing workflows in this repo;persist-credentials: false; triggers areschedule+workflow_dispatchonly (no untrusted-input triggers);CLAUDE_CODE_VERSIONpinned (2.1.138 default). - Model containment (verified):
claude --printwith all tools disallowed; output extracted between sentinel markers, validated (valid_content, MD013 length checks with one retry), and routed to a rolling PR — the script never direct-pushes to a default branch. - Prior bot findings resolved: all 19 review threads resolved; CodeRabbit's changes-requested review was superseded by its own approval after fixes (SKIP-retry loop, per-repo error isolation, 60-min timeout, version pin, persist-credentials).
- Non-blocking — token persistence:
git clone -c http.extraHeader=...writes the PAT into the temp clone's.git/config(this is what authenticates the later push). Acceptable on an ephemeral runner withtrap-based cleanup of$WORK_DIR. - Non-blocking —
[skip ci]: generated commits carry[skip ci], so markdownlint will not run on the rolling PRs; the PR body's "trim before merge" warnings are the only guard for residual MD013 violations. Consider dropping[skip ci]in a follow-up so target-repo lint validates generated output. - Secret scan:
run_secret_scanningMCP tool unavailable in this run (noted, non-fatal); gitleaks CI check is green and the diff introduces no secret-like literals. - AGENTS.md compliance: repo-specific workflow exception documented in AGENTS.md, and the new bats file added to the lint.yml test list per the documented convention.
CI status
All 33 checks green at fce70c9: Lint, ShellCheck, bats (unit-tests), CodeQL (actions + python), gitleaks secret scan, SonarCloud quality gate, agent-shield, Agent Security Scan, template-drift, holdout-guard, gh-aw-compile, CodeRabbit. SKIPPED entries are inapplicable ecosystem audits (npm/pnpm/cargo/pip/go).
Reviewed automatically by the PR-review agent (single-reviewer mode: fable 5). Reply if you need a human review.
Dev-Lead — review-changes (no-changes)No changes were needed for this PR. |
Summary
Adds a weekly scheduled Claude agent that keeps the org's four "meta-repo" READMEs accurate from live org state, opening a human-reviewed PR per repo. Built on the org's own proven automation pattern (
standards-sync.yml+release-notes.sh) — no generic OSS README generator, which would produce weak output for these curated meta-repos and blank good prose.Why
The meta-repo READMEs had drifted from reality:
.github-private/README.mdlisted frameworksspec-kit/gsdthat don't exist (actual:bmad-method,bmad-test-architecture) and omitted theagentic-workflowsagent.repo-templateandbroodminder-export..github/README.mdand the member-only.github-private/profile/README.mddidn't exist at all.What it does
Targets four READMEs across two repos:
.githubprofile/README.md.githubREADME.md.github-privateREADME.md.github-privateprofile/README.mdDesign principle — facts injected, prose curated. A shell step assembles an authoritative facts bundle (live
gh repo list,standards/*.md, agent frontmatter, frameworkVENDOR.md) so the model never invents names. The model may only add missing repos, fix stale languages, and correct agent/framework lists — existing curated descriptions are preserved. Repos with empty GitHub descriptions (TalkTerm,markets) are flagged in the PR body, never auto-blanked.Files
.github/workflows/readme-refresh.yml— weekly cron (Mon 09:00 UTC) +workflow_dispatch(dry_runinput); shared claude-CLI install/cache block;CLAUDE_CODE_OAUTH_TOKEN+DON_PETRY_BOT_GH_PAT; concurrency guard.scripts/aw-readme-refresh.sh— facts bundle, marker-delimited content-only generation, markdownlint line-length guard with one corrective regeneration, rollingchore/readme-refreshPR per repo,DRY_RUNsupport.prompts/aw/readme-refresh.md— per-target prompt with preserve/add/flag rules.AGENTS.md— documents the workflow as a repo-specific exception.Verification
shellcheck --severity=warning -x— clean..github-privateREADME: framework/agent corrections).markdownlint-cli2against both repos' configs — 0 errors.Rollout
Merge, then verify with a manual dry run before the first scheduled run:
Then a live run opens the four-README PRs (two PRs, one per repo) for review.
🤖 Generated with Claude Code
https://claude.ai/code/session_01VAsu1rBxAkMnAqFZaWKV6t
Summary by CodeRabbit