@aimlsuperagent/agent 0.1.0

package/AGENTS.md

@@ -0,0 +1,86 @@
+# AiML SuperAgent Operating Contract
+
+This file is the behavior and operation contract for AI coding assistants working in this repository.
+
+## Mission
+
+Build a public-ready, model-agnostic framework that teaches AI coding assistants how to operate real software projects over time.
+
+The framework must be:
+
+- practical enough to use immediately
+- rigorous enough for production projects
+- small enough to avoid context bloat
+- clear enough for developers to trust
+
+## Working Rules
+
+1. Read `REPO_SOURCE_OF_TRUTH.json` before making structural claims about this repo.
+2. Read `WORKING_NOTES.md` only when present and directly relevant.
+3. Prefer targeted search over loading broad folders.
+4. Do not add secrets, tokens, private URLs, account IDs, or credential values to examples.
+5. Keep examples generic unless explicitly marked as fictional.
+6. Make small diffs with a clear reason.
+7. Run the fastest meaningful verification after changes.
+8. Update durable notes only when a fact will help future work.
+
+## Context Minimizer Rules
+
+Load only what the current task needs.
+
+Do not load these by default:
+
+- `.git`
+- `node_modules`
+- `dist`
+- `build`
+- `.next`
+- `coverage`
+- generated files
+- old logs
+- archived incidents
+
+Search before reading:
+
+```bash
+rg --files
+rg -n "keyword"
+```
+
+## Secret Safety
+
+Allowed in docs:
+
+- environment variable names
+- credential roles
+- setup locations
+- placeholder values such as `YOUR_API_KEY`
+
+Never store:
+
+- actual API keys
+- access tokens
+- refresh tokens
+- passwords
+- private keys
+- customer PII
+- private database URLs
+
+## Verification Standard
+
+For documentation changes:
+
+- run the checker
+- inspect generated examples when changed
+
+For script changes:
+
+- run the script on this repo
+- run at least one negative or edge case when practical
+
+For release changes:
+
+- confirm repo status
+- confirm private/public state before publication
+- confirm no secrets are present
+

package/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing
+
+AiML SuperAgent contributions should improve long-term project operation.
+
+## Good Contributions
+
+- clearer memory templates
+- better context minimizer checks
+- safer secret detection
+- model adapter examples
+- production verification patterns
+- concise docs that reduce future ambiguity
+
+## Avoid
+
+- vendor lock-in
+- giant prompts
+- speculative abstractions
+- secrets in examples
+- customer-specific workflows without sanitization
+
+## Development
+
+Run:
+
+```bash
+npm run check
+```
+
+The repo should stay useful without installing dependencies.
+

package/DEPLOYMENT_LOG.md

