multimodel-dev-os 0.3.0

package/bin/multimodel-dev-os.js

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+
+/**
+ * multimodel-dev-os CLI
+ * Dependency-free local initialization and validation utility.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, statSync } from 'fs';
+import { join, dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const sourceRoot = resolve(__dirname, '..');
+
+let version = '0.3.0';
+try {
+  const pkgData = JSON.parse(readFileSync(resolve(sourceRoot, 'package.json'), 'utf8'));
+  version = pkgData.version;
+} catch (e) {}
+
+const ARGS = process.argv.slice(2);
+
+// Parse parameters manually to avoid external dependencies
+function parseArgs(args) {
+  const params = {
+    command: null,
+    target: process.cwd(),
+    template: 'general-app',
+    adapters: [],
+    caveman: false,
+    dryRun: false,
+    force: false,
+    help: false
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--target' || arg === '-t') {
+      params.target = resolve(args[++i]);
+    } else if (arg === '--template') {
+      params.template = args[++i];
+    } else if (arg === '--adapter' || arg === '-a') {
+      params.adapters.push(args[++i]);
+    } else if (arg === '--caveman') {
+      params.caveman = true;
+    } else if (arg === '--dry-run' || arg === '-d') {
+      params.dryRun = true;
+    } else if (arg === '--force' || arg === '-f') {
+      params.force = true;
+    } else if (arg === '--help' || arg === '-h') {
+      params.help = true;
+    } else if (!params.command && !arg.startsWith('-')) {
+      params.command = arg;
+    }
+  }
+  return params;
+}
+
+const params = parseArgs(ARGS);
+const COMMAND = params.command;
+
+if (params.help || !COMMAND) {
+  showHelp();
+  process.exit(0);
+}
+
+if (COMMAND === 'init') {
+  handleInit(params);
+} else if (COMMAND === 'verify') {
+  handleVerify(params);
+} else {
+  console.error(`\x1b[31mUnknown command: ${COMMAND}\x1b[0m`);
+  showHelp();
+  process.exit(1);
+}
+
+function showHelp() {
+  console.log(`\n🧠 \x1b[36mmultimodel-dev-os CLI v${version}\x1b[0m`);
+  console.log('====================================');
+  console.log('Usage: node bin/multimodel-dev-os.js <command> [options]\n');
+  console.log('Commands:');
+  console.log('  init       Initialize a project with configs and adapters');
+  console.log('  verify     Validate structural integrity of an existing project\n');
+  console.log('Options:');
+  console.log('  -t, --target <path>     Target folder destination (default: current working directory)');
+  console.log('  --template <name>       Template profile: nextjs-saas, wordpress-site, ecommerce-store,');
+  console.log('                          seo-landing-page, general-app (default: general-app)');
+  console.log('  -a, --adapter <name>    Inject specific adapter: codex, antigravity, cursor, claude, gemini, vscode');
+  console.log('  --caveman               Use minimal-token templates (~79% fewer tokens)');
+  console.log('  -d, --dry-run           Preview planned file actions without modifying the filesystem');
+  console.log('  -f, --force             Overwrite existing files without prompting\n');
+}
+
+function handleInit(options) {
+  console.log(`\n\x1b[34mInitializing multimodel-dev-os in: ${options.target}\x1b[0m`);
+  console.log(`Template profile: \x1b[32m${options.template}\x1b[0m`);
+  if (options.caveman) console.log('Bone variant: \x1b[33mCaveman Mode Active\x1b[0m');
+  if (options.dryRun) console.log('\x1b[36mDry Run active - no actual modifications will occur\x1b[0m');
+
+  const operations = [];
+  const conflicts = [];
+
+  // Determine core source files based on template and mode
+  let agentsSrc = join(sourceRoot, 'AGENTS.md');
+  let memorySrc = join(sourceRoot, 'MEMORY.md');
+  let tasksSrc = join(sourceRoot, 'TASKS.md');
+  let runbookSrc = join(sourceRoot, 'RUNBOOK.md');
+  let configSrc = join(sourceRoot, '.ai', 'config.yaml');
+
+  // Load custom template directories if selected
+  if (options.template !== 'general-app') {
+    const templateDir = join(sourceRoot, 'examples', options.template);
+    if (existsSync(templateDir)) {
+      agentsSrc = join(templateDir, 'AGENTS.md');
+      memorySrc = join(templateDir, 'MEMORY.md');
+      configSrc = join(templateDir, '.ai', 'config.yaml');
+    }
+  }
+
+  // Handle Caveman Mode overrides
+  if (options.caveman) {
+    agentsSrc = join(sourceRoot, '.ai', 'templates', 'AGENTS.caveman.md');
+    memorySrc = join(sourceRoot, '.ai', 'templates', 'MEMORY.caveman.md');
+    tasksSrc = join(sourceRoot, '.ai', 'templates', 'TASKS.caveman.md');
+    runbookSrc = join(sourceRoot, '.ai', 'templates', 'RUNBOOK.caveman.md');
+  }
+
+  // 1. Core Root Files
+  operations.push({ dest: 'AGENTS.md', src: agentsSrc });
+  operations.push({ dest: 'MEMORY.md', src: memorySrc });
+  operations.push({ dest: 'TASKS.md', src: tasksSrc });
+  operations.push({ dest: 'RUNBOOK.md', src: runbookSrc });
+  operations.push({ dest: '.ai/config.yaml', src: configSrc });
+
+  // 2. .ai/ Subdirectories & Core Specification Files
+  const aiSubdirs = ['context', 'agents', 'skills', 'prompts', 'checks', 'templates', 'session-logs'];
+  aiSubdirs.forEach(sub => {
+    const srcDir = join(sourceRoot, '.ai', sub);
+    if (existsSync(srcDir)) {
+      readdirSync(srcDir).forEach(file => {
+        operations.push({
+          dest: join('.ai', sub, file),
+          src: join(srcDir, file)
+        });
+      });
+    }
+  });
+
+  // 3. Selected Adapters
+  options.adapters.forEach(adapter => {
+    const adapterDir = join(sourceRoot, 'adapters', adapter);
+    if (existsSync(adapterDir)) {
+      // Helper function to read recursive files in adapter
+      const copyRecursive = (currSrc, currRel) => {
+        if (statSync(currSrc).isDirectory()) {
+          readdirSync(currSrc).forEach(file => {
+            copyRecursive(join(currSrc, file), join(currRel, file));
+          });
+        } else {
+          operations.push({
+            dest: join('adapters', adapter, currRel),
+            src: currSrc
+          });
+        }
+      };
+      readdirSync(adapterDir).forEach(file => {
+        copyRecursive(join(adapterDir, file), file);
+      });
+    } else {
+      console.warn(`\x1b[33mWarning: Adapter '${adapter}' not found. Skipping.\x1b[0m`);
+    }
+  });
+
+  // Check for conflicts
+  operations.forEach(op => {
+    const targetFile = join(options.target, op.dest);
+    if (existsSync(targetFile)) {
+      if (!options.force) {
+        conflicts.push(op.dest);
+      }
+    }
+  });
+
+  if (conflicts.length > 0) {
+    console.error('\n\x1b[31m[ABORT] Overwrite Conflict Detected!\x1b[0m');
+    console.error('The following files already exist in the target directory:');
+    conflicts.forEach(c => console.error(`  - ${c}`));
+    console.error('\nRun command with \x1b[33m--force\x1b[0m to overwrite these files.');
+    process.exit(1);
+  }
+
+  // Execute operations
+  operations.forEach(op => {
+    const targetFile = join(options.target, op.dest);
+    const targetDir = dirname(targetFile);
+
+    if (options.dryRun) {
+      console.log(`  \x1b[36m[DRY-RUN] WOULD CREATE:\x1b[0m ${op.dest}`);
+    } else {
+      if (!existsSync(targetDir)) {
+        mkdirSync(targetDir, { recursive: true });
+      }
+      const data = readFileSync(op.src);
+      writeFileSync(targetFile, data);
+      console.log(`  \x1b[32mCREATE:\x1b[0m ${op.dest}`);
+    }
+  });
+
+  console.log(`\n\x1b[32m✔ Project initialized successfully! [Total Operations: ${operations.length}]\x1b[0m\n`);
+}
+
+function handleVerify(options) {
+  console.log(`\n\x1b[34mRunning strict verification in: ${options.target}\x1b[0m\n`);
+
+  let passed = 0;
+  let failed = 0;
+
+  const assertFile = (relPath) => {
+    const fullPath = join(options.target, relPath);
+    if (existsSync(fullPath) && statSync(fullPath).isFile()) {
+      console.log(`  \x1b[32m✓\x1b[0m ${relPath}`);
+      passed++;
+    } else {
+      console.error(`  \x1b[31m✗ ${relPath} (missing)\x1b[0m`);
+      failed++;
+    }
+  };
+
+  // 1. Core Files
+  const rootFiles = ['AGENTS.md', 'MEMORY.md', 'TASKS.md', 'RUNBOOK.md', '.ai/config.yaml'];
+  rootFiles.forEach(assertFile);
+
+  // 2. .ai/context
+  const contextFiles = [
+    '.ai/context/project-brief.md',
+    '.ai/context/architecture.md',
+    '.ai/context/business-rules.md',
+    '.ai/context/seo-rules.md',
+    '.ai/context/deployment-rules.md',
+    '.ai/context/model-map.md',
+    '.ai/context/context-budget.md'
+  ];
+  contextFiles.forEach(assertFile);
+
+  // 3. .ai/agents
+  const agentFiles = [
+    '.ai/agents/multimodel-orchestrator.md',
+    '.ai/agents/planner.md',
+    '.ai/agents/coder.md',
+    '.ai/agents/reviewer.md',
+    '.ai/agents/qa-tester.md',
+    '.ai/agents/security-auditor.md',
+    '.ai/agents/seo-auditor.md',
+    '.ai/agents/devops.md'
+  ];
+  agentFiles.forEach(assertFile);
+
+  console.log('\n=====================================');
+  if (failed > 0) {
+    console.error(`  \x1b[31mVerification FAILED. [Passed: ${passed}, Failed: ${failed}]\x1b[0m\n`);
+    process.exit(1);
+  } else {
+    console.log(`  \x1b[32mVerification PASSED. [All ${passed} files present]\x1b[0m\n`);
+    process.exit(0);
+  }
+}

package/docs/adapters.md

@@ -0,0 +1,79 @@
+# Adapter Guide
+
+> How to create, maintain, and contribute adapters for AI coding tools.
+
+## What is an Adapter?
+
+An adapter translates the root `AGENTS.md` source of truth into a tool's native configuration format. It does **not** contain original instructions — it references the root files.
+
+## Adapter Structure
+
+```
+adapters/{tool-name}/
+├── {tool-native-file}     # e.g., CLAUDE.md, .cursorrules
+├── setup.md               # Human-readable setup guide
+└── {config-files}         # Optional tool-native config
+```
+
+## Creating a New Adapter
+
+### Step 1: Research the Tool
+
+- What file(s) does the tool auto-detect? (e.g., `CLAUDE.md`, `.cursorrules`)
+- Where does it expect config files? (e.g., `.vscode/`, `.gemini/`)
+- What format does it use? (markdown, JSON, YAML, plain text)
+
+### Step 2: Create the Adapter Directory
+
+```bash
+mkdir -p adapters/your-tool/
+```
+
+### Step 3: Create the Native File
+
+Start with this template:
+
+```markdown
+<!-- AUTO-GENERATED REFERENCE — Source of truth: /AGENTS.md -->
+<!-- Do not edit this file directly. Edit /AGENTS.md and re-sync. -->
+
+# {Tool Name} Agent Instructions
+
+This project uses multimodel-dev-os.
+Full instructions: /AGENTS.md
+
+## Tool-Specific Notes
+{What's unique about this tool's behavior}
+
+## References
+- /AGENTS.md
+- /MEMORY.md
+```
+
+### Step 4: Create `setup.md`
+
+Include:
+- Overview (1 paragraph)
+- Setup steps (numbered list)
+- How it works (brief explanation)
+- Tips (3-5 bullets)
+- Troubleshooting table
+
+### Step 5: Submit a PR
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md).
+
+## Maintaining Adapters
+
+- When a tool changes its config format, update the adapter
+- Test adapter files with the actual tool before submitting
+- Keep adapter files under 50 lines — they're references, not full configs
+- Version adapter changes in `CHANGELOG.md`
+
+## Adapter Best Practices
+
+1. **Never duplicate** instructions from `AGENTS.md`
+2. **Always reference** root files with absolute paths (`/AGENTS.md`)
+3. **Include only** tool-specific overrides or behavior notes
+4. **Test with the actual tool** — don't guess at file detection behavior
+5. **Document quirks** — if a tool has unusual behavior, note it in `setup.md`

package/docs/architecture.md

@@ -0,0 +1,64 @@
+# Architecture
+
+## Design Principles
+
+1. **Markdown-first** — all configuration is human-readable markdown or YAML
+2. **Vendor-neutral** — no tool is the source of truth; the root files are
+3. **Zero dependencies** — no runtime, no package manager, no build step
+4. **Non-destructive** — installers never overwrite, adapters never conflict
+5. **Progressive complexity** — start with `AGENTS.md`, add orchestrator later
+
+## Layer Architecture
+
+```
+┌──────────────────────────────────────┐
+│          Human Layer                 │
+│   README.md  CONTRIBUTING.md  docs/  │
+├──────────────────────────────────────┤
+│        Source of Truth Layer         │
+│  AGENTS.md  MEMORY.md  TASKS.md     │
+│  RUNBOOK.md                         │
+├──────────────────────────────────────┤
+│        AI Operating Layer            │
+│  .ai/config.yaml                    │
+│  .ai/agents/multimodel-orchestrator.md│
+│  .ai/context/  .ai/prompts/          │
+│  .ai/skills/  .ai/checks/           │
+│  .ai/session-logs/  .ai/templates/  │
+├──────────────────────────────────────┤
+│         Adapter Layer                │
+│  adapters/codex/                    │
+│  adapters/antigravity/              │
+│  adapters/cursor/                   │
+│  adapters/claude/                   │
+│  adapters/gemini/                   │
+│  adapters/vscode/                   │
+└──────────────────────────────────────┘
+```
+
+## Data Flow
+
+1. **User edits** root markdown files (`AGENTS.md`, etc.)
+2. **Adapters read** from root files and translate to tool-native format
+3. **AI agents** read their adapter file + root files
+4. **Agents write** results back to `TASKS.md`, `MEMORY.md`, and session logs
+5. **Orchestrator** coordinates multi-agent workflows via session logs
+
+## File Ownership
+
+| File | Owner | Who Reads | Who Writes |
+|------|-------|-----------|------------|
+| `AGENTS.md` | Human | All agents | Human |
+| `MEMORY.md` | Shared | All agents | Human + agents |
+| `TASKS.md` | Shared | All agents | Human + agents |
+| `RUNBOOK.md` | Human | All agents | Human |
+| `.ai/config.yaml` | Human | System | Human |
+| `.ai/session-logs/*.md` | Agents | Next agent | Current agent |
+| `adapters/*/` | Community | Specific tool | Maintainers |
+
+## Security Considerations
+
+- Never store secrets in any multimodel-dev-os file
+- Handoff logs may contain sensitive context — gitignored by default
+- Adapter config files should not contain API keys or tokens
+- Use `.env` files (gitignored) for secrets, referenced in `RUNBOOK.md`

package/docs/caveman-mode.md

@@ -0,0 +1,74 @@
+# Caveman Mode
+
+> Cut ~79% of tokens from your AI context without losing functionality.
+
+## Why Caveman Mode?
+
+AI agents consume tokens for every file they read. In large projects, context windows fill up fast. Caveman Mode provides stripped-down templates that preserve structure but eliminate:
+
+- Comments and explanations
+- Examples and sample data
+- Verbose headers
+- Decorative whitespace
+
+## Token Budget
+
+| File | Standard | Caveman | Savings |
+|------|----------|---------|---------|
+| `AGENTS.md` | ~500 tokens | ~120 tokens | 76% |
+| `MEMORY.md` | ~400 tokens | ~80 tokens | 80% |
+| `TASKS.md` | ~300 tokens | ~60 tokens | 80% |
+| `RUNBOOK.md` | ~400 tokens | ~80 tokens | 80% |
+| **Total** | **~1,600** | **~340** | **~79%** |
+
+## How to Use
+
+### Fresh Install
+
+```bash
+curl -fsSL .../install.sh | bash -s -- --caveman
+```
+
+### Convert Existing Project
+
+Replace root files with caveman variants:
+```bash
+cp .ai/templates/AGENTS.caveman.md AGENTS.md
+cp .ai/templates/MEMORY.caveman.md MEMORY.md
+cp .ai/templates/TASKS.caveman.md TASKS.md
+cp .ai/templates/RUNBOOK.caveman.md RUNBOOK.md
+```
+
+Update config:
+```yaml
+# .ai/config.yaml
+mode: "caveman"
+```
+
+### Switch Back to Standard
+
+```bash
+# Re-download standard templates
+curl -fsSL .../AGENTS.md -o AGENTS.md
+# Or restore from git
+git checkout -- AGENTS.md MEMORY.md TASKS.md RUNBOOK.md
+```
+
+## Caveman Writing Rules
+
+If you're writing your own caveman-style files:
+
+1. No comments — every token must be actionable
+2. No examples — agents know common patterns
+3. No headers longer than 3 words
+4. No blank lines between sections
+5. Use abbreviations: `dev`, `deps`, `cfg`, `env`
+6. Use `null` for missing values
+7. Tables over prose — always
+
+## When NOT to Use Caveman Mode
+
+- New projects where you need detailed templates as guides
+- Teams where multiple humans need to read the files
+- When you have plenty of context window budget
+- When onboarding new team members who need explanations

package/docs/cli-roadmap.md

@@ -0,0 +1,44 @@
+# CLI Roadmap
+
+> The local `node bin/multimodel-dev-os.js` CLI tool is fully implemented in v0.2.0!
+
+## Current CLI Usage
+
+```bash
+# Initialize project with configurations
+node bin/multimodel-dev-os.js init
+
+# Initialize with specific template and adapters
+node bin/multimodel-dev-os.js init --template nextjs-saas --adapter cursor --adapter claude
+
+# Run dry-run preview
+node bin/multimodel-dev-os.js init --dry-run
+
+# Force overwrite existing files
+node bin/multimodel-dev-os.js init --force
+
+# Check structural health of target directory
+node bin/multimodel-dev-os.js verify
+```
+
+## CLI Roadmap & Commands Status
+
+| Command | Purpose | Target Version | Status |
+|---------|---------|----------------|--------|
+| `init` | Scaffold multimodel-dev-os into a project | v0.2.0 | ✅ Completed |
+| `verify` | Check that all required files exist and are valid | v0.2.0 | ✅ Completed |
+| `sync` | Regenerate adapter files from root AGENTS.md | v0.3.0 | 📋 Planned |
+| `add-adapter` | Add a new adapter to the project | v0.3.0 | 📋 Planned |
+
+## Requirements Completed in v0.2.0
+
+- [x] `package.json` with `bin` entry
+- [x] CLI argument parser (implemented purely with Node.js built-ins)
+- [x] Template profile injection (Next.js SaaS, WordPress, etc.)
+- [x] Conflict protection and `--force` overrides
+- [x] Dry-run preview mode
+- [x] Tested on Node 18+ and Windows/macOS/Linux
+
+## Future Releases (v0.3.0+)
+- Publish package to npm as `multimodel-dev-os` to support `npx` execution.
+- Implement the `sync` subcommand to parse custom override markers inside adapters and align them with changes in root instructions.

package/docs/faq.md

@@ -0,0 +1,66 @@
+# FAQ
+
+## General
+
+**What is multimodel-dev-os?**
+A set of markdown files and conventions that let multiple AI coding tools
+(Codex, Cursor, Claude, Gemini, Antigravity, VS Code) share the same
+project context. Not a runtime. Not an AI agent. Think `.editorconfig`
+but for AI tools.
+
+**Is this an operating system?**
+No. "Dev OS" is a metaphor for the shared operating layer between tools.
+It's just markdown files in your repo.
+
+**What does "multimodel" mean?**
+Multiple AI models/tools working on the same project.
+Not "multimodal" (multiple input types like text + image).
+
+## Setup
+
+**Do I need Node.js?**
+No. The installer scripts use bash or PowerShell only.
+`package.json` is included for metadata and future CLI support.
+
+**Can I use just one AI tool?**
+Yes. Use a single adapter. The multi-agent features are optional.
+
+**Which files are required?**
+At minimum: `AGENTS.md`. Everything else is optional.
+The installer creates the full structure, but you can delete what you
+don't need.
+
+## Adapters
+
+**Do I copy adapter files to my project root?**
+Yes, for tools that auto-detect specific files:
+- Cursor → copy `.cursorrules` to root
+- Claude → copy `CLAUDE.md` to root
+- VS Code → copy `.vscode/` to root
+
+**My tool isn't listed. Can I add one?**
+Yes. See [docs/adapters.md](adapters.md) for the guide. PRs welcome.
+
+**Will adapters break if a tool changes its config format?**
+Possibly. Adapters are community-maintained. File an issue if you
+notice an adapter is outdated.
+
+## Caveman Mode
+
+**When should I use Caveman Mode?**
+When your context window is tight, your model is small, or you're
+optimizing for API cost. It cuts ~79% of tokens.
+
+**Can I mix standard and caveman files?**
+Yes. Each file is independent. You could have a standard `AGENTS.md`
+and a caveman `TASKS.md`.
+
+## Orchestrator
+
+**Does the orchestrator run agents automatically?**
+No, not in v0.1. It's a protocol spec — conventions for how agents
+should coordinate. Runtime orchestration is planned for v0.2+.
+
+**Do I need the orchestrator for single-agent workflows?**
+No. The orchestrator is only relevant when multiple agents work
+on the same codebase.

package/docs/installers.md

@@ -0,0 +1,58 @@
+# Installers
+
+## Overview
+
+Cross-platform scripts that scaffold multimodel-dev-os into any project. Located in `scripts/`.
+
+## Usage
+
+### macOS / Linux / WSL (`install.sh`)
+
+```bash
+# Standard install (interactive adapter selection)
+curl -fsSL https://raw.githubusercontent.com/rizvee/multimodel-dev-os/main/scripts/install.sh | bash
+
+# Caveman Mode (minimal tokens)
+curl -fsSL https://raw.githubusercontent.com/rizvee/multimodel-dev-os/main/scripts/install.sh | bash -s -- --caveman
+
+# All adapters, no prompts
+curl -fsSL https://raw.githubusercontent.com/rizvee/multimodel-dev-os/main/scripts/install.sh | bash -s -- --all
+
+# Dry run (preview only)
+curl -fsSL https://raw.githubusercontent.com/rizvee/multimodel-dev-os/main/scripts/install.sh | bash -s -- --dry-run
+```
+
+### Windows (`install.ps1`)
+
+```powershell
+# Standard install
+irm https://raw.githubusercontent.com/rizvee/multimodel-dev-os/main/scripts/install.ps1 | iex
+
+# With flags (download first, then run)
+Invoke-WebRequest -Uri "https://raw.githubusercontent.com/rizvee/multimodel-dev-os/main/scripts/install.ps1" -OutFile install.ps1
+.\install.ps1 -Caveman -All
+```
+
+## Flags
+
+| Flag | Bash | PowerShell | Effect |
+|------|------|------------|--------|
+| Caveman Mode | `--caveman` | `-Caveman` | Install minimal-token templates |
+| All adapters | `--all` | `-All` | Skip adapter selection prompt |
+| Dry run | `--dry-run` | `-DryRun` | Preview without creating files |
+| Help | `--help` | `-Help` | Show usage information |
+
+## Behavior
+
+- **Non-destructive** — never overwrites existing files by default.
+- **CLI-integrated** — bundles our zero-dependency CLI `bin/multimodel-dev-os.js` script so you can perform advanced target-directory routing and local schema verifications after installation.
+- **Selective** — choose which adapters to install.
+- **Offline-safe** — fails gracefully if downloads fail.
+
+## What Gets Created
+
+The installer creates:
+1. Root files: `AGENTS.md`, `MEMORY.md`, `TASKS.md`, `RUNBOOK.md`
+2. Core configuration utilities: `.gitattributes` (enforces LF line endings) and `bin/multimodel-dev-os.js` CLI
+3. `.ai/` directory with config, skills, checks, templates
+4. Selected adapter directories under `adapters/`