multimodel-dev-os 0.3.0

package/.ai/agents/README.md

@@ -0,0 +1,23 @@
+# Agents
+
+> Agent role definitions and orchestration configuration.
+
+## Purpose
+
+This directory defines:
+- Agent roles and their file scopes
+- Orchestration mode (sequential, parallel, supervised)
+- Handoff protocol between agents
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `orchestrator.md` | Multi-agent coordination protocol |
+| `{role-name}.md` | Custom role definitions (optional) |
+
+## Quick Reference
+
+Define agents in root `.ai/config.yaml`, then detail their coordination here.
+
+See `orchestrator.md` for the full protocol spec.

package/.ai/agents/coder.md

@@ -0,0 +1,11 @@
+# Coder Agent Spec
+
+> Responsible for writing clean, structured, and modular implementation code based on an approved plan.
+
+## Focus Areas
+- Enforce strict typing and standard style guides.
+- Avoid introducing unused variables or broken code imports.
+- Make targeted atomic edits instead of rewriting large file sections.
+
+## Primary Tooling
+- IDE agents, code completion engines, or fast edit tools (e.g. Cursor / Claude)

package/.ai/agents/devops.md

@@ -0,0 +1,8 @@
+# DevOps Agent Spec
+
+> Responsible for managing deployment configurations, CI/CD pipelines, container boundaries, server environments, and rollbacks.
+
+## Focus Areas
+- Enforce strict continuous deployment gating.
+- Manage Dockerfiles, container definitions, and cloud config templates safely.
+- Write robust, fail-safe recovery scripts.

package/.ai/agents/multimodel-orchestrator.md

@@ -0,0 +1,105 @@
+# Multimodel Orchestrator Protocol — v0.1
+
+> Specification for coordinating multiple AI coding agents on a single project.
+> v0.1 is a **protocol document** — runtime implementation comes in v0.2+.
+
+## Purpose
+
+When multiple AI tools work on the same codebase, they need:
+1. **Role clarity** — who does what
+2. **File boundaries** — who touches which files
+3. **Session logging** — how to pass context between agents
+4. **Conflict prevention** — avoid stepping on each other's changes
+
+## Agent Roles
+
+Define agents in `.ai/config.yaml`:
+
+```yaml
+orchestrator:
+  agents:
+    - name: "architect"
+      tool: "claude"
+      role: "Design and plan architecture"
+      files: ["docs/**", "AGENTS.md", "MEMORY.md"]
+      permissions: "read+write"
+
+    - name: "implementer"
+      tool: "cursor"
+      role: "Write implementation code"
+      files: ["src/**", "lib/**", "tests/**"]
+      permissions: "read+write"
+
+    - name: "reviewer"
+      tool: "codex"
+      role: "Review code and suggest fixes"
+      files: ["**"]
+      permissions: "read-only"
+```
+
+## Execution Modes
+
+| Mode | Behavior |
+|------|----------|
+| `sequential` | One agent at a time. Session log required between each. |
+| `parallel` | Multiple agents work simultaneously on different file scopes. |
+| `supervised` | Human reviews each agent's output before the next agent starts. |
+
+## Session Log Protocol
+
+When an agent finishes a task, it writes a session log to `.ai/session-logs/`:
+
+### Session Log Format
+
+```markdown
+# Session: {agent_name} → {next_agent}
+
+**Timestamp:** {ISO 8601}
+**Agent:** {tool_name} ({role_name})
+**Mode:** {execution_mode}
+
+## Action Summary
+{What was done in 2-3 sentences}
+
+## Files Changed
+- {path} ({created|modified|deleted})
+
+## Next Steps
+1. {Concrete next action}
+2. {Another action}
+
+## Blockers
+- {Any blockers, or "None"}
+
+## Context for Next Agent
+{Any important context the next agent needs}
+```
+
+### Naming Convention
+
+```
+.ai/session-logs/{YYYY-MM-DD}-{agent}-{summary}.md
+```
+
+Example: `.ai/session-logs/2026-05-30-architect-auth-design.md`
+
+## Conflict Prevention Rules
+
+1. **File scoping:** Agents should only modify files in their defined `files` glob
+2. **Lock files:** If an agent is working on a file, other agents should skip it
+3. **Pull before push:** Always check for changes before committing
+4. **Atomic tasks:** Each agent should complete a coherent unit of work
+
+## Current Limitations (v0.1)
+
+- No runtime enforcement — this is a convention, not a system
+- No automatic conflict detection
+- No agent-to-agent messaging (use session logs)
+- No parallel execution safeguards
+
+## Roadmap
+
+- **v0.2:** CLI that reads config and routes tasks
+- **v0.3:** Automatic session log generation
+- **v0.4:** Conflict detection and resolution
+- **v0.5:** Real-time agent coordination

