chati-dev 2.1.0 → 3.0.0

package/framework/constitution.md

@@ -368,6 +368,18 @@ The orchestrator SHALL select the optimal AI model for each agent to balance qua
 
 8. Model selections are logged in session.yaml under `model_selections[]` for cost tracking and optimization.
 
+9. Four provider categories are recognized for multi-CLI execution:
+   - **claude**: Primary provider. Deep reasoning, complex analysis, code generation. Full hook support, MCP support.
+   - **gemini**: Large-context provider. Codebase analysis, discovery, document review. 1M token context window. Full hook support, MCP support.
+   - **codex**: Rapid-coding provider. Fast code generation, sandbox execution. No hook support, MCP support.
+   - **copilot**: Multi-model provider. Reads CLAUDE.md, GEMINI.md, and AGENTS.md natively. Full hook support, MCP support.
+
+10. Claude is the default and primary provider. Multi-CLI is opt-in via `config.yaml` `providers` section. When only `claude` is enabled, the system behaves identically to v2.x.
+
+11. Provider assignments per agent are defined in `config.yaml` under `agent_overrides`. When no override exists, the agent uses the primary provider.
+
+12. For providers without hook support (e.g., codex), governance is enforced by prompt injection — the PRISM context block is embedded in the prompt rather than injected via hooks. This provides softer but functional governance.
+
 **Enforcement: GUIDE** — Model recommendations are advisory in IDE mode; automatic in SDK mode.
 
 ---
@@ -402,5 +414,58 @@ The system SHALL support two execution modes that govern the degree of human inv
 
 ---
 
-*Chati.dev Constitution v2.1.0 — 17 Articles + Preamble*
+## Article XVIII: Execution Profile Governance
+
+The system SHALL support three execution profiles that govern the degree of confirmation required for agent actions. Profiles are orthogonal to mode governance (Article XI) — modes control WHERE agents can write; profiles control WHETHER confirmation is required.
+
+1. Three profiles are recognized:
+   - **explore**: Read-only mode. Agents analyze, investigate, and suggest but perform NO write operations. Useful for safe discovery and analysis.
+   - **guided**: Default profile. Agents propose actions and wait for user confirmation before writes. Balances safety with productivity.
+   - **autonomous**: Full autonomy. Agents execute without confirmation when quality gate scores meet thresholds. Requires cumulative gate scores >= 90%.
+
+2. The default profile is `guided`. Profile selection is stored in `session.yaml` under `execution_profile`.
+
+3. Profile transitions are logged in `session.yaml` under `profile_transitions[]` for audit trail.
+
+4. Certain operations ALWAYS require confirmation regardless of profile:
+   - Destructive operations (file deletion, database drops, force push)
+   - Deployment to production environments
+   - Deviation protocol activation
+   - Backward pipeline transitions (build → planning)
+
+5. The `autonomous` profile is gated by quality: it can only be activated when the most recent QA gate score is >= 90%. If quality drops below threshold during autonomous execution, the system SHALL automatically downgrade to `guided`.
+
+6. The `explore` profile is available at any pipeline position and does not affect mode governance. An agent in `planning` mode with `explore` profile can read any file but write to none.
+
+**Enforcement: BLOCK** — Write operations in `explore` profile are rejected. Autonomous mode without qualifying gate scores is rejected.
+
+---
+
+## Article XIX: Multi-CLI Governance
+
+When multiple CLI providers are enabled, the system SHALL coordinate agent execution across providers while maintaining governance consistency.
+
+1. The CLI Provider Registry (`packages/chati-dev/src/terminal/cli-registry.js`) is the source of truth for provider capabilities: command syntax, model flags, stdin support, hook support, MCP support, and context file format.
+
+2. The handoff format is provider-agnostic. All agents, regardless of which CLI executes them, produce handoffs in the same two-layer format (Article VIII). This ensures seamless inter-provider communication.
+
+3. Provider availability SHALL be validated by the health check engine before spawning. If a configured provider is unavailable, the system SHALL fall back to the primary provider (claude) with a warning.
+
+4. Context file generation is automatic. When a provider is enabled in `config.yaml`, the installer SHALL generate the corresponding context file (GEMINI.md for gemini, AGENTS.md for codex) derived from CLAUDE.md content.
+
+5. Hook-based governance (constitution-guard, mode-governance, read-protection) applies ONLY to providers with hook support. For providers without hooks, equivalent governance is enforced via prompt injection — the PRISM context block includes governance directives.
+
+6. The orchestrator SHALL select the optimal provider for each agent based on:
+   a. Agent's provider preference (defined in agent Identity section)
+   b. Project-level overrides (config.yaml `agent_overrides`)
+   c. Provider availability (health check)
+   d. Fallback: primary provider (claude)
+
+7. Cost tracking SHALL include provider information. Each model selection entry in session.yaml includes: provider, model, agent, timestamp, and estimated token usage.
+
+**Enforcement: GUIDE** — Provider selection is advisory. The system falls back gracefully when providers are unavailable.
+
+---
+
+*Chati.dev Constitution v3.0.0 — 19 Articles + Preamble*
 *All agents are bound by this Constitution. Violations are enforced per article.*

