Initial commit
This commit is contained in:
Zhongwei Li
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!** 🚀
|
||||
|
||||
Reference in New Issue
Block a user