steward
Skill13 starsChanged 3 months agoApache-2.0View on GitHub
Kraft's own rules for driving a pull request on itsOmidKarami/kraft to green - which checks to run before a push, how to regenerate generated files and lockfiles, how to answer each CI job, and what the description and labels must carry. Read by Claude Code sessions that drive or babysit a Kraft pull request, or a Kraft worker; not for writing the change itself.
19 other projects use a version of this.
Adopted by
Most recently taken up by
- btraceio/btracetheir own version, first seen Nov 16, 2026
- fworks-tech/agenthoodtheir own version, first seen Nov 16, 2026
- ForeactLabs/OpenExecutivetheir own version, first seen Nov 15, 2026
- 5thlayer/skillworkstheir own version, first seen Nov 8, 2026
- ElcanoTek/fleettheir own version, first seen Nov 8, 2026
- jmagly/kintsugi-usbtheir own version, first seen Nov 8, 2026
Other versions19 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 19
- btraceio/btrace★ 6ksame name
- ForeactLabs/OpenExecutive★ 5.8ksame name
- SenteLabsAI/OpenExecutive★ 5.8ksame name
- richlander/dotnet-inspect★ 166same name
- mendixlabs/mxcli★ 139same name
- yschimke/compose-ai-tools★ 127same name
- antiv/mate★ 111same name
- michelbr84/GarraRUST★ 19same name
- jmagly/kintsugi-usb★ 18same name
- jmagly/carbonyl-agent★ 16same name
9 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
The file
We split this skill into the rules it gives an agent
4 rules. 0 are common, 0 are distinctive, and 4 are very specific to this project.
0
Common
Most of the 18 edited versions we read keep these.
0
Distinctive
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 25
Done: when test, both kraft-lite legs, removals declared, release impact declared and, when it ran, docs are green.
- Very specific: line 31
Run what the change touches, from the repo root.
- Very specific: line 62
Never touched by a pull request, because the release writes them: CHANGELOG.md, vscode/CHANGELOG.md, _Added in X.Y_ notes, and the version …
- Very specific: line 116
Keep the template's sections.
“Common” is measured: kept by at least 6 in 10 of the 18 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Steward a Kraft pull request
These are this repository's conventions for getting a pull request mergeable.
CONTRIBUTING.md and the docs pages it links are the source of truth: where
they disagree with this file, they win. Read docs/ci.md, "What CI checks",
before working a red check.
In a Kraft worker ($KRAFT_WORK_ITEM_ID set) there's no gh and no user
to ask. Set a label with kraft item mr-label; where it isn't available (a
sandboxed worker's kraft has no mr-label), name the label you need in your
summary. Read a job's log with kraft view jobs --pipeline P and
kraft view job-log --pipeline P --job J. Re-run a job with
kraft item rerun-ci --reason "..." only for CI that failed outside the code
(a download or runner failure before any check ran), once per attempt and only
when your task prompt allows it. Leave a conflict with main to Kraft: report
it, never merge in the worktree. What this file says to ask the user about,
leave undone and say so in your summary.
Done when test, both kraft-lite legs, removals declared,
release impact declared and, when it ran, docs are green. docs nudge,
tests nudge and test report never count.
Before every push
Run what the change touches, from the repo root. Run just setup first in a
fresh checkout.
| The diff touches | Run |
| anything | just ci-checks (CI's whole lint job, plus the intent check) |
src/, tests/, config/, skills, fixtures | just test-targeted (testmon can't see config/, packaged skills or fixtures, so it adds the tests that read them, or runs the full suite); just test tests/<pkg> -n auto is the quick loop |
frontend/ | just test-ui |
vscode/ or a config model | just test-vscode |
plugins/kraft-lite/ | CI's own command: uv run --python 3.10 --no-project --with pytest pytest plugins/kraft-lite/tests -q |
docsite/ or frontend/src/ (the docs job) | dev/build_docs_site.sh docsite/dist-site && python3 dev/check_llm_docs.py docsite/dist-site; just docs-site ends in a server that never exits |
Never run pytest directly. A hook blocks it; just test is the door.
The kraft-lite row is the one exception: CI runs it on Python 3.10 with
nothing installed, which just test cannot reproduce. just ci-test
reproduces CI's lint and unit jobs on the full suite (about 14 minutes);
keep it for when a targeted run cannot reproduce a failure. A unit shard red
on one Python version only: just test-py 3.12 (or 3.13, 3.14, 3.15).
Regenerate, never hand-edit
- Lockfiles:
uv lockforuv.lock;npm installinsidefrontend/,vscode/,vscode/dev/screenshots/ordocsite/for that folder'spackage-lock.json. In a conflict, takemain's lockfile, then rerun the command. vscode/schemas/:just schemas.frontend/src/types/vocab.generated.ts:just vocab.tests/api/api_shapes.json:just shapes.src/kraft/templates/lucide_icons.txt:just icons.frontend/src/ng/theme/theme.cssandsrc/kraft/console/theme.py:uv run python dev/gen_theme.py.- Never touched by a pull request, because the release writes them:
CHANGELOG.md,vscode/CHANGELOG.md,_Added in X.Y_notes, and theversionin the filesdev/stamp_plugin_versions.pylists (the plugin manifests underplugins/,vscode/package.json,vscode/package-lock.json). - The opposite rule for add-ons: a change to
addons/<name>/raises that add-on'sversioninaddons/<name>/.kraft/addon.json, in the same pull request (docs/maintainers.md, "Kraft's own collection", says by how much).kraft-default(config/) ships with Kraft and takes Kraft's version, so aconfig/change needs no raise.
Merge conflicts
The repo merges by squash, so a merge commit on the branch costs nothing:
merge origin/main into the branch, never rebase or force-push a branch you
did not create. After a merge, rerun the regenerate steps for any generated
file either side changed. Never push to a branch whose pull request already
merged: cut a fresh one from origin/main (CONTRIBUTING.md, "Branch hygiene").
Answering each check
release impact declared: the pull request needs exactly onerelease::*label. Set it on a pull request you opened (CONTRIBUTING.md, "Pull requests and release labels" says which). On anyone else's, say which label you would pick and let the maintainer apply it. Never addnotes::highlight; that is the maintainer's call.removals declared: the description is missing a## Removed testsor## Removed requirementsline for something the diff deletes or renames. Fix the description, not the code, and declare only removals the change means to make: a red test is fixed, not deleted. Check it locally withuv run python dev/check_removals.py origin/main BODY.md. Editing the body starts no run: re-run the failedremovals declaredjob afterwards.lint:just fixcovers ruff. Adev/check_docs_*.pyfailure names the page and the rule; docs/writing-docs.md's "Which page a change updates" explains each. Acheck_addon_versions.pyfailure means an add-on changed without itsversionraised (above).- An intent pin (
python -m kraft.intentin the first test shard): repoint it withjust intent-repoint OLD NEW. e2e (real CLIs),playwright,ui contract: real failures as often as not. Reproduce with the command in docs/ci.md's table before calling one a flake.e2e (macOS sandbox, …)is in thetestgate too and cannot be reproduced on Linux: read its log and fix from that.docs tests: a docs-only pull request's stand-in for the unit tier. It runs the unit test files that name a docs path; docs/ci.md's table says how to find them.docs nudge,tests nudge: comments, never failures. A docs nudge saying source moved without its docs page is usually right: update the page in this pull request (docs/writing-docs.md, "Page rules"). A tests nudge is information; act on it only if it names a test you deleted without declaring.test report,codeql:test reportonly reports. Treat acodeqlalert like a security review finding.
The description
Keep the template's sections. A pull request that ships something has one
user-facing line under ## Changelog; a release::none one leaves it empty.
A new docs page, section or CLI verb carries _Added in next_ under its
heading, never a version number.
Ask the user first
- Pushing a
kraft/<branch>-screenshotsbranch for a pull request that changes a screen. docs/maintainers.md, "A pull request that changes a screen", says what it holds. - Any change to
.github/workflows/,RELEASING.mdor.claude/skills/release/, unless the pull request is about them. - Changing a label on a pull request you did not open.
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.

