claude-autopm 1.20.1 → 1.22.0

package/autopm/.claude/scripts/pm/epic-sync/README.md

@@ -0,0 +1,208 @@
+# Epic Sync Modular Scripts
+
+This directory contains the modular implementation of the epic-sync workflow that pushes epics and tasks to GitHub as issues.
+
+## Architecture
+
+The epic-sync process is split into 4 specialized scripts:
+
+1. **create-epic-issue.sh** - Creates the main epic GitHub issue
+2. **create-task-issues.sh** - Creates GitHub issues for all tasks
+3. **update-references.sh** - Renames task files to match GitHub issue numbers
+4. **update-epic-file.sh** - Updates epic.md with real issue numbers
+
+## Orchestration
+
+The **recommended way** to use these scripts is via the orchestration script:
+
+```bash
+# From project root
+bash .claude/scripts/pm/epic-sync.sh <epic_name>
+```
+
+This automatically runs all 4 steps in the correct order.
+
+## Individual Scripts
+
+### 1. create-epic-issue.sh
+
+**Purpose:** Creates the main GitHub issue for the epic
+
+**Input:**
+- Epic name (e.g., `postgresql-connection-module`)
+
+**Output:**
+- GitHub issue number (stdout)
+
+**What it does:**
+- Strips frontmatter from epic.md
+- Counts tasks in epic directory
+- Detects epic type (bug vs feature)
+- Creates GitHub issue with proper labels
+- Returns epic issue number
+
+**Usage:**
+```bash
+epic_number=$(bash .claude/scripts/pm/epic-sync/create-epic-issue.sh "my-feature")
+echo "Epic created: #$epic_number"
+```
+
+### 2. create-task-issues.sh
+
+**Purpose:** Creates GitHub issues for all task files
+
+**Input:**
+- Epic name
+- Epic issue number (from step 1)
+
+**Output:**
+- Path to task mapping file (stdout)
+
+**What it does:**
+- Finds all `[0-9]*.md` files in epic directory
+- Strips frontmatter from each task
+- Creates GitHub issue for each task
+- Labels with `task,epic:<epic_name>`
+- Saves mapping of old_name -> issue_number to `.task-mapping.txt`
+- **Mapping file is saved in epic directory** (persistent, not in /tmp)
+
+**Usage:**
+```bash
+mapping=$(bash .claude/scripts/pm/epic-sync/create-task-issues.sh "my-feature" "42")
+echo "Mapping saved: $mapping"
+```
+
+**Important:** The mapping file is saved as `.claude/epics/<epic>/.task-mapping.txt` for use in subsequent steps.
+
+### 3. update-references.sh
+
+**Purpose:** Renames task files to GitHub issue numbers and updates frontmatter
+
+**Input:**
+- Epic name
+- Path to task mapping file (from step 2)
+
+**Output:**
+- None (modifies files in place)
+
+**What it does:**
+- Reads `.task-mapping.txt` file
+- For each mapping (e.g., `001 -> 2`):
+  - Renames `001.md` to `2.md`
+  - Updates frontmatter with GitHub URL
+  - Updates frontmatter timestamp
+- Creates backups during rename (removed on success)
+
+**Usage:**
+```bash
+bash .claude/scripts/pm/epic-sync/update-references.sh "my-feature" ".claude/epics/my-feature/.task-mapping.txt"
+```
+
+**Before:**
+```
+.claude/epics/my-feature/
+├── 001.md (github: [Will be updated...])
+├── 002.md (github: [Will be updated...])
+```
+
+**After:**
+```
+.claude/epics/my-feature/
+├── 2.md (github: https://github.com/user/repo/issues/2)
+├── 3.md (github: https://github.com/user/repo/issues/3)
+```
+
+### 4. update-epic-file.sh
+
+**Purpose:** Updates epic.md with GitHub URL and real task references
+
+**Input:**
+- Epic name
+- Epic issue number
+
+**Output:**
+- None (modifies epic.md in place)
+
+**What it does:**
+- Updates epic.md frontmatter with GitHub URL
+- Updates timestamp
+- Reads `.task-mapping.txt`
+- Replaces task references (e.g., `- [ ] 001` → `- [ ] #2`)
+- Creates backup during update (removed on success)
+
+**Usage:**
+```bash
+bash .claude/scripts/pm/epic-sync/update-epic-file.sh "my-feature" "42"
+```
+
+## File Persistence Fix
+
+**IMPORTANT:** The task mapping file is saved to a **persistent location**:
+
+```
+.claude/epics/<epic_name>/.task-mapping.txt
+```
+
+This fixes the bug where the mapping file was being saved to `/tmp` and deleted before subsequent scripts could use it.
+
+## Error Handling
+
+All scripts use `set -euo pipefail` for robust error handling:
+- `-e`: Exit on error
+- `-u`: Error on undefined variables
+- `-o pipefail`: Fail if any command in pipeline fails
+
+## Testing
+
+Test individual scripts:
+
+```bash
+# Create a test epic first
+mkdir -p .claude/epics/test-epic
+echo "---\ntitle: Test\n---\n# Test Epic" > .claude/epics/test-epic/epic.md
+echo "---\ntitle: Task 1\n---\n# Task 1" > .claude/epics/test-epic/001.md
+echo "---\ntitle: Task 2\n---\n# Task 2" > .claude/epics/test-epic/002.md
+
+# Run orchestration script
+bash .claude/scripts/pm/epic-sync.sh test-epic
+
+# Verify files were renamed
+ls .claude/epics/test-epic/
+# Should show: epic.md, <issue_number>.md files
+```
+
+## Dependencies
+
+- **bash** >= 4.0
+- **gh** (GitHub CLI) - authenticated
+- **awk** - for frontmatter processing
+- **find** - for file discovery
+- **grep** - for pattern matching
+
+## Common Issues
+
+### "Template repository detected"
+```bash
+# Fix: Set correct remote
+git remote set-url origin https://github.com/YOUR_USERNAME/YOUR_REPO.git
+```
+
+### "GitHub CLI not authenticated"
+```bash
+gh auth login
+```
+
+### "Mapping file not found"
+- Ensure step 2 completed successfully
+- Check `.claude/epics/<epic>/.task-mapping.txt` exists
+
+### "Task files still numbered 001, 002..."
+- Step 3 (update-references.sh) may not have run
+- Check for errors in step 2 output
+- Run orchestration script instead of individual scripts
+
+## Related Files
+
+- **/.claude/commands/pm/epic-sync.md** - Command documentation
+- **/.claude/commands/pm/issue-start.md** - Works with renamed files
+- **/.claude/commands/pm/issue-analyze.md** - Expects GitHub issue numbers

