@agentlee5/agent-skills 1.0.0

package/LeeWay-Standards/src/agents/mcp/runtime-agent.js

@@ -0,0 +1,108 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: MCP.AGENT.RUNTIME
+TAG: MCP.RUNTIME.AGENT.MAIN
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=zap
+
+5WH:
+WHAT = Runtime agent — checks module and runtime compatibility before build and start
+WHY = Runtime version mismatches cause failures that are difficult to diagnose in CI
+WHO = Rapid Web Development
+WHERE = src/agents/mcp/runtime-agent.js
+WHEN = 2026
+HOW = Reads package.json engines field and compares against current Node version
+
+AGENTS:
+RUNTIME
+ENV
+ALIGN
+
+LICENSE:
+MIT
+*/
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * RuntimeAgent checks module type compatibility and Node.js version requirements.
+ */
+export class RuntimeAgent {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir || process.cwd();
+  }
+
+  /**
+   * Check runtime compatibility for the current project.
+   * @returns {Promise<RuntimeCheckResult>}
+   */
+  async check() {
+    const issues = [];
+    const info = {
+      nodeVersion: process.version,
+      platform: process.platform,
+      arch: process.arch,
+    };
+
+    let pkg = null;
+    try {
+      const raw = await readFile(join(this.rootDir, 'package.json'), 'utf8');
+      pkg = JSON.parse(raw);
+    } catch {
+      issues.push('Cannot read package.json');
+      return { valid: false, issues, info };
+    }
+
+    info.packageName = pkg.name;
+    info.packageVersion = pkg.version;
+    info.moduleType = pkg.type || 'commonjs';
+
+    if (pkg.engines?.node) {
+      const required = pkg.engines.node;
+      const current = process.version.replace('v', '');
+      const compatible = this._semverSatisfies(current, required);
+      if (!compatible) {
+        issues.push(`Node.js ${process.version} does not satisfy required ${required}`);
+      }
+    }
+
+    const moduleIssues = await this._checkModuleConsistency(pkg);
+    issues.push(...moduleIssues);
+
+    return { valid: issues.length === 0, issues, info };
+  }
+
+  async _checkModuleConsistency(pkg) {
+    const issues = [];
+    const declaredType = pkg.type || 'commonjs';
+
+    if (declaredType === 'module') {
+      if (pkg.main && !pkg.main.endsWith('.mjs') && !pkg.main.endsWith('.js')) {
+        issues.push('Package type is "module" but main entry does not use .js or .mjs');
+      }
+    }
+
+    return issues;
+  }
+
+  _semverSatisfies(version, range) {
+    const cleanVersion = version.replace(/[^0-9.]/g, '').split('.').map(Number);
+    const rangeMatch = range.match(/[><=!^~]*([\d.]+)/);
+    if (!rangeMatch) return true;
+
+    const [major, minor = 0] = rangeMatch[1].split('.').map(Number);
+    if (range.startsWith('>=')) return cleanVersion[0] > major || (cleanVersion[0] === major && cleanVersion[1] >= minor);
+    if (range.startsWith('>')) return cleanVersion[0] > major || (cleanVersion[0] === major && cleanVersion[1] > minor);
+    if (range.startsWith('^')) return cleanVersion[0] === major && cleanVersion[1] >= minor;
+    return true;
+  }
+}

package/LeeWay-Standards/src/agents/mcp/transport-agent.js

