graphite-skill

What this skill does

# Graphite Skill - Context-Efficient Git/Graphite Workflows

Stop drowning in verbose git/Graphite output. This skill automatically enables context-efficient workflows for all git and Graphite CLI operations in Claude Code through automatic delegation patterns.

## Core Principles

1. **Automatic Delegation**: Verbose git/Graphite operations are automatically delegated to Task subagents
2. **Context Isolation**: Raw CLI output (15KB+) is processed in isolated context, summaries (<50 tokens) returned
3. **Zero Friction**: SessionStart hooks inject patterns automatically - no manual invocation needed
4. **Team-Ready**: Git-trackable configuration for team-wide distribution
5. **225x Efficiency**: Dramatic context window improvements (4,108 tokens → 18 tokens)

## Problem Statement

### Before Graphite Skill (Context Pollution)

```bash
You: "Check my Graphite stack"
Claude: [Returns 15KB of JSON → 4,000+ tokens consumed]
Result: Context polluted, reasoning degraded, 2-3 operations max
```

**Traditional git/Graphite operations flood context:**
- `gt stack` → 15KB JSON (4,108 tokens)
- `git log --graph` → 50KB output (12,000+ tokens)
- `gt pr info` → 20KB JSON (5,000+ tokens)
- Multiple queries → Context window exhaustion

### After Graphite Skill (Context Efficiency)

```bash
You: "Check my Graphite stack"
Claude: [Automatically delegates to Task subagent]
Subagent: [Processes 15KB in isolated context]
Claude: "✓ feature/auth | 3 PRs | Review #456"
Result: Clean context, 18 tokens used, 100+ operations possible
```

## Installation

### Auto-Detection (Recommended)

**The skill automatically detects if setup is needed!**

When you have the carbon-flow plugin installed globally but haven't set up Graphite Skill in your project, the SessionStart hook will automatically prompt you with:

```
⚠️ Graphite Skill Setup Required

Would you like to set up Graphite Skill in this project now?

If yes, run: bash ~/.claude/plugins/mad-skills/graphite-skill/install.sh --project
```

Simply run the provided command and the skill activates immediately. No need to remember or look up installation steps.

### Prerequisites

- Git repository
- Claude Code 2.0+
- (Optional) Graphite CLI for Graphite-specific workflows
- (Optional) jq for JSON processing in hooks

### Manual Installation

```bash
# Navigate to your project
cd /path/to/your/project

# Run the installer
bash ~/.claude/plugins/mad-skills/graphite-skill/install.sh --project

# The installer will:
# - Copy hooks to .claude/plugins/graphite-skill/
# - Configure SessionStart hook
# - Set up agent templates
# - Make scripts executable
```

### Manual Installation

```bash
# In your project
mkdir -p .claude/plugins/graphite-skill/hooks

# Copy files from the carbon skill directory
cp ~/.claude/plugins/mad-skills/graphite-skill/hooks/session-start.sh .claude/plugins/graphite-skill/hooks/
cp ~/.claude/plugins/mad-skills/graphite-skill/settings.json .claude/plugins/graphite-skill/

# Make hook executable
chmod +x .claude/plugins/graphite-skill/hooks/session-start.sh

# Optional: Copy agent template
mkdir -p .claude/agents
cp ~/.claude/plugins/mad-skills/graphite-skill/agents/graphite-ops-template.md .claude/agents/
```

### Verification

```bash
# Test hook execution
bash .claude/plugins/graphite-skill/hooks/session-start.sh

# Should output JSON with hookSpecificOutput

# Test in Claude Code
claude --debug hooks

# Look for:
# [SessionStart] Executing hook: session-start.sh
# [SessionStart] Hook completed successfully
```

## How It Works

### SessionStart Hook Mechanism

The skill uses a SessionStart hook to inject context-optimization patterns automatically:

```
1. Session starts → SessionStart hook fires
2. Hook detects: git repo, project setup status, Graphite CLI, custom agent
3a. If not set up → Prompts user to run install.sh (auto-detection)
3b. If set up → Hook injects ~800 tokens of delegation patterns into context
4. Claude knows: Use Task delegation for verbose operations automatically
5. User benefits: Automatic context efficiency, zero manual effort
```