package/framework/domains/agents/brownfield-wu.yaml

@@ -47,3 +47,7 @@ rules:
   - id: bf-05
     text: "MUST assess technical debt and provide risk scores in wu-report.yaml"
     priority: normal
+
+  # Provider Preference (v3.0.0)
+  - wu-provider: "Default provider: claude. Gemini recommended for large codebases (>100K LOC) due to 1M context window."
+    priority: normal

package/framework/domains/agents/dev.yaml

@@ -47,3 +47,7 @@ rules:
   - id: dev-iterate
     text: "Iterate on implementation until acceptance criteria are met."
     priority: normal
+
+  # Provider Preference (v3.0.0)
+  - dev-provider: "Default provider: claude. Can run on gemini for large codebase tasks (1M context window)."
+    priority: normal

package/framework/domains/agents/orchestrator.yaml

@@ -47,3 +47,11 @@ rules:
   - id: orch-session
     text: "Persist all state changes to session.yaml immediately."
     priority: high
+
+  # Provider Routing (v3.0.0)
+  - provider-routing: "Select optimal provider for each agent based on: agent preference, project overrides, provider availability, fallback to primary."
+    priority: high
+  - provider-health: "Validate provider availability via health check before spawning agent terminals."
+    priority: high
+  - provider-command: "/chati providers lists all enabled providers and their status."
+    priority: normal

package/framework/domains/constitution.yaml

@@ -79,3 +79,31 @@ rules:
   - id: art-xvii
     text: "Execution mode governance: autonomous requires gate >= 90%. Safety net with circuit breaker (3 failures)."
     priority: critical
+
+articles:
+  article-xviii:
+    name: "Execution Profile Governance"
+    enforcement: block
+    rules:
+      - profile-explore: "In explore profile, agents read and analyze only. No write operations permitted."
+        priority: critical
+      - profile-guided: "In guided profile, agents propose actions and wait for user confirmation before writes."
+        priority: high
+      - profile-autonomous: "In autonomous profile, agents execute without confirmation when gate scores >= 90%."
+        priority: critical
+      - profile-always-confirm: "Destructive operations, deployments, deviations, and backward transitions always require confirmation regardless of profile."
+        priority: critical
+  article-xix:
+    name: "Multi-CLI Governance"
+    enforcement: guide
+    rules:
+      - provider-registry: "CLI Provider Registry is source of truth for provider capabilities."
+        priority: high
+      - provider-agnostic-handoff: "Handoff format is provider-agnostic. All agents produce handoffs in the same two-layer format."
+        priority: critical
+      - provider-fallback: "If a configured provider is unavailable, fall back to primary provider (claude) with warning."
+        priority: high
+      - provider-hooks: "Hook-based governance applies only to providers with hook support. Others use prompt injection."
+        priority: high
+      - provider-context-files: "Context file generation is automatic when a provider is enabled."
+        priority: normal

package/framework/domains/global.yaml

@@ -18,6 +18,26 @@ rules:
     text: "Interact with user in their preferred language. Artifacts stay in English."
     priority: normal
 
+  # Execution Profile Rules (v3.0.0)
+  execution-profiles:
+    - explore-readonly: "In explore profile, all write/edit tool calls are blocked."
+      priority: critical
+    - guided-confirmation: "In guided profile, significant writes require user confirmation."
+      priority: high
+    - autonomous-gate-check: "Autonomous profile requires cumulative gate scores >= 90%."
+      priority: critical
+    - profile-downgrade: "If quality drops below threshold during autonomous execution, auto-downgrade to guided."
+      priority: critical
+
+  # Multi-CLI Rules (v3.0.0)
+  multi-cli:
+    - primary-provider: "Claude is the default and primary provider. Multi-CLI is opt-in."
+      priority: high
+    - provider-validation: "Health check validates provider availability before spawning."
+      priority: high
+    - provider-model-map: "Each provider has its own model map. Agent assignments reference tier (opus/sonnet/haiku) which maps to provider-specific models."
+      priority: normal
+
 modes:
   planning:
     writeScope: "chati.dev/"

