claude-autopm 1.25.0 → 1.27.0

package/README.md

@@ -328,6 +328,117 @@ claude --dangerously-skip-permissions .
 
 ---
 
+## 🔧 Advanced Tools
+
+### Epic Sync (JavaScript)
+
+Complete epic synchronization workflow in one command:
+
+```bash
+# Full epic sync (create epic + tasks + update references)
+node .claude/lib/commands/pm/epicSync.js sync fullstack/01-infrastructure
+
+# Individual operations
+node .claude/lib/commands/pm/epicSync.js create-epic fullstack/01-infrastructure
+node .claude/lib/commands/pm/epicSync.js create-tasks fullstack/01-infrastructure 2
+node .claude/lib/commands/pm/epicSync.js update-epic fullstack/01-infrastructure 2
+```
+
+**Features:**
+- Creates GitHub epic issue with labels and stats
+- Creates task issues for all tasks in epic
+- Updates epic file with GitHub URLs
+- Renames task files to match issue numbers
+- Updates all cross-references automatically
+
+### Issue Sync (JavaScript)
+
+Synchronize local development progress with GitHub issues:
+
+```bash
+# Full sync workflow
+node .claude/lib/commands/pm/issueSync.js sync 123 .claude/epics/auth/updates/123
+
+# Mark task as complete
+node .claude/lib/commands/pm/issueSync.js sync 456 ./updates --complete
+
+# Dry run (preview without posting)
+node .claude/lib/commands/pm/issueSync.js sync 789 ./updates --dry-run
+
+# Individual operations
+node .claude/lib/commands/pm/issueSync.js gather 123 ./updates
+node .claude/lib/commands/pm/issueSync.js format 123 ./updates
+```
+
+**Features:**
+- Gathers updates from multiple sources (progress, notes, commits)
+- Formats professional GitHub comments
+- Posts updates to issues
+- Updates frontmatter with sync timestamps
+- Preflight validation (auth, issue exists, etc.)
+- Supports completion workflow
+
+**What gets synced:**
+- Progress updates and completion %
+- Technical notes and decisions
+- Recent commits (auto-detected or manual)
+- Acceptance criteria updates
+- Next steps and blockers
+
+### Epic Status (JavaScript)
+
+Track epic progress with detailed status reporting:
+
+```bash
+# Show epic status
+node .claude/lib/commands/pm/epicStatus.js fullstack/01-infrastructure
+
+# List available epics
+node .claude/lib/commands/pm/epicStatus.js
+```
+
+**Features:**
+- Counts tasks by status (completed/in-progress/pending)
+- Calculates progress percentage
+- Visual progress bar
+- Sub-epic breakdown
+- Comprehensive status reporting
+
+**Example output:**
+```
+Epic: fullstack/01-infrastructure
+==================================
+
+Total tasks:     12
+Completed:       8 (67%)
+In Progress:     2
+Pending:         2
+
+Progress: [=================================-------------] 67%
+
+Sub-Epic Breakdown:
+-------------------
+  backend                        6 tasks (4 completed)
+  frontend                       4 tasks (3 completed)
+  infrastructure                 2 tasks (1 completed)
+```
+
+### Why JavaScript Tools?
+
+**Replaced 10 Bash scripts** (~2600 lines) with **3 JavaScript tools** (~1500 lines):
+
+**Benefits:**
+- ✅ Zero parsing errors (no heredoc/awk/sed complexity)
+- 🧪 Fully testable (all functions exported)
+- 📖 More readable and maintainable
+- 🚀 50% less code
+- 💾 Better error handling
+- 🔍 Easier debugging
+
+**Backward compatible:** Old Bash scripts still work, but new JS tools are recommended.
+
+---
+
 ## 🤝 Contributing
 
 We welcome contributions! See [CONTRIBUTING.md](docs/development/contributing.md) for:

package/autopm/.claude/agents/frameworks/e2e-test-engineer.md

@@ -39,24 +39,7 @@ Access E2E testing frameworks and patterns:
 - `mcp://context7/agile/acceptance-criteria` - Writing effective AC
 - `mcp://context7/project-management/estimation` - Effort estimation
 