package/.ai/agents/planner.md

@@ -0,0 +1,11 @@
+# Planner Agent Spec
+
+> Responsible for requirement clarification, researching dependencies, and designing robust step-by-step implementation plans.
+
+## Focus Areas
+- Research before taking action.
+- Outline files to create, modify, or delete.
+- Define a strict verification plan.
+
+## Primary Tooling
+- Reasoning models (e.g. Claude Code / Antigravity with high reasoning)

package/.ai/agents/qa-tester.md

@@ -0,0 +1,8 @@
+# QA Tester Agent Spec
+
+> Responsible for writing comprehensive unit, integration, and E2E test suites, and running regression checks.
+
+## Focus Areas
+- Write unit tests covering Edge Cases.
+- Validate component routing and user experience.
+- Maintain test coverage budgets.

package/.ai/agents/reviewer.md

@@ -0,0 +1,11 @@
+# Reviewer Agent Spec
+
+> Responsible for conducting strict pull request reviews, evaluating diff structures, and finding performance code smells.
+
+## Focus Areas
+- Evaluate security vulnerability risks.
+- Look for resource leaks or inefficient algorithms.
+- Enforce coding rules defined in `AGENTS.md`.
+
+## Primary Tooling
+- Codex / large reasoning review assistants

package/.ai/agents/security-auditor.md

@@ -0,0 +1,8 @@
+# Security Auditor Agent Spec
+
+> Responsible for identifying potential security vulnerabilities, reviewing third-party dependencies for CVE issues, and validating input sanitization.
+
+## Focus Areas
+- Enforce strict input sanitization and parameter encoding.
+- Verify JWT verification, auth scopes, and RBAC rules.
+- Prevent inclusion of plain text keys or secrets.

package/.ai/agents/seo-auditor.md

@@ -0,0 +1,8 @@
+# SEO Auditor Agent Spec
+
+> Responsible for conducting strict audits on HTML structures, metadata tags, heading hierarchies, and validating conformance with search indexing best practices.
+
+## Focus Areas
+- Enforce exactly one main `<h1>` per page.
+- Audit semantic elements hierarchy.
+- Validate open graph/meta title and description formats.

package/.ai/checks/README.md

@@ -0,0 +1,38 @@
+# Checks
+
+> Pre- and post-action checks that agents run before/after critical operations.
+
+## What is a Check?
+
+A check is a markdown file that defines verification steps an agent should run:
+- Before committing code
+- Before deploying
+- After a migration
+- After a dependency update
+
+## Structure
+
+```
+.ai/checks/
+├── README.md            ← You are here
+├── pre-commit.md        ← Example pre-commit check
+└── your-check.md        ← Your custom checks
+```
+
+## Enabling Checks
+
+Set in `.ai/config.yaml`:
+
+```yaml
+checks:
+  pre_commit:
+    enabled: true
+    file: ".ai/checks/pre-commit.md"
+```
+
+## Creating a Check
+
+1. Create a markdown file in this directory
+2. Define the check name, trigger, and steps
+3. Include pass/fail criteria
+4. Reference it in `.ai/config.yaml`

package/.ai/checks/context-budget.md

@@ -0,0 +1,7 @@
+# Context Budget Checks
+
+> Active checks to evaluate token and context window state.
+
+- [ ] Check active files in prompt < 15
+- [ ] Confirm no build outputs or temp files are passed
+- [ ] Active usage of Caveman Mode for bulk refactorings

package/.ai/checks/pre-commit.md

@@ -0,0 +1,8 @@
+# Pre-Commit Checks
+
+> Self-checklist before committing changes.
+
+- [ ] Run linter and verify 0 errors
+- [ ] Run test suite and verify 100% pass
+- [ ] No local machine paths committed
+- [ ] No credentials/secrets in code

