@agentlee5/agent-skills 1.0.0

package/LeeWay-Standards/src/agents/standards/header-agent.js

@@ -0,0 +1,120 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: AI.AGENT.STANDARDS
+TAG: AI.AGENT.HEADER.MAIN
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=file-plus
+
+5WH:
+WHAT = Header agent — inserts and repairs LEEWAY headers in source files
+WHY = All LEEWAY files must have a valid identity header; this agent enforces that rule
+WHO = Rapid Web Development
+WHERE = src/agents/standards/header-agent.js
+WHEN = 2026
+HOW = Reads files, detects missing or malformed headers, inserts or repairs as needed
+
+AGENTS:
+HEADER
+ASSESS
+ALIGN
+
+LICENSE:
+MIT
+*/
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseHeader, validateHeader, buildHeader } from '../../core/header-parser.js';
+import { inferTag } from '../../core/tag-validator.js';
+import { classifyRegion } from '../../core/region-classifier.js';
+
+/**
+ * HeaderAgent inserts and repairs LEEWAY headers in source files.
+ */
+export class HeaderAgent {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir || process.cwd();
+    this.dryRun = options.dryRun !== false;
+    this.author = options.author || 'LEEWAY Header Agent';
+  }
+
+  /**
+   * Process a single file — insert header if missing, repair if invalid.
+   *
+   * @param {string} filePath - Absolute or relative file path
+   * @returns {Promise<{ file: string, action: string, dryRun: boolean }>}
+   */
+  async processFile(filePath) {
+    const fullPath = filePath.startsWith('/') ? filePath : join(this.rootDir, filePath);
+    const relPath = filePath.startsWith('/') ? filePath.replace(this.rootDir + '/', '') : filePath;
+
+    let content;
+    try {
+      content = await readFile(fullPath, 'utf8');
+    } catch (err) {
+      return { file: relPath, action: 'error', reason: err.message };
+    }
+
+    const header = parseHeader(content);
+
+    if (!header) {
+      return this._insertHeader(fullPath, relPath, content);
+    }
+
+    const { valid, errors } = validateHeader(header);
+    if (!valid) {
+      return { file: relPath, action: 'needs_repair', errors, dryRun: this.dryRun };
+    }
+
+    return { file: relPath, action: 'valid', dryRun: this.dryRun };
+  }
+
+  async _insertHeader(fullPath, relPath, content) {
+    const regionResult = classifyRegion(relPath);
+    const tag = inferTag(relPath);
+    const fileName = relPath.split('/').pop().replace(/\.[^.]+$/, '');
+
+    const headerBlock = buildHeader({
+      region: regionResult.region,
+      tag,
+      fiveWH: {
+        WHAT: `${fileName} module`,
+        WHY: `${regionResult.metadata.description}`,
+        WHO: this.author,
+        WHERE: relPath,
+        WHEN: new Date().getFullYear().toString(),
+        HOW: 'Auto-inserted by LEEWAY header-agent',
+      },
+      agents: ['ASSESS', 'ALIGN', 'AUDIT'],
+      license: 'MIT',
+    });
+
+    if (!this.dryRun) {
+      await writeFile(fullPath, headerBlock + '\n' + content, 'utf8');
+    }
+
+    return { file: relPath, action: 'header_inserted', dryRun: this.dryRun };
+  }
+
+  /**
+   * Process multiple files.
+   *
+   * @param {string[]} filePaths
+   * @returns {Promise<object[]>}
+   */
+  async processFiles(filePaths) {
+    const results = [];
+    for (const fp of filePaths) {
+      results.push(await this.processFile(fp));
+    }
+    return results;
+  }
+}

package/LeeWay-Standards/src/agents/standards/placement-agent.js

