@agentlee5/agent-skills 1.0.0

package/LeeWay-Standards/src/agents/discovery/schema-agent.js

@@ -0,0 +1,116 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: SEO.AGENT.SCHEMA
+TAG: SEO.SCHEMA.AGENT.MAIN
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=code
+
+5WH:
+WHAT = Schema agent — generates machine-readable schemas and capability metadata
+WHY = Applications must expose structured data for AI tools, search engines, and voice assistants
+WHO = Rapid Web Development
+WHERE = src/agents/discovery/schema-agent.js
+WHEN = 2026
+HOW = Generates Schema.org JSON-LD, OpenGraph, and capability manifest from LEEWAY metadata
+
+AGENTS:
+SCHEMA
+SITEMAP
+DISCOVERY
+
+LICENSE:
+MIT
+*/
+
+/**
+ * SchemaAgent generates structured discovery metadata from LEEWAY headers and config.
+ */
+export class SchemaAgent {
+  /**
+   * Generate Schema.org JSON-LD for a software application.
+   *
+   * @param {{ name: string, description: string, url?: string, version?: string, author?: string }} config
+   * @returns {object} - JSON-LD schema object
+   */
+  generateSoftwareApplicationSchema(config) {
+    return {
+      '@context': 'https://schema.org',
+      '@type': 'SoftwareApplication',
+      name: config.name,
+      description: config.description,
+      url: config.url || '',
+      version: config.version || '1.0.1',
+      author: {
+        '@type': 'Organization',
+        name: config.author || 'Unknown',
+      },
+      applicationCategory: 'DeveloperApplication',
+      operatingSystem: 'Cross-platform',
+    };
+  }
+
+  /**
+   * Generate OpenGraph metadata tags.
+   *
+   * @param {{ title: string, description: string, url?: string, image?: string, type?: string }} config
+   * @returns {object[]} - Array of meta tag objects
+   */
+  generateOpenGraphMeta(config) {
+    return [
+      { property: 'og:title', content: config.title },
+      { property: 'og:description', content: config.description },
+      { property: 'og:type', content: config.type || 'website' },
+      { property: 'og:url', content: config.url || '' },
+      { property: 'og:image', content: config.image || '' },
+    ];
+  }
+
+  /**
+   * Generate FAQ structured data from a Q&A list.
+   *
+   * @param {{ question: string, answer: string }[]} faqs
+   * @returns {object} - FAQ JSON-LD schema
+   */
+  generateFAQSchema(faqs) {
+    return {
+      '@context': 'https://schema.org',
+      '@type': 'FAQPage',
+      mainEntity: faqs.map(({ question, answer }) => ({
+        '@type': 'Question',
+        name: question,
+        acceptedAnswer: {
+          '@type': 'Answer',
+          text: answer,
+        },
+      })),
+    };
+  }
+
+  /**
+   * Generate a LEEWAY capability manifest for a module.
+   *
+   * @param {{ name: string, region: string, tag: string, fiveWH: object, agents: string[] }} header
+   * @returns {object} - Capability manifest
+   */
+  generateCapabilityManifest(header) {
+    return {
+      leeway: '1.0',
+      identity: {
+        name: header.name || header.fiveWH?.WHAT || 'Unknown',
+        region: header.region,
+        tag: header.tag,
+      },
+      fiveWH: header.fiveWH,
+      authorizedAgents: header.agents || [],
+      generated: new Date().toISOString(),
+    };
+  }
+}

package/LeeWay-Standards/src/agents/discovery/sitemap-agent.js