package/.ai/checks/pre-deploy.md

@@ -0,0 +1,8 @@
+# Pre-Deploy Checks
+
+> Gating checks prior to deploying to staging/production.
+
+- [ ] All CI pipeline checks pass successfully
+- [ ] Environment variables configured correctly
+- [ ] Database migrations mapped and tested
+- [ ] Rollback recovery script verified

package/.ai/checks/pre-implementation.md

@@ -0,0 +1,7 @@
+# Pre-Implementation Checks
+
+> Self-checklist before modifying codebase files.
+
+- [ ] Clear planning document approved
+- [ ] Understand target file boundaries
+- [ ] Verify test suite works locally before any edits

package/.ai/checks/regression-checklist.md

@@ -0,0 +1,8 @@
+# Regression Checklist
+
+> Procedures to ensure modifications do not disrupt existing application functionality.
+
+- [ ] Check primary user authentication flows
+- [ ] Verify core page loading parameters
+- [ ] Check console log errors
+- [ ] Confirm layout styling holds across sizes

package/.ai/config.yaml

@@ -0,0 +1,60 @@
+# multimodel-dev-os configuration
+# Source of truth for AI operating layer settings
+
+project:
+  name: null                    # Your project name
+  description: null             # One-line description
+  version: null                 # Project version
+
+# Mode: "standard" (full templates) or "caveman" (minimal tokens)
+mode: "standard"
+
+# Orchestrator configuration
+# See .ai/agents/orchestrator.md for full protocol spec
+orchestrator:
+  version: "0.1"
+  mode: "sequential"           # sequential | parallel | supervised
+  session_logs:
+    format: "markdown"
+    location: ".ai/session-logs/"
+    required_fields:
+      - agent_name
+      - timestamp
+      - action_summary
+      - files_changed
+      - next_steps
+
+  agents:
+    - name: "default"
+      tool: "any"
+      role: "General development"
+      files: ["**"]
+      permissions: "read+write"
+
+# Adapter configuration
+# Only enable adapters for tools you use
+adapters:
+  codex: false
+  antigravity: false
+  cursor: false
+  claude: false
+  gemini: false
+  vscode: false
+
+# Checks configuration
+checks:
+  pre_commit:
+    enabled: false
+    file: ".ai/checks/pre-commit.md"
+  post_commit:
+    enabled: false
+    file: null
+
+# Skills
+skills:
+  directory: ".ai/skills/"
+  auto_load: true
+
+# Prompts
+prompts:
+  directory: ".ai/prompts/"

package/.ai/context/README.md

@@ -0,0 +1,18 @@
+# Context
+
+> Shared project context that AI agents read at session start.
+
+## Purpose
+
+Place files here that provide essential background for any AI agent:
+- Architecture decisions not yet in `MEMORY.md`
+- Design documents under active discussion
+- Reference material agents need frequently
+- External specs or API docs relevant to current work
+
+## Guidelines
+
+- Keep files under 200 lines each
+- Use markdown for all context files
+- Remove stale context regularly
+- Prefer structured data (tables, lists) over prose

package/.ai/context/architecture.md

@@ -0,0 +1,15 @@
+# Technical Architecture
+
+> High-level technical architecture, system design, data flows, and tech stack configurations.
+
+## Stack Overview
+- Frontend: `null`
+- Backend: `null`
+- Database: `null`
+- Hosting: `null`
+
+## System Diagram & Data Flow
+`null`
+
+## Key Boundaries & Core Services
+`null`

package/.ai/context/business-rules.md

@@ -0,0 +1,12 @@
+# Business Rules & Domain Logic
+
+> Central rules governing application domain models, logic constraints, workflows, and edge-cases.
+
+## User Constraints & Rules
+- `null`
+
+## Financial & Transactional Rules
+- `null`
+
+## State Transitions & Workflows
+- `null`

package/.ai/context/context-budget.md

@@ -0,0 +1,12 @@
+# Context Budget & Token Management
+
+> Core limits, file exclusion lists, and guidelines to prevent context window saturation and minimize token bloat.
+
+## Rules
+1. Never pass unnecessary build outputs or dependencies (`node_modules`, `.next`, `dist`) to the context.
+2. In large codebases, switch the AI config `mode` to `caveman` to use abbreviated instructions.
+3. Keep logs inside `.ai/session-logs/` pruned or gitignored by default.
+
+## Budgets
+- Target instruction token size: under 1,000 tokens
+- Max active codebase files in context: 15-20 files

