Master Control ⚡

📦 Public Archive — November 2025

This project is being archived as a public reference implementation of a multi-agent website optimization platform. It demonstrates practical patterns for local-first agent orchestration, tri-swarm analysis (PMM + QA + AEO), and reproducible agent-driven QA/SEO workflows.

Note: The repository remains available for reference and reuse. Active development has stopped; see docs/ARCHIVE_SUMMARY.md and the archived docs in docs/legacy/ for details about moved content and rationale.

Status: Archived — read-only reference (no active maintenance)

---

Multi-Agent Grid Optimization Platform

Master Control is a comprehensive agent platform that deploys specialized programs to analyze, optimize, and enhance websites using AI-powered agents with memory, learning, and cross-agent collaboration.

"I fight for the users." - Tron

---

🎯 What Is Master Control?

Master Control deploys intelligent programs (agents) that work together to optimize your grid (website):

1. ⚡ PMM Agent - Product Marketing analysis (clarity, positioning, 7-second rule)
2. ⚡ QA Agent - Quality assurance with 6 specialized sub-agents
3. ⚡ Git Agent - Clean conventional commit generation
4. ⚡ AEO Agent - SEO/AEO optimization via SwarmCoordinator

Stop manually analyzing websites. Let Master Control deploy the programs.

---

✨ Key Features

🏭 Agent Factory Architecture

• ~90% code reuse for new agents via base class
• Memory integration with AgentDB
• Cross-learning between agents
• Type-safe TypeScript with generics
• Battle-tested on production sites

🧠 Memory & Learning

• AgentDB integration stores patterns and insights
• Vector embeddings for semantic search
• Success rate tracking for fixes
• Cross-agent knowledge sharing
• Continuous improvement with each analysis

🐝 Swarm Coordination

• Parallel execution of multiple agents
• TriSwarm runs PMM + QA + AEO simultaneously
• Cross-learning validates insights across agents
• Auto-balancing for optimal performance

---

🚀 Quick Start

Installation

npm install @mastercontrol/grid

Deploy Your First Swarm

# Analyze local grid
npm run grid:swarm http://localhost:3000

# Or use the CLI
npx mcp analyze https://yoursite.com

Results

⚡ Master Control Analysis Complete

📊 Tri-Swarm Results:
   PMM Clarity: 100/100 ✅
   7-Second Test: FAIL (value proposition not in first impression)
   QA Quality: 95/100 ✅
   AEO Score: 88/100 ✅

🎯 Key Findings:
   • 3 PMM issues detected
   • 2 QA warnings (performance)
   • 5 AEO optimizations recommended
   • 8 cross-learnings discovered

💾 Stored 15 patterns in AgentDB memory core

End of line.

---

🎮 Available Commands

Slash Commands (Claude Code)

/mcp-analyze <url>           # Grid analysis protocol
/mcp-grid-optimize           # Complete optimization
/mcp-swarm <url>             # Deploy multi-program swarm
/mcp-tri-swarm <url>         # Deploy PMM + QA + AEO swarms

NPM Scripts

npm run grid:analyze         # Analyze grid
npm run grid:optimize        # Optimize grid
npm run grid:swarm           # Deploy tri-swarm
npm run commit               # Generate conventional commit
npm run commit:push          # Commit and push

CLI Commands

mcp analyze <url>            # Analyze grid
master-control optimize      # Optimize grid

---

⚡ Agent Programs

1. PMM Agent (Product Marketing Manager)

Analyzes product marketing using FletchPMM principles:

Core Principles:

• ✅ Clarity Over Cleverness - "More people buy if they understand what it is"
• ✅ 7-Second Rule - Communicate value immediately
• ✅ Product-First - Focus on WHAT you do, not just outcomes
• ✅ Primary Audience - Pick one, serve them well

What It Analyzes:

• Clarity score (0-100)
• 7-second test pass/fail
• Competitive positioning
• Messaging quality
• Primary audience identification

