# MultiModel Dev OS — Comprehensive AI Assistant Discoverability Guide (v2.6.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 & Modules (.ai/)                │
│ context/ • agents/ • skills/ • prompts/ • checks/      │
└──────────────────────────┬─────────────────────────────┘
                           │ Routes files dynamically
┌──────────────────────────▼─────────────────────────────┐
│ LAYER 3: 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 <adapter>`: Show rules diff between bundled template and target root file.
  - `sync <adapter|all>`: 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.
- **`verify`**: Automated release script that checks structure integrity.
- **`templates`**: Lists built-in template profiles (supports overrides via `--registry <path>`).
- **`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/
- **GitHub Codebase**: https://github.com/rizvee/multimodel-dev-os
- **v2.0.0 Roadmap**: https://rizvee.github.io/multimodel-dev-os/v2-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
