@aimlsuperagent/agent 0.1.0

package/docs/comparison-claude-md.md

@@ -0,0 +1,56 @@
+# AiML SuperAgent And CLAUDE.md
+
+A `CLAUDE.md` file can teach an assistant how to behave.
+
+AiML SuperAgent teaches an assistant how to operate a real project over time.
+
+## The Behavior Layer
+
+The viral `CLAUDE.md` pattern is strong because it captures obvious engineering discipline:
+
+- think before coding
+- keep changes simple
+- make surgical edits
+- define success criteria
+- verify the result
+
+That should remain the baseline.
+
+## The Missing Operating Layer
+
+Behavior rules do not answer:
+
+- Which repository owns production?
+- Which deployment is live?
+- Which env var is stale?
+- Which logs are resolved history?
+- Which notes are safe to trust?
+- Which files should not be loaded by default?
+- Which proof is meaningful for this task?
+- Which credential names are safe to document?
+
+AiML SuperAgent adds that layer.
+
+## Practical Difference
+
+Behavior rule:
+
+```text
+Do not make unnecessary changes.
+```
+
+Operating rule:
+
+```text
+Before changing this route, confirm which backend is live, check the deployment log, inspect only the route and config files, avoid stale notes, patch the smallest diff, run the route probe, then update durable memory only if the production fact changed.
+```
+
+## Positioning
+
+AiML SuperAgent is not a replacement for `CLAUDE.md`.
+
+It is the next layer after it:
+
+- use `CLAUDE.md` for session behavior
+- use AiML SuperAgent for project memory, verification, deployment discipline, secret safety, and context minimization
+

package/docs/npm-private-publishing.md

@@ -0,0 +1,89 @@
+# Private npm Publishing
+
+This repository is prepared for a private npm package named:
+
+```text
+@aimlsuperagent/agent
+```
+
+Do not publish until npm confirms that the `@aimlsuperagent` scope is owned by the correct account or organization and private packages are enabled.
+
+## Current Safety State
+
+`package.json` intentionally keeps:
+
+```json
+"private": true
+```
+
+That blocks accidental publishing.
+
+The package also includes:
+
+```json
+"publishConfig": {
+  "access": "restricted",
+  "registry": "https://registry.npmjs.org/"
+}
+```
+
+Restricted access is the npm setting required for a private scoped package.
+
+## Confirm Scope Ownership
+
+Log in:
+
+```bash
+npm login
+npm whoami
+```
+
+Check organization or scope access:
+
+```bash
+npm org ls aimlsuperagent
+npm access ls-packages @aimlsuperagent
+```
+
+If those commands fail because the scope or organization does not exist, create or claim the npm organization/scope before publishing.
+
+## Dry Run
+
+Run:
+
+```bash
+npm run check:release
+npm run pack:dry-run
+```
+
+Review the file list. It should include docs, templates, examples, schemas, the CLI, and root operating files. It should not include secrets, local logs, or build output.
+
+## Publishing Procedure
+
+Only after private package access is confirmed:
+
+1. Remove `"private": true` from `package.json` in a dedicated publish commit.
+2. Run:
+
+```bash
+npm run check:release
+npm run pack:dry-run
+npm publish --access restricted
+```
+
+Do not run `npm publish --access public`.
+
+## Install
+
+Authorized users can install globally:
+
+```bash
+npm login
+npm i -g @aimlsuperagent/agent
+aiml-superagent --help
+```
+
+## Failure Rule
+
+If npm cannot confirm restricted/private access, do not publish. Keep using the private GitHub repo or a private tarball.
+

package/docs/release-checklist.md