@@ -0,0 +1,78 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: MCP.AGENT.TRANSPORT
+TAG: MCP.TRANSPORT.AGENT.MAIN
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=activity
+
+5WH:
+WHAT = Transport agent — verifies approved MCP transport usage
+WHY = MCP transport mismatches cause silent failures and security violations
+WHO = Rapid Web Development
+WHERE = src/agents/mcp/transport-agent.js
+WHEN = 2026
+HOW = Checks transport declarations in manifests and source for approved protocols
+
+AGENTS:
+TRANSPORT
+ENDPOINT
+
+LICENSE:
+MIT
+*/
+
+const APPROVED_TRANSPORTS = ['stdio', 'http', 'sse', 'websocket'];
+const DEPRECATED_TRANSPORTS = ['xmlrpc', 'soap', 'raw-tcp'];
+
+/**
+ * TransportAgent verifies that only approved MCP transport protocols are used.
+ */
+export class TransportAgent {
+  constructor(options = {}) {
+    this.approvedTransports = options.approvedTransports || APPROVED_TRANSPORTS;
+  }
+
+  /**
+   * Check if a transport is approved.
+   *
+   * @param {string} transport
+   * @returns {{ approved: boolean, deprecated: boolean, reason: string }}
+   */
+  check(transport) {
+    const t = (transport || '').toLowerCase().trim();
+    if (this.approvedTransports.includes(t)) {
+      return { approved: true, deprecated: false, reason: `Transport "${t}" is approved` };
+    }
+    if (DEPRECATED_TRANSPORTS.includes(t)) {
+      return { approved: false, deprecated: true, reason: `Transport "${t}" is deprecated and not allowed` };
+    }
+    return { approved: false, deprecated: false, reason: `Transport "${t}" is not in the approved list: ${this.approvedTransports.join(', ')}` };
+  }
+
+  /**
+   * Scan manifest object for transport declarations.
+   *
+   * @param {object} manifest
+   * @returns {{ valid: boolean, issues: string[] }}
+   */
+  validateManifest(manifest) {
+    const issues = [];
+    const transports = manifest?.transports || manifest?.transport ? [manifest.transport] : [];
+
+    for (const t of transports) {
+      if (!t) continue;
+      const result = this.check(typeof t === 'string' ? t : t.type);
+      if (!result.approved) issues.push(result.reason);
+    }
+
+    return { valid: issues.length === 0, issues };
+  }
+}

package/LeeWay-Standards/src/agents/orchestration/doctor-agent.js

