feat(vcs): enhance graphite-stacks skill with additional CLI features

[galligan]

Summary

Research of official Graphite CLI documentation reveals several valuable features and workflows not currently covered in the graphite-stacks skill. This issue tracks enhancements to make the skill more comprehensive and useful for real-world Graphite workflows.

Research Findings

Detailed research available at: .scratch/graphite-docs-research.md

Key Gaps Identified

The current skill covers core workflows well but is missing:

1. Collaboration features (frozen branches, fetching remote work)
2. AI-powered workflows (auto-generated branch names and PR metadata)
3. Advanced branch operations (squash, fold, split)
4. Stack testing (running tests across entire stacks)
5. Command aliases and shortcuts (faster workflow)
6. Global flags (--dry-run, --debug, --quiet, etc.)

Prioritized Additions

Priority 1: Essential Collaboration Features

Impact: HIGH - Critical for multi-developer teams

• gt get [branch] - Fetch remote branches for collaboration

  • Automatically freezes fetched branches by default
  • Flags: --remote-upstack, --force, --unfrozen
  • Use case: Building on teammate's unmerged work

• gt freeze / gt unfreeze - Prevent accidental modifications

  • Read-only mode for branches
  • Visual indication in gt info and gt log
  • Use case: Safely stack on others' work without conflicts

• Expand recovery.md - Add frozen branch recovery scenarios

Documentation:

• Introducing Frozen Branches
• Graphite Synchronizing Changes

Priority 2: Developer Productivity

Impact: MEDIUM-HIGH - Reduces friction in daily workflows

• AI Features - Auto-generate names and metadata

  • gt create --ai - GPT-4 generated branch names from diff
  • gt submit --ai - Auto-generate PR titles/descriptions
  • --edit flag - Use AI output as starting point

• Branch Manipulation Commands

  • gt squash - Combine commits into one (with auto-restack)
  • gt fold - Merge branch into parent (with --keep flag)
  • gt split - Split by commit/hunk/file (--by-commit, --by-hunk, --by-file)

• Enhanced Delete

  • gt delete with --close, --upstack, --downstack flags
  • Cascade deletion and PR closure

Documentation:

• Graphite CLI Features
• Squash, Fold, and Split

Priority 3: Advanced Workflows

Impact: MEDIUM - Valuable for teams with complex workflows

• Stack Testing

  • gt stack test [command] - Run tests across entire stack
  • gt upstack test, gt downstack test - Directional testing
  • Use case: CI/CD integration, pre-submit validation

• Merge Queue Integration

  • gt merge command with --dry-run, --confirm
  • Stack-aware parallel CI
  • Prevention of semantic merge conflicts

• Command Aliases

  • Noun-verb structure: gt branch create = gt bc
  • Shortcuts: gt bb (bottom), gt bt (top), gt bu (up)
  • Faster common operations

Documentation:

• Run Command on Stack
• Merge Queue
• Command Reference (GitHub)

Priority 4: Reference Material

Impact: MEDIUM - Improves skill comprehensiveness

• Create collaboration.md reference

  • Frozen branches workflow
  • Fetching and building on remote work
  • Multi-developer stack patterns

• Create advanced-operations.md reference

  • When to use squash vs fold vs split
  • Stack testing patterns
  • Commit operations (gt commit amend, gt commit create)

• Enhance commands.md

  • Add global flags section (--help, --debug, --dry-run, --quiet, --no-interactive, --no-verify)
  • Add command aliases table
  • Add missing commands (gt rename, gt continue, gt dash, gt pr)

• Create configuration.md reference (optional)

  • gt repo config (name, owner, pr-templates, remote)
  • gt user config (branch-date, branch-prefix, editor, submit-body)
  • PR template integration

Suggested Structure

vcs/skills/graphite-stacks/
├── SKILL.md                         # Enhanced with collaboration focus
├── references/
│   ├── commands.md                  # Add aliases, global flags, missing commands
│   ├── recovery.md                  # Existing - add frozen branch scenarios
│   ├── collaboration.md             # NEW - frozen branches, gt get workflows
│   ├── advanced-operations.md       # NEW - squash, fold, split, testing
│   └── configuration.md             # NEW (optional) - repo/user config
└── examples/                        # NEW (optional)
    ├── multi-developer-workflow.md
    └── ai-assisted-workflow.md

Clarity Improvements

The following areas could be clearer in the current skill:

1. Difference between gt sync and gt get

   • gt sync - Full repo sync (pull trunk, rebase stacks, clean merged)
   • gt get - Fetch specific remote branches (for collaboration)

2. When to use gt modify vs gt commit amend/create

   • Current skill only covers gt modify
   • Alternative commit-focused commands exist

3. Additional flags for existing commands

   • gt submit --dry-run, --edit
   • gt absorb --dry-run, --patch
   • gt restack --branch, --upstack, --downstack

Implementation Approach

Suggested order:

1. Start with Priority 1 (collaboration features) - highest impact
2. Add Priority 2 (productivity features) - quick wins
3. Create new reference files as needed
4. Add examples if valuable
5. Update SKILL.md to reference new content

Keep skill focused:

• SKILL.md should remain <500 lines (core methodology)
• Move detailed command docs to references/
• Use progressive disclosure pattern

Sources

Official Documentation

• Graphite Command Reference
• Graphite CLI Documentation
• Configure CLI
• Squash, Fold, and Split
• Merge Queue

Guides and Blog Posts

• Introducing Frozen Branches
• Graphite Cheatsheet
• Complete Guide Gist

Community Resources

• Fig.io Manual
• Tower Git: Synchronizing

---

Related: Full research document available at .scratch/graphite-docs-research.md