ai-flow-dev 1.0.1

package/templates/frontend/README.template.md

@@ -0,0 +1,121 @@
+# {{PROJECT_NAME}}
+
+> {{PROJECT_DESCRIPTION}}
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Node.js {{NODE_VERSION}} or higher
+- {{PACKAGE_MANAGER}} (npm/yarn/pnpm)
+
+### Installation
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd {{PROJECT_NAME}}
+
+# Install dependencies
+{{PACKAGE_MANAGER}} install
+
+# Start development server
+{{PACKAGE_MANAGER}} run dev
+```
+
+### Environment Setup
+
+Copy `.env.example` to `.env` and configure:
+
+```bash
+cp .env.example .env
+```
+
+See `specs/configuration.md` for all environment variables.
+
+---
+
+## 📁 Project Structure
+
+```
+{{FOLDER_STRUCTURE}}
+```
+
+---
+
+## 🛠️ Development
+
+### Available Scripts
+
+- `{{PACKAGE_MANAGER}} run dev` - Start development server
+- `{{PACKAGE_MANAGER}} run build` - Build for production
+- `{{PACKAGE_MANAGER}} run preview` - Preview production build
+- `{{PACKAGE_MANAGER}} run test` - Run tests
+- `{{PACKAGE_MANAGER}} run lint` - Run linter
+- `{{PACKAGE_MANAGER}} run format` - Format code
+
+### Tech Stack
+
+- **Framework:** {{UI_FRAMEWORK}} {{UI_FRAMEWORK_VERSION}}
+- **Build Tool:** {{BUILD_TOOL}}
+- **Styling:** {{STYLING_APPROACH}}
+- **State Management:** {{STATE_MANAGEMENT}}
+- **Testing:** {{UNIT_TEST_FRAMEWORK}}, {{E2E_FRAMEWORK}}
+
+See `ai-instructions.md` for complete tech stack.
+
+---
+
+## 📚 Documentation
+
+**For AI Assistants:**
+- `AGENT.md` - Start here for AI context
+- `ai-instructions.md` - Tech stack and rules
+
+**For Developers:**
+- `docs/components.md` - Component architecture
+- `docs/state-management.md` - State patterns
+- `docs/styling.md` - Styling guidelines
+- `docs/testing.md` - Testing strategy
+- `specs/accessibility.md` - A11y requirements
+
+---
+
+## 🧪 Testing
+
+```bash
+# Run all tests
+{{PACKAGE_MANAGER}} run test
+
+# Run with coverage
+{{PACKAGE_MANAGER}} run test:coverage
+
+# Run E2E tests
+{{PACKAGE_MANAGER}} run test:e2e
+```
+
+---
+
+## 🚢 Deployment
+
+{{DEPLOYMENT_INSTRUCTIONS}}
+
+See `docs/operations.md` for detailed deployment procedures.
+
+---
+
+## 🤝 Contributing
+
+See `docs/contributing.md` for contribution guidelines.
+
+---
+
+## 📄 License
+
+{{LICENSE}}
+
+---
+
+**Last Updated:** {{GENERATION_DATE}}

package/templates/frontend/ai-instructions.template.md

@@ -0,0 +1,368 @@
+# AI Instructions - Frontend
+
+> **CRITICAL:** Every AI assistant MUST read and follow this document before any work.
+
+---
+
+## 🎯 Project Overview
+
+**Name:** {{PROJECT_NAME}}
+
+**Description:** {{PROJECT_DESCRIPTION}}
+
+**Purpose:** {{PROBLEM_STATEMENT}}
+
+**Target Users:** {{TARGET_USERS}}
+
+---
+
+## 🏗️ Tech Stack
+
+### Frontend
+
+- **UI Framework:** {{UI_FRAMEWORK}} {{UI_FRAMEWORK_VERSION}}
+- **Meta Framework:** {{META_FRAMEWORK}}
+- **Language:** {{LANGUAGE}} {{LANGUAGE_VERSION}}
+- **Build Tool:** {{BUILD_TOOL}}
+- **Package Manager:** {{PACKAGE_MANAGER}}
+
+### UI & Components
+
+- **Component Pattern:** {{COMPONENT_PATTERN}}
+- **Component Library:** {{COMPONENT_LIBRARY}}
+- **Form Management:** {{FORM_LIBRARY}}
+- **Icon System:** {{ICON_SYSTEM}}
+
+### State Management
+
+- **State Solution:** {{STATE_MANAGEMENT}}
+- **Data Fetching:** {{DATA_FETCHING}}
+- **Cache Strategy:** {{CACHE_STRATEGY}}
+
+### Styling
+
+- **Styling Approach:** {{STYLING_APPROACH}}
+- **CSS Preprocessor:** {{CSS_PREPROCESSOR}}
+- **Design Tokens:** {{DESIGN_TOKENS}}
+- **Theme Support:** {{THEME_SUPPORT}}
+
+### Routing
+
+- **Router:** {{ROUTING_LIBRARY}}
+- **Route Strategy:** {{ROUTE_STRATEGY}}
+
+### Testing
+
+- **Unit Testing:** {{UNIT_TEST_FRAMEWORK}}
+- **Component Testing:** {{COMPONENT_TEST_LIBRARY}}
+- **E2E Testing:** {{E2E_FRAMEWORK}}
+- **Coverage Target:** {{TEST_COVERAGE_TARGET}}
+
+### Build & Deployment
+
+- **Deployment:** {{DEPLOYMENT_PLATFORM}}
+- **CI/CD:** {{CICD_PLATFORM}}
+- **CDN:** {{CDN_PROVIDER}}
+- **Analytics:** {{ANALYTICS_TOOL}}
+
+---
+
+## 🏛️ Architecture
+
+**Component Pattern:** {{COMPONENT_PATTERN}}
+
+{{ARCHITECTURE_DESCRIPTION}}
+
+**File Organization:** {{FILE_ORGANIZATION}}
+
+**Folder Structure:**
+```
+{{FOLDER_STRUCTURE}}
+```
+
+---
+
+## ❌ NEVER Rules
+
+**YOU MUST NEVER:**
+
+### Performance
+
+- ❌ Import entire libraries - Use tree-shaking friendly imports
+  ```typescript
+  // Bad
+  import _ from 'lodash';
+  // Good
+  import debounce from 'lodash/debounce';
+  ```
+
+- ❌ Render large lists without virtualization - Use react-window, vue-virtual-scroller
+- ❌ Forget to memoize expensive computations - Use useMemo, computed
+- ❌ Load all routes upfront - Use code splitting and lazy loading
+- ❌ Use inline function props in render - Define outside or use useCallback (React)
+- ❌ Skip image optimization - Use next/image, nuxt/image, or optimize manually
+- ❌ Ignore bundle size - Monitor and optimize regularly
+- ❌ Fetch data in loops - Batch requests or use GraphQL
+
+### Accessibility (WCAG {{A11Y_COMPLIANCE}})
+
+- ❌ Use divs for buttons - Use semantic HTML (`<button>`, `<a>`)
+- ❌ Forget alt text on images - Every `<img>` needs descriptive alt
+- ❌ Skip keyboard navigation support - All interactive elements must be keyboard accessible
+- ❌ Ignore color contrast ratios - Minimum 4.5:1 for text (WCAG AA)
+- ❌ Remove focus outlines without replacement - Provide visible focus indicators
+- ❌ Skip ARIA labels on icon buttons - Use aria-label or sr-only text
+- ❌ Use placeholder as label - Labels must be visible, not just placeholder
+- ❌ Forget to test with screen readers - Test with NVDA, JAWS, or VoiceOver
+
+### Security
+
+- ❌ Trust user input - Sanitize everything to prevent XSS
+  ```typescript
+  // Bad - XSS vulnerability
+  div.innerHTML = userInput;
+  // Good - sanitized
+  div.textContent = userInput;
+  ```
+
+- ❌ Store sensitive data in localStorage - Use httpOnly cookies for tokens
+- ❌ Expose API keys in frontend code - Use environment variables + backend proxy
+- ❌ Skip CSRF protection for forms - Use CSRF tokens
+- ❌ Allow dangerous HTML in user content - Use DOMPurify or similar
+- ❌ Log sensitive user data - Sanitize logs and avoid PII
+- ❌ Use eval() or Function() constructor - Major security risk
+- ❌ Ignore Content Security Policy - Configure CSP headers
+
+### Code Quality
+
+- ❌ Use inline styles (except dynamic values) - Use {{STYLING_APPROACH}}
+- ❌ Create massive components (>300 lines) - Split into smaller components
+- ❌ Mutate state directly - Use immutable updates
+  ```typescript
+  // Bad (React)
+  state.items.push(newItem);
+  // Good
+  setState({ items: [...state.items, newItem] });
+  ```
+
+- ❌ Use `any` type in TypeScript - Always use proper types
+- ❌ Nest ternary operators - Use if-else or early returns
+- ❌ Put business logic in components - Extract to hooks, composables, or services
+- ❌ Skip error boundaries - Wrap component trees with error handlers
+- ❌ Leave console.log in production - Use proper logging or remove
+
+### State Management
+
+- ❌ Prop drill more than 2-3 levels - Use context, provide/inject, or state management
+- ❌ Store derived data in state - Compute on the fly
+- ❌ Forget to clean up subscriptions - Unsubscribe in useEffect cleanup, onUnmounted
+- ❌ Use global state for everything - Keep state as local as possible
+- ❌ Update state during render - Use effects or event handlers
+
+### API Integration
+
+- ❌ Make API calls directly in components - Use custom hooks, composables, or services
+- ❌ Forget loading and error states - Always handle both
+- ❌ Skip request cancellation - Cancel pending requests on unmount
+- ❌ Expose backend errors to users - Show user-friendly messages
+- ❌ Ignore rate limiting - Debounce/throttle frequent requests
+
+### Styling
+
+- ❌ Use !important unless absolutely necessary - Fix specificity instead
+- ❌ Hardcode pixel values everywhere - Use design tokens, CSS variables
+- ❌ Forget responsive design - Mobile-first approach
+- ❌ Ignore dark mode support (if {{THEME_SUPPORT}} includes dark mode)
+- ❌ Use RGB hex colors directly - Use CSS variables or design tokens
+
+---
+
+## ✅ ALWAYS Rules
+
+**YOU MUST ALWAYS:**
+
+### Component Design
+
+- ✅ Keep components focused on one responsibility
+- ✅ Use TypeScript for type safety
+- ✅ Write PropTypes or TypeScript interfaces for props
+- ✅ Provide default props where sensible
+- ✅ Document complex components with JSDoc
+- ✅ Use meaningful, descriptive component names (PascalCase)
+
+### Performance
+
+- ✅ Implement code splitting for routes
+  ```typescript
+  // React
+  const Dashboard = lazy(() => import('./Dashboard'));
+  // Vue
+  const Dashboard = defineAsyncComponent(() => import('./Dashboard.vue'));
+  ```
+
+- ✅ Optimize images (WebP format, lazy loading)
+- ✅ Monitor Core Web Vitals: {{WEB_VITALS_TARGETS}}
+- ✅ Use production builds for deployment
+- ✅ Implement proper caching strategies
+- ✅ Debounce search inputs and expensive operations
+
+### Accessibility
+
+- ✅ Use semantic HTML elements
+- ✅ Add ARIA attributes when needed
+- ✅ Ensure keyboard navigation works
+- ✅ Test with keyboard only (Tab, Enter, Escape)
+- ✅ Provide text alternatives for non-text content
+- ✅ Use proper heading hierarchy (h1 → h2 → h3)
+- ✅ Announce dynamic content changes to screen readers
+
+### State Management
+
+- ✅ Keep state as close as possible to where it's used
+- ✅ Use {{STATE_MANAGEMENT}} for global state
+- ✅ Normalize complex nested state
+- ✅ Use {{DATA_FETCHING}} for server state
+- ✅ Implement optimistic updates for better UX
+
+### Error Handling
+
+- ✅ Wrap component trees with error boundaries
+- ✅ Show user-friendly error messages
+- ✅ Log errors to monitoring service ({{MONITORING_TOOL}})
+- ✅ Provide fallback UI for errors
+- ✅ Handle network failures gracefully
+
+### Testing
+
+- ✅ Write tests for critical user paths
+- ✅ Test component behavior, not implementation
+- ✅ Mock external dependencies (API calls)
+- ✅ Test accessibility (screen reader compatibility)
+- ✅ Achieve {{TEST_COVERAGE_TARGET}} coverage minimum
+- ✅ Run tests before committing
+
+### Code Organization
+
+- ✅ Follow {{COMPONENT_PATTERN}} structure
+- ✅ Co-locate related files (component + styles + tests)
+- ✅ Use absolute imports for cleaner code
+- ✅ Extract reusable logic to custom hooks/composables
+- ✅ Keep files under 300 lines
+
+### Styling
+
+- ✅ Use {{STYLING_APPROACH}} consistently
+- ✅ Follow mobile-first responsive design
+- ✅ Use CSS variables / design tokens for theming
+- ✅ Ensure dark mode compatibility (if enabled)
+- ✅ Test on multiple screen sizes
+
+### Forms
+
+- ✅ Use {{FORM_LIBRARY}} for complex forms
+- ✅ Validate on blur and submit
+- ✅ Show validation errors inline
+- ✅ Disable submit during submission
+- ✅ Provide clear error messages
+- ✅ Use proper input types (email, tel, number)
+
+### API Integration
+
+- ✅ Use {{DATA_FETCHING}} for server data
+- ✅ Handle loading, success, and error states
+- ✅ Implement proper error messages
+- ✅ Cache responses when appropriate
+- ✅ Cancel requests on component unmount
+
+---
+
+## 🎨 Code Style
+
+### Naming Conventions
+
+- **Components:** PascalCase (`UserProfile.tsx`)
+- **Hooks/Composables:** camelCase with prefix (`useAuth`, `useCounter`)
+- **Utilities:** camelCase (`formatDate`, `validateEmail`)
+- **Constants:** UPPER_SNAKE_CASE (`API_BASE_URL`)
+- **CSS Classes:** {{CSS_NAMING_CONVENTION}}
+
+### File Structure
+
+```
+{{FILE_STRUCTURE_EXAMPLE}}
+```
+
+### Import Order
+
+1. External libraries (react, vue, etc.)
+2. Internal libraries (@/components, @/hooks)
+3. Relative imports (./Button, ../utils)
+4. Styles
+5. Types (if separate file)
+
+---
+
+## 🚀 Development Workflow
+
+### Before Starting Any Task
+
+1. Read this document completely
+2. Check `docs/components.md` for component patterns
+3. Review `docs/state-management.md` for state patterns
+4. Check `docs/styling.md` for styling guidelines
+
+### When Creating Components
+
+1. Start with TypeScript interface for props
+2. Implement component logic
+3. Add styles using {{STYLING_APPROACH}}
+4. Write component tests
+5. Update Storybook/documentation (if applicable)
+
+### When Adding Features
+
+1. Design component hierarchy
+2. Identify state needs (local vs global)
+3. Plan API integration
+4. Implement with tests
+5. Test accessibility
+6. Check performance impact
+
+### Before Committing
+
+- ✅ Run linter: `npm run lint`
+- ✅ Run tests: `npm test`
+- ✅ Build succeeds: `npm run build`
+- ✅ No console.log statements
+- ✅ No commented code
+
+---
+
+## 📊 Performance Targets
+
+**Core Web Vitals:**
+- LCP (Largest Contentful Paint): {{LCP_TARGET}}
+- FID (First Input Delay): {{FID_TARGET}}
+- CLS (Cumulative Layout Shift): {{CLS_TARGET}}
+
+**Bundle Size:**
+- Initial bundle: {{INITIAL_BUNDLE_TARGET}}
+- Route bundles: {{ROUTE_BUNDLE_TARGET}}
+
+---
+
+## 🔗 Related Documents
+
+- [Component Architecture](docs/components.md) - Component patterns and structure
+- [State Management](docs/state-management.md) - State management guidelines
+- [Styling Guide](docs/styling.md) - Styling conventions
+- [Testing Strategy](docs/testing.md) - Testing approach
+- [API Integration](docs/api-integration.md) - API communication patterns
+- [Performance](docs/performance.md) - Performance optimization
+- [Accessibility](specs/accessibility.md) - WCAG compliance details
+
+---
+
+**Last Updated:** {{GENERATION_DATE}}
+
+**Framework:** {{UI_FRAMEWORK}} {{UI_FRAMEWORK_VERSION}}