multimodel-dev-os 0.3.0

package/docs/multimodel-workflow.md

@@ -0,0 +1,121 @@
+# Orchestrator Guide
+
+> How to coordinate multiple AI coding agents on a single project.
+
+## Overview
+
+The Multimodel Orchestrator defines how different AI agents share work, avoid conflicts, and hand off context. In v0.1, it's a **protocol specification** — a set of conventions your team follows manually.
+
+## Quick Start
+
+### 1. Define Roles
+
+Edit `.ai/config.yaml`:
+
+```yaml
+orchestrator:
+  mode: "sequential"
+  agents:
+    - name: "planner"
+      tool: "claude"
+      role: "Architecture and planning"
+      files: ["docs/**", "AGENTS.md", "MEMORY.md"]
+      permissions: "read+write"
+
+    - name: "builder"
+      tool: "cursor"
+      role: "Implementation"
+      files: ["src/**", "lib/**", "tests/**"]
+      permissions: "read+write"
+
+    - name: "checker"
+      tool: "codex"
+      role: "Code review and testing"
+      files: ["**"]
+      permissions: "read-only"
+```
+
+### 2. Choose a Mode
+
+| Mode | How It Works | Best For |
+|------|-------------|----------|
+| `sequential` | One agent at a time, session log between each | Solo devs switching tools |
+| `parallel` | Multiple agents on different file scopes | Teams with clear boundaries |
+| `supervised` | Human reviews between each agent | Critical/production code |
+
+### 3. Use Handoff Logs
+
+When switching from one agent to another, the outgoing agent writes a session log:
+
+```markdown
+# Handoff: planner → builder
+
+**Timestamp:** 2026-05-30T12:00:00Z
+**Agent:** Claude (planner)
+
+## Action Summary
+Designed the auth module with JWT tokens and refresh token rotation.
+
+## Files Changed
+- docs/auth-design.md (created)
+- TASKS.md (updated)
+
+## Next Steps
+1. Implement /auth/login endpoint
+2. Implement /auth/refresh endpoint
+
+## Blockers
+- Need to decide: Redis vs PostgreSQL for refresh token storage
+```
+
+Save to: `.ai/session-logs/2026-05-30-planner-auth-design.md`
+
+## Common Workflows
+
+### Solo Dev, Multiple Tools
+
+```
+Morning:  Claude (architecture) → session log
+Afternoon: Cursor (implementation) → session log
+Evening:  Codex (review) → session log
+```
+
+### Pair: Human + AI
+
+```
+Human: writes TASKS.md with requirements
+Agent: reads TASKS.md, implements, updates MEMORY.md
+Human: reviews, provides feedback
+Agent: iterates, writes session log
+```
+
+### Team: Multiple Humans + Multiple AIs
+
+```
+Dev A + Claude: works on auth module (src/auth/**)
+Dev B + Cursor: works on dashboard (src/dashboard/**)
+Both: read shared MEMORY.md, coordinate via TASKS.md
+```
+
+## Conflict Prevention
+
+1. **Define file scopes** — each agent role specifies which files it can touch
+2. **Check before writing** — agents should read `TASKS.md` and recent session logs first
+3. **Atomic tasks** — each agent completes a coherent unit before handing off
+4. **Single writer** — only one agent should modify a given file at a time
+
+## Limitations (v0.1)
+
+- Manual enforcement only — no runtime checks
+- No automatic conflict detection
+- No real-time agent-to-agent messaging
+- Handoff logs must be written manually by the agent
+
+## Roadmap
+
+| Version | Feature |
+|---------|---------|
+| v0.2 | CLI reads config and routes tasks |
+| v0.3 | Automatic session log generation |
+| v0.4 | Conflict detection |
+| v0.5 | Real-time coordination |

package/docs/npm-publishing.md