@@ -0,0 +1,96 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: AI.AGENT.STANDARDS
+TAG: AI.AGENT.PLACEMENT.MAIN
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=folder-check
+
+5WH:
+WHAT = Placement agent — checks file placement against LEEWAY directory structure rules
+WHY = Files in wrong directories break discoverability and architecture legibility
+WHO = Rapid Web Development
+WHERE = src/agents/standards/placement-agent.js
+WHEN = 2026
+HOW = Compares declared REGION against expected directory paths, reports misplacements
+
+AGENTS:
+PLACEMENT
+ASSESS
+AUDIT
+
+LICENSE:
+MIT
+*/
+
+import { readFile } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { parseHeader } from '../../core/header-parser.js';
+import { classifyRegion } from '../../core/region-classifier.js';
+
+const REGION_EXPECTED_DIRS = {
+  UI: ['src/components', 'src/pages', 'src/layouts', 'src/ui', 'src/views', 'src/screens'],
+  CORE: ['src/core', 'src/sdk', 'src/lib', 'src/runtime', 'src/engine'],
+  DATA: ['src/data', 'src/store', 'src/stores', 'src/db', 'src/models'],
+  AI: ['src/ai', 'src/agents', 'src/llm', 'src/ml', 'src/prompts'],
+  SEO: ['src/seo', 'src/discovery', 'src/schema', 'src/sitemap'],
+  UTIL: ['src/utils', 'src/util', 'src/helpers', 'src/shared'],
+  MCP: ['src/mcp', 'src/transport', 'src/endpoints'],
+  SECURITY: ['src/security', 'src/auth', 'src/authorization'],
+  TEST: ['src/tests', 'src/__tests__', 'test', 'tests', '__tests__'],
+  DOCS: ['docs', 'documentation', 'guides'],
+};
+
+/**
+ * PlacementAgent validates that files are in the correct LEEWAY directories.
+ */
+export class PlacementAgent {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir || process.cwd();
+  }
+
+  /**
+   * Check placement of a file.
+   *
+   * @param {string} filePath
+   * @returns {Promise<PlacementResult>}
+   */
+  async checkFile(filePath) {
+    const fullPath = filePath.startsWith('/') ? filePath : join(this.rootDir, filePath);
+    const relPath = filePath.startsWith('/') ? filePath.replace(this.rootDir + '/', '') : filePath;
+    const normalizedPath = relPath.replace(/\\/g, '/');
+
+    let content = '';
+    try {
+      content = await readFile(fullPath, 'utf8');
+    } catch {
+      return { file: relPath, status: 'error' };
+    }
+
+    const header = parseHeader(content);
+    const declaredRegion = header?.region?.split('.')?.[0];
+    const { region: inferredRegion, confidence } = classifyRegion(relPath);
+
+    const regionToCheck = declaredRegion || inferredRegion;
+    const expectedDirs = REGION_EXPECTED_DIRS[regionToCheck] || [];
+    const isCorrectlyPlaced = expectedDirs.length === 0
+      || expectedDirs.some(dir => normalizedPath.startsWith(dir.replace(/^\//, '')));
+
+    return {
+      file: relPath,
+      declaredRegion,
+      inferredRegion,
+      confidence,
+      expectedDirectories: expectedDirs,
+      status: isCorrectlyPlaced ? 'correct' : 'misplaced',
+      suggestion: isCorrectlyPlaced ? null : `Move to one of: ${expectedDirs.slice(0, 3).join(', ')}`,
+    };
+  }
+}

package/LeeWay-Standards/src/agents/standards/region-agent.js

@@ -0,0 +1,99 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: AI.AGENT.STANDARDS
+TAG: AI.AGENT.REGION.MAIN
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=map
+
+5WH:
+WHAT = Region agent — assigns REGION correctly to files based on path and content
+WHY = Files must belong to the correct system region for governance and discoverability
+WHO = Rapid Web Development
+WHERE = src/agents/standards/region-agent.js
+WHEN = 2026
+HOW = Path analysis and content scanning to determine the most appropriate region
+
+AGENTS:
+REGION
+ASSESS
+
+LICENSE:
+MIT
+*/
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { classifyRegion, REGIONS } from '../../core/region-classifier.js';
+import { parseHeader } from '../../core/header-parser.js';
+
+/**
+ * RegionAgent assigns and validates LEEWAY REGION values.
+ */
+export class RegionAgent {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir || process.cwd();
+  }
+
+  /**
+   * Analyze a file and determine its correct REGION.
+   *
+   * @param {string} filePath
+   * @returns {Promise<RegionAnalysis>}
+   */
+  async analyzeFile(filePath) {
+    const fullPath = filePath.startsWith('/') ? filePath : join(this.rootDir, filePath);
+    const relPath = filePath.startsWith('/') ? filePath.replace(this.rootDir + '/', '') : filePath;
+
+    let content = '';
+    try {
+      content = await readFile(fullPath, 'utf8');
+    } catch {
+      return { file: relPath, status: 'error' };
+    }
+
+    const header = parseHeader(content);
+    const { region: inferredRegion, confidence, metadata } = classifyRegion(relPath);
+
+    if (!header) {
+      return {
+        file: relPath,
+        status: 'no_header',
+        inferredRegion,
+        confidence,
+        description: metadata.description,
+      };
+    }
+
+    const declaredRegion = header.region ? header.region.split('.')[0] : null;
+    const mismatch = declaredRegion && declaredRegion !== inferredRegion && confidence === 'high';
+
+    return {
+      file: relPath,
+      status: mismatch ? 'region_mismatch' : 'valid',
+      declaredRegion: header.region,
+      inferredRegion,
+      confidence,
+      description: metadata.description,
+      mismatch,
+    };
+  }
+
+  /**
+   * Get a summary of all available regions.
+   * @returns {object}
+   */
+  getRegionMap() {
+    return Object.entries(REGIONS).reduce((acc, [key, val]) => {
+      acc[key] = { label: val.label, description: val.description, color: val.color };
+      return acc;
+    }, {});
+  }
+}

package/LeeWay-Standards/src/agents/standards/registry-agent.js

@@ -0,0 +1,153 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: AI.AGENT.STANDARDS
+TAG: AI.AGENT.REGISTRY.MAIN
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=database
+
+5WH:
+WHAT = Registry agent — updates tag registry, file registry, and system map
+WHY = A LEEWAY system needs a queryable registry of all files and their identities
+WHO = Rapid Web Development
+WHERE = src/agents/standards/registry-agent.js
+WHEN = 2026
+HOW = Walks codebase, reads LEEWAY headers, writes to .leeway/registry.json
+
+AGENTS:
+REGISTRY
+ASSESS
+AUDIT
+
+LICENSE:
+MIT
+*/
+
+import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join, relative, extname } from 'node:path';
+import { parseHeader } from '../../core/header-parser.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']);
+
+/**
+ * RegistryAgent builds and updates the LEEWAY file and tag registries.
+ */
+export class RegistryAgent {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir || process.cwd();
+    this.registryDir = join(this.rootDir, '.leeway');
+    this.registryPath = join(this.registryDir, 'registry.json');
+  }
+
+  /**
+   * Build the registry from the current codebase.
+   * @returns {Promise<Registry>}
+   */
+  async build() {
+    const registry = {
+      version: '1.0.1',
+      built: new Date().toISOString(),
+      rootDir: this.rootDir,
+      files: {},
+      tags: {},
+      regions: {},
+    };
+
+    await this._walk(this.rootDir, registry);
+    return registry;
+  }
+
+  /**
+   * Build and persist the registry to .leeway/registry.json
+   * @returns {Promise<Registry>}
+   */
+  async buildAndSave() {
+    const registry = await this.build();
+
+    try {
+      await mkdir(this.registryDir, { recursive: true });
+      await writeFile(this.registryPath, JSON.stringify(registry, null, 2), 'utf8');
+      registry.savedTo = this.registryPath;
+    } catch (err) {
+      registry.saveError = err.message;
+    }
+
+    return registry;
+  }
+
+  /**
+   * Load the existing registry from disk.
+   * @returns {Promise<Registry | null>}
+   */
+  async load() {
+    try {
+      const raw = await readFile(this.registryPath, 'utf8');
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
+
+  async _walk(dir, registry, 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);
+      const relPath = relative(this.rootDir, fullPath);
+
+      if (entry.isDirectory()) {
+        await this._walk(fullPath, registry, depth + 1);
+      } else if (entry.isFile() && CODE_EXTENSIONS.has(extname(entry.name))) {
+        await this._indexFile(fullPath, relPath, registry);
+      }
+    }
+  }
+
+  async _indexFile(fullPath, relPath, registry) {
+    let content;
+    try {
+      content = await readFile(fullPath, 'utf8');
+    } catch {
+      return;
+    }
+
+    const header = parseHeader(content);
+    const entry = {
+      path: relPath,
+      hasHeader: !!header,
+      region: header?.region || null,
+      tag: header?.tag || null,
+      agents: header?.agents || [],
+      license: header?.license || null,
+      fiveWH: header?.fiveWH || {},
+    };
+
+    registry.files[relPath] = entry;
+
+    if (header?.tag) {
+      if (!registry.tags[header.tag]) registry.tags[header.tag] = [];
+      registry.tags[header.tag].push(relPath);
+    }
+
+    if (header?.region) {
+      const regionKey = header.region.split('.')[0];
+      registry.regions[regionKey] = (registry.regions[regionKey] || 0) + 1;
+    }
+  }
+}

