@aimlsuperagent/agent 0.1.0

package/docs/03-project-memory.md

@@ -0,0 +1,83 @@
+# Project Memory
+
+AiML SuperAgent memory is not a transcript. It is an operating index.
+
+## Memory Types
+
+### Source Of Truth
+
+File: `REPO_SOURCE_OF_TRUTH.json`
+
+Stores stable facts:
+
+- project name and purpose
+- production owners
+- deploy surfaces
+- package manager
+- default verification commands
+- context minimizer rules
+- secret policy
+
+### Working Notes
+
+File: `WORKING_NOTES.md`
+
+Stores current durable facts:
+
+- active architecture decisions
+- recent production findings
+- unresolved risks
+- test devices or accounts
+- known temporary workarounds
+
+### Deployment Log
+
+File: `DEPLOYMENT_LOG.md`
+
+Stores:
+
+- deployed version
+- date
+- environment
+- URL or platform
+- verification result
+- rollback note
+
+### Incident Reports
+
+File: `INCIDENT_REPORT.md` or dated files under `incidents/`
+
+Stores only incidents that change future behavior.
+
+### Safe Environment Audit
+
+File: `SAFE_ENV_AUDIT.md`
+
+Stores env var names, roles, owners, and expected environments. Never store values.
+
+## Memory Quality Test
+
+A note is worth keeping if it helps answer one of these:
+
+- Which repo owns production?
+- Which backend is live?
+- Which env var is still active?
+- Which failure was already fixed?
+- Which command proves the current behavior?
+- Which files are dangerous to edit blindly?
+
+If not, archive or delete it.
+
+## Staleness Policy
+
+Every durable fact should be easy to challenge.
+
+Use labels:
+
+- `verified`
+- `assumed`
+- `deprecated`
+- `needs-check`
+
+Do not let assumptions age into facts.
+

package/docs/04-verification-loop.md

@@ -0,0 +1,82 @@
+# Verification Loop
+
+AiML SuperAgent treats verification as part of implementation, not an optional afterthought.
+
+## Verification Hierarchy
+
+Use the cheapest proof that meaningfully reduces risk.
+
+1. Static check
+2. Unit or focused test
+3. Build
+4. Local smoke test
+5. Staging probe
+6. Production read-only probe
+7. Production mutation test with approval
+
+## Production-First Verification
+
+Verify production reality before code changes when the issue depends on:
+
+- deployed environment variables
+- external APIs
+- app store metadata
+- browser behavior
+- cloud routing
+- database schema
+- background jobs
+- push notification credentials
+- live webhooks
+
+The repo can be correct while production is wrong.
+
+## Proof Statement
+
+Every completed task should end with a proof statement:
+
+```text
+Verified with:
+- npm run build
+- curl -sSI https://example.com/route returned 200
+```
+
+If not verified:
+
+```text
+Not verified because:
+- device was not connected
+- credentials were not available
+- network access was blocked
+```
+
+## Avoid False Proof
+
+Do not claim success from:
+
+- code inspection only
+- unrelated tests
+- old logs
+- successful deploy without route check
+- local build when the bug was production configuration
+
+## Fast Proof Examples
+
+Next.js route:
+
+```bash
+npm run build
+curl -sSI https://example.com/api/health
+```
+
+Database migration:
+
+```bash
+node scripts/validate-schema.mjs
+```
+
+CLI script:
+
+```bash
+node bin/aiml-superagent.js check .
+```
+

package/docs/05-secret-safe-operations.md

@@ -0,0 +1,63 @@
+# Secret-Safe Operations
+
+AiML SuperAgent requires secret-safe memory.
+
+Agents need to know which credentials exist and what they do. They do not need credential values in notes.
+
+## Allowed
+
+- variable names
+- credential role
+- service owner
+- environment scope
+- rotation date
+- where to update the value
+- placeholder examples
+
+Example:
+
+```text
+OPENAI_API_KEY
+Role: server-side model calls
+Environments: production, preview
+Owner: platform
+Value: never stored in repo
+```
+
+## Forbidden
+
+- actual API keys
+- database URLs with passwords
+- private keys
+- access tokens
+- refresh tokens
+- production passwords
+- customer PII
+- password hashes tied to real users
+
+## Redaction Pattern
+
+Use this form:
+
+```text
+sk-...abcd
+postgres://USER@HOST/DB
+CR...1234
+```
+
+## Environment Audits
+
+Use `SAFE_ENV_AUDIT.md` to record:
+
+- env var name
+- expected environment
+- role
+- source of truth
+- stale duplicate risk
+- verification date
+
+Never paste values.
+
+## Agent Rule
+
+If a user gives a secret in chat or terminal, use it only for the immediate task when necessary. Do not write it to durable notes, examples, commit messages, logs, or documentation.

package/docs/06-deployment-discipline.md

