gh-setup

Setup / Update GitHub Workflow

Analyze the current repository and generate customized GitHub workflow configuration. If gh-workflow is already configured, detect the existing version and offer to update it with new commands and features while preserving customizations.

Tool Usage: This workflow uses the AskUserQuestion tool extensively to gather preferences, confirm detected conventions, and approve generated configurations.

Contract

GOAL: Project-specific workflow configuration generated, applied, or updated based on detected tech stack and conventions. Testable: .claude/CLAUDE.md contains workflow section with correct branch/commit conventions, all current gh-workflow commands listed, and version marker reflecting current plugin version ($PLUGIN_VERSION from plugin.json).

CONSTRAINTS:

• Never overwrite existing CLAUDE.md - merge or append the workflow section
• Always create backup before modifying existing files
• Always confirm detected patterns with user before applying

FORMAT: Generated CLAUDE.md workflow section with branching strategy, commit conventions, commands table, and tech-stack-specific quality checklist.

FAILURE CONDITIONS (output is unacceptable if any apply):

• Existing CLAUDE.md overwritten without backup
• Wrong tech stack detected (e.g., Python project identified as Go)
• Configuration applied without user preview and approval
• Generated conventions conflict with existing project conventions
• Existing customizations lost during update (branch naming, labels, checklists)

Purpose

This command analyzes your codebase and generates:

1. A .claude/CLAUDE.md section with GitHub workflow documentation
2. Optionally, local command overrides for project-specific customizations
3. Recommendations for labels to create

Phase 0: Installation Detection

Before performing any analysis, read the plugin version and detect whether gh-workflow is already configured.

1. Read plugin version (single source of truth):

   # Try known plugin locations (marketplace source, then cache, then local dev)
   PLUGIN_VERSION=""
   # Marketplace source (unversioned, always matches installed version)
   for MARKET in "$HOME/.claude/plugins/marketplaces"/*/plugins/gh-workflow/.claude-plugin/plugin.json; do
     [ -f "$MARKET" ] && { PLUGIN_VERSION=$(jq -r '.version' "$MARKET"); break; }
   done
   # Cache (versioned dirs — take the latest)
   if [ -z "$PLUGIN_VERSION" ]; then
     LATEST=$(ls -d "$HOME/.claude/plugins/cache"/*/gh-workflow/*/.claude-plugin/plugin.json 2>/dev/null | sort -V | tail -1)
     [ -n "$LATEST" ] && PLUGIN_VERSION=$(jq -r '.version' "$LATEST")
   fi
   # Local development (running from marketplace repo)
   [ -z "$PLUGIN_VERSION" ] && [ -f "plugins/gh-workflow/.claude-plugin/plugin.json" ] && \
     PLUGIN_VERSION=$(jq -r '.version' "plugins/gh-workflow/.claude-plugin/plugin.json")
   [ -z "$PLUGIN_VERSION" ] && PLUGIN_VERSION="unknown"
   echo "gh-workflow version: $PLUGIN_VERSION"