bestax
CLAUDE.md14 starsChanged 8 days agoMITView on GitHub
React component library for Bulma v1 in TypeScript. pnpm monorepo orchestrated by turbo: - bulma-ui/ — the library, published as @allxsmith/bestax-bulma (has its own CLAUDE.md) - docs/ — Docusaurus site → https://bestax.io (has its own CLAUDE.md) - create-bestax/ — the npm create bestax scaffolder (has its own CLAUDE.md) - bestax-migrate/ — the bestax-migrate codemod CLI, and in codemod/ its Codemod Registry wrapper (has its own CLAUDE.md) - bestax-mcp/ — the bestax-mcp MCP server; its data/ index is generated (has its…
- Reads credentials
- Installs packages
In this repository19 other files it gives its agents.
- AGENTS.mdAGENTS.md
- bulma-ui/AGENTS.mdAGENTS.md
- bestax-mcp/CLAUDE.mdCLAUDE.md
- bestax-migrate/CLAUDE.mdCLAUDE.md
- bulma-ui/CLAUDE.mdCLAUDE.md
- create-bestax/CLAUDE.mdCLAUDE.md
- docs/CLAUDE.mdCLAUDE.md
- eslint-plugin/CLAUDE.mdCLAUDE.md
- .github/CLAUDE.mdCLAUDE.md
- skills/CLAUDE.mdCLAUDE.md
- templates/CLAUDE.mdCLAUDE.md
- bulma-ui/llms.txtllms.txt
- bestax-custom-componentSkill
- bestax-formSkill
- bestax-iconsSkill
- bestax-layout-scaffoldSkill
- bestax-migrateSkill
- bestax-optimizeSkill
- bestax-themingSkill
The file
We split this CLAUDE.md into the rules it gives an agent
7 rules. About 0 are common, 1 is distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 62
Run pnpm format before pnpm lint: lint includes prettier (eslint-plugin-prettier), so an unformatted tree fails lint while typecheck and …
- Very specific: line 109
Run pnpm all locally before opening a PR.
- Very specific: line 122
Read the guide for each directory you change: Every CLAUDE.md on the path to a file you edit applies to it (bulma-ui/CLAUDE.md, …
- Very specific: line 126
Edited a skill, an API docs page or a TSDoc comment: run pnpm format, then pnpm gen, and commit what they rewrite.
- Very specific: line 302
Read its "What goes stale" section before a change that adds, renames or removes a skill, changes what bestax-mcp offers or how it starts, …
- Distinctive: line 306
Update the page in the same PR when a listing is added, accepted or removed, or when how one updates changes.
- Very specific: line 391
Kill switches and variables: Remove ai-loop (per PR) or set repo variable AI_LOOP_ENABLED=false (whole system).
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
bestax
React component library for Bulma v1 in TypeScript. pnpm monorepo orchestrated by turbo:
bulma-ui/— the library, published as@allxsmith/bestax-bulma(has its own CLAUDE.md)docs/— Docusaurus site → https://bestax.io (has its own CLAUDE.md)create-bestax/— thenpm create bestaxscaffolder (has its own CLAUDE.md)bestax-migrate/— thebestax-migratecodemod CLI, and incodemod/its Codemod Registry wrapper (has its own CLAUDE.md)bestax-mcp/— thebestax-mcpMCP server; itsdata/index is generated (has its own CLAUDE.md)eslint-plugin/—@allxsmith/eslint-plugin-bestax, lint rules for the library; itssrc/generated/metadata is generated (has its own CLAUDE.md)skills/— Agent Skills, a shipped product bundled into create-bestax (has its own CLAUDE.md)templates/: Bulma templates rebuilt with bestax, each a create-bestax project the docs Templates page lists, published to a mirror StackBlitz opens; not workspace packages (has its own CLAUDE.md, the porting guide)plugin/: the hand-written inputs of thebestaxcoding-agent plugin, which is generated into allxsmith/bestax-skills (see "The bestax plugin" below)telemetry-worker/— Cloudflare Worker ingesting the CLIs' opt-in telemetry (deployed from CI bydeploy-worker.yml— a merged change under it ships to production immediately)eval/agent-loop/— cold-start eval harness: does an unassisted agent build correctly when given one of our guidance channels (the skills, the MCP server, both)? Frozen rubric, its own README.github/— CI and AI-automation workflows, human-authored only (has its own CLAUDE.md, which is the security contract for anything inworkflows/)scripts/gen-component-catalog.mjs— generates the skill component catalog (pnpm gen:catalog)scripts/gen-mcp-index.mjs— generates the MCP server's data index (pnpm gen:mcp)scripts/gen-skills-rosters.mjs— writes the skill install rosters fromskills/(pnpm gen:skills)scripts/gen-skills-repo.mjs: writes the allxsmith/bestax-skills tree into a directory (node scripts/gen-skills-repo.mjs <dir>, in a checkout with full history)scripts/gen-eslint-meta.mjs— generates the ESLint plugin's component metadata (pnpm gen:eslint-meta)
Toolchain
Node 22 locally (.nvmrc; CI runs Node 24) and pnpm@11.9.0 (pinned via packageManager; run
corepack enable once). Install with pnpm install --frozen-lockfile for CI parity.
Commands
pnpm all # the pre-PR gate: build, typecheck, tests (once, with coverage), bundle:stats, conformance, the three staleness checks, lint, format:check, storybook build
pnpm test # every package's suite (turbo), then test:scripts
pnpm test:scripts # the root scripts/ suite, with coverage held to per-file floors (see below)
pnpm test:coverage # coverage — thresholds live in each package's `vitest.config.ts` (see below); pnpm all and CI run package tests through it, so a package with no coverage tool aliases it to its `test`
pnpm lint # eslint
pnpm typecheck # tsc --noEmit (each package's build program)
pnpm typecheck:tests # tsc over bulma-ui's tests and stories, which `typecheck` excludes
pnpm format # prettier --write (format:check to verify; covers md/mdx too)
pnpm gen:catalog # regenerate the skills component catalog (CI fails if stale)
pnpm gen:mcp # regenerate the MCP server's data index (CI fails if stale)
pnpm gen:skills # regenerate the skill install rosters (conformance fails if stale)
pnpm gen:eslint-meta # regenerate the ESLint plugin's metadata (CI fails if stale)
pnpm gen # every generator (api docs, catalog, MCP index, skill rosters, eslint metadata)
pnpm docs # Docusaurus dev server :3000
pnpm storybook # Storybook dev server :6006
pnpm exec turbo run test --filter=@allxsmith/bestax-bulma # scope any task to one package- Run
pnpm formatbeforepnpm lint: lint includes prettier (eslint-plugin-prettier), so an unformatted tree fails lint while typecheck and tests pass, andpnpm allruns lint beforeformat:checkwithout formatting, so it fails there too. A multi-taskturbo runburies the cause. pnpm allrunsbundle:statsin aturbo runof its own, after the tests. It rebuildsbulma-ui/dist, which other packages' tests typecheck against, and nothing orders the two inside one run, so folding it back in brings back a flaky "is not a module" failure.
Quality gates
Enforced by CI (.github/workflows/ci.yml):
- Coverage thresholds from each package's
vitest.config.ts: bulma-ui 99% (all metrics); every other published package 95% (78% branches).docshas none. - The root
scripts/suite has a coverage floor per file inscripts/coverage-floors.json, checked bypnpm test:scripts(whichpnpm testandpnpm allrun). Per file because a total hides a small script losing most of its coverage. A floor is where the file stood, less a small allowance on branches for run-to-run noise, not a target. A file below its floor fails, as does a loaded file with no row or a row no test loads. Floors are judged only on a green run, so withoutbulma-ui/distthe suites still fail on their own "build first" messages.scripts/coverage-floors.mjshas the rest, including when lowering a floor is the right fix. - A stale generated artefact fails its own step: the skill catalog
(
gen:catalog:check), the MCP index (gen:mcp:check) and the ESLint plugin's metadata (gen:eslint-meta:check). Plus build, typecheck, lint, format, audit. - Tests and stories are type-checked too, by a second project
(
bulma-ui/tsconfig.test.json, scripttypecheck:tests) —tsconfig.jsonexcludes them because it is also the build's program. Vitest strips types rather than checking them, so the test run never stands in for this. Two consequences worth knowing: an@ts-expect-errorin a test or story is live and fails as TS2578 once it stops being needed, and in JSX the directive must sit in its OWN single-line{/* … */}— TypeScript anchors it to the line a comment STARTS on, so a multi-line one suppresses nothing (#663). pnpm buildis not a type gate.@rollup/plugin-typescriptreports semantic errors as warnings, so the build succeeds on source that does not type-check. The twotypecheckscripts are what stands between a type error and a published package, which is why both run in CI even though one reads a subset of the other's files:tsconfig.test.jsonextends the build config and REPLACES its include/exclude rather than merging, so only the narrowertypecheckchecks the shipped program withouttypes/assets.d.ts— and itsdeclare module '*.svg'— in scope.- House conventions fail via
pnpm check:conformance(error messages name the file and fix); a React 18/19 matrix runs bulma-ui's tests on the newest release of both majors.
Enforced in review (a green CI does not check these):
- CI only checks that a story and docs page exist per component — prop-level changes still
need both updated, and skill-affecting changes update
skills/in the same PR. - Run
pnpm alllocally before opening a PR.
Finishing a change
A change is rarely one file. Go through this list before you commit, for a one-line fix as much as for a feature. CI catches some of these and not others, so a green run doesn't mean it's done.
- Read the issue's comments, not only its body. A maintainer's comment can widen the scope or settle a design question the body left open. Do what the latest one asks, or say in the PR body why you didn't.
- Look for the same defect next door: the other variants, sizes and states a selector reaches, the components that share the hook or mixin, a sibling with the same default. Fix what the issue covers and name the rest in the PR body.
- Read the guide for each directory you change. Every
CLAUDE.mdon the path to a file you edit applies to it (bulma-ui/CLAUDE.md,bulma-ui/src/scss/CLAUDE.md,docs/CLAUDE.md,skills/CLAUDE.mdand the rest). Some agent tools load only the ones on the path to the directory they started in, so open them yourself. - Edited a skill, an API docs page or a TSDoc comment: run
pnpm format, thenpnpm gen, and commit what they rewrite.genreads the API pages' examples asformatleaves them, so formatting aftergencan leave what it wrote stale. - Added an SCSS partial: register it in its folder's
_index.scss, then update everything that lists the partials or shows a modular build:skills/bestax-optimize/references/modular-build.md(the inventory, which stock components have a partial, and the starter's worked example), the quick example inskills/bestax-optimize/SKILL.mdand its copy indocs/docs/skills/optimize.mdx, anddocs/docs/guides/getting-started/modular.md(the partials block, and the paragraphs on what each partial adjusts and what it needs). Only the inventory has a test. - Changed what a partial does, for example it now applies outside forced colors: update how those same pages describe it.
- Changed what a component does for accessibility (a focus ring, forced colors, an
aria-*attribute it sets): add or update the bullet in the Accessibility section of its API page. That section is written by hand, and nothing checks it. - Declared a prop on a props interface, even one it already inherits, to give it TSDoc: keep
the inherited type (see TSDoc in
bulma-ui/CLAUDE.md). If the component is a target of bestax-migrate's bulma-classes class map, classify the prop there (ownPropsorpassThrough), since its truth test holds the map to every prop a target declares. - Test the fix, not the code near it. Assert the declaration or behavior that is the fix, revert the fix and watch the test fail, then put it back. For CSS, cover the class-prefixed build too.
- Changed more than one package: one commit per package, each with that package's scope (see "Commits" below).
- Keep the PR body true. Tick only what you did, name follow-up work as an issue or as not done, and leave no placeholders. Change the body in the same step as the push that changes what it describes.
Commits — release-affecting, not cosmetic
Conventional Commits, enforced by commitlint (husky commit-msg hook) and consumed by
semantic-release. Two repo-specific rules:
- Commits of type
feat|fix|perf|refactor|style|revertmust use a scope ofbulma-ui,docs,create-bestax,bestax-migrate,bestax-mcp, oreslint-plugin— an unscoped commit of any of these scope-gated types is rejected (RELEASE_SCOPESincommitlint.config.jsis the source of truth). One exception worth knowing: commitlint's default ignores skip git's ownRevert "…"messages, so the hook cannot reject an unscoped revert in that form — keep reverts conventional and scoped by hand, and know that a scoped revert releases nothing: ship a rollback asfix(<scope>)(see VERSIONING.md for why). - Packages release independently, keyed off the scope:
fix(create-bestax)bumps onlycreate-bestax. The exception is bestax-mcp, which also cuts a patch with every@allxsmith/bestax-bulmarelease because its index documents the library (VERSIONING.md, "bestax-mcp releases with bestax-bulma"). ThereleaseRulesin each package'srelease.config.jsare the source of truth. - A change to two packages needs a commit for each, with that package's scope. A release reads
the scope of each commit, so a bestax-migrate change inside a
fix(bulma-ui)commit releases only the library, and the published codemod never gets it.
feat(bulma-ui): add Collapse component → minor release of bulma-ui, patch of bestax-mcp
fix(create-bestax): handle missing TTY → patch release of create-bestax only
docs: fix typo in contributing guide → no release; scope optionalFull versioning details (breaking-change footers, tag formats): VERSIONING.md.
No breaking changes to @allxsmith/bestax-bulma until its next major. A library change
that would need a BREAKING CHANGE: footer doesn't ship: a removed or renamed export, prop or
type, a narrowed type or peer range, a raised Node floor, or a default or behavior existing code
relies on. That includes what a value a caller passes means. A fix may change what happens by
default where nothing could rely on the old result, but an explicit prop value keeps its meaning
(#1336). Its issue gets the next-major label and waits, so the library's breaking changes land
together in one major release rather than one at a time. Where an issue offers a breaking fix and
a compatible one, ship the compatible one and split the breaking option into its own next-major
issue. The other packages may take a major of their own when a change needs one: put the
BREAKING CHANGE: footer on that package's commit, and say so in the PR body.
Dependencies are a deliberate act
pnpm-workspace.yaml (read its comments before touching deps) enforces supply-chain hardening:
- Install/postinstall scripts are blocked by default — new native deps need an
allowBuildsentry. minimumReleaseAgecooldown: versions younger than 3 days won't install.- Every bypass carries an expiry. Entries in
allowBuilds(grants only — apkg: falsedenial restates the default and is exempt),overrides,minimumReleaseAgeExcludeandauditConfig.ignoreGhsasneed# bestax:review YYYY-MM-DD — why(or# bestax:permanent — whyfor standing policy) in the comment above them.check:conformance --only=bypass-expiryfails on a missing annotation and again once a date arrives, so a temporary bypass can't silently become permanent (#391). A blocking audit gate plus the cooldown means a fresh advisory can red every open PR — CONTRIBUTING.md has the runbook. - Isolated node linker: undeclared (phantom) dependencies fail — declare everything you import.
- How a package publishes decides what its manifest may contain.
npm publishresolves no pack-time protocol at all, so a package published that way must not ship one — the tarball becomes uninstallable (#412). Every package here hands its publish step topnpm publishinstead (#436 for bestax-migrate, #532 for the rest), through the sharedscripts/lib/pnpm-publish.mjs, which buys each a narrow exemption:workspace:/catalog:in devDependencies only.jsr:becomes an aliasednpm:@jsr/…specifier andlink:/portal:/file:are not rewritten at all, so each of those is a violation in any section, exemption or not.workspace:/catalog:are additionally a violation in a section consumers resolve, since pnpm resolving them does not stop every consumer being made to install the dependency. Which packages publish with pnpm is declared incheck:conformancerather than inferred from their release config — inferring it meant parsing semantic-release's config format, which was wrong four times, and every miss granted the exemption. A workspace sibling independenciesoroptionalDependenciesis separately a violation however the specifier is spelled (#537), and the only way through is a line inSIBLING_RUNTIME_DEPS— same declared shape — for a package that depends on a sibling at runtime on purpose (#644: the three CLIs and the ESLint plugin on@allxsmith/bestax-bulma, the way bulma-ui declaresbulma); the test holds that declaration to the real manifests, so a removed dependency cannot leave a standing exemption.
Workflow
PRs target main; direct pushes to main are not allowed — a repository ruleset enforces
this, and its only automation bypass is the GitHub App that pushes semantic-release's
chore(release) commit. Full contributor guide:
CONTRIBUTING.md; for a new component, CONTRIBUTING-COMPONENTS.md is the end-to-end
checklist. New components should stay within the Bulma spec — propose anything beyond it in
an issue first.
AI/LLM surfaces: the docs build publishes an LLM index (see docs/CLAUDE.md); the skills are a
shipped product (see skills/CLAUDE.md); the MCP server serves a generated index of both (see
bestax-mcp/CLAUDE.md). This file is also read by CodeRabbit (PR reviews)
and the @claude GitHub Action (project instructions), so keep it accurate.
The templates mirror. StackBlitz opens the ported templates from allxsmith/bestax-templates,
whose whole tree .github/workflows/templates-publish.yml generates with
scripts/gen-templates-repo.mjs on each change to templates/ on main. Never edit
bestax-templates. CONTRIBUTING.md ("The bestax-templates repository") has the rest.
The bestax plugin. The bestax coding-agent plugin, the skills plus the MCP server, installs
from its own repository, allxsmith/bestax-skills, so an install does not clone this one.
.github/workflows/skills-publish.yml generates that repository's whole tree with
scripts/gen-skills-repo.mjs, from skills/, plugin/ and bestax-mcp's server.json,
package.json and data/skills.json, each time one of them changes on main and after each
bestax-mcp release. Never edit bestax-skills. Change the source here and the workflow carries it
over once merged. The generator reuses the repo's readers rather than its own: the skill vetting
gate in scripts/lib/skills.mjs, the server.json reader in scripts/mcp-registry-publish.mjs,
and the region helpers in scripts/lib/api-page.mjs. Its header lists the rest.
plugin/manifest.jsonholds the manifest fields. Itsplugin.versionis MAJOR.MINOR only. The generator appends a patch, the number of commits onmainthat touched the plugin's content (CONTENT_PATHS) plusOUTPUT_FORMAT, both in the generator, so the version in the Agent Pluginsplugin.json,.claude-plugin/plugin.jsonand.cursor-plugin/plugin.jsonrises with each content commit and nobody bumps it by hand. A generator change that alters the published output raisesOUTPUT_FORMATin the same PR. Its tests pin a hash of the tree built from fixed inputs next toOUTPUT_FORMAT, so a change to the output for those inputs fails until the two are updated together, and a comment-only change passes. They see only the paths those inputs reach, so a new rendering path gets an input of its own. Bump the minor whenever a path leavesCONTENT_PATHS, since the count can then fall. The workflow's paths filter isPUBLISH_PATHS, the content plus the generator's code. Claude Code updates users only when the version changes, so a missedOUTPUT_FORMATbump holds them back. The bestax-mcp pin is read from bestax-mcp'spackage.json, and the publish run refuses one npm does not serve (--require-published).plugin/icon.pngis the plugin's icon, published as.claude-plugin/icon.pngand named byiconin the Claude manifest. The generator refuses one that is not a complete PNG, square, 512 to 2048 px a side and under 2 MB. Its header has the ImageMagick command that renders it fromdocs/static/img/logo.svg. Anthropic's directory takes the icon only the first time the plugin is saved or submitted, so a new one does not reach an existing listing.plugin/logo.pngis the same logo on a white background, published asassets/logo.pngand named bylogoin.cursor-plugin/plugin.json, the manifest the Cursor Marketplace reviews. Cursor asks for a logo with a background plate, so the generator refuses one that is not a complete square PNG or that can hold a transparent pixel. The generator's header has its ImageMagick command too. That manifest takes its display name fromcursor.displayNameinplugin/manifest.json.plugin/SECURITY.mdis copied as written to bestax-skills'SECURITY.md. That repository has its issues turned off, so the file gives the private reporting channels and links the monorepo'sSECURITY.mdfor the rest. A change to how vulnerabilities are reported updates both.gemini-extension.jsonmakes bestax-skills a Gemini CLI extension, with the same server launch as the Claude manifest. Gemini's extension gallery lists a repository that has this file and thegemini-cli-extensiontopic. A tree cannot carry a topic, so it is set by hand on bestax-skills.plugin/README.mdbecomes the repository's README, and it must say everything the plugin runs, sends or fetches. Its skill list and the server's launch command and environment variables are generated into itsbestax:generatedregions, from the skill index andserver.json. The prose around them is hand-written: a change to what bestax-mcp does over the network, to its telemetry or to its dependencies updates it in the same PR.- The generator fails on a tree that breaks a rule of Anthropic's plugin directory, and its tests
run it on the real tree, so
pnpm testcatches a skill change that would.
Distribution and listings
docs/docs/guides/distribution.md lists the registries, plugin marketplaces, directories and
curated lists we know carry Bestax, and marks which ones only change when a maintainer updates
them by hand. Third-party entries copy facts from this repo, and no check here can see them.
- Read its "What goes stale" section before a change that adds, renames or removes a skill,
changes what
bestax-mcpoffers or how it starts, ships a new major, renames or moves a package or a bestax.io page, or changes an install command. Say in the PR which listings that section names need a manual update. - Update the page in the same PR when a listing is added, accepted or removed, or when how one updates changes.
AI development loop
The fix loop. Issues labeled claude-fix (requires triage+ access, verified live) are
implemented autonomously: Claude opens a PR labeled ai-loop, CodeRabbit + a Claude deep
review comment on it, and claude-pr-loop.yml drives fix/verify rounds (cap 4) until CI is
green and every AI review thread is resolved.
- Labels:
ai-loop(in the loop),needs-human-review(converged or contested — owner reviews and squash-merges manually; the loop never merges),ai-loop-paused(cap/guard hit). AI-assisted PRs (bestaxbot author or the Claude Code attribution footer) also get an auto-appliedclaude-assistedprovenance label. Outside the loop,review-convergedmarks adeep-reviewPR based on the default branch whose newest deep-review summary is pinned to the head commit with nothing left open, with every review thread resolved and every check green. Every deep-review finding, advisory included, is a review thread. A verify pass reviews no commits, so the PR also needs a fresh deep review of the head commit with no findings, or a fresh review whose findings later verify passes resolved, as fixed or as a refutation the reviewer accepted, with the pass that resolved the last of them pinned to the head commit. A stacked PR gets no CI run, so it is out of scope.review-converged.ymladds it and removes it while the PR keepsdeep-review, notai-loop, and the default branch as its base.scripts/review-converged.mjsholds the full definition, and anai-loopPR never gets it. - Deep review on demand: a triage+ user can apply the opt-in
deep-reviewlabel to any same-repo PR to run the Claude deep review on it. Never a fork: the job gate requires the head repository to be this one, so labelling a fork PR is a no-op: the job reports skipped and no review appears. That gate also requires the loop switch to be on, so a label does nothing while it is off either — see the kill switches below.claude-review.ymlfires onpull_request: [opened, labeled]— deliberately not onsynchronize, to stop reviewer/fixer ping-pong — so pushing a commit starts no review, and neither does a comment. Re-applying a label that is already present emits nolabeledevent either, so a re-run needs the label removed and added back, not just added. A loop driven by pushes and steer comments alone stalls silently and looks exactly like a review that is merely slow. Re-applying the label settles that review's own open threads and raises nothing new — it does not review the commits pushed since, unless the steer the run reads is a fresh one: a steer comment whose first word afterdeep-review:isfreshas a word of its own (notfresh,) makes the run a full review of the current code instead, and keeps doing so on later toggles while it is the steer the run reads. A steer selects the MODE of a run the label toggle starts and does not start one; which steer a run reads, and how to get a verify pass back, are in the focus step ofclaude-review.yml. Adeep-review:-prefixed PR comment from a triage+ user pre-steers the focus. Its output lands as a PR review fromclaudemarked<!-- claude-deep-review -->; it reviewed the code checked out when its workflow started, which a racing push may have superseded — so look for that review comment (not the current head's checks) and verify its findings against current code. Today a PR whose copy ofclaude-review.ymldiffers from the default branch's is not deep-reviewed: the run logsSkipping action due to workflow validationand posts nothing while the job still goes green — so check for the review comment, never the job's conclusion. Read that condition as written, because the narrower version ("a PR that modifiesclaude-review.yml") is what this line said until it bit. The workflow runs from the PR head's copy, so what matters is only whether that copy still matches the default branch — never the branch's age, and never whether the PR touched the file. An old branch that has since merged or rebased the current version is fine; a branch opened five minutes ago off a stale base is not. #578's flip changed the file, so every PR still carrying the pre-flip copy inherited a skipped review; #605 reproduced it ("egress_policy":"audit"read from the branch's own retained copy, session skipped) and mergingmainin fixed it. Expect this after any edit toclaude-review.yml, and confirm the head's copy matches before trusting a green deep-review job. That is a consequence of configuration rather than a property of the action: the validation lives on the OIDC to app-token exchange, andsetupGitHubToken()returns before reaching it whenever agithub_tokeninput is supplied — the same early returnai-triage.ymlalready documents for #312.claude-review.ymlandclaude.ymlare where this bites in practice, but they are not the only jobs that omit the input:claude-pr-loop.yml'sverifyomits one too. Its usual triggers (workflow_run/workflow_dispatch/schedule) are not PR contexts, so the validation path is not reached on them — but that workflow also fires onpull_request_review, and its gate can selectverifyon that event, so a PR modifyingclaude-pr-loop.ymlcan hit the same silent skip on the review-triggered path. Treat "omitsgithub_tokenand can run in a PR context" as the test, not the workflow name. SupplyingGITHUB_TOKENwould restore the review, at the cost of moving the posting identity away fromclaude, which the loop's gate and the<!-- claude-deep-review -->convention rely on. Weigh that before changing it. - Reviewer mechanics: CodeRabbit reviews incrementally and rate-limits on OSS. After it
posts "review limit reached" it will not retry on its own; once the window resets, push a
commit or comment
@coderabbitai review. Copilot also auto-reviews PRs and re-reviews on push. - State comment: the
<!-- ai-loop-state … -->PR comment is machine-managed — never reformat its first line. - Refusals: the loop refuses PRs that touch
.github/**or the vitest/commitlint/release/pnpm-workspace configs — workflow changes are human-authored, and.github/CLAUDE.mdstates the rules they must hold to (allowlists are a confinement boundary and never widen casually; action SHAs stay on the repo-wide pin; anything that spends model usage gates on== 'on').
Kill switches and variables. Remove ai-loop (per PR) or set repo variable
AI_LOOP_ENABLED=false (whole system). Every repository variable that steers this
automation is tabulated in the ai-development docs guide, including which ones require an
exact value. Everything that spends model usage is explicit opt-in —
AI_LOOP_ENABLED=true, AI_SCAN_MODE=on (or y), AI_LOOP_COPILOT=true — so unset,
empty, off or a typo all mean off, and deleting a variable never enables anything.
AI_TRIAGE_MODE is the exception: its label path is != 'off', so unset still allows
label-triggered triage.
Triage. ai-triage runs a one-shot sonnet triage session that searches for related
issues/duplicates and reports them as a structured payload; the session itself posts nothing
(#457). scripts/render-triage-comment.mjs renders the comment deterministically
from that payload in the session's own job, and a separate job — holding the PAT and
running no model — publishes it as bestaxbot. Triage is
automatic on new issues/PRs when AI_TRIAGE_MODE=auto (outside authors
capped at AI_TRIAGE_DAILY_LIMIT/day via a counter comment on issue #290; items opened by
triage+ collaborators are uncapped), or on demand via the label (triage+ only,
budget-exempt; auto-removed after the run). Fork PRs are never triaged (same-repo
pull_request only — never pull_request_target; see #312). Flagged duplicates may be
auto-closed after 14 days per AI_TRIAGE_AUTOCLOSE (see the ai-development docs guide).
Repro drafts. A triage+ user can apply claude-repro to an issue: Claude drafts a
reproduction test (author-only — never executed by CI) that github-actions[bot] posts for a
human to run; the pipeline holds no PAT and no job co-locates the model token with code
execution.
Security scan. ai-scan.yml read-only-scans new issues/PRs for malicious code, prompt
injection, and social engineering, applying needs-security-review (fail-closed; controls
AI_SCAN_MODE, AI_SCAN_DAILY_LIMIT). A clean verdict is advisory (it only covers the
text as it was at open time), but the flag itself gates every entry point this repo
controls — claude-repro, claude-fix, @claude and @bestaxbot all refuse a flagged
item until a maintainer removes the label. If @claude seems to ignore a mention, check
for that label first.
Stale automation. PRs go stale at 30 days and close 14 days later — except
Claude-assisted PRs (claude-assisted label or bestaxbot author), which skip that sweep
and instead close after 90 days of inactivity; neverstale exempts a PR from both layers.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

