claude-autopm 1.27.0 → 1.28.0

package/autopm/.claude/templates/prds/ui-feature.md

@@ -0,0 +1,365 @@
+---
+id: {{id}}
+title: {{title}}
+type: prd
+status: draft
+priority: {{priority}}
+created: {{timestamp}}
+author: {{author}}
+timeline: {{timeline}}
+---
+
+# PRD: {{title}}
+
+## Executive Summary
+
+Design and implement {{title}} - a {{component_type}} component for {{feature_purpose}}.
+
+**Component Type**: {{component_type}}
+**Target Platform**: {{platform}}
+
+## Problem Statement
+
+### Background
+{{problem}}
+
+### User Need
+Users need to {{user_need}} in order to {{user_goal}}.
+
+### Current Pain Points
+{{#if pain_points}}
+{{#each pain_points}}
+- {{this}}
+{{/each}}
+{{/if}}
+
+## User Stories (INVEST Criteria)
+
+Following INVEST principles (Independent, Negotiable, Valuable, Estimable, Small, Testable):
+
+- As a **{{user_role}}**, I want to **{{user_action}}** so that **{{user_benefit}}**
+
+{{#if additional_stories}}
+{{#each additional_stories}}
+- As a **{{role}}**, I want to **{{action}}** so that **{{benefit}}**
+{{/each}}
+{{/if}}
+
+## UI/UX Requirements
+
+### Component Specifications
+- **Type**: {{component_type}} (Page/Modal/Widget/Form/Dashboard)
+- **Location**: {{component_location}}
+- **Interaction Pattern**: {{interaction_pattern}}
+- **Responsive Breakpoints**: Mobile (320px+), Tablet (768px+), Desktop (1024px+)
+
+### Design Assets
+- **Wireframes**: {{wireframe_link}} <!-- e.g. https://figma.com/file/xyz or /assets/wireframes/homepage.png -->
+- **Mockups**: {{design_link}} <!-- e.g. https://invisionapp.com/mockup/abc or /assets/mockups/modal.jpg -->
+- **Design System**: {{design_system}} <!-- e.g. https://company.com/design-system or /docs/design-system.md -->
+- **Brand Guidelines**: {{brand_guidelines}} <!-- e.g. https://company.com/brand-guidelines.pdf or /assets/brand-guidelines.pdf -->
+
+### Accessibility (WCAG 2.1 Level AA - 2025 Compliance)
+
+#### Perceivable
+- [ ] **Text Alternatives**: All non-text content has alt text
+- [ ] **Color Contrast**: Minimum 4.5:1 ratio for normal text, 3:1 for large text
+- [ ] **Resize Text**: Content readable at 200% zoom
+- [ ] **Images of Text**: Avoided unless essential
+
+#### Operable
+- [ ] **Keyboard Accessible**: All functionality via keyboard (no mouse required)
+- [ ] **Focus Indicators**: Visible focus states (outline, highlight)
+- [ ] **No Keyboard Trap**: Focus can move away from component
+- [ ] **Skip Links**: Skip to main content option
+- [ ] **Tab Order**: Logical navigation flow
+
+#### Understandable
+- [ ] **Clear Labels**: Form inputs have associated labels
+- [ ] **Error Identification**: Errors clearly described
+- [ ] **Consistent Navigation**: UI patterns consistent across app
+- [ ] **Predictable**: Components behave as expected
+
+#### Robust
+- [ ] **Valid HTML**: Semantic markup, no errors
+- [ ] **ARIA Labels**: Proper ARIA attributes where needed
+- [ ] **Screen Reader Testing**: NVDA, JAWS, VoiceOver compatible
+- [ ] **Browser Compatibility**: Chrome, Firefox, Safari, Edge
+
+### Responsive Design
+
+**Mobile First Approach** (320px - 767px):
+- [ ] Touch-friendly targets (min 44x44px)
+- [ ] Single column layout
+- [ ] Simplified navigation
+- [ ] Optimized images
+
+**Tablet** (768px - 1023px):
+- [ ] Two column layout where appropriate
+- [ ] Enhanced navigation
+- [ ] Adaptive components
+
+**Desktop** (1024px+):
+- [ ] Multi-column layouts
+- [ ] Full feature set
+- [ ] Hover states
+- [ ] Advanced interactions
+
+## Technical Requirements
+
+### Frontend Stack
+- **Framework**: {{frontend_framework}} (React 18+/Vue 3+/Angular 17+)
+- **State Management**: {{state_management}} (Redux/Zustand/Pinia/NgRx)
+- **Styling**: {{styling_approach}} (CSS-in-JS/Sass/Tailwind/CSS Modules)
+- **Build Tool**: {{build_tool}} (Vite/Webpack 5/Parcel)
+
+### Component Architecture
+
+```
+{{component_name}}/
+├── index.jsx/tsx           # Main component
+├── styles.module.css       # Component styles
+├── hooks/
+│   ├── useComponentState.js
+│   └── useComponentEffects.js
+├── utils/
+│   └── helpers.js
+├── types/
+│   └── index.ts            # TypeScript definitions
+├── __tests__/
+│   ├── index.test.jsx
+│   ├── integration.test.jsx
+│   └── a11y.test.jsx       # Accessibility tests
+└── README.md
+```
+
+### API Integration
+- **Endpoints**: {{api_endpoints}}
+- **Loading States**:
+  - Skeleton loaders for content
+  - Spinners for actions
+  - Progress indicators for long operations
+- **Error Handling**:
+  - Toast notifications
+  - Inline error messages
+  - Fallback UI components
+- **Caching Strategy**: {{cache_strategy}}
+
+### Performance Requirements
+
+**Core Web Vitals (2025 Standards)**:
+- [ ] **LCP (Largest Contentful Paint)**: < 2.5s
+- [ ] **FID (First Input Delay)**: < 100ms
+- [ ] **CLS (Cumulative Layout Shift)**: < 0.1
+- [ ] **INP (Interaction to Next Paint)**: < 200ms
+- [ ] **TTFB (Time to First Byte)**: < 600ms
+
+**Bundle Size**:
+- [ ] Component bundle: < 50KB (gzipped)
+- [ ] Total page size: < 500KB (initial load)
+- [ ] Code splitting implemented
+- [ ] Lazy loading for routes
+
+**Runtime Performance**:
+- [ ] 60 FPS scrolling
+- [ ] Smooth animations (requestAnimationFrame)
+- [ ] Debounced inputs (300ms)
+- [ ] Virtualized lists (for 100+ items)
+
+**Lighthouse Scores (Mobile)**:
+- Performance: > 90
+- Accessibility: 100
+- Best Practices: > 95
+- SEO: > 90
+
+## Testing Requirements (TDD Approach)
+
+### Unit Tests (Jest/Vitest)
+- [ ] Component rendering (all states)
+- [ ] User interactions (click, input, submit)
+- [ ] State management (updates, side effects)
+- [ ] Edge cases (empty states, errors)
+- [ ] Utility functions (pure logic)
+- **Coverage Target**: 100% for new code
+
+### Integration Tests
+- [ ] API integration (success/error flows)
+- [ ] Navigation flow (routing)
+- [ ] Form submission (validation, submission)
+- [ ] State persistence (localStorage/sessionStorage)
+
+### Accessibility Tests
+- [ ] axe-core automated testing
+- [ ] Keyboard navigation testing
+- [ ] Screen reader testing (NVDA, JAWS, VoiceOver)
+- [ ] Color contrast validation
+- [ ] ARIA attributes validation
+
+### E2E Tests (Playwright/Cypress)
+- [ ] User journey (complete flow)
+- [ ] Cross-browser (Chrome, Firefox, Safari, Edge)
+- [ ] Responsive design (mobile, tablet, desktop)
+- [ ] Performance profiling
+- [ ] Visual regression testing
+
+### Visual Testing
+- [ ] Chromatic/Percy visual regression
+- [ ] Storybook component documentation
+- [ ] Design system adherence
+
+## Internationalization (i18n)
+
+{{#if i18n_required}}
+- [ ] Text externalized to language files
+- [ ] RTL (Right-to-Left) support
+- [ ] Date/time localization
+- [ ] Number/currency formatting
+- [ ] Pluralization rules
+- **Languages**: {{supported_languages}}
+{{/if}}
+
+## Success Metrics (SMART Goals)
+
+- **Usability**: {{usability_score}}/100 SUS (System Usability Scale) score
+- **Adoption**: {{adoption_target}}% user engagement within {{adoption_timeframe}}
+- **Performance**: {{lighthouse_target}}/100 Lighthouse score
+- **Accessibility**: 100% WCAG 2.1 AA compliance
+- **Error Rate**: < {{error_rate}}%
+- **User Satisfaction**: {{nps_target}} NPS score
+
+## User Feedback Collection
+
+- [ ] Analytics integration (GA4/Mixpanel)
+- [ ] Heatmap tracking (Hotjar/FullStory)
+- [ ] User surveys (post-interaction)
+- [ ] A/B testing framework
+- [ ] Session replay analysis
+
+## Implementation Plan
+
+### Phase 1: Design & Setup (Week 1)
+- [ ] UI/UX review and approval
+- [ ] Component architecture design
+- [ ] API contracts finalized
+- [ ] Accessibility audit plan
+- [ ] Development environment setup
+
+### Phase 2: Development (Week 2-3)
+- [ ] Write failing tests (TDD Red)
+- [ ] Implement component logic (TDD Green)
+- [ ] Apply styling and responsive design
+- [ ] Accessibility implementation
+- [ ] Code review and refactoring
+
+### Phase 3: Testing (Week 4)
+- [ ] Unit test completion (100% coverage)
+- [ ] Integration testing
+- [ ] Accessibility testing (manual + automated)
+- [ ] Cross-browser testing
+- [ ] Performance optimization
+- [ ] Visual regression testing
+
+### Phase 4: Release (Week 5)
+- [ ] Staging deployment
+- [ ] QA validation
+- [ ] Usability testing
+- [ ] Documentation finalization
+- [ ] Production deployment
+- [ ] Monitoring setup
+- [ ] User feedback collection
+
+## Browser & Device Support
+
+### Desktop Browsers
+- Chrome (latest 2 versions)
+- Firefox (latest 2 versions)
+- Safari (latest 2 versions)
+- Edge (latest 2 versions)
+
+### Mobile Browsers
+- iOS Safari (latest 2 versions)
+- Chrome Mobile (latest version)
+- Samsung Internet (latest version)
+
+### Device Testing
+- [ ] iPhone (12, 13, 14, 15)
+- [ ] iPad (9th gen, Pro)
+- [ ] Android phones (Samsung, Pixel)
+- [ ] Desktop (1920x1080, 2560x1440)
+
+## Monitoring & Analytics
+
+### Performance Monitoring
+- Real User Monitoring (RUM)
+- Core Web Vitals tracking
+- Error tracking (Sentry/Rollbar)
+- Bundle size monitoring
+
+### User Analytics
+- User flow tracking
+- Feature usage metrics
+- Conversion funnels
+- Drop-off points
+
+### Alerts
+- Performance degradation (LCP > 3s)
+- Error rate spike (> {{error_threshold}}%)
+- Accessibility violations
+- Browser compatibility issues
+
+## Rollback Plan
+
+### Rollback Triggers
+- Accessibility compliance failure
+- Critical UI bug affecting {{user_percentage}}% users
+- Performance degradation > {{perf_degradation}}%
+- Cross-browser compatibility issues
+
+### Rollback Procedure
+1. Feature flag toggle (immediate disable)
+2. Revert deployment to previous version
+3. Notify affected users
+4. Root cause analysis
+5. Fix and re-deploy
+
+## Risks and Mitigation
+
+### Technical Risks
+| Risk | Impact | Probability | Mitigation |
+|------|--------|-------------|------------|
+| Browser compatibility issues | High | Medium | Cross-browser testing early |
+| Performance degradation | High | Low | Performance budgets, monitoring |
+| Accessibility violations | Critical | Low | Automated + manual testing |
+
+### UX Risks
+| Risk | Impact | Probability | Mitigation |
+|------|--------|-------------|------------|
+| Poor usability | High | Medium | User testing, feedback loops |
+| Confusing navigation | Medium | Medium | A/B testing, analytics |
+
+## Open Questions
+
+- [ ] {{question_1}}
+- [ ] {{question_2}}
+- [ ] {{question_3}}
+
+## Appendix
+
+### Design Resources
+- Design system: {{design_system_link}}
+- Component library: {{component_library_link}}
+- Icon library: {{icon_library}}
+
+### References
+- [WCAG 2.1 Guidelines](https://www.w3.org/TR/WCAG21/)
+- [Web Vitals](https://web.dev/vitals/)
+- [Accessibility Testing Guide](https://www.w3.org/WAI/test-evaluate/)
+- [React Best Practices 2025](https://react.dev/learn)
+
+### Changelog
+- {{timestamp}}: Initial PRD created by {{author}}
+
+---
+
+*UI Feature PRD - Generated from template: ui-feature*
+*Template follows 2025 best practices: WCAG 2.1 AA compliance, Core Web Vitals, TDD methodology, Mobile-first design*

package/lib/template-engine.js

@@ -0,0 +1,347 @@
+/**
+ * Template Engine - Pure Node.js Implementation
+ *
+ * NO external dependencies - uses only built-in Node.js modules
+ *
+ * Features:
+ * - Variable substitution: {{variable}}
+ * - Conditionals: {{#if variable}}...{{/if}}
+ * - Loops: {{#each items}}...{{/each}}
+ * - Auto-generated variables: id, timestamp, author, date
+ * - Template discovery: user custom overrides built-in
+ *
+ * @example Basic Usage
+ * ```javascript
+ * const TemplateEngine = require('./lib/template-engine');
+ * const engine = new TemplateEngine();
+ *
+ * // Find template
+ * const templatePath = engine.findTemplate('prds', 'api-feature');
+ *
+ * // Render with variables
+ * const rendered = engine.renderFile(templatePath, {
+ *   title: 'User Authentication API',
+ *   priority: 'P0',
+ *   problem: 'Users cannot login securely'
+ * });
+ * ```
+ *
+ * @example Advanced Features
+ * ```javascript
+ * // Template with conditionals and loops
+ * const template = `
+ * # {{title}}
+ *
+ * {{#if description}}
+ * ## Description
+ * {{description}}
+ * {{/if}}
+ *
+ * ## Features
+ * {{#each features}}
+ * - {{this}}
+ * {{/each}}
+ * `;
+ *
+ * const result = engine.render(template, {
+ *   title: 'My Feature',
+ *   description: 'Feature description',
+ *   features: ['Auth', 'API', 'UI']
+ * });
+ * ```
+ *
+ * @module TemplateEngine
+ * @version 1.0.0
+ * @since v1.28.0
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+class TemplateEngine {
+  constructor(builtInDir, userDir) {
+    // For testing, allow custom built-in directory and user directory
+    // In production, use autopm/.claude/templates and .claude/templates
+    this.builtInDir = builtInDir || path.join(__dirname, '..', 'autopm', '.claude', 'templates');
+    this.userDir = userDir || path.join('.claude', 'templates');
+  }
+
+  /**
+   * Find template by name
+   * Priority: user templates > built-in templates
+   *
+   * @param {string} type - Template type (prds/epics/tasks)
+   * @param {string} name - Template name (without .md extension)
+   * @returns {string|null} - Path to template or null if not found
+   */
+  findTemplate(type, name) {
+    const userPath = path.resolve(this.userDir, type, `${name}.md`);
+    const builtInPath = path.resolve(this.builtInDir, type, `${name}.md`);
+
+    if (fs.existsSync(userPath)) return userPath;
+    if (fs.existsSync(builtInPath)) return builtInPath;
+    return null;
+  }
+
+  /**
+   * List all available templates of a given type
+   *
+   * @param {string} type - Template type (prds/epics/tasks)
+   * @returns {Array<{name: string, custom: boolean}>}
+   */
+  listTemplates(type) {
+    const templates = [];
+
+    // Built-in templates
+    const builtInPath = path.join(this.builtInDir, type);
+    if (fs.existsSync(builtInPath)) {
+      const files = fs.readdirSync(builtInPath)
+        .filter(f => f.endsWith('.md'))
+        .map(f => ({ name: f.replace('.md', ''), custom: false }));
+      templates.push(...files);
+    }
+
+    // User custom templates
+    const userPath = path.join(this.userDir, type);
+    if (fs.existsSync(userPath)) {
+      const files = fs.readdirSync(userPath)
+        .filter(f => f.endsWith('.md'))
+        .map(f => ({ name: f.replace('.md', ''), custom: true }));
+      templates.push(...files);
+    }
+
+    return templates;
+  }
+
+  /**
+   * Generate auto variables
+   *
+   * @returns {Object} - Auto-generated variables
+   */
+  generateAutoVariables() {
+    const now = new Date();
+    return {
+      id: '', // Will be set by generateId()
+      timestamp: now.toISOString(),
+      date: now.toISOString().split('T')[0],
+      author: process.env.USER || process.env.USERNAME || 'unknown'
+    };
+  }
+
+  /**
+   * Generate sequential ID
+   *
+   * @param {string} prefix - ID prefix (prd/epic/task)
+   * @param {string} directory - Directory to scan for existing IDs
+   * @returns {string} - Next sequential ID
+   */
+  generateId(prefix, directory) {
+    if (!fs.existsSync(directory)) {
+      return `${prefix}-001`;
+    }
+
+    const files = fs.readdirSync(directory)
+      .filter(f => f.startsWith(`${prefix}-`) && f.endsWith('.md'));
+
+    if (files.length === 0) {
+      return `${prefix}-001`;
+    }
+
+    // Extract numbers and find max
+    const numbers = files
+      .map(f => {
+        const match = f.match(new RegExp(`${prefix}-(\\d+)\\.md`));
+        return match ? parseInt(match[1], 10) : 0;
+      })
+      .filter(n => !isNaN(n));
+
+    const maxNum = Math.max(...numbers);
+    const nextNum = maxNum + 1;
+
+    return `${prefix}-${String(nextNum).padStart(3, '0')}`;
+  }
+
+  /**
+   * Render template with variables
+   *
+   * @param {string} template - Template string
+   * @param {Object} variables - Variables to substitute
+   * @returns {string} - Rendered template
+   */
+  render(template, variables) {
+    // Auto-generate variables
+    const autoVars = this.generateAutoVariables();
+
+    // Generate ID if not provided
+    if (!variables.id && !autoVars.id) {
+      // Try to infer type and directory from variables
+      const type = variables.type || 'item';
+      const directory = `.claude/${type}s`;
+      autoVars.id = this.generateId(type, directory);
+    }
+
+    const allVars = { ...autoVars, ...variables };
+
+    let content = template;
+
+    // Process loops first ({{#each}}...{{/each}})
+    content = this.processLoops(content, allVars);
+
+    // Process conditionals ({{#if}}...{{/if}})
+    content = this.processConditionals(content, allVars);
+
+    // Simple variable substitution ({{variable}})
+    for (const [key, value] of Object.entries(allVars)) {
+      const regex = new RegExp(`\\{\\{${key}\\}\\}`, 'g');
+      content = content.replace(regex, value || '');
+    }
+
+    // Replace any remaining {{variables}} that weren't in allVars with empty string
+    content = content.replace(/\{\{(\w+)\}\}/g, '');
+
+    return content;
+  }
+
+  /**
+   * Render template from file
+   *
+   * @param {string} templatePath - Path to template file
+   * @param {Object} variables - Variables to substitute
+   * @returns {string} - Rendered template
+   */
+  renderFile(templatePath, variables) {
+    const template = fs.readFileSync(templatePath, 'utf8');
+    return this.render(template, variables);
+  }
+
+  /**
+   * Process conditionals {{#if var}}...{{/if}}
+   *
+   * @param {string} content - Template content
+   * @param {Object} vars - Variables
+   * @returns {string} - Processed content
+   */
+  processConditionals(content, vars) {
+    // Match {{#if variable}}...{{/if}} - process from inside out for nested conditionals
+    const ifRegex = /\{\{#if\s+(\w+)\}\}([\s\S]*?)\{\{\/if\}\}/;
+
+    let result = content;
+    let changed = true;
+    let iterations = 0;
+    const maxIterations = 100;
+
+    // Keep processing until no more conditionals found (handles nesting)
+    while (changed && iterations < maxIterations) {
+      iterations++;
+      changed = false;
+
+      const match = result.match(ifRegex);
+      if (match) {
+        const [fullMatch, varName, innerContent] = match;
+        const varValue = vars[varName];
+
+        // If variable is truthy, keep inner content; otherwise remove
+        const replacement = varValue ? innerContent : '';
+        result = result.replace(fullMatch, replacement);
+        changed = true;
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Process loops {{#each items}}...{{/each}}
+   *
+   * @param {string} content - Template content
+   * @param {Object} vars - Variables
+   * @returns {string} - Processed content
+   */
+  processLoops(content, vars) {
+    // Match {{#each variable}}...{{/each}}
+    // Limit inner content to 10,000 characters to prevent ReDoS
+    const eachRegex = /\{\{#each\s+(\w+)\}\}([\s\S]{0,10000}?)\{\{\/each\}\}/g;
+
+    let result = content;
+    let match;
+
+    // Safety counter
+    let iterations = 0;
+    const maxIterations = 100;
+
+    while ((match = eachRegex.exec(content)) !== null && iterations < maxIterations) {
+      iterations++;
+      const [fullMatch, varName, template] = match;
+      const items = vars[varName];
+
+      if (!Array.isArray(items)) {
+        // Not an array, remove the loop
+        result = result.replace(fullMatch, '');
+        continue;
+      }
+
+      // Render each item
+      let rendered = '';
+      for (const item of items) {
+        if (typeof item === 'object' && item !== null) {
+          // Object: replace {{property}} with object properties
+          let itemRendered = template;
+          for (const [key, value] of Object.entries(item)) {
+            const regex = new RegExp(`\\{\\{${key}\\}\\}`, 'g');
+            itemRendered = itemRendered.replace(regex, value || '');
+          }
+          rendered += itemRendered;
+        } else {
+          // Primitive: replace {{this}} with the value
+          rendered += template.replace(/\{\{this\}\}/g, item);
+        }
+      }
+
+      result = result.replace(fullMatch, rendered);
+    }
+
+    return result;
+  }
+
+  /**
+   * Validate template
+   *
+   * @param {string} template - Template string
+   * @returns {Object} - {valid: boolean, errors: string[]}
+   */
+  validate(template) {
+    const errors = [];
+
+    // Check frontmatter
+    if (!template.startsWith('---')) {
+      errors.push('Missing frontmatter');
+    }
+
+    // Check required variables
+    const requiredVars = ['id', 'title', 'type'];
+    for (const varName of requiredVars) {
+      if (!template.includes(`{{${varName}}}`)) {
+        errors.push(`Missing required variable: {{${varName}}}`);
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+
+  /**
+   * Ensure template directory exists
+   *
+   * @param {string} type - Template type (prds/epics/tasks)
+   */
+  ensureTemplateDir(type) {
+    const dir = path.join(this.userDir, type);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+  }
+}
+
+module.exports = TemplateEngine;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-autopm",
-  "version": "1.27.0",
+  "version": "1.28.0",
   "description": "Autonomous Project Management Framework for Claude Code - Advanced AI-powered development automation",
   "main": "bin/autopm.js",
   "bin": {