@@ -0,0 +1,42 @@
+# Release Checklist
+
+Use this before making the repository public.
+
+## Repository State
+
+- Repository visibility intentionally selected.
+- README quick start tested.
+- `npm run check` passes.
+- No actual secrets in docs, examples, notes, commit history, or issue templates.
+- License decision made intentionally.
+- Package publishing state is intentional.
+
+## Content
+
+- README explains the project in one minute.
+- Comparison to behavior-only agent rules is respectful and accurate.
+- Context Minimizer is prominent.
+- Templates are copy-safe.
+- Examples are fictional or sanitized.
+- Docs do not depend on private company infrastructure.
+
+## Verification
+
+```bash
+npm run check
+node bin/aiml-superagent.js check . --release --strict
+git status --short
+```
+
+Optional:
+
+```bash
+node bin/aiml-superagent.js init /tmp/superagent-smoke
+node bin/aiml-superagent.js check /tmp/superagent-smoke
+```
+
+## Publication
+
+- Confirm MIT License is still the intended public license.
+- Remove private release candidate wording if appropriate.
+- Tag first public release.

package/examples/nextjs-vercel-app/AGENTS.md

@@ -0,0 +1,26 @@
+# Agent Operating Contract
+
+## Project Mission
+
+Example Next.js app deployed on Vercel.
+
+## First Files To Read
+
+1. `REPO_SOURCE_OF_TRUTH.json`
+2. `WORKING_NOTES.md`
+3. current task prompt
+
+## Working Rules
+
+- Verify the live route before assuming production behavior.
+- Use `rg --files` and `rg -n` before opening broad folders.
+- Do not store Vercel tokens or env values in notes.
+- Use small diffs and run `npm run build` before deploy.
+
+## Verification
+
+```bash
+npm run build
+curl -sSI https://example.com
+```
+

package/examples/nextjs-vercel-app/DEPLOYMENT_LOG.md

@@ -0,0 +1,13 @@
+# Deployment Log
+
+This is a fictional example. Do not treat it as a real deployment record.
+
+## 2026-05-31 - Example Production
+
+Platform: Vercel
+Commit or build: example-only
+Change: Demonstrates how to record a deployment.
+Verification: `curl -sSI https://example.com` returns a response from the placeholder domain.
+Rollback: redeploy previous known-good production deployment.
+Risks: none because this is not a real deployment.
+

package/examples/nextjs-vercel-app/README.md

@@ -0,0 +1,12 @@
+# Example: Next.js Vercel App
+
+This example shows how a web app can adopt AiML SuperAgent without exposing secrets.
+
+It includes:
+
+- `AGENTS.md`
+- `REPO_SOURCE_OF_TRUTH.json`
+- `WORKING_NOTES.md`
+
+Use it as a starting point, not as a real deployment config.
+

package/examples/nextjs-vercel-app/REPO_SOURCE_OF_TRUTH.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "../../schemas/repo-source-of-truth.schema.json",
+  "project": {
+    "name": "Example Next.js Vercel App",
+    "purpose": "Demonstrate AiML SuperAgent memory for a deployed web app.",
+    "status": "example",
+    "primaryAudience": [
+      "web app teams"
+    ]
+  },
+  "sourceOfTruth": {
+    "behaviorContract": "AGENTS.md",
+    "durableNotes": "WORKING_NOTES.md",
+    "deploymentLog": "DEPLOYMENT_LOG.md",
+    "envAudit": "SAFE_ENV_AUDIT.md"
+  },
+  "contextMinimizer": {
+    "readFirst": [
+      "AGENTS.md",
+      "REPO_SOURCE_OF_TRUTH.json",
+      "WORKING_NOTES.md"
+    ],
+    "doNotLoadByDefault": [
+      ".git",
+      "node_modules",
+      ".next",
+      "dist",
+      "coverage",
+      "large logs",
+      "old screenshots"
+    ],
+    "searchFirst": [
+      "rg --files",
+      "rg -n \"route|env|api|middleware\""
+    ],
+    "contextRules": [
+      "Open route files only after search identifies them.",
+      "Verify production route headers with curl before claiming deploy success.",
+      "Store env var names and roles only."
+    ]
+  },
+  "verification": {
+    "defaultCommands": [
+      "npm run build"
+    ],
+    "releaseChecks": [
+      "curl -sSI https://example.com returns 200",
+      "no secret values in repo"
+    ]
+  },
+  "secrets": {
+    "policy": "Store names and roles only. Never store values.",
+    "allowedExamples": [
+      "DATABASE_URL",
+      "VERCEL_PROJECT_ID",
+      "OPENAI_API_KEY"
+    ],
+    "forbiddenExamples": [
+      "actual tokens",
+      "database URLs with passwords",
+      "private keys"
+    ]
+  }
+}
+