Example:

const pmmAgent = new PMMAgent({ memory, verbose: true });

const result = await pmmAgent.analyze({
  url: 'https://example.com',
  html: pageHtml,
  text: pageText,
  metadata: { title, description }
});

console.log(`Clarity: ${result.clarity.score}/100`);
console.log(`7-Second Test: ${result.sevenSecondTest.passed ? 'PASS' : 'FAIL'}`);

2. QA Agent (Quality Assurance)

Autonomous testing with 6 specialized sub-agents:

Sub-Agents:

1. Smoke Agent - Page load validation
2. Link Agent - Navigation integrity
3. Console Agent - JS error detection (with false positive filtering)
4. Accessibility Agent - WCAG compliance
5. Form Agent - Enhanced detection (Shadcn/ui, React Hook Form)
6. Performance Agent - Load time optimization

What It Tests:

• Page accessibility (HTTP 200)
• Broken links
• Console errors (filters SSL/CDN false positives)
• Accessibility violations
• Form functionality
• Performance metrics (A-F grade)

Example:

const qaAgent = new QAAgent({ memory, verbose: true });

const result = await qaAgent.analyze({
  baseUrl: 'https://example.com',
  maxPages: 10
});

console.log(`Overall Score: ${result.summary.overallScore}/100`);
console.log(`Pages Pass: ${result.summary.pagesPass}/${result.totalPages}`);

3. Git Agent (Commit Management)

Generates professional conventional commits:

Features:

• Analyzes staged changes
• Detects type (feat/fix/refactor/docs/test/chore)
• Extracts scope from directory structure
• Identifies breaking changes
• Interactive confirmation
• Never mentions "Claude" or "AI"

Example:

npm run commit

🔍 Analyzing staged changes...

📊 Change Analysis:
   Type: feat (agents)
   Files: 3
   Changes: +546 -0

📝 Commit Message:
   feat(agents): implement git management agent

   Added GitAgent using Agent Factory pattern.

❓ Commit with this message? (y/n)

4. AEO Agent (SEO/AEO Optimization)

Automated SEO via SwarmCoordinator:

What It Analyzes:

• Schema.org detection
• Meta tag quality
• Heading structure
• Readability scores
• Content optimization

Handled by: Multi-agent swarm system

---

🏭 Agent Factory Pattern

All agents extend a common base class:

import { AgentFactory, type AgentFactoryConfig } from './agents/base/agent-factory.js';

export class MyAgent extends AgentFactory<MyInput, MyResult> {
  constructor(config: AgentFactoryConfig) {
    super({
      ...config,
      agentType: 'my-agent',
      enableLearning: true
    });
  }

  async analyze(input: MyInput): Promise<MyResult> {
    // Your analysis logic
  }

  async generateRecommendations(result: MyResult): Promise<string[]> {
    // Return recommendations
  }

  protected async storeResults(input, result, recommendations): Promise<number> {
    // Store in memory for learning
  }

  protected async extractPatterns(result: MyResult): Promise<number> {
    // Share insights with other agents
  }
}

Benefits:

• ~90% code reuse for new agents
• Consistent interface across all agents
• Built-in memory integration
• Cross-learning capabilities
• Type safety with TypeScript generics

---

🧠 AgentDB Memory Core

All agents store and retrieve patterns:

// Store fix pattern
await memory.storeFixPattern({
  category: 'cross-learning-aeo',
  issue: 'Meta descriptions prioritize keywords over clarity',
  fix: 'State "what you do" first, then add keywords naturally',
  successRate: 0.85,
  description: 'Clarity-first meta descriptions'
});

// Find similar analyses
const similar = await memory.findSimilarAnalyses('homepage clarity issues', 5);

// Get site experiences
const experiences = await memory.getSimilarSiteExperiences('example.com', 5);

---

🔄 Cross-Learning Matrix

Agents share insights bidirectionally:

┌─────────┐      Insights       ┌─────────┐
│   PMM   │ ←─────────────────→ │   AEO   │
└─────────┘                      └─────────┘
     ↕                                ↕
  Insights                        Insights
     ↕                                ↕
┌─────────┐      Insights       ┌─────────┐
│    QA   │ ←─────────────────→ │   AEO   │
└─────────┘                      └─────────┘

Example Cross-Learning:

• PMM → AEO: "Meta descriptions should state 'what you do' first"
• QA → AEO: "Filter false positives (SSL errors, CDN blocks) before scoring"
• PMM → QA: "Enhanced form detection finds 8+ elements (was 0)"

---

🌐 Analyzing External Websites

Master Control's primary use case is analyzing ANY website - remote, local, or competitor sites.

⚠️ CRITICAL: Always Use Real Agents

DON'T DO THIS ❌

# Manual analysis (WRONG!)
cat app/layout.tsx
grep "title" app/page.tsx
# → Guess scores like "PMM: 90/100"

DO THIS INSTEAD ✅

# Run REAL agents (CORRECT!)
node scripts/full-swarm-analysis.mjs /path/to/repo
# → PMMAgent measures clarity, 7-second test
# → QAAgent tests links, performance
# → GitAgent analyzes commits
# → Results are MEASURED, not guessed

Why This Matters

Manual analysis vs real agents:

• Manual Guess: PMM Clarity 90/100, 7-Second Test PASS ❌
• Real Agent: PMM Clarity 100/100, 7-Second Test FAIL ✅
• Discovery: Found 3 bugs in PMMAgent by running on real sites!

Lesson Stored in AgentDB:

{
  category: 'cross-learning-platform',
  issue: 'Manual analysis performed instead of using validated agents',
  fix: 'ALWAYS run real agents with TriSwarm',
  successRate: 1.0
}

Analysis Workflow Options

Option 1: Remote Website + Local Repository

node scripts/analyze-external-site.mjs https://example.com /path/to/repo

What it does:

1. Crawls live site with Puppeteer
2. Runs PMMAgent (clarity, positioning)
3. Runs QAAgent (links, performance)
4. Analyzes git history
5. Generates recommendations

Option 2: Local Repository Only

node scripts/full-swarm-analysis.mjs /path/to/repo

What it does:

1. Extracts page data from local files
2. Runs PMMAgent
3. Runs GitAgent
4. Stores patterns in AgentDB
5. Cross-learning between agents

Option 3: Full Tri-Swarm

node scripts/run-tri-swarm.mjs https://example.com ./public

What it does:

1. Deploys AEO + PMM + QA swarms in parallel
2. Cross-learning between all three
3. Stores comprehensive patterns
4. Generates unified report

---

📊 Real-World Case Study: mattstrautmann.com

Analysis Performed:

git clone https://github.com/matt-strautmann/mattstrautmann.com /tmp/site
node scripts/full-swarm-analysis.mjs /tmp/site

Agents Found:

1. PMMAgent - 7-Second Test FAIL (value proposition unclear)
2. PMMAgent - Primary audience misdetected as "AI search engines" (BUG!)
3. PMMAgent - CTA detection missed React Link components (BUG!)
4. GitAgent - Claude found in all 52 commits
5. AEOAgent - Meta description too long (169 → 152 chars)

Fixes Applied:

1. Fixed 3 bugs in PMMAgent
2. Cleaned git history
3. Optimized meta description
4. Enhanced H1 tag
5. Added Speed Insights

Results:

• SEO Score: 85/100 → 95/100 (+10 points)
• Grade: A → A+
• Git History: Clean (no Claude mentions)
• PMMAgent: Now works for ALL products, not just calculators

Lesson: Running real agents on real sites finds bugs that unit tests miss!

---

🔧 Configuration

Environment Variables

# Memory core settings
AEO_MEMORY_PATH=./data/aeo-memory.db
AEO_MEMORY_CACHE_SIZE=100

