@agentlee5/agent-skills 1.0.0

package/LeeWay-Standards/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "leeway-sdk",
+  "version": "1.0.1",
+  "description": "LEEWAY™ — Logically Enhanced Engineering Web Architecture Yield. A lightweight autonomous code governance SDK that embeds identity, safety, readability, and repair assistance directly into the developer workflow.",
+  "main": "src/index.js",
+  "type": "module",
+  "bin": {
+    "leeway": "src/cli/leeway.js"
+  },
+  "scripts": {
+    "start": "node src/cli/leeway.js",
+    "doctor": "node src/cli/leeway.js doctor",
+    "audit": "node src/cli/leeway.js audit",
+    "assess": "node src/cli/leeway.js assess",
+    "test": "node --test \"src/**/*.test.js\""
+  },
+  "keywords": [
+    "leeway",
+    "governance",
+    "ai-native",
+    "mcp",
+    "agents",
+    "llm",
+    "code-standards",
+    "sdk",
+    "autonomous",
+    "architecture"
+  ],
+  "author": "Rapid Web Development",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/4citeB4U/LeeWay-Standards.git"
+  },
+  "bugs": {
+    "url": "https://github.com/4citeB4U/LeeWay-Standards/issues"
+  },
+  "homepage": "https://github.com/4citeB4U/LeeWay-Standards#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src/",
+    "schemas/",
+    ".leeway/",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "exports": {
+    ".": "./src/index.js",
+    "./agents/*": "./src/agents/*",
+    "./core/*": "./src/core/*"
+  },
+  "dependencies": {
+    "leeway-sdk": "^1.0.1"
+  }
+}

package/LeeWay-Standards/schemas/leeway-config.schema.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://leeway-standards.dev/schemas/leeway-config.schema.json",
+  "title": "LEEWAY SDK Configuration Schema",
+  "description": "Validates the .leeway/config.json project configuration file",
+  "type": "object",
+  "properties": {
+    "version": {
+      "type": "string",
+      "description": "LEEWAY standard version this project targets",
+      "default": "1.0.0"
+    },
+    "project": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string" },
+        "author": { "type": "string" },
+        "license": { "type": "string", "default": "MIT" }
+      }
+    },
+    "rootDir": {
+      "type": "string",
+      "description": "Root directory for LEEWAY governance (relative to config file)",
+      "default": "src"
+    },
+    "agents": {
+      "type": "object",
+      "description": "Agent-specific configuration overrides",
+      "properties": {
+        "assess": { "type": "object" },
+        "align": { "type": "object", "properties": { "dryRun": { "type": "boolean", "default": true } } },
+        "audit": { "type": "object", "properties": { "outputDir": { "type": "string", "default": "reports" } } },
+        "secret-scan": { "type": "object" },
+        "health": { "type": "object", "properties": { "timeout": { "type": "number", "default": 5000 } } }
+      }
+    },
+    "policies": {
+      "type": "object",
+      "description": "Policy enforcement overrides",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "enforced": { "type": "boolean" },
+          "description": { "type": "string" }
+        }
+      }
+    },
+    "compliance": {
+      "type": "object",
+      "properties": {
+        "minimumScore": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 100,
+          "default": 60,
+          "description": "Minimum average compliance score to pass audit"
+        },
+        "blockOnFail": {
+          "type": "boolean",
+          "default": false,
+          "description": "Exit with error code if compliance is below minimum"
+        }
+      }
+    },
+    "discovery": {
+      "type": "object",
+      "properties": {
+        "baseUrl": { "type": "string", "format": "uri" },
+        "generateSitemap": { "type": "boolean", "default": false },
+        "generateSchema": { "type": "boolean", "default": false }
+      }
+    },
+    "ignore": {
+      "type": "array",
+      "description": "Glob patterns to ignore during governance scans",
+      "items": { "type": "string" },
+      "default": ["node_modules/**", "dist/**", "build/**", ".next/**", "coverage/**"]
+    }
+  }
+}

