Work Script

IMPORTANT: When the user asks to work on, start, or fix a GitHub or JIRA issue, USE THIS SKILL to spawn a dedicated worker. Do NOT work on the issue in the current session unless explicitly told to (e.g., "work on issue 42 here" or "in this session").

The work script creates isolated Claude Code sessions for GitHub issues and JIRA issues using git worktrees, with SQLite-based worker monitoring for managing multiple parallel sessions.

Usage

# GitHub issues - spawn in new terminal tabs (default)
work 97 98 99                    # Multiple issues in parallel
work https://github.com/owner/repo/issues/42

# JIRA issues (requires acli CLI)
work AIE-123                     # JIRA issue key
work AIE-123 "fix validation"   # With description for branch name
work https://netflix.atlassian.net/browse/AIE-123

# Run in current terminal
work --here 42
work --here AIE-123
work --here 42 "fix memory leak"

# New feature branch (not tied to an issue)
work "add dark mode support"

Cross-Repository Issues

IMPORTANT: The work command must be run from within the repository that the issue belongs to. If you provide a full GitHub URL for an issue in a different repo than your current directory, the script will error with a helpful message.

# Example: You're in ~/projects/repo-a but the issue is in repo-b
$ work https://github.com/owner/repo-b/issues/42
Error: Repository mismatch detected!

  Issue/PR is from:  owner/repo-b
  Current repo:      repo-a

The worktree would be created from the wrong repository.

To fix this, run the work command from the correct repository:
  cd /path/to/repo-b && work https://github.com/owner/repo-b/issues/42

When spawning workers for cross-repo issues:

1. •First cd to the correct repository directory
2. •Then run the work command

Worker Management

Monitor and control spawned workers from a parent session:

# Show all active workers across repos
work --status
# repo_name          | issue | stage           | in_stage | pr   | status
# hawkins-dash       | 12    | implementing    | 15m      | -    | running
# dotfiles           | 45    | ci_waiting      | 8m       | #47  | running
# hawkins-dash       | 34    | review_waiting  | 1h       | #46  | running

# Show recent events (optionally filtered by issue)
work --events
work --events 42

# View events for a specific worker
work --logs 42

# Stop a specific worker
work --stop 42

Issue Argument Syntax

All worker management commands support flexible issue lookups:

# By GitHub issue number (defaults to current repo)
work --stop 42
work --logs 42

# By JIRA key
work --stop AIE-123
work --logs AIE-456
work --send AIE-789 "message"

# By PR number (searches both issue_number and pr_number)
work --logs 47                  # Finds worker by its PR number

# Explicit repo (for cross-repo management)
work --stop hawkins-dash:42     # Stop issue 42 in hawkins-dash repo
work --send myrepo:50 "message" # Send message to worker in different repo

This is useful when managing workers across multiple repositories simultaneously.

Stage Tracking

Workers report their current stage for better visibility. Stages are:

Workers update their stage via:

work --stage implementing      # Set current stage
work --stage ci_waiting --pr 47  # Set stage with PR number

Parent-to-Worker Messaging

Send messages from a parent session to workers:

# Send a message to a worker
work --send 42 "Check the updated API spec before continuing"
work --send 42 --type priority "This is now high priority"
work --send 42 --type context "The database schema changed, see PR #123"

# View pending messages (marks as read by default)
work --messages 42              # View messages for issue #42 (marks as read)
work --messages                 # From within worker, uses WORK_WORKER_ID
work --messages 42 --peek       # View without marking as read

Message types:

• •info (default) - General information
• •priority - Priority change notifications
• •context - Additional context or requirements
• •instruction - Specific instructions to follow

What it does

1. •Parses GitHub issue/PR URLs or numbers, or JIRA issue keys
2. •Fetches issue title from GitHub or JIRA (via acli) for branch naming
3. •Creates or reuses a git worktree at ~/.worktrees/{repo}/{branch} (repo-isolated)
4. •Registers worker in SQLite database for monitoring
5. •Starts Claude Code with a structured prompt for end-to-end completion
6. •Tracks worker status and stage for visibility into workflow progress

JIRA Support

JIRA issue support is automatically enabled when the Atlassian CLI (acli) is installed and authenticated. Without acli, JIRA keys are not recognized and the script works with GitHub issues only.

Install JIRA support:

brew tap atlassian/homebrew-acli
brew install acli
acli jira auth login

How it works:

• •JIRA keys (e.g., AIE-123) are detected by their pattern: uppercase letters, dash, numbers
• •Issue summary is fetched using acli jira workitem view for branch naming
• •Workers can be looked up by JIRA key for all management commands
• •The Claude Code prompt includes instructions to fetch full JIRA issue details using MCP tools

Graceful fallback: If acli is not installed, the script ignores JIRA key patterns and treats them as feature descriptions. This allows the same dotfiles to work on machines with and without JIRA integration.

Auto-Detection Hooks

When installed, Claude Code hooks automatically detect workflow events and update worker status:

Installing Hooks

# Run the installer from your dotfiles repo
./genai/hooks/install-hooks.sh

This installs a PostToolUse hook that monitors Bash commands and automatically updates the worker database.

How It Works

The hook script (~/.claude/hooks/work-stage-detector.sh):

1. •Runs after every Bash tool call
2. •Parses the command and output from the hook input
3. •Detects workflow events (PR creation, CI checks, merges, conflicts)
4. •Updates the worker's status/phase in the SQLite database
5. •Logs events for tracking via work --events

This eliminates manual stage reporting, ensuring accurate workflow progression tracking.

Database

Worker state is stored in ~/.worktrees/work-sessions.db with four tables:

• •workers - Active worker metadata (repo, issue_number, jira_key, issue_source, branch, PID, status, stage, pr_number)
• •events - History of status changes, stage transitions, and events
• •completions - Final summaries when workers complete
• •messages - Parent-to-worker message queue

Directory Structure

Worktrees are organized by repository to prevent issue number collisions:

~/.worktrees/
├── work-sessions.db          # Shared SQLite database
├── hawkins-dash/
│   ├── issue-42-fix-auth/
│   └── issue-99-add-metrics/
└── dotfiles/
    └── issue-15-work-hooks/

Environment variables

• •MAIN_BRANCH - Base branch for new branches (default: main)
• •WORKTREE_BASE - Directory for worktrees (default: ~/.worktrees)
• •SPAWN_DELAY - Delay between tab spawns (default: 0.5s)

Workers also export these variables for use by Claude Code:

• •WORK_WORKER_ID - Database ID of the current worker
• •WORK_DB_PATH - Path to the SQLite database

When to use this skill

ALWAYS use this skill when the user:

• •Says "work on issue X", "start issue X", "fix issue X", "implement issue X"
• •Wants to work on a GitHub issue or JIRA issue (spawn a worker, don't work here)
• •References a JIRA key like "AIE-123" or "work on AIE-123"
• •Asks to work on multiple issues in parallel
• •Wants to check on running workers (work --status)
• •Needs to send messages to workers (work --send)
• •Wants to stop a worker (work --stop)

DO NOT use this skill when:

• •User explicitly says "work on it here" or "in this session"
• •User is asking about the work script itself (just answer the question)
• •User wants to see worker status (use work --status directly via Bash)

Note

This script is designed to run outside Claude Code to start new sessions. If run from within a Claude Code session, it outputs the task info instead of starting a nested session.