@@ -0,0 +1,39 @@
+# Deployment Log
+
+This repository is currently a private release candidate and has not been publicly deployed as a package.
+
+## 2026-05-31 - Private Repository Buildout
+
+Platform: local repository
+Commit or build: pending
+Change: Created AiML SuperAgent framework docs, templates, examples, schema, and checker.
+Verification: `npm run check`
+Rollback: revert this repository buildout before public release.
+Risks: license choice is intentionally unresolved before publication.
+
+## 2026-05-31 - Hardening Pass
+
+Platform: local repository
+Commit or build: pending
+Change: Added stricter checker validation, public-repo templates, evaluation docs, anti-pattern docs, adoption playbook, and context-budget guidance.
+Verification: `npm run check`; example check; smoke init check; release check.
+Rollback: revert hardening pass before public release.
+Risks: release mode intentionally requires a license decision before public launch.
+
+## 2026-05-31 - License Selection
+
+Platform: local repository
+Commit or build: pending
+Change: Added MIT License and updated package metadata.
+Verification: `node bin/aiml-superagent.js check . --release --strict`
+Rollback: change `LICENSE` and `package.json` before public release if a different license is selected.
+Risks: repository remains private; MIT terms matter when shared or made public.
+
+## 2026-05-31 - Private npm Package Preparation
+
+Platform: npm package metadata
+Commit or build: pending
+Change: Prepared package metadata for `@aimlsuperagent/agent` with restricted publish config, file allowlist, dry-run script, and private publishing documentation.
+Verification: `npm run check:release`; `npm run pack:dry-run`.
+Rollback: revert package metadata to local-only package before publishing.
+Risks: publishing remains intentionally blocked by `private:true` until npm scope ownership and private package support are confirmed.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marvin Freedman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,253 @@
+# AiML SuperAgent
+
+A token-efficient operating framework for AI coding assistants.
+
+AiML SuperAgent turns an AI coding assistant into a long-term project operator. It keeps scoped memory, verifies production reality before changing code, protects secrets, tracks deployments, minimizes wasted context, and produces small safe diffs.
+
+This is not another prompt collection. It is a repeatable operating layer for real repositories.
+
+## Why AiML SuperAgent?
+
+Most AI coding assistants fail on long-running projects for two reasons:
+
+1. They forget durable production facts.
+2. They overload themselves with stale or irrelevant context.
+
+A behavior file such as `CLAUDE.md` can teach an assistant how to behave in one session: think first, keep changes small, avoid assumptions, and verify results. That is useful and should be kept.
+
+AiML SuperAgent adds the missing operating layer:
+
+- scoped project memory
+- source-of-truth files
+- production-first verification
+- secret-safe notes
+- deployment logs
+- incident memory
+- context minimization
+- task-traceable diffs
+- model-agnostic workflows
+
+Use `CLAUDE.md` for behavior. Use AiML SuperAgent for project operation.
+
+## The Core Idea
+
+The goal is not bigger notes.
+
+The goal is smaller active context.
+
+AiML SuperAgent separates durable memory from temporary work. The assistant starts with high-signal files, then searches only the parts of the repo relevant to the current task.
+
+Default read order:
+
+1. `AGENTS.md`
+2. `REPO_SOURCE_OF_TRUTH.json`
+3. `WORKING_NOTES.md`
+4. the current task prompt
+5. targeted source files found by search
+
+Default skip list:
+
+- `node_modules`
+- build output
+- `.next`
+- `dist`
+- `coverage`
+- derived data
+- generated artifacts
+- large logs
+- resolved incidents
+- old screenshots
+- unrelated archives
+
+That is the Context Minimizer.
+
+## What This Repo Provides
+
+```text
+aiml-superagent/
+  README.md
+  AGENTS.md
+  bin/
+    aiml-superagent.js
+  docs/
+    01-operating-model.md
+    02-context-minimizer.md
+    03-project-memory.md
+    04-verification-loop.md
+    05-secret-safe-operations.md
+    06-deployment-discipline.md
+    07-note-hygiene.md
+    08-model-agnostic-use.md
+    09-agent-evaluation.md
+    10-adoption-playbook.md
+    11-anti-patterns.md
+    12-context-budget.md
+    comparison-claude-md.md
+    release-checklist.md
+  schemas/
+    repo-source-of-truth.schema.json
+  templates/
+    AGENTS.template.md
+    REPO_SOURCE_OF_TRUTH.template.json
+    WORKING_NOTES.template.md
+    DEPLOYMENT_LOG.template.md
+    INCIDENT_REPORT.template.md
+    SAFE_ENV_AUDIT.template.md
+    PRODUCTION_CHECK.template.md
+    TASK_BRIEF.template.md
+  examples/
+    nextjs-vercel-app/
+      README.md
+      AGENTS.md
+      REPO_SOURCE_OF_TRUTH.json
+      WORKING_NOTES.md
+```
+
+## Quick Start
+
+From this repository:
+
+```bash
+npm run check
+```
+
+Copy the templates into a project:
+
+```bash
+node bin/aiml-superagent.js init ../your-project
+```
+
+Check a project for SuperAgent readiness:
+
+```bash
+node bin/aiml-superagent.js check ../your-project
+```
+
+Freshly initialized projects are expected to show `needs-review` until template placeholders for project name, dates, and proof commands are replaced.
+
+Private npm package preparation:
+
+```bash
+npm run pack:dry-run
+```
+
+Before making a repo public:
+
+```bash
+node bin/aiml-superagent.js check . --release
+```
+
+For CI where medium-risk findings should fail the build:
+
+```bash
+node bin/aiml-superagent.js check . --strict
+```
+
+## The Operating Loop
+
+Every task follows the same loop:
+
+```text
+1. Orient
+   Read only the source-of-truth files and the active task.
+
+2. Verify
+   Check production reality before changing code when the answer depends on live state.
+
+3. Narrow
+   Search for the smallest source area that can solve the task.
+
+4. Patch
+   Make the smallest safe diff.
+
+5. Prove
+   Run the fastest meaningful test or runtime check.
+
+6. Record
+   Update durable notes only if reality changed.
+```
+
+## Framework Guarantees
+
+AiML SuperAgent is designed to make an assistant:
+
+- explicit about assumptions
+- resistant to stale context
+- careful with secrets
+- aware of production and deployment state
+- less likely to edit the wrong repo
+- less likely to over-refactor
+- more likely to leave a useful audit trail
+
+It does not guarantee correctness. It gives the assistant a better operating system for reaching correctness.
+
+## Maturity Model
+
+AiML SuperAgent adoption has four levels:
+
+| Level | Name | Description |
+| --- | --- | --- |
+| 0 | Behavior only | A single behavior file tells the assistant to be careful. |
+| 1 | Scoped memory | The project has source-of-truth files and working notes. |
+| 2 | Verified operation | The assistant checks production reality and records proof. |
+| 3 | Context-minimized operation | The assistant loads only durable memory and targeted task context by default. |
+
+The public goal of this framework is Level 3.
+
+## Model Support
+
+AiML SuperAgent is model-agnostic. It works with:
+
+- Claude
+- GPT-5.5
+- Codex
+- Cursor
+- Perplexity
+- Gemini
+- local models
+- future coding agents
+
+The model can change. The operating discipline should remain stable.
+
+## Recommended Adoption Path
+
+1. Add `AGENTS.md`, `REPO_SOURCE_OF_TRUTH.json`, and `WORKING_NOTES.md`.
+2. Fill in production owners, deployment surfaces, package manager, test commands, and secret names.
+3. Add `DEPLOYMENT_LOG.md` after the next live deploy.
+4. Add incident reports only for issues that change future behavior.
+5. Run `node bin/aiml-superagent.js check`.
+6. Iterate until the checker reports no high-risk gaps.
+
+## Design Principles
+
+- Memory should be durable, scoped, and revisable.
+- Context should be loaded by relevance, not by habit.
+- Secrets should be referenced by name and role, never by value.
+- Production reality beats repo assumptions.
+- A small verified diff beats a large plausible rewrite.
+- Notes should reduce future token use, not increase it.
+
+## How This Improves on a Single Behavior File
+
+The viral `CLAUDE.md` approach is valuable because it gives assistants simple behavioral rules. AiML SuperAgent builds on that idea by adding project-level operation:
+
+- where to find durable facts
+- how to avoid stale context
+- how to verify live systems
+- how to record deployments and incidents
+- how to protect secrets
+- how to keep memory useful over months, not just one session
+
+See [docs/comparison-claude-md.md](docs/comparison-claude-md.md).
+
+## Status
+
+Private release candidate. The repository can remain private while using the MIT License; the license defines reuse terms if and when the project is shared publicly.
+
+Prepared package name: `@aimlsuperagent/agent`.
+
+Publishing is intentionally blocked by `"private": true` until npm scope ownership and private package access are confirmed. See [docs/npm-private-publishing.md](docs/npm-private-publishing.md).
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

