Initial commit
This commit is contained in:
Zhongwei Li
200
skills/graphite-skill/references/quickstart.md
Normal file
200
skills/graphite-skill/references/quickstart.md
Normal file
@@ -0,0 +1,200 @@
|
||||
# Quick Start Guide
|
||||
|
||||
Get context-efficient git/Graphite workflows running in 5 minutes.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Git repository
|
||||
- Claude Code 2.0+
|
||||
- (Optional) Graphite CLI
|
||||
- (Optional) jq for JSON processing
|
||||
|
||||
## Installation
|
||||
|
||||
### Option 1: Automated Installation (Recommended)
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/your-username/carbon.git
|
||||
cd carbon
|
||||
|
||||
# Run installer
|
||||
./install.sh --project
|
||||
|
||||
# The installer will:
|
||||
# - Copy files to .claude/plugins/
|
||||
# - Configure SessionStart hook
|
||||
# - Set up agent template
|
||||
```
|
||||
|
||||
### Option 2: Manual Installation
|
||||
|
||||
```bash
|
||||
# In your project
|
||||
mkdir -p .claude/plugins/carbon/hooks
|
||||
cd .claude/plugins/carbon
|
||||
|
||||
# Copy files
|
||||
cp /path/to/plugin/hooks/session-start.sh hooks/
|
||||
cp /path/to/plugin/settings.json .
|
||||
cp /path/to/plugin/plugin.json .
|
||||
|
||||
# Make hook executable
|
||||
chmod +x hooks/session-start.sh
|
||||
|
||||
# Copy agent template (optional)
|
||||
mkdir -p .claude/agents
|
||||
cp /path/to/plugin/./agents/graphite-ops-template.md .claude/agents/
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
# Test hook execution
|
||||
bash .claude/plugins/carbon/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
|
||||
```
|
||||
|
||||
## First Use
|
||||
|
||||
```bash
|
||||
# Start Claude Code
|
||||
claude
|
||||
|
||||
# Try it out (hook automatically active)
|
||||
> "Check my Graphite stack"
|
||||
|
||||
# Claude should automatically:
|
||||
# 1. Recognize verbose operation
|
||||
# 2. Delegate to Task subagent
|
||||
# 3. Return concise summary
|
||||
|
||||
# Expected response:
|
||||
# "✓ feature/auth | 3 PRs | Review #456"
|
||||
# NOT: [15KB of JSON]
|
||||
```
|
||||
|
||||
## Team Distribution
|
||||
|
||||
```bash
|
||||
# Commit the configuration
|
||||
git add .claude/
|
||||
git commit -m "Add Graphite context-optimization plugin"
|
||||
git push
|
||||
|
||||
# Team members pull and get automatic optimization
|
||||
git pull
|
||||
# Plugin activates automatically ✓
|
||||
```
|
||||
|
||||
## Optional: Custom Agent Setup
|
||||
|
||||
For enhanced UX with colored terminal output:
|
||||
|
||||
```bash
|
||||
# In Claude Code
|
||||
claude
|
||||
|
||||
# Create agent
|
||||
/agents create
|
||||
Name: graphite-ops
|
||||
Color: cyan
|
||||
Scope: project
|
||||
Prompt: Load from ./agents/graphite-ops-template.md
|
||||
|
||||
# Use it
|
||||
> "graphite-ops check my stack"
|
||||
|
||||
# Output appears with cyan color:
|
||||
graphite-ops [cyan]: ✓ feature/auth | 3 PRs | Review #456
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Hook not firing
|
||||
|
||||
```bash
|
||||
# Check permissions
|
||||
chmod +x .claude/plugins/carbon/hooks/session-start.sh
|
||||
|
||||
# Check settings.json exists
|
||||
ls -la .claude/settings.json
|
||||
|
||||
# Test manually
|
||||
bash .claude/plugins/carbon/hooks/session-start.sh | jq .
|
||||
```
|
||||
|
||||
### Context not appearing
|
||||
|
||||
```bash
|
||||
# Verify hook returns correct JSON
|
||||
bash .claude/plugins/carbon/hooks/session-start.sh | \
|
||||
jq '.hookSpecificOutput.hookEventName'
|
||||
|
||||
# Should output: "SessionStart"
|
||||
```
|
||||
|
||||
### Patterns not applied
|
||||
|
||||
Start Claude with debug mode:
|
||||
|
||||
```bash
|
||||
claude --debug hooks
|
||||
|
||||
# Check for:
|
||||
# - Hook execution
|
||||
# - Context injection
|
||||
# - Any error messages
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Read [User Guide](USER-GUIDE.md) for comprehensive usage
|
||||
- Read [Custom Agents](CUSTOM-AGENTS.md) for agent setup
|
||||
- See [examples/](../examples/) for configuration examples
|
||||
- Check [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Common Operations
|
||||
|
||||
```bash
|
||||
# Stack status
|
||||
"Check my stack"
|
||||
→ ✓ feature/auth | 3 PRs | Review #456
|
||||
|
||||
# PR list
|
||||
"Show PRs needing review"
|
||||
→ 📋 2 PRs: #456 (Auth), #457 (Docs)
|
||||
|
||||
# Git log
|
||||
"Show me recent commits"
|
||||
→ Last 10: abc123 Feature, def456 Fix, ...
|
||||
|
||||
# Submit
|
||||
"Submit my stack"
|
||||
→ ✓ 3 PRs created | CI running | Ready for review
|
||||
```
|
||||
|
||||
### Using Custom Agent
|
||||
|
||||
```bash
|
||||
"graphite-ops check my stack"
|
||||
"graphite-ops show review queue"
|
||||
"graphite-ops submit"
|
||||
"graphite-ops navigate to next branch"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**That's it! You're ready to use context-efficient git/Graphite workflows.** 🚀
|
||||
|
||||
For more details, see the [complete User Guide](USER-GUIDE.md).
|
||||
282
skills/graphite-skill/references/readme.md
Normal file
282
skills/graphite-skill/references/readme.md
Normal file
@@ -0,0 +1,282 @@
|
||||
# Graphite Context-Optimized Plugin for Claude Code
|
||||
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://code.claude.com)
|
||||
|
||||
**Stop drowning in verbose git/Graphite output.** This plugin automatically enables context-efficient workflows for all git and Graphite CLI operations in Claude Code.
|
||||
|
||||
## 🎯 What This Does
|
||||
|
||||
Transforms Claude Code's interaction with git/Graphite from context-polluting to context-efficient:
|
||||
|
||||
**Before (without plugin):**
|
||||
```bash
|
||||
You: "Check my Graphite stack"
|
||||
Claude: [Returns 15KB of JSON → 4,000+ tokens consumed]
|
||||
Context: Polluted, reasoning degraded
|
||||
```
|
||||
|
||||
**After (with plugin):**
|
||||
```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"
|
||||
Context: Clean, 18 tokens used (225x more efficient)
|
||||
```
|
||||
|
||||
## ✨ Features
|
||||
|
||||
- **🔄 Automatic Delegation** - Task subagents handle verbose operations automatically
|
||||
- **🎨 Colored Agent Support** - Optional custom agent with cyan terminal output
|
||||
- **⚡ Zero Friction** - SessionStart hook activates patterns automatically
|
||||
- **📦 Team-Ready** - Git-trackable configuration for team distribution
|
||||
- **🎯 225x Efficiency** - Dramatic context window improvements
|
||||
- **🔧 Flexible** - Supports both Task tool (simple) and custom agents (enhanced UX)
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
# Clone this repository
|
||||
git clone https://github.com/your-username/carbon.git
|
||||
cd carbon
|
||||
|
||||
# Option 1: Install globally (affects all projects)
|
||||
./install.sh --global
|
||||
|
||||
# Option 2: Install in current project (recommended for teams)
|
||||
./install.sh --project
|
||||
|
||||
# Option 3: Manual installation
|
||||
mkdir -p .claude/plugins/carbon
|
||||
cp -r hooks settings.json plugin.json .claude/plugins/carbon/
|
||||
chmod +x .claude/plugins/carbon/hooks/session-start.sh
|
||||
```
|
||||
|
||||
### Verification
|
||||
|
||||
```bash
|
||||
# Test the installation
|
||||
./test/verify-installation.sh
|
||||
|
||||
# Start Claude Code with debug mode
|
||||
claude --debug hooks
|
||||
|
||||
# Test automatic delegation
|
||||
claude
|
||||
> "Check my Graphite stack"
|
||||
# Should automatically use Task delegation ✓
|
||||
```
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
- **[Quick Start Guide](docs/QUICKSTART.md)** - Get running in 5 minutes
|
||||
- **[User Guide](docs/USER-GUIDE.md)** - Complete usage documentation
|
||||
- **[Architecture](docs/ARCHITECTURE.md)** - How it works under the hood
|
||||
- **[Custom Agents](docs/CUSTOM-AGENTS.md)** - Optional colored agent setup
|
||||
- **[Troubleshooting](docs/TROUBLESHOOTING.md)** - Common issues and solutions
|
||||
|
||||
## 🎨 Two Approaches
|
||||
|
||||
### Task Tool (Default - Recommended for Most Users)
|
||||
|
||||
Zero setup, works immediately:
|
||||
|
||||
```bash
|
||||
You: "Check my stack"
|
||||
Claude: [Uses Task delegation automatically]
|
||||
```
|
||||
|
||||
**Characteristics:**
|
||||
- ⚡ No configuration needed
|
||||
- 📦 Works universally
|
||||
- 🎯 Full context isolation
|
||||
- ⚪ Generic terminal output
|
||||
|
||||
### Custom Agent (Optional - Power Users)
|
||||
|
||||
Enhanced UX with colored output:
|
||||
|
||||
```bash
|
||||
# One-time setup
|
||||
/agents create
|
||||
Name: graphite-ops
|
||||
Color: cyan
|
||||
Template: ./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
|
||||
- 👤 Consistent persona
|
||||
- 📁 Git-tracked definition
|
||||
- 🎯 Same context isolation
|
||||
|
||||
See [Custom Agents Guide](docs/CUSTOM-AGENTS.md) for setup instructions.
|
||||
|
||||
## 🔧 How It Works
|
||||
|
||||
### SessionStart Hook
|
||||
|
||||
The plugin uses a SessionStart hook to inject context-optimization patterns into Claude's context window automatically:
|
||||
|
||||
```
|
||||
1. Session starts → Hook fires
|
||||
2. Hook detects: git repo, Graphite CLI, custom agent
|
||||
3. Hook injects: ~800 tokens of patterns into context
|
||||
4. Claude knows: Use Task delegation for verbose operations
|
||||
5. User benefits: Automatic context efficiency, zero friction
|
||||
```
|
||||
|
||||
### Automatic Delegation
|
||||
|
||||
When you request git/Graphite operations, Claude automatically:
|
||||
|
||||
1. Recognizes the operation will return verbose output
|
||||
2. Delegates to Task subagent with explicit instructions
|
||||
3. Subagent executes with `--json` and `2>/dev/null`
|
||||
4. Subagent parses and returns summary <50 tokens
|
||||
5. You receive concise, actionable summary
|
||||
|
||||
**No manual invocation needed - it just works!**
|
||||
|
||||
## 📊 Efficiency Metrics
|
||||
|
||||
| Metric | Before (Raw CLI) | After (Plugin) | Improvement |
|
||||
|--------|------------------|----------------|-------------|
|
||||
| Tokens consumed | 4,108 | 18 | **225x** |
|
||||
| Context pollution | High | Minimal | **99.6% reduction** |
|
||||
| Response quality | Degraded | Optimal | **Focused reasoning** |
|
||||
| User effort | Manual patterns | Zero | **Automatic** |
|
||||
|
||||
## 🎯 Use Cases
|
||||
|
||||
### For Solo Developers
|
||||
|
||||
```bash
|
||||
# Just use Claude naturally
|
||||
"Check my stack"
|
||||
"Show PRs needing review"
|
||||
"Submit for review"
|
||||
|
||||
# Plugin handles context efficiency automatically
|
||||
```
|
||||
|
||||
### For Teams
|
||||
|
||||
```bash
|
||||
# One-time setup
|
||||
git clone <your-repo>
|
||||
./install.sh --project
|
||||
git add .claude/
|
||||
git commit -m "Add Graphite context-optimization"
|
||||
|
||||
# Team members pull and get:
|
||||
# ✓ Automatic context optimization
|
||||
# ✓ Consistent behavior
|
||||
# ✓ Zero per-developer setup
|
||||
```
|
||||
|
||||
### Supported Operations
|
||||
|
||||
**Graphite CLI:**
|
||||
- `gt stack` - Stack status with delegation
|
||||
- `gt pr list` - PR listing with filtering
|
||||
- `gt pr info` - Detailed PR data with parsing
|
||||
- `gt submit` - Submission with confirmation
|
||||
- All other verbose gt commands
|
||||
|
||||
**Git:**
|
||||
- `git log --graph` - Commit history with summarization
|
||||
- `git diff` - Changes with statistics
|
||||
- `git status` - Status with file grouping
|
||||
- All other verbose git commands
|
||||
|
||||
## 🛠️ Configuration
|
||||
|
||||
### Default Configuration
|
||||
|
||||
The plugin works out-of-box with sensible defaults. No configuration required.
|
||||
|
||||
### Custom Configuration
|
||||
|
||||
Adjust behavior by editing `.claude/plugins/carbon/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"contextTokens": 800,
|
||||
"delegationThreshold": 100,
|
||||
"autoDetectGraphite": true,
|
||||
"autoDetectCustomAgent": true,
|
||||
"enableTaskDelegation": true,
|
||||
"enableCustomAgent": true
|
||||
}
|
||||
```
|
||||
|
||||
See [Configuration Guide](docs/CONFIGURATION.md) for details.
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
|
||||
|
||||
### Development Setup
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://github.com/your-username/carbon.git
|
||||
cd carbon
|
||||
|
||||
# Install dependencies (jq required)
|
||||
# Ubuntu/Debian: sudo apt install jq
|
||||
# macOS: brew install jq
|
||||
|
||||
# Run tests
|
||||
./test/run-tests.sh
|
||||
|
||||
# Make changes
|
||||
# ...
|
||||
|
||||
# Test your changes
|
||||
./test/verify-installation.sh
|
||||
```
|
||||
|
||||
## 📝 License
|
||||
|
||||
MIT License - see [LICENSE](LICENSE) for details.
|
||||
|
||||
## 🙏 Acknowledgments
|
||||
|
||||
- [Graphite](https://graphite.dev) - Excellent stacked diff workflow tool
|
||||
- [Claude Code](https://code.claude.com) - Powerful AI-assisted development
|
||||
- Community contributors who provided feedback and testing
|
||||
|
||||
## 📮 Support
|
||||
|
||||
- **Issues**: [GitHub Issues](https://github.com/your-username/carbon/issues)
|
||||
- **Discussions**: [GitHub Discussions](https://github.com/your-username/carbon/discussions)
|
||||
- **Documentation**: [docs/](docs/)
|
||||
|
||||
## 🚦 Status
|
||||
|
||||
- ✅ Production-ready
|
||||
- ✅ Actively maintained
|
||||
- ✅ Tested with Claude Code 2.0+
|
||||
- ✅ Compatible with Graphite CLI 1.0+
|
||||
|
||||
## 📈 Roadmap
|
||||
|
||||
- [ ] Additional git workflow patterns
|
||||
- [ ] Integration with other git tools (gh, lab)
|
||||
- [ ] Advanced custom agent templates
|
||||
- [ ] VSCode extension integration
|
||||
- [ ] Metrics dashboard for context efficiency
|
||||
|
||||
---
|
||||
|
||||
**Install once → Benefit forever → Share with team → Zero-friction context efficiency!** 🚀
|
||||
|
||||
146
skills/graphite-skill/references/team-configuration.md
Normal file
146
skills/graphite-skill/references/team-configuration.md
Normal file
@@ -0,0 +1,146 @@
|
||||
# Example: Team Configuration with Custom Agent
|
||||
|
||||
This example shows a complete team configuration with:
|
||||
- SessionStart hook enabled
|
||||
- Custom graphite-ops agent configured
|
||||
- Team-shared via git
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
your-project/
|
||||
├── .git/
|
||||
└── .claude/
|
||||
├── settings.json # Hook configuration
|
||||
├── agents/
|
||||
│ └── graphite-ops.md # Custom agent definition
|
||||
└── plugins/
|
||||
└── carbon/
|
||||
├── hooks/
|
||||
│ └── session-start.sh # Hook script
|
||||
├── plugin.json
|
||||
└── settings.json
|
||||
```
|
||||
|
||||
## settings.json
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"SessionStart": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "$CLAUDE_PROJECT_DIR/.claude/plugins/carbon/hooks/session-start.sh",
|
||||
"timeout": 10
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## graphite-ops.md (Custom Agent)
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: graphite-ops
|
||||
description: Context-efficient Graphite and git operations
|
||||
agent-color: cyan
|
||||
tools:
|
||||
- bash_tool
|
||||
- view
|
||||
- str_replace
|
||||
---
|
||||
|
||||
[... agent prompt from template ...]
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### For Team Lead (Setup)
|
||||
|
||||
```bash
|
||||
# Install plugin
|
||||
./install.sh --project
|
||||
|
||||
# Create custom agent
|
||||
claude
|
||||
/agents create
|
||||
Name: graphite-ops
|
||||
Color: cyan
|
||||
Prompt: Load from ./agents/graphite-ops-template.md
|
||||
|
||||
# Commit configuration
|
||||
git add .claude/
|
||||
git commit -m "Add Graphite context-optimization plugin"
|
||||
git push
|
||||
```
|
||||
|
||||
### For Team Members (Automatic)
|
||||
|
||||
```bash
|
||||
# Pull repository
|
||||
git pull
|
||||
|
||||
# Plugin activates automatically!
|
||||
claude
|
||||
> "Check my stack"
|
||||
# Uses Task delegation automatically ✓
|
||||
|
||||
# Or use custom agent
|
||||
> "graphite-ops check my stack"
|
||||
# Gets cyan-colored output ✓
|
||||
```
|
||||
|
||||
## Benefits for Teams
|
||||
|
||||
✅ **Zero per-developer setup** - Pull repo → get optimization
|
||||
✅ **Consistent behavior** - Everyone uses same patterns
|
||||
✅ **Visual organization** - Colored agents for easy recognition
|
||||
✅ **Git-tracked** - Configuration version-controlled
|
||||
|
||||
## Customization
|
||||
|
||||
### Adjust Context Size
|
||||
|
||||
Edit `hooks/session-start.sh`:
|
||||
|
||||
```bash
|
||||
# Reduce injected context from ~800 to ~400 tokens
|
||||
CONTEXT="# Context-Optimization Active
|
||||
|
||||
For git/Graphite operations >100 tokens:
|
||||
- Delegate to Task subagent
|
||||
- Return: ✓ [state] | [count] | [action]"
|
||||
```
|
||||
|
||||
### Project-Specific Patterns
|
||||
|
||||
Add custom patterns for your team:
|
||||
|
||||
```bash
|
||||
CONTEXT+="
|
||||
|
||||
## Team-Specific Patterns
|
||||
- Always run tests before submitting stack
|
||||
- Check Jira ticket in commit messages
|
||||
- Use branch naming: feature/PROJ-123-description"
|
||||
```
|
||||
|
||||
### Multiple Agents
|
||||
|
||||
Create specialized agents for different workflows:
|
||||
|
||||
```bash
|
||||
# Git operations
|
||||
/agents create → git-ops [green]
|
||||
|
||||
# PR reviews
|
||||
/agents create → review-ops [blue]
|
||||
|
||||
# CI/CD
|
||||
/agents create → deploy-ops [red]
|
||||
```
|
||||
Reference in New Issue
Block a user