package/.ai/context/deployment-rules.md

@@ -0,0 +1,15 @@
+# Deployment Rules & Procedures
+
+> Standard parameters for continuous delivery, deployment gating, production environments, and rollbacks.
+
+## Environments
+- Staging URL: `null`
+- Production URL: `null`
+
+## Build Gating Checks
+- All unit tests must pass
+- Code build must succeed in production bundle mode
+- Lint checks must return 0 errors
+
+## Automated Rollback Criteria
+- `null`

package/.ai/context/model-map.md

@@ -0,0 +1,11 @@
+# Model Map & Capability Routing
+
+> Guidelines mapping specific project features and workflow steps to the best-suited AI coding models.
+
+## Routing Schema
+
+| Model Class | Ideal Tasks | Examples |
+|-------------|-------------|----------|
+| High-Reasoning (e.g. Claude 3.5 Sonnet, GPT-4o) | Planning, Architecture, Refactoring, Complex Logic | Planning a module, multi-file edits |
+| Fast/Token-Minimized (e.g. Gemini Flash, GPT-4o-mini) | Quick Bugfixes, Repetitive edits, Lint fixing, Verification | Fixing single-line errors |
+| Specialized Code Models (e.g. Codex variants) | Review, Inline Completions | PR audits, Doc writing |

package/.ai/context/project-brief.md

@@ -0,0 +1,17 @@
+# Project Brief
+
+> Central description of the project, mission statement, target audience, and key goals.
+
+## Core Purpose
+Provide a single sentence defining the project's primary value proposition.
+`null`
+
+## Target Audience
+- `null`
+
+## Key Business Goals
+1. `null`
+2. `null`
+
+## Success Metrics
+- `null`

package/.ai/context/seo-rules.md

@@ -0,0 +1,15 @@
+# SEO & Semantic HTML Rules
+
+> Standard guidelines for search engine optimization, meta descriptions, page speed parameters, and page structure.
+
+## Document Structure & Heading Rules
+- Ensure exactly one `<h1>` per page.
+- Maintain a proper hierarchy for `<h2>` down to `<h6>`.
+- Use HTML5 semantic elements (`<header>`, `<main>`, `<article>`, `<footer>`).
+
+## Metadata Standards
+- Title tag formatting: `null`
+- Description constraints: `null` (Under 160 characters recommended)
+
+## Performance Metrics
+- Core Web Vitals target: `null`

package/.ai/prompts/README.md

@@ -0,0 +1,37 @@
+# Prompts
+
+> Reusable prompt templates for AI coding agents.
+
+## Purpose
+
+Store prompt templates that agents or humans can reference:
+- Code review prompts
+- Architecture analysis prompts
+- Refactoring prompts
+- Testing strategy prompts
+
+## Format
+
+Each prompt is a markdown file:
+
+```markdown
+# Prompt: {name}
+
+## When to Use
+{Trigger conditions}
+
+## Template
+{The prompt text with {placeholders}}
+
+## Variables
+| Variable | Description |
+|----------|-------------|
+| {project} | Project name |
+```
+
+## Guidelines
+
+- One prompt per file
+- Use `{variable}` syntax for placeholders
+- Keep prompts under 50 lines
+- Name files descriptively: `code-review.md`, `architecture-audit.md`

package/.ai/prompts/generate-tests.md

@@ -0,0 +1,5 @@
+# System Prompt: Generate Tests
+
+> Instructions for drafting high-coverage unit tests and integration suites covering edge cases.
+
+Analyze logic boundaries. Draft assertions covering successful states, empty inputs, null constraints, and failure modes.

package/.ai/prompts/handoff-to-next-model.md

@@ -0,0 +1,5 @@
+# System Prompt: Handoff to Next Model
+
+> Instructions to prepare file indicators and transition details when switching to another agent/model.
+
+Detail current milestone progress. Point the next model/agent specifically to files to work on and next actions.

package/.ai/prompts/implement-safely.md

@@ -0,0 +1,5 @@
+# System Prompt: Implement Safely
+
+> Instructions guiding safe, modular coding with targeted replacements and regression awareness.
+
+Do not rewrite whole files. Target specific line modifications. Enforce lint correctness and run local build verification checks proactively.