package/REPO_SOURCE_OF_TRUTH.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "./schemas/repo-source-of-truth.schema.json",
+  "project": {
+    "name": "AiML SuperAgent",
+    "purpose": "A token-efficient operating framework for AI coding assistants.",
+    "status": "private-release-candidate",
+    "primaryAudience": [
+      "software teams using AI coding assistants",
+      "solo builders managing long-running projects",
+      "agent framework authors"
+    ]
+  },
+  "sourceOfTruth": {
+    "behaviorContract": "AGENTS.md",
+    "durableNotes": "WORKING_NOTES.md",
+    "templates": "templates/",
+    "docs": "docs/",
+    "examples": "examples/",
+    "privateNpmPublishing": "docs/npm-private-publishing.md"
+  },
+  "contextMinimizer": {
+    "readFirst": [
+      "AGENTS.md",
+      "REPO_SOURCE_OF_TRUTH.json",
+      "WORKING_NOTES.md"
+    ],
+    "doNotLoadByDefault": [
+      ".git",
+      "node_modules",
+      "dist",
+      "build",
+      ".next",
+      "coverage",
+      "generated artifacts",
+      "large logs",
+      "resolved incidents",
+      "old screenshots",
+      "unrelated archives"
+    ],
+    "searchFirst": [
+      "rg --files",
+      "rg -n \"keyword\""
+    ],
+    "contextRules": [
+      "Load only files directly related to the current task.",
+      "Summarize long logs before saving them to notes.",
+      "Move resolved incidents into dated archives.",
+      "Keep secrets out of notes; store names and roles only."
+    ]
+  },
+  "verification": {
+    "defaultCommands": [
+      "npm run check"
+    ],
+    "releaseChecks": [
+      "no real secrets in docs or examples",
+      "all templates are copy-safe",
+      "checker passes",
+      "README links resolve",
+      "npm private scope confirmed before removing private:true"
+    ]
+  },
+  "secrets": {
+    "policy": "Store variable names and roles only. Never store values.",
+    "allowedExamples": [
+      "DATABASE_URL",
+      "OPENAI_API_KEY",
+      "VERCEL_PROJECT_ID"
+    ],
+    "forbiddenExamples": [
+      "actual tokens",
+      "private keys",
+      "password hashes tied to real users",
+      "customer data"
+    ]
+  }
+}

