Weekly skill refresh

Unattended weekly refresh of one client's two skills against that client's latest stable release. This is a repository maintenance skill, not an installable artifact. It runs in a fresh cloud clone: no local worktrees, no ~/projects paths, no .venv, no GraphQL, and no way to delete remote branches.

Parameter: client, one of claudecode, codex, copilot, opencode. Use the row below for everything client-specific; every other step is identical.

Branch name: refresh/<client>. This run owns that branch and nothing else.

Rules that override this file

Read AGENTS.md first. It governs git, documentation and PR rules. Never commit or push to main or master, never merge a PR, never bypass hooks, never git add -A or git add ., and never edit site/. Put scratch files in .agent-output/. If anything below conflicts with AGENTS.md, AGENTS.md wins, with one standing exception: the maintainer (Micheal) pre-approved, for these scheduled refresh runs, the two outward actions section 3 and 5 call for: posting the one tracking issue per client per run (AGENTS.md "Planned work" asks for a draft and approval; the issue content here is generated from .github/ISSUE_TEMPLATE/weekly_maintenance.md and contains nothing private), and opening one ready-for-review (not draft) PR per client per run. The approval is Micheal's instruction on 2026-11-01 in the project thread that created this procedure, which required the issue-first, PR-every-run flow, and his answer "READY PR's". It covers only that issue and that PR. It does not cover merging, any other issue (including deferrals under section 6, which are reported, not posted), or any other PR.

1. Prepare

1. The clone may be shallow and single-branch, so a plain git fetch origin <branch> can update only FETCH_HEAD. Always fetch into explicit remote-tracking refs: git fetch --unshallow origin 2>/dev/null || true, then git fetch origin +refs/heads/main:refs/remotes/origin/main.

2. Set up tooling from the repo's own instructions (AGENTS.md, "Python environment"):

   uv venv --python 3.14
   source .venv/bin/activate
   uv pip install pyyaml mkdocs mkdocs-material mkdocs-callouts

   markdownlint runs through npx --yes markdownlint-cli2 <changed files> (config in .markdownlint.json). If it cannot be installed, say so in the PR; do not claim it passed.

3. Look for this client's unmerged work with GitHub MCP list_pull_requests (state open, head CowboyLogic:refresh/<client>, no base filter). Reset or force-push only after a successful and complete lookup: the call returned without error, you paged until no further page remained, and it returned zero open PRs for this head. On any error, truncated or ambiguous result, retry once, then stop and report; never treat a failed lookup as "no open PR". If an open PR targets a base other than main, do not continue or reset the branch: stop and report.
   • Open PR exists: continue it. git fetch origin +refs/heads/refresh/<client>:refs/remotes/origin/refresh/<client> and git checkout -B refresh/<client> origin/refresh/<client>. Take the issue number from the Closes #<n> line in the PR body. Open no new issue or PR this run.
   • No open PR: start fresh. Cloud sessions cannot delete remote branches, so reset instead: git checkout -B refresh/<client> origin/main. If refresh/<client> exists on origin (check with git ls-remote --heads origin refresh/<client>; if it does, fetch it with the same explicit refspec as above so origin/refresh/<client> exists), the first push is git push --force-with-lease=refresh/<client>:<sha-you-fetched> -u origin refresh/<client>, where the sha is git rev-parse origin/refresh/<client>. Force only here, only on this branch, only when no open PR exists. If the branch is not on origin, plain git push -u origin refresh/<client>.
4. Before the first edit, confirm git rev-parse --abbrev-ref HEAD is refresh/<client>.

2. Establish the basis

1. Find the latest stable release from the table's source. Skip alpha, beta, rc and other prereleases.
2. Find the basis recorded by the previous refresh in each skill's README.md, SKILL.md and CHANGELOG.md (agent-creator skills may have no CHANGELOG.md).
3. The window is the previous basis through the new version.

3. Open the tracking issue (every run, even if nothing changed)

Skip when step 1.3 found an open PR; use the issue it closes.

1. Read .github/ISSUE_TEMPLATE/weekly_maintenance.md, drop its frontmatter, and fill in every section from what you know now. Tick only what is true. In "Before starting", the worktree line is satisfied by this run's fresh clone; say so.
2. Create it with GitHub MCP issue_write (method create), title [<skill 1>, <skill 2>] Weekly refresh against <Tool> <version>, issue type Maintenance, labels documentation and skill. If the MCP tool cannot set the type, use gh api -X POST repos/CowboyLogic/ai-dev/issues ... -f type=Maintenance.
3. Keep the number. If the issue cannot be created, stop and report why.

4. Refresh the skills