@@ -0,0 +1,50 @@
+# Deployment Discipline
+
+Long-running agent work fails when deployment state is vague.
+
+AiML SuperAgent records deployments as operational facts.
+
+## Deployment Log Fields
+
+Each deployment entry should include:
+
+- date and time
+- environment
+- platform
+- commit or build ID
+- changed behavior
+- verification command
+- rollback note
+- open risks
+
+## Deployment Entry
+
+```text
+## 2026-05-31 - Production
+
+Platform: Vercel
+Commit: abc1234
+Change: Added /api/health route.
+Verify: curl -sSI https://example.com/api/health returned 200.
+Rollback: redeploy previous production deployment.
+Risks: none known.
+```
+
+## Deploy Before Or After Notes?
+
+Update the deployment log after verification, not before.
+
+Do not record planned deployments as completed deployments.
+
+## Release Gates
+
+Before public release:
+
+- checker passes
+- no secrets in repo
+- README quick start works
+- examples are fictional or sanitized
+- license is intentional
+- public/private repo state is intentional
+- deployment target is documented
+

package/docs/07-note-hygiene.md

@@ -0,0 +1,51 @@
+# Note Hygiene
+
+Notes are useful only when they reduce future work.
+
+## Keep
+
+- durable project facts
+- surprising production behavior
+- deployment history
+- incident outcomes
+- known stale credentials
+- exact verification commands
+- decisions that prevent future mistakes
+
+## Remove Or Archive
+
+- resolved logs
+- speculative guesses
+- duplicate notes
+- stale TODOs
+- one-off command output
+- old screenshots
+- copied documentation
+
+## Compression Pattern
+
+Turn raw logs into a useful memory:
+
+```text
+Observed:
+Route /api/catalog/sync returned 413 for large payloads.
+
+Cause:
+Payload exceeded platform body limit.
+
+Fix:
+Chunk upload into product batches.
+
+Verified:
+227 products and 1068 variants synced on 2026-05-31.
+```
+
+## Note Review Cadence
+
+For active projects:
+
+- review `WORKING_NOTES.md` weekly
+- archive resolved incidents monthly
+- update `REPO_SOURCE_OF_TRUTH.json` whenever production ownership changes
+- prune logs as soon as they stop helping
+

package/docs/08-model-agnostic-use.md

@@ -0,0 +1,53 @@
+# Model-Agnostic Use
+
+AiML SuperAgent is not tied to one model or vendor.
+
+The framework can be used with:
+
+- Claude
+- GPT-5.5
+- Codex
+- Cursor
+- Perplexity
+- Gemini
+- local models
+- future coding assistants
+
+## Why Model-Agnostic Matters
+
+Models change quickly. Project operation should not.
+
+The stable layer should be:
+
+- memory structure
+- verification loop
+- secret policy
+- deployment discipline
+- note hygiene
+- context minimization
+
+## Adapter Pattern
+
+Different tools can read different files:
+
+- `AGENTS.md` for general coding agents
+- `CLAUDE.md` for Claude-specific behavior
+- `.cursor/rules` for Cursor
+- local skill files for specialized workflows
+
+AiML SuperAgent can generate or coexist with those files. The source of truth remains the project memory, not the vendor-specific wrapper.
+
+## Prompt Starter
+
+Use this with any coding assistant:
+
+```text
+Follow AiML SuperAgent for this task.
+Read AGENTS.md, REPO_SOURCE_OF_TRUTH.json, and only the relevant working notes.
+Use targeted search before loading broad folders.
+Verify production reality when the task depends on live state.
+Make the smallest safe diff.
+Run the fastest meaningful proof.
+Update durable notes only if reality changed.
+```
+

package/docs/09-agent-evaluation.md

@@ -0,0 +1,95 @@
+# Agent Evaluation
+
+AiML SuperAgent should be evaluated by operational behavior, not by how impressive the response sounds.
+
+## Evaluation Dimensions
+
+### Context Discipline
+
+Good:
+
+- reads source-of-truth files first
+- searches before loading broad folders
+- avoids generated files and stale logs
+- summarizes long proof output
+
+Bad:
+
+- opens unrelated files
+- loads old notes without checking relevance
+- pastes logs into durable memory
+- assumes the current repo owns production
+
+### Production Awareness
+
+Good:
+
+- verifies live URLs, deployed env names, current schema, or current package versions when relevant
+- distinguishes repo state from production state
+- records the proof after verification
+
+Bad:
+
+- says a change is fixed because code looks right
+- trusts old deployment notes
+- ignores hosted configuration
+
+### Diff Quality
+
+Good:
+
+- small patch
+- no unrelated refactors
+- changed lines trace to the task
+- existing style is preserved
+
+Bad:
+
+- broad cleanup during bug fix
+- rewrites working code without proof
+- changes public behavior outside scope
+
+### Memory Quality
+
+Good:
+
+- records only durable facts
+- marks assumptions
+- archives resolved incidents
+- removes stale facts
+
+Bad:
+
+- notes become a transcript
+- secrets appear in memory
+- temporary guesses become permanent facts
+
+## Simple Scorecard
+
+| Dimension | 0 | 1 | 2 |
+| --- | --- | --- | --- |
+| Context discipline | Loads broadly | Some targeting | Minimal targeted context |
+| Production awareness | Assumes | Checks sometimes | Verifies when live state matters |
+| Diff quality | Broad | Mostly focused | Small and traceable |
+| Memory quality | Noisy | Useful but stale risk | Durable and compressed |
+| Secret safety | Unsafe | Manual caution | Explicit policy and checks |
+
+Target score: 8 or higher out of 10.
+
+## Test Task Pattern
+
+Use tasks that include ambiguity:
+
+```text
+Production route is returning 404. Fix it.
+```
+
+A good agent should:
+
+1. identify the likely route owner
+2. verify production route behavior
+3. inspect only relevant route/config files
+4. patch the smallest diff
+5. build or probe
+6. record the production fact if it changed
+