package/SAFE_ENV_AUDIT.md

@@ -0,0 +1,12 @@
+# Safe Environment Audit
+
+This framework repository should not require production secrets.
+
+| Name | Role | Environments | Source Of Truth | Status | Last Verified |
+| --- | --- | --- | --- | --- | --- |
+| None required | This repo is documentation and local tooling only | local | repository | verified | 2026-05-31 |
+
+## Policy
+
+Examples may include environment variable names and placeholder values only. Do not store actual API keys, tokens, private keys, database URLs with passwords, customer PII, or password hashes tied to real users.
+

package/SECURITY.md

@@ -0,0 +1,32 @@
+# Security Policy
+
+AiML SuperAgent is designed around secret-safe operation.
+
+## Reporting
+
+Do not open public issues containing secrets.
+
+If this repo is made public, use the repository security contact or private advisory flow for sensitive reports.
+
+## Secret Policy
+
+Documentation may include:
+
+- env var names
+- credential roles
+- placeholder values
+
+Documentation must not include:
+
+- credential values
+- private keys
+- production database URLs
+- passwords
+- customer PII
+
+Run before release:
+
+```bash
+npm run check
+```
+

package/WORKING_NOTES.md

@@ -0,0 +1,27 @@
+# Working Notes
+
+## Current State
+
+- Repository is private.
+- Goal is a public-ready release candidate for AiML SuperAgent.
+- Positioning: not a replacement for behavior files, but the next operating layer after them.
+- Core differentiator: Context Minimizer, which reduces token waste by separating durable memory from active task context.
+- Checker now validates unresolved placeholders, source-of-truth paths, context-bloat size limits, and optional release/strict gates.
+
+## Release Requirements
+
+- README must explain the framework in one minute.
+- Docs must make the system usable without a course or video.
+- Templates must be safe to copy into customer or open-source repos.
+- Examples must not contain real secrets or private infrastructure.
+- Checker must catch missing operating files and obvious secret leakage.
+
+## Open Decisions
+
+- Whether to publish as a GitHub-only framework or an npm starter package.
+- Whether to add model-specific adapter files for Claude, Codex, Cursor, and Gemini in separate folders.
+
+## Decisions
+
+- License set to MIT while repository remains private. This preserves private development while preparing clean public reuse terms.
+- Package name prepared as `@aimlsuperagent/agent`, but `private:true` remains as a safety brake until npm scope ownership and private package access are confirmed.

package/adapters/claude/CLAUDE.md

@@ -0,0 +1,27 @@
+# CLAUDE.md Adapter
+
+Use this as a thin behavior wrapper when a project already uses AiML SuperAgent.
+
+## Behavior
+
+- Think before coding.
+- Prefer simple solutions.
+- Make surgical changes.
+- Define success criteria.
+- Verify results.
+
+## Operation
+
+Before changing code:
+
+1. Read `AGENTS.md`.
+2. Read `REPO_SOURCE_OF_TRUTH.json`.
+3. Read only relevant `WORKING_NOTES.md` sections.
+4. Use targeted search for source files.
+5. Verify production reality when live state matters.
+6. Make the smallest safe diff.
+7. Run the fastest meaningful proof.
+8. Update durable notes only if reality changed.
+
+Do not store secrets in notes, examples, logs, or commits.
+

package/adapters/codex/AGENTS.md

@@ -0,0 +1,24 @@
+# Codex Adapter
+
+This adapter mirrors the root AiML SuperAgent contract for Codex-style agents.
+
+## First Step
+
+Read:
+
+1. `AGENTS.md`
+2. `REPO_SOURCE_OF_TRUTH.json`
+3. relevant parts of `WORKING_NOTES.md`
+
+## Execution
+
+- Prefer `rg --files` and `rg -n`.
+- Use small patches.
+- Do not rewrite unrelated files.
+- Verify with the fastest meaningful command.
+- Summarize what changed and what was verified.
+
+## Safety
+
+Never write secrets to durable memory.
+

package/adapters/cursor/rules.md

@@ -0,0 +1,12 @@
+# Cursor Rules Adapter
+
+Use AiML SuperAgent as the project operating layer.
+
+- Read `AGENTS.md`, `REPO_SOURCE_OF_TRUTH.json`, and relevant `WORKING_NOTES.md` before broad edits.
+- Search before opening broad folders.
+- Keep active context small.
+- Verify live production state when the task depends on it.
+- Make the smallest safe diff.
+- Do not store secrets in generated code, examples, notes, or comments.
+- Update durable notes only when future tasks benefit.
+