claude-autopm 1.20.1 → 1.21.0

package/autopm/.claude/commands/pm/epic-sync.md

@@ -11,6 +11,21 @@ Push epic and tasks to GitHub as issues using modular scripts.
 /pm:epic-sync <feature_name>
 ```
 
+## Quick Start
+
+The simplest way to sync an epic to GitHub:
+
+```bash
+# Full automated sync (recommended)
+bash .claude/scripts/pm/epic-sync.sh "$ARGUMENTS"
+```
+
+This orchestration script automatically runs all 4 steps:
+1. Creates epic issue
+2. Creates task issues
+3. Renames files to issue numbers
+4. Updates all references
+
 ## Quick Check
 
 ```bash
@@ -32,7 +47,14 @@ If no tasks found: "❌ No tasks to sync. Run: /pm:epic-decompose $ARGUMENTS"
 
 ## Instructions
 
-The epic sync process is now modularized into 4 specialized scripts that handle different aspects of the synchronization. Each script is designed for reliability, testability, and maintainability.
+**⚡ Quick Command:**
+```bash
+bash .claude/scripts/pm/epic-sync.sh "$ARGUMENTS"
+```
+
+The epic sync process is modularized into 4 specialized scripts that handle different aspects of the synchronization. Each script is designed for reliability, testability, and maintainability.
+
+The orchestration script (`.claude/scripts/pm/epic-sync.sh`) automatically runs all 4 steps in sequence. The individual scripts are documented below for reference and debugging.
 
 ### Processing Mode Detection
 
@@ -158,13 +180,24 @@ echo "✅ Created branch: epic/$ARGUMENTS"
 
 ## Complete Workflow Examples
 
-### Single Epic Workflow
+### Single Epic Workflow (Automated - Recommended)
+
+The **easiest way** is to use the orchestration script that handles everything:
+
+```bash
+# One command does it all!
+bash .claude/scripts/pm/epic-sync.sh "$ARGUMENTS"
+```
+
+This automatically runs all 4 steps and provides a complete summary.
+
+### Single Epic Workflow (Manual Steps)
 