package/LeeWay-Standards/schemas/leeway-header.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://leeway-standards.dev/schemas/leeway-header.schema.json",
+  "title": "LEEWAY Header Schema",
+  "description": "Validates the LEEWAY identity header structure embedded in source files",
+  "type": "object",
+  "required": ["region", "tag", "fiveWH", "license"],
+  "properties": {
+    "region": {
+      "type": "string",
+      "description": "System region in dot-notation: DOMAIN.SUBDOMAIN.CONTEXT",
+      "pattern": "^[A-Z][A-Z0-9]*(\\.[A-Z][A-Z0-9]*)*$",
+      "examples": ["UI.APP.SURFACE", "CORE.SDK.ENTRY", "AI.AGENT.GOVERNANCE"]
+    },
+    "tag": {
+      "type": "string",
+      "description": "Discoverable tag in DOMAIN.SUBDOMAIN.ASSET.PURPOSE format",
+      "pattern": "^[A-Z][A-Z0-9]*(\\.[A-Z][A-Z0-9]*){2,}$",
+      "examples": ["UI.COMPONENT.NEXUS.BUTTON", "AI.AGENT.ASSESS.MAIN"]
+    },
+    "colorOnionHex": {
+      "type": "object",
+      "description": "Color classification for system layer visualization",
+      "properties": {
+        "NEON": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" },
+        "FLUO": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" },
+        "PASTEL": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }
+      }
+    },
+    "iconAscii": {
+      "type": "object",
+      "description": "Icon reference for IDE and tooling visualization",
+      "properties": {
+        "family": { "type": "string", "enum": ["lucide", "heroicons", "material", "custom"] },
+        "glyph": { "type": "string" }
+      }
+    },
+    "fiveWH": {
+      "type": "object",
+      "description": "The 5WH identity block — answers fundamental questions about the file",
+      "required": ["WHAT", "WHY", "WHO", "WHERE", "WHEN", "HOW"],
+      "properties": {
+        "WHAT": { "type": "string", "description": "What does this file do?" },
+        "WHY": { "type": "string", "description": "Why does this file exist?" },
+        "WHO": { "type": "string", "description": "Who created or owns this file?" },
+        "WHERE": { "type": "string", "description": "Where does this file live in the system?" },
+        "WHEN": { "type": "string", "description": "When was this file created or last reviewed?" },
+        "HOW": { "type": "string", "description": "How does this file operate?" }
+      }
+    },
+    "agents": {
+      "type": "array",
+      "description": "List of LEEWAY agents authorized to act on this file",
+      "items": { "type": "string" },
+      "examples": [["ASSESS", "ALIGN", "AUDIT"]]
+    },
+    "license": {
+      "type": "string",
+      "description": "License identifier for this file",
+      "examples": ["MIT", "Apache-2.0", "GPL-3.0", "PROPRIETARY"]
+    }
+  }
+}

package/LeeWay-Standards/src/agents/discovery/architecture-map-agent.js