**Auto-Detection Logic:**

The hook intelligently detects whether per-project setup has been completed by checking for the existence of `.claude/plugins/graphite-skill/hooks/session-start.sh` in your project directory.

- **Not set up**: Hook displays setup prompt with installation instructions
- **Set up**: Hook injects delegation patterns and activates context optimization

This means you never have to remember installation steps - the skill tells you exactly what to do.

### Automatic Delegation Pattern

When you request git/Graphite operations, Claude automatically:

1. **Recognizes** the operation will return verbose output
2. **Delegates** to Task subagent with explicit instructions:
   - Use `--json` flags for structured output
   - Redirect errors with `2>/dev/null`
   - Parse and summarize results
3. **Subagent executes** in isolated context (absorbs verbose output)
4. **Subagent returns** concise summary (<50 tokens)
5. **You receive** actionable summary without context pollution

**No manual invocation needed - patterns apply automatically!**

## Workflows

### Basic Git Operations

**Checking status:**
```bash
You: "Check git status"
Claude: [Delegates automatically]
→ "3 modified, 2 staged, 1 untracked | Ready to commit"
```

**Viewing commit history:**
```bash
You: "Show me recent commits"
Claude: [Delegates automatically]
→ "Last 10: abc123 Feature, def456 Fix, ... | 3 authors, 2 days"
```

**Reviewing changes:**
```bash
You: "Show git diff"
Claude: [Delegates automatically]
→ "+47/-12 across 3 files | auth.ts, api.ts, tests/ | No conflicts"
```

### Graphite Workflows

**Stack status:**
```bash
You: "Check my Graphite stack"
Claude: [Delegates automatically]
→ "✓ feature/auth | 3 PRs | #456 (needs review), #457 (approved), #458 (draft)"
```

**PR management:**
```bash
You: "Show PRs needing review"
Claude: [Delegates automatically]
→ "📋 2 PRs: #456 (Auth - awaiting review), #459 (Docs - changes requested)"
```

**Submitting stack:**
```bash
You: "Submit my stack for review"
Claude: [Delegates automatically]
→ "✓ 3 PRs created | CI running on all | Ready for review"
```

**Stack navigation:**
```bash
You: "Navigate to next branch in stack"
Claude: [Delegates automatically]
→ "Switched to feature/auth-ui (3/5 in stack)"
```

### Supported Operations

**Git Commands (auto-delegated):**
- `git log --graph` - Commit history with summarization
- `git diff` - Changes with statistics
- `git status` - Status with file grouping
- `git branch` - Branch listing with current indicator
- All other verbose git commands

**Graphite CLI Commands (auto-delegated):**
- `gt stack` - Stack status with PR summaries
- `gt pr list` - PR listing with filtering
- `gt pr info` - Detailed PR data with parsing
- `gt submit` - Submission with confirmation
- `gt log` - Stack history with formatting
- All other verbose gt commands

## Two Approaches: Task Tool vs Custom Agent

### Task Tool (Default - Recommended)

Zero setup, works immediately with automatic delegation:

```bash
You: "Check my stack"
Claude: [Uses Task delegation automatically]
→ Concise summary
```

**Characteristics:**
- ⚡ No configuration needed
- 📦 Works universally
- 🎯 Full context isolation
- ⚪ Standard terminal output
- ✅ **Recommended for most users**

### Custom Agent (Optional - Power Users)

Enhanced UX with colored terminal output:

```bash
# One-time setup in Claude Code
/agents create
  Name: graphite-ops
  Color: cyan
  Scope: project
  Prompt: Load from .claude/agents/graphite-ops-template.md

# Use with color
You: "graphite-ops check my stack"
graphite-ops [cyan]: ✓ feature/auth | 3 PRs | Review #456
```

**Characteristics:**
- 🎨 Colored terminal output (cyan)
- 👤 Consistent persona
- 📁 Git-tracked definition
- 🎯 Same context isolation
- 🔧 Requires one-time agent creation

**Agent Template Location:** `graphite-skill/agents/graphite-ops-template.md`

## Team Distribution

G