-## Task Creation Excellence
-
-When creating implementation tasks (for epic decomposition or project planning):
-
-1. **Query Context7 First**: Access latest agile/PM best practices
-2. **Follow INVEST Criteria**: Tasks must be Independent, Negotiable, Valuable, Estimable, Small, Testable
-3. **Include TDD Requirements**: Every task must enforce Test-Driven Development
-4. **Technology-Specific Details**: Leverage your E2E testing expertise in technical details
-5. **Clear Acceptance Criteria**: Specific, measurable, testable criteria
-
-**Task Structure Template**: Use frontmatter with name, status, created, depends_on, parallel, conflicts_with. Include sections for Description, TDD Requirements, Acceptance Criteria, Technical Details, Dependencies, Effort Estimate, Definition of Done.
-
-**Quality Standards**:
-- Tasks completable in 1-3 days maximum
-- Action-oriented titles (verb + noun)
-- Specific E2E test framework and scenario guidance
-- Dependency and parallelization mapping
-- Test automation, visual regression, and accessibility testing considerations
+@include includes/task-creation-excellence.md
 
 ## E2E Testing Methodology
 

package/autopm/.claude/agents/frameworks/nats-messaging-expert.md

@@ -37,24 +37,7 @@ Use this agent for NATS messaging system including pub/sub, request/reply, and q
 - `mcp://context7/agile/acceptance-criteria` - Writing effective AC
 - `mcp://context7/project-management/estimation` - Effort estimation
 
-## Task Creation Excellence
-
-When creating implementation tasks (for epic decomposition or project planning):
-
-1. **Query Context7 First**: Access latest agile/PM best practices
-2. **Follow INVEST Criteria**: Tasks must be Independent, Negotiable, Valuable, Estimable, Small, Testable
-3. **Include TDD Requirements**: Every task must enforce Test-Driven Development
-4. **Technology-Specific Details**: Leverage your NATS messaging expertise in technical details
-5. **Clear Acceptance Criteria**: Specific, measurable, testable criteria
-
-**Task Structure Template**: Use frontmatter with name, status, created, depends_on, parallel, conflicts_with. Include sections for Description, TDD Requirements, Acceptance Criteria, Technical Details, Dependencies, Effort Estimate, Definition of Done.
-
-**Quality Standards**:
-- Tasks completable in 1-3 days maximum
-- Action-oriented titles (verb + noun)
-- Specific NATS messaging pattern and JetStream guidance
-- Dependency and parallelization mapping
-- Pub/sub, clustering, and high availability considerations
+@include includes/task-creation-excellence.md
 
 ## Core Expertise
 

package/autopm/.claude/agents/frameworks/react-frontend-engineer.md

@@ -45,24 +45,7 @@ Before starting any implementation, you have access to live documentation throug
 - `mcp://context7/agile/acceptance-criteria` - Writing effective AC
 - `mcp://context7/project-management/estimation` - Effort estimation
 
-## Task Creation Excellence
-
-When creating implementation tasks (for epic decomposition or project planning):
-
-1. **Query Context7 First**: Access latest agile/PM best practices
-2. **Follow INVEST Criteria**: Tasks must be Independent, Negotiable, Valuable, Estimable, Small, Testable
-3. **Include TDD Requirements**: Every task must enforce Test-Driven Development
-4. **Technology-Specific Details**: Leverage your React expertise in technical details
-5. **Clear Acceptance Criteria**: Specific, measurable, testable criteria
-
-**Task Structure Template**: Use frontmatter with name, status, created, depends_on, parallel, conflicts_with. Include sections for Description, TDD Requirements, Acceptance Criteria, Technical Details, Dependencies, Effort Estimate, Definition of Done.
-
-**Quality Standards**:
-- Tasks completable in 1-3 days maximum
-- Action-oriented titles (verb + noun)
-- Specific React implementation guidance
-- Dependency and parallelization mapping
-- Component architecture and state management considerations
+@include includes/task-creation-excellence.md
 
 **Core Expertise:**
 

package/autopm/.claude/agents/frameworks/react-ui-expert.md

@@ -32,24 +32,7 @@ Before implementing any UI solution, access live documentation through context7:
 - `mcp://context7/agile/acceptance-criteria` - Writing effective AC
 - `mcp://context7/project-management/estimation` - Effort estimation
 