@@ -0,0 +1,134 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: DOCS.AGENT.ARCHITECTURE
+TAG: DOCS.STANDARD.ARCHITECTURE.MAP
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=network
+
+5WH:
+WHAT = Architecture map agent — produces a visual or JSON architecture map of the codebase
+WHY = Understanding system architecture is essential for safe evolution and AI-assisted development
+WHO = Rapid Web Development
+WHERE = src/agents/discovery/architecture-map-agent.js
+WHEN = 2026
+HOW = Reads LEEWAY registry and builds a layered region/module graph in JSON and ASCII
+
+AGENTS:
+ARCHITECTURE
+DOCS
+REGISTRY
+
+LICENSE:
+MIT
+*/
+
+import { readdir, readFile } 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', 'coverage', '.leeway']);
+const CODE_EXTENSIONS = new Set(['.js', '.ts', '.jsx', '.tsx', '.mjs', '.cjs']);
+
+/**
+ * ArchitectureMapAgent builds a structured architecture map from LEEWAY headers.
+ */
+export class ArchitectureMapAgent {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir || process.cwd();
+  }
+
+  /**
+   * Build a JSON architecture map.
+   * @returns {Promise<ArchitectureMap>}
+   */
+  async buildMap() {
+    const map = {
+      agent: 'architecture-map-agent',
+      generated: new Date().toISOString(),
+      regions: {},
+      modules: {},
+      edges: [],
+    };
+
+    await this._walk(this.rootDir, map);
+    return map;
+  }
+
+  /**
+   * Build an ASCII text architecture diagram.
+   * @returns {Promise<string>}
+   */
+  async buildAsciiDiagram() {
+    const map = await this.buildMap();
+    const lines = [
+      '╔════════════════════════════════════════╗',
+      '║      LEEWAY™ ARCHITECTURE MAP          ║',
+      '╚════════════════════════════════════════╝',
+      '',
+    ];
+
+    for (const [region, data] of Object.entries(map.regions)) {
+      lines.push(`┌─ ${region} (${data.color}) `);
+      for (const mod of data.modules) {
+        lines.push(`│  ├─ [${mod.tag || 'NO TAG'}] ${mod.path}`);
+        lines.push(`│  │   └─ ${mod.what || 'No description'}`);
+      }
+      lines.push('│');
+    }
+
+    return lines.join('\n');
+  }
+
+  async _walk(dir, map, depth = 0) {
+    if (depth > 8) 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._walk(fullPath, map, depth + 1);
+      } else if (CODE_EXTENSIONS.has(extname(entry.name))) {
+        const relPath = relative(this.rootDir, fullPath);
+        try {
+          const content = await readFile(fullPath, 'utf8');
+          const header = parseHeader(content);
+          if (header) {
+            const regionKey = header.region?.split('.')?.[0] || 'UNKNOWN';
+            if (!map.regions[regionKey]) {
+              map.regions[regionKey] = { modules: [], color: this._regionColor(regionKey) };
+            }
+            map.regions[regionKey].modules.push({
+              path: relPath,
+              tag: header.tag,
+              what: header.fiveWH?.WHAT,
+              agents: header.agents,
+            });
+            map.modules[relPath] = { region: regionKey, tag: header.tag };
+          }
+        } catch {
+          continue;
+        }
+      }
+    }
+  }
+
+  _regionColor(region) {
+    const colors = { UI: '#39FF14', CORE: '#FF6B35', DATA: '#4ECDC4', AI: '#A855F7', SEO: '#F59E0B', UTIL: '#6B7280', MCP: '#0EA5E9', SECURITY: '#EF4444' };
+    return colors[region] || '#888888';
+  }
+}

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

