claude-autopm 1.20.0 → 1.21.0

package/autopm/.claude/examples/mcp-servers.example.json

@@ -37,7 +37,7 @@
     },
     "react-docs": {
       "type": "shared",
-      "agents": ["react-frontend-engineer", "playwright-test-engineer"],
+      "agents": ["react-frontend-engineer", "frontend-testing-engineer"],
       "sources": ["context7"],
       "filters": ["react", "nextjs", "typescript", "tailwind", "vite"],
       "maxSize": "75MB",
@@ -64,7 +64,7 @@
     },
     "testing-context": {
       "type": "shared",
-      "agents": ["playwright-test-engineer", "test-runner"],
+      "agents": ["frontend-testing-engineer", "test-runner"],
       "sources": ["context7", "playwright-mcp"],
       "filters": ["playwright", "testing", "e2e"],
       "maxSize": "50MB",

package/autopm/.claude/hooks/docker-first-enforcement.sh

@@ -89,7 +89,7 @@ check_docker_files() {
     if [[ ${#missing_files[@]} -gt 0 ]]; then
         echo ""
         echo "📝 MISSING FILES: ${missing_files[*]}"
-        echo "💡 TIP: Use docker-expert agent to create Docker files:"
+        echo "💡 TIP: Use docker-containerization-expert agent to create Docker files:"
         echo "   Task: Create Docker development environment for this project"
         echo ""
     fi

package/autopm/.claude/mcp/playwright-mcp.md

@@ -74,7 +74,7 @@ autopm mcp sync
 ### Integration with Agents
 
 Used extensively with:
-- `e2e-test-engineer` - For E2E test creation
+- `frontend-testing-engineer` - For E2E test creation
 - `react-frontend-engineer` - For UI testing
 - `ux-design-expert` - For visual regression
 
@@ -309,4 +309,4 @@ npx playwright show-trace trace.zip
 
 - [Playwright Documentation](https://playwright.dev)
 - [MCP Browser Control](https://modelcontextprotocol.org/browser)
-- [E2E Test Engineer Agent](../agents/frameworks/e2e-test-engineer.md)
+- [E2E Test Engineer Agent](../agents/frameworks/frontend-testing-engineer.md)

package/autopm/.claude/rules/agent-coordination.md

@@ -20,10 +20,10 @@ Comprehensive coordination system for multi-agent collaboration in ClaudeAutoPM.
 | python-backend-expert | Backend APIs | `*.py`, `requirements.txt`, `pyproject.toml` | react-ui-expert, kubernetes, cloud architects | framework: fastapi/flask/django |
 | react-ui-expert | Frontend UI | `*.tsx`, `*.jsx`, `*.css`, `package.json` | python-backend, e2e-test | framework: mui/chakra/antd/bootstrap |
 | e2e-test-engineer | E2E Tests | `tests/`, `*.spec.ts`, `playwright.config.ts` | react-ui, python-backend | tool: playwright/cypress |
-| multi-cloud-architect | Cloud Infrastructure | `terraform/`, `*.tf`, cloud configs | kubernetes, docker | provider: aws/azure/gcp |
+| terraform-infrastructure-expert | Cloud Infrastructure | `terraform/`, `*.tf`, cloud configs | kubernetes, docker, cloud architects | provider: aws/azure/gcp |
 | kubernetes-orchestrator | K8s Manifests | `k8s/`, `charts/`, `*.yaml` | cloud architects, github-ops | tool: helm/kustomize |
 | docker-containerization-expert | Containers | `Dockerfile*`, `docker-compose*.yml` | All deployment agents | strategy: multi-stage/compose |
-| database-architect | Database | `migrations/`, `*.sql`, schema files | python-backend | engine: postgresql/mysql/mongodb |
+| postgresql-expert / mongodb-expert | Database | `migrations/`, `*.sql`, schema files | python-backend-engineer | engine: postgresql/mongodb/redis |
 | github-operations-specialist | CI/CD | `.github/`, `*.yml`, `*.yaml` | All agents | platform: actions/azure-devops |
 | mcp-context-manager | Context | `.claude/mcp-servers.json`, context pools | All agents | pool: shared/isolated |
 
@@ -32,7 +32,7 @@ Comprehensive coordination system for multi-agent collaboration in ClaudeAutoPM.
 | Agent | Use Case | Replaces |
 |-------|----------|----------|
 | azure-devops-specialist | Azure DevOps specific | Part of github-operations |
-| playwright-mcp-frontend-tester | MCP browser control | Enhanced e2e-test |
+| e2e-test-engineer | E2E testing with Playwright/Cypress | Support role |
 | code-analyzer | Read-only analysis | Support role |
 | file-analyzer | Log/file summarization | Support role |
 | test-runner | Test execution only | Support role |
@@ -103,7 +103,7 @@ Notes: Added rate limiting middleware
 
 ```yaml
 backend-context:
-  agents: [python-backend-expert, database-architect]
+  agents: [python-backend-expert, postgresql-expert, mongodb-expert]
   sources: [context7, context7]
   filters: [python, fastapi, flask, django, sqlalchemy, databases]
   persistence: true
@@ -115,7 +115,7 @@ frontend-context:
   persistence: true
 
 infrastructure-context:
-  agents: [multi-cloud-architect, kubernetes-orchestrator, docker-containerization-expert]
+  agents: [terraform-infrastructure-expert, kubernetes-orchestrator, docker-containerization-expert]
   sources: [context7, terraform-registry]
   filters: [terraform, kubernetes, docker, cloud-providers]
   persistence: true
@@ -159,7 +159,7 @@ Stream B: Frontend Development
   Priority: P1
 
 Stream C: Infrastructure
-  Agent: multi-cloud-architect
+  Agent: terraform-infrastructure-expert
   Parameters:
     provider: aws
     iac: terraform
@@ -243,7 +243,7 @@ graph LR
   B -->|UI Ready| C[e2e-test-engineer]
   C -->|Tests Pass| D[github-operations-specialist]
   D -->|CI/CD Ready| E[kubernetes-orchestrator]
-  E -->|Deployment Config| F[multi-cloud-architect]
+  E -->|Deployment Config| F[terraform-infrastructure-expert]
   F -->|Infrastructure| G[Production]
 ```
 
@@ -261,7 +261,7 @@ graph LR
 
 ```mermaid
 graph LR
-  A[multi-cloud-architect] -->|New Infrastructure| B[docker-containerization-expert]
+  A[terraform-infrastructure-expert] -->|New Infrastructure| B[docker-containerization-expert]
   B -->|Updated Images| C[kubernetes-orchestrator]
   C -->|Manifests Ready| D[github-operations-specialist]
   D -->|Blue-Green Deploy| E[Production]
@@ -325,11 +325,11 @@ git commit -m "Multiple changes"
 
 | Scenario | Priority | Lead Agent | Support Agents | SLA |
 |----------|----------|------------|----------------|-----|
-| Production Down | P0 | kubernetes-orchestrator | multi-cloud, python-backend | 15 min |
+| Production Down | P0 | kubernetes-orchestrator | terraform-infrastructure-expert, python-backend | 15 min |
 | Security Vulnerability | P0 | code-analyzer | python-backend, github-ops | 30 min |
-| Data Loss Risk | P0 | database-architect | multi-cloud, kubernetes | 15 min |
+| Data Loss Risk | P0 | postgresql-expert | terraform-infrastructure-expert, kubernetes | 15 min |
 | Failed Deployment | P1 | github-operations-specialist | kubernetes-orchestrator | 1 hour |
-| Performance Degradation | P1 | python-backend-expert | database-architect, multi-cloud | 2 hours |
+| Performance Degradation | P1 | python-backend-expert | postgresql-expert, terraform-infrastructure-expert | 2 hours |
 | Test Failures | P2 | e2e-test-engineer | react-ui, python-backend | 4 hours |
 | Feature Development | P3 | Varies by stream | Full stack team | 1-5 days |
 | Technical Debt | P4 | code-analyzer | All relevant agents | Best effort |
@@ -338,13 +338,13 @@ git commit -m "Multiple changes"
 
 ### Never Modify Without Coordination
 
-- **Production configurations** - Requires multi-cloud-architect + kubernetes-orchestrator
+- **Production configurations** - Requires terraform-infrastructure-expert + kubernetes-orchestrator
 - **Security settings** - Requires security review + python-backend-expert
 - **API contracts** - Requires python-backend + react-ui agreement
-- **Database schemas** - Requires database-architect + python-backend
+- **Database schemas** - Requires postgresql-expert + python-backend
 - **Authentication flows** - Requires security review + full stack team
 - **Payment processing** - Requires security + compliance review
-- **User data handling** - Requires privacy review + database-architect
+- **User data handling** - Requires privacy review + postgresql-expert
 
 ### Safe for Independent Work
 
@@ -405,31 +405,31 @@ git commit -m "chore: Sync checkpoint"
 ### System Down
 
 1. **kubernetes-orchestrator** takes incident command
-2. **multi-cloud-architect** checks infrastructure health
+2. **terraform-infrastructure-expert** checks infrastructure health
 3. **python-backend-expert** validates application state
-4. **database-architect** verifies data integrity
+4. **postgresql-expert** verifies data integrity
 5. **github-operations-specialist** prepares rollback if needed
 
 ### Security Breach
 
 1. **code-analyzer** identifies scope and entry point
-2. **multi-cloud-architect** isolates affected resources
+2. **terraform-infrastructure-expert** isolates affected resources
 3. **python-backend-expert** patches vulnerability
-4. **database-architect** audits data access
+4. **postgresql-expert** audits data access
 5. **github-operations-specialist** deploys emergency fix
 
 ### Performance Crisis
 
 1. **python-backend-expert** profiles application bottlenecks
-2. **database-architect** analyzes and optimizes queries
+2. **postgresql-expert** analyzes and optimizes queries
 3. **docker-containerization-expert** optimizes container resources
 4. **kubernetes-orchestrator** scales resources horizontally
-5. **multi-cloud-architect** provisions additional infrastructure
+5. **terraform-infrastructure-expert** provisions additional infrastructure
 
 ### Data Corruption
 
-1. **database-architect** stops writes immediately
-2. **multi-cloud-architect** initiates backup restoration
+1. **postgresql-expert** stops writes immediately
+2. **terraform-infrastructure-expert** initiates backup restoration
 3. **kubernetes-orchestrator** redirects traffic to healthy replicas
 4. **python-backend-expert** validates data integrity checks
 5. **e2e-test-engineer** runs full regression suite
@@ -444,11 +444,13 @@ git commit -m "chore: Sync checkpoint"
 | flask-backend-engineer | python-backend-expert | framework: flask |
 | mui-react-expert | react-ui-expert | framework: mui |
 | chakra-ui-expert | react-ui-expert | framework: chakra |
+| antd-react-expert | react-ui-expert | framework: antd |
+| bootstrap-ui-expert | react-ui-expert | framework: bootstrap |
 | docker-expert | docker-containerization-expert | focus: dockerfile |
 | docker-compose-expert | docker-containerization-expert | focus: compose |
-| aws-cloud-architect | multi-cloud-architect | provider: aws |
-| gcp-cloud-architect | multi-cloud-architect | provider: gcp |
+| docker-development-orchestrator | docker-containerization-expert | focus: development |
 | playwright-test-engineer | e2e-test-engineer | tool: playwright |
+| playwright-mcp-frontend-tester | e2e-test-engineer | browser_control: mcp-enhanced |
 
 ### Backward Compatibility
 

package/autopm/.claude/rules/docker-first-development.md

@@ -43,7 +43,7 @@ project/
 ```bash
 # 1. Check if Docker files exist
 if [ ! -f "Dockerfile" ]; then
-  Use docker-expert agent to create Dockerfile
+  Use docker-containerization-expert agent to create Dockerfile
 fi
 
 # 2. Build development image

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/rules/infrastructure-pipeline.md

@@ -23,7 +23,7 @@
 **Sequence**:
 
 ```
-1. docker-expert → Optimize Dockerfile
+1. docker-containerization-expert → Optimize Dockerfile
 2. Security scan with Trivy/Snyk
 3. Build multi-stage image
 4. test-runner → Test container functionality

package/autopm/.claude/rules/ui-development-standards.md

@@ -6,7 +6,7 @@
 
 ### 1. FRAMEWORK DECISION MATRIX
 
-**Bootstrap** - Use `bootstrap-ui-expert`:
+**Bootstrap** - Use `react-ui-expert` (framework=bootstrap):
 
 - Rapid prototyping and MVP development
 - Component-heavy applications (dashboards, admin panels)

package/autopm/.claude/rules/visual-testing.md

@@ -179,8 +179,8 @@ describe('Accessibility', () => {
 
 ### Required Agents for Visual Testing
 
-- **playwright-test-engineer**: Visual regression tests
-- **playwright-mcp-frontend-tester**: Browser automation
+- **frontend-testing-engineer**: Visual regression tests
+- **frontend-testing-engineer**: Browser automation
 - **react-frontend-engineer**: Component development
 - **code-analyzer**: Review UI code quality
 
@@ -188,7 +188,7 @@ describe('Accessibility', () => {
 
 ```
 1. Implement UI change following TDD
-2. playwright-test-engineer → Create visual tests
+2. frontend-testing-engineer → Create visual tests
 3. Run visual regression tests at all breakpoints
 4. code-analyzer → Verify accessibility
 5. Capture screenshots for PR

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