-## Task Creation Excellence
-
-When creating implementation tasks (for epic decomposition or project planning):
-
-1. **Query Context7 First**: Access latest agile/PM best practices
-2. **Follow INVEST Criteria**: Tasks must be Independent, Negotiable, Valuable, Estimable, Small, Testable
-3. **Include TDD Requirements**: Every task must enforce Test-Driven Development
-4. **Technology-Specific Details**: Leverage your React UI expertise in technical details
-5. **Clear Acceptance Criteria**: Specific, measurable, testable criteria
-
-**Task Structure Template**: Use frontmatter with name, status, created, depends_on, parallel, conflicts_with. Include sections for Description, TDD Requirements, Acceptance Criteria, Technical Details, Dependencies, Effort Estimate, Definition of Done.
-
-**Quality Standards**:
-- Tasks completable in 1-3 days maximum
-- Action-oriented titles (verb + noun)
-- Specific React UI framework implementation guidance
-- Dependency and parallelization mapping
-- Component design system and accessibility considerations
+@include includes/task-creation-excellence.md
 
 ## Test-Driven Development (TDD) Methodology
 

package/autopm/.claude/agents/frameworks/tailwindcss-expert.md

@@ -40,24 +40,7 @@ Access Tailwind CSS documentation through context7:
 - `mcp://context7/agile/acceptance-criteria` - Writing effective AC
 - `mcp://context7/project-management/estimation` - Effort estimation
 
-## Task Creation Excellence
-
-When creating implementation tasks (for epic decomposition or project planning):
-
-1. **Query Context7 First**: Access latest agile/PM best practices
-2. **Follow INVEST Criteria**: Tasks must be Independent, Negotiable, Valuable, Estimable, Small, Testable
-3. **Include TDD Requirements**: Every task must enforce Test-Driven Development
-4. **Technology-Specific Details**: Leverage your TailwindCSS expertise in technical details
-5. **Clear Acceptance Criteria**: Specific, measurable, testable criteria
-
-**Task Structure Template**: Use frontmatter with name, status, created, depends_on, parallel, conflicts_with. Include sections for Description, TDD Requirements, Acceptance Criteria, Technical Details, Dependencies, Effort Estimate, Definition of Done.
-
-**Quality Standards**:
-- Tasks completable in 1-3 days maximum
-- Action-oriented titles (verb + noun)
-- Specific TailwindCSS utility and design system guidance
-- Dependency and parallelization mapping
-- Responsive design and theme customization considerations
+@include includes/task-creation-excellence.md
 
 ## When to Use This Agent
 

package/autopm/.claude/agents/frameworks/ux-design-expert.md

@@ -41,24 +41,7 @@ Access UX design and accessibility documentation:
 - `mcp://context7/agile/acceptance-criteria` - Writing effective AC
 - `mcp://context7/project-management/estimation` - Effort estimation
 
-## Task Creation Excellence
-
-When creating implementation tasks (for epic decomposition or project planning):
-
-1. **Query Context7 First**: Access latest agile/PM best practices
-2. **Follow INVEST Criteria**: Tasks must be Independent, Negotiable, Valuable, Estimable, Small, Testable
-3. **Include TDD Requirements**: Every task must enforce Test-Driven Development
-4. **Technology-Specific Details**: Leverage your UX design expertise in technical details
-5. **Clear Acceptance Criteria**: Specific, measurable, testable criteria
-
-**Task Structure Template**: Use frontmatter with name, status, created, depends_on, parallel, conflicts_with. Include sections for Description, TDD Requirements, Acceptance Criteria, Technical Details, Dependencies, Effort Estimate, Definition of Done.
-
-**Quality Standards**:
-- Tasks completable in 1-3 days maximum
-- Action-oriented titles (verb + noun)
-- Specific UX/UI design and accessibility guidance
-- Dependency and parallelization mapping
-- User research, interaction design, and accessibility compliance considerations
+@include includes/task-creation-excellence.md
 
 ## Core Expertise
 

package/autopm/.claude/agents/languages/bash-scripting-expert.md

@@ -50,24 +50,7 @@ Before starting any implementation, you have access to live documentation throug
 - `mcp://context7/agile/acceptance-criteria` - Writing effective AC
 - `mcp://context7/project-management/estimation` - Effort estimation
 
