Repository navigation
Conversation
Commit messages here come from Claude Code, Crush and Codex, and each harness ships its own default for length and trailers. commit-craft was Chris Beams' seven rules written for a person, with generic examples. It triggered only when someone asked for a message, not when an agent committed on its own, and its last step pushed straight to main. This is the same skill as on develop (c42e3bf on the claude/fervent-feynman-sfduqg branch), at main's path. It defines one format, `<area>(<scope>): <summary>` with a required body in a fixed order (why, what and how, verification, what is left), and a procedure that ends with `jj describe --stdin`. scripts/check-message enforces the mechanical rules: subject shape, case, length and tense, the blank line, a body, and a 72-column wrap. An agent runs it before it sets a message, so a model that knows the rules less well still produces the same shape. The only change from develop is the line that says where the skill sits: here, tools/agents/skills, deployed whole to ~/.agents/skills by agent-skills.nix, whose comment now describes it. Tested in a git-only sandbox (no nix, no jj): develop's bats suite for the checker passes against this copy (10 tests), shellcheck 0.11 passes, and check-skill-frontmatter.sh accepts the skill (492 bytes). main has no bats or shellcheck job, so CI does not run the checker's tests here. Not evaluated with nix; the .nix change is a comment. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Soievfadhy2k17VT4VecnT
Four places described a commit message, and they disagreed. CLAUDE.md had a subject-plus-bulleted-body template. The jujutsu skill asked for sentence case and conventional `feat:` prefixes. ste100 named "the seven rules" and a 50-character subject as commit-craft's. commit-craft itself was the fourth. CLAUDE.md's Commit Message Format now points at commit-craft by path, so an agent that only reads the always-loaded file (Codex reads it through AGENTS.md) still finds the skill. It keeps two things specific to this repository: a body says what was learned when the change came out of a mistake, and because PRs are squash-merged, the PR title is the subject on main and the branch commits make up its body, so both follow the format. The jujutsu skill drops its format and keeps the commands: its `-m` rule gains `jj describe --stdin < file` for messages with a body, and the intent message from "describe first" is a subject line that the full message replaces before a push. version-notes says why agents use `--stdin` now. ste100's handoff names commit-craft's format and checker, and says to run the checker again after a rewording pass. Same change as 6bb1247 on develop's branch, applied to main's copies: the jujutsu skill here is still the 0.44 one, so its edits were made by hand rather than ported. Checked with rumdl, which main's CI does not run: CLAUDE.md and the jujutsu skill gain three warnings that match their existing style (bare code fences, the long Last updated line), and ste100 stays clean. check-skill-frontmatter.sh passes for all skills. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Soievfadhy2k17VT4VecnT
Contributor
⊕ Entity-level changes.github/workflows/commit-messages.yml
CLAUDE.md
home-manager/modules/common.nix
home-manager/modules/git.nix
home-manager/modules/tools/agent-skills.nix
tools/agents/skills/commit-craft/SKILL.md
tools/agents/skills/jujutsu/SKILL.md
tools/agents/skills/jujutsu/references/version-notes.md
tools/agents/skills/ste100/SKILL.md
tools/commit/check-commit-msg
tools/commit/check-commits
tools/git/config
tools/git/dotfiles-repo.gitconfig
tools/git/hooks/commit-msg
tools/jujutsu/config
tools/mise/bootstrap.sh
tools/mise/config.toml
Summary: 32 added, 17 modified, 25 deleted, 1 renamed across 17 files (6 added orphans, 3 modified orphans, 1 deleted orphan) functions and classes, not lines · sem |
alycda
commented
Oct 1, 2026
alycda
commented
Oct 1, 2026
alycda
commented
Oct 1, 2026
| ``` | ||
|
|
||
| Copy: the first paragraph names the change that caused the problem by its | ||
| jj change ID (`vmp`) and gives the exact failure ("7 of its 8 tests |
Owner
Author
There was a problem hiding this comment.
use git... but this can change if rebase so IDK how to handle this...
Owner
Author
There was a problem hiding this comment.
A hash only goes stale while a commit can still be rewritten. That gives a rule per case, which 4f1e34b adds to the skill:
- Default reference: the subject line, in quotes. It survives a rebase, a squash and the move to GitHub, and
git log --grepfinds it. - A git hash: only for a commit already on the default branch, which isn't rewritten.
- Merged work: prefer the PR number (
#N). GitHub links it, and it still resolves after a squash.
On this repo's squash-merge flow, the branch commits are the ones whose hashes change. The subject is the only reference that stays valid for them. My own commit messages on this branch break this rule: they cite c42e3bf/6bb1247 on the develop branch. They'll be squashed, so I've left them.
Generated by Claude Code
Review on #197 found two faults in the first example and in the rules behind it. The example named another commit by its jj change ID, which GitHub cannot resolve, so the reference is lost once the commit is pushed. It also ended with "to squash or rebase as you choose", an instruction to Alyssa inside a commit that she is the author of. The skill told agents to do both. The skill now says to name another commit by its subject line in quotes. A subject survives a rebase, a squash and the move to GitHub, and `git log --grep` finds it. A git hash is allowed only for a commit already on the default branch, and a PR number is preferred for merged work. A new rule says to write as the author and to put notes for the reviewer in the PR body. The "what is left" paragraph no longer offers an instruction for the person who merges. The example is rewritten to follow both rules, with a note that says what was removed and why. Checked: the rewritten example passes check-message, the checker's bats suite passes (10 tests), and check-skill-frontmatter.sh and rumdl pass. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Soievfadhy2k17VT4VecnT
alycda
pushed a commit
that referenced
this pull request
Oct 1, 2026
Review on #197 found two faults in the first example and in the rules behind it. The example named another commit by its jj change ID, which GitHub cannot resolve, so the reference is lost once the commit is pushed. It also ended with "to squash or rebase as you choose", an instruction to Alyssa inside a commit that she is the author of. The skill told agents to do both. The skill now says to name another commit by its subject line in quotes. A subject survives a rebase, a squash and the move to GitHub, and `git log --grep` finds it. A git hash is allowed only for a commit already on the default branch, and a PR number is preferred for merged work. A new rule says to write as the author and to put notes for the reviewer in the PR body. The "what is left" paragraph no longer offers an instruction for the person who merges. The example is rewritten to follow both rules, with a note that says what was removed and why. Same change as on main's copy in #197. Checked: the rewritten example passes check-message, the checker's bats suite passes (10 tests), and check-skill-frontmatter.sh and rumdl pass. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Soievfadhy2k17VT4VecnT
alycda
pushed a commit
that referenced
this pull request
Oct 1, 2026
The skill had copied its language rules and examples from this repo's history. That history has no convention, so the skill made the noise a rule. It also carried a checker that is now in tools/commit, and it told agents to follow a repo's history when the history looked consistent. The skill now follows the ste100 pattern: it adds only what is specific to commits, and it gives the wording to another skill. The body is a ste100 "commit body" surface, in STE-flavored mode. When ste100 is not installed, the agent says so and does not reconstruct its rules. The skill keeps the subject format, the order of the body paragraphs, the trailers, and two rules from the review of #197: write as the author, and name another commit by its subject line, not by a jj change ID. A table says which check runs where. The rule to copy a repo's history is gone. references/examples.md is gone, and so are the language rules. One example and two bad subjects stay in SKILL.md, and the first bats test runs them. The jujutsu skill's push section says to push with `jj push` in a repo that uses this format. CLAUDE.md says where the checks run. Tested: tests/commit.bats passes (14 tests), and rumdl passes on the skill and CLAUDE.md. The jujutsu skill gains two long lines, in its existing style. ste100 is not installed in this sandbox, so this message and the skill's example were not given a ste100 pass. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Soievfadhy2k17VT4VecnT
The commit message format was only in the commit-craft skill. A skill works only when an agent loads it and follows it, and Alyssa writes commits too. Configuration applies to every commit, whoever writes it. This is the same change as "vc: check the commit message format in jj, git and CI" on the develop line, fitted to how main installs config. The checker moves out of the skill to tools/commit/check-commit-msg. A new script, tools/commit/check-commits, runs it on each commit in a jj revset or a git range and skips merges. home-manager installs both as one package (common.nix). The account without Nix gets them on PATH from mise's [env], from the checkout bootstrap.sh makes. The checks run in four places: - jj: tools/jujutsu/config is new on main. A new description opens with the format as `JJ:` lines, and a `jj push` alias runs `check-commits --jj` on the stack that is not on trunk yet before it runs `jj git push`. jj runs no git hooks, so the check happens before the push. home-manager links the file to ~/.config/jj/conf.d/dotfiles.toml; bootstrap.sh links the same path. - git: a `commit-msg` hook in tools/git/hooks, for the dotfiles checkouts only, because `core.hooksPath` replaces .git/hooks for the whole repo. tools/git/config has the `includeIf` for the account without Nix, which includes that file from the checkout. home-manager copies it into the store alone, where the relative include finds nothing, so git.nix adds the same conditional include. - CI: a new commit-messages workflow checks every commit on a pull request. PRs here are squash-merged and the squash body is made of the branch commits' messages, so all of them are checked. Tested in a git-only sandbox, with jj 0.45.1 and nix added. The develop line's tests/commit.bats, pointed at these files, passes (14 tests). alyssa@dev-x86 evaluates, with the GitHub inputs fetched through git+https (the sandbox blocks the GitHub API). Its git config has both `includeIf` blocks, and the commit-checks package builds and passes check-commits on this branch. In a scratch HOME laid out like the account without Nix, a bad `git commit` fails in the checkout. mise 2026.8.6 puts tools/commit on PATH. statix, deadnix, shellcheck, actionlint and taplo pass. The darwin configurations were not evaluated, and main has no CI job for the bats suite. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Soievfadhy2k17VT4VecnT
The skill had copied its language rules and examples from this repo's history. That history has no convention, so the skill made the noise a rule. It also carried the checker that is now in tools/commit, and it told agents to follow a repo's history when the history looked consistent. The skill now follows the ste100 pattern: it adds only what is specific to commits, and it gives the wording to another skill. The body is a ste100 "commit body" surface, in STE-flavored mode. When ste100 is not installed, the agent says so and does not reconstruct its rules. The skill keeps the subject format, the order of the body paragraphs, the trailers, and two rules from the review of #197: write as the author, and name another commit by its subject line, not by a jj change ID. A table says which check runs where. The rule to copy a repo's history is gone. references/examples.md is gone, and so are the language rules. One example and two bad subjects stay in SKILL.md. SKILL.md is the same file as on the develop line. ste100's handoff names `check-commit-msg`. The jujutsu skill's push section says to push with `jj push` in a repo that uses this format. CLAUDE.md says where the checks run, and agent-skills.nix's comment says what the skill now covers. Tested: the develop line's tests/commit.bats passes against these files (14 tests, including the skill's example and bad subjects), and check-skill-frontmatter.sh accepts the skill (508 bytes). ste100 is not installed in this sandbox, so this message and the skill's example were not given a ste100 pass. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Soievfadhy2k17VT4VecnT
alycda
changed the title
commit-craft told agents to read `jj diff --git` and work out what changed. In a large or mixed diff that is where messages go wrong: formatter churn sits next to the real change, and entity names get paraphrased. The entity-level-git skill already has a tool for this. sem now supplies the facts, ste100 the words, and commit-craft the order. A new Facts section says to start with `sem diff --no-cosmetics`, to name each entity as sem names it, to cover the cosmetic edits in one sentence, and to use `sem impact <entity> --tests` to find the tests for the verification paragraph. It points to entity-level-git for sem's language gaps, and says to fall back to `jj diff` without sem and to say so. The split step gains two signs of two commits from sem's output. Tested with sem 0.25.0 (upstream's release binary, sha256 checked against its checksums.txt) in a scratch colocated jj repo: `sem diff` shows `@` against `@-`, `sem diff <commit>^ <commit>` shows one commit, `--no-cosmetics` drops a whitespace-only edit, Nix bindings come out as entities (`home.packages`), and `sem impact --tests` finds a test that names the function. The develop line's tests/commit.bats still passes (14 tests). Same change as on the develop line. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Soievfadhy2k17VT4VecnT
alycda
force-pushed
the
claude/fervent-feynman-sfduqg-main
branch
from
October 1, 2026 22:16
54ff9e3 to
a2b1431
Compare
The compound-engineering plugin is enabled on these machines, and its ce-commit skill also triggers on "commit this". The two skills disagreed. ce-commit adds a body only when the reason is not obvious, and without CLAUDE.md in context it copies the recent log. The hook and `jj push` then refuse its commits. ce-commit also had rules that commit-craft lacked: when to stop, a subject that names the outcome, and paths named on `git commit`. commit-craft gains four of those rules: - Done and stop: done when each change is a commit that passes check-commit-msg and none of the task's changes are left; stop when there is nothing to commit, with no empty commit. - The summary names the outcome, not the files, with a bad and a good example. - With git only, stage files by name and name them again on `git commit -F msg -- <paths>`, because a commit without paths takes everything already staged. Never `git add -A`. - A plan unit ID from compound-engineering can end the subject, as in `(U3)`, when the commit implements one unit. A new section says how the two skills work together. ce-commit's step 3 follows the project convention, which here is commit-craft, so the format, the required body and the ste100 wording apply. The agent runs check-commit-msg on ce-commit's message file, and in a jj repository it uses the jujutsu skill's commands instead of ce-commit's `git checkout -b` and staging. CLAUDE.md says the same in one sentence. The push step said to push with `jj push` every time. That disagreed with the jujutsu skill, which says never to push unless Alyssa asks. It now says to push only when asked. Tested: the develop line's tests/commit.bats passes against these files (15 tests, one new for the plan unit suffix), check-skill-frontmatter.sh accepts the skill, and rumdl passes on it. ce-commit was read at compound-engineering-plugin main; its behavior beside this skill was not run. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Soievfadhy2k17VT4VecnT
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Draft. The commits are a starting point for line review and are not expected to survive as-is.
Why
A skill only works when an agent loads it and follows it. Commit messages here come from Claude Code, Crush, Codex and from Alyssa, so the format has to be enforced by the commit path itself. The old commit-craft was Chris Beams' rules written for a person. Four files described the format, and they disagreed. The first rewrite in this PR then codified the repo's history, which has no convention.
What
Configuration (
e86ed4b) enforces the format:tools/commit/check-commit-msg<area>(<scope>): <summary>, lowercase, at most 72 characters, no period, not past tense; a blank line; a body, wrapped at 72.tools/commit/check-commitscheck-commit-msgon every commit in a jj revset or a git range, merges skipped.tools/jujutsu/config, new on main)JJ:lines. Ajj pushalias checks the stack that is not on trunk yet, then runsjj git push. jj runs no git hooks.tools/git/hooks/commit-msg)includeIf), becausecore.hooksPathreplaces.git/hooksfor the whole repo.commit-messages.yml)check-commitson every commit of a pull request. Squash bodies are made of those messages.Wiring: home-manager installs the scripts as one package, links the jj file to
~/.config/jj/conf.d/dotfiles.toml, and repeats theincludeIfingit.nix, because the store copy oftools/git/configcannot resolve a relative include. The account without Nix gets the scripts through mise's[env]and the jj file throughbootstrap.sh.The skill (
88dda6b) keeps only what no check can judge. It is a layer over ste100, following the ste100-over-asd-ste100 pattern: commit bodies use ste100's STE-flavored mode. The rule "follow the repo's history", the history-derived examples and the skill's own language rules are removed. Kept from review: write as the author, and name commits by their subject, never by a jj change ID. The jujutsu skill pushes withjj push, and ste100, CLAUDE.md andagent-skills.nixare updated.Facts from sem (
a2b1431):sem diff --no-cosmeticssupplies the changed entities andsem impact --teststhe tests to name. Entity names go in verbatim. The entity-level-git skill's language gaps apply, and without sem the agent falls back tojj diff.Beside ce-commit (
a7f3d63): the compound-engineering plugin is enabled, and itsce-commitalso triggers on "commit this". commit-craft is the project convention ce-commit's step 3 defers to: the body stays required, and in jj repos the jujutsu skill's commands replace ce-commit's git steps. Taken from ce-commit:git commit -F msg -- <paths>on the git fallback, nevergit add -A;(U3)plan-unit suffix.The push step now says to push only when asked, which matches the jujutsu skill.
The same change is on develop's line (#196), which also has
tests/commit.batsin its CI.Verification
tests/commit.batspasses against this branch's files (15 tests). It covers each rule, the(U3)suffix,check-commitsover git and jj, the jj template in a real editor run,jj pushstopping beforejj git push, and the hook with git's comment lines.alyssa@dev-x86evaluates, with GitHub inputs throughgit+httpsbecause the sandbox blocks the GitHub API. Its git config has bothincludeIfblocks, and thecommit-checkspackage builds.git commitfails in the checkout, and mise putstools/commiton PATH.check-skill-frontmatter.shpass. Every commit on this branch passescheck-commits.Open
anthropic-skills:commit-craftis still the old version.$HOME.🤖 Generated with Claude Code
https://claude.ai/code/session_01Soievfadhy2k17VT4VecnT