# Swarm settings
AEO_MAX_CONCURRENT_AGENTS=6

# Auto-optimization
AEO_AUTO_FIX=true
AEO_CONFIDENCE_THRESHOLD=0.75

# Output
VERBOSE=true

Agent Configuration

const triSwarm = new TriSwarmCoordinator({
  memory,
  enableAEO: true,
  enablePMM: true,
  enableQA: true,
  enableCrossLearning: true,
  maxConcurrentAgents: 6,
  verbose: true,
  baseUrl: 'https://example.com'
});

---

📈 Performance Metrics

Metric	Value
Agent creation	<100ms
Analysis time	5-10s per page
Memory storage	<50ms per pattern
Cross-learning	Real-time
API costs	$0 (rule-based)
Platform score	9.2/10 production-ready

---

🛠️ Development

Build & Test

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests
npm test

# Run with coverage
npm run test:coverage

Creating New Agents

1. Define types:

export interface MyAgentInput {
  url: string;
  data: any;
}

export interface MyAgentResult {
  score: number;
  findings: string[];
}

2. Extend AgentFactory:

export class MyAgent extends AgentFactory<MyAgentInput, MyAgentResult> {
  constructor(config: AgentFactoryConfig) {
    super({ ...config, agentType: 'my-agent' });
  }

  async analyze(input: MyAgentInput): Promise<MyAgentResult> {
    // Implementation
  }

  async generateRecommendations(result: MyAgentResult): Promise<string[]> {
    // Implementation
  }
}

3. Add cross-learning:

protected async extractPatterns(result: MyAgentResult): Promise<number> {
  await this.storeFixPattern({
    category: 'cross-learning-aeo',
    issue: 'Example issue',
    fix: 'Example fix',
    successRate: 0.90
  });
  return 1;
}

---

🎯 Best Practices

1. Always Run Full Swarm

# For local repos
node scripts/full-swarm-analysis.mjs /path/to/repo

# For remote sites
node scripts/analyze-external-site.mjs https://example.com /path/to/repo

2. Store Lessons in AgentDB

await memory.storeFixPattern({
  category: 'cross-learning-platform',
  issue: 'Description of what went wrong',
  fix: 'How to do it correctly',
  successRate: 1.0
});

3. Validate Agent Results

Check:

1. Does the clarity score make sense?
2. Did it find issues you know exist?
3. Are recommendations actionable?
4. Did it store patterns in memory?

4. Test on Multiple Sites

# Validate agents work for different use cases
node scripts/analyze-external-site.mjs https://portfolio.com /tmp/site1
node scripts/analyze-external-site.mjs https://saas-product.com /tmp/site2
node scripts/analyze-external-site.mjs https://blog.com /tmp/site3

---

📚 Documentation

• CLAUDE.md - Complete integration guide
• PLATFORM_VALIDATION_REPORT.md - 9.2/10 production-ready validation
• ENHANCEMENT_ROADMAP.md - 12-week implementation plan
• LESSONS_LEARNED.md - Critical mistakes and fixes

---

🚨 Troubleshooting

Issue: Agents not finding issues

Solution: Verify you're running REAL agents, not manual analysis

Issue: Memory core not persisting

Solution:

ls -la ./data/aeo-memory.db
chmod 755 ./data

Issue: Swarm using excessive resources

Solution:

echo "AEO_MAX_CONCURRENT_AGENTS=3" >> .env

---

📄 License

MIT

👤 Author

Matt Strautmann

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md

🔗 Links

• Repository: https://github.com/matt-strautmann/aeo-now
• Issues: https://github.com/matt-strautmann/aeo-now/issues
• Documentation: See CLAUDE.md for complete guide

---

⚡ Master Control Program

Multi-agent platform for grid optimization and analysis.

Built with Agent Factory Architecture, AgentDB Memory Core, and Cross-Agent Learning.

I fight for the users. End of line.