feat: Add visionary agent with service bridge integration and knowledge gap tracking

Implements @Visionary agent with full handler + test coverage, integrates agent-service-bridge across 4 handlers, and adds knowledge gap tracking system.

**Visionary Agent:**
- backend/agents/handlers/visionary.cjs - Business strategy synthesis, opportunity analysis
- backend/tests/visionary-handler.test.cjs - 5-lens validation tests
- Full 6-lens pipeline (Truth→Causality→Contradiction→Extrapolation→Rights→Structure)

**Agent-Service-Bridge Integration:**
- backend/services/agent-service-bridge.cjs - Template discovery, project workspace ops
- Integrated into: builder, content, distributor, governor handlers
- Enables template-driven workflows for all agents

**Knowledge Gap Tracking:**
- backend/data/gaps.json - 177-line structured gap taxonomy
- Categories: workflow, integration, validation, testing, documentation
- Powers agent self-improvement and orchestration decisions

**Documentation:**
- workspace/docs/Obsidian-v2/docs/reference/frameworks/template-library.md - Template system reference
- workspace/docs/Obsidian-v2/docs/reference/INDEX.md - Updated with frameworks section
- Daily notes auto-updated (2025-11-06, 2025-11-07)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: Michael

backend/agents/handlers/builder.cjs