package/LeeWay-Standards/src/agents/standards/tag-agent.js

@@ -0,0 +1,111 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: AI.AGENT.STANDARDS
+TAG: AI.AGENT.TAG.MAIN
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=tag
+
+5WH:
+WHAT = Tag agent — infers TAG values from file path, purpose, and role
+WHY = Every file needs an accurate TAG for the system to be machine-searchable
+WHO = Rapid Web Development
+WHERE = src/agents/standards/tag-agent.js
+WHEN = 2026
+HOW = Uses path heuristics and file content analysis to suggest optimal TAGs
+
+AGENTS:
+TAG
+ASSESS
+
+LICENSE:
+MIT
+*/
+
+import { readFile } from 'node:fs/promises';
+import { join, extname } from 'node:path';
+import { validateTag, inferTag } from '../../core/tag-validator.js';
+import { parseHeader } from '../../core/header-parser.js';
+
+/**
+ * TagAgent infers and validates LEEWAY TAG values for files.
+ */
+export class TagAgent {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir || process.cwd();
+  }
+
+  /**
+   * Analyze a file and suggest or validate its TAG.
+   *
+   * @param {string} filePath
+   * @returns {Promise<TagAnalysis>}
+   */
+  async analyzeFile(filePath) {
+    const fullPath = filePath.startsWith('/') ? filePath : join(this.rootDir, filePath);
+    const relPath = filePath.startsWith('/') ? filePath.replace(this.rootDir + '/', '') : filePath;
+
+    let content = '';
+    try {
+      content = await readFile(fullPath, 'utf8');
+    } catch {
+      return { file: relPath, status: 'error', reason: 'Cannot read file' };
+    }
+
+    const header = parseHeader(content);
+    const suggestedTag = inferTag(relPath, this._extractContext(content));
+
+    if (!header) {
+      return {
+        file: relPath,
+        status: 'no_header',
+        suggestedTag,
+        currentTag: null,
+      };
+    }
+
+    if (!header.tag) {
+      return {
+        file: relPath,
+        status: 'missing_tag',
+        suggestedTag,
+        currentTag: null,
+      };
+    }
+
+    const { valid, errors } = validateTag(header.tag);
+    return {
+      file: relPath,
+      status: valid ? 'valid' : 'invalid_tag',
+      currentTag: header.tag,
+      suggestedTag: valid ? header.tag : suggestedTag,
+      errors: valid ? [] : errors,
+    };
+  }
+
+  _extractContext(content) {
+    const lines = content.split('\n').slice(0, 30).join(' ');
+    const purposeMatch = lines.match(/(?:export|function|class|const)\s+([A-Za-z][A-Za-z0-9]+)/);
+    return { purpose: purposeMatch ? purposeMatch[1] : 'MAIN' };
+  }
+
+  /**
+   * Analyze multiple files.
+   * @param {string[]} filePaths
+   * @returns {Promise<TagAnalysis[]>}
+   */
+  async analyzeFiles(filePaths) {
+    const results = [];
+    for (const fp of filePaths) {
+      results.push(await this.analyzeFile(fp));
+    }
+    return results;
+  }
+}