# MultiModel Dev OS — Comprehensive AI Assistant Discoverability Guide (v3.5.0 Stable Release) MultiModel Dev OS is a repository-level porting specification designed to align context and instructions across diverse developer tools and AI models. --- ## 1. Core Architecture Layers The protocol decouples the centralized workspace context from the individual tool rules: ``` ┌────────────────────────────────────────────────────────┐ │ LAYER 1: Root Contracts (Single Source of Truth) │ │ AGENTS.md • MEMORY.md • TASKS.md • RUNBOOK.md │ │ (And central registries under .ai/models/ & .ai/adps/) │ └──────────────────────────┬─────────────────────────────┘ │ Centralizes project context ┌──────────────────────────▼─────────────────────────────┐ │ LAYER 2: Configuration & Intelligence (.ai/) │ │ context/ • agents/ • skills/ • prompts/ • checks/ │ └──────────────────────────┬─────────────────────────────┘ │ Routes files dynamically ┌──────────────────────────▼─────────────────────────────┐ │ LAYER 3: Engine Workflows & Safety Gates │ │ onboard • adapter sync • improve • verify doctor │ └──────────────────────────┬─────────────────────────────┘ │ Runs compliance checkups ┌──────────────────────────▼─────────────────────────────┐ │ LAYER 4: Tool & IDE Adapters │ │ .cursorrules • CLAUDE.md • .vscode/ • .gemini/ • etc. │ └────────────────────────────────────────────────────────┘ ``` ### Layer 1: Root Documents - **`AGENTS.md`**: Defines teams, capabilities, boundaries, and model instructions. - **`MEMORY.md`**: Holds architectural decisions, repository milestones, and tech stacks. - **`TASKS.md`**: Active backlog tracking items. - **`RUNBOOK.md`**: Operational verification commands and post-deployment routines. --- ## 2. CLI Command Specifications All compliant MultiModel Dev OS CLIs strictly enforce the following command contracts: - **`init`**: Scaffolds the standard `.ai/` context configuration directories. Supports `--template`, `--caveman`, `--adapter`, and dynamic registries mapping. - **`status`**: Displays a compact project intelligence dashboard summarizing package details, frameworks, memory freshness, feedback logs, improvement proposals, and audit execution metrics. - **`scan`**: Performs a read-only codebase scan to detect frameworks, package managers, MultiModel Dev OS configurations, and potential context-bloat or security risks. - **`onboard`**: Safely integrates MultiModel Dev OS into existing repositories. Subcommands: - `analyze`: Scans repository structure, frameworks, languages, and risk markers. Read-only. - `recommend`: Runs scanner diagnostics and recommendations for templates and adapters. Read-only. - `plan`: Generates onboarding plan `.ai/intelligence/onboarding.plan.json` and report `.ai/intelligence/onboarding.report.md`. Read-only. - `apply`: Copies configuration templates to target directory. Overwrites require `--force` and automatically generate backups. - `status`: Show progress and completeness percentage dashboard. - **`adapter`**: Manage and sync rule/settings files for IDE adapters. Subcommands: - `status`: Show rules files status and enable/disable states from config. - `diff `: Show rules diff between bundled template and target root file. - `sync `: Synchronizes rule files (requires `--approved`). Overwrites require `--force` and automatically generate backups. - **`memory`**: Compiles or reviews codebase hash-compressed memory. Subcommands: - `build`: Scans target codebase and writes memory metadata to `.ai/intelligence/memory.hash.json` and `.ai/intelligence/memory.summary.md`. - `refresh`: Incremental update comparing changed file hashes to update the memory files. - `diff`: Prints added, removed, or changed files compared to `memory.hash.json` without executing writes. - **`feedback`**: Manage developer feedback loops. Subcommands: - `add`: Logs raw developer feedback to `feedback-log.jsonl`. - `list`: Lists logged feedback entries. - `summarize`: Compiles feedback entries into `learning-rules.md`. - **`improve`**: Manage codebase self-improvement proposals. Subcommands: - `propose`: Scans context and writes a proposal file under `.ai/proposals/`. - `review`: Lists proposals and their active statuses. - `status`: Shows aggregates of proposal statuses. - `validate`: Validate proposal safety gates and operations block. - `diff`: Preview proposed changes in unified diff format without modifying files. - `apply`: Deterministically apply approved operations to the target codebase (requires `--approved`). - `log`: Display Applied Proposals Audit Log execution history. - **`workflow`**: Orchestrate read-only development workflows (list, show, plan, run). Steps are restricted to safe, non-destructive CLI functions. - **`handoff`**: Compile token-compressed session context (build, show) at `.ai/intelligence/handoff.md` to transfer state to a new agent or model session. - **`dashboard`** (alias **`ui`**): Launches the zero-dependency interactive TUI dashboard. Automatically falls back to a clean list of equivalent commands when stdin/stdout are non-TTY. - **`plugin`**: Manage declarative plugins. Subcommands: - `list`: Lists installed plugins. - `show `: Shows detailed capabilities and safety notes of the plugin. - `validate `: Validates a YAML config file against the plugin JSON schema. - `install `: Previews file copy actions, and copies them to whitelisted paths under `.ai/` or `adapters/` if `--approved` is specified. - `status`: Audits target directory to ensure all declared plugin assets are present. - **`catalog`**: Manage the local Workflow Marketplace & Plugin Catalog. Subcommands: - `list`: Lists all catalog plugins (supports `--category`). - `search `: Case-insensitively searches catalog plugins. - `show `: Displays catalog plugin metadata and file previews. - `categories`: Lists all unique categories in the catalog. - `recommend`: Scans repo signals to recommend matching catalog plugins. - `install `: Installs a catalog plugin to the target repo (requires `--approved`). - `status`: Audits installation status of catalog entries. - **`registry`**: Manage trusted remote catalog registries (v3.0.0+). Subcommands: - `list`: Lists all configured registry sources from `sources.yaml`. - `add `: Adds a new remote registry source (requires `--approved`). - `remove `: Removes a registry source and its cache (requires `--approved`). - `sync `: Fetches remote `catalog.yaml` and `manifest.json` into `.ai/registry-cache//` (requires `--approved`). - `status`: Shows all sources, sync timestamps, cache health, and policy status. - `verify `: Verifies SHA256 checksums of cached files against `checksums.json`. - `show `: Shows detailed metadata and policies of a specific registry source. - `cache clear`: Deletes all files in `.ai/registry-cache/` (requires `--approved`). - `trust list`: Lists trusted publisher keys. - `trust show `: Shows details of a specific trusted key. - **`verify`**: Automated release script that checks structure integrity. - **`templates`**: Lists built-in template profiles (supports overrides via `--registry `). - **`validate`**: Strict Quality Gate checking the layout rules on disk (supports `--all-registries`). - **`validate-template`**: Scans a template registry entry and source directory structure for completeness. - **`validate-adapter`**: Audits an adapter config file and directory setup compliance. - **`validate-skill`**: Checks a custom skill file against standard Markdown headers. - **`doctor`**: Advisory checkup auditing ignored folders and token footprint (supports `--tokens`, `--release`, `--intelligence`, and `--onboarding`). --- ## 3. Registries & Mappings ### Model Compatibility Registry Central registry configuration resides in `.ai/models/`: * `registry.yaml`: Maps model aliases to official provider IDs, context windows, and tiers. * `providers.yaml`: API base urls and environment variables keys. * `routing-presets.yaml`: Multi-model presets for task-oriented routing. * `local-models.yaml`: Endpoint mappings for offline model engines (Ollama, Llama.cpp). ### IDE/Agent Adapters Registry Central adapter rules mapped under `.ai/adapters/registry.yaml`: * Targets files like `.cursorrules`, `CLAUDE.md`, `.vscode/settings.json`, `.clinerules`, `.aider.conf.yml`, `.windsurfrules`, `.continue/config.json`. --- ## 4. Key Context Optimization (Caveman Mode) Toggling **Caveman Mode** dynamically reduces system prompt instructions to highly-optimized shorthand symbols, reducing rule tokens footprint by **~79%** for low-cost token execution budgets: ```bash npx multimodel-dev-os@latest init --caveman ``` --- ## 5. Canonical Links - **Documentation site**: https://rizvee.github.io/multimodel-dev-os/ - **Guided Demo Workflows**: https://rizvee.github.io/multimodel-dev-os/demos/ - **GitHub Codebase**: https://github.com/rizvee/multimodel-dev-os - **v3.0.0 Roadmap**: https://rizvee.github.io/multimodel-dev-os/v3-roadmap - **Release Policies**: https://rizvee.github.io/multimodel-dev-os/release-policy - **Upgrade Playbook**: https://rizvee.github.io/multimodel-dev-os/migration-guide - **Model Compatibility**: https://rizvee.github.io/multimodel-dev-os/model-compatibility - **Security Threat Model**: https://rizvee.github.io/multimodel-dev-os/security-threat-model - **v3.5.0 Release Readiness**: https://rizvee.github.io/multimodel-dev-os/v3.5.0-readiness