@@ -0,0 +1,149 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: AI.AGENT.ORCHESTRATION
+TAG: AI.AGENT.DOCTOR.MAIN
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=stethoscope
+
+5WH:
+WHAT = Doctor agent — runs a full system health and compliance diagnosis
+WHY = The entire LEEWAY system must be diagnosable in a single command
+WHO = Rapid Web Development
+WHERE = src/agents/orchestration/doctor-agent.js
+WHEN = 2026
+HOW = Orchestrates assess, audit, runtime, env, and health checks into one unified report
+
+AGENTS:
+DOCTOR
+ASSESS
+AUDIT
+HEALTH
+ENV
+RUNTIME
+
+LICENSE:
+MIT
+*/
+
+import { AssessAgent } from '../governance/assess-agent.js';
+import { AuditAgent } from '../governance/audit-agent.js';
+import { RuntimeAgent } from '../mcp/runtime-agent.js';
+import { EnvAgent } from '../mcp/env-agent.js';
+import { HealthAgentLite } from '../mcp/health-agent-lite.js';
+
+/**
+ * DoctorAgent orchestrates a full system health and compliance diagnosis.
+ */
+export class DoctorAgent {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir || process.cwd();
+    this.options = options;
+  }
+
+  /**
+   * Run a full system diagnosis.
+   * @returns {Promise<DiagnosisReport>}
+   */
+  async run() {
+    const startTime = Date.now();
+    const report = {
+      agent: 'doctor-agent',
+      rootDir: this.rootDir,
+      timestamp: new Date().toISOString(),
+      checks: {},
+      summary: {},
+      healthy: true,
+    };
+
+    const assess = new AssessAgent({ rootDir: this.rootDir });
+    const audit = new AuditAgent({ rootDir: this.rootDir });
+    const runtime = new RuntimeAgent({ rootDir: this.rootDir });
+    const env = new EnvAgent({ rootDir: this.rootDir });
+    const health = HealthAgentLite.withSystemChecks();
+
+    const [assessResult, auditResult, runtimeResult, envResult, healthResult] = await Promise.allSettled([
+      assess.run(),
+      audit.run(),
+      runtime.check(),
+      env.validate(),
+      health.run(),
+    ]);
+
+    report.checks.assessment = assessResult.status === 'fulfilled'
+      ? { status: 'pass', data: assessResult.value.summary }
+      : { status: 'error', error: assessResult.reason?.message };
+
+    report.checks.compliance = auditResult.status === 'fulfilled'
+      ? {
+          status: auditResult.value.summary.averageScore >= 60 ? 'pass' : 'warn',
+          score: auditResult.value.summary.averageScore,
+          level: auditResult.value.summary.complianceLevel,
+        }
+      : { status: 'error', error: auditResult.reason?.message };
+
+    report.checks.runtime = runtimeResult.status === 'fulfilled'
+      ? { status: runtimeResult.value.valid ? 'pass' : 'fail', issues: runtimeResult.value.issues }
+      : { status: 'error', error: runtimeResult.reason?.message };
+
+    report.checks.environment = envResult.status === 'fulfilled'
+      ? { status: envResult.value.valid ? 'pass' : 'warn', missing: envResult.value.missing }
+      : { status: 'error', error: envResult.reason?.message };
+
+    report.checks.system = healthResult.status === 'fulfilled'
+      ? { status: healthResult.value.healthy ? 'pass' : 'fail', summary: healthResult.value.summary }
+      : { status: 'error', error: healthResult.reason?.message };
+
+    const statuses = Object.values(report.checks).map(c => c.status);
+    report.healthy = !statuses.includes('fail') && !statuses.includes('error');
+    report.durationMs = Date.now() - startTime;
+
+    const passCount = statuses.filter(s => s === 'pass').length;
+    report.summary = {
+      totalChecks: statuses.length,
+      passed: passCount,
+      warnings: statuses.filter(s => s === 'warn').length,
+      failed: statuses.filter(s => s === 'fail' || s === 'error').length,
+      status: report.healthy ? '✅ HEALTHY' : '⚠️  NEEDS ATTENTION',
+    };
+
+    return report;
+  }
+
+  /**
+   * Format a diagnosis report as human-readable text.
+   *
+   * @param {object} report
+   * @returns {string}
+   */
+  formatReport(report) {
+    const lines = [
+      '═══════════════════════════════════════════════',
+      '          LEEWAY™ SYSTEM DOCTOR REPORT         ',
+      '═══════════════════════════════════════════════',
+      `Status    : ${report.summary.status}`,
+      `Timestamp : ${report.timestamp}`,
+      `Duration  : ${report.durationMs}ms`,
+      '',
+      '── CHECKS ──────────────────────────────────────',
+    ];
+
+    for (const [name, check] of Object.entries(report.checks)) {
+      const icon = check.status === 'pass' ? '✅' : check.status === 'warn' ? '⚠️ ' : '❌';
+      lines.push(`${icon} ${name.padEnd(15)} [${check.status.toUpperCase()}]`);
+      if (check.issues?.length) lines.push(`   Issues: ${check.issues.slice(0, 2).join(', ')}`);
+      if (check.missing?.length) lines.push(`   Missing env: ${check.missing.join(', ')}`);
+      if (check.score !== undefined) lines.push(`   Score: ${check.score}/100 (${check.level})`);
+    }
+
+    lines.push('═══════════════════════════════════════════════');
+    return lines.join('\n');
+  }
+}

package/LeeWay-Standards/src/agents/orchestration/memory-agent-lite.js