@@ -0,0 +1,74 @@
+# npm & npx Publishing Guide
+
+> Operational runbook for packaging, testing, publishing, and maintaining the `multimodel-dev-os` package on the public npm registry.
+
+---
+
+## 1. Local Packaging Integrity Test
+
+Before publishing, always test the built package locally by compiling a compressed tarball:
+
+1. **Build the local tarball archive:**
+   ```bash
+   npm pack
+   ```
+   This creates a file named like `multimodel-dev-os-0.1.0.tgz` in your directory root.
+
+2. **Verify bundle contents:**
+   Create an empty temporary workspace, extract the tarball, and confirm that only required scaffold folders are included (no `.github/`, test configurations, or local system files):
+   ```bash
+   mkdir -p /tmp/package-test && cd /tmp/package-test
+   tar -xzf /path/to/multimodel-dev-os-0.1.0.tgz
+   ls -la package/
+   ```
+
+3. **Verify CLI execution from the package:**
+   ```bash
+   node package/bin/multimodel-dev-os.js --help
+   ```
+
+---
+
+## 2. Pre-Flight Publishing Checklist
+
+Execute these validation actions strictly in sequence before triggering a release:
+
+1. **Verify structural health:**
+   Ensure all 96 file assertions in our verification script pass successfully:
+   ```bash
+   npm run verify
+   ```
+
+2. **Login to npm secure registry:**
+   ```bash
+   npm login
+   ```
+
+3. **Dry-run packaging audit:**
+   Inspect final bundle metrics and check for unexpected files:
+   ```bash
+   npm publish --dry-run
+   ```
+
+4. **Trigger publication:**
+   Once metadata and file exclusions are verified:
+   ```bash
+   npm publish --access public
+   ```
+
+---
+
+## 3. Versioning & Rollback Strategy
+
+* **Semantic Versioning (SemVer) Discipline:**
+  * **Patch Release (e.g. 0.3.1):** Backward-compatible bug fixes or documentation updates.
+  * **Minor Release (e.g. 0.4.0):** Backward-compatible new features (like new adapter sync mechanisms).
+  * **Major Release (e.g. 1.0.0):** Breaking changes to core specification files.
+
+* **Rollback & Deprecation Guidelines:**
+  * Since published versions cannot be republished or overwritten, **never unpublish** unless absolutely necessary.
+  * If a critical bug is discovered, immediately publish a new patch version (e.g. `v0.3.1`).
+  * If a version is broken, flag it as deprecated to inform downstream installers:
+    ```bash
+    npm deprecate multimodel-dev-os@0.3.0 "Critical bug found, please use v0.3.1 instead."
+    ```

package/docs/quickstart.md