-Here's the complete modular epic sync workflow for a single epic:
+If you need to run steps individually for debugging:
 
 ```bash
 #!/bin/bash
-# Complete epic sync using modular scripts
+# Complete epic sync using modular scripts (manual)
 
 EPIC_NAME="$ARGUMENTS"
 

package/autopm/.claude/rules/framework-path-rules.md

@@ -0,0 +1,180 @@
+# Framework Path Rules
+
+## Critical Path Convention
+
+**NEVER** hardcode the `autopm/` directory path in framework files. The `autopm/` directory only exists during development and is **NOT** present after installation in user projects.
+
+## The Problem
+
+During installation, files from `autopm/.claude/` are copied to user projects as `.claude/`. Any references to `autopm/.claude/` or `autopm/scripts/` will be broken after installation.
+
+```
+❌ WRONG (Development structure):
+autopm/
+├── .claude/
+│   ├── commands/
+│   ├── scripts/
+│   └── agents/
+
+✅ CORRECT (After installation):
+user-project/
+├── .claude/
+│   ├── commands/
+│   ├── scripts/
+│   └── agents/
+```
+
+## Rules
+
+### 1. Use Relative Paths from Project Root
+
+All paths in framework files must be relative to the **user's project root** (where `.claude/` will exist after installation).
+
+**✅ CORRECT:**
+```bash
+bash .claude/scripts/pm/epic-sync/create-epic-issue.sh "$EPIC_NAME"
+node .claude/lib/commands/pm/prdStatus.js
+source .claude/scripts/lib/github-utils.sh
+```
+
+**❌ WRONG:**
+```bash
+bash autopm/.claude/scripts/pm/epic-sync/create-epic-issue.sh "$EPIC_NAME"
+node autopm/.claude/lib/commands/pm/prdStatus.js
+source autopm/.claude/scripts/lib/github-utils.sh
+```
+
+### 2. Exception: Comments and Documentation References
+
+It's acceptable to reference `autopm/` in:
+- Code comments explaining migration history
+- Documentation describing the development structure
+- Git commit messages
+
+**✅ ACCEPTABLE:**
+```javascript
+/**
+ * Migrated from autopm/.claude/scripts/azure/validate.sh to Node.js
+ */
+```
+
+**✅ ACCEPTABLE:**
+```markdown
+## Development Structure
+During development, framework files are in `autopm/.claude/`, but after
+installation they are copied to the user project's `.claude/` directory.
+```
+
+### 3. Files That Must Follow These Rules
+
+- **Commands** (`autopm/.claude/commands/**/*.md`)
+- **Scripts** (`autopm/.claude/scripts/**/*.sh`, `**/*.js`)
+- **Agents** (`autopm/.claude/agents/**/*.md`)
+- **Rules** (`autopm/.claude/rules/**/*.md`)
+- **Templates** (`autopm/.claude/templates/**/*`)
+
+### 4. Environment Variables
+
+If you need to reference the framework location dynamically, use environment variables that work in both contexts:
+
+**✅ CORRECT:**
+```bash
+CLAUDE_DIR="${CLAUDE_DIR:-.claude}"
+bash "${CLAUDE_DIR}/scripts/pm/epic-sync/create-epic-issue.sh"
+```
+
+This allows:
+- Development: `CLAUDE_DIR=autopm/.claude`
+- Production: `CLAUDE_DIR=.claude` (default)
+
+## Validation
+
+### Pre-Commit Hook
+
+A pre-commit hook validates all framework files before commit:
+
+```bash
+# Checks for hardcoded autopm/ paths (excluding comments)
+grep -r "bash autopm" autopm/.claude --include="*.md" --include="*.sh"
+grep -r "node autopm" autopm/.claude --include="*.md" --include="*.sh"
+grep -r "source autopm" autopm/.claude --include="*.md" --include="*.sh"
+```
+
+### Manual Check
+
+Before committing changes to framework files:
+
+```bash
+# Run validation
+npm run validate:paths
+
+# Or manually
+./scripts/validate-framework-paths.sh
+```
+
+## Common Mistakes
+
+### Mistake 1: Copy-Paste from Development Environment
+
+```bash
+# ❌ Copying terminal command that worked in development
+bash autopm/.claude/scripts/pm/epic-sync/create-epic-issue.sh "feature-name"
+
+# ✅ Use project-relative path
+bash .claude/scripts/pm/epic-sync/create-epic-issue.sh "feature-name"
+```
+
+### Mistake 2: Documentation Examples
+
+```markdown
+❌ WRONG:
+To run the script:
+`bash autopm/.claude/scripts/pm/issue-sync/preflight-validation.sh`
+
+✅ CORRECT:
+To run the script:
+`bash .claude/scripts/pm/issue-sync/preflight-validation.sh`
+```
+
+### Mistake 3: Relative Imports in Scripts
+
+```bash
+# ❌ WRONG - hardcoded framework path
+source autopm/.claude/scripts/lib/github-utils.sh
+
+# ✅ CORRECT - relative to project root
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../lib/github-utils.sh"
+
+# ✅ ALSO CORRECT - explicit project root
+source .claude/scripts/lib/github-utils.sh
+```
+
+## Enforcement
+
+This rule is enforced by:
+
+1. **Pre-commit hook** - Blocks commits with hardcoded `autopm/` paths
+2. **CI/CD validation** - GitHub Actions check on every PR
+3. **Installation tests** - Verify all paths work post-installation
+4. **Code review** - Reviewers check for path correctness
+
+## Quick Reference
+
+| Context | Use | Don't Use |
+|---------|-----|-----------|
+| Shell scripts | `.claude/scripts/` | `autopm/.claude/scripts/` |
+| Node.js scripts | `.claude/lib/` | `autopm/.claude/lib/` |
+| Command files | `.claude/commands/` | `autopm/.claude/commands/` |
+| Documentation | `.claude/agents/` | `autopm/.claude/agents/` |
+| Comments | `autopm/` ✅ OK | N/A |
+
+## Related Rules
+
+- `/rules/naming-conventions.md` - File and directory naming
+- `/rules/development-workflow.md` - Development best practices
+- `/rules/golden-rules.md` - Core framework principles
+
+---
+
+**Remember:** If a user installs this framework, the `autopm/` directory will not exist in their project. All paths must work from their project root where `.claude/` is located.

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