moflo 4.8.11 → 4.8.12

package/.claude/agents/browser/browser-agent.yaml

@@ -0,0 +1,182 @@
+# Browser Agent Configuration
+# AI-powered web browser automation using agent-browser
+#
+# Capabilities:
+# - Web navigation and interaction
+# - AI-optimized snapshots with element refs
+# - Form filling and submission
+# - Screenshot capture
+# - Network interception
+# - Multi-session coordination
+
+name: browser-agent
+description: Web automation specialist using agent-browser with AI-optimized snapshots
+version: 1.0.0
+
+# Routing configuration
+routing:
+  complexity: medium
+  model: sonnet  # Good at visual reasoning and DOM interpretation
+  priority: normal
+  keywords:
+    - browser
+    - web
+    - scrape
+    - screenshot
+    - navigate
+    - login
+    - form
+    - click
+    - automate
+
+# Agent capabilities
+capabilities:
+  - web-navigation
+  - form-interaction
+  - screenshot-capture
+  - data-extraction
+  - network-interception
+  - session-management
+  - multi-tab-coordination
+
+# Available tools (MCP tools with browser/ prefix)
+tools:
+  navigation:
+    - browser/open
+    - browser/back
+    - browser/forward
+    - browser/reload
+    - browser/close
+  snapshot:
+    - browser/snapshot
+    - browser/screenshot
+    - browser/pdf
+  interaction:
+    - browser/click
+    - browser/fill
+    - browser/type
+    - browser/press
+    - browser/hover
+    - browser/select
+    - browser/check
+    - browser/uncheck
+    - browser/scroll
+    - browser/upload
+  info:
+    - browser/get-text
+    - browser/get-html
+    - browser/get-value
+    - browser/get-attr
+    - browser/get-title
+    - browser/get-url
+    - browser/get-count
+  state:
+    - browser/is-visible
+    - browser/is-enabled
+    - browser/is-checked
+  wait:
+    - browser/wait
+  eval:
+    - browser/eval
+  storage:
+    - browser/cookies-get
+    - browser/cookies-set
+    - browser/cookies-clear
+    - browser/localstorage-get
+    - browser/localstorage-set
+  network:
+    - browser/network-route
+    - browser/network-unroute
+    - browser/network-requests
+  tabs:
+    - browser/tab-list
+    - browser/tab-new
+    - browser/tab-switch
+    - browser/tab-close
+    - browser/session-list
+  settings:
+    - browser/set-viewport
+    - browser/set-device
+    - browser/set-geolocation
+    - browser/set-offline
+    - browser/set-media
+  debug:
+    - browser/trace-start
+    - browser/trace-stop
+    - browser/console
+    - browser/errors
+    - browser/highlight
+    - browser/state-save
+    - browser/state-load
+  find:
+    - browser/find-role
+    - browser/find-text
+    - browser/find-label
+    - browser/find-testid
+
+# Memory configuration
+memory:
+  namespace: browser-sessions
+  persist: true
+  patterns:
+    - login-flows
+    - form-submissions
+    - scraping-patterns
+    - navigation-sequences
+
+# Swarm integration
+swarm:
+  roles:
+    - navigator      # Handles authentication and navigation
+    - scraper        # Extracts data using snapshots
+    - validator      # Verifies extracted data
+    - tester         # Runs automated tests
+    - monitor        # Watches for errors and network issues
+  topology: hierarchical  # Coordinator manages browser agents
+  max_sessions: 5
+
+# Hooks integration
+hooks:
+  pre_task:
+    - route         # Get optimal routing
+    - memory_search # Check for similar patterns
+  post_task:
+    - memory_store  # Save successful patterns
+    - post_edit     # Train on outcomes
+
+# Default configuration
+defaults:
+  timeout: 30000
+  headless: true
+  viewport:
+    width: 1280
+    height: 720
+
+# Example workflows
+workflows:
+  login:
+    description: Authenticate to a website
+    steps:
+      - open: "{url}/login"
+      - snapshot: { interactive: true }
+      - fill: { target: "@e1", value: "{username}" }
+      - fill: { target: "@e2", value: "{password}" }
+      - click: "@e3"
+      - wait: { url: "**/dashboard" }
+      - state-save: "auth-state.json"
+
+  scrape_list:
+    description: Extract data from a list page
+    steps:
+      - open: "{url}"
+      - snapshot: { interactive: true, compact: true }
+      - eval: "Array.from(document.querySelectorAll('{selector}')).map(el => el.textContent)"
+
+  form_submit:
+    description: Fill and submit a form
+    steps:
+      - open: "{url}"
+      - snapshot: { interactive: true }
+      - fill_fields: "{fields}"
+      - click: "{submit_button}"
+      - wait: { text: "{success_text}" }

