# MultiModel Dev OS — Comprehensive AI Assistant Discoverability Guide (v2.0.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.
- **`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` and `--release`).

---

## 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