@@ -0,0 +1,125 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: AI.AGENT.ORCHESTRATION
+TAG: AI.AGENT.MEMORY.LITE
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=hard-drive
+
+5WH:
+WHAT = Memory agent lite — stores SDK-local state, receipts, audit history, and registries
+WHY = Agent operations must be logged and recoverable; receipts provide auditability
+WHO = Rapid Web Development
+WHERE = src/agents/orchestration/memory-agent-lite.js
+WHEN = 2026
+HOW = Persistent JSON store in .leeway/memory.json with receipt logging
+
+AGENTS:
+MEMORY
+ROUTER
+DOCTOR
+
+LICENSE:
+MIT
+*/
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * MemoryAgentLite provides lightweight persistent state management for the LEEWAY SDK.
+ */
+export class MemoryAgentLite {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir || process.cwd();
+    this.storePath = join(this.rootDir, '.leeway', 'memory.json');
+    this.maxReceipts = options.maxReceipts || 1000;
+    this.state = null;
+  }
+
+  async _load() {
+    if (this.state) return this.state;
+    try {
+      const raw = await readFile(this.storePath, 'utf8');
+      this.state = JSON.parse(raw);
+    } catch {
+      this.state = { receipts: [], kv: {}, lastUpdated: null };
+    }
+    return this.state;
+  }
+
+  async _save() {
+    await mkdir(join(this.rootDir, '.leeway'), { recursive: true });
+    this.state.lastUpdated = new Date().toISOString();
+    await writeFile(this.storePath, JSON.stringify(this.state, null, 2), 'utf8');
+  }
+
+  /**
+   * Store a key-value pair in persistent memory.
+   *
+   * @param {string} key
+   * @param {*} value
+   */
+  async set(key, value) {
+    const state = await this._load();
+    state.kv[key] = value;
+    await this._save();
+  }
+
+  /**
+   * Retrieve a value from persistent memory.
+   *
+   * @param {string} key
+   * @param {*} [defaultValue]
+   * @returns {Promise<*>}
+   */
+  async get(key, defaultValue = null) {
+    const state = await this._load();
+    return key in state.kv ? state.kv[key] : defaultValue;
+  }
+
+  /**
+   * Log an operation receipt for audit purposes.
+   *
+   * @param {{ agent: string, action: string, target?: string, result?: string }} receipt
+   */
+  async logReceipt(receipt) {
+    const state = await this._load();
+    state.receipts.unshift({
+      ...receipt,
+      timestamp: new Date().toISOString(),
+    });
+
+    if (state.receipts.length > this.maxReceipts) {
+      state.receipts = state.receipts.slice(0, this.maxReceipts);
+    }
+
+    await this._save();
+  }
+
+  /**
+   * Get recent receipts.
+   *
+   * @param {number} [limit]
+   * @returns {Promise<object[]>}
+   */
+  async getReceipts(limit = 50) {
+    const state = await this._load();
+    return state.receipts.slice(0, limit);
+  }
+
+  /**
+   * Clear all stored state.
+   */
+  async clear() {
+    this.state = { receipts: [], kv: {}, lastUpdated: null };
+    await this._save();
+  }
+}

package/LeeWay-Standards/src/agents/orchestration/router-agent.js

@@ -0,0 +1,110 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: AI.AGENT.ORCHESTRATION
+TAG: AI.AGENT.ROUTER.MAIN
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=git-fork
+
+5WH:
+WHAT = Router agent — chooses which other agents to invoke for a given task
+WHY = Complex governance tasks require orchestrated invocation of multiple specialized agents
+WHO = Rapid Web Development
+WHERE = src/agents/orchestration/router-agent.js
+WHEN = 2026
+HOW = Intent-based routing from task descriptions to named agent handlers
+
+AGENTS:
+ROUTER
+ASSESS
+AUDIT
+DOCTOR
+
+LICENSE:
+MIT
+*/
+
+/**
+ * RouterAgent routes tasks to the appropriate LEEWAY agents.
+ */
+export class RouterAgent {
+  constructor(options = {}) {
+    this.routes = new Map();
+    this.fallback = options.fallback || null;
+  }
+
+  /**
+   * Register a route mapping an intent pattern to an agent handler.
+   *
+   * @param {string | RegExp} intentPattern
+   * @param {{ agent: string, handler: Function }} route
+   */
+  register(intentPattern, route) {
+    this.routes.set(intentPattern, route);
+  }
+
+  /**
+   * Route a task to the appropriate agent.
+   *
+   * @param {string} task - Natural language task description
+   * @param {object} [context] - Additional context
+   * @returns {Promise<RouterResult>}
+   */
+  async route(task, context = {}) {
+    const taskLower = task.toLowerCase();
+
+    for (const [pattern, route] of this.routes.entries()) {
+      const matches = pattern instanceof RegExp
+        ? pattern.test(task)
+        : taskLower.includes(pattern.toLowerCase());
+
+      if (matches) {
+        try {
+          const result = await route.handler(context);
+          return { routed: true, agent: route.agent, result };
+        } catch (err) {
+          return { routed: true, agent: route.agent, error: err.message };
+        }
+      }
+    }
+
+    if (this.fallback) {
+      const result = await this.fallback(task, context);
+      return { routed: true, agent: 'fallback', result };
+    }
+
+    return { routed: false, reason: `No route matched for task: "${task}"` };
+  }
+
+  /**
+   * Create a router with standard LEEWAY governance routes.
+   *
+   * @param {object} agents - Map of agent instances
+   * @returns {RouterAgent}
+   */
+  static withStandardRoutes(agents) {
+    const router = new RouterAgent();
+
+    if (agents.assess) {
+      router.register('assess', { agent: 'assess-agent', handler: () => agents.assess.run() });
+      router.register('survey', { agent: 'assess-agent', handler: () => agents.assess.run() });
+    }
+    if (agents.audit) {
+      router.register('audit', { agent: 'audit-agent', handler: () => agents.audit.run() });
+      router.register('compliance', { agent: 'audit-agent', handler: () => agents.audit.run() });
+    }
+    if (agents.doctor) {
+      router.register('doctor', { agent: 'doctor-agent', handler: () => agents.doctor.run() });
+      router.register('diagnose', { agent: 'doctor-agent', handler: () => agents.doctor.run() });
+    }
+
+    return router;
+  }
+}

