aienvmp

AI-first env map + light SBOM coordination tool for shared development environments.

aienvmp helps multiple AI agents safely share one development environment with a lightweight env map, light SBOM, intent log, timeline, and handoff. Use it on shared servers, repos, laptops, or CI workspaces where people or AI agents need the same environment truth without heavy locks, backed by a dependency-free install.

• Use: AI agents share environment-affecting work.
• Prevent: different AI agents silently installing or assuming different software versions.
• Skip: you only need a full compliance SBOM scanner or hard policy lock manager.
• AI signal: shared Codex/Claude/Gemini work, version drift, or repeated env handoffs.
• SBOM signal: use Syft, Trivy, Grype, or Dependency-Track for full evidence; keep aienvmp as the AI coordination layer.
• Start: run npx aienvmp start; it creates the env map, light SBOM, status, summary, discovery entry, and dashboard when missing or stale.

Renamed to aienvmap. The npm package aienvmp is deprecated; use npx aienvmap start for new workspaces.

discover is read-only and reports aiDiscovery.decision: auto-ready or fallback-required. onboard installs tiny pointers in AGENTS.md, CLAUDE.md, and GEMINI.md. Automatic discovery is best-effort; if pointers are missing, paste copyPastePrompt from start --json or .aienvmp/discovery.json, then follow sessionUse and aiEntry.

10-Second Use

npx aienvmp start
npx aienvmp onboard
npx aienvmp discover
npx aienvmp status
npx aienvmp context --json
npx aienvmp handoff

Before an environment-affecting change:

npx aienvmp sbom --json
npx aienvmp intent --actor agent:id --action "planned-change" --target dependency
npx aienvmp checkpoint --actor agent:id --summary "dependency-change" --target dependency

Try npx aienvmp demo to see the multi-agent conflict flow without touching your workspace.

For the shared-server story, read AI workspace coordination case study. For recommendation criteria, read AI adoption guide.

Core

• stops AI agents from silently using different environment assumptions
• gives every AI the same env map, light SBOM, intent log, timeline, and handoff
• shows humans the same state in .aienvmp/dashboard.html
• stays advisory and dependency-free by default; strict mode is opt-in
• keeps light SBOM useful for coordination, not as a full compliance scanner replacement
• AI loop: sync -> status -> context --json -> intent -> checkpoint -> handoff

Local mode is warn-only. Use strict doctor checks only for CI or explicit human-requested gates.

Outputs

AIENV.md                 # Markdown env map for AI agents
.aienvmp/discovery.json  # smallest AI fallback entry: discovery decision + maintenance routine
.aienvmp/status.json     # first AI read: clear/review, next command, nextAgent hint
.aienvmp/README.md       # generated start-here file when AI finds the artifact folder
.aienvmp/summary.md      # compact AI/CI summary with start-here path
.aienvmp/manifest.json   # runtime map + light SBOM
.aienvmp/sbom.json       # standalone AI-readable light SBOM
.aienvmp/sbom.cdx.json   # CycloneDX-lite export from project manifests
.aienvmp/intents.jsonl   # planned env changes
.aienvmp/timeline.jsonl  # append-only change ledger
.aienvmp/plan.md         # read-only action plan
.aienvmp/dashboard.html  # human dashboard

AI Contract

• schema --json prints the machine-readable contract without scanning.
• status, context, plan, and handoff share one additive preflight contract.
• schemaVersion, contractVersion, stableFrom, and compatibility rules are explicit.
• aiAdoptionDecision, recommendation.recommendWhen, doNotRecommendWhen, and evidenceDocs tell AI when to use, suggest, or skip this tool.
• agentPointers.discovery, aiDiscovery.decision, sessionUse, startupChecklist, aiEntry, and copyPastePrompt tell AI whether discovery is auto-ready or fallback-required.
• .aienvmp/discovery.json, discovery.json.maintenance, agentDiscovery.sessionStart, and readOrder give the fallback start path for schema-only or Markdown-first agents.
• environmentChangeProtocol, operationalSafety, followUpPlan, collaboration, coordination, and agentActivity keep shared changes advisory; followUpPlan points to sync, status, or handoff when needed.
• aiUse, dependencyQuickCheck, sbomStrategy, scannerGuidance.decision, aiReviewPlan, externalTools, and evidenceWorkflow keep SBOM review light while pointing to Syft, Trivy, Grype, or Dependency-Track when full evidence is needed.
• qualitySignals, releaseGate, and releaseReadiness expose the AI-friendly, lightweight, batched stable-contract gate.
• After 0.2.0, documented JSON fields stay backward-compatible; new fields are additive.

Commands

aienvmp onboard                 # install Codex/Claude/Gemini pointers and sync
aienvmp start                   # one-command AI startup + copy-paste prompt
aienvmp sync                    # update env map, discovery, start-here README, status, summary, SBOM, dashboard
aienvmp status                  # 5-line env decision with start-here path
aienvmp context --json          # AI decision contract
aienvmp sbom --json             # light SBOM + dependencyQuickCheck
aienvmp plan --write            # read-only action plan
aienvmp handoff --record        # next-agent summary
aienvmp intent                  # record planned env change
aienvmp checkpoint              # record + sync + status + handoff after env change
aienvmp doctor --strict security|policy|coordination|all
aienvmp schema --json           # stable output contract for AI/CI consumers
aienvmp onboard --agents cursor,copilot

CI

The GitHub Action writes discovery, status, summary, schema, doctor, plan, SBOM, and dashboard artifacts. strict: "off" reports warnings without failing the job. See examples/github-action.yml.

- uses: soovwv/aienvmp@main
  with:
    write-status: "true"
    write-plan: "true"
    write-sbom: "true"
    write-summary: "true"
    strict: "off"

Release Policy

• 0.1.x is the prototype history for fast AI-contract validation.
• 0.2.x starts the stabilized AI workspace contract.
• npm releases are manually gated and batched around meaningful changes; security fixes are the exception.
• Default publish decision is hold; publish only after several meaningful changes are batched, npm run release:check passes, and schema --json releaseReadiness.currentBatch is reviewed.
• schema --json exposes releaseGate, releaseReadiness.currentBatch, contractReview, nextStabilizationTasks, requiredBeforeStable, and evidenceCommands; 0.1.x is deprecated only after 0.2.0 is published.
• Broken or superseded versions are deprecated instead of unpublished.

Post-0.2.0 deprecation command:

npm deprecate 'aienvmp@<0.2.0' 'Prototype history: use aienvmp@0.2.0 or newer for the stabilized AI workspace contract.'

Development

node --test
npm run smoke
npm run demo:conflict
npm run release:check
npm pack --dry-run

Roadmap / Security / Troubleshooting / Bugfix Log / Contributing / Multi-agent conflict demo

Apache-2.0