@aimlsuperagent/agent 0.1.0

package/bin/aiml-superagent.js

@@ -0,0 +1,477 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+const REQUIRED_FILES = [
+  "AGENTS.md",
+  "REPO_SOURCE_OF_TRUTH.json",
+  "WORKING_NOTES.md"
+];
+
+const RECOMMENDED_FILES = [
+  "DEPLOYMENT_LOG.md",
+  "SAFE_ENV_AUDIT.md"
+];
+
+const TEMPLATE_MAP = new Map([
+  ["AGENTS.template.md", "AGENTS.md"],
+  ["REPO_SOURCE_OF_TRUTH.template.json", "REPO_SOURCE_OF_TRUTH.json"],
+  ["WORKING_NOTES.template.md", "WORKING_NOTES.md"],
+  ["DEPLOYMENT_LOG.template.md", "DEPLOYMENT_LOG.md"],
+  ["INCIDENT_REPORT.template.md", "INCIDENT_REPORT.md"],
+  ["SAFE_ENV_AUDIT.template.md", "SAFE_ENV_AUDIT.md"],
+  ["PRODUCTION_CHECK.template.md", "PRODUCTION_CHECK.md"],
+  ["TASK_BRIEF.template.md", "TASK_BRIEF.md"]
+]);
+
+const SECRET_PATTERNS = [
+  {
+    name: "private-key-block",
+    pattern: /-----BEGIN (RSA |EC |OPENSSH |DSA |PRIVATE )?PRIVATE KEY-----/
+  },
+  {
+    name: "assignment-with-sensitive-name",
+    pattern: /\b(api[_-]?key|secret|token|password|passwd|auth[_-]?token|private[_-]?key)\b\s*[:=]\s*["']?[A-Za-z0-9_./+=-]{16,}/i
+  },
+  {
+    name: "database-url-with-credentials",
+    pattern: /\b(postgres|postgresql|mysql|mongodb):\/\/[^:\s]+:[^@\s]+@/i
+  }
+];
+
+const PLACEHOLDER_PATTERNS = [
+  {
+    name: "project-name-placeholder",
+    pattern: /\bPROJECT_NAME\b/
+  },
+  {
+    name: "command-placeholder",
+    pattern: /\b(REPLACE_WITH_COMMAND|COMMANDS_HERE)\b/
+  },
+  {
+    name: "date-placeholder",
+    pattern: /\bYYYY-MM-DD\b/
+  },
+  {
+    name: "generic-template-instruction",
+    pattern: /Describe the project in one paragraph|One sentence describing what this project does|One sentence\./
+  }
+];
+
+const CONTEXT_SIZE_LIMITS = [
+  {
+    file: "WORKING_NOTES.md",
+    maxBytes: 80 * 1024,
+    severity: "medium",
+    message: "WORKING_NOTES.md is large enough to risk context bloat. Archive or compress resolved material."
+  },
+  {
+    file: "AGENTS.md",
+    maxBytes: 40 * 1024,
+    severity: "medium",
+    message: "AGENTS.md is large enough to weaken instruction focus. Move project history into notes."
+  }
+];
+
+function usage() {
+  console.log(`AiML SuperAgent
+
+Usage:
+  aiml-superagent init [target-dir]
+  aiml-superagent check [target-dir] [--json] [--release] [--strict]
+
+Examples:
+  node bin/aiml-superagent.js init ../my-app
+  node bin/aiml-superagent.js check ../my-app
+  node bin/aiml-superagent.js check ../my-app --release
+  node bin/aiml-superagent.js check ../my-app --strict
+`);
+}
+
+function repoRootFromScript() {
+  return path.resolve(path.dirname(new URL(import.meta.url).pathname), "..");
+}
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function copyTemplates(targetDir) {
+  const root = repoRootFromScript();
+  const templateDir = path.join(root, "templates");
+  const actions = [];
+
+  ensureDir(targetDir);
+
+  for (const [templateName, outputName] of TEMPLATE_MAP.entries()) {
+    const source = path.join(templateDir, templateName);
+    const target = path.join(targetDir, outputName);
+
+    if (!fs.existsSync(source)) {
+      actions.push({ type: "missing-template", file: templateName });
+      continue;
+    }
+
+    if (fs.existsSync(target)) {
+      actions.push({ type: "skipped-existing", file: outputName });
+      continue;
+    }
+
+    fs.copyFileSync(source, target);
+    actions.push({ type: "created", file: outputName });
+  }
+
+  return actions;
+}
+
+function isIgnoredForPlaceholderScan(relPath) {
+  return (
+    relPath === "bin/aiml-superagent.js" ||
+    relPath.startsWith("templates/") ||
+    relPath.startsWith("schemas/")
+  );
+}
+
+function listTextFiles(rootDir) {
+  const skip = new Set([".git", "node_modules", ".next", "dist", "build", "coverage"]);
+  const files = [];
+
+  function walk(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (skip.has(entry.name)) continue;
+      const fullPath = path.join(dir, entry.name);
+      const relPath = path.relative(rootDir, fullPath);
+
+      if (entry.isDirectory()) {
+        walk(fullPath);
+        continue;
+      }
+
+      if (entry.isFile() && /\.(md|json|js|ts|tsx|yml|yaml|env|txt)$/i.test(entry.name)) {
+        files.push(relPath);
+      }
+    }
+  }
+
+  walk(rootDir);
+  return files;
+}
+
+function scanForSecrets(rootDir) {
+  const findings = [];
+  for (const relPath of listTextFiles(rootDir)) {
+    const fullPath = path.join(rootDir, relPath);
+    const content = fs.readFileSync(fullPath, "utf8");
+
+    for (const rule of SECRET_PATTERNS) {
+      if (rule.pattern.test(content)) {
+        findings.push({
+          severity: "high",
+          rule: rule.name,
+          file: relPath,
+          message: "Possible secret value found. Store names and roles only, never credential values."
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+function scanForPlaceholders(rootDir) {
+  const findings = [];
+  for (const relPath of listTextFiles(rootDir)) {
+    if (isIgnoredForPlaceholderScan(relPath)) continue;
+
+    const fullPath = path.join(rootDir, relPath);
+    const content = fs.readFileSync(fullPath, "utf8");
+
+    for (const rule of PLACEHOLDER_PATTERNS) {
+      if (rule.pattern.test(content)) {
+        findings.push({
+          severity: "medium",
+          rule: rule.name,
+          file: relPath,
+          message: "Template placeholder appears to be unresolved."
+        });
+        break;
+      }
+    }
+  }
+
+  return findings;
+}
+
+function validateContextSize(rootDir) {
+  const findings = [];
+
+  for (const rule of CONTEXT_SIZE_LIMITS) {
+    const file = path.join(rootDir, rule.file);
+    if (!fs.existsSync(file)) continue;
+
+    const size = fs.statSync(file).size;
+    if (size > rule.maxBytes) {
+      findings.push({
+        severity: rule.severity,
+        file: rule.file,
+        message: `${rule.message} Current size: ${size} bytes.`
+      });
+    }
+  }
+
+  return findings;
+}
+
+function validateRelativePath(rootDir, relPath) {
+  if (typeof relPath !== "string" || relPath.trim() === "") return false;
+  if (/^https?:\/\//i.test(relPath)) return true;
+  return fs.existsSync(path.join(rootDir, relPath));
+}
+
+function validateSourceOfTruth(rootDir) {
+  const findings = [];
+  const file = path.join(rootDir, "REPO_SOURCE_OF_TRUTH.json");
+
+  if (!fs.existsSync(file)) {
+    findings.push({
+      severity: "high",
+      file: "REPO_SOURCE_OF_TRUTH.json",
+      message: "Missing source-of-truth file."
+    });
+    return findings;
+  }
+
+  let data;
+  try {
+    data = readJson(file);
+  } catch (error) {
+    findings.push({
+      severity: "high",
+      file: "REPO_SOURCE_OF_TRUTH.json",
+      message: `Invalid JSON: ${error.message}`
+    });
+    return findings;
+  }
+
+  if (!data.project?.name) {
+    findings.push({
+      severity: "medium",
+      file: "REPO_SOURCE_OF_TRUTH.json",
+      message: "Missing project.name."
+    });
+  }
+
+  if (data.sourceOfTruth && typeof data.sourceOfTruth === "object") {
+    for (const [key, relPath] of Object.entries(data.sourceOfTruth)) {
+      if (!validateRelativePath(rootDir, relPath)) {
+        findings.push({
+          severity: "medium",
+          file: "REPO_SOURCE_OF_TRUTH.json",
+          message: `sourceOfTruth.${key} points to a missing path: ${relPath}`
+        });
+      }
+    }
+  }
+
+  if (!Array.isArray(data.contextMinimizer?.readFirst) || data.contextMinimizer.readFirst.length === 0) {
+    findings.push({
+      severity: "medium",
+      file: "REPO_SOURCE_OF_TRUTH.json",
+      message: "contextMinimizer.readFirst should list the files an agent reads first."
+    });
+  }
+
+  if (Array.isArray(data.contextMinimizer?.readFirst)) {
+    for (const relPath of data.contextMinimizer.readFirst) {
+      if (!validateRelativePath(rootDir, relPath)) {
+        findings.push({
+          severity: "high",
+          file: "REPO_SOURCE_OF_TRUTH.json",
+          message: `contextMinimizer.readFirst points to a missing path: ${relPath}`
+        });
+      }
+    }
+  }
+
+  if (!Array.isArray(data.contextMinimizer?.doNotLoadByDefault) || data.contextMinimizer.doNotLoadByDefault.length < 5) {
+    findings.push({
+      severity: "medium",
+      file: "REPO_SOURCE_OF_TRUTH.json",
+      message: "contextMinimizer.doNotLoadByDefault should protect active context from generated or stale folders."
+    });
+  }
+
+  if (!data.secrets?.policy) {
+    findings.push({
+      severity: "medium",
+      file: "REPO_SOURCE_OF_TRUTH.json",
+      message: "Missing secrets.policy."
+    });
+  }
+
+  if (!Array.isArray(data.verification?.defaultCommands) || data.verification.defaultCommands.length === 0) {
+    findings.push({
+      severity: "medium",
+      file: "REPO_SOURCE_OF_TRUTH.json",
+      message: "verification.defaultCommands should list the fastest meaningful proof command."
+    });
+  }
+
+  return findings;
+}
+
+function checkProject(targetDir, options = {}) {
+  const rootDir = path.resolve(targetDir);
+  const findings = [];
+
+  if (!fs.existsSync(rootDir)) {
+    findings.push({
+      severity: "high",
+      file: rootDir,
+      message: "Target directory does not exist."
+    });
+    return { rootDir, findings };
+  }
+
+  for (const file of REQUIRED_FILES) {
+    if (!fs.existsSync(path.join(rootDir, file))) {
+      findings.push({
+        severity: "high",
+        file,
+        message: "Required SuperAgent operating file is missing."
+      });
+    }
+  }
+
+  for (const file of RECOMMENDED_FILES) {
+    if (!fs.existsSync(path.join(rootDir, file))) {
+      findings.push({
+        severity: "low",
+        file,
+        message: "Recommended for production projects."
+      });
+    }
+  }
+
+  findings.push(...validateSourceOfTruth(rootDir));
+  findings.push(...scanForSecrets(rootDir));
+  findings.push(...scanForPlaceholders(rootDir));
+  findings.push(...validateContextSize(rootDir));
+
+  if (options.release) {
+    if (!fs.existsSync(path.join(rootDir, "SECURITY.md"))) {
+      findings.push({
+        severity: "medium",
+        file: "SECURITY.md",
+        message: "Recommended before making the repository public."
+      });
+    }
+
+    if (!fs.existsSync(path.join(rootDir, "CONTRIBUTING.md"))) {
+      findings.push({
+        severity: "low",
+        file: "CONTRIBUTING.md",
+        message: "Recommended before making the repository public."
+      });
+    }
+
+    if (!fs.existsSync(path.join(rootDir, "LICENSE"))) {
+      findings.push({
+        severity: "medium",
+        file: "LICENSE",
+        message: "No license file found. Choose public terms before release."
+      });
+    }
+  }
+
+  return { rootDir, findings };
+}
+
+function score(findings) {
+  const high = findings.filter((item) => item.severity === "high").length;
+  const medium = findings.filter((item) => item.severity === "medium").length;
+  const low = findings.filter((item) => item.severity === "low").length;
+
+  if (high > 0) return { label: "not-ready", high, medium, low };
+  if (medium > 0) return { label: "needs-review", high, medium, low };
+  return { label: "ready", high, medium, low };
+}
+
+function printCheck(result, jsonMode) {
+  const readiness = score(result.findings);
+
+  if (jsonMode) {
+    console.log(JSON.stringify({ ...result, readiness }, null, 2));
+    return;
+  }
+
+  console.log(`AiML SuperAgent check: ${result.rootDir}`);
+  console.log(`Readiness: ${readiness.label}`);
+  console.log(`Findings: high=${readiness.high} medium=${readiness.medium} low=${readiness.low}`);
+
+  if (result.findings.length === 0) {
+    console.log("No findings.");
+    return;
+  }
+
+  for (const item of result.findings) {
+    console.log(`- [${item.severity}] ${item.file}: ${item.message}`);
+  }
+}
+
+function parseArgs(argv) {
+  const args = [...argv];
+  const options = {
+    json: false,
+    release: false,
+    strict: false
+  };
+  const positionals = [];
+
+  for (const arg of args) {
+    if (arg === "--json") {
+      options.json = true;
+    } else if (arg === "--release") {
+      options.release = true;
+    } else if (arg === "--strict") {
+      options.strict = true;
+    } else {
+      positionals.push(arg);
+    }
+  }
+
+  return { command: positionals[0], targetArg: positionals[1], options };
+}
+
+const { command, targetArg, options } = parseArgs(process.argv.slice(2));
+
+if (!command || command === "--help" || command === "-h") {
+  usage();
+  process.exit(0);
+}
+
+if (command === "init") {
+  const targetDir = path.resolve(targetArg || ".");
+  const actions = copyTemplates(targetDir);
+  for (const action of actions) {
+    console.log(`${action.type}: ${action.file}`);
+  }
+  process.exit(0);
+}
+
+if (command === "check") {
+  const targetDir = path.resolve(targetArg || ".");
+  const result = checkProject(targetDir, options);
+  const readiness = score(result.findings);
+  printCheck(result, options.json);
+  process.exit(readiness.high > 0 || (options.strict && readiness.medium > 0) ? 1 : 0);
+}
+
+console.error(`Unknown command: ${command}`);
+usage();
+process.exit(1);

package/docs/01-operating-model.md

@@ -0,0 +1,95 @@
+# Operating Model
+
+AiML SuperAgent defines a project operating loop for AI coding assistants.
+
+Behavior rules are necessary, but they are not enough. A coding assistant also needs a stable way to know what is true, what is stale, what is safe to read, what must be verified, and what should be remembered.
+
+## The Six-Phase Loop
+
+### 1. Orient
+
+Read the minimum durable context:
+
+- `AGENTS.md`
+- `REPO_SOURCE_OF_TRUTH.json`
+- `WORKING_NOTES.md`
+- current task prompt
+
+The assistant should not load the whole repository at this stage.
+
+### 2. Verify
+
+If the task depends on live reality, verify before changing code.
+
+Examples:
+
+- current deployed URL
+- active environment variable names
+- current package version
+- latest error log
+- actual database schema
+- currently selected build
+
+Production reality beats memory.
+
+### 3. Narrow
+
+Use targeted search to find only the relevant files:
+
+```bash
+rg --files
+rg -n "keyword"
+```
+
+The assistant should explain why the files it opens are relevant.
+
+### 4. Patch
+
+Make the smallest safe diff.
+
+Rules:
+
+- no unrelated refactors
+- no style churn
+- no speculative abstractions
+- no deleting user work
+- no broad rewrites unless explicitly requested
+
+### 5. Prove
+
+Run the fastest meaningful verification.
+
+Examples:
+
+- typecheck
+- unit test
+- endpoint probe
+- build
+- smoke test
+- focused script
+
+When tests cannot be run, state the missing prerequisite.
+
+### 6. Record
+
+Update durable memory only if reality changed.
+
+Good notes:
+
+- prevent repeating investigation
+- identify production owners
+- record exact deployment behavior
+- explain why a surprising decision was made
+
+Bad notes:
+
+- paste giant logs
+- store secrets
+- preserve resolved noise
+- duplicate README content
+- record temporary guesses as facts
+
+## Operating Principle
+
+The assistant should leave the repo easier to operate than it found it.
+

package/docs/02-context-minimizer.md

@@ -0,0 +1,113 @@
+# Context Minimizer
+
+Context Minimizer is the central feature of AiML SuperAgent.
+
+It reduces token waste by separating durable memory from active working context.
+
+The goal is not smaller notes.
+
+The goal is smaller active context.
+
+## Problem
+
+Large-context agents often fail because they read too much:
+
+- stale notes
+- resolved logs
+- generated files
+- unrelated code
+- old screenshots
+- duplicate repos
+- package output
+
+The model becomes slower, more expensive, and more confused.
+
+## Strategy
+
+AiML SuperAgent divides context into four layers.
+
+### Layer 1: Durable Memory
+
+Always small. Read first.
+
+- `AGENTS.md`
+- `REPO_SOURCE_OF_TRUTH.json`
+- `WORKING_NOTES.md`
+
+### Layer 2: Task Context
+
+Provided by the user or issue.
+
+- current request
+- relevant error message
+- direct file path
+- screenshot or log excerpt
+
+### Layer 3: Targeted Source Context
+
+Found through search.
+
+- files matching the symbol
+- route handling the endpoint
+- config controlling the behavior
+- test covering the bug
+
+### Layer 4: Proof Context
+
+Generated during verification.
+
+- focused test result
+- build result
+- endpoint response
+- deployment status
+
+Proof context should be summarized before being saved.
+
+## Context Budget
+
+Every task should answer:
+
+1. What durable files are needed?
+2. What exact source files are needed?
+3. What logs or production checks are needed?
+4. What can be skipped?
+
+## Do Not Load By Default
+
+- `node_modules`
+- `.git`
+- `.next`
+- `dist`
+- `build`
+- `coverage`
+- `DerivedData`
+- huge logs
+- old screenshots
+- resolved incidents
+- unrelated archives
+
+## Search-First Commands
+
+```bash
+rg --files
+rg -n "symbolOrKeyword"
+rg -n "route|env|error|function"
+```
+
+## Note Compression Rule
+
+When saving a finding, write the smallest future-useful version:
+
+```text
+Bad:
+Pasted 700 lines of build logs.
+
+Good:
+Build failed because Next.js could not resolve package X from route Y.
+Fixed by pinning package version Z. Verified with npm run build on 2026-05-31.
+```
+
+## Success Metric
+
+Context Minimizer is working when future tasks need fewer broad searches and fewer repeated investigations.
+