package/autopm/.claude/scripts/pm/epic-sync/create-epic-issue.sh

@@ -1,201 +1,77 @@
 #!/bin/bash
-# Create Epic Issue Script
-# Extracts content from epic.md, processes it, and creates GitHub issue
+# Create Epic Issue
+# Creates the main GitHub issue for an epic with proper labels and stats
 
 set -euo pipefail
 
-# Load libraries
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "${SCRIPT_DIR}/../../lib/logging-utils.sh"
-source "${SCRIPT_DIR}/../../lib/github-utils.sh"
-source "${SCRIPT_DIR}/../../lib/frontmatter-utils.sh"
-source "${SCRIPT_DIR}/../../lib/validation-utils.sh"
-
-# Script configuration
-readonly EPIC_NAME="${1:-}"
-
-# Main function
-main() {
-    print_banner "Epic Issue Creator" "1.0.0"
-
-    # Validate inputs
-    log_info "Validating epic: $EPIC_NAME"
-    validate_epic_name "$EPIC_NAME" || exit 1
-    validate_epic_structure "$EPIC_NAME" || exit 1
-
-    # Check GitHub authentication and repo protection
-    validate_github_auth || exit 1
-    check_repo_protection || exit 1
-
-    local epic_file=".claude/epics/$EPIC_NAME/epic.md"
-    local temp_dir="/tmp/epic-sync-$$"
-
-    log_info "Creating temporary workspace: $temp_dir"
-    mkdir -p "$temp_dir"
-
-    # Ensure cleanup on exit
-    trap "rm -rf '$temp_dir'" EXIT
-
-    # Process epic content
-    with_error_handling "Strip frontmatter from epic" \
-        strip_frontmatter "$epic_file" "$temp_dir/epic-body-raw.md"
-
-    with_error_handling "Process epic content and stats" \
-        process_epic_content "$temp_dir/epic-body-raw.md" "$temp_dir/epic-body.md"
-
-    with_error_handling "Determine epic type" \
-        epic_type=$(determine_epic_type "$temp_dir/epic-body.md")
-
-    with_error_handling "Create GitHub epic issue" \
-        issue_number=$(create_epic_github_issue "$temp_dir/epic-body.md" "$epic_type")
-
-    # Output result
-    local repo_info
-    repo_info=$(get_repo_info)
-    local repo_name
-    repo_name=$(echo "$repo_info" | grep -o '"nameWithOwner":"[^"]*"' | cut -d'"' -f4)
-
-    log_success "Epic issue created successfully!"
-    echo "Epic Issue: #${issue_number}"
-    echo "URL: https://github.com/${repo_name}/issues/${issue_number}"
-    echo "$issue_number"  # For script consumption
-}
-
-# Process epic content and replace Tasks Created section with Stats
-process_epic_content() {
-    local input_file="$1"
-    local output_file="$2"
-
-    log_function_entry "process_epic_content" "$input_file" "$output_file"
-
-    # Count tasks in epic directory
-    local epic_dir=".claude/epics/$EPIC_NAME"
-    local total_tasks parallel_tasks sequential_tasks total_effort
-
-    total_tasks=$(find "$epic_dir" -name '[0-9][0-9][0-9].md' -type f | wc -l)
-    parallel_tasks=$(grep -l '^parallel: true' "$epic_dir"/[0-9][0-9][0-9].md 2>/dev/null | wc -l || echo 0)
-    sequential_tasks=$((total_tasks - parallel_tasks))
-
-    # Try to calculate total effort from task files
-    total_effort=$(calculate_total_effort "$epic_dir")
-
-    # Process content with awk to replace Tasks Created section
-    awk -v total_tasks="$total_tasks" \
-        -v parallel_tasks="$parallel_tasks" \
-        -v sequential_tasks="$sequential_tasks" \
-        -v total_effort="$total_effort" '
-        /^## Tasks Created/ {
-            in_tasks=1
-            next
-        }
-        /^## / && in_tasks {
-            in_tasks=0
-            # Add Stats section
-            print "## Stats"
-            print ""
-            print "Total tasks: " total_tasks
-            print "Parallel tasks: " parallel_tasks " (can be worked on simultaneously)"
-            print "Sequential tasks: " sequential_tasks " (have dependencies)"
-            if (total_effort) print "Estimated total effort: " total_effort " hours"
-            print ""
-        }
-        /^Total tasks:/ && in_tasks { next }
-        /^Parallel tasks:/ && in_tasks { next }
-        /^Sequential tasks:/ && in_tasks { next }
-        /^Estimated total effort:/ && in_tasks { next }
-        !in_tasks { print }
-        END {
-            # If we were still in tasks section at EOF, add stats
-            if (in_tasks) {
-                print "## Stats"
-                print ""
-                print "Total tasks: " total_tasks
-                print "Parallel tasks: " parallel_tasks " (can be worked on simultaneously)"
-                print "Sequential tasks: " sequential_tasks " (have dependencies)"
-                if (total_effort) print "Estimated total effort: " total_effort " hours"
-            }
-        }
-    ' "$input_file" > "$output_file"
-
-    log_debug "Processed epic content with stats: $total_tasks total, $parallel_tasks parallel"
-    log_function_exit "process_epic_content"
-}
-
-# Calculate total effort from task files
-calculate_total_effort() {
-    local epic_dir="$1"
-    local total_effort=0
-
-    for task_file in "$epic_dir"/[0-9][0-9][0-9].md; do
-        [[ -f "$task_file" ]] || continue
-
-        local effort
-        effort=$(get_frontmatter_field "$task_file" "effort" 2>/dev/null || echo "")
-
-        if [[ "$effort" =~ ^[0-9]+$ ]]; then
-            total_effort=$((total_effort + effort))
-        fi
-    done
-
-    if [[ "$total_effort" -gt 0 ]]; then
-        echo "$total_effort"
-    fi
-}
-
-# Determine epic type from content
-determine_epic_type() {
-    local content_file="$1"
-
-    log_function_entry "determine_epic_type" "$content_file"
-
-    if grep -qi "bug\|fix\|issue\|problem\|error\|hotfix\|patch" "$content_file"; then
-        echo "bug"
-    else
-        echo "feature"
-    fi
-
-    log_function_exit "determine_epic_type"
-}
-
-# Create GitHub epic issue with proper labels
-create_epic_github_issue() {
-    local body_file="$1"
-    local epic_type="$2"
-
-    log_function_entry "create_epic_github_issue" "$body_file" "$epic_type"
-
-    local title="Epic: $EPIC_NAME"
-    local labels="epic,epic:$EPIC_NAME,$epic_type"
-
-    local issue_number
-    issue_number=$(create_github_issue "$title" "$body_file" "$labels")
-
-    log_function_exit "create_epic_github_issue" 0
-    echo "$issue_number"
-}
-
-# Error handling
-handle_error() {
-    local exit_code=$?
-    log_error "Script failed with exit code: $exit_code"
-    log_error "Epic issue creation failed for: $EPIC_NAME"
-    exit "$exit_code"
-}
-
-# Set up error handling
-trap handle_error ERR
-
-# Validate arguments
-if [[ $# -ne 1 ]]; then
+EPIC_NAME="${1:-}"
+
+if [[ -z "$EPIC_NAME" ]]; then
+    echo "❌ Error: Epic name required"
     echo "Usage: $0 <epic_name>"
-    echo ""
-    echo "Creates a GitHub issue for the specified epic."
-    echo ""
-    echo "Example:"
-    echo "  $0 authentication"
-    echo ""
     exit 1
 fi
 
-# Run main function
-main "$@"
+# Source utilities if they exist
+if [[ -f "$SCRIPT_DIR/../../lib/github-utils.sh" ]]; then
+    source "$SCRIPT_DIR/../../lib/github-utils.sh"
+fi
+
+EPIC_FILE=".claude/epics/$EPIC_NAME/epic.md"
+
+if [[ ! -f "$EPIC_FILE" ]]; then
+    echo "❌ Error: Epic file not found: $EPIC_FILE"
+    exit 1
+fi
+
+# Check GitHub CLI
+if ! command -v gh &> /dev/null; then
+    echo "❌ Error: GitHub CLI (gh) not installed"
+    exit 1
+fi
+
+# Check authentication
+if ! gh auth status &> /dev/null; then
+    echo "❌ Error: GitHub CLI not authenticated. Run: gh auth login"
+    exit 1
+fi
+
+# Strip frontmatter and get content
+epic_content=$(awk 'BEGIN{p=0} /^---$/{p++; next} p==2{print}' "$EPIC_FILE")
+
+# Count tasks
+task_count=$(find ".claude/epics/$EPIC_NAME" -name "[0-9]*.md" -type f 2>/dev/null | wc -l)
+
+# Detect epic type (bug vs feature)
+if echo "$epic_content" | grep -qi "bug\|fix\|error\|issue"; then
+    labels="epic,bug"
+else
+    labels="epic,feature"
+fi
+
+# Create issue
+echo "📝 Creating epic issue for: $EPIC_NAME"
+echo "   Tasks: $task_count"
+echo "   Labels: $labels"
+
+# Create the issue
+epic_number=$(gh issue create \
+    --title "Epic: $EPIC_NAME" \
+    --body "$epic_content
+
+---
+**Epic Statistics:**
+- Tasks: $task_count
+- Status: Planning
+- Created: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+" \
+    --label "$labels" \
+    2>&1 | grep -oP '(?<=#)[0-9]+' | head -1)
+
+if [[ -z "$epic_number" ]]; then
+    echo "❌ Error: Failed to create epic issue"
+    exit 1
+fi
+
+echo "$epic_number"