package/examples/nextjs-vercel-app/SAFE_ENV_AUDIT.md

@@ -0,0 +1,9 @@
+# Safe Environment Audit
+
+This is a fictional example. No real secrets are required.
+
+| Name | Role | Environments | Source Of Truth | Status | Last Verified |
+| --- | --- | --- | --- | --- | --- |
+| DATABASE_URL | Server database connection | production, preview | hosting provider env | placeholder | 2026-05-31 |
+| OPENAI_API_KEY | Server-side model calls | production | hosting provider env | placeholder | 2026-05-31 |
+

package/examples/nextjs-vercel-app/WORKING_NOTES.md

@@ -0,0 +1,16 @@
+# Working Notes
+
+## Current Durable Facts
+
+- This is a fictional example.
+- Production URL uses `https://example.com` as a placeholder.
+- Env var names may be documented; values must never be stored.
+
+## Active Risks
+
+- None. This example does not connect to a real deployment.
+
+## Recent Verification
+
+- Not applicable.
+

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@aimlsuperagent/agent",
+  "version": "0.1.0",
+  "description": "A token-efficient operating framework for AI coding assistants.",
+  "type": "module",
+  "bin": {
+    "aiml-superagent": "bin/aiml-superagent.js"
+  },
+  "files": [
+    "bin/",
+    "adapters/",
+    "docs/",
+    "examples/",
+    "schemas/",
+    "templates/",
+    "AGENTS.md",
+    "CONTRIBUTING.md",
+    "DEPLOYMENT_LOG.md",
+    "LICENSE",
+    "README.md",
+    "REPO_SOURCE_OF_TRUTH.json",
+    "SAFE_ENV_AUDIT.md",
+    "SECURITY.md",
+    "WORKING_NOTES.md"
+  ],
+  "scripts": {
+    "check": "node bin/aiml-superagent.js check .",
+    "check:json": "node bin/aiml-superagent.js check . --json",
+    "check:release": "node bin/aiml-superagent.js check . --release --strict",
+    "pack:dry-run": "npm pack --dry-run --cache ./.npm-cache",
+    "prepublishOnly": "node scripts/assert-private-publish-ready.js && node bin/aiml-superagent.js check . --release --strict"
+  },
+  "keywords": [
+    "ai",
+    "coding-agent",
+    "agents",
+    "context-minimizer",
+    "developer-tools",
+    "llm"
+  ],
+  "homepage": "https://aimlsuperagent.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/whisperaiml/superagent-repo.git"
+  },
+  "bugs": {
+    "url": "https://github.com/whisperaiml/superagent-repo/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT"
+}

package/schemas/repo-source-of-truth.schema.json

