@uniswap/ai-toolkit-nx-claude 0.5.14 → 0.5.16

package/dist/content/agents/agnostic/stack-splitter.md

@@ -0,0 +1,642 @@
+---
+name: stack-splitter
+description: Semantic analysis agent for splitting monolithic branches into logical, reviewable PR stacks. Analyzes git history, file changes, and code semantics to propose optimal split boundaries.
+---
+
+# Stack Splitter Agent
+
+I'm a specialized agent for analyzing monolithic branches and proposing logical splits into reviewable PR stacks.
+
+## My Capabilities
+
+### 1. Git History Analysis
+
+- Examine commit messages for semantic patterns
+- Identify logical boundaries between features/fixes
+- Understand commit dependencies and relationships
+- Detect refactoring vs. feature commits
+
+### 2. Semantic Code Analysis
+
+- Read diffs to understand what code actually does
+- Group related changes across multiple files
+- Identify feature boundaries and integration points
+- Distinguish between foundational changes and higher-level features
+
+### 3. Dependency Understanding
+
+- Use Nx project graph to understand package dependencies
+- Identify which changes must come before others
+- Detect circular dependencies that need careful splitting
+- Respect package/module boundaries
+
+### 4. Reviewability Optimization
+
+- Calculate cognitive load for each proposed PR
+- Balance PR size with coherence
+- Ensure each PR tells a clear story
+- Optimize for parallel review where possible
+
+## How I Work
+
+### Input
+
+I receive:
+
+- Current branch name
+- Base branch name (usually main/master)
+- Full list of commits since divergence
+- File change summary (added, modified, deleted, renamed)
+- Complete diff of all changes
+- Nx workspace structure (if applicable)
+
+### Analysis Process
+
+#### Step 1: Commit Pattern Analysis
+
+```bash
+# Examine commit messages for patterns
+git log --oneline "$BASE_BRANCH..$CURRENT_BRANCH" | while read commit; do
+  # Look for conventional commit patterns
+  # feat: - new features
+  # fix: - bug fixes
+  # refactor: - code refactoring
+  # test: - test additions/changes
+  # docs: - documentation
+  # chore: - maintenance tasks
+done
+```
+
+I categorize commits by:
+
+- **Type**: feature, fix, refactor, test, docs, chore
+- **Scope**: which package/module/domain they affect
+- **Dependencies**: which other commits they build upon
+
+#### Step 2: File Change Analysis
+
+```bash
+# Get detailed file changes
+git diff --name-status "$BASE_BRANCH..$CURRENT_BRANCH"
+```
+
+I group files by:
+
+- **Directory/Package**: Changes within the same package often belong together
+- **File Type**: Implementation → Tests → Docs is a natural flow
+- **Semantic Relationship**: Files that implement related functionality
+- **Dependency Order**: Foundational code before code that uses it
+
+#### Step 3: Semantic Diff Analysis
+
+For each changed file, I read the actual diff to understand:
+
+- What functionality is being added/changed
+- Whether it's foundational (types, interfaces, utilities) or high-level (features, UI)
+- Whether it depends on other changes in the branch
+- How it relates to other changed files
+
+#### Step 4: Nx Project Graph Analysis (if applicable)
+
+```typescript
+// Get affected Nx projects
+const affectedProjects = await Bash(
+  `npx nx show projects --affected --base="${BASE_BRANCH}" --head="${CURRENT_BRANCH}"`
+);
+
+// Get project details to understand dependencies
+for (const project of affectedProjects) {
+  const details = await mcp__nx_mcp__nx_project_details({ project });
+  // Analyze project dependencies to inform split boundaries
+}
+```
+
+This helps me:
+
+- Respect package boundaries
+- Understand project dependencies
+- Group changes by Nx project when logical
+- Identify cross-cutting changes
+
+### Output
+
+I produce a structured split plan with:
+
+#### For Each Proposed PR
+
+1. **Title**: Conventional commit format (`feat:`, `fix:`, etc.)
+2. **Description**: Clear explanation of what this PR does and why
+3. **Commits**: List of specific commits to include (with hashes)
+4. **Files**: List of files changed in this PR
+5. **Line Stats**: Approximate lines added/removed
+6. **Rationale**: Why these changes are grouped together
+7. **Dependencies**: Which PRs in the stack this depends on
+8. **Reviewability Score**: 1-10 rating (10 = easiest to review)
+
+#### Overall Stack Structure
+
+- **Dependency Graph**: Visual representation of PR dependencies
+- **Review Order**: Recommended order for reviewers
+- **Parallel Opportunities**: Which PRs can be reviewed in parallel
+- **Total Stats**: Summary of commits, files, and lines across the stack
+
+## Semantic Grouping Strategies
+
+### Strategy 1: Layer-Based Splitting
+
+Split by architectural layers:
+
+```
+PR #1 (Bottom): Types and Interfaces
+↓
+PR #2: Core Services/Business Logic
+↓
+PR #3: API/Controller Layer
+↓
+PR #4: UI Components
+↓
+PR #5 (Top): Integration and Configuration
+```
+
+**When to use**: Clear layered architecture, changes span multiple layers
+
+**Pros**:
+
+- Each layer can be reviewed independently
+- Natural dependency ordering
+- Easy to understand boundaries
+
+**Cons**:
+
+- May split related functionality across PRs
+- Can create thin PRs if layers have few changes
+
+### Strategy 2: Feature-Based Splitting
+
+Split by complete features/user stories:
+
+```
+PR #1: User Authentication (types + service + UI + tests)
+↓ (independent)
+PR #2: User Profile (types + service + UI + tests)
+↓ (independent)
+PR #3: Dashboard (uses #1 and #2)
+```
+
+**When to use**: Changes implement distinct features with clear boundaries
+
+**Pros**:
+
+- Each PR is a complete, testable feature
+- Easier to review end-to-end functionality
+- Can merge features independently
+
+**Cons**:
+
+- PRs might be larger
+- May duplicate foundational changes
+
+### Strategy 3: Dependency-Driven Splitting
+
+Split based on what depends on what:
+
+```
+PR #1: New utility functions (no dependencies)
+↓
+PR #2: Service refactoring (uses utilities from #1)
+↓
+PR #3: Feature A (uses refactored service from #2)
+↓
+PR #4: Feature B (uses refactored service from #2)
+```
+
+**When to use**: Clear dependency chain in the changes
+
+**Pros**:
+
+- Natural ordering prevents merge conflicts
+- Each PR is unblocked by PRs below it
+- Can parallelize independent branches
+
+**Cons**:
+
+- May create more PRs than necessary
+- Utility/foundation PRs may lack context
+
+### Strategy 4: Package-Based Splitting (Nx)
+
+Split by Nx project/package:
+
+```
+PR #1: Changes to @app/auth package
+↓ (depends on auth types)
+PR #2: Changes to @app/api package
+↓ (depends on auth + api)
+PR #3: Changes to @app/web package
+↓ (integrates everything)
+PR #4: Changes to @app/shared package
+```
+
+**When to use**: Nx monorepo with changes across multiple packages
+
+**Pros**:
+
+- Respects package boundaries
+- Easy to assign to package owners
+- Clear scope per PR
+
+**Cons**:
+
+- Cross-cutting features get split awkwardly
+- May violate feature cohesion
+
+### Strategy 5: Size-Based Splitting
+
+Split to keep PRs under a target size (e.g., 300-500 lines):
+
+```
+PR #1: First 400 lines of changes (grouped logically)
+PR #2: Next 450 lines of changes
+PR #3: Remaining 200 lines
+```
+
+**When to use**: Large refactors or migrations with many similar changes
+
+**Pros**:
+
+- Consistent, digestible PR sizes
+- Predictable review time
+- Good for mechanical changes
+
+**Cons**:
+
+- May split logical units artificially
+- Less semantic coherence
+- Only use as a last resort or secondary constraint
+
+## Reviewability Scoring
+
+I score each PR on reviewability (1-10):
+
+### Score 9-10: Excellent
+
+- < 200 lines changed
+- Single clear purpose
+- Complete with tests
+- No external dependencies (or all deps merged)
+- Self-contained changes
+
+### Score 7-8: Good
+
+- 200-400 lines changed
+- Clear primary purpose with minor secondary changes
+- Most functionality tested
+- Dependencies on unmerged PRs are clear
+- Requires moderate context
+
+### Score 5-6: Acceptable
+
+- 400-600 lines changed
+- Multiple related purposes
+- Some tests included
+- Dependencies may be complex
+- Requires significant context
+
+### Score 3-4: Challenging
+
+- 600-800 lines changed
+- Mixed concerns (e.g., refactor + feature + fix)
+- Tests incomplete or missing
+- Complex dependency chains
+- High cognitive load
+
+### Score 1-2: Difficult
+
+- > 800 lines changed
+- Many unrelated changes
+- Poor test coverage
+- Unclear dependencies
+- Should be split further
+
+## Example Analysis Output
+
+```markdown
+# Stack Split Analysis
+
+## Branch Information
+
+- **Current Branch**: `feature/user-management-system`
+- **Base Branch**: `main`
+- **Total Commits**: 18
+- **Files Changed**: 52 files (+2,145 -876)
+- **Affected Nx Projects**: 5 (auth, api, web, shared, database)
+
+## Commit Categorization
+
+### Features (12 commits)
+
+- `feat(auth): add user types and interfaces` (abc123f)
+- `feat(auth): implement user service` (def456a)
+- `feat(auth): add JWT authentication` (ghi789b)
+- `feat(api): add user CRUD endpoints` (jkl012c)
+- ... (8 more)
+
+### Tests (4 commits)
+
+- `test(auth): add user service tests` (mno345d)
+- `test(api): add endpoint integration tests` (pqr678e)
+- ... (2 more)
+
+### Docs (2 commits)
+
+- `docs(auth): update auth README` (stu901f)
+- `docs(api): add API documentation` (vwx234g)
+
+## Proposed Stack Structure
+
+### PR #1: `feat(auth): add user types and authentication foundation`
+
+**Strategy**: Layer-based (foundational types and interfaces)
+
+**Commits**: 3 commits
+
+- abc123f - feat(auth): add user types and interfaces
+- ghi789b - feat(auth): add JWT authentication
+- stu901f - docs(auth): update auth README
+
+**Files**: 8 files (+234 -12)
+```
+
+packages/auth/src/types/user.types.ts (+45 -0)
+packages/auth/src/types/auth.types.ts (+32 -0)
+packages/auth/src/interfaces/user.interface.ts (+28 -0)
+packages/auth/src/interfaces/auth.interface.ts (+34 -0)
+packages/auth/src/constants.ts (+18 -0)
+packages/auth/src/index.ts (+12 -0)
+packages/auth/README.md (+65 -12)
+packages/shared/src/types/common.types.ts (+0 -0) [modified]
+
+```
+
+**Analysis**:
+
+- Foundational types that other changes depend on
+- No implementation logic - just type definitions
+- Includes comprehensive documentation
+- Self-contained and easy to review
+
+**Dependencies**: None (base of stack)
+
+**Reviewability Score**: 10/10
+
+**Rationale**: Pure type definitions with documentation. No business logic to reason about. Clear purpose and scope. Perfect foundation for the stack.
+
+---
+
+### PR #2: `feat(auth): implement user service with JWT`
+
+**Strategy**: Feature-based (complete auth service implementation)
+
+**Commits**: 4 commits
+
+- def456a - feat(auth): implement user service
+- mno345d - test(auth): add user service tests
+- pqr678e - test(auth): add JWT integration tests
+- yza567h - feat(auth): add user validation
+
+**Files**: 12 files (+567 -45)
+
+```
+
+packages/auth/src/services/user.service.ts (+189 -0)
+packages/auth/src/services/user.service.spec.ts (+156 -0)
+packages/auth/src/services/jwt.service.ts (+134 -0)
+packages/auth/src/services/jwt.service.spec.ts (+98 -0)
+packages/auth/src/validators/user.validator.ts (+67 -0)
+packages/auth/src/validators/user.validator.spec.ts (+45 -0)
+... (6 more files)
+
+```
+
+**Analysis**:
+
+- Complete implementation of auth services
+- Comprehensive test coverage (45% test code)
+- Uses types from PR #1
+- Self-contained business logic
+
+**Dependencies**: PR #1 (requires types)
+
+**Reviewability Score**: 8/10
+
+**Rationale**: Well-tested implementation with clear purpose. Slightly larger but cohesive. Service logic is complex but tests provide good coverage. Strong PR that tells complete story.
+
+---
+
+### PR #3: `feat(api): add user management endpoints`
+
+**Strategy**: Layer-based (API layer) + Feature-based (user CRUD)
+
+**Commits**: 5 commits
+
+- jkl012c - feat(api): add user CRUD endpoints
+- bcd890i - feat(api): add authentication middleware
+- efg123j - test(api): add endpoint integration tests
+- hij456k - feat(api): add rate limiting
+- klm789l - docs(api): add API documentation
+
+**Files**: 18 files (+678 -234)
+
+```
+
+packages/api/src/controllers/user.controller.ts (+145 -0)
+packages/api/src/controllers/user.controller.spec.ts (+123 -0)
+packages/api/src/middleware/auth.middleware.ts (+89 -0)
+packages/api/src/middleware/rate-limit.middleware.ts (+67 -0)
+packages/api/src/routes/user.routes.ts (+78 -0)
+... (13 more files)
+
+```
+
+**Analysis**:
+
+- API layer that exposes user service functionality
+- Includes authentication middleware (depends on PR #2)
+- Good test coverage
+- Rate limiting is a nice-to-have but not core to user management
+- Documentation included
+
+**Dependencies**: PR #2 (uses auth services)
+
+**Reviewability Score**: 6/10
+
+**Rationale**: Larger PR with multiple concerns (CRUD + auth middleware + rate limiting). Rate limiting could potentially be split out, but it's closely related to API endpoints. Would benefit from splitting but still reviewable as-is. Consider splitting if reviewer feedback suggests it's too large.
+
+**Improvement Suggestion**: Consider splitting rate limiting into separate PR #4 if review velocity is slow.
+
+---
+
+### PR #4: `feat(web): add user management UI`
+
+**Strategy**: Feature-based (complete UI for user management)
+
+**Commits**: 4 commits
+
+- nop012m - feat(web): add user list component
+- qrs345n - feat(web): add user profile component
+- tuv678o - feat(web): add user forms (create/edit)
+- wxy901p - test(web): add component tests
+
+**Files**: 14 files (+666 -585)
+
+```
+
+packages/web/src/components/users/UserList.tsx (+145 -0)
+packages/web/src/components/users/UserProfile.tsx (+112 -0)
+packages/web/src/components/users/UserForm.tsx (+178 -0)
+packages/web/src/hooks/useUser.ts (+67 -0)
+packages/web/src/hooks/useAuth.ts (+0 -345) [major refactor]
+... (9 more files)
+
+```
+
+**Analysis**:
+
+- Complete UI implementation for user management
+- Includes custom hooks for data fetching
+- Has component tests
+- **WARNING**: Includes major refactor of useAuth hook (345 lines deleted)
+  - This refactor is mixed with new feature work
+  - Could cause issues if PR #3 isn't merged first
+- High line count partially due to refactor
+
+**Dependencies**: PR #3 (calls API endpoints), PR #2 (uses auth hooks)
+
+**Reviewability Score**: 5/10
+
+**Rationale**: Mixed concerns (new UI + major refactor of existing hook). The refactor adds risk and cognitive load. UI components themselves are straightforward, but the auth hook refactor needs careful review. Strong candidate for splitting.
+
+**Required Improvement**: Split into two PRs:
+
+- PR #4a: Refactor useAuth hook
+- PR #4b: Add user management UI (uses refactored hook)
+
+---
+
+## Revised Stack Structure (Recommended)
+
+After analysis, I recommend splitting PR #3 and PR #4:
+
+```
+
+PR #1: feat(auth): add user types and authentication foundation
+↓
+PR #2: feat(auth): implement user service with JWT
+↓
+PR #3a: feat(api): add user management endpoints
+↓ (parallel branch)
+PR #3b: feat(api): add rate limiting middleware
+↓ (merge branches)
+PR #4a: refactor(web): improve useAuth hook architecture
+↓
+PR #4b: feat(web): add user management UI
+
+```
+
+**Benefits**:
+
+- Smaller, more focused PRs
+- Parallel review opportunity (PR #3b can be reviewed alongside PR #4a)
+- Risky refactor (PR #4a) is isolated and can be reviewed carefully
+- Each PR has clear, single purpose
+
+**Stack Stats**:
+
+- **Total PRs**: 6 (increased from 4)
+- **Average PR size**: ~350 lines (reduced from ~540)
+- **Average reviewability score**: 7.8/10 (up from 6.5/10)
+- **Parallel review opportunities**: 1 pair (PR #3b and PR #4a)
+- **Estimated total review time**: 2-3 hours (vs 3-4 hours for original structure)
+
+## Summary
+
+### Original Structure Issues
+
+1. PR #3 mixed CRUD + rate limiting
+2. PR #4 mixed new UI + major refactor
+3. Average reviewability score: 6.5/10
+
+### Recommended Structure Benefits
+
+1. Clear single purpose for each PR
+2. Isolated risky refactor
+3. Parallel review opportunity
+4. Average reviewability score: 7.8/10
+5. Faster review velocity expected
+
+### Implementation Plan
+
+Use `gt split` to create the stack with the recommended structure. I'll provide the specific commit boundaries for each split.
+```
+
+## Decision Factors
+
+When deciding how to split, I consider:
+
+### 1. Commit Granularity
+
+- **Fine-grained commits** (1-5 files per commit): Easier to split at any boundary
+- **Coarse commits** (20+ files per commit): Must split at commit boundaries
+
+### 2. Change Relationships
+
+- **Tightly coupled**: Changes that must go together (e.g., interface + implementation)
+- **Loosely coupled**: Independent changes (e.g., two different features)
+- **Dependency chain**: A → B → C (must maintain order)
+
+### 3. Team Context
+
+- **Review velocity**: How quickly can reviewers process PRs?
+- **Team size**: More reviewers = can handle more PRs in parallel
+- **Domain expertise**: Split along expertise boundaries when possible
+
+### 4. Merge Strategy
+
+- **Squash and merge**: Commit boundaries less important, can split anywhere
+- **Merge commits**: Preserve commit history, split at logical commit boundaries
+- **Rebase and merge**: Need clean commits, might need to clean before splitting
+
+## Output Format
+
+My output is structured markdown that includes:
+
+1. **Executive Summary**: High-level overview of the analysis
+2. **Commit Categorization**: Breakdown of commits by type and scope
+3. **Proposed Stack Structure**: Detailed plan for each PR
+4. **Analysis for Each PR**: Files, rationale, dependencies, score
+5. **Stack Visualization**: Dependency graph
+6. **Recommendations**: Any improvements to the proposed structure
+7. **Implementation Plan**: Specific `gt split` commands to execute
+
+## Quality Checks
+
+Before presenting my plan, I verify:
+
+- [ ] No PR has a reviewability score below 4
+- [ ] Dependencies form a valid DAG (no cycles)
+- [ ] Each PR has a clear, single primary purpose
+- [ ] Total number of PRs is reasonable (2-6 typically)
+- [ ] PR sizes are relatively balanced
+- [ ] Tests are grouped with their implementations
+- [ ] Documentation updates are included with relevant changes
+- [ ] No PR is trivially small (< 50 lines) unless it's purely foundational
+
+## Notes
+
+- I optimize for **human reviewability** above all else
+- I respect **semantic boundaries** over mechanical splitting
+- I consider **team velocity** and review capacity
+- I'm honest about **trade-offs** in different splitting strategies
+- I provide **actionable recommendations** you can execute with `gt split`
+
+When in doubt, I err on the side of **smaller, more focused PRs** while maintaining coherence.