@@ -0,0 +1,85 @@
+# Quickstart
+
+Get multimodel-dev-os into your project in under 2 minutes.
+
+## Option A: One-Line Install
+
+**macOS / Linux / WSL (bash):**
+```bash
+curl -fsSL https://raw.githubusercontent.com/rizvee/multimodel-dev-os/main/scripts/install.sh | bash
+```
+
+**Windows (PowerShell):**
+```powershell
+irm https://raw.githubusercontent.com/rizvee/multimodel-dev-os/main/scripts/install.ps1 | iex
+```
+
+## Option B: Manual Scaffolding
+
+```bash
+git clone https://github.com/rizvee/multimodel-dev-os.git /tmp/mmdos
+cp /tmp/mmdos/AGENTS.md    your-project/
+cp /tmp/mmdos/MEMORY.md    your-project/
+cp /tmp/mmdos/TASKS.md     your-project/
+cp /tmp/mmdos/RUNBOOK.md   your-project/
+cp /tmp/mmdos/.gitattributes your-project/
+cp -r /tmp/mmdos/.ai       your-project/
+```
+
+## Option C: Caveman Mode (Minimal Tokens)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/rizvee/multimodel-dev-os/main/scripts/install.sh | bash -s -- --caveman
+```
+
+## Option D: Node.js CLI Scaffolding (v0.2.0+)
+
+For a direct, highly customized local setup using our zero-dependency CLI utility:
+1. Clone this repository locally:
+   ```bash
+   git clone https://github.com/rizvee/multimodel-dev-os.git
+   ```
+2. Run the CLI to scaffold into your target project:
+   ```bash
+   node bin/multimodel-dev-os.js init --target /path/to/your-project --template nextjs-saas --adapter cursor
+   ```
+
+## Option E: npx Scaffolding (Planned v0.3.0+)
+
+Once published to the public npm registry, you can initialize any project globally without local clones using:
+```bash
+# General setup
+npx multimodel-dev-os init
+
+# Target specific layouts and templates
+npx multimodel-dev-os init --template nextjs-saas --adapter cursor
+```
+
+## After Install
+
+1. **Edit `AGENTS.md`** — fill in your project name, stack, and build commands
+2. **Edit `.ai/config.yaml`** — enable adapters for your tools
+3. **Copy adapter files** to your project root:
+   - Cursor: `cp adapters/cursor/.cursorrules .cursorrules`
+   - Claude: `cp adapters/claude/CLAUDE.md CLAUDE.md`
+   - VS Code: `cp -r adapters/vscode/.vscode/ .vscode/`
+4. **Start coding** — your AI tools will read the shared config
+
+## Verify
+
+You can run our strict verification script to validate structural health:
+```bash
+# Via CLI
+node bin/multimodel-dev-os.js verify --target /path/to/your-project
+
+# Via verification shell script
+bash scripts/verify.sh
+```
+
+## Next Steps
+
+- [Architecture overview](architecture.md)
+- [Adapter setup](adapters.md)
+- [Multi-agent workflows](multimodel-workflow.md)
+- [Caveman Mode](caveman-mode.md)
+- [NPM Publishing Runbook](npm-publishing.md)

package/docs/testing-v0.2.md

@@ -0,0 +1,73 @@
+# multimodel-dev-os v0.2.0 Testing Documentation
+
+This document describes how to execute local test cases to verify the `bin/multimodel-dev-os.js` CLI tool and installer scripts.
+
+---
+
+## 1. Platform Requirements
+* **Node.js:** v18.0.0 or higher.
+* **Unix-like Shell (Git Bash, macOS Terminal, Linux Bash):** Required for executing `.sh` scripts.
+* **Windows PowerShell:** Required for executing `.ps1` scripts.
+
+---
+
+## 2. CLI Validation Tests
+
+### Test Case A: Help Command
+Ensures the argument parser and help outputs render correctly.
+```bash
+# Git Bash / macOS / Linux / PowerShell
+node bin/multimodel-dev-os.js --help
+```
+* **Expected Output:** Displays correct option flags, commands (`init`, `verify`), and versions.
+
+### Test Case B: Structural Verification Check
+Verifies structural presence of 20 critical files inside the repository.
+```bash
+# Git Bash / macOS / Linux / PowerShell
+node bin/multimodel-dev-os.js verify
+```
+* **Expected Output:** Outputs `✓` indicators for each file and returns a `PASSED` status with exit code `0`.
+
+### Test Case C: Dry-Run Scaffolding Check
+Validates loading of custom templates (e.g. `nextjs-saas`) and adapter boundaries without actual writes.
+```bash
+# Git Bash / macOS / Linux / PowerShell
+node bin/multimodel-dev-os.js init --target ./test-project --template nextjs-saas --adapter cursor --dry-run
+```
+* **Expected Output:** Outputs 61 `[DRY-RUN] WOULD CREATE` operation logs and a final `Project initialized successfully!` success message.
+
+### Test Case D: Conflict Prevention Check
+Verifies that the CLI protects existing files from overwrites.
+```bash
+# 1. Create a dummy file
+mkdir -p test-conflict && touch test-conflict/AGENTS.md
+
+# 2. Run init without force
+node bin/multimodel-dev-os.js init --target ./test-conflict
+```
+* **Expected Output:** Safely aborts, prints a red `CONFLICT` warning, and exits with code `1`.
+
+### Test Case E: Overwrite Override Check
+Verifies that `--force` successfully bypasses conflict protection.
+```bash
+# Run init with force
+node bin/multimodel-dev-os.js init --target ./test-conflict --force
+```
+* **Expected Output:** Overwrites conflicting files and completes successfully.
+
+---
+
+## 3. Script Installer Validation Tests
+
+### macOS / Linux / WSL (bash):
+```bash
+# Run dry-run installation
+bash scripts/install.sh --dry-run
+```
+
+### Windows (PowerShell):
+```powershell
+# Run dry-run installation
+.\scripts\install.ps1 -DryRun
+```

package/examples/ecommerce-store/.ai/config.yaml

@@ -0,0 +1,4 @@
+version: "0.1"
+project:
+  name: "ecommerce-headless-store"
+  mode: "standard"

package/examples/ecommerce-store/AGENTS.md

@@ -0,0 +1,5 @@
+# E-commerce Store — Agent Instructions
+
+project: ecommerce-headless-store
+stack: React, Next.js, Shopify Storefront API, Tailwind CSS
+description: High-performance headless e-commerce store implementation

package/examples/ecommerce-store/MEMORY.md

@@ -0,0 +1,4 @@
+# E-commerce Store — Memory
+
+## Architecture Decisions
+- Integrated static generation ISR for product details pages.

package/examples/general-app/.ai/config.yaml

@@ -0,0 +1,4 @@
+version: "0.1"
+project:
+  name: "general-project-template"
+  mode: "standard"

package/examples/general-app/AGENTS.md

@@ -0,0 +1,5 @@
+# General App — Agent Instructions
+
+project: general-project-template
+stack: Multi-stack
+description: Generic scaffolding for general software projects

package/examples/general-app/MEMORY.md

@@ -0,0 +1,4 @@
+# General App — Memory
+
+## Architecture Decisions
+- Configured modular abstraction layers for generic project support.

package/examples/nextjs-saas/.ai/config.yaml

@@ -0,0 +1,4 @@
+version: "0.1"
+project:
+  name: "nextjs-saas-starter"
+  mode: "standard"

package/examples/nextjs-saas/AGENTS.md

@@ -0,0 +1,13 @@
+# Next.js SaaS — Agent Instructions
+
+project: nextjs-saas-starter
+stack: Next.js 14 (App Router), TypeScript, Tailwind CSS, Prisma, PostgreSQL, Stripe
+description: Subscription-based software-as-a-service application template
+
+## Build Commands
+```
+dev:   npm run dev
+build: npm run build
+test:  npm run test
+lint:  npm run lint
+```

package/examples/nextjs-saas/MEMORY.md

@@ -0,0 +1,5 @@
+# Next.js SaaS — Memory
+
+## Architecture Decisions
+- Decided to use Next-Auth with JWT session strategy.
+- Stripe Webhook events are processed asynchronously in route handlers.

package/examples/seo-landing-page/.ai/config.yaml

@@ -0,0 +1,4 @@
+version: "0.1"
+project:
+  name: "marketing-landing-page"
+  mode: "caveman"

package/examples/seo-landing-page/AGENTS.md

@@ -0,0 +1,5 @@
+# SEO Landing Page — Agent Instructions
+
+project: marketing-landing-page
+stack: HTML5, CSS3, Vanilla JS
+description: Fast, high-conversion static landing page optimized for Core Web Vitals

package/examples/seo-landing-page/MEMORY.md

@@ -0,0 +1,5 @@
+# SEO Landing Page — Memory
+
+## key-patterns
+- Strictly matching exactly one main header rules.
+- Fast interactive element parameters.

package/examples/wordpress-site/.ai/config.yaml

@@ -0,0 +1,4 @@
+version: "0.1"
+project:
+  name: "custom-wordpress-theme"
+  mode: "standard"

package/examples/wordpress-site/AGENTS.md

@@ -0,0 +1,5 @@
+# WordPress Site — Agent Instructions
+
+project: custom-wordpress-theme
+stack: PHP, WordPress Core, MySQL, Sass, Webpack
+description: Custom theme design and plugin configuration for enterprise website

package/examples/wordpress-site/MEMORY.md

@@ -0,0 +1,4 @@
+# WordPress Site — Memory
+
+## Key Decisions
+- Standardized custom post types for "Events" and "News" services.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "multimodel-dev-os",
+  "version": "0.3.0",
+  "bin": {
+    "multimodel-dev-os": "bin/multimodel-dev-os.js"
+  },
+  "description": "Portable, vendor-neutral AI Dev OS for multi-agent coding workflows",
+  "keywords": [
+    "ai",
+    "agents",
+    "coding",
+    "multi-agent",
+    "developer-tools",
+    "agents-md",
+    "ai-dev-os"
+  ],
+  "homepage": "https://github.com/rizvee/multimodel-dev-os",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rizvee/multimodel-dev-os.git"
+  },
+  "license": "MIT",
+  "author": "rizvee",
+  "type": "module",
+  "files": [
+    "AGENTS.md",
+    "MEMORY.md",
+    "TASKS.md",
+    "RUNBOOK.md",
+    ".ai/",
+    "adapters/",
+    "scripts/",
+    "docs/",
+    "examples/",
+    "bin/"
+  ],
+  "scripts": {
+    "verify": "bash scripts/verify.sh",
+    "test:cli": "node bin/multimodel-dev-os.js verify",
+    "pack:template": "bash scripts/pack-template.sh",
+    "pack": "bash scripts/pack-template.sh"
+  }
+}