Skip to content

Commit b2b6933

Browse files
edmundmillerclaude
andcommitted
feat(claude): Add Agent Skills to JJ workflow plugin
Refactor JJ plugin to use hybrid Skills + slash commands architecture for better autonomous behavior: **New Skills (model-invoked):** 1. Working with Jujutsu Version Control - Core jj concepts (change-based, automatic snapshotting, stack-based) - Working copy state management (@, @-, ancestors) - Plan-driven workflow guidance - When to suggest jj commands vs slash commands 2. Curating Jujutsu Commits - Pattern recognition for splits (test/docs/config mixed with code) - WIP and fixup commit detection - When to suggest /jj:split vs /jj:squash - File type pattern matching 3. Generating JJ Commit Messages - Conventional commit format (type, scope, description) - Project-specific style matching - Plan-to-reality conversion - Auto-generation from file patterns **Plugin Updates:** - Created skills/ directory with 3 SKILL.md files - Updated plugin.json: added "skills": "./skills/", bumped to v0.2.0 - Updated README.md: documented Skills feature and Skills vs Slash Commands **Architecture:** - Skills: Claude autonomously activates based on context - Slash commands: User explicitly invokes (/jj:commit, /jj:split, etc.) - Hooks: Unchanged, continue providing automatic behaviors **Benefits:** - Proactive commit curation suggestions - Better commit message generation - Autonomous jj workflow understanding - Maintained explicit user control via slash commands 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 8a6c225 commit b2b6933

5 files changed

Lines changed: 946 additions & 3 deletions

File tree