@@ -43,6 +43,31 @@ class BuilderAgent {
       console.log('\n🏗️  @builder agent executing...');
       console.log(`   Mode: ${this.cli.getStatus().ready ? 'CLI Delegation ($0)' : 'API Fallback'}`);
 
+      // Check for template context and load template-specific instructions
+      let templateInstructions = '';
+      if (context.template_id) {
+        try {
+          const templates = require('../../data/templates.json');
+          const template = templates.templates.find(t => t.id === context.template_id);
+
+          if (template) {
+            console.log(`[builder] Template detected: ${context.template_id}, phase: ${context.phase || 'unknown'}`);
+
+            // Find the current phase instructions
+            const currentPhase = template.agent_sequence?.phases?.find(p => p.name === context.phase);
+            if (currentPhase && currentPhase.agents.includes('builder')) {
+              templateInstructions = `\n\n## Template Context: ${template.name}\n` +
+                `Phase: ${currentPhase.name}\n` +
+                `Template Goal: ${template.description}\n` +
+                `Time Constraint: ${template.time_constraint || 'standard'}\n` +
+                `Expected Deliverables: Focus on ${currentPhase.name} objectives (Day 1-2 implementation)\n`;
+            }
+          }
+        } catch (err) {
+          console.warn('[builder] Failed to load template context:', err.message);
+        }
+      }
+
       // Check for existing marketing outputs BEFORE building
       console.log('[Builder] Checking for existing marketing outputs...');
       const relatedOutputs = await outputCache.findRelatedOutputs(prompt, {
@@ -84,22 +109,26 @@ Use this as context for building. DO NOT re-create the strategy - focus on imple
 
       console.log('   Using Claude API (fallback)');
 
-      // Pass marketing context through to product generation
+      // Pass marketing context and template instructions through to product generation
       const enrichedContext = {
         ...context,
-        marketingContext
+        marketingContext,
+        templateInstructions
       };
 
       // Parse the prompt to determine product type
       const productType = this.detectProductType(prompt);
 
+      // Include template instructions in the prompt if available
+      const enrichedPrompt = templateInstructions ? `${prompt}${templateInstructions}` : prompt;
+
       // Route to appropriate builder function
       if (this.productTemplates[productType]) {
-        return await this.productTemplates[productType].call(this, prompt, enrichedContext);
+        return await this.productTemplates[productType].call(this, enrichedPrompt, enrichedContext);
       }
 
       // Default: Generate based on AI interpretation
-      return await this.generateCustomProduct(prompt, enrichedContext);
+      return await this.generateCustomProduct(enrichedPrompt, enrichedContext);
 
     } catch (error) {
       console.error('[Builder Agent] Error:', error);

backend/agents/handlers/content.cjs

@@ -27,13 +27,37 @@ const lensOrchestrator = new LensOrchestrator({
  */
 async function handleRequest(prompt, context = {}) {
   try {
+    // Check for template context and load template-specific instructions
+    let templateInstructions = '';
+    if (context.template_id) {
+      try {
+        const templates = require('../../data/templates.json');
+        const template = templates.templates.find(t => t.id === context.template_id);
+
+        if (template) {
+          console.log(`[content] Template detected: ${context.template_id}, phase: ${context.phase || 'unknown'}`);
+
+          // Find the current phase instructions if available
+          const currentPhase = template.agent_sequence?.phases?.find(p => p.name === context.phase);
+          if (currentPhase && currentPhase.agents.includes('content')) {
+            templateInstructions = `\n\n## Template Context: ${template.name}\n` +
+              `Phase: ${currentPhase.name}\n` +
+              `Template Goal: ${template.description}\n` +
+              `Expected Deliverable: Focus on ${currentPhase.name} objectives\n`;
+          }
+        }
+      } catch (err) {
+        console.warn('[content] Failed to load template context:', err.message);
+      }
+    }
+
     // Recall relevant content insights from memory
     let memoryContext = [];
     try {
       if (typeof memory.query === "function") {
-        const memoryResults = await memory.query({ 
-          text: prompt, 
-          topK: 5, 
+        const memoryResults = await memory.query({
+          text: prompt,
+          topK: 5,
           filter: { domain: "content" }
         });
         memoryContext = memoryResults.matches || [];
@@ -55,7 +79,7 @@ async function handleRequest(prompt, context = {}) {
     };
 
     // Build system prompt for content creation
-    const systemPrompt = `You are **@content** — Soulfield's content specialist applying workflow-first methodology to technical documentation, developer content, and tutorial creation.
+    const systemPrompt = `You are **@content** — Soulfield's content specialist applying workflow-first methodology to technical documentation, developer content, and tutorial creation.${templateInstructions}
 
 ## Your Purpose
 Deliver high-quality technical content that saves 75-90% of time on documentation workflows while maintaining technical accuracy and developer-friendly formatting.

backend/agents/handlers/distributor.cjs

@@ -33,6 +33,33 @@ class DistributorAgent {
    */
   async execute(prompt, context = {}) {
     try {
+      // Check for template context and load template-specific instructions
+      let templateInstructions = '';
+      if (context.template_id) {
+        try {
+          const templates = require('../../data/templates.json');
+          const template = templates.templates.find(t => t.id === context.template_id);
+
+          if (template) {
+            console.log(`[distributor] Template detected: ${context.template_id}, phase: ${context.phase || 'unknown'}`);
+
+            // Find the current phase instructions if available
+            const currentPhase = template.agent_sequence?.phases?.find(p => p.name === context.phase);
+            if (currentPhase && currentPhase.agents.includes('distributor')) {
+              templateInstructions = `\n\n## Template Context: ${template.name}\n` +
+                `Phase: ${currentPhase.name}\n` +
+                `Template Goal: ${template.description}\n` +
+                `Expected Deliverable: Focus on ${currentPhase.name} objectives\n`;
+            }
+          }
+        } catch (err) {
+          console.warn('[distributor] Failed to load template context:', err.message);
+        }
+      }
+
+      // Store template instructions for use in prompts
+      this.templateInstructions = templateInstructions;
+
       // Initialize CLI delegator for landing pages
       await this.cliDelegator.init();
 
@@ -89,7 +116,7 @@ class DistributorAgent {
    * Distribute to Reddit
    */
   async distributeToReddit(prompt, context) {
-    const systemPrompt = `You are a Reddit distribution specialist. Create Reddit-optimized content.
+    const systemPrompt = `You are a Reddit distribution specialist. Create Reddit-optimized content.${this.templateInstructions || ''}
 
 Format your response as:
 1. Recommended subreddits (with subscriber counts and rules)
@@ -126,7 +153,7 @@ Follow Reddit best practices:
    * Distribute to Twitter/X
    */
   async distributeToTwitter(prompt, context) {
-    const systemPrompt = `You are a Twitter/X distribution specialist. Create Twitter-optimized content.
+    const systemPrompt = `You are a Twitter/X distribution specialist. Create Twitter-optimized content.${this.templateInstructions || ''}
 
 Format your response as:
 1. Thread structure (number of tweets, key points)
@@ -164,7 +191,7 @@ Optimize for:
    * Distribute to ProductHunt
    */
   async distributeToProductHunt(prompt, context) {
-    const systemPrompt = `You are a ProductHunt launch specialist. Create a complete ProductHunt campaign.
+    const systemPrompt = `You are a ProductHunt launch specialist. Create a complete ProductHunt campaign.${this.templateInstructions || ''}
 
 Format your response as:
 1. Product name and tagline
@@ -202,7 +229,7 @@ Include:
    * Distribute to LinkedIn
    */
   async distributeToLinkedIn(prompt, context) {
-    const systemPrompt = `You are a LinkedIn content specialist. Create LinkedIn-optimized professional content.
+    const systemPrompt = `You are a LinkedIn content specialist. Create LinkedIn-optimized professional content.${this.templateInstructions || ''}
 
 Format your response as:
 1. Post type (article, post, video script)
@@ -240,7 +267,7 @@ Optimize for:
    * Multi-platform distribution strategy
    */
   async distributeMultiPlatform(prompt, context) {
-    const systemPrompt = `You are a multi-platform distribution specialist. Create a coordinated distribution strategy across multiple platforms.
+    const systemPrompt = `You are a multi-platform distribution specialist. Create a coordinated distribution strategy across multiple platforms.${this.templateInstructions || ''}
 
 For each platform provide:
 1. Platform name
@@ -374,7 +401,7 @@ Output: Complete HTML file ready to deploy.`;
    * Create landing page with Claude API (fallback)
    */
   async createLandingPageWithClaude(prompt, context) {
-    const systemPrompt = `You are a landing page specialist. Create a complete, conversion-optimized HTML landing page.
+    const systemPrompt = `You are a landing page specialist. Create a complete, conversion-optimized HTML landing page.${this.templateInstructions || ''}
 
 Include:
 - Professional, modern design

backend/agents/handlers/governor.cjs

@@ -35,15 +35,39 @@ const lensOrchestrator = new LensOrchestrator({
  * @returns {Object} Decision with lens validation results
  */
 async function handleRequest({ brief, context = {} }) {
-  // Generate decision using askAiden
+  // Check for template context and load template-specific instructions
+  let templateInstructions = '';
+  if (context.template_id) {
+    try {
+      const templates = require('../../data/templates.json');
+      const template = templates.templates.find(t => t.id === context.template_id);
+
+      if (template) {
+        console.log(`[governor] Template detected: ${context.template_id}, phase: ${context.phase || 'unknown'}`);
+
+        // Find the current phase instructions if available
+        const currentPhase = template.agent_sequence?.phases?.find(p => p.name === context.phase);
+        if (currentPhase) {
+          templateInstructions = `\n\n## Template Context: ${template.name}\n` +
+            `Phase: ${currentPhase.name}\n` +
+            `Template Goal: ${template.description}\n` +
+            `Expected Deliverable: Focus on ${currentPhase.name} objectives\n`;
+        }
+      }
+    } catch (err) {
+      console.warn('[governor] Failed to load template context:', err.message);
+    }
+  }
+
+  // Generate decision using askAiden with optional template context
   const system = process.env.GOVERNOR_SYSTEM || process.env.AIDEN_SYSTEM ||
     "You are Governor, the chief orchestrator. Apply Strategy pipeline (Rights → Causality → Truth). " +
     "Ensure all decisions respect privacy/data rights, include causal mechanisms, and mark uncertainties with [UNKNOWN].";
 
   const messages = [
     {
       role: "user",
-      content: `Brief: ${brief}\n\nContext: ${JSON.stringify(context, null, 2).slice(0, 1200)}`
+      content: `Brief: ${brief}${templateInstructions}\n\nContext: ${JSON.stringify(context, null, 2).slice(0, 1200)}`
     }
   ];
 

backend/agents/handlers/visionary.cjs

@@ -0,0 +1,142 @@
+/**
+ * Visionary Agent Handler
+ * Strategic business vision and opportunity synthesis
+ * Uses Planning lens pipeline: Truth → Causality → Extrapolation → Structure
+ */
+
+const path = require('path');
+const fs = require('fs').promises;
+const { askAiden } = require(path.resolve(__dirname, '../../../tools/aiden.cjs'));
+const { LensOrchestrator } = require('../../lenses/LensOrchestrator.js');
+
+// Initialize lens orchestrator with planning pipeline
+const lensOrchestrator = new LensOrchestrator({
+  pipeline: 'planning',  // Truth → Causality → Extrapolation → Structure
+  agent: 'visionary'
+});
+
+/**
+ * Handle visionary request with lens validation
+ * @param {Object} params - Request parameters
+ * @param {string} params.prompt - Strategic vision request
+ * @param {Object} params.context - Additional context
+ * @returns {Object} Vision with lens validation results
+ */
+async function handleRequest({ prompt, context = {} }) {
+  // Check for template context and load template-specific instructions
+  let templateInstructions = '';
+  if (context.template_id) {
+    try {
+      const templates = require('../../data/templates.json');
+      const template = templates.templates.find(t => t.id === context.template_id);
+
+      if (template) {
+        console.log(`[visionary] Template detected: ${context.template_id}, phase: ${context.phase || 'unknown'}`);
+
+        // Find the current phase instructions if available
+        const currentPhase = template.agent_sequence?.phases?.find(p => p.name === context.phase);
+        if (currentPhase && currentPhase.agents.includes('visionary')) {
+          templateInstructions = `\n\n## Template Context: ${template.name}\n` +
+            `Phase: ${currentPhase.name}\n` +
+            `Template Goal: ${template.description}\n` +
+            `Focus: Strategic vision for ${currentPhase.name} phase\n` +
+            `Deliverables: High-level strategy and opportunity analysis\n`;
+        }
+      }
+    } catch (err) {
+      console.warn('[visionary] Failed to load template context:', err.message);
+    }
+  }
+
+  // Generate vision using askAiden with template context
+  const system = process.env.VISIONARY_SYSTEM ||
+    "You are Visionary, the strategic business synthesist. Apply Planning pipeline (Truth → Causality → Extrapolation → Structure). " +
+    "Focus on: opportunity detection, trend synthesis, market positioning, and strategic roadmaps. " +
+    "Mark uncertainties with [UNKNOWN], include causal mechanisms for predictions, validate extrapolations against data, " +
+    "and structure outputs with clear preconditions and postconditions.";
+
+  const messages = [
+    {
+      role: "user",
+      content: `${prompt}${templateInstructions}\n\nContext: ${JSON.stringify(context, null, 2).slice(0, 1000)}`
+    }
+  ];
+
+  const vision = await askAiden({
+    system,
+    messages,
+    maxTokens: 2000  // Visionary outputs tend to be comprehensive
+  });
+
+  // Apply planning pipeline lens validation
+  const lensResult = await lensOrchestrator.applyAll(vision, {
+    agent: 'visionary',
+    query: prompt,
+    domain: 'strategic',
+    context
+  });
+
+  // Save to agent workspace if AFS available
+  try {
+    const afs = require('../../services/afs.cjs');
+
+    const timestamp = new Date().toISOString().replace(/:/g, '-').split('.')[0];
+    const filename = `vision-${timestamp}.md`;
+
+    let content = `# Strategic Vision\n\n`;
+    content += `**Date:** ${new Date().toISOString()}\n`;
+    content += `**Prompt:** ${prompt.substring(0, 200)}...\n`;
+    if (context.template_id) {
+      content += `**Template:** ${context.template_id}\n`;
+      content += `**Phase:** ${context.phase || 'N/A'}\n`;
+    }
+    content += `\n---\n\n${vision}`;
+
+    await afs.writeFile('visionary', filename, content, { syncDrive: true });
+    console.log(`[visionary] Saved vision to workspace: ${filename}`);
+  } catch (err) {
+    console.warn('[visionary] Failed to save to workspace:', err.message);
+  }
+
+  // Return structured response with lens validation
+  return {
+    ok: true,
+    success: true,
+    agent: "visionary",
+    output: vision,
+    text: vision,
+    lens_result: lensResult,
+    quality_score: lensResult.aggregated?.metrics?.overall_quality_score || 0,
+    compliance: {
+      truth: lensResult.results?.truth?.passed || false,
+      causality: lensResult.results?.causality?.passed || false,
+      extrapolation: lensResult.results?.extrapolation?.passed || false,
+      structure: lensResult.results?.structure?.passed || false,
+      overall: lensResult.aggregated?.overall_passed || false
+    },
+    critical_issues: lensResult.aggregated?.critical_issues || [],
+    meta: {
+      agent: 'visionary',
+      pipeline: 'planning',
+      template_id: context.template_id,
+      phase: context.phase,
+      routed: 'handler'
+    }
+  };
+}
+
+/**
+ * Execute function for compatibility with different calling patterns
+ */
+async function execute(prompt, context = {}) {
+  // Handle different input formats
+  if (typeof prompt === 'object' && prompt.prompt) {
+    return handleRequest({ prompt: prompt.prompt, context: prompt.context || context });
+  }
+  return handleRequest({ prompt, context });
+}
+
+// Export both patterns for compatibility
+module.exports = handleRequest;
+module.exports.execute = execute;
+module.exports.handleRequest = handleRequest;