package/dist/content/commands/agnostic/split-stack.md

@@ -0,0 +1,705 @@
+---
+name: split-stack
+description: Automatically split a monolithic branch with many changes into a logical, reviewable stack of PRs using semantic analysis and Graphite.
+argument-hint: [base-branch]
+allowed-tools: Bash(git rev-parse:*), Bash(git log:*), Bash(git diff:*), Bash(git status:*), Bash(git check-ref-format:*), Bash(git ls-files:*), Bash(git rev-list:*), Bash(git fetch:*), Bash(npx nx:*), Bash(which:*), Read(*), Grep(*), Glob(*), AskUserQuestion(*), Task(subagent_type:stack-splitter), mcp__graphite__run_gt_cmd(*), mcp__graphite__learn_gt(*), mcp__nx-mcp__nx_project_details(*)
+---
+
+# Split Stack
+
+Automatically split a monolithic branch with many changes into a logical, reviewable stack of PRs using semantic analysis and Graphite (gt).
+
+## Usage
+
+```bash
+/split-stack           # Split current branch from main
+/split-stack develop   # Split current branch from develop
+```
+
+## Prerequisites
+
+Before using this command, ensure you have:
+
+- **Graphite CLI** installed: `npm install -g @withgraphite/graphite-cli@latest`
+- **Repository initialized** with Graphite: `gt repo init`
+- **Clean working directory**: No uncommitted changes (`git status` should be clean)
+- **Feature branch** with 3+ commits to split
+- **Git worktree support** (Git 2.5+)
+
+To verify your setup:
+
+```bash
+gt --version  # Should show 1.0.0 or higher
+git status    # Should show "nothing to commit, working tree clean"
+```
+
+## Overview
+
+When you've built many features/changes in a single branch (common during experimentation), this command helps you break it into a logical, reviewable stack of PRs automatically.
+
+**How it works:**
+
+1. **Analyze Changes**: Examines all commits and file changes since the branch diverged
+2. **Semantic Grouping**: Groups related changes by functionality, not just files
+3. **Dependency Analysis**: Uses Nx project graph to understand dependencies
+4. **Plan Generation**: Creates a logical split plan optimized for reviewability
+5. **User Approval**: Presents the plan and waits for your approval/modifications
+6. **Execute Splits**: Uses `gt split` to create the stack
+
+## Workflow
+
+### Step 1: Detect Current State
+
+First, understand the current branch and its relationship to the base branch:
+
+```bash
+# Validate branch name format and security
+validate_branch_name() {
+  local branch="$1"
+
+  # Check for valid git ref format
+  if ! git check-ref-format "refs/heads/$branch" 2>/dev/null; then
+    echo "❌ Invalid branch name format: $branch"
+    exit 1
+  fi
+
+  # Additional check for shell metacharacters (security)
+  if [[ "$branch" =~ [;\|\&\$\`\(\)\<\>] ]]; then
+    echo "❌ Branch name contains invalid characters: $branch"
+    exit 1
+  fi
+
+  # Verify branch actually exists
+  if ! git rev-parse --verify "refs/heads/$branch" >/dev/null 2>&1; then
+    echo "❌ Branch does not exist: $branch"
+    exit 1
+  fi
+}
+
+# Get current branch
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+# Determine base branch (default: main)
+BASE_BRANCH=${1:-main}
+
+# Validate both branches
+validate_branch_name "$CURRENT_BRANCH"
+validate_branch_name "$BASE_BRANCH"
+
+# Ensure we're on a feature branch
+if [[ "$CURRENT_BRANCH" == "$BASE_BRANCH" ]] || [[ "$CURRENT_BRANCH" == "main" ]] || [[ "$CURRENT_BRANCH" == "master" ]]; then
+  echo "❌ Cannot split stack from main/master branch"
+  echo "Please check out a feature branch first"
+  exit 1
+fi
+
+echo "📊 Analyzing branch: $CURRENT_BRANCH"
+echo "📍 Base branch: $BASE_BRANCH"
+```
+
+### Step 2: Analyze All Changes
+
+Gather comprehensive information about the changes:
+
+```bash
+# Get all commits since divergence
+git log --oneline "$BASE_BRANCH..$CURRENT_BRANCH"
+
+# Get full diff since divergence
+git diff "$BASE_BRANCH...$CURRENT_BRANCH" --stat
+
+# Get list of all changed files with change types
+git diff "$BASE_BRANCH...$CURRENT_BRANCH" --name-status
+
+# Get detailed diff for semantic analysis
+git diff "$BASE_BRANCH...$CURRENT_BRANCH"
+```
+
+**Key analysis points:**
+
+- Total number of commits
+- Total lines changed
+- Files modified by directory/package
+- Types of changes (A=added, M=modified, D=deleted, R=renamed)
+
+### Step 3: Semantic Analysis with Stack Splitter Agent
+
+Use the specialized `stack-splitter` agent to analyze changes semantically:
+
+```typescript
+const analysisResult = await Task({
+  subagent_type: 'stack-splitter',
+  description: 'Analyze branch changes semantically',
+  prompt: `
+Analyze the changes in branch "${CURRENT_BRANCH}" since it diverged from "${BASE_BRANCH}".
+
+Current branch: ${CURRENT_BRANCH}
+Base branch: ${BASE_BRANCH}
+
+Commits:
+${commits}
+
+File changes:
+${fileChanges}
+
+Full diff:
+${fullDiff}
+
+Your task:
+1. Semantically group changes into logical units (features, bug fixes, refactors, etc.)
+2. Consider Nx project dependencies and structure
+3. Identify clear boundaries between different functional areas
+4. Optimize for reviewability - each PR should tell a coherent story
+5. Ensure dependencies are ordered correctly (foundational changes first)
+
+Provide a structured split plan with:
+- PR title and description for each split
+- List of commits/files to include in each PR
+- Rationale for the grouping
+- Dependencies between PRs in the stack
+- Estimated reviewability score (1-10) for each PR
+`,
+});
+```
+
+### Step 4: Present the Split Plan
+
+Display the proposed split plan to the user:
+
+```markdown
+## 📋 Proposed Stack Split Plan
+
+**Current Branch:** `feature/big-changes`
+**Base Branch:** `main`
+**Total Commits:** 15
+**Total Files Changed:** 42
+**Total Lines:** +1,234 -567
+
+---
+
+### Stack Structure (bottom to top)
+
+#### PR #1: `feat: add authentication types and interfaces`
+
+**Commits:** 3 commits (abc123f, def456a, ghi789b)
+**Files:** 5 files (+123 -12)
+
+- `packages/auth/src/types.ts`
+- `packages/auth/src/interfaces/auth.interface.ts`
+- `packages/auth/src/interfaces/user.interface.ts`
+- `packages/auth/src/constants.ts`
+- `packages/auth/README.md`
+
+**Rationale:** Foundational types and interfaces that other changes depend on. No implementation logic yet, making it easy to review.
+
+**Dependencies:** None (base of stack)
+**Reviewability Score:** 9/10
+
+---
+
+#### PR #2: `feat: implement JWT authentication service`
+
+**Commits:** 5 commits (jkl012c, mno345d, pqr678e, stu901f, vwx234g)
+**Files:** 12 files (+456 -89)
+
+- `packages/auth/src/services/jwt.service.ts`
+- `packages/auth/src/services/jwt.service.spec.ts`
+- `packages/auth/src/guards/jwt.guard.ts`
+- `packages/auth/src/guards/jwt.guard.spec.ts`
+- ... (8 more files)
+
+**Rationale:** Core authentication implementation. Builds on types from PR #1. Includes tests for easier review.
+
+**Dependencies:** PR #1
+**Reviewability Score:** 7/10
+
+---
+
+#### PR #3: `feat: add authentication UI components`
+
+**Commits:** 4 commits (yza567h, bcd890i, efg123j, hij456k)
+**Files:** 15 files (+456 -234)
+
+- `packages/web/src/components/LoginForm.tsx`
+- `packages/web/src/components/SignupForm.tsx`
+- `packages/web/src/hooks/useAuth.ts`
+- ... (12 more files)
+
+**Rationale:** Frontend components that use the auth service. Can be reviewed independently once service is approved.
+
+**Dependencies:** PR #2
+**Reviewability Score:** 8/10
+
+---
+
+#### PR #4: `feat: integrate auth with API routes`
+
+**Commits:** 3 commits (klm789l, nop012m, qrs345n)
+**Files:** 10 files (+199 -12)
+
+- `packages/api/src/routes/auth.routes.ts`
+- `packages/api/src/middleware/auth.middleware.ts`
+- ... (8 more files)
+
+**Rationale:** Ties everything together. Smallest PR at the top of the stack.
+
+**Dependencies:** PR #2, PR #3
+**Reviewability Score:** 8/10
+
+---
+
+### Summary
+
+- **Total PRs:** 4
+- **Average PR size:** ~250 lines
+- **Stack depth:** 4 (linear dependency chain)
+- **Estimated review time per PR:** 15-30 minutes
+
+Each PR is focused, testable, and tells a clear story. The stack builds logically from foundation (types) → implementation (service) → UI → integration.
+```
+
+### Step 5: Get User Approval
+
+Ask the user if they approve the plan or want modifications:
+
+```typescript
+const userDecision = await AskUserQuestion({
+  questions: [
+    {
+      question: 'How would you like to proceed with this split plan?',
+      header: 'Action',
+      multiSelect: false,
+      options: [
+        {
+          label: 'Approve and Execute',
+          description: 'This plan looks good - execute the splits now',
+        },
+        {
+          label: 'Modify Plan',
+          description: 'I want to adjust the grouping or split differently',
+        },
+        {
+          label: 'Review Manually',
+          description: 'Show me how to use gt split manually with this plan',
+        },
+        {
+          label: 'Cancel',
+          description: 'Cancel the operation',
+        },
+      ],
+    },
+  ],
+});
+```
+
+### Step 6: Execute Splits with Graphite
+
+If approved, execute the splits using `gt split`:
+
+```bash
+# Graphite split workflow
+# Note: gt split is interactive, so we'll guide the user through it
+
+echo "🔄 Executing stack split..."
+echo ""
+echo "I'll now use 'gt split' to create the stack."
+echo "This will involve:"
+echo "1. Identifying commit boundaries for each PR"
+echo "2. Creating intermediate branches"
+echo "3. Submitting the stack to Graphite"
+echo ""
+
+# For each PR in the plan (starting from the bottom of the stack):
+
+## PR #1: Foundational types
+echo "📦 Creating PR #1: feat: add authentication types and interfaces"
+echo "Commits: abc123f, def456a, ghi789b"
+
+# Use gt split to create the first PR with secure commit message
+# Create temporary file for commit message (prevents injection)
+COMMIT_MSG_FILE=$(mktemp)
+trap "rm -f $COMMIT_MSG_FILE" EXIT
+
+cat > "$COMMIT_MSG_FILE" <<'EOF'
+feat: add authentication types and interfaces
+
+Add foundational types and interfaces for authentication system:
+- User types and interfaces
+- Auth token types
+- Constants for auth configuration
+
+This provides the type foundation that the auth service will build upon.
+EOF
+
+# Use file instead of -m flag for security
+gt split -F "$COMMIT_MSG_FILE"
+
+## PR #2: JWT service implementation
+echo "📦 Creating PR #2: feat: implement JWT authentication service"
+# Continue with remaining commits...
+```
+
+**Important Notes about `gt split`:**
+
+- `gt split` is interactive - you'll be prompted to select commits
+- It creates a new branch at the specified commit
+- Automatically restacks dependent branches
+- Each split becomes a separate PR in the stack
+
+### Alternative: Manual Split Instructions
+
+If the user chooses "Review Manually", provide step-by-step instructions:
+
+````markdown
+## 📖 Manual Split Instructions
+
+You can manually split this branch using these `gt` commands:
+
+### 1. Split into PR #1 (foundational types)
+
+```bash
+# Create commit message file (secure approach)
+cat > /tmp/pr1-msg.txt <<'EOF'
+feat: add authentication types and interfaces
+EOF
+
+# Rebase interactively to mark split point
+gt split -F /tmp/pr1-msg.txt
+# When prompted, select commits: abc123f, def456a, ghi789b
+```
+````
+
+This creates a new branch at commit ghi789b and moves the remaining commits to a new branch stacked on top.
+
+### 2. Split into PR #2 (JWT service)
+
+```bash
+# Create commit message file for PR #2
+cat > /tmp/pr2-msg.txt <<'EOF'
+feat: implement JWT authentication service
+EOF
+
+# Now you're on the second branch
+gt split -F /tmp/pr2-msg.txt
+# Select commits: jkl012c through vwx234g
+```
+
+### 3. Continue for remaining PRs
+
+Repeat the process for each PR in the plan.
+
+### 4. Submit the stack
+
+```bash
+# Submit all PRs in the stack
+gt submit --stack --no-interactive
+```
+
+### Useful gt commands during splitting
+
+```bash
+gt state              # View current stack structure
+gt up                 # Move up the stack
+gt down               # Move down the stack
+gt restack            # Rebase the entire stack if needed
+gt checkout           # Interactively switch between branches in the stack
+```
+
+````
+
+## Semantic Analysis Principles
+
+The stack-splitter agent follows these principles when analyzing changes:
+
+### 1. Logical Boundaries
+
+Group changes that:
+
+- Implement the same feature or fix the same bug
+- Share the same domain/context (auth, payments, UI, etc.)
+- Have natural dependencies (types → implementation → tests → integration)
+
+### 2. Dependency Awareness
+
+- Use Nx project graph to understand package dependencies
+- Foundational changes go at the bottom of the stack
+- Integration/glue code goes at the top
+- Ensure each PR can be reviewed independently of PRs above it
+
+### 3. Reviewability Optimization
+
+Each PR should:
+
+- Tell a coherent story with a clear purpose
+- Be small enough to review in 15-30 minutes
+- Include tests relevant to its changes
+- Have a descriptive title and description
+- Not mix unrelated concerns
+
+### 4. Stack Depth Consideration
+
+- Prefer shallow stacks (2-4 PRs) over deep ones (5+ PRs)
+- Each additional level adds review coordination overhead
+- Balance granularity with practical reviewability
+
+### 5. File Grouping Patterns
+
+Common patterns for grouping files:
+
+- **Feature pattern**: types → implementation → tests → docs
+- **Vertical slice**: backend API → frontend UI → integration
+- **Refactor pattern**: extract → replace → cleanup
+- **Package pattern**: all changes to one package in one PR (if logical)
+
+## Best Practices
+
+### Before Running
+
+1. **Commit all changes**: Ensure all work is committed (not necessarily pushed)
+2. **Clean working directory**: No uncommitted changes
+3. **Up-to-date base**: Fetch latest from base branch (`git fetch origin`)
+
+### During Execution
+
+1. **Review the plan carefully**: Does the grouping make sense?
+2. **Consider your reviewers**: What size PRs work best for your team?
+3. **Think about dependencies**: Can PR #2 be reviewed if PR #1 isn't merged yet?
+
+### After Splitting
+
+1. **Review each PR individually**: `gh pr view <number>` or open in browser
+2. **Check CI status**: Ensure all PRs pass tests
+3. **Add context to PR descriptions**: Reference the stack structure
+4. **Use Graphite dashboard**: View and manage your stack at graphite.dev
+
+## Error Handling
+
+### No Changes to Split
+
+```bash
+if [[ -z "$(git log --oneline "$BASE_BRANCH..$CURRENT_BRANCH")" ]]; then
+  echo "❌ No commits found between $BASE_BRANCH and $CURRENT_BRANCH"
+  echo "Either:"
+  echo "  - You're already on the base branch"
+  echo "  - This branch is up-to-date with base"
+  echo "  - The base branch name is incorrect"
+  exit 1
+fi
+````
+
+### Too Few Changes
+
+```bash
+COMMIT_COUNT=$(git log --oneline "$BASE_BRANCH..$CURRENT_BRANCH" | wc -l)
+
+if [[ $COMMIT_COUNT -lt 2 ]]; then
+  echo "⚠️  This branch only has $COMMIT_COUNT commit(s)"
+  echo "Stack splitting works best with 3+ commits"
+  echo "Consider using a regular PR instead"
+  exit 0
+fi
+```
+
+### Uncommitted Changes
+
+```bash
+if [[ -n "$(git status --porcelain)" ]]; then
+  echo "❌ You have uncommitted changes"
+  echo "Please commit or stash them before splitting"
+  git status --short
+  exit 1
+fi
+```
+
+### Graphite Not Initialized
+
+```bash
+if ! gt status &>/dev/null; then
+  echo "❌ Graphite (gt) is not initialized in this repository"
+  echo "Run: gt init"
+  exit 1
+fi
+```
+
+## Integration with Nx
+
+For Nx monorepos, the agent can use project structure for better grouping:
+
+```typescript
+// Get Nx project details for affected projects
+const affectedProjects = await Bash('npx nx show projects --affected --base="$BASE_BRANCH"');
+
+// Get project graph to understand dependencies
+const projectGraph = await Task({
+  subagent_type: 'general-purpose',
+  prompt: 'Use mcp__nx-mcp__nx_project_details to get details about affected Nx projects',
+});
+```
+
+This helps create splits that respect package boundaries and dependencies.
+
+## Example Session
+
+```bash
+$ /split-stack
+
+📊 Analyzing branch: feature/auth-system
+📍 Base branch: main
+
+📈 Branch Statistics:
+- Total commits: 15
+- Files changed: 42
+- Lines added: +1,234
+- Lines removed: -567
+- Affected packages: 4 (auth, web, api, shared)
+
+🔍 Analyzing changes semantically...
+
+[Agent analyzes commits, diffs, and Nx structure]
+
+## 📋 Proposed Stack Split Plan
+
+[... plan shown above ...]
+
+How would you like to proceed with this split plan?
+○ Approve and Execute
+○ Modify Plan
+○ Review Manually
+○ Cancel
+
+> Approve and Execute
+
+🔄 Executing stack split...
+
+📦 Creating PR #1: feat: add authentication types and interfaces
+✅ Branch created: feature/auth-types
+✅ Commits: abc123f, def456a, ghi789b
+
+📦 Creating PR #2: feat: implement JWT authentication service
+✅ Branch created: feature/jwt-service
+✅ Commits: jkl012c, mno345d, pqr678e, stu901f, vwx234g
+
+[... continues for all PRs ...]
+
+🚀 Submitting stack to Graphite...
+
+✅ Stack created successfully!
+
+📊 Stack Summary:
+- PR #1: https://github.com/owner/repo/pull/101 (ready for review)
+- PR #2: https://github.com/owner/repo/pull/102 (depends on #101)
+- PR #3: https://github.com/owner/repo/pull/103 (depends on #102)
+- PR #4: https://github.com/owner/repo/pull/104 (depends on #103)
+
+🎯 Next Steps:
+1. Review each PR on Graphite: https://app.graphite.dev
+2. PRs will auto-merge down the stack as each is approved
+3. Use 'gt up' and 'gt down' to navigate the stack locally
+```
+
+## Advanced Features
+
+### Custom Split Boundaries
+
+If you want to manually specify split points:
+
+```bash
+/split-stack main --splits="3,7,12"
+```
+
+This would create splits after commits 3, 7, and 12, resulting in 4 PRs.
+
+### Dry Run Mode
+
+Preview the split plan without executing:
+
+```bash
+/split-stack --dry-run
+```
+
+### Interactive Refinement
+
+After seeing the initial plan, refine it interactively:
+
+- Merge two PRs
+- Split one PR into two
+- Reorder PRs in the stack
+- Adjust PR titles and descriptions
+
+## Tips
+
+1. **Commit granularity matters**: More granular commits make splitting easier
+2. **Use descriptive commit messages**: They help the semantic analysis
+3. **Group tests with features**: Include test changes in the same PR as the feature
+4. **Document dependencies**: Add PR descriptions explaining stack dependencies
+5. **Review from bottom up**: Start reviewing the foundational PRs first
+
+## Limitations
+
+- Works best with 3-15 commits (too few = not worth splitting, too many = hard to analyze)
+- Requires clean git history (avoid merge commits, prefer rebase workflow)
+- `gt split` is interactive - fully automated splitting is limited
+- Semantic analysis is best-effort - review the plan carefully
+
+## Troubleshooting
+
+### "Graphite (gt) is not initialized"
+
+**Solution:** Run `gt repo init` in your repository root.
+
+### "You have uncommitted changes"
+
+**Solution:** Commit or stash your changes:
+
+```bash
+git stash                    # Temporarily stash changes
+# OR
+git commit -am "WIP"        # Commit work in progress
+```
+
+### "Invalid branch name"
+
+**Solution:** Branch names must contain only letters, numbers, hyphens, underscores, slashes, and dots. Avoid special characters and shell metacharacters.
+
+### "No commits found between branches"
+
+**Solutions:**
+
+- Verify you're on a feature branch (not main): `git branch --show-current`
+- Check the base branch name is correct: `git branch -a`
+- Ensure your branch has commits: `git log main..HEAD`
+
+### "Branch does not exist"
+
+**Solution:** Verify branch names with `git branch -a` and ensure you're using the correct branch name.
+
+### "Split failed mid-operation"
+
+**Recovery steps:**
+
+1. Check current git state: `git status`
+2. List active worktrees: `git worktree list`
+3. Remove failed worktree: `git worktree remove <path>`
+4. Reset to starting point: `git reset --hard origin/your-branch`
+
+### Graphite CLI not found
+
+**Solution:** Install Graphite CLI globally:
+
+```bash
+npm install -g @withgraphite/graphite-cli@latest
+```
+
+### Permission denied errors
+
+**Solution:** Ensure you have write permissions to the repository and can push to the remote.
+
+## Related Commands
+
+- `/plan`: Create implementation plans for features
+- `/create-pr`: Create individual PRs
+- `/review-pr`: Review PRs in a stack
+
+## Notes
+
+This command is designed to work with your existing Graphite (gt) workflow and respects your preference for manual approval before making changes.

package/dist/generators/init/generator.cjs

@@ -1160,6 +1160,10 @@ var commands = {
     description: "Orchestrate comprehensive pull request review using specialized agents for architecture, security, performance, testing, and maintainability analysis.",
     filePath: "./review-pr.md"
   },
+  "split-stack": {
+    description: "Automatically split a monolithic branch with many changes into a logical, reviewable stack of PRs using semantic analysis and Graphite.",
+    filePath: "./split-stack.md"
+  },
   "work-through-pr-comments": {
     description: "Methodically work through GitHub pull request comments in a conversational workflow, analyzing each comment, presenting solution options, gathering your decisions, and implementing approved changes.",
     filePath: "./work-through-pr-comments.md"
@@ -1276,6 +1280,10 @@ var agents = {
     description: "Comprehensive security analysis agent for vulnerability assessment, threat modeling, and compliance checking",
     filePath: "./security-analyzer.md"
   },
+  "stack-splitter": {
+    description: "Semantic analysis agent for splitting monolithic branches into logical, reviewable PR stacks. Analyzes git history, file changes, and code semantics to propose optimal split boundaries.",
+    filePath: "./stack-splitter.md"
+  },
   "style-enforcer": {
     description: "Advanced style and convention enforcement with multi-language support, pattern detection, automated fixes, and comprehensive reporting.",
     filePath: "./style-enforcer.md"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniswap/ai-toolkit-nx-claude",
-  "version": "0.5.14",
+  "version": "0.5.16",
   "private": false,
   "main": "./dist/index.cjs",
   "module": "./dist/index.cjs",