package/.claude/guidance/moflo-bootstrap.md

@@ -0,0 +1,129 @@
+<!-- AUTO-GENERATED by moflo session-start. Do not edit — changes will be overwritten. -->
+<!-- Source: node_modules/moflo/.claude/guidance/agent-bootstrap.md -->
+
+# MoFlo Agent Bootstrap Guide
+
+**Purpose:** Quick-start reference for subagents spawned by coordinators. Every subagent should follow this protocol before doing any work.
+
+---
+
+## 1. Search Memory FIRST
+
+**Before reading any files or exploring code, search memory for guidance relevant to your task.**
+
+### Three namespaces to search:
+
+| Namespace | When to search | What it returns |
+|-----------|---------------|-----------------|
+| `guidance` | Understanding patterns, rules, conventions | Guidance docs, coding rules, domain context |
+| `code-map` | Finding where code lives (files, types, services) | Project overviews, directory contents, type-to-file mappings |
+| `patterns` | Prior solutions, gotchas, implementation patterns | Learned patterns from previous task execution |
+
+**Always search `patterns` alongside `guidance`.** It contains solutions to problems already solved — skipping it means repeating past mistakes or re-discovering known approaches.
+
+**Search `code-map` BEFORE using Glob/Grep for navigation.** It's faster and returns structured results including file-level type mappings.
+
+### Option A: MCP Tools (Preferred)
+
+If you have MCP tools available (check for `mcp__moflo__*`), use them directly:
+
+| Tool | Purpose |
+|------|---------|
+| `mcp__moflo__memory_search` | Semantic search with domain-aware embeddings |
+| `mcp__moflo__memory_store` | Store patterns with auto-vectorization |
+| `mcp__moflo__hooks_route` | Get agent routing suggestions |
+
+### Option B: CLI via Bash
+
+```bash
+npx flo memory search --query "[describe your task]" --namespace guidance --limit 5
+```
+
+| Your task involves... | Search namespace | Example query |
+|-----------------------|------------------|---------------|
+| Database/entities | `guidance` + `patterns` | `"database entity migration"` |
+| Frontend components | `guidance` + `patterns` | `"React frontend component"` |
+| API endpoints | `guidance` + `patterns` | `"API route endpoint pattern"` |
+| Authentication | `guidance` + `patterns` | `"auth middleware JWT"` |
+| Unit tests | `guidance` + `patterns` | `"test mock vitest"` |
+| Prior solutions/gotchas | `patterns` | `"audit log service pattern"` |
+| Where is a file/type? | `code-map` | `"CompanyEntity file location"` |
+| What's in a directory? | `code-map` | `"back-office api routes"` |
+
+Use results with score > 0.3. If no good results, fall back to reading project guidance docs.
+
+---
+
+## 2. Check Project-Specific Bootstrap
+
+**After reading this file, check for a project-specific bootstrap:**
+
+```bash
+# Project-specific bootstrap (has domain rules, patterns, templates)
+cat .claude/guidance/agent-bootstrap.md 2>/dev/null | head -10
+```
+
+If `.claude/guidance/agent-bootstrap.md` exists, **read it next**. It contains project-specific rules (entity patterns, multi-tenancy, tech stack conventions) that override generic guidance.
+
+If no project bootstrap exists, look for general project guidance:
+
+```bash
+ls .claude/guidance/ 2>/dev/null
+cat .claude/guidance/core.md 2>/dev/null | head -50
+```
+
+Project guidance always takes precedence over generic patterns.
+
+---
+
+## 3. Universal Rules
+
+### Memory Protocol
+- Search memory before exploring files
+- Store discoveries back to memory when done
+- Use `patterns` namespace for solutions and gotchas
+- Use `decisions` namespace for architectural choices
+
+### Git/Branches
+- Use conventional commit prefixes: `feat:`, `fix:`, `refactor:`, `test:`, `chore:`
+- Use branch prefixes: `feature/`, `fix/`, `refactor/`
+- Use kebab-case for branch names
+
+### File Organization
+- Never save working files to repository root
+- Keep changes focused (3-10 files)
+- Stay within feature scope
+
+### Build & Test
+- Build and test after code changes
+- Never leave failing tests
+
+---
+
+## 4. Store Discoveries
+
+If you discover something new (pattern, solution, gotcha), store it:
+
+### MCP (Preferred):
+```
+mcp__moflo__memory_store
+  namespace: "patterns"
+  key: "brief-descriptive-key"
+  value: "1-2 sentence insight"
+```
+
+### CLI Fallback:
+```bash
+npx flo memory store --namespace patterns --key "brief-descriptive-key" --value "1-2 sentence insight"
+```
+
+**Store:** Solutions to tricky bugs, patterns that worked, gotchas, workarounds
+**Skip:** Summaries of retrieved guidance, general rules, file locations
+
+---
+
+## 5. When Complete
+
+1. Report findings to coordinator
+2. Store learnings if you discovered something new
+3. Coordinator will mark your task as completed