@@ -0,0 +1,126 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: DOCS.AGENT.GENERATOR
+TAG: DOCS.STANDARD.DOCS.AGENT
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=book-open
+
+5WH:
+WHAT = Docs agent — generates structured plain-English docs from LEEWAY headers and registries
+WHY = Human-readable documentation must be automatically derivable from code headers
+WHO = Rapid Web Development
+WHERE = src/agents/discovery/docs-agent.js
+WHEN = 2026
+HOW = Reads LEEWAY headers and produces Markdown documentation summaries
+
+AGENTS:
+DOCS
+EXPLAIN
+REGISTRY
+
+LICENSE:
+MIT
+*/
+
+import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join, relative, extname, dirname } from 'node:path';
+import { parseHeader } from '../../core/header-parser.js';
+
+const SKIP_DIRS = new Set(['.git', 'node_modules', 'dist', 'build', '.next', 'coverage', '.leeway']);
+const CODE_EXTENSIONS = new Set(['.js', '.ts', '.jsx', '.tsx', '.mjs', '.cjs']);
+
+/**
+ * DocsAgent generates Markdown documentation from LEEWAY headers.
+ */
+export class DocsAgent {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir || process.cwd();
+    this.outputPath = options.outputPath || join(this.rootDir, 'docs', 'AUTO-GENERATED.md');
+  }
+
+  /**
+   * Generate documentation for the entire codebase.
+   * @returns {Promise<string>} - Markdown string
+   */
+  async generate() {
+    const docs = [];
+    docs.push('# LEEWAY Codebase Documentation\n');
+    docs.push(`> Auto-generated by LEEWAY docs-agent on ${new Date().toISOString()}\n`);
+    docs.push('---\n');
+
+    const sections = new Map();
+    await this._walk(this.rootDir, sections);
+
+    for (const [region, files] of [...sections.entries()].sort()) {
+      docs.push(`## ${region}\n`);
+      for (const file of files) {
+        docs.push(this._formatFileDoc(file));
+      }
+    }
+
+    return docs.join('\n');
+  }
+
+  /**
+   * Generate and save documentation to disk.
+   * @returns {Promise<string>} - Path to saved file
+   */
+  async generateAndSave() {
+    const content = await this.generate();
+    await mkdir(dirname(this.outputPath), { recursive: true });
+    await writeFile(this.outputPath, content, 'utf8');
+    return this.outputPath;
+  }
+
+  async _walk(dir, sections, depth = 0) {
+    if (depth > 8) 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._walk(fullPath, sections, depth + 1);
+      } else if (CODE_EXTENSIONS.has(extname(entry.name))) {
+        const relPath = relative(this.rootDir, fullPath);
+        try {
+          const content = await readFile(fullPath, 'utf8');
+          const header = parseHeader(content);
+          if (header) {
+            const region = header.region?.split('.')?.[0] || 'UNKNOWN';
+            if (!sections.has(region)) sections.set(region, []);
+            sections.get(region).push({ path: relPath, header });
+          }
+        } catch {
+          continue;
+        }
+      }
+    }
+  }
+
+  _formatFileDoc({ path, header }) {
+    const wh = header.fiveWH || {};
+    return `### \`${path}\`
+- **TAG**: \`${header.tag || 'N/A'}\`
+- **WHAT**: ${wh.WHAT || 'N/A'}
+- **WHY**: ${wh.WHY || 'N/A'}
+- **HOW**: ${wh.HOW || 'N/A'}
+- **Agents**: ${(header.agents || []).join(', ') || 'None declared'}
+
+`;
+  }
+}

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

@@ -0,0 +1,95 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: DOCS.AGENT.EXPLAIN
+TAG: DOCS.STANDARD.EXPLAIN.MAIN
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=message-circle
+
+5WH:
+WHAT = Explain agent — explains a file, module, or service in plain English
+WHY = Any file in a LEEWAY system must be self-explainable to any developer or AI tool
+WHO = Rapid Web Development
+WHERE = src/agents/discovery/explain-agent.js
+WHEN = 2026
+HOW = Reads LEEWAY headers and produces structured human-readable explanations
+
+AGENTS:
+EXPLAIN
+DOCS
+ASSESS
+
+LICENSE:
+MIT
+*/
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseHeader } from '../../core/header-parser.js';
+import { classifyRegion } from '../../core/region-classifier.js';
+
+/**
+ * ExplainAgent produces human-readable explanations of LEEWAY files and modules.
+ */
+export class ExplainAgent {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir || process.cwd();
+  }
+
+  /**
+   * Explain a file in plain English.
+   *
+   * @param {string} filePath
+   * @returns {Promise<Explanation>}
+   */
+  async explain(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, explanation: 'File could not be read.', hasHeader: false };
+    }
+
+    const header = parseHeader(content);
+    if (!header) {
+      const { region, metadata } = classifyRegion(relPath);
+      return {
+        file: relPath,
+        hasHeader: false,
+        explanation: `This file does not have a LEEWAY header. Based on its path, it appears to be a ${metadata.label} (${region}) module. It has not been documented according to LEEWAY standards.`,
+        region,
+      };
+    }
+
+    const wh = header.fiveWH || {};
+    const parts = [
+      `This file is "${relPath}".`,
+      wh.WHAT ? `It is: ${wh.WHAT}.` : null,
+      wh.WHY ? `It exists because: ${wh.WHY}.` : null,
+      header.region ? `It belongs to the ${header.region} system region.` : null,
+      header.tag ? `Its discovery tag is ${header.tag}.` : null,
+      wh.HOW ? `It operates via: ${wh.HOW}.` : null,
+      wh.WHO ? `It was created by: ${wh.WHO}.` : null,
+      header.agents?.length ? `It is managed by these agents: ${header.agents.join(', ')}.` : null,
+    ].filter(Boolean);
+
+    return {
+      file: relPath,
+      hasHeader: true,
+      region: header.region,
+      tag: header.tag,
+      explanation: parts.join(' '),
+      fiveWH: wh,
+    };
+  }
+}