package/LeeWay-Standards/src/agents/security/permission-agent.js

@@ -0,0 +1,98 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: SECURITY.AGENT.PERMISSION
+TAG: SECURITY.PERMISSION.AGENT.MAIN
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=lock
+
+5WH:
+WHAT = Permission agent — checks action permissions and runtime boundaries
+WHY = Actions must be gated by explicit permission checks to prevent unauthorized operations
+WHO = Rapid Web Development
+WHERE = src/agents/security/permission-agent.js
+WHEN = 2026
+HOW = Checks declared AGENTS list in headers and validates against permission rules
+
+AGENTS:
+PERMISSION
+POLICY
+AUTHORITY
+
+LICENSE:
+MIT
+*/
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseHeader } from '../../core/header-parser.js';
+
+/**
+ * PermissionAgent checks what agents are allowed to act on a file.
+ */
+export class PermissionAgent {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir || process.cwd();
+  }
+
+  /**
+   * Check if a specific agent is authorized to act on a file.
+   *
+   * @param {string} filePath
+   * @param {string} agentName
+   * @returns {Promise<{ allowed: boolean, reason: string }>}
+   */
+  async checkAccess(filePath, agentName) {
+    const fullPath = filePath.startsWith('/') ? filePath : join(this.rootDir, filePath);
+    let content = '';
+    try {
+      content = await readFile(fullPath, 'utf8');
+    } catch {
+      return { allowed: false, reason: 'Cannot read file' };
+    }
+
+    const header = parseHeader(content);
+    if (!header) {
+      return { allowed: false, reason: 'No LEEWAY header — file governance not established' };
+    }
+
+    const allowedAgents = header.agents || [];
+    if (allowedAgents.length === 0) {
+      return { allowed: true, reason: 'No agent restrictions declared — open access' };
+    }
+
+    const agentUpper = agentName.toUpperCase();
+    const isAllowed = allowedAgents.some(a => a.toUpperCase() === agentUpper || a === '*');
+
+    return {
+      allowed: isAllowed,
+      reason: isAllowed
+        ? `Agent "${agentName}" is listed in file AGENTS declaration`
+        : `Agent "${agentName}" is NOT in allowed agents: [${allowedAgents.join(', ')}]`,
+    };
+  }
+
+  /**
+   * Get all agents authorized for a file.
+   *
+   * @param {string} filePath
+   * @returns {Promise<string[]>}
+   */
+  async getAuthorizedAgents(filePath) {
+    const fullPath = filePath.startsWith('/') ? filePath : join(this.rootDir, filePath);
+    try {
+      const content = await readFile(fullPath, 'utf8');
+      const header = parseHeader(content);
+      return header?.agents || [];
+    } catch {
+      return [];
+    }
+  }
+}