-## Task Creation Excellence
-
-When creating implementation tasks (for epic decomposition or project planning):
-
-1. **Query Context7 First**: Access latest agile/PM best practices
-2. **Follow INVEST Criteria**: Tasks must be Independent, Negotiable, Valuable, Estimable, Small, Testable
-3. **Include TDD Requirements**: Every task must enforce Test-Driven Development (with bats for Bash)
-4. **Technology-Specific Details**: Leverage your Bash/scripting expertise in technical details
-5. **Clear Acceptance Criteria**: Specific, measurable, testable criteria
-
-**Task Structure Template**: Use frontmatter with name, status, created, depends_on, parallel, conflicts_with. Include sections for Description, TDD Requirements, Acceptance Criteria, Technical Details, Dependencies, Effort Estimate, Definition of Done.
-
-**Quality Standards**:
-- Tasks completable in 1-3 days maximum
-- Action-oriented titles (verb + noun)
-- Specific shell scripting implementation guidance
-- Dependency and parallelization mapping
-- Security and portability considerations included
+@include includes/task-creation-excellence.md
 
 ## Core Expertise
 

package/autopm/.claude/agents/languages/javascript-frontend-engineer.md

@@ -48,24 +48,7 @@ Before starting any implementation, you have access to live documentation throug
 - `mcp://context7/agile/acceptance-criteria` - Writing effective AC
 - `mcp://context7/project-management/estimation` - Effort estimation
 
-## Task Creation Excellence
-
-When creating implementation tasks (for epic decomposition or project planning):
-
-1. **Query Context7 First**: Access latest agile/PM best practices
-2. **Follow INVEST Criteria**: Tasks must be Independent, Negotiable, Valuable, Estimable, Small, Testable
-3. **Include TDD Requirements**: Every task must enforce Test-Driven Development
-4. **Technology-Specific Details**: Leverage your JavaScript/TypeScript expertise in technical details
-5. **Clear Acceptance Criteria**: Specific, measurable, testable criteria
-
-**Task Structure Template**: Use frontmatter with name, status, created, depends_on, parallel, conflicts_with. Include sections for Description, TDD Requirements, Acceptance Criteria, Technical Details, Dependencies, Effort Estimate, Definition of Done.
-
-**Quality Standards**:
-- Tasks completable in 1-3 days maximum
-- Action-oriented titles (verb + noun)
-- Specific technical implementation guidance
-- Dependency and parallelization mapping
-- No vague descriptions or missing acceptance criteria
+@include includes/task-creation-excellence.md
 
 ## Core Expertise
 

package/autopm/.claude/agents/languages/nodejs-backend-engineer.md

@@ -52,24 +52,7 @@ Before starting any implementation, you have access to live documentation throug
 3. **Security Standards**: Access current security recommendations
 4. **Performance Patterns**: Get latest Node.js optimization techniques
 
-## Task Creation Excellence
-
-When creating implementation tasks (for epic decomposition or project planning):
-
-1. **Query Context7 First**: Access latest agile/PM best practices
-2. **Follow INVEST Criteria**: Tasks must be Independent, Negotiable, Valuable, Estimable, Small, Testable
-3. **Include TDD Requirements**: Every task must enforce Test-Driven Development
-4. **Technology-Specific Details**: Leverage your Node.js/backend expertise in technical details
-5. **Clear Acceptance Criteria**: Specific, measurable, testable criteria
-
-**Task Structure Template**: Use frontmatter with name, status, created, depends_on, parallel, conflicts_with. Include sections for Description, TDD Requirements, Acceptance Criteria, Technical Details, Dependencies, Effort Estimate, Definition of Done.
-
-**Quality Standards**:
-- Tasks completable in 1-3 days maximum
-- Action-oriented titles (verb + noun)
-- Specific technical implementation guidance for backend/APIs
-- Dependency and parallelization mapping
-- Security and performance considerations included
+@include includes/task-creation-excellence.md
 
 ## Core Expertise
 

package/autopm/.claude/agents/languages/python-backend-engineer.md

@@ -45,24 +45,7 @@ Before starting any implementation, you have access to live documentation throug
 - `mcp://context7/agile/acceptance-criteria` - Writing effective AC
 - `mcp://context7/project-management/estimation` - Effort estimation
 
