grimoire-framework 1.0.0

package/.grimoire/docs/standards/EXECUTOR-DECISION-TREE.md

@@ -0,0 +1,698 @@
+# grimoire Executor Decision Tree
+
+**Date:** 2025-11-13  
+**Version:** 1.0.0  
+**Status:** Standard  
+**Author:** Brad Frost Cognitive Clone
+
+---
+
+## Purpose
+
+This document defines HOW to choose the appropriate executor type (Agente, Worker, Humano, Clone) for any grimoire Task based on task characteristics, requirements, and constraints.
+
+---
+
+## The Four Executor Types
+
+### 1. Agente (AI-Powered Execution)
+
+**Definition:** AI agent that uses Large Language Models to perform creative, analytical, or generative tasks.
+
+**When to use:**
+- Task requires creativity or subjective judgment
+- Task involves natural language understanding/generation
+- Task needs contextual analysis
+- Task has no deterministic algorithm
+
+**Examples:**
+- Analyze brief and extract key insights
+- Generate ad copy from brief
+- Design component styles based on brand
+- Select optimal template for campaign
+
+**Cost:** $$$$ High ($0.001 - $0.01 per execution)  
+**Speed:** Slow (3-10 seconds)  
+**Deterministic:** ❌ No (stochastic outputs)
+
+---
+
+### 2. Worker (Script-Based Execution)
+
+**Definition:** Deterministic script or function that transforms data using predefined logic.
+
+**When to use:**
+- Task is deterministic (same input → same output)
+- Task is a data transformation or validation
+- Task reads/writes files or databases
+- Task calls external APIs with no AI
+
+**Examples:**
+- Load configuration from JSON file
+- Validate HTML structure
+- Export PNG from HTML using Puppeteer
+- Calculate spacing based on safe zones
+
+**Cost:** $ Low ($0 - $0.001 per execution)  
+**Speed:** Fast (< 1 second)  
+**Deterministic:** ✅ Yes (same input → same output)
+
+---
+
+### 3. Humano (Manual Human Execution)
+
+**Definition:** Human operator who performs the task manually, often requiring subjective judgment or approval.
+
+**When to use:**
+- Task requires human subjective judgment
+- Task is a quality gate or approval step
+- Task involves sensitive decisions
+- Task cannot be automated (yet)
+
+**Examples:**
+- Review ad quality and approve/reject
+- Make strategic campaign decisions
+- Handle edge cases that AI can't resolve
+- Provide creative direction
+
+**Cost:** $$$ Medium ($5 - $50 per execution)  
+**Speed:** Very Slow (minutes to hours)  
+**Deterministic:** ❌ No (subjective)
+
+---
+
+### 4. Clone (Mind Emulation with Heuristics)
+
+**Definition:** AI agent augmented with personality heuristics and domain axioms to emulate a specific person's methodology.
+
+**When to use:**
+- Task requires specific domain expertise
+- Task must follow a specific methodology (e.g., Atomic Design)
+- Task needs validation against established principles
+- Task benefits from "personality-driven" execution
+
+**Examples:**
+- Validate components against Atomic Design principles (Brad Frost)
+- Review copy using specific writing methodology (Alex Hormozi)
+- Evaluate design system consistency (Design System Specialist)
+- Apply specific mental models (Domain Expert)
+
+**Cost:** $$$$ High ($0.002 - $0.015 per execution) [AI + validation]  
+**Speed:** Slow (5-15 seconds)  
+**Deterministic:** ⚠️ Partial (heuristics guide AI, but AI is stochastic)
+
+---
+
+## Decision Tree
+
+```mermaid
+graph TD
+    Start[Task to Execute] --> Q1{Requires<br/>Creativity or<br/>Subjectivity?}
+    
+    Q1 -->|No| Q2{Deterministic<br/>Algorithm<br/>Exists?}
+    Q1 -->|Yes| Q3{Human<br/>Judgment<br/>Required?}
+    
+    Q2 -->|Yes| Q4{External<br/>API Call?}
+    Q2 -->|No| Q3
+    
+    Q3 -->|Yes| Q5{Critical<br/>Decision<br/>with Legal/Financial<br/>Impact?}
+    Q3 -->|No| Q6{Specific<br/>Methodology<br/>Required?}
+    
+    Q4 -->|Yes| Worker[Worker<br/>with API]
+    Q4 -->|No| Worker2[Worker<br/>Script]
+    
+    Q5 -->|Yes| Humano[Humano]
+    Q5 -->|No| Q6
+    
+    Q6 -->|Yes<br/>Brad Frost,<br/>Alex Hormozi,<br/>etc.| Clone[Clone<br/>with Heuristics]
+    Q6 -->|No| Agente[Agente<br/>Generic AI]
+    
+    Worker --> End[Execute Task]
+    Worker2 --> End
+    Humano --> End
+    Clone --> End
+    Agente --> End
+    
+    style Worker fill:#90EE90
+    style Worker2 fill:#90EE90
+    style Humano fill:#FFB6C1
+    style Clone fill:#ADD8E6
+    style Agente fill:#FFFFE0
+```
+
+---
+
+## Detailed Decision Criteria
+
+### Criterion 1: Creativity / Subjectivity Required
+
+**Question:** Does the task require creative thinking, subjective judgment, or contextual understanding?
+
+**Examples:**
+
+| Task | Requires Creativity? | Why? |
+|------|---------------------|------|
+| Analyze brief and extract insights | ✅ Yes | Requires understanding nuance, context, emotional triggers |
+| Load brand config from JSON | ❌ No | Deterministic file read |
+| Generate ad copy | ✅ Yes | Requires creativity, brand voice adaptation |
+| Calculate content area height | ❌ No | Simple math: `canvas.height - safeZones.top - safeZones.bottom` |
+| Select optimal template | ✅ Yes | Requires matching brief goals with template strengths |
+
+**If YES → Consider Agente, Clone, or Humano**  
+**If NO → Consider Worker**
+
+---
+
+### Criterion 2: Deterministic Algorithm Exists
+
+**Question:** Can the task be solved with a predefined algorithm (if-then-else, formula, lookup table)?
+
+**Examples:**
+
+| Task | Deterministic Algorithm? | Algorithm |
+|------|-------------------------|-----------|
+| Validate email format | ✅ Yes | Regex: `/^[^\s@]+@[^\s@]+\.[^\s@]+$/` |
+| Decide if urgency is "high" | ❌ No | Subjective (depends on context, emotional triggers) |
+| Calculate color contrast ratio | ✅ Yes | Formula: `(L1 + 0.05) / (L2 + 0.05)` (WCAG) |
+| Choose between 3 templates | ❌ No | Depends on brief goals, brand, campaign type |
+
+**If YES → Worker**  
+**If NO → Consider Agente, Clone, or Humano**
+
+---
+
+### Criterion 3: External API Call Required
+
+**Question:** Does the task call an external API (not AI)?
+
+**Examples:**
+
+| Task | External API? | API |
+|------|--------------|-----|
+| Face detection | ✅ Yes (AI) | OpenRouter (Gemini Vision) → **Agente** |
+| Image search | ✅ Yes (AI) | Semantic search with embeddings → **Agente** |
+| File upload | ✅ Yes (Storage) | AWS S3, Supabase Storage → **Worker** |
+| Send email | ✅ Yes (Email) | SendGrid, Mailgun → **Worker** |
+| Webhook trigger | ✅ Yes (HTTP) | Generic HTTP POST → **Worker** |
+
+**If YES (AI API) → Agente**  
+**If YES (Non-AI API) → Worker**  
+**If NO → Continue decision tree**
+
+---
+
+### Criterion 4: Human Judgment Required
+
+**Question:** Does the task require subjective human judgment that cannot (or should not) be delegated to AI?
+
+**Examples:**
+
+| Task | Human Judgment Required? | Why? |
+|------|--------------------------|------|
+| Quality review of final ad | ⚠️ Maybe | Can be automated, but human review adds confidence |
+| Legal compliance check | ✅ Yes | Legal liability, requires human accountability |
+| Approve $10k media spend | ✅ Yes | Financial decision, requires human authorization |
+| Brand alignment validation | ⚠️ Maybe | AI can check, but human can catch nuances |
+| Emergency bug fix decision | ✅ Yes | High stakes, requires human judgment |
+
+**If YES (critical/legal/financial) → Humano**  
+**If MAYBE → Consider Agente or Clone (with human review as acceptance criteria)**  
+**If NO → Continue decision tree**
+
+---
+
+### Criterion 5: Specific Methodology Required
+
+**Question:** Must the task follow a specific person's methodology, principles, or mental models?
+
+**Examples:**
+
+| Task | Specific Methodology? | Whose? |
+|------|-----------------------|--------|
+| Validate Atomic Design compliance | ✅ Yes | Brad Frost (Atomic Design creator) |
+| Write high-converting ad copy | ✅ Yes | Alex Hormozi (copywriting methodology) |
+| Evaluate UX usability | ✅ Yes | Jakob Nielsen (Usability heuristics) |
+| Generic ad brief analysis | ❌ No | Any AI strategist can do it |
+| Generic component design | ❌ No | Standard design principles |
+
+**If YES → Clone (with heuristics + axioms of that person)**  
+**If NO → Agente (generic AI)**
+
+---
+
+## Cost-Benefit Analysis
+
+### Executor Cost Comparison
+
+| Executor | Cost per Execution | Speed | Deterministic | When to Use |
+|----------|-------------------|-------|---------------|-------------|
+| **Worker** | $ Low<br/>($0 - $0.001) | ⚡ Fast<br/>(< 1s) | ✅ Yes | - Config loading<br/>- File I/O<br/>- Simple calculations<br/>- API calls (non-AI) |
+| **Agente** | $$$$ High<br/>($0.001 - $0.01) | 🐌 Slow<br/>(3-10s) | ❌ No | - Creative tasks<br/>- Analysis<br/>- Generation<br/>- AI API calls |
+| **Humano** | $$$ Medium<br/>($5 - $50) | 🐢 Very Slow<br/>(minutes-hours) | ❌ No | - Legal/financial decisions<br/>- Quality gates<br/>- Strategic decisions<br/>- Edge cases |
+| **Clone** | $$$$ High<br/>($0.002 - $0.015) | 🐌 Slow<br/>(5-15s) | ⚠️ Partial | - Methodology validation<br/>- Expert review<br/>- Domain-specific tasks<br/>- Personality-driven execution |
+
+### ROI Calculation
+
+**Formula:**
+```
+ROI = (Time Saved × Hourly Rate - Executor Cost) / Executor Cost × 100%
+```
+
+**Example 1: Brief Analysis (Agente vs Humano)**
+
+```
+Agente:
+  Cost: $0.0025
+  Time: 4 seconds
+  Human alternative: 15 minutes = $12.50 (at $50/hour)
+  ROI: ($12.50 - $0.0025) / $0.0025 × 100% = 499,900%
+
+Humano:
+  Cost: $12.50
+  Time: 15 minutes
+  ROI: N/A (baseline)
+  
+Decision: ✅ Agente (massive ROI)
+```
+
+**Example 2: Load Config (Worker vs Agente)**
+
+```
+Worker:
+  Cost: $0
+  Time: 0.05 seconds
+  Agente alternative: $0.005, 5 seconds
+  ROI: Infinite (free vs paid)
+
+Agente:
+  Cost: $0.005
+  Time: 5 seconds
+  ROI: Negative (slower and more expensive)
+  
+Decision: ✅ Worker (no reason to use AI)
+```
+
+**Example 3: Quality Review (Humano vs Agente)**
+
+```
+Humano:
+  Cost: $5
+  Time: 3 minutes
+  Accuracy: 95%
+
+Agente:
+  Cost: $0.01
+  Time: 5 seconds
+  Accuracy: 85%
+
+Trade-off:
+  - Agente is 500x cheaper, 36x faster
+  - But 10% less accurate
+  
+Decision: Depends on use case:
+  - High-volume batch: ✅ Agente (with spot-check by Humano)
+  - Critical campaign: ✅ Humano (stakes too high)
+```
+
+---
+
+## Capability Matrix
+
+### What Each Executor CAN Do
+
+| Capability | Agente | Worker | Humano | Clone |
+|------------|--------|--------|--------|-------|
+| **AI Model Calls** | ✅ Yes | ❌ No | ❌ No | ✅ Yes |
+| **Script Execution** | ⚠️ Limited<br/>(via tools) | ✅ Yes | ❌ No | ⚠️ Limited<br/>(via tools) |
+| **File I/O** | ⚠️ Limited<br/>(via tools) | ✅ Yes | ❌ No | ⚠️ Limited<br/>(via tools) |
+| **Database Access** | ⚠️ Limited<br/>(via tools) | ✅ Yes | ✅ Yes<br/>(via UI) | ⚠️ Limited<br/>(via tools) |
+| **External APIs** | ✅ Yes<br/>(AI APIs) | ✅ Yes<br/>(Non-AI) | ❌ No | ✅ Yes<br/>(AI APIs) |
+| **Creative Thinking** | ✅ Yes | ❌ No | ✅ Yes | ✅ Yes<br/>(guided by heuristics) |
+| **Subjective Judgment** | ⚠️ Simulated | ❌ No | ✅ Yes | ✅ Yes<br/>(via axioms) |
+| **Deterministic** | ❌ No | ✅ Yes | ❌ No | ⚠️ Partial |
+| **Legal Accountability** | ❌ No | ❌ No | ✅ Yes | ❌ No |
+
+---
+
+## Executor Substitution Rules
+
+### When to Swap Executors
+
+#### Rule 1: Agente → Worker (Cost Optimization)
+
+**Condition:** If task becomes deterministic after enough training data.
+
+**Example:**
+```yaml
+# BEFORE: Agente (creative)
+Step 4: Select Template
+  responsavel_type: Agente
+  cost: $0.0003
+
+# AFTER: Worker (lookup table)
+Step 4: Select Template
+  responsavel_type: Worker
+  logic: |
+    if (brief.campaign_goal === "conversion") return "ad-01-cta-focused";
+    if (brief.campaign_goal === "awareness") return "ad-02-hero-visual";
+    else return "ad-01-hero-overlay";  # Default
+  cost: $0
+```
+
+**Savings:** 100% cost reduction
+
+---
+
+#### Rule 2: Humano → Agente (Automation)
+
+**Condition:** If task can be automated with acceptable accuracy drop.
+
+**Example:**
+```yaml
+# BEFORE: Humano (manual review)
+Step 15: Quality Review
+  responsavel_type: Humano
+  cost: $5
+  time: 3 minutes
+  accuracy: 95%
+
+# AFTER: Agente (automated review) with spot-check
+Step 15: Quality Review
+  responsavel_type: Agente
+  cost: $0.01
+  time: 5 seconds
+  accuracy: 85%
+  acceptance-criteria:
+    - [ ] Random 10% reviewed by Humano
+      tipo: acceptance
+      blocker: false
+```
+
+**Trade-off:** -10% accuracy, -99.8% cost, -97% time
+
+---
+
+#### Rule 3: Agente → Clone (Methodology Enforcement)
+
+**Condition:** If task benefits from specific domain expertise or methodology.
+
+**Example:**
+```yaml
+# BEFORE: Agente (generic design validation)
+Step 7c: Validate Components
+  responsavel_type: Agente
+  prompt: "Check if components follow best practices"
+  accuracy: 70%
+
+# AFTER: Clone (Brad Frost's Atomic Design)
+Step 7c: Validate Components
+  responsavel_type: Clone
+  heuristics: clones/brad_frost/heuristics.yaml
+  axioms: clones/brad_frost/axioms.yaml
+  accuracy: 95%  # Higher accuracy due to domain expertise
+```
+
+**Trade-off:** +25% accuracy, +3x cost, +2x time (worth it for quality)
+
+---
+
+#### Rule 4: Clone → Agente (Simplification)
+
+**Condition:** If specific methodology is not critical to task success.
+
+**Example:**
+```yaml
+# BEFORE: Clone (overkill for simple task)
+Step 5: Craft Ad Copy
+  responsavel_type: Clone
+  clone: alex_hormozi
+  cost: $0.015
+
+# AFTER: Agente (sufficient for generic copy)
+Step 5: Craft Ad Copy
+  responsavel_type: Agente
+  cost: $0.005
+```
+
+**Savings:** -67% cost (when methodology not critical)
+
+---
+
+## Hybrid Executor Strategies
+
+### Strategy 1: Agente + Worker (AI with Fallback)
+
+**Use Case:** AI does creative work, Worker provides fallback if AI fails.
+
+```yaml
+Step 4: Select Template
+
+responsavel_type: Agente
+fallback_executor: Worker
+
+logic: |
+  try {
+    # Try AI selection
+    return await agente.selectTemplate(brief, brand);
+  } catch (error) {
+    # Fallback to Worker (rule-based)
+    return worker.selectTemplateDefault(brief.campaign_goal);
+  }
+
+cost:
+  - Primary: $0.0003 (Agente)
+  - Fallback: $0 (Worker)
+  - Average: $0.00027 (if 90% success rate)
+```
+
+---
+
+### Strategy 2: Agente + Humano (AI with Review)
+
+**Use Case:** AI does bulk work, Humano reviews edge cases or high-stakes decisions.
+
+```yaml
+Step 15: Quality Review
+
+responsavel_type: Agente
+
+acceptance-criteria:
+  - [ ] If quality score < 80%, escalate to Humano
+    tipo: acceptance
+    blocker: false
+    escalation:
+      condition: quality_score < 80
+      executor: Humano
+
+logic: |
+  const aiReview = await agente.reviewQuality(ad);
+  
+  if (aiReview.score < 80) {
+    # Escalate to human
+    return await humano.reviewQuality(ad);
+  }
+  
+  return aiReview;
+
+cost:
+  - Agente: $0.01 (100% of ads)
+  - Humano: $5 (10% of ads)
+  - Average: $0.51 per ad
+```
+
+---
+
+### Strategy 3: Clone + Agente (Methodology + Creativity)
+
+**Use Case:** Clone validates, Agente executes (best of both worlds).
+
+```yaml
+Step 7: Design Components
+
+primary_executor: Agente
+validator_executor: Clone
+
+logic: |
+  # 1. Agente designs component (creative)
+  const component = await agente.designCTA(adCopy, brand);
+  
+  # 2. Clone validates (methodology)
+  const validation = await clone.validateAtomicDesign(component);
+  
+  if (!validation.valid) {
+    # 3. Retry with corrections
+    component = await agente.designCTA(adCopy, brand, {
+      corrections: validation.violations
+    });
+  }
+  
+  return component;
+
+cost:
+  - Agente: $0.005
+  - Clone: $0.001
+  - Total: $0.006 (higher quality, worth it)
+```
+
+---
+
+## Real-World Examples from V2.0 Workflow
+
+### Step 1: Load Format Configuration
+
+**Decision Process:**
+
+1. Requires creativity? ❌ No (deterministic file read)
+2. Deterministic algorithm? ✅ Yes (read JSON, calculate content area)
+3. External API? ❌ No
+
+**Executor:** ✅ **Worker**
+
+**Rationale:** Pure data transformation, no AI needed.
+
+---
+
+### Step 3: Analyze Brief
+
+**Decision Process:**
+
+1. Requires creativity? ✅ Yes (contextual understanding, insight extraction)
+2. Human judgment? ⚠️ Maybe (can be automated with good accuracy)
+3. Specific methodology? ❌ No (generic strategy)
+
+**Executor:** ✅ **Agente**
+
+**Rationale:** AI excels at natural language understanding and insight extraction.
+
+**Alternative (Ready Copy Mode):** ✅ **Worker** (skip AI, use defaults)
+
+---
+
+### Step 7: Design Components
+
+**Decision Process:**
+
+1. Requires creativity? ✅ Yes (color selection, style decisions)
+2. Specific methodology? ⚠️ Partial (Atomic Design compliance)
+3. Human judgment? ❌ No (can be automated)
+
+**Executor:** ✅ **Agente** (primary)
+
+**Alternative (with validation):** ✅ **Agente** + **Clone** (Brad Frost validates)
+
+**Rationale:** AI designs, Clone ensures Atomic Design compliance.
+
+---
+
+### Step 7c: Validate Components (NEW in V3.0)
+
+**Decision Process:**
+
+1. Requires creativity? ❌ No (validation against rules)
+2. Specific methodology? ✅ Yes (Brad Frost's Atomic Design)
+3. Deterministic algorithm? ⚠️ Partial (heuristics + axioms)
+
+**Executor:** ✅ **Clone** (Brad Frost)
+
+**Rationale:** Validation requires domain expertise and methodology adherence.
+
+---
+
+### Step 10: Detect Faces
+
+**Decision Process:**
+
+1. Requires creativity? ❌ No (computer vision task)
+2. External API? ✅ Yes (OpenRouter Gemini Vision)
+3. Deterministic algorithm? ❌ No (AI vision model)
+
+**Executor:** ✅ **Agente** (external AI API)
+
+**Rationale:** Face detection requires AI, but it's an external API call.
+
+---
+
+### Step 13: Render HTML
+
+**Decision Process:**
+
+1. Requires creativity? ❌ No (template compilation)
+2. Deterministic algorithm? ✅ Yes (Handlebars rendering)
+3. External API? ❌ No
+
+**Executor:** ✅ **Worker**
+
+**Rationale:** Pure template compilation, no AI needed.
+
+---
+
+### Step 15: Quality Review (OPTIONAL - NEW in V3.0)
+
+**Decision Process:**
+
+1. Requires creativity? ❌ No (checklist validation)
+2. Human judgment? ✅ Yes (subjective quality assessment)
+3. Critical decision? ⚠️ Depends (high-stakes campaigns → yes)
+
+**Executor (High Stakes):** ✅ **Humano**  
+**Executor (Batch Mode):** ✅ **Agente** (with spot-check by Humano)
+
+**Rationale:** Depends on campaign importance and volume.
+
+---
+
+## Summary Checklist
+
+Use this checklist to decide executor type for any task:
+
+### Step 1: Quick Filters
+
+- [ ] Is task deterministic? (same input → same output)
+  - ✅ YES → **Worker**
+  - ❌ NO → Continue
+  
+- [ ] Does task call external AI API?
+  - ✅ YES → **Agente**
+  - ❌ NO → Continue
+  
+- [ ] Is task critical legal/financial decision?
+  - ✅ YES → **Humano**
+  - ❌ NO → Continue
+
+### Step 2: Creativity vs Methodology
+
+- [ ] Does task require creativity?
+  - ✅ YES + No specific methodology → **Agente**
+  - ✅ YES + Specific methodology → **Clone**
+  - ❌ NO → **Worker**
+
+### Step 3: Cost-Benefit
+
+- [ ] Is AI cost justified by time savings or quality?
+  - ✅ YES → Keep Agente/Clone
+  - ❌ NO → Consider Worker or Humano
+
+### Step 4: Hybrid Strategy
+
+- [ ] Would task benefit from multiple executors?
+  - ✅ YES → Use primary + fallback/validator
+  - ❌ NO → Single executor
+
+---
+
+## Version History
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 1.0.0 | 2025-11-13 | Brad Frost Clone | Initial decision tree |
+
+---
+
+**END OF EXECUTOR DECISION TREE**
+
+**Related Documents:**
+- `TASK-FORMAT-SPECIFICATION-V1.md` - Task format with executor type
+- `CLONE-ARCHITECTURE-GUIDE.md` - How to implement Clones
+- `WORKFLOW-ORCHESTRATION-GUIDE.md` - Executor execution patterns
+
+