package/framework/hooks/model-governance.js

@@ -27,19 +27,19 @@ import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 
 const AGENT_MODELS = {
-  orchestrator: 'sonnet',
-  'greenfield-wu': 'haiku',
-  'brownfield-wu': 'opus',
-  brief: 'sonnet',
-  detail: 'opus',
-  architect: 'opus',
-  ux: 'sonnet',
-  phases: 'sonnet',
-  tasks: 'sonnet',
-  'qa-planning': 'opus',
-  'qa-implementation': 'opus',
-  dev: 'opus',
-  devops: 'sonnet',
+  orchestrator: { provider: 'claude', model: 'sonnet', tier: 'sonnet' },
+  'greenfield-wu': { provider: 'claude', model: 'haiku', tier: 'haiku' },
+  'brownfield-wu': { provider: 'claude', model: 'opus', tier: 'opus' },
+  brief: { provider: 'claude', model: 'sonnet', tier: 'sonnet' },
+  detail: { provider: 'claude', model: 'opus', tier: 'opus' },
+  architect: { provider: 'claude', model: 'opus', tier: 'opus' },
+  ux: { provider: 'claude', model: 'sonnet', tier: 'sonnet' },
+  phases: { provider: 'claude', model: 'sonnet', tier: 'sonnet' },
+  tasks: { provider: 'claude', model: 'sonnet', tier: 'sonnet' },
+  'qa-planning': { provider: 'claude', model: 'opus', tier: 'opus' },
+  'qa-implementation': { provider: 'claude', model: 'opus', tier: 'opus' },
+  dev: { provider: 'claude', model: 'opus', tier: 'opus' },
+  devops: { provider: 'claude', model: 'sonnet', tier: 'sonnet' },
 };
 
 /**
@@ -77,11 +77,13 @@ async function main() {
     const agent = getCurrentAgent(projectDir);
 
     if (agent && AGENT_MODELS[agent]) {
-      const expected = AGENT_MODELS[agent];
+      const assignment = AGENT_MODELS[agent];
+      const expected = assignment.model || assignment;
+      const provider = assignment.provider || 'claude';
       // Advisory note — appended to context
       process.stdout.write(JSON.stringify({
         result: 'allow',
-        prefix: `<!-- [Article XVI] Agent "${agent}" assigned model: ${expected} -->`,
+        prefix: `<!-- [Article XVI] Agent "${agent}" assigned model: ${expected} (provider: ${provider}) -->`,
       }));
     } else {
       process.stdout.write(JSON.stringify({ result: 'allow' }));

package/framework/intelligence/context-engine.md

@@ -161,3 +161,32 @@ If Smart Continuation is insufficient, the orchestrator spawns a new session:
 ---
 
 *Context Engine v1.0 — Chati.dev Intelligence Layer*
+
+---
+
+## Multi-CLI Context Strategy (v3.0.0)
+
+When agents execute on different CLI providers, context injection adapts to the provider's capabilities:
+
+### Hook-Based Providers (Claude Code, Gemini CLI, Copilot CLI)
+- PRISM context injected via `UserPromptSubmit` hook
+- Mode governance enforced via `PreToolUse` hook
+- Constitution guard enforced via `PreToolUse` hook
+- Full governance parity with Claude Code
+
+### Prompt-Based Providers (Codex CLI)
+- PRISM context embedded directly in the spawned prompt (via prompt-builder)
+- Governance directives included as system instructions in the prompt
+- Softer enforcement — relies on model compliance rather than hook interception
+- Write scope restrictions communicated via prompt, not blocked at tool level
+
+### Context File Mapping
+| Provider | Context File | Generation |
+|----------|-------------|------------|
+| Claude Code | CLAUDE.md | Native (already exists) |
+| Gemini CLI | GEMINI.md | Auto-generated from CLAUDE.md |
+| Codex CLI | AGENTS.md | Auto-generated from CLAUDE.md |
+| Copilot CLI | All three | Reads CLAUDE.md, GEMINI.md, AGENTS.md natively |
+
+### Cross-Provider Handoff
+Handoff format is identical regardless of which provider executed the agent. The two-layer structure (Article VIII) ensures any provider can read any handoff. Session state in `.chati/session.yaml` is the single source of truth — all providers read from and write to the same session file.

package/framework/intelligence/memory-layer.md

@@ -185,3 +185,20 @@ This prevents cross-contamination while enabling knowledge sharing.
 ---
 
 *Memory Layer v1.0 — Chati.dev Intelligence Layer*
+
+---
+
+## Cross-CLI Memory Persistence (v3.0.0)
+
+Memory is provider-agnostic. All providers read from and write to the same memory store (`.chati/memories/`).
+
+### Memory Capture Across Providers
+- **Hook-based providers**: Capture via `PreCompact` hook (session-digest.js)
+- **Prompt-based providers**: Capture via explicit instructions in the spawned prompt — the agent is instructed to output a `<chati-memory>` block that the orchestrator parses from stdout
+
+### Memory Injection Across Providers
+- **Hook-based providers**: Injected via PRISM engine hook (prism-engine.js)
+- **Prompt-based providers**: Relevant memories are included in the spawned prompt by the prompt-builder
+
+### Gotchas Auto-Capture
+Gotchas are captured regardless of provider. The auto-capture engine monitors agent stdout for error patterns and tracks frequency. When an error pattern appears 3+ times across any provider combination, a gotcha is auto-created.

package/framework/orchestrator/chati.md

@@ -45,10 +45,15 @@ Before determining state, check if the user passed a subcommand:
   -> Resume session with full context recovery
   -> Re-activate session lock
 
+/chati providers:
+  -> Display enabled providers and per-agent overrides (see Provider Routing section)
+  -> Stay locked
+
 /chati help:
   -> Display available commands:
      /chati              Start or resume session
      /chati status       Show project dashboard
+     /chati providers    List enabled providers and overrides
      /chati resume       Resume from continuation file
      /chati exit         Save and exit session
      /chati help         Show this help
@@ -338,20 +343,20 @@ Model selection is **enforced by construction**: the orchestrator passes `--mode
 
 ### Model Map (Quick Reference)
 
-| Agent | Default | Upgrade Condition |
-|-------|---------|-------------------|
-| greenfield-wu | haiku | sonnet if multi-stack or enterprise |
-| brownfield-wu | opus | no downgrade |
-| brief | sonnet | opus if enterprise or 10+ integrations |
-| detail | opus | no downgrade |
-| architect | opus | no downgrade |
-| ux | sonnet | opus if design system from scratch |
-| phases | sonnet | opus if 20+ requirements |
-| tasks | sonnet | opus if 50+ tasks |
-| qa-planning | opus | no downgrade |
-| dev | opus | no downgrade |
-| qa-implementation | opus | no downgrade |
-| devops | sonnet | opus if multi-environment or IaC |
+| Agent | Default | Upgrade Condition | Provider |
+|-------|---------|-------------------|----------|
+| greenfield-wu | haiku | sonnet if multi-stack or enterprise | claude (default) |
+| brownfield-wu | opus | no downgrade | claude (default) | gemini (when codebase > 100K LOC) |
+| brief | sonnet | opus if enterprise or 10+ integrations | claude (default) |
+| detail | opus | no downgrade | claude (default) |
+| architect | opus | no downgrade | claude (default) |
+| ux | sonnet | opus if design system from scratch | claude (default) |
+| phases | sonnet | opus if 20+ requirements | claude (default) |
+| tasks | sonnet | opus if 50+ tasks | claude (default) |
+| qa-planning | opus | no downgrade | claude (default) |
+| dev | opus | no downgrade | claude (default) | gemini (when large codebase tasks) |
+| qa-implementation | opus | no downgrade | claude (default) |
+| devops | sonnet | opus if multi-environment or IaC | claude (default) |
 
 ### Enforcement
 
@@ -383,6 +388,81 @@ model_selections:
 
 ---
 
+## Provider Routing
+
+The orchestrator selects the optimal provider for each agent based on the task context, codebase characteristics, and configuration. Provider routing determines WHICH CLI or API backend executes the agent, while model selection determines WHICH model runs within that provider.
+
+### Provider Selection Priority
+
+```
+Resolution order (highest to lowest priority):
+  1. agent_overrides (config.yaml) — explicit per-agent provider override
+  2. Agent default (AGENT_MODELS map) — provider defined in agent Identity section
+  3. Primary provider — the project-level default provider (claude)
+
+Example resolution:
+  config.yaml has: agent_overrides.brownfield-wu.provider = gemini
+  Agent default has: Provider: claude (default) | gemini (when codebase > 100K LOC)
+  Primary provider: claude
+
+  -> Result: gemini (config.yaml override wins)
+
+If no override exists and no agent default specifies a condition match:
+  -> Result: claude (primary provider fallback)
+```
+
+### Provider Fallback
+
+```
+If the selected provider is unavailable (CLI not installed, API unreachable, auth failure):
+  1. Log the failure:
+     provider_fallback:
+       agent: {name}
+       intended_provider: {selected}
+       fallback_provider: claude
+       reason: "{error_message}"
+       timestamp: "{now}"
+  2. Fall back to the primary provider (claude)
+  3. Continue agent execution with fallback provider
+  4. Record the fallback in session.yaml for audit
+
+The primary provider (claude) is always the last-resort fallback.
+Provider fallback NEVER blocks the pipeline — it degrades gracefully.
+```
+
+### Subcommand: /chati providers
+
+```
+When the user types `/chati providers`:
+  Display enabled providers and their status:
+
+  Providers:
+    claude    PRIMARY   Enabled   Claude Code CLI
+    gemini    -         Enabled   Gemini CLI
+    codex     -         Disabled  OpenAI Codex CLI
+
+  Agent Overrides (from config.yaml):
+    brownfield-wu -> gemini (when codebase > 100K LOC)
+    dev           -> gemini (when large codebase tasks)
+
+  To configure: edit chati.dev/config.yaml -> providers section
+```
+
+### Provider Logging
+
+```yaml
+# Appended to session.yaml on each agent activation
+provider_selections:
+  - agent: brownfield-wu
+    resolved_provider: gemini
+    resolution_source: agent_default   # config_override | agent_default | primary
+    reason: "codebase > 100K LOC"
+    model: opus
+    timestamp: "2026-..."
+```
+
+---
+
 ## Mode Enforcement Protocol
 
 ### Scope Validation

package/framework/schemas/config.schema.json

@@ -37,6 +37,50 @@
       "type": "array",
       "items": { "type": "string" },
       "description": "IDEs configured during installation"
+    },
+    "providers": {
+      "type": "object",
+      "description": "CLI provider configuration",
+      "properties": {
+        "claude": {
+          "type": "object",
+          "properties": {
+            "enabled": { "type": "boolean", "default": true },
+            "primary": { "type": "boolean", "default": true }
+          }
+        },
+        "gemini": {
+          "type": "object",
+          "properties": {
+            "enabled": { "type": "boolean", "default": false },
+            "model_default": { "type": "string", "default": "pro" }
+          }
+        },
+        "codex": {
+          "type": "object",
+          "properties": {
+            "enabled": { "type": "boolean", "default": false },
+            "model_default": { "type": "string", "default": "codex" }
+          }
+        },
+        "copilot": {
+          "type": "object",
+          "properties": {
+            "enabled": { "type": "boolean", "default": false }
+          }
+        }
+      }
+    },
+    "agent_overrides": {
+      "type": "object",
+      "description": "Per-agent provider/model overrides",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "provider": { "type": "string" },
+          "model": { "type": "string" }
+        }
+      }
     }
   }
 }

package/framework/schemas/session.schema.json

@@ -19,6 +19,32 @@
       "default": "interactive",
       "description": "interactive = agent-driven guided mode; autonomous = Ralph Wiggum mode (Dev agent)"
     },
+    "execution_profile": {
+      "type": "string",
+      "enum": ["explore", "guided", "autonomous"],
+      "default": "guided",
+      "description": "Current execution profile governing confirmation requirements"
+    },
+    "providers_enabled": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": ["claude"],
+      "description": "List of enabled CLI providers"
+    },
+    "profile_transitions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "from": { "type": "string" },
+          "to": { "type": "string" },
+          "reason": { "type": "string" },
+          "timestamp": { "type": "string", "format": "date-time" }
+        }
+      },
+      "default": [],
+      "description": "History of execution profile changes"
+    },
     "current_agent": {
       "type": "string",
       "description": "Currently active agent name"
@@ -143,6 +169,7 @@
           "recommended": { "enum": ["opus", "sonnet", "haiku"], "description": "Recommended model" },
           "actual": { "enum": ["opus", "sonnet", "haiku"], "description": "Model actually used" },
           "reason": { "type": "string", "description": "Why this model was selected (default, upgrade condition, no downgrade)" },
+          "provider": { "type": "string", "description": "CLI provider used (claude, gemini, codex, copilot)" },
           "timestamp": { "type": "string", "format": "date-time" }
         }
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chati-dev",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "description": "AI-Powered Multi-Agent Orchestration System — Structured vibe coding for Full Stack Development",
   "type": "module",
   "bin": {
@@ -38,11 +38,15 @@
     "multi-agent",
     "cli",
     "claude",
+    "gemini",
+    "codex",
+    "copilot",
+    "multi-llm",
     "orchestration",
     "fullstack"
   ],
   "author": "Chati.dev",
-  "license": "BUSL-1.1",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/Chati-dev/Chati.dev.git",