@@ -0,0 +1,122 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://aimlsuperagent.com/schemas/repo-source-of-truth.schema.json",
+  "title": "AiML SuperAgent Repo Source Of Truth",
+  "type": "object",
+  "required": [
+    "project",
+    "sourceOfTruth",
+    "contextMinimizer",
+    "verification",
+    "secrets"
+  ],
+  "properties": {
+    "project": {
+      "type": "object",
+      "required": [
+        "name",
+        "purpose",
+        "status"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "purpose": {
+          "type": "string"
+        },
+        "status": {
+          "type": "string"
+        },
+        "primaryAudience": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "sourceOfTruth": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
+    "contextMinimizer": {
+      "type": "object",
+      "required": [
+        "readFirst",
+        "doNotLoadByDefault",
+        "searchFirst",
+        "contextRules"
+      ],
+      "properties": {
+        "readFirst": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "doNotLoadByDefault": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "searchFirst": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "contextRules": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "verification": {
+      "type": "object",
+      "properties": {
+        "defaultCommands": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "releaseChecks": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "secrets": {
+      "type": "object",
+      "required": [
+        "policy"
+      ],
+      "properties": {
+        "policy": {
+          "type": "string"
+        },
+        "allowedExamples": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "forbiddenExamples": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}
+

package/templates/AGENTS.template.md

@@ -0,0 +1,42 @@
+# Agent Operating Contract
+
+## Project Mission
+
+Describe the project in one paragraph.
+
+## First Files To Read
+
+1. `REPO_SOURCE_OF_TRUTH.json`
+2. `WORKING_NOTES.md`
+3. the current task prompt
+
+## Working Rules
+
+- Use targeted search before loading broad folders.
+- Make small, task-traceable diffs.
+- Verify production reality before changing code when the task depends on live state.
+- Do not store secrets in notes, examples, commits, or logs.
+- Update durable notes only when reality changed.
+
+## Do Not Load By Default
+
+- `.git`
+- `node_modules`
+- `.next`
+- `dist`
+- `build`
+- `coverage`
+- large logs
+- generated files
+- archived incidents
+
+## Verification
+
+Default proof command:
+
+```bash
+REPLACE_WITH_COMMAND
+```
+
+If the command cannot run, state why.
+

package/templates/DEPLOYMENT_LOG.template.md

@@ -0,0 +1,11 @@
+# Deployment Log
+
+## YYYY-MM-DD - ENVIRONMENT
+
+Platform:
+Commit or build:
+Change:
+Verification:
+Rollback:
+Risks:
+

package/templates/INCIDENT_REPORT.template.md

@@ -0,0 +1,26 @@
+# Incident Report
+
+## Summary
+
+What happened?
+
+## Impact
+
+Who or what was affected?
+
+## Cause
+
+What was the verified cause?
+
+## Fix
+
+What changed?
+
+## Verification
+
+How was the fix proved?
+
+## Future Memory
+
+What should future agents remember?
+

package/templates/PRODUCTION_CHECK.template.md

@@ -0,0 +1,24 @@
+# Production Check
+
+## Target
+
+URL, service, account, device, or deployment being checked.
+
+## Reason
+
+Why production reality matters for this task.
+
+## Read-Only Checks
+
+```bash
+COMMANDS_HERE
+```
+
+## Result
+
+Observed behavior.
+
+## Decision
+
+What this proves or changes.
+

package/templates/REPO_SOURCE_OF_TRUTH.template.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "./schemas/repo-source-of-truth.schema.json",
+  "project": {
+    "name": "PROJECT_NAME",
+    "purpose": "One sentence describing what this project does.",
+    "status": "active",
+    "primaryAudience": []
+  },
+  "sourceOfTruth": {
+    "behaviorContract": "AGENTS.md",
+    "durableNotes": "WORKING_NOTES.md",
+    "deploymentLog": "DEPLOYMENT_LOG.md",
+    "envAudit": "SAFE_ENV_AUDIT.md"
+  },
+  "contextMinimizer": {
+    "readFirst": [
+      "AGENTS.md",
+      "REPO_SOURCE_OF_TRUTH.json",
+      "WORKING_NOTES.md"
+    ],
+    "doNotLoadByDefault": [
+      ".git",
+      "node_modules",
+      "dist",
+      "build",
+      ".next",
+      "coverage",
+      "large logs",
+      "generated artifacts"
+    ],
+    "searchFirst": [
+      "rg --files",
+      "rg -n \"keyword\""
+    ],
+    "contextRules": [
+      "Load only files directly related to the task.",
+      "Summarize long logs before saving them.",
+      "Move resolved incidents into archive.",
+      "Store credential names and roles only."
+    ]
+  },
+  "verification": {
+    "defaultCommands": [],
+    "releaseChecks": []
+  },
+  "secrets": {
+    "policy": "Store names and roles only. Never store values.",
+    "allowedExamples": [],
+    "forbiddenExamples": [
+      "actual tokens",
+      "private keys",
+      "passwords",
+      "customer PII"
+    ]
+  }
+}
+

package/templates/SAFE_ENV_AUDIT.template.md

@@ -0,0 +1,8 @@
+# Safe Environment Audit
+
+Do not store values. Store names, roles, scope, and verification status only.
+
+| Name | Role | Environments | Source Of Truth | Status | Last Verified |
+| --- | --- | --- | --- | --- | --- |
+| EXAMPLE_API_KEY | Example external API access | production, preview | hosting provider env | placeholder | YYYY-MM-DD |
+