npm package: @randythechung/claude-workflows
Description: Multi-model AI workflow orchestration for code review, planning, and development
Author: Randy Marsh
Latest version: 1.0.0

# Dev Workspace

A unified terminal development environment combining:
- **zmux** - Zellij-based git worktree manager
- **Claude Workflows** - AI-powered development commands and agents
- **Terminal IDE** - Neovim + lazygit + delta for a complete dev setup

## Quick Start

```bash
# Clone and install
git clone https://github.com/YOU/dev-workspace.git
cd dev-workspace
./install.sh

# Set up a project
./install.sh ~/projects/my-app --init --namespace ABC

# Start working on a Linear ticket
cd ~/projects/my-app
zmux fc 123  # Creates worktree + starts Claude with /full-cycle ABC-123

# Or review PRs in parallel
zmux pr 261 263 265  # Opens 3 tabs, each reviewing a PR
```

## What's Included

```
dev-workspace/
├── install.sh                  # Installation script
├── bin/
│   └── zmux                    # Git worktree + Zellij manager
├── claude/
│   ├── agents/                 # Subagent definitions
│   │   ├── explorer.md
│   │   ├── planner.md
│   │   ├── implementer.md
│   │   ├── reviewer.md
│   │   ├── documenter.md
│   │   ├── summarizer.md
│   │   └── pr-reviewer.md
│   └── commands/               # Slash commands for Claude Code
│       ├── linear-task.md
│       ├── explore.md
│       ├── plan.md
│       ├── implement.md
│       ├── review.md
│       ├── review-response.md
│       ├── summarize.md
│       ├── document.md
│       ├── commit.md
│       ├── full-cycle.md
│       └── pr-review.md
├── scripts/
│   └── multi-model-review.sh   # Multi-AI PR review orchestrator
├── config/
│   └── nvim/                   # Neovim configuration
│       └── init.lua
└── templates/
    ├── CLAUDE.md.template
    ├── mcp.json.template
    └── zmux.yaml.template
```

## Components

### 1. zmux - Worktree Manager

zmux replaces tmux-based workmux with Zellij for better mouse support and workflow integration.

| Command | Description |
|---------|-------------|
| `zmux fc <ticket> [...]` | Create worktree(s) + start `/full-cycle` |
| `zmux pr <pr#> [...]` | Create worktree(s) + start `/pr-review` |
| `zmux add <branch>` | Create worktree and zellij tab |
| `zmux remove <branch>` | Remove worktree and close tab |
| `zmux merge <branch>` | Merge to main and cleanup |
| `zmux list` | Show active worktrees |
| `zmux goto <branch>` | Switch to tab by name |
| `zmux attach` | Attach to zmux session |

**Parallel workflows:**
```bash
# Work on 3 Linear tickets simultaneously
zmux fc 100 101 102

# Review 3 PRs in parallel
zmux pr 261 263 265

# Use Alt+1/2/3 or click tabs to switch
```

### 2. Claude Workflows

A complete workflow system with specialized agents:

| Agent | Role |
|-------|------|
| @explorer | Understand tickets + analyze codebase |
| @planner | Create detailed implementation plans |
| @implementer | Execute plans with precision |
| @reviewer | Thorough code review |
| @summarizer | Create summaries and commit messages |
| @documenter | Update documentation |
| @pr-reviewer | Multi-model PR review synthesis |

**Main commands:**
```bash
/linear-task ABC-123    # Load a Linear ticket
/full-cycle ABC-123     # Complete automated workflow
/pr-review 456          # Multi-model PR review
```

**Workflow stages:**
```
1. Explore → 2. Plan → [CHECKPOINT] → 3. Implement →
4-7. Review Loop → 8. Summarize → [CHECKPOINT] →
9. Document → 10. Commit
```

### 3. Terminal IDE

A three-pane development environment:

```
┌──────────────┬────────────────────────┬─────────────────┐
│ lazygit      │ neovim                 │ claude          │
│              │                        │                 │
│ • File tree  │ • Auto-reload on save  │ • AI assistant  │
│ • Git status │ • Side-by-side diffs   │ • Edits files   │
│ • Stage/diff │ • diffview.nvim        │ • Shows diffs   │
└──────────────┴────────────────────────┴─────────────────┘
```

## Installation

### System Requirements

```bash
# macOS
brew install neovim lazygit zellij git-delta fzf ripgrep gh

# Ubuntu/Debian
sudo apt install neovim ripgrep fzf
# Install lazygit, zellij, gh, delta from GitHub releases
```

### Install Dev Workspace