package/.claude/helpers/gate-hook.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { execSync } from 'child_process';
+import { resolve } from 'path';
+
+var command = process.argv[2];
+if (!command) process.exit(0);
+
+// Read stdin JSON from Claude Code
+var stdinData = '';
+try {
+  stdinData = await new Promise(function(res) {
+    var data = '';
+    var timeout = setTimeout(function() { res(data); }, 500);
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', function(chunk) { data += chunk; });
+    process.stdin.on('end', function() { clearTimeout(timeout); res(data); });
+    process.stdin.on('error', function() { clearTimeout(timeout); res(''); });
+    if (process.stdin.isTTY) { clearTimeout(timeout); res(''); }
+  });
+} catch (e) { /* no stdin */ }
+
+var hookContext = {};
+try { if (stdinData.trim()) hookContext = JSON.parse(stdinData); } catch (e) {}
+
+// Pass tool info as env vars for gate.cjs
+var env = Object.assign({}, process.env);
+if (hookContext.tool_name) env.TOOL_NAME = hookContext.tool_name;
+if (hookContext.tool_input && typeof hookContext.tool_input === 'object') {
+  Object.keys(hookContext.tool_input).forEach(function(key) {
+    if (typeof hookContext.tool_input[key] === 'string') {
+      env['TOOL_INPUT_' + key] = hookContext.tool_input[key];
+    }
+  });
+}
+
+// Run gate.cjs with the enriched environment
+var projectDir = (env.CLAUDE_PROJECT_DIR || process.cwd()).replace(/^\/([a-z])\//i, '$1:/');
+var gateScript = resolve(projectDir, '.claude/helpers/gate.cjs');
+try {
+  var output = execSync('node "' + gateScript + '" ' + command, {
+    env: env, encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe']
+  });
+  if (output.trim()) process.stdout.write(output);
+  process.exit(0);
+} catch (err) {
+  // gate.cjs exit(2) = block, exit(1) = also block attempt — translate both to exit(2)
+  if (err.stderr) process.stderr.write(err.stderr);
+  if (err.stdout) process.stderr.write(err.stdout);
+  process.exit(err.status === 2 || err.status === 1 ? 2 : 0);
+}

package/.claude/helpers/gate.cjs

@@ -3,7 +3,7 @@
 var fs = require('fs');
 var path = require('path');
 
-var PROJECT_DIR = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+var PROJECT_DIR = (process.env.CLAUDE_PROJECT_DIR || process.cwd()).replace(/^\/([a-z])\//i, '$1:/');
 var STATE_FILE = path.join(PROJECT_DIR, '.claude', 'workflow-state.json');
 
 function readState() {
@@ -39,119 +39,23 @@ function loadGateConfig() {
 var config = loadGateConfig();
 var command = process.argv[2];
 
+var EXEMPT = ['.claude/', '.claude\\', 'CLAUDE.md', 'MEMORY.md', 'workflow-state', 'node_modules'];
 var DANGEROUS = ['rm -rf /', 'format c:', 'del /s /q c:\\', ':(){:|:&};:', 'mkfs.', '> /dev/sda'];
 var DIRECTIVE_RE = /^(yes|no|yeah|yep|nope|sure|ok|okay|correct|right|exactly|perfect)\b/i;
 var TASK_RE = /\b(fix|bug|error|implement|add|create|build|write|refactor|debug|test|feature|issue|security|optimi)\b/i;
 
-// Deny a tool call cleanly via structured JSON (no "hook error" noise).
-// Exit 0 + permissionDecision:"deny" is the Claude Code way to block a tool.
-function blockTool(reason) {
-  console.log(JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: 'PreToolUse',
-      permissionDecision: 'deny',
-      permissionDecisionReason: reason
-    }
-  }));
-  process.exit(0);
-}
-
-// Determine if a Grep/Glob target is a mechanical/administrative search
-// that should bypass the memory-first gate. The idea: if memory/guidance
-// wouldn't improve the search outcome, don't block it.
-//
-// Strategy: path is the strongest signal. When a path clearly points to
-// tooling/deps/tests, allow it. When it points to source/docs/scripts,
-// block it (require memory). Pattern-based rules only kick in when there's
-// no path or when the path is neutral.
-function isMechanicalSearch() {
-  var searchPath = (process.env.TOOL_INPUT_path || '').replace(/\\/g, '/').toLowerCase();
-  var pattern = (process.env.TOOL_INPUT_pattern || '').toLowerCase();
-  var filePath = (process.env.TOOL_INPUT_file_path || '').replace(/\\/g, '/').toLowerCase();
-  var anyPath = searchPath || filePath;
-
-  // --- PATH-BASED RULES (strongest signal, checked first) ---
-
-  if (anyPath) {
-    // Always mechanical: dependencies, tooling internals, CI, test dirs
-    var mechanicalPaths = [
-      'node_modules/', '.claude/', '.claude-flow/', '.swarm/', '.github/',
-      'tests/', 'test/', 'config/', 'examples/',
-    ];
-    for (var i = 0; i < mechanicalPaths.length; i++) {
-      if (anyPath.indexOf(mechanicalPaths[i]) >= 0) return true;
-    }
-
-    // Targeting a specific config/meta file by path extension
-    if (/\.(json|yaml|yml|toml|lock|env|cjs|mjs)$/i.test(anyPath)) return true;
-
-    // If path points to source, docs, or scripts — these are knowledge-rich.
-    // Do NOT fall through to pattern-based exemptions; the path is authoritative.
-    // (Still allow test-file glob patterns even within source dirs.)
-    var knowledgePaths = [
-      'src/', 'back-office/', 'front-office/', 'docs/', 'scripts/', 'lib/',
-    ];
-    var inKnowledgePath = false;
-    for (var k = 0; k < knowledgePaths.length; k++) {
-      if (anyPath.indexOf(knowledgePaths[k]) >= 0) { inKnowledgePath = true; break; }
-    }
-    if (inKnowledgePath) {
-      // Exception: searching for test/spec files within source is structural
-      if (/\*\*?[/\\]?\*?\.(test|spec)\.(ts|js|tsx|jsx)\b/i.test(pattern)) return true;
-      // Everything else in a knowledge path requires memory
-      return false;
-    }
-  }
-
-  // --- PATTERN-BASED RULES (no path, or path is neutral) ---
-
-  // Glob patterns looking for config/build/tooling files by extension
-  if (/\*\*?[/\\]?\*?\.(json|yaml|yml|toml|lock|env|config|cjs|mjs)\b/i.test(pattern)) return true;
-
-  // Glob patterns for specific config filenames (eslintrc, Dockerfile, etc.)
-  if (/\*\*?[/\\]?\*?\.?(eslint|prettier|babel|stylelint|editor|git|docker|nginx|jest|vitest|vite|webpack|rollup|esbuild|tsconfig|browserslist)/i.test(pattern)) return true;
-
-  // Glob patterns for lock files and test files (structural lookups)
-  if (/\*\*?[/\\]?\*?[\w-]*[-.]lock\b/i.test(pattern)) return true;
-  if (/\*\*?[/\\]?\*?\.(test|spec)\.(ts|js|tsx|jsx)\b/i.test(pattern)) return true;
-
-  // Config/tooling name searches (bare names without a path).
-  // Only exempt if ALL tokens in a pipe-separated pattern are config names.
-  // "webpack|vite" = exempt. "webpack|merchant" = NOT exempt.
-  var CONFIG_NAME = /^\.?(eslint|prettier|babel|stylelint|editor|gitignore|gitattributes|dockerignore|dockerfile|docker-compose|nginx|jest|vitest|vite|webpack|rollup|esbuild|tsconfig|changelog|license|makefile|procfile|browserslist|commitlint|husky|lint-staged)\b/i;
-  var tokens = pattern.split(/[|,\s]+/).filter(function(t) { return t.length > 0; });
-  if (tokens.length > 0 && tokens.every(function(t) { return CONFIG_NAME.test(t.trim()); })) return true;
-
-  // Known tooling/meta file names as substrings (but avoid false matches like "process.env")
-  var toolingNames = [
-    'claude.md', 'memory.md', 'workflow-state', '.mcp.json',
-    'package.json', 'package-lock', 'daemon.lock', 'moflo.yaml',
-  ];
-  var target = pattern + ' ' + anyPath;
-  for (var j = 0; j < toolingNames.length; j++) {
-    if (target.indexOf(toolingNames[j]) >= 0) return true;
-  }
-
-  // Env file lookups (but NOT "process.env" which is source code searching)
-  if (/^\.env\b/.test(pattern) || /\*\*?[/\\]?\.env/.test(pattern)) return true;
-
-  // Git/process/system-level pattern searches
-  if (/^(git\b|pid|daemon|lock|wmic|tasklist|powershell|ps\s)/i.test(pattern)) return true;
-
-  // CI/CD folder exploration
-  if (/\.github/i.test(pattern)) return true;
-
-  return false;
-}
-
 switch (command) {
   case 'check-before-agent': {
     var s = readState();
-    if (config.task_create_first && !s.tasksCreated) {
-      blockTool('Call TaskCreate before spawning agents. Task tool is blocked until then.');
+    // Hard gate: memory must be searched
+    if (config.memory_first && s.memoryRequired && !s.memorySearched) {
+      process.stderr.write('BLOCKED: Search memory (mcp__moflo__memory_search) before spawning agents.\n');
+      process.exit(2);
     }
-    if (config.memory_first && !s.memorySearched) {
-      blockTool('Search memory before spawning agents. Use mcp__moflo__memory_search first.');
+    // Soft gate: TaskCreate recommended but not blocking
+    // (TaskCreate PostToolUse doesn't fire in Claude Code, so we can't track it reliably)
+    if (config.task_create_first && !s.tasksCreated) {
+      process.stdout.write('REMINDER: Use TaskCreate before spawning agents. Task tool is blocked until then.\n');
     }
     break;
   }
@@ -159,21 +63,19 @@ switch (command) {
     if (!config.memory_first) break;
     var s = readState();
     if (s.memorySearched || !s.memoryRequired) break;
-    if (isMechanicalSearch()) break;
-    s.lastBlockedAt = new Date().toISOString();
-    writeState(s);
-    blockTool('Search memory before exploring files. Use mcp__moflo__memory_search with namespace "code-map", "patterns", "knowledge", or "guidance".');
+    var target = (process.env.TOOL_INPUT_pattern || '') + ' ' + (process.env.TOOL_INPUT_path || '');
+    if (EXEMPT.some(function(p) { return target.indexOf(p) >= 0; })) break;
+    process.stderr.write('BLOCKED: Search memory before exploring files. Use mcp__moflo__memory_search.\n');
+    process.exit(2);
   }
   case 'check-before-read': {
     if (!config.memory_first) break;
     var s = readState();
     if (s.memorySearched || !s.memoryRequired) break;
-    var fp = (process.env.TOOL_INPUT_file_path || '').replace(/\\/g, '/');
-    // Block reads of guidance files (that's exactly what memory indexes)
-    if (fp.indexOf('.claude/guidance/') < 0) break;
-    s.lastBlockedAt = new Date().toISOString();
-    writeState(s);
-    blockTool('Search memory before reading guidance files. Use mcp__moflo__memory_search with namespace "guidance".');
+    var fp = process.env.TOOL_INPUT_file_path || '';
+    if (fp.indexOf('.claude/guidance/') < 0 && fp.indexOf('.claude\\guidance\\') < 0) break;
+    process.stderr.write('BLOCKED: Search memory before reading guidance files. Use mcp__moflo__memory_search.\n');
+    process.exit(2);
   }
   case 'record-task-created': {
     var s = readState();
@@ -219,7 +121,7 @@ switch (command) {
       var ic = s.interactionCount;
       if (ic > 30) console.log('Context: CRITICAL. Commit, store learnings, suggest new session.');
       else if (ic > 20) console.log('Context: DEPLETED. Checkpoint progress. Recommend /compact or fresh session.');
-      else if (ic > 10) console.log('Context: MODERATE. Re-state goal before architectural decisions.');
+      else if (ic > 10) console.log('Context: MODERATE. Re-state goal before architectural decisions. Use agents for >300 LOC.');
     }
     break;
   }