Plans

Fix auto-version-bump via ruleset bypass

Medium todo
2026-06-07 agentics fix Medium effort
Objective

Restore the direct-push version bump workflow by reverting PR #284's PR-based changes, removing the version guard bot exemption, and documenting the required GitHub ruleset bypass so github-actions[bot] can push directly to main.

Implement Read and implement all steps in the plan at docs/plans/fix-version-bump-ruleset-bypass.md — Fix auto-version-bump via ruleset bypass. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/fix-version-bump-ruleset-bypass.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
More ways to run this plan — goal & workflow prompts, file path
Pursue as goal — optimize for the outcome
Achieve this goal: Fix auto-version-bump via ruleset bypass. The plan at docs/plans/fix-version-bump-ruleset-bypass.md describes one approach — use it as reference, but optimize for the outcome. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/fix-version-bump-ruleset-bypass.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
File fix-version-bump-ruleset-bypass.html
Path docs/plans/fix-version-bump-ruleset-bypass.html
Spec docs/plans/fix-version-bump-ruleset-bypass.md
Definition of done 0 / 4 done

Context

The story behind this plan — what prompted the work and why it matters now.

The auto-version-bump.yml workflow runs after merges to main that touch kit/plugins/** . It computes the correct semver bump and updates marketplace.json , but cannot land the change because the repo's branch ruleset requires all changes go through a pull request. PR #284 changed the workflow to create PRs instead, but github-actions[bot] lacks permission to create PRs. The simplest fix is to add github-actions[bot] as a bypass actor in the branch ruleset and revert to the original direct-push workflow. The [skip ci] commit prefix and ci(versions): guard already prevent infinite loops.

Files that change

Every file this plan touches, and what happens to each one.

agentics/
  • .github/workflows/
    • auto-version-bump.yml modified revert to direct-push approach
    • version-guard.yml modified remove bot exemption condition
  • docs/GITHUB_SETUP.md new document ruleset bypass configuration

Steps

The step-by-step work, in order — each step says what to do, why it matters, and how to check it worked.

1
todo Revert auto-version-bump.yml to direct-push approach
Why
The PR-based approach fails without additional repo/token configuration; direct push with a ruleset bypass is simpler and has fewer moving parts.
Verify
Diff against the pre-PR#284 version; the only differences should be the original "Commit and push" step and contents: write permission (no pull-requests: write ).
2
todo Revert version-guard.yml to remove the bot exemption
Why
With direct push (no bot-authored PRs), the version guard never sees a bot PR, so the exemption is dead code. Removing it keeps the guard unconditional.
Verify
The job block has no if: condition; it runs for every PR that changes the guarded paths.
3
todo Add docs/GITHUB_SETUP.md documenting the required ruleset bypass
Why
This is a manual repo configuration step that can't be automated via code; documenting it prevents the next maintainer from hitting the same wall.
Verify
The file exists at docs/GITHUB_SETUP.md , names the exact Settings path, and references both the workflow file and the loop guards.
4
todo Test the workflow end-to-end after ruleset bypass is configured
Why
The workflow has failed on every run since the branch ruleset was added; this confirms the fix actually works.
Verify
gh run list --workflow auto-version-bump.yml --limit 1 shows conclusion: success ; git log --oneline -1 origin/main shows a ci(versions): commit.

Tests

The tests that prove the change does what it promises.

Tier 2 — Non-code plan
Objective Version bump workflow runs to completion File: N/A (manual verification via CI run) Type: smoke test Asserts: The auto-version-bump workflow runs to completion with conclusion: success after a plugin change is merged to main , and marketplace.json on main reflects the bumped version. Run: Merge a trivial plugin change, then: gh run list --repo shawn-sandy/agentics --workflow auto-version-bump.yml --limit 1 --json conclusion

Definition of done

The plan counts as done when every statement below is true — check each one off as you verify it.

Final check

One last pass to confirm the whole change works end to end.

Read auto-version-bump.yml — confirm it has a "Commit and push" step that runs git push directly, no gh pr create , and permissions list only contents: write .

Read version-guard.yml — confirm the job has no if: condition.

Read docs/GITHUB_SETUP.md — confirm it documents the bypass actor configuration.

After the repo owner adds github-actions[bot] to the ruleset bypass list, merge any feat(kit/plugins/*) or fix(kit/plugins/*) change and confirm the workflow run succeeds.

Wrapping up

Three gates that must all pass before this plan is marked completed.

Required

Completion Report

No items to report — all requirements met.

Next steps

Follow-up ideas that came up along the way — none of them are required to finish this plan.

Backfill pending version bumps

Paste this prompt into Claude to execute this follow-up:

Check the last 5 failed auto-version-bump workflow runs in the agentics repo. For each, identify which plugin(s) were supposed to be bumped and what the target version should have been. Run the bump script locally with --dry-run to verify, then apply the missing bumps manually by running: node scripts/auto-bump-version.mjs. Commit as a single fix(versions) commit and push to main (after confirming the ruleset bypass is configured).