```bash
# Clone
git clone https://github.com/YOU/dev-workspace.git ~/dev-workspace

# Install (global tools only)
cd ~/dev-workspace
./install.sh

# This will:
# 1. Install zmux to ~/.local/bin/
# 2. Configure git-delta (optional)
# 3. Set up Neovim config (optional)
```

## Project Setup

### New Project

```bash
./install.sh ~/projects/my-app --init --namespace ABC
```

This creates:
- `.zmux.yaml` - Worktree and pane configuration
- `.claude/` - Commands and agents
- `CLAUDE.md` - Project-specific AI instructions (customize this!)
- `.mcp.json` - MCP server configuration
- `scripts/` - Workflow scripts

### Existing Project

```bash
# Update workflow files (preserves your custom agents/commands)
./install.sh ~/projects/my-app

# Use --symlink for auto-updates from source
./install.sh ~/projects/my-app --symlink

# Use --force to overwrite existing files
./install.sh ~/projects/my-app --force
```

### Install Options

| Option | Description |
|--------|-------------|
| `--dry-run` | Show what would be done without doing it |
| `--symlink` | Symlink files for auto-updates from source |
| `--init` | Create CLAUDE.md and .mcp.json (new projects) |
| `--namespace <n>` | Linear namespace (required with --init) |
| `--force` | Overwrite existing files |

## Configuration

### .zmux.yaml

```yaml
# Where to create worktrees
worktree_dir: "../{{REPO_NAME}}__worktrees"

# Linear integration (use 'zmux fc 123' instead of 'zmux fc ABC-123')
linear_prefix: ABC

# Panes for each worktree tab
panes:
  - name: claude
    command: claude
    focus: true
  - name: shell
    command: ""

# File handling
files:
  symlink:
    - node_modules
    - .pnpm-store
  copy:
    - .env.local
```

### CLAUDE.md

The `CLAUDE.md` file gives Claude context about your project:

```markdown
# Project Name

## Overview
Brief description of the project.

## Tech Stack
- Language/framework
- Database
- Key dependencies

## Development Commands
- `pnpm dev` - Start dev server
- `pnpm test` - Run tests

## Code Conventions
- Style guide rules
- Architecture patterns
```

## Workflows in Detail

### Linear Ticket Workflow (`/full-cycle`)

```
zmux fc 123
  │
  ├─→ Creates worktree: abc-123
  ├─→ Opens Zellij tab with Claude + shell panes
  └─→ Claude runs /full-cycle ABC-123
        │
        ├─ 1. Load ticket from Linear API
        ├─ 2. @explorer analyzes codebase
        ├─ 3. @planner creates implementation plan
        │      └─ [CHECKPOINT: User approves plan]
        ├─ 4. @implementer executes plan
        ├─ 5. @reviewer performs code review
        ├─ 6-7. Review loop (max 3 iterations)
        ├─ 8. @summarizer presents changes
        │      └─ [CHECKPOINT: User approves]
        ├─ 9. @documenter updates docs
        └─ 10. Commit with generated message
```

### PR Review Workflow (`/pr-review`)

```
zmux pr 456
  │
  ├─→ Creates worktree: pr-456
  ├─→ Opens Zellij tab
  └─→ Claude runs /pr-review 456
        │
        ├─ 1. Fetch PR from GitHub (diff, comments)
        ├─ 2. Run multi-model-review.sh
        │      ├─ Claude analysis
        │      ├─ Gemini analysis
        │      └─ OpenAI analysis
        ├─ 3. @pr-reviewer synthesizes feedback
        └─ 4. Output actionable gh CLI commands
```

## Tips & Tricks

### Quick Navigation

```bash
# Inside Zellij
Alt+1/2/3       # Switch tabs
Ctrl+p n        # New pane
Ctrl+p x        # Close pane
Ctrl+o w        # Session picker

# Inside Neovim
<leader>ff      # Find files
<leader>fg      # Live grep
<leader>gd      # Git diff view
```

### Parallel PR Reviews

```bash
# Start reviewing multiple PRs
zmux pr 261 263 265

# Each tab has Claude pre-loaded with /pr-review
# Switch between them with Alt+1/2/3
```

### Copy from Terminal

Zellij supports native mouse selection:
- Select text with mouse → auto-copies
- Right-click to paste
- No special copy mode needed!

## Troubleshooting

### "Command not found: zmux"

```bash
# Add to PATH
export PATH="$HOME/.local/bin:$PATH"

# Or re-run install
~/dev-workspace/install.sh
```

### Zellij session won't start

```bash
# Check for existing sessions
zellij list-sessions

# Kill stuck sessions
zellij kill-session zmux
```

### Claude commands not showing

```bash
# Verify .claude directory exists
ls -la .claude/commands/

# Re-install to project
~/dev-workspace/install.sh /path/to/project --force
```

## License

MIT