1. Read both skills in full (SKILL.md, everything under references/, README.md, CHANGELOG.md where present) and the sources in the client's sources.json.
2. Check the vendor's release notes for the window and the published documentation for each source. Use authoritative sources only.
3. Make targeted edits. Do not rewrite sections that are still accurate.
4. Keep every change verifiable. If a claim cannot be checked against a source, do not make it. Label a claim that rests on release notes alone. Record conflicts between sources instead of resolving them.
5. Update the version basis and verification date in each skill's README.md and SKILL.md. Add a CHANGELOG.md entry per skill that has one; where a skill has none (the agent-creator skills), do not create one: record the change in the PR and the client-config entry. A refresh with no content change still gets the entry, saying what was verified and that no content changed.
6. Update the matching docs/ pages per AGENTS.md "Artifact and documentation synchronization". Docs link to the skill folder and never copy its content.

7. Run, with the venv active, and fix every failure:

   python scripts/validate_artifact_sync.py
   mkdocs build --clean --strict
   npx --yes markdownlint-cli2 <changed .md files>

8. If npm blocks installing a version this new (release-age guard), do not override it. Verify from the release docs and source, and say in the README and the PR that the binary was not run.

5. Record the outcome

Every run produces a PR, because the verification date and basis change every run.

1. Commit in logical units, conventional style (docs(skills): ...), staging exact paths.
2. Push refresh/<client> per step 1.3. Otherwise never force-push.
3. Continuing an open PR: the push updates it. Comment on the PR with what this run added, then go to section 6. Otherwise open the PR with GitHub MCP create_pull_request (head refresh/<client>, base main), body filled from .github/PULL_REQUEST_TEMPLATE/weekly_maintenance.md, with Closes #<issue>. Title: docs(skills): weekly <Tool> skills refresh against <Tool> <version> (<YYYY-MM-DD>). The body is the maintainer's review surface, since the maintainer reads it before merging. It must summarize, in plain terms: what changed per skill and why (with the source for each claim), what was verified with no change, what was deliberately left out or could not be verified, and which claims rest on release notes alone. A date-only refresh says so under "Changes made" and lists the sources checked. Begin the body with any attribution block the routine or session context requires.
4. Comment on the issue with the PR link. Leave it open; it closes when the PR merges.
5. Only if there is no diff at all (dates already match today), skip the PR: comment on the issue with the basis and sources checked, then close it as completed.

6. Answer the review

Opening the PR starts the review; it is not the end. Copilot reviews once and does not re-review. Codex reviews code and security and re-reviews after each push. Work in rounds and stop after 3 rounds in total. Wait at most 10 minutes in total for any one review; if it has not landed, stop waiting, report the PR link, and say the review is pending. Never call the PR clean in that case.

GraphQL is blocked in cloud. Use GitHub MCP pull_request_read (methods for review comments, reviews and review threads) to read; add_reply_to_pull_request_comment to reply; resolve_review_thread to resolve. REST via gh api repos/CowboyLogic/ai-dev/pulls/<n>/... is the fallback. Page through every result.

Each round is one pass, with one push at the end:

1. Wait 2 to 3 minutes after the PR opens or after a push, then read all reviews: inline threads and findings that appear only in a review summary.
2. Classify every finding before changing anything, checking each against the code:
   • Valid: fix it in its own commit, with the validator or test that covers it. Findings with one cause are one fix and one commit.
   • Invalid or inapplicable: no change; note what you checked.
   • Valid but out of scope: no change; note why. Follow AGENTS.md "Planned work" (draft the issue in .agent-output/, and because no human is present to approve, report it as a deferral in the final report instead of posting it; do not resolve that thread until an issue exists, and say so).
3. Run the applicable validators on the final tree, then push once. Never amend or rebase reviewed commits. Never push while a review is pending or while findings from the same round are unaddressed.
4. Reply on every thread (name the fix commit, or give the reason), then resolve it, except as noted for deferrals. Check resolution state, not comment presence.
5. If Codex reviews the push with new findings, that is the next round, up to 3 total. After the third round's push, check the resulting review but do not respond to a fourth; report its findings or pending status for human direction.

7. Merge-readiness bar

Before reporting, verify on the current PR head (pull_request_read get and status methods; gh api repos/CowboyLogic/ai-dev/pulls/<n> as fallback):

• Not a draft unless the routine said draft; mergeable is true and mergeable_state is clean; required checks pass. Unknown, pending or failing is unverified, not clean.
• Rebaseable onto main with no conflicts. git fetch origin +refs/heads/main:refs/remotes/origin/main and check git merge-tree --write-tree origin/main HEAD exits 0. If main moved and conflicts, merge origin/main into refresh/<client> (never rebase a reviewed branch), resolve, rerun the validators, push, and repeat sections 6 and 7 on the new head. Pushes count toward the 3-round cap.
• No unresolved review threads from any reviewer, outdated ones included, every page.

If a condition cannot be met within this procedure, report the exact blocker and the PR link as unfinished. Never claim mergeable or ready while anything is unresolved or unverified. Never merge.

8. Final report

Also post this as a final comment on the PR (the maintainer reads the PR, not the session), and update the PR body if the review rounds changed its content. State: client and version, issue and PR links, whether the PR is draft or ready, rounds used, fixes (with commits), refutations, deferrals, and the merge-readiness result with anything unverified.