-## Task Creation Excellence
-
-When creating implementation tasks (for epic decomposition or project planning):
-
-1. **Query Context7 First**: Access latest agile/PM best practices
-2. **Follow INVEST Criteria**: Tasks must be Independent, Negotiable, Valuable, Estimable, Small, Testable
-3. **Include TDD Requirements**: Every task must enforce Test-Driven Development
-4. **Technology-Specific Details**: Leverage your Python backend expertise in technical details
-5. **Clear Acceptance Criteria**: Specific, measurable, testable criteria
-
-**Task Structure Template**: Use frontmatter with name, status, created, depends_on, parallel, conflicts_with. Include sections for Description, TDD Requirements, Acceptance Criteria, Technical Details, Dependencies, Effort Estimate, Definition of Done.
-
-**Quality Standards**:
-- Tasks completable in 1-3 days maximum
-- Action-oriented titles (verb + noun)
-- Specific Python/FastAPI implementation guidance
-- Dependency and parallelization mapping
-- API design, database integration, and async pattern considerations
+@include includes/task-creation-excellence.md
 
 **Core Expertise:**
 

package/autopm/.claude/agents/languages/python-backend-expert.md

@@ -32,24 +32,7 @@ Before implementing any Python backend solution, access live documentation throu
 - `mcp://context7/agile/acceptance-criteria` - Writing effective AC
 - `mcp://context7/project-management/estimation` - Effort estimation
 
-## Task Creation Excellence
-
-When creating implementation tasks (for epic decomposition or project planning):
-
-1. **Query Context7 First**: Access latest agile/PM best practices
-2. **Follow INVEST Criteria**: Tasks must be Independent, Negotiable, Valuable, Estimable, Small, Testable
-3. **Include TDD Requirements**: Every task must enforce Test-Driven Development
-4. **Technology-Specific Details**: Leverage your Python backend expertise in technical details
-5. **Clear Acceptance Criteria**: Specific, measurable, testable criteria
-
-**Task Structure Template**: Use frontmatter with name, status, created, depends_on, parallel, conflicts_with. Include sections for Description, TDD Requirements, Acceptance Criteria, Technical Details, Dependencies, Effort Estimate, Definition of Done.
-
-**Quality Standards**:
-- Tasks completable in 1-3 days maximum
-- Action-oriented titles (verb + noun)
-- Specific Python framework implementation guidance
-- Dependency and parallelization mapping
-- Architecture patterns, ORM integration, and async support considerations
+@include includes/task-creation-excellence.md
 
 ## Test-Driven Development (TDD) Methodology
 

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

@@ -10,13 +10,13 @@ Break epic into concrete, actionable tasks.
 
 **Single Epic:**
 ```bash
-/pm:epic-decompose <feature_name>
+/pm:epic-decompose <feature_name> [--local]
 ```
 
 **Multi-Epic (decomposes ALL epics at once):**
 ```bash
-/pm:epic-decompose <feature_name>
-# Example: /pm:epic-decompose ecommerce-platform
+/pm:epic-decompose <feature_name> [--local]
+# Example: /pm:epic-decompose ecommerce-platform --local
 # This will automatically decompose ALL epics:
 #   - 01-infrastructure
 #   - 02-auth-backend
@@ -26,8 +26,22 @@ Break epic into concrete, actionable tasks.
 
 **Single Epic from Multi-Epic structure:**
 ```bash
-/pm:epic-decompose <feature_name>/<epic_folder>
-# Example: /pm:epic-decompose ecommerce-platform/01-infrastructure
+/pm:epic-decompose <feature_name>/<epic_folder> [--local]
+# Example: /pm:epic-decompose ecommerce-platform/01-infrastructure --local
+```
+
+## Flags
+
+`--local`, `-l`
+: Use local mode (offline workflow)
+: Creates task files in `.claude/epics/` directory structure
+: No GitHub/Azure synchronization
+: Task files remain local-only until manually synced
+: Ideal for offline work or projects without remote tracking
+
+Example:
+```
+/pm:epic-decompose user-authentication --local
 ```
 
 ## Required Documentation Access

package/autopm/.claude/commands/pm/prd-new.md

@@ -8,7 +8,20 @@ Launch interactive brainstorming session for new product requirement document.
 
 ## Usage
 ```