package/.ai/prompts/plan-first.md

@@ -0,0 +1,5 @@
+# System Prompt: Plan First
+
+> Instructions to instruct an agent to always draft an implementation plan before writing any code.
+
+Ensure you research the codebase, identify dependencies, list all files to create or modify, outline your verification test cases, and obtain approval before editing files.

package/.ai/prompts/review-diff.md

@@ -0,0 +1,5 @@
+# System Prompt: Review Diff
+
+> Instructions for conducting strict PR diff audits and locating syntax issues or memory leaks.
+
+Inspect git diffs strictly. Identify security flaws, resource leaks, syntax regressions, and deviations from style guidelines.

package/.ai/prompts/summarize-session.md

@@ -0,0 +1,5 @@
+# System Prompt: Summarize Session
+
+> Instructions to generate standardized markdown session summaries under `.ai/session-logs/`.
+
+Summarize what tasks were completed, files changed, blockers remaining, and context required for the next agent session.

package/.ai/session-logs/.gitkeep

@@ -0,0 +1 @@
+

package/.ai/session-logs/README.md

@@ -0,0 +1,49 @@
+# Session Logs
+
+> Agent session logs for tracking work across multi-agent workflows.
+
+## Purpose
+
+When an AI agent completes a session, it can log:
+- What was done
+- What files changed
+- What to do next
+- Any blockers or decisions made
+
+## Format
+
+```markdown
+# Session: {agent_name}
+**Timestamp:** {ISO 8601}
+**Tool:** {tool_name}
+**Role:** {role from .ai/agents/orchestrator.md}
+
+## Summary
+{What was done in 2-3 sentences}
+
+## Files Changed
+- {path} ({created|modified|deleted})
+
+## Next Steps
+1. {Concrete next action}
+
+## Blockers
+- {Any blockers, or "None"}
+```
+
+## Naming Convention
+
+```
+{YYYY-MM-DD}-{agent}-{summary}.md
+```
+
+Example: `2026-05-30-claude-auth-design.md`
+
+## Git Policy
+
+Session logs are **gitignored by default** (session-specific data).
+To commit them, remove the session-logs ignore rule from `.gitignore`.
+
+## Retention
+
+Keep the last 10 session logs. Archive or delete older ones.

package/.ai/skills/README.md

@@ -0,0 +1,34 @@
+# Skills
+
+> Reusable agent skills that extend what AI agents can do in your project.
+
+## What is a Skill?
+
+A skill is a markdown file that teaches an AI agent a specific capability:
+- How to perform a database migration
+- How to set up a new microservice
+- How to run a specific test suite
+- How to deploy to a specific environment
+
+## Structure
+
+Each skill is a markdown file in this directory:
+
+```
+.ai/skills/
+├── README.md              ← You are here
+├── example-skill.md       ← Example template
+├── your-skill-name.md     ← Your custom skills
+└── ...
+```
+
+## Creating a Skill
+
+1. Copy `example-skill.md` as a starting point
+2. Define the skill name, description, and steps
+3. Include any commands, code snippets, or decision trees
+4. Keep skills focused — one skill, one capability
+
+## Loading
+
+When `auto_load: true` in `.ai/config.yaml`, agents read all skills in this directory at session start. Keep the directory small to avoid context bloat.

package/.ai/skills/bug-fix.md

@@ -0,0 +1,9 @@
+# General Bug Fix Skill
+
+> Methodical approach for diagnosing, replicating, fixing, and verifying code issues.
+
+## Protocol
+1. Locate source of the issue using logs or stack trace details.
+2. Replicate the failure locally with a targeted test case.
+3. Apply minimal, precise code edits.
+4. Run validation checks to ensure no regressions are introduced.

package/.ai/skills/caveman-bug-fix.md

@@ -0,0 +1,2 @@
+# caveman-bug-fix
+locate error -> fix -> run tests -> repeat

package/.ai/skills/caveman-context-handoff.md

@@ -0,0 +1,2 @@
+# caveman-context-handoff
+write brief log -> notify next agent

package/.ai/skills/caveman-feature-build.md

@@ -0,0 +1,2 @@
+# caveman-feature-build
+map endpoints -> write components -> verify build