claude-autopm 1.26.0 → 1.28.0

package/autopm/.claude/scripts/pm-task-update-local.js

@@ -0,0 +1,109 @@
+/**
+ * Update Local Task
+ *
+ * Updates task frontmatter and automatically updates epic counters.
+ * Optionally validates dependency constraints.
+ *
+ * Usage:
+ *   const { updateLocalTask } = require('./pm-task-update-local');
+ *
+ *   // Update task status
+ *   await updateLocalTask('epic-001', 'task-001', { status: 'completed' });
+ *
+ *   // Update with dependency validation
+ *   await updateLocalTask('epic-001', 'task-002', {
+ *     status: 'completed',
+ *     validateDependencies: true
+ *   });
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const { parseFrontmatter, stringifyFrontmatter } = require('../lib/frontmatter');
+const { showLocalTask } = require('./pm-task-show-local');
+const { listLocalTasks } = require('./pm-task-list-local');
+const { updateLocalEpic } = require('./pm-epic-update-local');
+
+/**
+ * Update task frontmatter
+ *
+ * @param {string} epicId - Epic ID containing the task
+ * @param {string} taskId - Task ID to update
+ * @param {Object} updates - Fields to update
+ * @param {boolean} [updates.validateDependencies] - Validate dependencies before update
+ * @returns {Promise<Object>} Updated task object
+ * @throws {Error} If task not found or dependencies not met
+ */
+async function updateLocalTask(epicId, taskId, updates) {
+  const { validateDependencies, ...frontmatterUpdates } = updates;
+
+  // Get current task
+  const task = await showLocalTask(epicId, taskId);
+
+  // Validate dependencies if requested and status is changing to completed
+  if (validateDependencies && frontmatterUpdates.status === 'completed') {
+    const dependencies = task.frontmatter.dependencies || [];
+
+    if (dependencies.length > 0) {
+      // Check if all dependencies are completed
+      const allTasks = await listLocalTasks(epicId);
+
+      for (const depId of dependencies) {
+        const depTask = allTasks.find(t =>
+          t.id === depId ||
+          t.id === `task-${epicId}-${depId.replace('task-', '')}` ||
+          t.filename === `${depId}.md`
+        );
+
+        if (depTask && depTask.status !== 'completed') {
+          throw new Error(
+            `Dependencies not met: ${depId} (status: ${depTask.status}) must be completed first`
+          );
+        }
+      }
+    }
+  }
+
+  // Track if status changed to/from completed
+  const oldStatus = task.frontmatter.status;
+  const newStatus = frontmatterUpdates.status || oldStatus;
+  const statusChanged = oldStatus !== newStatus;
+  const wasCompleted = oldStatus === 'completed';
+  const nowCompleted = newStatus === 'completed';
+
+  // Merge updates into frontmatter
+  const updatedFrontmatter = {
+    ...task.frontmatter,
+    ...frontmatterUpdates
+  };
+
+  // Preserve body content
+  const updatedContent = stringifyFrontmatter(updatedFrontmatter, task.body);
+
+  // Write updated content back to file
+  await fs.writeFile(task.path, updatedContent, 'utf8');
+
+  // Update epic tasks_completed counter if status changed
+  if (statusChanged && (wasCompleted || nowCompleted)) {
+    const allTasks = await listLocalTasks(epicId);
+    const completedCount = allTasks.filter(t => {
+      if (t.id === task.frontmatter.id || t.id === updatedFrontmatter.id) {
+        return nowCompleted;
+      }
+      return t.status === 'completed';
+    }).length;
+
+    await updateLocalEpic(epicId, {
+      tasks_completed: completedCount
+    });
+  }
+
+  return {
+    taskId,
+    epicId,
+    frontmatter: updatedFrontmatter,
+    body: task.body
+  };
+}
+
+module.exports = { updateLocalTask };

package/autopm/.claude/scripts/setup-local-mode.js

