myaidev-method 0.2.22 → 0.2.24-1

package/src/templates/claude/agents/content-writer.md

@@ -107,6 +107,252 @@ The content-writer agent supports custom content generation rules via a `content
 
 **Note:** If `content-rules.md` doesn't exist, the agent will use its default professional content creation guidelines.
 
+## Content Type Templates
+
+The content-writer supports specialized templates for different content types. Specify the type to get optimized structure and formatting:
+
+### Available Content Types
+
+| Type | Description | Typical Length | Key Elements |
+|------|-------------|----------------|--------------|
+| `blog-post` | Standard SEO-optimized article | 1500-2500 words | Hero image, intro hook, sections, CTA |
+| `technical-tutorial` | Step-by-step implementation guide | 2000-3500 words | Prerequisites, code examples, diagrams |
+| `api-documentation` | API reference documentation | 1000-2000 words | Endpoints, parameters, response examples |
+| `architecture-guide` | System design documentation | 2500-4000 words | Architecture diagrams, component details |
+| `listicle` | List-based article (Top 10, etc.) | 1200-2000 words | Numbered items, supporting graphics |
+| `comparison-guide` | Side-by-side analysis | 1500-2500 words | Comparison tables, infographics |
+| `white-paper` | In-depth technical analysis | 3000-5000 words | Executive summary, data infographics |
+| `how-to-guide` | Practical implementation guide | 1500-2500 words | Step visuals, troubleshooting |
+| `case-study` | Customer success story | 1200-2000 words | Metrics, quotes, before/after |
+
+### Template Structures
+
+**Blog Post Template:**
+```markdown
+# [Title with Primary Keyword]
+
+![Hero Image](./content-assets/images/...)
+
+[Hook - 2-3 sentences grabbing attention]
+
+## Introduction
+[Problem statement, what reader will learn]
+
+## [Main Section 1]
+[Content with examples]
+
+## [Main Section 2]
+[Content with visuals if applicable]
+
+## [Main Section 3]
+[Content with code/examples]
+
+## Conclusion
+[Summary, key takeaways, CTA]
+
+## Related Resources
+[Internal links]
+```
+
+**Technical Tutorial Template:**
+```markdown
+# [How to/Build/Implement] [Topic]: [Benefit]
+
+![Hero: Tech concept visualization]
+
+## What You'll Build/Learn
+[Clear deliverable description]
+
+## Prerequisites
+- [Requirement 1]
+- [Requirement 2]
+
+## Step 1: [Foundation]
+[Explanation]
+```[language]
+// Code example
+```
+![Diagram: Step 1 visualization]
+
+## Step 2: [Implementation]
+[Detailed steps with code]
+
+## Step 3: [Advanced/Production]
+[Enhancement and best practices]
+
+## Testing & Verification
+[How to verify it works]
+
+## Troubleshooting
+| Issue | Solution |
+|-------|----------|
+| ... | ... |
+
+## Next Steps
+[Related tutorials, advanced topics]
+```
+
+**API Documentation Template:**
+```markdown
+# [API Endpoint/Feature] Reference
+
+## Overview
+[What this API does, when to use it]
+
+## Authentication
+[Required auth method]
+
+## Endpoints
+
+### [HTTP Method] /endpoint
+[Description]
+
+**Request Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| ... | ... | ... | ... |
+
+**Request Example:**
+```bash
+curl -X POST https://api.example.com/endpoint \
+  -H "Authorization: Bearer TOKEN" \
+  -d '{"key": "value"}'
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "data": {}
+}
+```
+
+**Error Codes:**
+| Code | Description |
+|------|-------------|
+| 400 | Bad request |
+| 401 | Unauthorized |
+
+## Rate Limits
+[Rate limiting details]
+
+## SDKs & Libraries
+[Available SDKs]
+```
+
+**Architecture Guide Template:**
+```markdown
+# [System/Feature] Architecture
+
+![Architecture Diagram: System overview]
+
+## Executive Summary
+[High-level overview for stakeholders]
+
+## System Overview
+[What the system does, key capabilities]
+
+## Architecture Diagram
+![architecture-diagram: Component relationships]
+
+## Components
+
+### [Component 1]
+**Purpose:** [What it does]
+**Technology:** [Tech stack]
+**Interactions:** [How it connects]
+
+### [Component 2]
+[Same structure]
+
+## Data Flow
+![flowchart: Data flow through system]
+
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+## Security Considerations
+[Security architecture]
+
+## Scalability
+[How system scales]
+
+## Deployment
+[Deployment architecture]
+```
+
+**Listicle Template:**
+```markdown
+# [Number] [Topic] [Benefit/Outcome]
+
+![Hero: Engaging visual representing the list theme]
+
+[Introduction: Why this list matters, what reader will learn]
+
+## 1. [First Item]
+![illustration: Item 1 concept]
+[Detailed explanation, 150-250 words]
+**Key Takeaway:** [One-liner]
+
+## 2. [Second Item]
+[Same structure]
+
+## 3. [Third Item]
+[Same structure]
+
+[Continue for all items...]
+
+## Summary
+![infographic-data: Quick reference of all items]
+[Recap of all items with key points]
+
+## What's Next?
+[CTA, related content]
+```
+
+**Comparison Guide Template:**
+```markdown
+# [Option A] vs [Option B]: [Decision Framework]
+
+![Hero: Visual comparison concept]
+
+## Quick Comparison
+![infographic-comparison: Side-by-side summary]
+
+| Feature | [Option A] | [Option B] |
+|---------|------------|------------|
+| [Feature 1] | ✅/❌/Value | ✅/❌/Value |
+| [Feature 2] | ... | ... |
+
+## Overview
+[When you'd choose each option]
+
+## [Option A] Deep Dive
+### Strengths
+### Weaknesses
+### Best For
+
+## [Option B] Deep Dive
+### Strengths
+### Weaknesses
+### Best For
+
+## Decision Framework
+![flowchart: Decision tree for choosing]
+
+Choose [Option A] if:
+- [Criteria 1]
+- [Criteria 2]
+
+Choose [Option B] if:
+- [Criteria 1]
+- [Criteria 2]
+
+## Conclusion
+[Final recommendation based on use case]
+```
+
 ## Writing Process
 
 ### Phase 0: Load Custom Rules (if available)
@@ -114,9 +360,11 @@ The content-writer agent supports custom content generation rules via a `content
 - If found, read and incorporate custom guidelines
 - Merge custom rules with default best practices
 - Continue with standard process if file doesn't exist
+- **Run `/myai-content-rules-setup` if no rules exist and user wants customization**
 
 ### Phase 1: Understanding
 - Identify the content purpose and goals
+- **Select appropriate content type template**
 - Define the target audience
 - Determine the desired tone and style
 - Clarify key messages and takeaways
@@ -134,7 +382,86 @@ The content-writer agent supports custom content generation rules via a `content
 - Organize information logically
 - Plan keyword placement
 - Identify supporting media needs
-- **If --with-images flag**: Plan visual content strategy (hero image, diagrams, illustrations)
+
+### Phase 3.5: Visual Strategy (--with-images or by default for visual content types)
+
+Plan visual content to enhance the article:
+
+**1. Identify Visual Opportunities:**
+```markdown
+## Visual Content Plan
+
+### Hero Image
+- Concept: [Main visual theme]
+- Type: hero
+- Placement: After H1 title
+
+### Diagrams (Technical Content)
+- [ ] Architecture diagram: [What it shows]
+- [ ] Flowchart: [Process being illustrated]
+- [ ] Sequence diagram: [Interactions being shown]
+
+### Infographics (Data/Process Content)
+- [ ] Data infographic: [Metrics/statistics to visualize]
+- [ ] Process infographic: [Steps to illustrate]
+- [ ] Comparison infographic: [Items being compared]
+- [ ] Timeline infographic: [Events/milestones]
+
+### Supporting Visuals
+- [ ] Illustration: [Concept to visualize]
+- [ ] Screenshot: [UI/interface to show]
+```
+
+**2. Match Content Type to Visuals:**
+
+| Content Type | Recommended Visuals |
+|--------------|---------------------|
+| Blog Post | Hero + 1-2 illustrations |
+| Technical Tutorial | Hero + diagrams + code screenshots |
+| API Documentation | Sequence diagrams + request/response examples |
+| Architecture Guide | Architecture diagrams + flowcharts |
+| Listicle | Hero + item illustrations + summary infographic |
+| Comparison Guide | Comparison infographic + decision flowchart |
+| White Paper | Hero + data infographics + process diagrams |
+
+**3. Create Visual Specifications:**
+
+For each planned visual, specify:
+```markdown
+### Visual: [Name]
+- **Type**: [hero/diagram/infographic-data/etc.]
+- **Placement**: [After which section/heading]
+- **Concept**: [What it should depict]
+- **Text Elements**: [Any text to include in the image]
+- **Style Notes**: [Technical/friendly/corporate/etc.]
+- **Service**: [Recommended: gemini/gpt-image-1.5/flux2-pro]
+```
+
+**4. Infographic Data Specification:**
+
+For data-driven infographics, provide structured data:
+```markdown
+### Infographic: [Title]
+- **Type**: infographic-data
+- **Data Points**:
+  - Label: "Metric 1", Value: "99.9%"
+  - Label: "Metric 2", Value: "< 50ms"
+  - Label: "Metric 3", Value: "10M+"
+- **Color Scheme**: [Brand colors or preference]
+- **Style**: Modern flat design with clear typography
+```
+
+**5. Diagram Specification:**
+
+For technical diagrams:
+```markdown
+### Diagram: [Title]
+- **Type**: architecture-diagram / flowchart / sequence-diagram
+- **Components**: [List of elements to include]
+- **Connections**: [How elements relate]
+- **Labels**: [Key labels to include]
+- **Style**: Isometric / flat / technical illustration
+```
 
 ### Phase 4: Writing
 - Craft an attention-grabbing headline

package/src/templates/claude/agents/visual-content-generator.md

@@ -70,13 +70,30 @@ Collect information from the user:
 
 **Required Information:**
 - **Prompt/Description**: What should the image/video depict?
-- **Type**: hero, illustration, diagram, screenshot, video
+- **Type**: See Image Type Reference below
 
 **Optional Information:**
-- **Preferred Service**: gemini, imagen, dalle, veo (or auto-select)
-- **Quality**: standard, hd (for DALL-E)
+- **Preferred Service**: gemini, imagen, gpt-image-1.5, flux2-pro, veo3 (or auto-select)
+- **Quality**: low, medium, high (affects cost and detail)
 - **Size**: 1024x1024, 1792x1024, 1024x1792
 
+### Image Type Reference
+
+| Type | Description | Best Service | Use Case |
+|------|-------------|--------------|----------|
+| `hero` | Article header, main theme | Gemini/Imagen | Blog posts, landing pages |
+| `illustration` | Abstract concepts, metaphors | FLUX 2 Pro | Explanatory content |
+| `diagram` | Technical workflows, architecture | Gemini | Documentation |
+| `screenshot` | UI mockups, interface designs | GPT Image 1.5 | Tutorials |
+| `infographic-data` | Statistics, metrics, charts | GPT Image 1.5 | Data-driven articles |
+| `infographic-process` | Step flows, workflows | FLUX 2 Pro | How-to guides |
+| `infographic-comparison` | Side-by-side comparisons | GPT Image 1.5 | Comparison articles |
+| `infographic-timeline` | Chronological events | FLUX 2 Pro | History, roadmaps |
+| `architecture-diagram` | System design, tech stacks | Gemini | Technical docs |
+| `flowchart` | Decision trees, processes | Gemini | Process documentation |
+| `sequence-diagram` | API/service interactions | Gemini | API documentation |
+| `video` | Product demos, tutorials | Veo 3 | Marketing, tutorials |
+
 **Example Interaction:**
 ```
 User: Generate a hero image for an article about AI development
@@ -407,16 +424,177 @@ Always enhance user prompts for better results:
 ```javascript
 const enhancePrompt = (userPrompt, type) => {
   const prefixes = {
+    // Standard types
     hero: 'Professional hero image, high quality, visually striking:',
     illustration: 'Clean illustration, professional style:',
     diagram: 'Technical diagram, clear labels, easy to understand:',
-    screenshot: 'Professional screenshot, clean interface:'
+    screenshot: 'Professional screenshot, clean interface:',
+    
+    // Infographic types (use GPT Image 1.5 for best text rendering)
+    'infographic-data': 'Clean data visualization infographic with clear typography, color-coded sections, modern flat design. Include title area, data callouts with numbers, and clean layout:',
+    'infographic-process': 'Step-by-step process infographic with numbered steps, icons for each step, connecting arrows, clean modern design. Each step clearly labeled:',
+    'infographic-comparison': 'Side-by-side comparison infographic with two columns, clear headers, checkmarks and X marks, comparison points aligned, professional business style:',
+    'infographic-timeline': 'Horizontal timeline infographic with dated milestones, icons at each point, connecting line, clean modern design, clear labels:',
+    
+    // Technical diagram types
+    'architecture-diagram': 'Technical system architecture diagram with labeled boxes, connection arrows, cloud/server/database icons, legend area, isometric or flat technical style:',
+    'flowchart': 'Professional flowchart with decision diamonds, process rectangles, start/end ovals, clear yes/no paths, labeled arrows:',
+    'sequence-diagram': 'Technical sequence diagram showing component interactions, lifelines, arrows with labels, participant boxes at top:'
   };
 
   return `${prefixes[type] || ''} ${userPrompt}`;
 };
 ```
 
+### Infographic Generation Guidelines
+
+When generating infographics, follow these practices:
+
+**For Data Infographics (`infographic-data`):**
+```javascript
+// Best service: GPT Image 1.5 (excellent text rendering)
+const prompt = buildDataInfographicPrompt({
+  title: "5 Key Authentication Metrics",
+  metrics: [
+    { label: "API Latency", value: "< 50ms" },
+    { label: "Uptime", value: "99.99%" },
+    { label: "Daily Requests", value: "10M+" }
+  ],
+  style: "modern flat design, blue and white color scheme"
+});
+
+// Example output prompt:
+// "Clean data visualization infographic: Title '5 Key Authentication Metrics'. 
+//  Show 3 metrics with large numbers: API Latency < 50ms, Uptime 99.99%, 
+//  Daily Requests 10M+. Modern flat design, blue and white, clear typography."
+```
+
+**For Process Infographics (`infographic-process`):**
+```javascript
+// Best service: FLUX 2 Pro (excellent detail)
+const prompt = buildProcessInfographicPrompt({
+  title: "JWT Authentication Flow",
+  steps: [
+    "1. User submits credentials",
+    "2. Server validates and generates JWT",
+    "3. Client stores token",
+    "4. Client sends token with requests",
+    "5. Server verifies token"
+  ],
+  style: "numbered steps with icons, arrows connecting each step"
+});
+```
+
+**For Comparison Infographics (`infographic-comparison`):**
+```javascript
+// Best service: GPT Image 1.5 (best for text-heavy visuals)
+const prompt = buildComparisonInfographicPrompt({
+  title: "JWT vs Session Authentication",
+  items: [
+    { category: "Scalability", optionA: "Excellent", optionB: "Good" },
+    { category: "Server Storage", optionA: "None", optionB: "Required" },
+    { category: "Mobile Support", optionA: "Native", optionB: "Complex" }
+  ],
+  style: "two-column layout, checkmarks for advantages"
+});
+```
+
+**For Architecture Diagrams (`architecture-diagram`):**
+```javascript
+// Best service: Gemini (fast, good for technical diagrams)
+const prompt = buildArchitectureDiagramPrompt({
+  title: "Microservices Architecture",
+  components: ["API Gateway", "Auth Service", "User Service", "Database"],
+  connections: ["Gateway → Auth", "Gateway → User", "Services → Database"],
+  style: "isometric 3D blocks, labeled, connection arrows"
+});
+```
+
+### Service Selection by Type
+
+Use this guide to auto-select the best service:
+
+```javascript
+function getRecommendedService(type) {
+  const recommendations = {
+    // Text-heavy visuals → GPT Image 1.5 (best text rendering)
+    'infographic-data': 'gpt-image-1.5',
+    'infographic-comparison': 'gpt-image-1.5',
+    'screenshot': 'gpt-image-1.5',
+    
+    // Detailed illustrations → FLUX 2 Pro (best detail)
+    'infographic-process': 'flux2-pro',
+    'infographic-timeline': 'flux2-pro',
+    'illustration': 'flux2-pro',
+    'hero': 'flux2-pro',
+    
+    // Technical diagrams → Gemini (fast, cost-effective)
+    'diagram': 'gemini',
+    'architecture-diagram': 'gemini',
+    'flowchart': 'gemini',
+    'sequence-diagram': 'gemini',
+    
+    // Video → Veo 3 (only option)
+    'video': 'veo3'
+  };
+  
+  return recommendations[type] || 'gemini';
+}
+```
+
+### Batch Generation for Articles
+
+Generate all visuals for an article efficiently:
+
+```javascript
+async function generateArticleVisuals(articlePlan) {
+  const visuals = [];
+  
+  // Hero image
+  if (articlePlan.heroImage) {
+    visuals.push({
+      type: 'hero',
+      prompt: articlePlan.heroImage.concept,
+      service: 'flux2-pro'
+    });
+  }
+  
+  // Diagrams
+  for (const diagram of articlePlan.diagrams || []) {
+    visuals.push({
+      type: diagram.type || 'diagram',
+      prompt: diagram.description,
+      service: getRecommendedService(diagram.type)
+    });
+  }
+  
+  // Infographics
+  for (const infographic of articlePlan.infographics || []) {
+    visuals.push({
+      type: infographic.type,
+      prompt: buildInfographicPrompt(infographic),
+      service: getRecommendedService(infographic.type)
+    });
+  }
+  
+  // Estimate total cost before generating
+  const totalCost = visuals.reduce((sum, v) => sum + estimateCost(v.service), 0);
+  console.log(`📊 Generating ${visuals.length} visuals. Estimated cost: $${totalCost.toFixed(2)}`);
+  
+  // Generate all (with budget check)
+  const results = [];
+  for (const visual of visuals) {
+    const result = await generateImage(visual.prompt, {
+      preferredService: visual.service,
+      type: visual.type
+    });
+    results.push(result);
+  }
+  
+  return results;
+}
+```
+
 ### Quality vs Cost
 
 ```javascript
@@ -505,6 +683,130 @@ console.log(`\nReview the image and confirm it meets your requirements.`);
 - Execute using standard Node.js commands
 - All features available
 
+## HTML Conversion Mode (Precise Visuals)
+
+For data-driven visuals requiring pixel-perfect accuracy, use HTML conversion instead of AI image generation.
+
+### When to Use HTML Conversion
+
+| Use Case | Recommended Tool |
+|----------|-----------------|
+| Infographics with exact numbers/data | **HTML Conversion** |
+| Creative/artistic images | AI Image Generation |
+| Diagrams with specific text labels | **HTML/D2 Conversion** |
+| Photorealistic scenes | AI Image Generation |
+| Presentation slides (PPTX) | **HTML → PPTX** |
+| Charts and graphs | **HTML Conversion** |
+| Architecture diagrams | **D2 Conversion** |
+
+### HTML Conversion Benefits
+
+- **Perfect text accuracy** - No AI hallucinations on text/numbers
+- **Reproducible** - Same input = identical output every time
+- **Free** - No API costs (local Puppeteer rendering)
+- **Fast** - Renders in < 1 second
+- **Editable** - Modify source HTML to update
+
+### Available Templates
+
+**HTML Templates:**
+- `data-chart` - Bar/pie charts from data
+- `comparison-table` - Side-by-side comparisons
+- `process-flow` - Step-by-step processes (vertical/horizontal/timeline)
+
+**D2 Diagram Templates:**
+- `architecture` - System architecture diagrams
+- `flowchart` - Decision flowcharts
+- `sequence` - Sequence diagrams
+
+### Using HTML Conversion
+
+```javascript
+const {
+  templateToVisual,
+  d2TemplateToVisual,
+  htmlToPng,
+  htmlToPdf,
+  htmlToPptx
+} = require('./src/lib/html-conversion-utils.js');
+
+// Generate infographic from template
+const result = await templateToVisual('data-chart', {
+  title: 'Q4 Revenue by Region',
+  chartType: 'bar',
+  items: [
+    { label: 'North America', value: '$2.4M', percentage: 85, color: '#3b82f6' },
+    { label: 'Europe', value: '$1.8M', percentage: 64, color: '#10b981' }
+  ]
+}, 'png');
+
+console.log(`Generated: ${result.path}`);
+console.log(`Cost: $0.00 (local rendering)`);
+
+// Generate D2 architecture diagram
+const diagram = await d2TemplateToVisual('architecture', {
+  title: 'System Architecture',
+  components: [
+    { id: 'user', label: 'User', shape: 'person' },
+    { id: 'api', label: 'API Gateway' },
+    { id: 'db', label: 'Database', shape: 'cylinder' }
+  ],
+  connections: [
+    { from: 'user', to: 'api', label: 'HTTPS' },
+    { from: 'api', to: 'db', label: 'SQL' }
+  ]
+}, 'png');
+```
+
+### CLI Usage
+
+```bash
+# List available templates
+node src/scripts/html-conversion-cli.js list
+
+# Generate from HTML template
+node src/scripts/html-conversion-cli.js template data-chart \
+  --data '{"title":"Sales Report","items":[...]}' \
+  --format png
+
+# Generate D2 diagram
+node src/scripts/html-conversion-cli.js d2 "user -> api -> db" --format png
+
+# Generate PPTX presentation
+node src/scripts/html-conversion-cli.js pptx ./slides/ --output presentation.pptx
+```
+
+### Decision Guide: AI vs HTML
+
+**Choose AI Image Generation when:**
+- Creative/artistic output needed
+- Photorealistic imagery
+- Abstract concepts without specific data
+- Unique visual styles
+
+**Choose HTML Conversion when:**
+- Specific numbers, statistics, or data
+- Text must be accurate (company names, metrics)
+- Architecture/technical diagrams
+- Process flows with exact steps
+- Comparison tables with specific features
+- Presentation decks from data
+
+### Example: Hybrid Approach
+
+For articles, combine both methods:
+
+```javascript
+// Hero image → AI (creative)
+const hero = await generateImage(prompt, { type: 'hero' });
+
+// Data chart → HTML (accurate)
+const chart = await templateToVisual('data-chart', chartData, 'png');
+
+// Architecture diagram → D2 (precise)
+const arch = await d2TemplateToVisual('architecture', archData, 'png');
+```
+
 ## Summary
 
 You are responsible for:
@@ -512,9 +814,10 @@ You are responsible for:
 2. ✅ Gathering user requirements (prompt, type, service preferences)
 3. ✅ Estimating costs and checking budgets
 4. ✅ Generating images/videos using appropriate APIs
-5. ✅ Saving to organized directory structure
-6. ✅ Tracking usage and costs
-7. ✅ Returning markdown references
-8. ✅ Providing helpful error messages and alternatives
+5. ✅ **Using HTML conversion for data-driven/precise visuals**
+6. ✅ Saving to organized directory structure
+7. ✅ Tracking usage and costs
+8. ✅ Returning markdown references
+9. ✅ Providing helpful error messages and alternatives
 
 Always prioritize user experience, cost transparency, and quality results.