package/docs/10-adoption-playbook.md

@@ -0,0 +1,62 @@
+# Adoption Playbook
+
+AiML SuperAgent can be adopted gradually.
+
+## Phase 1: Add Operating Files
+
+Add:
+
+- `AGENTS.md`
+- `REPO_SOURCE_OF_TRUTH.json`
+- `WORKING_NOTES.md`
+
+Run:
+
+```bash
+node bin/aiml-superagent.js check .
+```
+
+Replace every placeholder before relying on the output.
+
+## Phase 2: Add Verification
+
+Define the fastest meaningful proof commands:
+
+- typecheck
+- build
+- unit test
+- smoke probe
+- read-only production check
+
+Store them in `REPO_SOURCE_OF_TRUTH.json`.
+
+## Phase 3: Add Deployment Memory
+
+Add:
+
+- `DEPLOYMENT_LOG.md`
+- `SAFE_ENV_AUDIT.md`
+
+Record only verified deployments. Do not record planned deployments as completed.
+
+## Phase 4: Add Tool Adapters
+
+Use adapter files for each assistant:
+
+- `adapters/claude/CLAUDE.md`
+- `adapters/codex/AGENTS.md`
+- `adapters/cursor/rules.md`
+
+Keep the project source of truth centralized. Vendor-specific files should be thin wrappers.
+
+## Phase 5: Maintain Notes
+
+Review notes regularly:
+
+- archive resolved incidents
+- compress long logs
+- remove stale facts
+- mark assumptions explicitly
+
+The framework fails if notes become a junk drawer.
+

package/docs/11-anti-patterns.md

@@ -0,0 +1,85 @@
+# Anti-Patterns
+
+AiML SuperAgent exists to prevent common long-running agent failures.
+
+## Giant Prompt Syndrome
+
+The assistant receives every rule, every note, every log, and every file.
+
+Result:
+
+- slow reasoning
+- higher cost
+- stale assumptions
+- lower precision
+
+Fix:
+
+- read durable memory first
+- search for task-specific context
+- summarize proof output
+
+## Transcript Memory
+
+Working notes become a chronological chat transcript.
+
+Result:
+
+- important facts buried
+- contradictions accumulate
+- old incidents keep resurfacing
+
+Fix:
+
+- record conclusions, not conversations
+- archive resolved incidents
+- mark stale facts
+
+## Production Blindness
+
+The assistant treats the repo as the whole system.
+
+Result:
+
+- wrong backend patched
+- env var mismatch missed
+- hosted config ignored
+- deployment assumed but not verified
+
+Fix:
+
+- verify production reality when live state matters
+- record deploy surfaces
+- keep env audits secret-safe
+
+## Helpful Refactor Drift
+
+The assistant improves adjacent code while fixing a narrow issue.
+
+Result:
+
+- hard-to-review diffs
+- regressions
+- merge conflicts
+
+Fix:
+
+- changed lines must trace to the task
+- mention unrelated cleanup instead of doing it
+
+## Secret Memory
+
+The assistant saves credential values to notes for convenience.
+
+Result:
+
+- leaked secrets
+- unsafe examples
+- polluted commit history
+
+Fix:
+
+- store names and roles only
+- use placeholders
+- run the checker before release
+

package/docs/12-context-budget.md

@@ -0,0 +1,52 @@
+# Context Budget
+
+Context is a budget, not a warehouse.
+
+AiML SuperAgent expects the assistant to spend context deliberately.
+
+## Default Budget
+
+For most tasks:
+
+| Layer | Budget |
+| --- | --- |
+| Operating files | 3 files |
+| Source files | 1 to 6 files |
+| Logs | shortest relevant excerpt |
+| Tests/proof | summarized output |
+| Notes update | only durable facts |
+
+## Escalation
+
+Load more context only when:
+
+- the first targeted search fails
+- the dependency graph requires it
+- tests show a wider regression
+- the user asks for broad review
+- architecture-level changes are explicitly requested
+
+## Compression Rules
+
+Compress before saving:
+
+- logs longer than one screen
+- repeated errors
+- deployment output
+- browser console dumps
+- stack traces after the root cause is known
+
+## Budget Failure Signals
+
+The assistant is likely over budget if it:
+
+- repeatedly reopens the same files
+- references unrelated history
+- edits broad areas without a narrow proof
+- loses track of which repo or deployment is active
+- cannot explain why a file is in context
+
+## Practical Rule
+
+If a file cannot plausibly affect the current task, do not load it yet.
+