---
name: git-jj
description: "Used when working with vcs/git/jj/commit task, triggered by phrase like [git], [git commit], [diff], [push], [check git status], [create git branch], [git worktree], [git sqaush], [review with changes], [review with lifeguard], [jj], [jj commit], [jj changes], [commit changes]"
---

# Git/JJ VCS Skill

**Note**: `<skill-base-dir>` refers to the git skill directory (~/.claude/skills/git-jj/) containing this SKILL.md file.

## Purpose
Provide specialized workflows for Git and Jujutsu (jj) version control systems with automatic repository detection, command reference lookup, and safe operation practices.

## Trigger Conditions
Activate this skill for VCS tasks involving Git or Jujutsu (jj), such as:
- Checking status, diffs, logs
- Staging, committing, branching/bookmarks
- Pushing, pulling, fetching
- Managing worktrees/workspaces
- Integrating with lifeguard subagent for code reviews
- Repository initialization and configuration

## Repository Detection & Branching Workflow

### Step 1: Detect Repository Type
Run the repository detection script using the Bash tool:

```bash
bash ~/.claude/skills/git-jj/scripts/repo_check.sh
```

**Important**: Execute this command from the repository root (user's current working directory). The script checks for `.jj` or `.git` folders in the current directory.

The script outputs one of three values to stdout:
- `jj` - Jujutsu repository detected (.jj folder exists)
- `git` - Git repository detected
- `no-repo` - No repository found

**Priority**: If both `.jj` folder and `.git` exist (common when jj operates atop git), the script returns `jj` to respect jj-first preference.

### Step 2: Branch to Appropriate Workflow

| Output | Action |
|--------|--------|
| `jj` | Follow **JJ Branch** workflow. Read `~/.claude/skills/git-jj/references/jj_workflows.md` for core commands and working copy model. |
| `git` | Follow **Git Branch** workflow. Read `~/.claude/skills/git-jj/references/git_workflows.md` for command syntax. |
| `no-repo` | Proceed to **Repository Initialization** workflow below. |

#### JJ Branch: Conditional Reference read

When following the JJ branch, load additional references based on task complexity:

**Always read first:**

- `~/.claude/skills/git-jj/references/jj_workflows.md` - Core commands, working copy model, WIP pattern, filesets

**Read conditionally when needed:**
- **Bookmark operations** (create, track, push, conflicts): Read `~/.claude/skills/git-jj/references/jj_bookmarks.md`
- **Complex history queries** (ranges, filtering, ancestry): Read `~/.claude/skills/git-jj/references/jj_revset.md`
- **Automation/structured output** (CI scripts, release notes): Read `~/.claude/skills/git-jj/references/jj_template.md`

**Reference selection rules:**
- User mentions "bookmark", "track remote", "push bookmark" → Load `jj_bookmarks.md`
- User asks "show commits where...", "filter by author", "range between..." → Load `jj_revset.md`
- User requests "JSON output", "custom format", "parse for script" → Load `jj_template.md`
- Multiple file path filtering (globs, exclude patterns) → Already covered in `jj_workflows.md` (Fileset section)

#### Git Branch: Reference Loading
- Read `<skill-base-dir>/references/git_workflows.md` for all Git operations (covers branches, worktrees, stashing, troubleshooting)

### Step 3: Repository Initialization (if no-repo)
1. Use `AskUserQuestion` tool to ask: "No repository found. Initialize jj or git?"
   - Options: "jj (recommended)", "git"
   - header: "VCS choice"
2. Based on user selection:
   - **jj**: Run `jj init` or `jj git init` (if git backend desired), then load `references/jj_workflows.md`
   - **git**: Run `git init`, then load `references/git_workflows.md`
3. After initialization, proceed with original user intent

## Common Workflows

For command syntax, see reference files. This section covers workflow orchestration.

### 1. Show Status/Diff
- Always gather diff output via `Bash` tool BEFORE invoking other tools
- See `jj_workflows.md` or `git_workflows.md` for commands

### 2. Review Changes with Lifeguard
- Run `scripts/repo_check.sh` first to confirm VCS type.
- Git workflow (small diff <500 lines): you MAY embed the git diff directly. For larger diffs, prefer letting lifeguard fetch them itself.
- JJ workflow (preferred): DO NOT paste full `jj diff` output unless very small (<200 lines). Instead launch the lifeguard subagent with an execution plan listing jj commands it should run to gather its own context.
- Rationale: JJ diffs can be large and lifeguard has Bash(jj:*) capability; letting it execute jj commands avoids prompt bloat and enables multi‑commit exploration.
- Skill loading directive: In every lifeguard prompt include either (a) explicit phrase: `please load git claude skill` (this triggers skill reference loading), OR (b) inline list of reference file paths you want it to consult. Prefer phrase for brevity; attach paths when focusing on specialized areas (revsets, bookmarks, templates).

Reference file path list

- ~/.claude/skills/git-jj/references/git_workflows.md
- Read ~/.claude/skills/git-jj/references/jj_workflows.md (when commit changes, logs, review with jj etc)
- ~/.claude/skills/git-jj/references/jj_bookmarks.md
- ~/.claude/skills/git-jj/references/jj_revset.md
- ~/.claude/skills/git-jj/references/jj_template.md

Use this canonical jj command set in the lifeguard prompt (adjust as needed):

```
# Core context collection
jj --no-pager status
jj --no-pager log -n 20 --no-graph
jj --no-pager diff          # working copy changes

# Targeted commit review (replace <rev>)
jj --no-pager show <rev>

# Compare parent vs current working copy commit
jj --no-pager diff -r @-..@

# Multi-commit / ancestry exploration examples
jj --no-pager log -r "ancestors(@, 10)"
jj --no-pager log -r "descendants(@, 5)"
```
Optional revset queries when user asks for filtering:
```
# Author filter
jj --no-pager log -r "author('name@example.com') & ancestors(@, 20)"
# Files touched
jj --no-pager log -r "file('src/**') & ancestors(@, 30)"
```
Bookmark/WIP context to include in the lifeguard prompt (if applicable):
- Current bookmark name
- Whether parent description starts with "WIP:" and intended final message

Prompt template example (JJ):
```
Please load git claude skill.
Review JJ working copy and recent commits. Run the listed jj commands (modify as needed) to inspect changes; focus on correctness, style, and potential refactors. Repository uses JJ atop git.
Commands to run:
1. jj --no-pager status
2. jj --no-pager diff
3. jj --no-pager log -n 20 --no-graph
4. jj --no-pager diff -r @-..@
If needed: jj --no-pager show <rev>, jj --no-pager log -r "ancestors(@, 10)".
Bookmark: <bookmark-name>
Parent commit description: <parent-desc>
Relevant references (if needed): ~/.claude/skills/git-jj/references/jj_revset.md
```
Git prompt template (large diff scenario):
```
Please load git claude skill.
Review pending changes. Fetch diffs yourself; do NOT rely on inline diff copy. Focus on correctness, style, and commit structuring.
Commands to run:
1. git status
2. git diff
3. git log --oneline -n 20
```
When focusing on a subset of files, pass a short list of paths (not full diff). Lifeguard will retrieve their diffs directly.

Summary:
- Git: small diff inline OK; large diff let lifeguard fetch; always include skill loading phrase.
- JJ: pass command plan + context, not full diff; include skill loading phrase or attach needed reference paths.

### 3. Stage Changes
- **JJ**: Auto-tracks all changes (no staging needed)
- **Git**: Standard `git add` workflow

### 4. Commit Changes
- **CRITICAL**: NEVER commit without explicit user confirmation
- Before committing: Show summary and ask user to confirm
- **JJ**: Always use `-m` flag (bare `jj commit` opens editor, blocks agent). See `~/.claude/skills/git-jj/references/jj_workflows.md` for WIP pattern.
- After JJ commit: verify with `jj --no-pager log -n 4 --no-graph`

### 5. Push to Remote
- **CRITICAL**: NEVER push without explicit user confirmation
- NEVER use `--force` unless explicitly requested

### 6. Other Operations
- History, branches/bookmarks, worktrees: See reference files

## Key JJ vs Git Differences

- **JJ colocated**: When `.jj` + `.git` coexist, prefer jj commands
- **No staging in JJ**: All changes auto-tracked
- **JJ conflicts**: First-class objects (can commit conflicts)
- See `git_workflows.md` for full mapping table

## Example: Commit Workflow

1. Run `scripts/repo_check.sh` → Determine VCS type
2. Show current status/diff
3. **JJ**: Check for WIP commits (see `jj_workflows.md` WIP pattern)
4. **ASK USER** to confirm commit message
5. Execute commit only after confirmation
6. Verify with log output

## Safety Guidelines

1. **NEVER commit or push without explicit user confirmation**
2. **NEVER use force push** unless user explicitly requests it
3. **Verify branch/bookmark** before pushing (avoid main/master/staging)
4. **Pre-commit**: Show summary, suggest message, wait for approval
5. **Pre-push**: Show commits ahead of remote, verify target

## Integration Notes

- Favor `jj` when `.jj` folder exists
- Use `TodoWrite` for multi-step VCS workflows
- Read reference files only when command syntax is uncertain