@@ -0,0 +1,127 @@
+const fs = require('fs').promises;
+const path = require('path');
+
+/**
+ * Setup local mode directory structure
+ * Creates .claude/prds/, .claude/epics/, .claude/context/, .claude/logs/
+ *
+ * @returns {Promise<void>}
+ */
+async function setupLocalDirectories() {
+  const baseDir = path.join(process.cwd(), '.claude');
+
+  const directories = [
+    'prds',       // Product Requirements Documents
+    'epics',      // Epic definitions and task breakdowns
+    'context',    // Project context files (NEW)
+    'logs'        // Verification and operation logs (NEW)
+  ];
+
+  for (const dir of directories) {
+    const dirPath = path.join(baseDir, dir);
+
+    try {
+      await fs.mkdir(dirPath, { recursive: true, mode: 0o755 });
+      console.log(`✅ Created ${dirPath}`);
+    } catch (err) {
+      // EEXIST is OK - directory already exists
+      if (err.code !== 'EEXIST') {
+        throw err;
+      }
+    }
+  }
+}
+
+/**
+ * Update .gitignore with ClaudeAutoPM local mode entries
+ * Creates .gitignore if it doesn't exist
+ * Appends entries if .gitignore exists (idempotent)
+ *
+ * @returns {Promise<void>}
+ */
+async function updateGitignore() {
+  const gitignorePath = path.join(process.cwd(), '.gitignore');
+
+  const entries = [
+    '# ClaudeAutoPM Local Mode',
+    '.claude/logs/*.log',
+    '.claude/context/.context-version',
+    '.claude/prds/drafts/',
+    ''
+  ].join('\n');
+
+  try {
+    // Try to read existing .gitignore
+    const existing = await fs.readFile(gitignorePath, 'utf8');
+
+    // Check if our entries are already present
+    if (!existing.includes('.claude/logs/')) {
+      // Append our entries
+      await fs.appendFile(gitignorePath, '\n' + entries);
+      console.log('✅ Updated .gitignore');
+    } else {
+      console.log('ℹ️  .gitignore already contains ClaudeAutoPM entries');
+    }
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      // .gitignore doesn't exist, create it
+      await fs.writeFile(gitignorePath, entries);
+      console.log('✅ Created .gitignore');
+    } else {
+      throw err;
+    }
+  }
+}
+
+/**
+ * Main setup function
+ * Called during `autopm install` or standalone
+ *
+ * @returns {Promise<void>}
+ */
+async function setup() {
+  console.log('🚀 Setting up ClaudeAutoPM local mode...\n');
+
+  try {
+    await setupLocalDirectories();
+    await updateGitignore();
+
+    console.log('\n✅ Local mode setup complete!');
+    console.log('\nCreated directories:');
+    console.log('  - .claude/prds/     (Product Requirements Documents)');
+    console.log('  - .claude/epics/    (Epic breakdowns and tasks)');
+    console.log('  - .claude/context/  (Project context files)');
+    console.log('  - .claude/logs/     (Operation logs)');
+    console.log('\nUpdated .gitignore with exclusions for:');
+    console.log('  - .claude/logs/*.log');
+    console.log('  - .claude/context/.context-version');
+    console.log('  - .claude/prds/drafts/');
+    console.log('\nYou can now use local mode commands:');
+    console.log('  /pm:prd-new --local "Feature Name"');
+    console.log('  /pm:epic-decompose --local <id>');
+    console.log('  /pm:context-create');
+
+  } catch (error) {
+    console.error('❌ Setup failed:', error.message);
+
+    // Provide helpful error messages
+    if (error.code === 'EACCES') {
+      console.error('\nPermission denied. Try running with sudo or check directory permissions.');
+    } else if (error.code === 'ENOSPC') {
+      console.error('\nNo space left on device. Free up some space and try again.');
+    }
+
+    process.exit(1);
+  }
+}
+
+// If run directly (not required as module)
+if (require.main === module) {
+  setup();
+}
+
+module.exports = {
+  setupLocalDirectories,
+  updateGitignore,
+  setup
+};

package/autopm/.claude/templates/prds/README.md