-/pm:prd-new <feature_name>
+/pm:prd-new <feature_name> [--local]
+```
+
+## Flags
+
+`--local`, `-l`
+: Use local mode (offline workflow)
+: Creates PRD files in `.claude/prds/` directory
+: No GitHub/Azure synchronization required
+: Ideal for working offline or without remote provider configured
+
+Example:
+```
+/pm:prd-new user-authentication --local
 ```
 
 ## Required Documentation Access

package/autopm/.claude/includes/task-creation-excellence.md

@@ -0,0 +1,18 @@
+## Task Creation Excellence
+
+When creating implementation tasks (for epic decomposition or project planning):
+
+1. **Query Context7 First**: Access latest agile/PM best practices
+2. **Follow INVEST Criteria**: Tasks must be Independent, Negotiable, Valuable, Estimable, Small, Testable
+3. **Include TDD Requirements**: Every task must enforce Test-Driven Development
+4. **Technology-Specific Details**: Leverage your technology-specific expertise in technical details
+5. **Clear Acceptance Criteria**: Specific, measurable, testable criteria
+
+**Task Structure Template**: Use frontmatter with name, status, created, depends_on, parallel, conflicts_with. Include sections for Description, TDD Requirements, Acceptance Criteria, Technical Details, Dependencies, Effort Estimate, Definition of Done.
+
+**Quality Standards**:
+- Tasks completable in 1-3 days maximum
+- Action-oriented titles (verb + noun)
+- Specific technical implementation guidance
+- Dependency and parallelization mapping
+- No vague descriptions or missing acceptance criteria

package/autopm/.claude/lib/ai-task-generator.js

@@ -0,0 +1,84 @@
+/**
+ * AI Task Generator
+ *
+ * Generates tasks from epic content using AI providers (OpenAI, Claude, etc.)
+ * Supports dependency injection for testing with mock providers.
+ *
+ * Usage:
+ *   const { TaskGenerator } = require('./ai-task-generator');
+ *
+ *   const generator = new TaskGenerator();
+ *   const tasks = await generator.generate(epicContent, { maxTasks: 10 });
+ */
+
+/**
+ * Task Generator using AI providers
+ */
+class TaskGenerator {
+  constructor(provider = null) {
+    this.provider = provider; // Allow injection for testing
+  }
+
+  /**
+   * Generate tasks from epic content
+   *
+   * @param {string} epicContent - Epic markdown content
+   * @param {Object} options - Generation options
+   * @param {number} [options.maxTasks=15] - Maximum number of tasks to generate
+   * @param {number} [options.minHours=2] - Minimum estimated hours per task
+   * @param {number} [options.maxHours=8] - Maximum estimated hours per task
+   * @returns {Promise<Array>} Array of task objects
+   */
+  async generate(epicContent, options = {}) {
+    const {
+      maxTasks = 15,
+      minHours = 2,
+      maxHours = 8
+    } = options;
+
+    if (!this.provider) {
+      throw new Error('AI provider not configured. Use TaskGenerator(provider) or set via setProvider');
+    }
+
+    // Generate tasks using AI provider
+    const tasks = await this.provider.generateTasks(epicContent, {
+      maxTasks,
+      minHours,
+      maxHours
+    });
+
+    // Validate and normalize tasks
+    return tasks.map((task, index) => this.normalizeTask(task, index + 1));
+  }
+
+  /**
+   * Normalize task object to standard format
+   *
+   * @param {Object} task - Raw task from AI
+   * @param {number} taskNumber - Task sequence number
+   * @returns {Object} Normalized task object
+   */
+  normalizeTask(task, taskNumber) {
+    return {
+      number: taskNumber,
+      title: task.title || `Task ${taskNumber}`,
+      description: task.description || '',
+      acceptance_criteria: task.acceptance_criteria || [],
+      estimated_hours: task.estimated_hours || 4,
+      dependencies: task.dependencies || [],
+      priority: task.priority || 'medium',
+      tags: task.tags || []
+    };
+  }
+
+  /**
+   * Set AI provider (for dependency injection)
+   *
+   * @param {Object} provider - AI provider instance
+   */
+  setProvider(provider) {
+    this.provider = provider;
+  }
+}
+
+module.exports = { TaskGenerator };