Add entity-level-git skill for sem, weave, inspect tooling - #87
Draft
alycda wants to merge 5 commits into
Draft
Conversation
sem (as sem-cli, from homebrew core) has been installed since the entity-diff CI action landed (#78); weave and inspect complete the Ataraxy Labs entity-level git stack: - weave: entity-level merge driver — parses files with tree-sitter and merges at function/class granularity, dissolving the false conflicts line-based merge invents when independent agents edit the same file. It also ships first-class jj support (a merge-tools.weave config + `jj resolve --tool weave`), which fits this repo's jj-first workflow. - inspect: entity-level code review — triages diffs/PRs by structural risk via cross-file dependency graphs; LLM review is optional and the triage path needs no API key. Both live only in ataraxy-labs/homebrew-tap (neither is in nixpkgs), so this declares the tap with trusted = true — Homebrew 6.0's HOMEBREW_REQUIRE_TAP_TRUST would otherwise abort activation on an untrusted third-party tap (same reasoning as the existing taps). Agent-facing guidance for all three tools follows in the entity-level-git skill. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01J2Mv7iPiENFihUPt2zNdRe
sem, weave, and inspect needed to reach Claude somehow, and the choice was between an always-loaded hint (preferred-tooling.md / CLAUDE.md) and an on-demand skill. The full usage guidance — three command sets, jj merge-tool config, MCP notes, guardrails — is exactly the "tool-specific behavior that belongs in Claude skills" the agents README lists as a non-goal for the always-loaded layers, and preferred-tooling.md is imported into every Claude session, so bulk there is paid on every prompt. So: a skill carries the depth (progressive disclosure, same pattern as the jujutsu skill), and a compact pointer lands in the hints layer in the next commit. One skill rather than three because the tools share a mental model (tree-sitter entities over lines) and a vendor stack; splitting would triplicate the shared framing while fragmenting triggering. Notable content decisions: - `sem setup` / `weave setup` mutate git config and .gitattributes, so the skill instructs agents to propose them, never run unprompted - weave's jj merge-tool integration is called out — jj is the house VCS, and `jj resolve --tool weave` is documented as the exception to the jujutsu skill's "avoid jj resolve (it's a TUI)" rule - the dotfiles repo already gets sem entity-diff PR comments from CI (#78), so the skill warns against posting duplicates - none of the three are in nixpkgs, so the fallback rule can't summon them via `nix run` — sandboxes fall back to plain git equivalents Wired in agent-skills.nix like the existing local skills, so it deploys from the store (or the live checkout when agentSkills.liveCheckout is set). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01J2Mv7iPiENFihUPt2zNdRe
The companion to the entity-level-git skill: the skill only fires if Claude knows the tools exist, and the always-loaded layers are where that awareness lives. Two small additions, deliberately compact since both files are paid for on every session: - preferred-tooling.md gets a question->tool table (sem diff over git diff for structural questions, sem impact before refactors, weave for false merge conflicts, inspect for review triage) plus the two facts that override its own general rules: the nix-summon trick doesn't apply (none are in nixpkgs), and setup commands are propose-only. Depth is delegated to the skill by name. - CLAUDE.md's entity-diff CI section gets the local-tooling cross-reference and the don't-duplicate-the-CI-comment rule, plus a meta note recording the skill-vs-hints decision. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01J2Mv7iPiENFihUPt2zNdRe
Contributor
⊕ Entity-level changesCLAUDE.md
darwin/modules/homebrew.nix
home-manager/modules/tools/agent-skills.nix
tools/agents/preferred-tooling.md
tools/agents/skills/entity-level-git/SKILL.md
Summary: 8 added, 4 modified across 5 files functions and classes, not lines · sem |
A skill-creator review pass over the new skill caught an overclaim: "~28 languages each" flattened three different coverage numbers (sem ~32, weave ~28, inspect ~19) into one, which matters when deciding whether to lean on a tool for a less-mainstream language. Replaced with per-tool numbers plus the graceful-degradation note (unparseable files fall back to line-level behavior), and fixed an article typo. The audit's other half — a quantitative trigger evaluation of the frontmatter description (20 realistic should/should-not-trigger queries, 3 runs each via claude -p) — is running; any description changes it motivates land separately. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01J2Mv7iPiENFihUPt2zNdRe
The skill-creator trigger evaluation (20 realistic queries x 3 runs via claude -p) showed the original description badly under-triggered: 0/10 should-trigger queries consulted the skill, while all 10 near-miss negatives correctly stayed quiet. The failing clause was the abstract one — "use whenever the question is semantic rather than textual" loses to grep/git-diff muscle memory every time. Part of the zero was harness artifact (the eval runs in an empty directory and only counts the skill if it's the FIRST tool call), so the rewrite was validated manually instead: with this description, queries run inside a real repo consult the skill as their first action and then run the availability check it teaches (4/4 previously failing queries), while the riskiest near-miss — "review PR #85 but just the commit messages" — still routes to commit-craft, not here. What changed: abstract trigger conditions became concrete task shapes ("what breaks if I rename X", "which parts of this 4000-line PR need human review", "blame wrecked by a formatting commit", "false conflicts from parallel agents in one file"), plus an explicit consult-this-FIRST framing — skills under-trigger by default, and a description has to outbid the model's habit of just using plain git. Every clause stays function/code-anchored so semver, lockfile conflicts, and commit-message review keep failing to match. Eval set and results are in the session workspace, not committed — they're a measurement, not content; re-derive with skill-creator's run_eval.py when the description next changes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01J2Mv7iPiENFihUPt2zNdRe
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.
Introduces the Ataraxy Labs entity-level git stack (sem, weave, inspect) as an on-demand agent skill, with supporting infrastructure and documentation.
Summary
Adds comprehensive support for semantic (entity-level) git operations via three complementary tools from Ataraxy Labs:
These tools parse code with tree-sitter into entities (functions, classes, methods) rather than operating on lines, enabling precise analysis without reading entire files.
Changes
New skill documentation (
tools/agents/skills/entity-level-git/SKILL.md):Updated preferred-tooling guidance (
tools/agents/preferred-tooling.md):Updated CLAUDE.md (
CLAUDE.md):Homebrew configuration (
darwin/modules/homebrew.nix):ataraxy-labs/tapas a trusted tapweaveandinspectformulae (sem comes from core assem-cli)Agent skills installation (
home-manager/modules/tools/agent-skills.nix):entity-level-gitskill into the agent's.claude/skills/directoryDesign Notes
Following the repository's principle of keeping tool-specific behavior out of always-loaded instructions: full usage guidance lives in the on-demand skill, with only a compact decision table in
preferred-tooling.mdand a CI cross-reference inCLAUDE.md. This keeps the core agent instructions lean while making detailed guidance discoverable when needed.The guardrails around
sem setupandweave setup(which mutate git config) are explicit: agents should propose these changes and let the user choose, never run them unprompted.https://claude.ai/code/session_01J2Mv7iPiENFihUPt2zNdRe