claudecode-omc 4.3.4

package/skills/project-session-manager/SKILL.md

@@ -0,0 +1,564 @@
+---
+name: project-session-manager
+description: Manage isolated dev environments with git worktrees and tmux sessions
+aliases: [psm]
+---
+
+# Project Session Manager (PSM) Skill
+
+`psm` is the compatibility alias for this canonical skill entrypoint.
+
+> **Quick Start:** For simple worktree creation without tmux sessions, use `omc teleport`:
+> ```bash
+> omc teleport #123          # Create worktree for issue/PR
+> omc teleport my-feature    # Create worktree for feature
+> omc teleport list          # List worktrees
+> ```
+> See [Teleport Command](#teleport-command) below for details.
+
+Automate isolated development environments using git worktrees and tmux sessions with Claude Code. Enables parallel work across multiple tasks, projects, and repositories.
+
+Canonical slash command: `/oh-my-claudecode:project-session-manager` (alias: `/oh-my-claudecode:psm`).
+
+## Commands
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `review <ref>` | PR review session | `/psm review omc#123` |
+| `fix <ref>` | Issue fix session | `/psm fix omc#42` |
+| `feature <proj> <name>` | Feature development | `/psm feature omc add-webhooks` |
+| `list [project]` | List active sessions | `/psm list` |
+| `attach <session>` | Attach to session | `/psm attach omc:pr-123` |
+| `kill <session>` | Kill session | `/psm kill omc:pr-123` |
+| `cleanup` | Clean merged/closed | `/psm cleanup` |
+| `status` | Current session info | `/psm status` |
+
+## Project References
+
+Supported formats:
+- **Alias**: `omc#123` (requires `~/.psm/projects.json`)
+- **Full**: `owner/repo#123`
+- **URL**: `https://github.com/owner/repo/pull/123`
+- **Current**: `#123` (uses current directory's repo)
+
+## Configuration
+
+### Project Aliases (`~/.psm/projects.json`)
+
+```json
+{
+  "aliases": {
+    "omc": {
+      "repo": "Yeachan-Heo/oh-my-claudecode",
+      "local": "~/Workspace/oh-my-claudecode",
+      "default_base": "main"
+    }
+  },
+  "defaults": {
+    "worktree_root": "~/.psm/worktrees",
+    "cleanup_after_days": 14
+  }
+}
+```
+
+## Providers
+
+PSM supports multiple issue tracking providers:
+
+| Provider | CLI Required | Reference Formats | Commands |
+|----------|--------------|-------------------|----------|
+| GitHub (default) | `gh` | `owner/repo#123`, `alias#123`, GitHub URLs | review, fix, feature |
+| Jira | `jira` | `PROJ-123` (if PROJ configured), `alias#123` | fix, feature |
+
+### Jira Configuration
+
+To use Jira, add an alias with `jira_project` and `provider: "jira"`:
+
+```json
+{
+  "aliases": {
+    "mywork": {
+      "jira_project": "MYPROJ",
+      "repo": "mycompany/my-project",
+      "local": "~/Workspace/my-project",
+      "default_base": "develop",
+      "provider": "jira"
+    }
+  }
+}
+```
+
+**Important:** The `repo` field is still required for cloning the git repository. Jira tracks issues, but you work in a git repo.
+
+For non-GitHub repos, use `clone_url` instead:
+```json
+{
+  "aliases": {
+    "private": {
+      "jira_project": "PRIV",
+      "clone_url": "git@gitlab.internal:team/repo.git",
+      "local": "~/Workspace/repo",
+      "provider": "jira"
+    }
+  }
+}
+```
+
+### Jira Reference Detection
+
+PSM only recognizes `PROJ-123` format as Jira when `PROJ` is explicitly configured as a `jira_project` in your aliases. This prevents false positives from branch names like `FIX-123`.
+
+### Jira Examples
+
+```bash
+# Fix a Jira issue (MYPROJ must be configured)
+psm fix MYPROJ-123
+
+# Fix using alias (recommended)
+psm fix mywork#123
+
+# Feature development (works same as GitHub)
+psm feature mywork add-webhooks
+
+# Note: 'psm review' is not supported for Jira (no PR concept)
+# Use 'psm fix' for Jira issues
+```
+
+### Jira CLI Setup
+
+Install the Jira CLI:
+```bash
+# macOS
+brew install ankitpokhrel/jira-cli/jira-cli
+
+# Linux
+# See: https://github.com/ankitpokhrel/jira-cli#installation
+
+# Configure (interactive)
+jira init
+```
+
+The Jira CLI handles authentication separately from PSM.
+
+## Directory Structure
+
+```
+~/.psm/
+├── projects.json       # Project aliases
+├── sessions.json       # Active session registry
+└── worktrees/          # Worktree storage
+    └── <project>/
+        └── <type>-<id>/
+```
+
+## Session Naming
+
+| Type | Tmux Session | Worktree Dir |
+|------|--------------|--------------|
+| PR Review | `psm:omc:pr-123` | `~/.psm/worktrees/omc/pr-123` |
+| Issue Fix | `psm:omc:issue-42` | `~/.psm/worktrees/omc/issue-42` |
+| Feature | `psm:omc:feat-auth` | `~/.psm/worktrees/omc/feat-auth` |
+
+---
+
+## Implementation Protocol
+
+When the user invokes a PSM command, follow this protocol:
+
+### Parse Arguments
+
+Parse `{{ARGUMENTS}}` to determine:
+1. **Subcommand**: review, fix, feature, list, attach, kill, cleanup, status
+2. **Reference**: project#number, URL, or session ID
+3. **Options**: --branch, --base, --no-claude, --no-tmux, etc.
+
+### Subcommand: `review <ref>`
+
+**Purpose**: Create PR review session
+
+**Steps**:
+
+1. **Resolve reference**:
+   ```bash
+   # Read project aliases
+   cat ~/.psm/projects.json 2>/dev/null || echo '{"aliases":{}}'
+
+   # Parse ref format: alias#num, owner/repo#num, or URL
+   # Extract: project_alias, repo (owner/repo), pr_number, local_path
+   ```
+
+2. **Fetch PR info**:
+   ```bash
+   gh pr view <pr_number> --repo <repo> --json number,title,author,headRefName,baseRefName,body,files,url
+   ```
+
+3. **Ensure local repo exists**:
+   ```bash
+   # If local path doesn't exist, clone
+   if [[ ! -d "$local_path" ]]; then
+     git clone "https://github.com/$repo.git" "$local_path"
+   fi
+   ```
+
+4. **Create worktree**:
+   ```bash
+   worktree_path="$HOME/.psm/worktrees/$project_alias/pr-$pr_number"
+
+   # Fetch PR branch
+   cd "$local_path"
+   git fetch origin "pull/$pr_number/head:pr-$pr_number-review"
+
+   # Create worktree
+   git worktree add "$worktree_path" "pr-$pr_number-review"
+   ```
+
+5. **Create session metadata**:
+   ```bash
+   cat > "$worktree_path/.psm-session.json" << EOF
+   {
+     "id": "$project_alias:pr-$pr_number",
+     "type": "review",
+     "project": "$project_alias",
+     "ref": "pr-$pr_number",
+     "branch": "<head_branch>",
+     "base": "<base_branch>",
+     "created_at": "$(date -Iseconds)",
+     "tmux_session": "psm:$project_alias:pr-$pr_number",
+     "worktree_path": "$worktree_path",
+     "source_repo": "$local_path",
+     "github": {
+       "pr_number": $pr_number,
+       "pr_title": "<title>",
+       "pr_author": "<author>",
+       "pr_url": "<url>"
+     },
+     "state": "active"
+   }
+   EOF
+   ```
+
+6. **Update sessions registry**:
+   ```bash
+   # Add to ~/.psm/sessions.json
+   ```
+
+7. **Create tmux session**:
+   ```bash
+   tmux new-session -d -s "psm:$project_alias:pr-$pr_number" -c "$worktree_path"
+   ```
+
+8. **Launch Claude Code** (unless --no-claude):
+   ```bash
+   tmux send-keys -t "psm:$project_alias:pr-$pr_number" "claude" Enter
+   ```
+
+9. **Output session info**:
+   ```
+   Session ready!
+
+     ID: omc:pr-123
+     Worktree: ~/.psm/worktrees/omc/pr-123
+     Tmux: psm:omc:pr-123
+
+   To attach: tmux attach -t psm:omc:pr-123
+   ```
+
+### Subcommand: `fix <ref>`
+
+**Purpose**: Create issue fix session
+
+**Steps**:
+
+1. **Resolve reference** (same as review)
+
+2. **Fetch issue info**:
+   ```bash
+   gh issue view <issue_number> --repo <repo> --json number,title,body,labels,url
+   ```
+
+3. **Create feature branch**:
+   ```bash
+   cd "$local_path"
+   git fetch origin main
+   branch_name="fix/$issue_number-$(echo "$title" | tr ' ' '-' | tr '[:upper:]' '[:lower:]' | head -c 30)"
+   git checkout -b "$branch_name" origin/main
+   ```
+
+4. **Create worktree**:
+   ```bash
+   worktree_path="$HOME/.psm/worktrees/$project_alias/issue-$issue_number"
+   git worktree add "$worktree_path" "$branch_name"
+   ```
+
+5. **Create session metadata** (similar to review, type="fix")
+
+6. **Update registry, create tmux, launch claude** (same as review)
+
+### Subcommand: `feature <project> <name>`
+
+**Purpose**: Start feature development
+
+**Steps**:
+
+1. **Resolve project** (from alias or path)
+
+2. **Create feature branch**:
+   ```bash
+   cd "$local_path"
+   git fetch origin main
+   branch_name="feature/$feature_name"
+   git checkout -b "$branch_name" origin/main
+   ```
+
+3. **Create worktree**:
+   ```bash
+   worktree_path="$HOME/.psm/worktrees/$project_alias/feat-$feature_name"
+   git worktree add "$worktree_path" "$branch_name"
+   ```
+
+4. **Create session, tmux, launch claude** (same pattern)
+
+### Subcommand: `list [project]`
+
+**Purpose**: List active sessions
+
+**Steps**:
+
+1. **Read sessions registry**:
+   ```bash
+   cat ~/.psm/sessions.json 2>/dev/null || echo '{"sessions":{}}'
+   ```
+
+2. **Check tmux sessions**:
+   ```bash
+   tmux list-sessions -F "#{session_name}" 2>/dev/null | grep "^psm:"
+   ```
+
+3. **Check worktrees**:
+   ```bash
+   ls -la ~/.psm/worktrees/*/ 2>/dev/null
+   ```
+
+4. **Format output**:
+   ```
+   Active PSM Sessions:
+
+   ID                 | Type    | Status   | Worktree
+   -------------------|---------|----------|---------------------------
+   omc:pr-123        | review  | active   | ~/.psm/worktrees/omc/pr-123
+   omc:issue-42      | fix     | detached | ~/.psm/worktrees/omc/issue-42
+   ```
+
+### Subcommand: `attach <session>`
+
+**Purpose**: Attach to existing session
+
+**Steps**:
+
+1. **Parse session ID**: `project:type-number`
+
+2. **Verify session exists**:
+   ```bash
+   tmux has-session -t "psm:$session_id" 2>/dev/null
+   ```
+
+3. **Attach**:
+   ```bash
+   tmux attach -t "psm:$session_id"
+   ```
+
+### Subcommand: `kill <session>`
+
+**Purpose**: Kill session and cleanup
+
+**Steps**:
+
+1. **Kill tmux session**:
+   ```bash
+   tmux kill-session -t "psm:$session_id" 2>/dev/null
+   ```
+
+2. **Remove worktree**:
+   ```bash
+   worktree_path=$(jq -r ".sessions[\"$session_id\"].worktree" ~/.psm/sessions.json)
+   source_repo=$(jq -r ".sessions[\"$session_id\"].source_repo" ~/.psm/sessions.json)
+
+   cd "$source_repo"
+   git worktree remove "$worktree_path" --force
+   ```
+
+3. **Update registry**:
+   ```bash
+   # Remove from sessions.json
+   ```
+
+### Subcommand: `cleanup`
+
+**Purpose**: Clean up merged PRs and closed issues
+
+**Steps**:
+
+1. **Read all sessions**
+
+2. **For each PR session, check if merged**:
+   ```bash
+   gh pr view <pr_number> --repo <repo> --json merged,state
+   ```
+
+3. **For each issue session, check if closed**:
+   ```bash
+   gh issue view <issue_number> --repo <repo> --json closed,state
+   ```
+
+4. **Clean up merged/closed sessions**:
+   - Kill tmux session
+   - Remove worktree
+   - Update registry
+
+5. **Report**:
+   ```
+   Cleanup complete:
+     Removed: omc:pr-123 (merged)
+     Removed: omc:issue-42 (closed)
+     Kept: omc:feat-auth (active)
+   ```
+
+### Subcommand: `status`
+
+**Purpose**: Show current session info
+
+**Steps**:
+
+1. **Detect current session** from tmux or cwd:
+   ```bash
+   tmux display-message -p "#{session_name}" 2>/dev/null
+   # or check if cwd is inside a worktree
+   ```
+
+2. **Read session metadata**:
+   ```bash
+   cat .psm-session.json 2>/dev/null
+   ```
+
+3. **Show status**:
+   ```
+   Current Session: omc:pr-123
+   Type: review
+   PR: #123 - Add webhook support
+   Branch: feature/webhooks
+   Created: 2 hours ago
+   ```
+
+---
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| Worktree exists | Offer: attach, recreate, or abort |
+| PR not found | Verify URL/number, check permissions |
+| No tmux | Warn and skip session creation |
+| No gh CLI | Error with install instructions |
+
+## Teleport Command
+
+The `omc teleport` command provides a lightweight alternative to full PSM sessions. It creates git worktrees without tmux session management — ideal for quick, isolated development.
+
+### Usage
+
+```bash
+# Create worktree for an issue or PR
+omc teleport #123
+omc teleport owner/repo#123
+omc teleport https://github.com/owner/repo/issues/42
+
+# Create worktree for a feature
+omc teleport my-feature
+
+# List existing worktrees
+omc teleport list
+
+# Remove a worktree
+omc teleport remove issue/my-repo-123
+omc teleport remove --force feat/my-repo-my-feature
+```
+
+### Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--worktree` | Create worktree (default, kept for compatibility) | `true` |
+| `--path <path>` | Custom worktree root directory | `~/Workspace/omc-worktrees/` |
+| `--base <branch>` | Base branch to create from | `main` |
+| `--json` | Output as JSON | `false` |
+
+### Worktree Layout
+
+```
+~/Workspace/omc-worktrees/
+├── issue/
+│   └── my-repo-123/        # Issue worktrees
+├── pr/
+│   └── my-repo-456/        # PR review worktrees
+└── feat/
+    └── my-repo-my-feature/ # Feature worktrees
+```
+
+### PSM vs Teleport
+
+| Feature | PSM | Teleport |
+|---------|-----|----------|
+| Git worktree | Yes | Yes |
+| Tmux session | Yes | No |
+| Claude Code launch | Yes | No |
+| Session registry | Yes | No |
+| Auto-cleanup | Yes | No |
+| Project aliases | Yes | No (uses current repo) |
+
+Use **PSM** for full managed sessions. Use **teleport** for quick worktree creation.
+
+---
+
+## Requirements
+
+Required:
+- `git` - Version control (with worktree support v2.5+)
+- `jq` - JSON parsing
+- `tmux` - Session management (optional, but recommended)
+
+Optional (per provider):
+- `gh` - GitHub CLI (for GitHub workflows)
+- `jira` - Jira CLI (for Jira workflows)
+
+## Initialization
+
+On first run, create default config:
+
+```bash
+mkdir -p ~/.psm/worktrees ~/.psm/logs
+
+# Create default projects.json if not exists
+if [[ ! -f ~/.psm/projects.json ]]; then
+  cat > ~/.psm/projects.json << 'EOF'
+{
+  "aliases": {
+    "omc": {
+      "repo": "Yeachan-Heo/oh-my-claudecode",
+      "local": "~/Workspace/oh-my-claudecode",
+      "default_base": "main"
+    }
+  },
+  "defaults": {
+    "worktree_root": "~/.psm/worktrees",
+    "cleanup_after_days": 14,
+    "auto_cleanup_merged": true
+  }
+}
+EOF
+fi
+
+# Create sessions.json if not exists
+if [[ ! -f ~/.psm/sessions.json ]]; then
+  echo '{"version":1,"sessions":{},"stats":{"total_created":0,"total_cleaned":0}}' > ~/.psm/sessions.json
+fi
+```

package/skills/project-session-manager/lib/config.sh

@@ -0,0 +1,135 @@
+#!/bin/bash
+# PSM Configuration Management
+
+PSM_ROOT="${HOME}/.psm"
+PSM_WORKTREES="${PSM_ROOT}/worktrees"
+PSM_PROJECTS="${PSM_ROOT}/projects.json"
+PSM_SESSIONS="${PSM_ROOT}/sessions.json"
+PSM_LOGS="${PSM_ROOT}/logs"
+
+# Initialize PSM directories and config files
+psm_init() {
+    mkdir -p "$PSM_WORKTREES" "$PSM_LOGS"
+
+    # Create default projects.json if not exists
+    if [[ ! -f "$PSM_PROJECTS" ]]; then
+        cat > "$PSM_PROJECTS" << 'EOF'
+{
+  "aliases": {
+    "omc": {
+      "repo": "Yeachan-Heo/oh-my-claudecode",
+      "local": "~/Workspace/oh-my-claudecode",
+      "default_base": "main"
+    }
+  },
+  "defaults": {
+    "worktree_root": "~/.psm/worktrees",
+    "cleanup_after_days": 14,
+    "auto_cleanup_merged": true
+  }
+}
+EOF
+        echo "Created default projects.json"
+    fi
+
+    # Create sessions.json if not exists
+    if [[ ! -f "$PSM_SESSIONS" ]]; then
+        echo '{"version":1,"sessions":{},"stats":{"total_created":0,"total_cleaned":0}}' > "$PSM_SESSIONS"
+        echo "Created sessions.json"
+    fi
+}
+
+# Get project config by alias
+# Usage: psm_get_project "omc"
+# Returns: repo|local|default_base
+psm_get_project() {
+    local alias="$1"
+    if [[ ! -f "$PSM_PROJECTS" ]]; then
+        return 1
+    fi
+
+    local repo=$(jq -r --arg a "$alias" '.aliases[$a].repo // empty' "$PSM_PROJECTS")
+    local local_path=$(jq -r --arg a "$alias" '.aliases[$a].local // empty' "$PSM_PROJECTS")
+    local default_base=$(jq -r --arg a "$alias" '.aliases[$a].default_base // "main"' "$PSM_PROJECTS")
+
+    local clone_url=$(jq -r --arg a "$alias" '.aliases[$a].clone_url // empty' "$PSM_PROJECTS")
+    if [[ -z "$repo" && -z "$clone_url" ]]; then
+        return 1
+    fi
+
+    # Expand ~ to $HOME
+    local_path="${local_path/#\~/$HOME}"
+
+    echo "${repo}|${local_path}|${default_base}"
+}
+
+# Get provider for a project alias
+# Usage: psm_get_project_provider "mywork"
+# Returns: "github" | "jira" | empty (defaults to github)
+psm_get_project_provider() {
+    local alias="$1"
+    if [[ ! -f "$PSM_PROJECTS" ]]; then
+        echo "github"
+        return
+    fi
+    local provider
+    provider=$(jq -r --arg a "$alias" '.aliases[$a].provider // "github"' "$PSM_PROJECTS")
+    echo "$provider"
+}
+
+# Get Jira project key for alias
+# Usage: psm_get_project_jira_project "mywork"
+# Returns: "MYPROJ" or empty
+psm_get_project_jira_project() {
+    local alias="$1"
+    if [[ ! -f "$PSM_PROJECTS" ]]; then
+        return
+    fi
+    jq -r --arg a "$alias" '.aliases[$a].jira_project // empty' "$PSM_PROJECTS"
+}
+
+# Get explicit clone_url for alias (for non-GitHub repos)
+# Usage: psm_get_project_clone_url "mywork"
+# Returns: URL or empty
+psm_get_project_clone_url() {
+    local alias="$1"
+    if [[ ! -f "$PSM_PROJECTS" ]]; then
+        return
+    fi
+    jq -r --arg a "$alias" '.aliases[$a].clone_url // empty' "$PSM_PROJECTS"
+}
+
+# Get repo field for alias
+# Usage: psm_get_project_repo "mywork"
+# Returns: "owner/repo" or empty
+psm_get_project_repo() {
+    local alias="$1"
+    if [[ ! -f "$PSM_PROJECTS" ]]; then
+        return
+    fi
+    jq -r --arg a "$alias" '.aliases[$a].repo // empty' "$PSM_PROJECTS"
+}
+
+# Add or update project alias
+psm_set_project() {
+    local alias="$1"
+    local repo="$2"
+    local local_path="$3"
+    local default_base="${4:-main}"
+
+    local tmp=$(mktemp)
+    jq --arg a "$alias" --arg r "$repo" --arg l "$local_path" --arg b "$default_base" \
+        '.aliases[$a] = {"repo": $r, "local": $l, "default_base": $b}' \
+        "$PSM_PROJECTS" > "$tmp" && mv "$tmp" "$PSM_PROJECTS"
+}
+
+# Get default worktree root
+psm_get_worktree_root() {
+    local root=$(jq -r '.defaults.worktree_root // "~/.psm/worktrees"' "$PSM_PROJECTS")
+    echo "${root/#\~/$HOME}"
+}
+
+# Get cleanup days setting
+psm_get_cleanup_days() {
+    jq -r '.defaults.cleanup_after_days // 14' "$PSM_PROJECTS"
+}