@@ -0,0 +1,334 @@
+# Built-in PRD Templates
+
+**Version**: v1.28.0
+**Total Templates**: 5
+**Status**: Production Ready ✅
+
+---
+
+## 📋 Available Templates
+
+### 1. API Feature (`api-feature.md`)
+**Use for**: REST/GraphQL API development
+
+**Best for**:
+- Microservices endpoints
+- Public APIs
+- Internal service APIs
+- Authentication systems
+
+**Includes**:
+- OpenAPI specification (contract-first)
+- JWT authentication & security
+- Performance benchmarks (< 100ms)
+- Rate limiting & error handling
+- Comprehensive testing (TDD)
+
+**Example Variables**:
+```yaml
+title: "User Authentication API"
+api_purpose: "user authentication"
+http_method: "POST"
+api_endpoint: "/api/auth/login"
+auth_method: "JWT"
+rate_limit: "100 req/min"
+```
+
+---
+
+### 2. UI Feature (`ui-feature.md`)
+**Use for**: Frontend components and pages
+
+**Best for**:
+- React/Vue/Angular components
+- Dashboard pages
+- Forms and modals
+- Responsive layouts
+
+**Includes**:
+- WCAG 2.1 AA compliance (legal requirement 2025)
+- Core Web Vitals (LCP, FID, CLS)
+- Mobile-first responsive design
+- Accessibility testing (screen readers)
+- Lighthouse performance targets
+
+**Example Variables**:
+```yaml
+title: "User Dashboard"
+component_type: "Page"
+platform: "Web"
+frontend_framework: "React 18"
+state_management: "Zustand"
+styling_approach: "Tailwind CSS"
+```
+
+---
+
+### 3. Bug Fix (`bug-fix.md`)
+**Use for**: Bug resolution with root cause analysis
+
+**Best for**:
+- Critical production bugs
+- Performance issues
+- Data corruption fixes
+- Security vulnerabilities
+
+**Includes**:
+- 5 Whys root cause analysis
+- Severity classification (P0-P3)
+- Impact analysis (users, revenue, system)
+- Comprehensive rollback plan
+- Post-mortem documentation
+
+**Example Variables**:
+```yaml
+title: "Fix Login Timeout Issue"
+severity: "High"
+bug_id: "BUG-1234"
+affected_users: "5,000 (20%)"
+environment: "Production"
+root_cause: "Database connection pool exhaustion"
+```
+
+---
+
+### 4. Data Migration (`data-migration.md`)
+**Use for**: Database schema changes and data migration
+
+**Best for**:
+- Database migrations
+- Cloud migrations
+- Data consolidation
+- Schema refactoring
+
+**Includes**:
+- Data profiling & quality assessment
+- Migration strategies (Big Bang, Trickle, Phased)
+- Comprehensive validation (pre/post)
+- Performance optimization
+- Rollback procedures
+
+**Example Variables**:
+```yaml
+title: "Migrate User Data to PostgreSQL"
+migration_type: "Platform Migration"
+source_system: "MySQL 5.7"
+target_system: "PostgreSQL 15"
+data_volume: "10M records"
+estimated_duration: "4 hours"
+```
+
+---
+
+### 5. Documentation (`documentation.md`)
+**Use for**: Technical and user documentation
+
+**Best for**:
+- API documentation
+- User guides
+- Developer documentation
+- Runbooks
+- Tutorials
+
+**Includes**:
+- Documentation-as-Code approach
+- WCAG 2.1 AA accessibility
+- SEO optimization
+- Analytics & measurement
+- Localization (i18n) support
+
+**Example Variables**:
+```yaml
+title: "API Reference Documentation"
+doc_type: "API Documentation"
+target_audience: "External Developers"
+delivery_format: "Web (Docusaurus)"
+platform: "GitHub Pages"
+```
+
+---
+
+## 🚀 Quick Start
+
+### Using a Template
+
+```bash
+# With autopm CLI (coming in v1.28.0)
+autopm prd:new --template api-feature "User Authentication API"
+autopm prd:new --template ui-feature "Dashboard Redesign"
+autopm prd:new --template bug-fix "Fix Login Issue"
+autopm prd:new --template data-migration "Migrate to PostgreSQL"
+autopm prd:new --template documentation "API Reference"
+```
+
+### Manual Usage
+
+1. Copy template file to your PRDs directory
+2. Replace `{{variables}}` with actual values
+3. Fill in optional sections as needed
+4. Remove unused sections
+
+---
+
+## 🎯 Template Selection Guide
+
+**Choose based on your feature type**:
+
+| Feature Type | Template | Why |
+|-------------|----------|-----|
+| REST/GraphQL API | `api-feature` | OpenAPI spec, security, performance |
+| Frontend UI | `ui-feature` | WCAG compliance, Core Web Vitals |
+| Production Bug | `bug-fix` | RCA, rollback, post-mortem |
+| Data Work | `data-migration` | Validation, rollback, compliance |
+| Docs Update | `documentation` | Accessibility, SEO, analytics |
+
+---
+
+## 📝 Variable Reference
+
+### Common Variables (All Templates)
+
+**Auto-generated**:
+- `{{id}}` - Sequential ID (prd-001, prd-002...)
+- `{{timestamp}}` - ISO 8601 datetime
+- `{{date}}` - YYYY-MM-DD
+- `{{author}}` - From $USER or git config
+
+**User-provided**:
+- `{{title}}` - Feature/PRD title (required)
+- `{{priority}}` - P0/P1/P2/P3 or Critical/High/Medium/Low
+- `{{timeline}}` - Estimated timeline or "TBD"
+
+### Template-Specific Variables
+
+**api-feature.md**:
+- `{{api_purpose}}`, `{{http_method}}`, `{{api_endpoint}}`
+- `{{auth_method}}`, `{{rate_limit}}`
+- `{{request_body_example}}`, `{{response_body_example}}`
+
+**ui-feature.md**:
+- `{{component_type}}`, `{{platform}}`, `{{frontend_framework}}`
+- `{{wireframe_link}}`, `{{design_link}}`
+- `{{lighthouse_target}}`, `{{usability_score}}`
+
+**bug-fix.md**:
+- `{{severity}}`, `{{bug_id}}`, `{{affected_users}}`
+- `{{root_cause}}`, `{{solution_approach}}`
+- `{{why_1}}` through `{{why_5}}` (5 Whys)
+
+**data-migration.md**:
+- `{{migration_type}}`, `{{source_system}}`, `{{target_system}}`
+- `{{data_volume}}`, `{{migration_strategy}}`
+- `{{source_schema}}`, `{{target_schema}}`
+
+**documentation.md**:
+- `{{doc_type}}`, `{{target_audience}}`, `{{delivery_format}}`
+- `{{platform}}`, `{{content_sections}}`
+- `{{reading_level}}`, `{{adoption_target}}`
+
+---
+
+## ✨ Features
+
+### All Templates Include
+
+✅ **2025 Best Practices**: Context7-verified industry standards
+✅ **TDD Methodology**: Red-Green-Refactor testing approach
+✅ **SMART Goals**: Specific, Measurable, Achievable, Relevant, Time-bound
+✅ **INVEST User Stories**: Independent, Negotiable, Valuable, Estimable, Small, Testable
+✅ **Risk Assessment**: Comprehensive risk analysis and mitigation
+✅ **Rollback Plans**: Detailed rollback procedures and triggers
+✅ **Monitoring**: Metrics, alerts, and observability
+✅ **Communication Plans**: Internal and external stakeholder communication
+
+### Special Features by Template
+
+**API Feature**:
+- OpenAPI/Swagger specification
+- OWASP security compliance
+- Performance targets (p50, p95, p99)
+
+**UI Feature**:
+- WCAG 2.1 AA compliance (legal requirement)
+- Core Web Vitals optimization
+- Cross-browser testing matrix
+
+**Bug Fix**:
+- 5 Whys root cause analysis
+- Post-mortem documentation
+- Prevention strategies
+
+**Data Migration**:
+- Multiple migration strategies
+- Data quality assessment
+- Compliance & security
+
+**Documentation**:
+- Documentation-as-Code
+- SEO optimization
+- Analytics tracking
+
+---
+
+## 📚 References
+
+### Best Practices Sources
+- [PRD Best Practices 2025](https://productschool.com/blog/product-strategy/product-template-requirements-document-prd)
+- [INVEST Criteria](https://ones.com/blog/invest-criteria-scrum-user-stories-guide/)
+- [REST API Design](https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design)
+- [WCAG 2.1 Guidelines](https://www.w3.org/TR/WCAG21/)
+- [Root Cause Analysis](https://asana.com/resources/root-cause-analysis-template)
+
+### Technical Standards
+- [OpenAPI Specification](https://swagger.io/specification/)
+- [Core Web Vitals](https://web.dev/vitals/)
+- [TDD Methodology](https://martinfowler.com/bliki/TestDrivenDevelopment.html)
+- [SMART Goals](https://www.atlassian.com/blog/productivity/how-to-write-smart-goals)
+
+---
+
+## 🔄 Customization
+
+### Creating Custom Templates
+
+1. **Copy an existing template** as starting point
+2. **Modify sections** to match your needs
+3. **Add/remove variables** as required
+4. **Save to** `.claude/templates/prds/custom-name.md`
+5. **User templates override** built-in templates
+
+### Template Inheritance
+
+Templates support:
+- `{{#if variable}}...{{/if}}` - Conditional sections
+- `{{#each items}}...{{/each}}` - Loops
+- Nested variables and logic
+
+---
+
+## 📊 Template Statistics
+
+| Template | Lines | Size | Variables | Complexity |
+|----------|-------|------|-----------|------------|
+| api-feature.md | 306 | 7.4KB | ~45 | Medium |
+| ui-feature.md | 365 | 10KB | ~60 | High |
+| bug-fix.md | 413 | 9.5KB | ~70 | High |
+| data-migration.md | 483 | 12KB | ~80 | High |
+| documentation.md | 439 | 11KB | ~75 | High |
+
+**Total**: 2,006 lines across 5 templates
+
+---
+
+## 🆘 Support
+
+**Documentation**: See `docs/templates-design.md` for detailed design
+**Implementation**: See `docs/template-engine-implementation.md` for technical details
+**Examples**: See `docs/built-in-templates-summary.md` for comprehensive overview
+
+**Issues**: Report template issues to the ClaudeAutoPM repository
+
+---
+
+*Built-in PRD Templates - v1.28.0*
+*Context7-verified 2025 best practices*