@@ -0,0 +1,88 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: SEO.AGENT.SITEMAP
+TAG: SEO.SITEMAP.AGENT.MAIN
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=map
+
+5WH:
+WHAT = Sitemap agent — builds site and discovery maps from LEEWAY registry
+WHY = Applications must expose sitemaps for crawlers, search engines, and AI indexers
+WHO = Rapid Web Development
+WHERE = src/agents/discovery/sitemap-agent.js
+WHEN = 2026
+HOW = Reads route registrations and LEEWAY headers to build XML and JSON sitemaps
+
+AGENTS:
+SITEMAP
+SCHEMA
+REGISTRY
+
+LICENSE:
+MIT
+*/
+
+/**
+ * SitemapAgent builds XML and JSON sitemaps from route registrations.
+ */
+export class SitemapAgent {
+  constructor(options = {}) {
+    this.baseUrl = options.baseUrl || 'https://example.com';
+    this.routes = [];
+  }
+
+  /**
+   * Add a route to the sitemap.
+   *
+   * @param {{ path: string, priority?: number, changefreq?: string, lastmod?: string }} route
+   */
+  addRoute(route) {
+    this.routes.push({
+      path: route.path,
+      priority: route.priority || 0.5,
+      changefreq: route.changefreq || 'weekly',
+      lastmod: route.lastmod || new Date().toISOString().split('T')[0],
+    });
+  }
+
+  /**
+   * Generate an XML sitemap string.
+   * @returns {string}
+   */
+  generateXML() {
+    const urls = this.routes.map(route => `  <url>
+    <loc>${this.baseUrl}${route.path}</loc>
+    <lastmod>${route.lastmod}</lastmod>
+    <changefreq>${route.changefreq}</changefreq>
+    <priority>${route.priority}</priority>
+  </url>`).join('\n');
+
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${urls}
+</urlset>`;
+  }
+
+  /**
+   * Generate a JSON sitemap.
+   * @returns {object}
+   */
+  generateJSON() {
+    return {
+      baseUrl: this.baseUrl,
+      generated: new Date().toISOString(),
+      routes: this.routes.map(r => ({
+        url: `${this.baseUrl}${r.path}`,
+        ...r,
+      })),
+    };
+  }
+}

package/LeeWay-Standards/src/agents/governance/align-agent.js

@@ -0,0 +1,155 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: AI.AGENT.GOVERNANCE
+TAG: AI.AGENT.ALIGN.MAIN
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=align-left
+
+5WH:
+WHAT = Align agent — normalizes files, settings, transports, ports, and env structure
+WHY = Drift in naming, structure, and configuration breaks governance and causes deployment failures
+WHO = Rapid Web Development
+WHERE = src/agents/governance/align-agent.js
+WHEN = 2026
+HOW = Reads assessment results, proposes normalized corrections, applies non-destructive patches
+
+AGENTS:
+ALIGN
+ASSESS
+
+LICENSE:
+MIT
+*/
+
+import { readFile, writeFile, rename } from 'node:fs/promises';
+import { join, basename, dirname, extname } from 'node:path';
+import { buildHeader, parseHeader } from '../../core/header-parser.js';
+import { inferTag } from '../../core/tag-validator.js';
+import { classifyRegion } from '../../core/region-classifier.js';
+
+/**
+ * AlignAgent normalizes files and structures according to LEEWAY standards.
+ * Operates in dry-run mode by default — set options.dryRun = false to apply changes.
+ */
+export class AlignAgent {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir || process.cwd();
+    this.dryRun = options.dryRun !== false;
+    this.log = options.log || (() => {});
+    this.changes = [];
+  }
+
+  /**
+   * Align a list of files that were identified as needing headers by the assess agent.
+   *
+   * @param {string[]} filePaths - Relative file paths from assessment
+   * @returns {Promise<AlignResult>}
+   */
+  async alignHeaders(filePaths) {
+    const results = [];
+
+    for (const relPath of filePaths) {
+      const fullPath = join(this.rootDir, relPath);
+      try {
+        const content = await readFile(fullPath, 'utf8');
+        const existingHeader = parseHeader(content);
+
+        if (existingHeader) {
+          results.push({ file: relPath, action: 'skipped', reason: 'Header already present' });
+          continue;
+        }
+
+        const regionResult = classifyRegion(relPath);
+        const tag = inferTag(relPath);
+        const fileName = basename(relPath, extname(relPath));
+
+        const header = buildHeader({
+          region: regionResult.region,
+          tag,
+          fiveWH: {
+            WHAT: `${fileName} module`,
+            WHY: `Part of ${regionResult.region} region`,
+            WHO: 'LEEWAY Align Agent',
+            WHERE: relPath,
+            WHEN: new Date().getFullYear().toString(),
+            HOW: 'Auto-aligned by LEEWAY align-agent',
+          },
+          agents: ['ASSESS', 'ALIGN', 'AUDIT'],
+          license: 'MIT',
+        });
+
+        const newContent = header + '\n' + content;
+
+        if (!this.dryRun) {
+          await writeFile(fullPath, newContent, 'utf8');
+        }
+
+        this.changes.push({ type: 'header_added', file: relPath });
+        results.push({ file: relPath, action: 'header_added', dryRun: this.dryRun });
+      } catch (err) {
+        results.push({ file: relPath, action: 'error', reason: err.message });
+      }
+    }
+
+    return {
+      agent: 'align-agent',
+      dryRun: this.dryRun,
+      processed: results.length,
+      results,
+      changes: this.changes,
+    };
+  }
+
+  /**
+   * Align naming conventions for a list of files.
+   * Reports violations without renaming (renaming requires explicit approval).
+   *
+   * @param {string[]} filePaths
+   * @returns {Promise<object[]>}
+   */
+  async checkNaming(filePaths) {
+    const violations = [];
+
+    for (const relPath of filePaths) {
+      const fileName = basename(relPath);
+      const dir = dirname(relPath).toLowerCase();
+      const ext = extname(fileName);
+      const base = basename(fileName, ext);
+
+      const isComponent = dir.includes('component') || dir.includes('page') || dir.includes('layout');
+      const isUtil = dir.includes('util') || dir.includes('helper');
+
+      if (isComponent) {
+        const isPascal = /^[A-Z][a-zA-Z0-9]*$/.test(base);
+        if (!isPascal) {
+          violations.push({
+            file: relPath,
+            issue: 'React component should use PascalCase',
+            current: base,
+            suggested: base.charAt(0).toUpperCase() + base.slice(1),
+          });
+        }
+      } else if (isUtil) {
+        const isCamel = /^[a-z][a-zA-Z0-9]*$/.test(base);
+        const isKebab = /^[a-z][a-z0-9-]*$/.test(base);
+        if (!isCamel && !isKebab) {
+          violations.push({
+            file: relPath,
+            issue: 'Utility file should use camelCase or kebab-case',
+            current: base,
+          });
+        }
+      }
+    }
+
+    return violations;
+  }
+}

package/LeeWay-Standards/src/agents/governance/assess-agent.js

@@ -0,0 +1,161 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: AI.AGENT.GOVERNANCE
+TAG: AI.AGENT.ASSESS.MAIN
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=search
+
+5WH:
+WHAT = Assess agent — surveys what already exists before anything is created or patched
+WHY = Prevents duplicate work, identifies existing patterns, and gives align/audit agents accurate ground truth
+WHO = Rapid Web Development
+WHERE = src/agents/governance/assess-agent.js
+WHEN = 2026
+HOW = Event-driven file walker, dormant until invoked, returns structured inventory
+
+AGENTS:
+ASSESS
+
+LICENSE:
+MIT
+*/
+
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, relative, extname } from 'node:path';
+import { parseHeader } from '../../core/header-parser.js';
+import { classifyRegion } from '../../core/region-classifier.js';
+
+const SKIP_DIRS = new Set(['.git', 'node_modules', 'dist', 'build', '.next', '.cache', 'coverage']);
+const CODE_EXTENSIONS = new Set(['.js', '.ts', '.jsx', '.tsx', '.mjs', '.cjs', '.py', '.go', '.rs']);
+
+/**
+ * AssessAgent surveys a directory for existing files, headers, regions, and patterns.
+ * Must be called before any modification or creation operations.
+ */
+export class AssessAgent {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir || process.cwd();
+    this.maxDepth = options.maxDepth || 10;
+    this.log = options.log || (() => {});
+  }
+
+  /**
+   * Run assessment on the root directory.
+   * @returns {Promise<AssessmentResult>}
+   */
+  async run() {
+    const startTime = Date.now();
+    const inventory = {
+      totalFiles: 0,
+      codeFiles: 0,
+      filesWithHeaders: 0,
+      filesWithoutHeaders: [],
+      regionMap: {},
+      tagMap: {},
+      duplicateTags: [],
+      missingHeaders: [],
+      structure: {},
+    };
+
+    await this._walk(this.rootDir, inventory, 0);
+    this._detectDuplicateTags(inventory);
+
+    return {
+      agent: 'assess-agent',
+      rootDir: this.rootDir,
+      durationMs: Date.now() - startTime,
+      inventory,
+      summary: this._buildSummary(inventory),
+    };
+  }
+
+  async _walk(dir, inventory, depth) {
+    if (depth > this.maxDepth) return;
+
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      const fullPath = join(dir, entry.name);
+      const relPath = relative(this.rootDir, fullPath);
+
+      if (entry.isDirectory()) {
+        inventory.structure[relPath] = 'directory';
+        await this._walk(fullPath, inventory, depth + 1);
+      } else if (entry.isFile()) {
+        inventory.totalFiles++;
+        inventory.structure[relPath] = 'file';
+
+        if (CODE_EXTENSIONS.has(extname(entry.name))) {
+          inventory.codeFiles++;
+          await this._analyzeFile(fullPath, relPath, inventory);
+        }
+      }
+    }
+  }
+
+  async _analyzeFile(fullPath, relPath, inventory) {
+    let content;
+    try {
+      content = await readFile(fullPath, 'utf8');
+    } catch {
+      return;
+    }
+
+    const header = parseHeader(content);
+    if (header) {
+      inventory.filesWithHeaders++;
+
+      if (header.region) {
+        inventory.regionMap[header.region] = (inventory.regionMap[header.region] || 0) + 1;
+      }
+      if (header.tag) {
+        if (!inventory.tagMap[header.tag]) inventory.tagMap[header.tag] = [];
+        inventory.tagMap[header.tag].push(relPath);
+      }
+    } else {
+      inventory.filesWithoutHeaders.push(relPath);
+      inventory.missingHeaders.push(relPath);
+
+      const regionResult = classifyRegion(relPath);
+      const region = regionResult.region;
+      inventory.regionMap[`UNCLASSIFIED.${region}`] = (inventory.regionMap[`UNCLASSIFIED.${region}`] || 0) + 1;
+    }
+  }
+
+  _detectDuplicateTags(inventory) {
+    for (const [tag, files] of Object.entries(inventory.tagMap)) {
+      if (files.length > 1) {
+        inventory.duplicateTags.push({ tag, files });
+      }
+    }
+  }
+
+  _buildSummary(inventory) {
+    const headerCoverage = inventory.codeFiles > 0
+      ? Math.round((inventory.filesWithHeaders / inventory.codeFiles) * 100)
+      : 0;
+
+    return {
+      headerCoverage: `${headerCoverage}%`,
+      codeFiles: inventory.codeFiles,
+      totalFiles: inventory.totalFiles,
+      filesNeedingHeaders: inventory.missingHeaders.length,
+      duplicateTagCount: inventory.duplicateTags.length,
+      regionsFound: Object.keys(inventory.regionMap).filter(r => !r.startsWith('UNCLASSIFIED')).length,
+    };
+  }
+}

package/LeeWay-Standards/src/agents/governance/audit-agent.js

@@ -0,0 +1,185 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: AI.AGENT.GOVERNANCE
+TAG: AI.AGENT.AUDIT.MAIN
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=clipboard-check
+
+5WH:
+WHAT = Audit agent — scores compliance, generates reports, and blocks unsafe changes
+WHY = LEEWAY systems must be continuously validated to remain stable and governable
+WHO = Rapid Web Development
+WHERE = src/agents/governance/audit-agent.js
+WHEN = 2026
+HOW = Aggregates compliance scores across all files, produces JSON and text reports
+
+AGENTS:
+AUDIT
+ASSESS
+
+LICENSE:
+MIT
+*/
+
+import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join, relative, extname } from 'node:path';
+import { scoreCompliance } from '../../core/compliance-scorer.js';
+
+const SKIP_DIRS = new Set(['.git', 'node_modules', 'dist', 'build', '.next', '.cache', 'coverage']);
+const CODE_EXTENSIONS = new Set(['.js', '.ts', '.jsx', '.tsx', '.mjs', '.cjs']);
+
+/**
+ * AuditAgent scores the entire codebase for LEEWAY compliance and generates reports.
+ */
+export class AuditAgent {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir || process.cwd();
+    this.outputDir = options.outputDir || join(this.rootDir, 'reports');
+    this.log = options.log || (() => {});
+  }
+
+  /**
+   * Run a full compliance audit.
+   * @returns {Promise<AuditReport>}
+   */
+  async run() {
+    const startTime = Date.now();
+    const fileResults = [];
+
+    await this._walkAndScore(this.rootDir, fileResults);
+
+    const totalScore = fileResults.length > 0
+      ? Math.round(fileResults.reduce((sum, r) => sum + r.score, 0) / fileResults.length)
+      : 0;
+
+    const report = {
+      agent: 'audit-agent',
+      rootDir: this.rootDir,
+      timestamp: new Date().toISOString(),
+      durationMs: Date.now() - startTime,
+      summary: {
+        totalFiles: fileResults.length,
+        averageScore: totalScore,
+        complianceLevel: this._getLevel(totalScore),
+        passing: fileResults.filter(r => r.score >= 60).length,
+        failing: fileResults.filter(r => r.score < 60).length,
+        platinum: fileResults.filter(r => r.score >= 95).length,
+        gold: fileResults.filter(r => r.score >= 80 && r.score < 95).length,
+        silver: fileResults.filter(r => r.score >= 60 && r.score < 80).length,
+        bronze: fileResults.filter(r => r.score >= 40 && r.score < 60).length,
+        none: fileResults.filter(r => r.score < 40).length,
+      },
+      files: fileResults.sort((a, b) => a.score - b.score),
+    };
+
+    return report;
+  }
+
+  /**
+   * Run audit and write reports to the output directory.
+   * @returns {Promise<AuditReport>}
+   */
+  async runAndSave() {
+    const report = await this.run();
+
+    try {
+      await mkdir(this.outputDir, { recursive: true });
+      const jsonPath = join(this.outputDir, 'leeway-audit.json');
+      const textPath = join(this.outputDir, 'leeway-audit.txt');
+      await writeFile(jsonPath, JSON.stringify(report, null, 2), 'utf8');
+      await writeFile(textPath, this._formatTextReport(report), 'utf8');
+      report.savedTo = { json: jsonPath, text: textPath };
+    } catch (err) {
+      report.saveError = err.message;
+    }
+
+    return report;
+  }
+
+  async _walkAndScore(dir, results, depth = 0) {
+    if (depth > 10) return;
+
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      const fullPath = join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        await this._walkAndScore(fullPath, results, depth + 1);
+      } else if (entry.isFile() && CODE_EXTENSIONS.has(extname(entry.name))) {
+        const relPath = relative(this.rootDir, fullPath);
+        try {
+          const content = await readFile(fullPath, 'utf8');
+          const result = scoreCompliance({ filePath: relPath, content });
+          results.push({ file: relPath, ...result });
+        } catch {
+          results.push({ file: relPath, score: 0, level: 'NONE', issues: ['Could not read file'] });
+        }
+      }
+    }
+  }
+
+  _getLevel(score) {
+    if (score >= 95) return 'PLATINUM';
+    if (score >= 80) return 'GOLD';
+    if (score >= 60) return 'SILVER';
+    if (score >= 40) return 'BRONZE';
+    return 'NONE';
+  }
+
+  _formatTextReport(report) {
+    const lines = [
+      '═══════════════════════════════════════════════════',
+      '           LEEWAY™ COMPLIANCE AUDIT REPORT         ',
+      '═══════════════════════════════════════════════════',
+      `Timestamp : ${report.timestamp}`,
+      `Root Dir  : ${report.rootDir}`,
+      `Duration  : ${report.durationMs}ms`,
+      '',
+      '── SUMMARY ─────────────────────────────────────────',
+      `Total Files     : ${report.summary.totalFiles}`,
+      `Average Score   : ${report.summary.averageScore}/100`,
+      `Compliance Level: ${report.summary.complianceLevel}`,
+      `Passing (≥60)   : ${report.summary.passing}`,
+      `Failing (<60)   : ${report.summary.failing}`,
+      '',
+      '── BREAKDOWN ───────────────────────────────────────',
+      `  🥇 Platinum (95-100): ${report.summary.platinum}`,
+      `  🥈 Gold     (80-94) : ${report.summary.gold}`,
+      `  🥉 Silver   (60-79) : ${report.summary.silver}`,
+      `  🔶 Bronze   (40-59) : ${report.summary.bronze}`,
+      `  ❌ None     (0-39)  : ${report.summary.none}`,
+      '',
+      '── FILES NEEDING ATTENTION ─────────────────────────',
+    ];
+
+    const failing = report.files.filter(f => f.score < 60).slice(0, 20);
+    if (failing.length === 0) {
+      lines.push('  ✅ All files pass minimum compliance threshold');
+    } else {
+      for (const f of failing) {
+        lines.push(`  [${f.score.toString().padStart(3)}] ${f.file}`);
+        for (const issue of (f.issues || []).slice(0, 3)) {
+          lines.push(`         ↳ ${issue}`);
+        }
+      }
+    }
+
+    lines.push('═══════════════════════════════════════════════════');
+    return lines.join('\n');
+  }
+}