package/LeeWay-Standards/src/agents/discovery/intent-registry-agent.js

@@ -0,0 +1,119 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: SEO.AGENT.INTENT
+TAG: SEO.INTENT.REGISTRY.MAIN
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=list-tree
+
+5WH:
+WHAT = Intent registry agent — tracks supported intents and their routes
+WHY = AI agents and voice assistants need a machine-readable registry of supported intents
+WHO = Rapid Web Development
+WHERE = src/agents/discovery/intent-registry-agent.js
+WHEN = 2026
+HOW = Maintains a registry of intent-to-handler mappings in .leeway/intents.json
+
+AGENTS:
+INTENT
+SCHEMA
+REGISTRY
+
+LICENSE:
+MIT
+*/
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * IntentRegistryAgent tracks supported intents and routes.
+ */
+export class IntentRegistryAgent {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir || process.cwd();
+    this.registryPath = join(this.rootDir, '.leeway', 'intents.json');
+    this.intents = new Map();
+  }
+
+  /**
+   * Register an intent.
+   *
+   * @param {string} intentName
+   * @param {{ handler: string, description: string, examples?: string[], parameters?: object }} config
+   */
+  register(intentName, config) {
+    this.intents.set(intentName.toLowerCase(), {
+      name: intentName,
+      handler: config.handler,
+      description: config.description,
+      examples: config.examples || [],
+      parameters: config.parameters || {},
+      registered: new Date().toISOString(),
+    });
+  }
+
+  /**
+   * Resolve an intent by name.
+   *
+   * @param {string} intentName
+   * @returns {object | null}
+   */
+  resolve(intentName) {
+    return this.intents.get(intentName.toLowerCase()) || null;
+  }
+
+  /**
+   * Persist the intent registry.
+   */
+  async save() {
+    await mkdir(join(this.rootDir, '.leeway'), { recursive: true });
+    const data = {
+      version: '1.0',
+      updated: new Date().toISOString(),
+      intents: Object.fromEntries(this.intents),
+    };
+    await writeFile(this.registryPath, JSON.stringify(data, null, 2), 'utf8');
+  }
+
+  /**
+   * Load intents from disk.
+   */
+  async load() {
+    try {
+      const raw = await readFile(this.registryPath, 'utf8');
+      const data = JSON.parse(raw);
+      for (const [key, val] of Object.entries(data.intents || {})) {
+        this.intents.set(key, val);
+      }
+    } catch {
+      // No registry yet
+    }
+  }
+
+  /**
+   * Export as a machine-readable discovery manifest.
+   * @returns {object}
+   */
+  toDiscoveryManifest() {
+    return {
+      '@context': 'https://schema.org',
+      '@type': 'DataCatalog',
+      name: 'LEEWAY Intent Registry',
+      description: 'Machine-readable registry of supported intents and their handlers',
+      dataset: Array.from(this.intents.values()).map(intent => ({
+        '@type': 'Dataset',
+        name: intent.name,
+        description: intent.description,
+        keywords: intent.examples,
+      })),
+    };
+  }
+}