config/claude/plugins/jj-workflow-plugin/.claude-plugin/plugin.json

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,14 @@
11
{
22
"name": "jj",
3-
"version": "0.1.0",
3+
"version": "0.2.0",
44
"description": "Autonomous commit stacking and curation workflow for Jujutsu (jj) version control",
55
"author": {
66
"name": "emiller"
77
},
88
"keywords": ["jujutsu", "jj", "version-control", "workflow", "commit-stacking"],
99
"license": "MIT",
1010
"commands": "./commands/",
11+
"skills": "./skills/",
1112
"hooks": {
1213
"UserPromptSubmit": [
1314
{

config/claude/plugins/jj-workflow-plugin/README.md

Lines changed: 71 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
# Jujutsu Workflow Plugin
22

3-
Autonomous commit stacking and curation workflow for Jujutsu (jj) version control. This plugin provides Claude Code with specialized commands for managing commits in a jj repository using a stack-based workflow.
3+
Autonomous commit stacking and curation workflow for Jujutsu (jj) version control. This plugin provides Claude Code with specialized commands, Skills, and hooks for managing commits in a jj repository using a stack-based workflow.
44

55
**Features:**
66

7-
- **Commit stacking** - `/jj:commit`, `/jj:split`, `/jj:squash`, `/jj:cleanup`
7+
- **Slash Commands** - `/jj:commit`, `/jj:split`, `/jj:squash`, `/jj:cleanup` for explicit user actions
8+
- **Agent Skills** - Autonomous JJ workflow understanding, commit curation, and message generation
89
- **Git translation** - Automatic hook to suggest jj equivalents and block git commands
910
- **Plan-driven workflow** - Automatic commit planning and validation hooks
1011
- **Auto-formatting** - Runs `jj fix` after edits to format code automatically
@@ -150,6 +151,74 @@ The plugin supports a plan-driven workflow where Claude commits intent BEFORE wo
150151
- **Everything undoable** - Operation log makes everything reversible
151152
- **Clean history** - Curate before pushing, work however you want locally
152153

154+
## Agent Skills
155+
156+
This plugin includes three Agent Skills that Claude autonomously uses to understand and work with jj workflows. Skills are **model-invoked** - Claude automatically activates them based on context, unlike slash commands which require explicit user invocation.
157+
158+
### Working with Jujutsu Version Control
159+
160+
**When activated:** When user mentions commits, changes, version control, or working with jj repositories.
161+
162+
**What it provides:**
163+
- Core jj concepts and mental model (change-based, automatic snapshotting, stack-based workflow)
164+
- Working copy state management (`@`, `@-`, ancestors)
165+
- Plan-driven workflow guidance
166+
- When to suggest jj commands vs slash commands
167+
- Git-to-JJ translation knowledge
168+
- Best practices for jj workflows
169+
170+
**Example:** User says "I need to commit these changes" → Claude understands jj workflow, suggests `/jj:commit`, explains plan-driven approach if applicable.
171+
172+
### Curating Jujutsu Commits
173+
174+
**When activated:** When working with multiple commits, WIP changes, or preparing work for sharing.
175+
176+
**What it provides:**
177+
- Pattern recognition for split opportunities (tests+code, docs+code, config+code)
178+
- WIP and fixup commit detection
179+
- When to suggest `/jj:split` vs `/jj:squash`
180+
- File type pattern matching (test, docs, config)
181+
- Curation workflow guidance
182+
- Avoiding over-curation
183+
184+
**Example:** User makes changes mixing test files and implementation → Claude suggests: "Your changes mix tests and implementation. Consider: `/jj:split test`"
185+
186+
### Generating JJ Commit Messages
187+
188+
**When activated:** When creating commits, describing changes, or when user asks for commit message help.
189+
190+
**What it provides:**
191+
- Conventional commit format (type, scope, description)
192+
- Project-specific commit style matching
193+
- Plan-to-reality pattern for plan-driven workflow
194+
- Message writing guidelines (imperative mood, specificity, what/why)
195+
- Auto-generation from file patterns
196+
- Length and formatting best practices
197+
198+
**Example:** User runs `/jj:commit` without message → Claude analyzes changes, generates: "feat(auth): implement JWT-based authentication"
199+
200+
### Skills vs Slash Commands
201+
202+
**Skills (model-invoked):**
203+
- Claude automatically uses when relevant
204+
- Provide knowledge and understanding
205+
- Guide workflow decisions
206+
- Suggest appropriate commands
207+
208+
**Slash Commands (user-invoked):**
209+
- User explicitly types `/jj:commit`, `/jj:split`, etc.
210+
- Execute specific actions
211+
- Provide consistent interface
212+
- Work whether Skills active or not
213+
214+
**Example workflow:**
215+
1. User: "I added login and some tests"
216+
2. **Skill activates:** Claude understands mixed changes
217+
3. **Skill suggests:** `/jj:split test` to separate concerns
218+
4. User: `/jj:split test`
219+
5. **Command executes:** Splits tests into separate commit
220+
6. **Skill activates:** Claude generates commit messages for both commits
221+
153222
## Integration
154223

155224
### Automatic Snapshotting
Lines changed: 291 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,291 @@
1+
---
2+
name: Curating Jujutsu Commits
3+
description: Help curate and organize commits in jujutsu repositories. Use when working with multiple commits, WIP changes, or preparing work for sharing. Suggests when to split, squash, or reorganize commits based on change patterns.
4+
---
5+
6+
# Curating Jujutsu Commits
7+
8+
## Purpose
9+
10+
Help organize commits into clean, reviewable, atomic units before sharing. This Skill provides guidance on when and how to curate commits in a jujutsu repository.
11+
12+
## When to Curate
13+
14+
**Good times to suggest curation:**
15+
- Before sharing work (PR, pushing to remote)
16+
- After completing a feature with multiple incremental commits
17+
- When commits mix unrelated concerns
18+
- When you notice WIP, fixup, or temporary commits
19+
20+
**Don't suggest curation when:**
21+
- Changes are simple and focused
22+
- Single commit addresses one concern
23+
- Work is still in early exploration
24+
- User explicitly wants incremental history
25+
26+
## Split Pattern Recognition
27+
28+
Suggest `/jj:split <pattern>` when commits mix concerns:
29+
30+
### Test Files Mixed with Implementation
31+
32+
**Pattern:** Changes include both source code and test files
33+
34+
**Indicators:**
35+
- Files matching: `*test*.{py,js,ts}`, `*spec*.{py,js,ts}`, `test_*.py`, `*Test.java`
36+
- Mixed with implementation in same commit
37+
38+
**Suggestion:**
39+
```
40+
Your changes include both implementation and tests. Consider splitting:
41+
/jj:split test
42+
```
43+
44+
**Why:** Tests and implementation are easier to review separately
45+
46+
### Documentation Mixed with Code
47+
48+
**Pattern:** Changes include both code and documentation
49+
50+
**Indicators:**
51+
- Files matching: `*.md`, `README*`, `CHANGELOG*`, `docs/**/*`
52+
- Mixed with code changes
53+
54+
**Suggestion:**
55+
```
56+
Your changes mix code and documentation. Consider splitting:
57+
/jj:split docs
58+
```
59+
60+
**Why:** Documentation and code changes reviewed by different people/processes
61+
62+
### Configuration Mixed with Features
63+
64+
**Pattern:** Changes include both config and feature code
65+
66+
**Indicators:**
67+
- Files matching: `*.json`, `*.yaml`, `*.toml`, `*.ini`, `.env*`, `*config*`
68+
- Mixed with feature implementation
69+
70+
**Suggestion:**
71+
```
72+
Your changes include configuration updates. Consider splitting:
73+
/jj:split config
74+
```
75+
76+
**Why:** Config changes often need separate security/ops review
77+
78+
### File Type Patterns
79+
80+
**Common split patterns:**
81+
- `test` → Test and spec files
82+
- `docs` → Documentation (*.md, README, CHANGELOG)
83+
- `config` → Config files (*.json, *.yaml, *.toml)
84+
- `*.{ext}` → Specific file types
85+
- Custom glob patterns
86+
87+
## Squash Pattern Recognition
88+
89+
Suggest `/jj:squash` when commits should be combined:
90+
91+
### Multiple WIP Commits
92+
93+
**Pattern:** Sequential commits with WIP, fixup, or similar messages
94+
95+
**Indicators:**
96+
- Messages like "WIP", "wip", "fixup", "temp", "checkpoint"
97+
- Multiple commits for same logical change
98+
- Sequential commits touching same files
99+
100+
**Suggestion:**
101+
```
102+
You have multiple WIP commits for the same feature. Consider squashing:
103+
/jj:squash
104+
```
105+
106+
**Why:** Clean up incremental work into cohesive commits
107+
108+
### Fixup Commits
109+
110+
**Pattern:** Later commits fix earlier commits
111+
112+
**Indicators:**
113+
- Messages like "fix typo", "fix tests", "fix formatting"
114+
- Touching same files as recent commit
115+
- Small changes that belong with earlier work
116+
117+
**Suggestion:**
118+
```
119+
This looks like a fixup for your previous commit. Consider squashing:
120+
/jj:squash
121+
```
122+
123+
**Why:** Fixes should be part of original commit in shared history
124+
125+
### Related Small Changes
126+
127+
**Pattern:** Multiple small commits that logically belong together
128+
129+
**Indicators:**
130+
- Same feature/scope in multiple commits
131+
- Commits from same work session
132+
- Would be clearer as single commit
133+
134+
**Suggestion:**
135+
```
136+
These commits are closely related. Consider combining:
137+
/jj:squash
138+
```
139+
140+
**Why:** Atomic commits easier to review and understand
141+
142+
## Curation Workflow
143+
144+
**Typical curation sequence:**
145+
146+
1. **Review current stack:**
147+
```bash
148+
jj log
149+
```
150+
151+
2. **Identify mixed concerns** → Use `/jj:split <pattern>`
152+
153+
3. **Identify WIP commits** → Use `/jj:squash`
154+
155+
4. **Verify result:**
156+
```bash
157+
jj log
158+
jj diff -r <commit>
159+
```
160+
161+
5. **Update descriptions if needed** → Use `/jj:commit` or `jj describe`
162+
163+
## Examples
164+
165+
### Example 1: Mixed Test and Implementation
166+
167+
**Before:**
168+
```
169+
@ abc123: Add login feature and tests
170+
- src/auth/login.py (new)
171+
- src/auth/test_login.py (new)
172+
- src/auth/config.yaml (new)
173+
```
174+
175+
**Suggest:**
176+
```
177+
Your commit mixes implementation, tests, and config. Consider:
178+
179+
1. /jj:split test # Separate tests
180+
2. /jj:split config # Separate config
181+
182+
Result: Three focused commits
183+
```
184+
185+
### Example 2: WIP Commits
186+
187+
**Before:**
188+
```
189+
@ abc123: WIP: fix validation
190+
@ def456: WIP: add validation
191+
@ ghi789: Add user form
192+
```
193+
194+
**Suggest:**
195+
```
196+
You have two WIP commits for validation. Consider:
197+
198+
jj edit def456 # Edit the first validation commit
199+
/jj:squash # Squash abc123 into def456
200+
201+
Result: Clean commit history
202+
```
203+
204+
### Example 3: Documentation Update
205+
206+
**Before:**
207+
```
208+
@ abc123: Implement OAuth and update README
209+
- src/oauth.py (new)
210+
- README.md (modified)
211+
- docs/oauth.md (new)
212+
```
213+
214+
**Suggest:**
215+
```
216+
Your commit mixes OAuth implementation and documentation. Consider:
217+
218+
/jj:split docs
219+
220+
Result:
221+
- Commit 1: Implement OAuth (code only)
222+
- Commit 2: Document OAuth (docs only)
223+
```
224+
225+
## Change Pattern Analysis
226+
227+
**Analyzing current changes:**
228+
```bash
229+
jj status # See what's changed
230+
jj diff # Review changes
231+
jj log -r 'ancestors(@, 5)' # View recent stack
232+
```
233+
234+
**Questions to ask:**
235+
1. Do changes serve multiple purposes?
236+
2. Could parts be reviewed separately?
237+
3. Do file types suggest natural splits?
238+
4. Are there WIP or fixup commits?
239+
5. Would this be easier to understand as multiple commits?
240+
241+
## Avoiding Over-Curation
242+
243+
**Don't suggest curation when:**
244+
245+
- **Single purpose changes**: All files work toward one goal
246+
- **Tightly coupled changes**: Splitting would break logical cohesion
247+
- **Already atomic**: Commit is focused and clear
248+
- **Early exploration**: User is still figuring things out
249+
250+
**Examples of good single commits:**
251+
- "Refactor authentication module" (all auth files together)
252+
- "Add user profile page" (template + route + tests together)
253+
- "Fix memory leak in data processor" (investigation + fix together)
254+
255+
## Integration with TodoWrite
256+
257+
When user has TodoWrite todos:
258+
259+
**Pattern:** One commit per major todo completion
260+
261+
**Workflow:**
262+
1. Complete todo
263+
2. Use `/jj:commit` to describe work
264+
3. `jj new` for next todo
265+
4. Repeat
266+
267+
**Don't suggest splitting** if commits align with todo structure (already organized)
268+
269+
## Best Practices
270+
271+
**Do:**
272+
- Suggest curation before sharing work
273+
- Recognize common file patterns (test, docs, config)
274+
- Explain why splitting helps review
275+
- Provide specific `/jj:split` or `/jj:squash` commands
276+
277+
**Don't:**
278+
- Over-curate working commits
279+
- Split tightly coupled changes
280+
- Suggest curation during active development
281+
- Make curation feel mandatory
282+
283+
## When This Skill Activates
284+
285+
Use this Skill when:
286+
- User has multiple commits to organize
287+
- Changes mix different file types or concerns
288+
- User mentions preparing work for PR/sharing
289+
- WIP or fixup commits are present
290+
- User asks about organizing commits
291+
- Before suggesting pushing or creating PRs

0 commit comments

Comments
 (0)