Coordinate an estate-wide change across repositories, verified by the lucos_repos dry-run diff
Follow this process to roll out an estate-wide change across lucos repositories, using the lucos_repos dry-run diff to verify the migration at each stage. The user will describe the change to be made.
Send a message to lucos-developer:
"Implement the following change in lucos_repos: {description of the convention change — either editing an existing convention or creating a new one, based on what the user described}. Create a DRAFT pull request with the change. Do not mark it ready for review yet — we need to verify the dry-run diff first. After creating the draft PR, report back with the PR URL."
Wait for the developer to respond with the draft PR URL.
Once the developer reports back with the draft PR URL, wait for the audit dry-run diff to be posted as a comment on the PR. This happens automatically via GitHub Actions.
Check the diff comment on the PR. It should show additional failures — these are the repos that don't yet comply with the new or updated convention. Report the number of affected repos to the user and ask them to confirm the diff matches expectations before proceeding.
If the dry-run has not posted yet, wait and re-check periodically. If the workflow is not present (e.g. the dry-run CI hasn't been set up yet), tell the user and stop.
This step is mandatory when the convention change involves a reusable workflow or workflows that call a reusable workflow (e.g. changes to code-reviewer-auto-merge.yml, codeql-analysis.yml, or any caller template that references a workflow in lucas42/.github). Skip this step only if the change has no relationship to reusable workflows.
Before migrating any other repositories, the change must be applied to lucas42/.github-test first and validated against the smoke tests in lucas42/.github.
Send a message to lucos-system-administrator:
"Apply the following per-repo change to
lucas42/.github-testonly: {description of the per-repo change}. After pushing, check whether the smoke tests inlucas42/.githubpass. Report back with the result — do not proceed to other repos."
Wait for the system administrator to report back.
Self-referential changes: Pay particular attention when the change touches the merge workflow itself (e.g. code-reviewer-auto-merge.yml). A broken caller template will prevent auto-merge from triggering on the very PR that introduced the change — a self-locking situation that cannot be detected by code review alone. The .github-test smoke test is the only way to catch this before the PR merges and the breakage propagates estate-wide.
Once the user confirms the diff looks correct (and the smoke test has passed, if applicable), send a message to lucos-system-administrator:
"Apply the following change across all affected repositories: {description of the per-repo change the user described}. The dry-run diff on {PR URL} shows which repos need updating. {If Step 3 was performed: 'Note: lucas42/.github-test has already been migrated during the smoke test step — skip it in this batch.'}"
Migration means deployed, not just PR-opened. The migration is not complete until the changes have been merged and deployed. Opening pull requests is the first step — the system administrator must also ensure the PRs are reviewed, approved, and merged. On unsupervised repos, approved PRs auto-merge.
Estate rollout merge exception: For estate rollouts of templated changes (the same change applied across all repos), the system administrator may merge PRs directly on supervised repos — this is an explicit exception to the normal unsupervisedAgentCode policy. This is permitted because estate rollouts have already passed multiple verification gates that exceed normal PR review:
.github-testThe system administrator must verify that CI checks (tests, builds, and other required workflows) are passing before merging each PR. If CI is still running, enable auto-merge on the PR rather than waiting — but check back to confirm it actually merged before declaring the migration complete.
The system administrator should merge in staggered batches where deploys are triggered (see staggering guidance below).
Staggering applies to merges, not PR creation. PRs can be created in any order at any speed — creating a PR does not trigger CI. The staggering concern is about concurrent CI pipeline execution triggered when PRs are merged:
dependabot.yml, or any other file that causes CircleCI or GitHub Actions to run): "Merge one PR at a time with a 60-second interval between merges. PRs can be created all at once." This prevents CI pipelines from running concurrently, which has caused GitHub GraphQL rate limit exhaustion, Docker Hub throttling, and CircleCI concurrency failures during past estate-wide rollouts (see 2026-04-16 incident — dependabot.yml changes were incorrectly treated as deploy-free and merged in bulk, triggering concurrent CI across 57 repos). A 60-second gap is enough for each pipeline to start and stagger its API calls before the next begins..md changes, comment-only changes): "No staggering needed." When in doubt, assume staggering is needed — the cost of over-staggering is time; the cost of under-staggering is a CI incident.Also ask the system administrator to post a comment on the draft PR summarising what was done once the migration is complete — e.g. how many repos were migrated, any failures or repos that needed special handling. This gives the code reviewer context when they review the PR later.
Wait for the system administrator to report back that the migration is complete (PRs merged and deployed, not just opened).
After the migration is complete, the dry-run needs to be re-run on the same draft PR. Send a message to lucos-system-administrator asking them to trigger the audit dry-run workflow via workflow_dispatch:
~/sandboxes/lucos_agent/gh-as-agent --app lucos-system-administrator \
repos/lucas42/lucos_repos/actions/workflows/audit-dry-run.yml/dispatches \
--method POST \
-f ref="{pr_branch_name}" \
-f inputs[pr_number]="{pr_number}"
Only lucos-system-administrator has actions:write permission for this. Do not push empty commits to re-trigger — use workflow_dispatch instead to keep commit history clean.
Check the updated diff comment. The "new failures" count must be zero. An open PR on a repo does not count as resolving a violation — the PR must be merged and the repo's default branch must pass the convention.
Do not move the PR out of draft status until the dry-run shows zero new failures. If failures remain:
Only then proceed to Step 6.
Once the dry-run confirms zero new failures, send a message to lucos-developer:
"The dry-run on {PR URL} confirms all repos have been migrated (zero new failures). Please mark the PR as ready for review and drive the PR review loop (see
~/.claude/pr-review-loop.md)."
Wait for the developer to complete the review loop and report back.
If this estate rollout was triggered by a specific GitHub issue (passed in as context at Step 1), check whether the convention PR merging completes the issue's requirements. If so, post a closing comment summarising what was done (convention added, N repos migrated, PR merged) and close the issue. If the issue has remaining work beyond the convention + migration, leave it open and note what's left.
Summarise the outcome: how many repos were migrated, the PR URL, whether the review loop completed successfully, and whether the originating issue was closed.