chati-dev 1.3.3 → 1.4.0

package/README.md

@@ -3,7 +3,7 @@
 <img src="packages/chati-dev/assets/logo.svg" alt="chati.dev" width="380">
 <br><br>
 <strong>AI-Powered Multi-Agent Orchestration System</strong><br>
-<em>13 agents. 15 articles. 6 IDEs. 4 languages. Structured vibe coding.</em>
+<em>13 agents. 16 articles. 6 IDEs. 4 languages. Structured vibe coding.</em>
 </div>
 
 <p align="center">
@@ -167,7 +167,7 @@ Every agent follows 8 universal protocols:
 
 ### Constitution
 
-The system is governed by a **15-article Constitution** that enforces agent behavior, quality standards, security, and system integrity. Key articles:
+The system is governed by a **16-article Constitution** that enforces agent behavior, quality standards, security, and system integrity. Key articles:
 
 | Article | Governance |
 |---------|-----------|
@@ -177,6 +177,7 @@ The system is governed by a **15-article Constitution** that enforces agent beha
 | XI | Mode governance (clarity/build/deploy) with autonomous transitions |
 | XII-XIV | Context bracket governance, memory governance, framework registry |
 | XV | Session lock governance — mandatory lock, explicit exit only |
+| XVI | Model governance — opus/sonnet/haiku per agent, no downgrade rule |
 
 ---
 
@@ -256,7 +257,7 @@ your-project/
 │   ├── data/                     # Entity registry
 │   ├── i18n/                     # EN, PT, ES, FR translations
 │   ├── migrations/               # Version migration scripts
-│   ├── constitution.md           # 15 Articles + Preamble
+│   ├── constitution.md           # 16 Articles + Preamble
 │   └── config.yaml               # System configuration
 ├── chati.dev/artifacts/          # Generated during pipeline
 │   ├── 0-WU/

package/framework/agents/clarity/architect.md

@@ -13,6 +13,7 @@ You are the **Architect Agent**, responsible for defining HOW the system will be
 - **Duration**: 45-90 min
 - **Ratio**: 50% Human / 50% AI
 - **Absorbs**: Data Engineer (data modeling, DB audit, schema design, RLS policies)
+- **Model**: opus | no downgrade (architecture decisions require deep reasoning)
 
 ## Required MCPs
 - context7 (library documentation search)

package/framework/agents/clarity/brief.md

@@ -12,6 +12,7 @@ You are the **Brief Agent**, responsible for extracting and structuring the core
 - **Question Answered**: WHAT is the problem?
 - **Duration**: 30-60 min
 - **Ratio**: 90% Human / 10% AI
+- **Model**: sonnet | upgrade: opus if enterprise or 10+ integrations
 
 ## Required MCPs
 - None

package/framework/agents/clarity/brownfield-wu.md

@@ -12,6 +12,7 @@ You are the **Brownfield WU Agent**, responsible for comprehensive discovery of
 - **Question Answered**: HOW does it work today? (both code and operations)
 - **Duration**: 1-4h depending on codebase size
 - **Ratio**: 40% Human / 60% AI
+- **Model**: opus | no downgrade (codebase analysis requires deep reasoning)
 
 ## Required MCPs
 - git (read-only)

package/framework/agents/clarity/detail.md

@@ -13,6 +13,7 @@ You are the **Detail Agent**, responsible for transforming the Brief into a form
 - **Duration**: 45-90 min
 - **Ratio**: 70% Human / 30% AI
 - **Absorbs**: PM (PRD creation, product strategy), Analyst (market research, competitive analysis)
+- **Model**: opus | no downgrade (PRD traceability requires deep reasoning)
 
 ## Required MCPs
 - None

package/framework/agents/clarity/greenfield-wu.md

@@ -12,6 +12,7 @@ You are the **Greenfield WU Agent**, responsible for understanding HOW the user
 - **Question Answered**: HOW does it work today?
 - **Duration**: 15-30 min
 - **Ratio**: 70% Human / 30% AI
+- **Model**: haiku | upgrade: sonnet if multi-stack or enterprise
 
 ## Required MCPs
 - None

package/framework/agents/clarity/phases.md

@@ -13,6 +13,7 @@ You are the **Phases Agent**, responsible for breaking the PRD into development
 - **Duration**: 20-40 min
 - **Ratio**: 60% Human / 40% AI
 - **Absorbs**: SM (sprint planning, prioritization, wave sequencing)
+- **Model**: sonnet | upgrade: opus if 20+ requirements or complex dependencies
 
 ## Required MCPs
 - None

package/framework/agents/clarity/tasks.md

@@ -13,6 +13,7 @@ You are the **Tasks Agent**, responsible for breaking phases into atomic, execut
 - **Duration**: 30-60 min
 - **Ratio**: 50% Human / 50% AI
 - **Absorbs**: SM (structured task creation, Given-When-Then criteria)
+- **Model**: sonnet | upgrade: opus if 50+ tasks or complex acceptance criteria
 
 ## Required MCPs
 - None

package/framework/agents/clarity/ux.md

@@ -13,6 +13,7 @@ You are the **UX Agent**, responsible for defining HOW the product will look and
 - **Duration**: 30-60 min
 - **Ratio**: 60% Human / 40% AI
 - **Absorbs**: Design System init + audit (embedded workflow)
+- **Model**: sonnet | upgrade: opus if design system creation from scratch
 
 ## Required MCPs
 - None

package/framework/agents/deploy/devops.md

@@ -12,6 +12,7 @@ You are the **DevOps Agent**, responsible for shipping the project: Git operatio
 - **Question Answered**: SHIP it
 - **Duration**: 15-30 min
 - **Ratio**: 30% Human / 70% AI
+- **Model**: sonnet | upgrade: opus if multi-environment or infrastructure-as-code
 - **Absorbs**: Docs-gen (auto documentation generation)
 
 ## Required MCPs

package/framework/agents/quality/qa-implementation.md

@@ -12,6 +12,7 @@ You are the **QA-Implementation Agent**, the quality gate between BUILD and DEPL
 - **Question Answered**: DOES it work correctly?
 - **Duration**: 15-45 min (mostly automated)
 - **Ratio**: 90% AI / 10% Human
+- **Model**: opus | no downgrade (code review and SAST require deep reasoning)
 - **Absorbs**: Tests + SAST + CodeRabbit code review
 
 ## Required MCPs

package/framework/agents/quality/qa-planning.md

@@ -12,6 +12,7 @@ You are the **QA-Planning Agent**, the quality gate between CLARITY (planning) a
 - **Question Answered**: IS everything traceable and rigorous?
 - **Duration**: 15-30 min (automated validation)
 - **Ratio**: 95% AI / 5% Human
+- **Model**: opus | no downgrade (cross-artifact validation requires deep reasoning)
 - **Absorbs**: Manager (cross-artifact validation), PO (quality gate validation, coherence checks)
 
 ## Required MCPs

package/framework/constitution.md

@@ -345,5 +345,32 @@ Once the orchestrator is activated via `/chati`, a session lock engages. All age
 
 ---
 
-*chati.dev Constitution v1.3.3 — 15 Articles + Preamble*
+## Article XVI: Model Governance
+
+The orchestrator SHALL select the optimal AI model for each agent to balance quality and cost efficiency.
+
+1. Every agent definition MUST include a `Model` field in its Identity section specifying default model and upgrade conditions.
+
+2. Three model tiers are recognized:
+   - **opus**: Deep reasoning, complex analysis, code generation. Use for agents that make critical decisions or produce complex artifacts.
+   - **sonnet**: Structured tasks, guided workflows, template-based output. Use for agents with clear inputs and predictable output formats.
+   - **haiku**: Simple detection, classification, status checks. Use for agents with minimal reasoning requirements.
+
+3. The orchestrator SHALL read the agent's `Model` field before activation and communicate the recommended model to the user.
+
+4. Agents marked `no downgrade` MUST NOT run on a model below their default. Quality degradation in these agents compromises downstream artifacts.
+
+5. Upgrade conditions (e.g., "upgrade: opus if enterprise") are evaluated by the orchestrator based on session context: project type, codebase size, number of integrations, and complexity signals from previous agents.
+
+6. In IDE environments (Claude Code, Cursor, VS Code), the orchestrator SHALL display a model recommendation message before activating each agent. The user decides whether to switch.
+
+7. In programmatic environments (Agent SDK, API), the model selection SHALL be automatic — no user intervention required.
+
+8. Model selections are logged in session.yaml under `model_selections[]` for cost tracking and optimization.
+
+**Enforcement: GUIDE** — Model recommendations are advisory in IDE mode; automatic in SDK mode.
+
+---
+
+*chati.dev Constitution v1.4.0 — 16 Articles + Preamble*
 *All agents are bound by this Constitution. Violations are enforced per article.*

package/framework/data/entity-registry.yaml

@@ -241,7 +241,7 @@ entities:
     constitution:
       path: chati.dev/constitution.md
       type: governance
-      purpose: "15 Articles + Preamble governing all agent behavior"
+      purpose: "16 Articles + Preamble governing all agent behavior"
       keywords: [constitution, governance, rules, articles, enforcement]
       dependencies: []
       adaptability: 0.1

package/framework/i18n/en.yaml

@@ -21,7 +21,7 @@ installer:
   agents_count: "13 agent definitions (CLARITY, BUILD, DEPLOY phases)"
   workflows_count: "5 workflow blueprints"
   templates_count: "5 templates (PRD, Brownfield PRD, Architecture, Task, QA Gate)"
-  constitution: "Constitution (15 Articles + Preamble)"
+  constitution: "Constitution (16 Articles + Preamble)"
   session_mgmt: "Session management system"
   quality_gates: "Quality gates (4-tier validation)"
   proceed: "Proceed with installation?"
@@ -29,7 +29,7 @@ installer:
   created_chati: "Created .chati/ session directory"
   created_framework: "Created chati.dev/ system directory (agents, templates, workflows)"
   created_commands: "Created .claude/commands/ (thin router)"
-  installed_constitution: "Installed Constitution (Articles I-XV)"
+  installed_constitution: "Installed Constitution (Articles I-XVI)"
   created_session: "Created session.yaml schema"
   created_claude_md: "Created CLAUDE.md"
   configured_mcps: "Configured MCPs:"
@@ -37,7 +37,7 @@ installer:
   agents_valid: "All 13 agents implement 8 protocols"
   handoff_ok: "Handoff protocol: OK"
   validation_ok: "Self-validation criteria: OK"
-  constitution_ok: "Constitution: 15 articles verified"
+  constitution_ok: "Constitution: 16 articles verified"
   created_memories: "Created .chati/memories/ (Memory Layer)"
   installed_intelligence: "Installed Intelligence Layer (Context Engine, Memory, Registry)"
   intelligence_valid: "Intelligence: 6 spec files verified"

package/framework/i18n/es.yaml

@@ -21,7 +21,7 @@ installer:
   agents_count: "13 definiciones de agentes (fases CLARITY, BUILD, DEPLOY)"
   workflows_count: "5 blueprints de workflow"
   templates_count: "5 templates (PRD, PRD Brownfield, Arquitectura, Task, QA Gate)"
-  constitution: "Constitucion (15 Articulos + Preambulo)"
+  constitution: "Constitucion (16 Articulos + Preambulo)"
   session_mgmt: "Sistema de gestion de sesion"
   quality_gates: "Quality gates (validacion en 4 capas)"
   proceed: "Proceder con la instalacion?"
@@ -29,7 +29,7 @@ installer:
   created_chati: "Creado directorio de sesion .chati/"
   created_framework: "Creado directorio del sistema chati.dev/ (agentes, templates, workflows)"
   created_commands: "Creado .claude/commands/ (enrutador)"
-  installed_constitution: "Instalada Constitucion (Articulos I-XV)"
+  installed_constitution: "Instalada Constitucion (Articulos I-XVI)"
   created_session: "Creado schema session.yaml"
   created_claude_md: "Creado CLAUDE.md"
   configured_mcps: "MCPs configurados:"
@@ -37,7 +37,7 @@ installer:
   agents_valid: "Los 13 agentes implementan 8 protocolos"
   handoff_ok: "Protocolo de handoff: OK"
   validation_ok: "Criterios de auto-validacion: OK"
-  constitution_ok: "Constitucion: 15 articulos verificados"
+  constitution_ok: "Constitucion: 16 articulos verificados"
   created_memories: "Creado .chati/memories/ (Memory Layer)"
   installed_intelligence: "Instalada Intelligence Layer (Context Engine, Memory, Registry)"
   intelligence_valid: "Intelligence: 6 archivos de spec verificados"

package/framework/i18n/fr.yaml

@@ -21,7 +21,7 @@ installer:
   agents_count: "13 definitions d'agents (phases CLARITY, BUILD, DEPLOY)"
   workflows_count: "5 blueprints de workflow"
   templates_count: "5 templates (PRD, PRD Brownfield, Architecture, Task, QA Gate)"
-  constitution: "Constitution (15 Articles + Preambule)"
+  constitution: "Constitution (16 Articles + Preambule)"
   session_mgmt: "Systeme de gestion de session"
   quality_gates: "Quality gates (validation en 4 couches)"
   proceed: "Proceder a l'installation?"
@@ -29,7 +29,7 @@ installer:
   created_chati: "Cree le repertoire de session .chati/"
   created_framework: "Cree le repertoire du systeme chati.dev/ (agents, templates, workflows)"
   created_commands: "Cree .claude/commands/ (routeur)"
-  installed_constitution: "Installee la Constitution (Articles I-XV)"
+  installed_constitution: "Installee la Constitution (Articles I-XVI)"
   created_session: "Cree le schema session.yaml"
   created_claude_md: "Cree CLAUDE.md"
   configured_mcps: "MCPs configures:"
@@ -37,7 +37,7 @@ installer:
   agents_valid: "Les 13 agents implementent 8 protocoles"
   handoff_ok: "Protocole de passation: OK"
   validation_ok: "Criteres d'auto-validation: OK"
-  constitution_ok: "Constitution: 15 articles verifies"
+  constitution_ok: "Constitution: 16 articles verifies"
   created_memories: "Cree .chati/memories/ (Memory Layer)"
   installed_intelligence: "Installee Intelligence Layer (Context Engine, Memory, Registry)"
   intelligence_valid: "Intelligence: 6 fichiers de spec verifies"

package/framework/i18n/pt.yaml

@@ -21,7 +21,7 @@ installer:
   agents_count: "13 definicoes de agentes (fases CLARITY, BUILD, DEPLOY)"
   workflows_count: "5 blueprints de workflow"
   templates_count: "5 templates (PRD, PRD Brownfield, Arquitetura, Task, QA Gate)"
-  constitution: "Constituicao (15 Artigos + Preambulo)"
+  constitution: "Constituicao (16 Artigos + Preambulo)"
   session_mgmt: "Sistema de gerenciamento de sessao"
   quality_gates: "Quality gates (validacao em 4 camadas)"
   proceed: "Prosseguir com a instalacao?"
@@ -29,7 +29,7 @@ installer:
   created_chati: "Criado diretorio de sessao .chati/"
   created_framework: "Criado diretorio do sistema chati.dev/ (agentes, templates, workflows)"
   created_commands: "Criado .claude/commands/ (roteador)"
-  installed_constitution: "Instalada Constituicao (Artigos I-XV)"
+  installed_constitution: "Instalada Constituicao (Artigos I-XVI)"
   created_session: "Criado schema session.yaml"
   created_claude_md: "Criado CLAUDE.md"
   configured_mcps: "MCPs configurados:"
@@ -37,7 +37,7 @@ installer:
   agents_valid: "Todos os 13 agentes implementam 8 protocolos"
   handoff_ok: "Protocolo de handoff: OK"
   validation_ok: "Criterios de auto-validacao: OK"
-  constitution_ok: "Constituicao: 15 artigos verificados"
+  constitution_ok: "Constituicao: 16 artigos verificados"
   created_memories: "Criado .chati/memories/ (Memory Layer)"
   installed_intelligence: "Instalada Intelligence Layer (Context Engine, Memory, Registry)"
   intelligence_valid: "Intelligence: 6 arquivos de spec verificados"

package/framework/intelligence/context-engine.md

@@ -25,7 +25,7 @@ The orchestrator injects context through 5 hierarchical layers:
 
 | Layer | Name | Source | When Active |
 |-------|------|--------|-------------|
-| **L0** | Constitution | `chati.dev/constitution.md` (Articles I-XV) | ALWAYS (non-negotiable) |
+| **L0** | Constitution | `chati.dev/constitution.md` (Articles I-XVI) | ALWAYS (non-negotiable) |
 | **L1** | Mode + Global | `config.yaml` + mode governance (clarity/build/deploy) | ALWAYS |
 | **L2** | Agent Scope | `chati.dev/agents/{agent}/` — mission, inputs, outputs, criteria | When agent is active |
 | **L3** | Pipeline State | `.chati/session.yaml` — pipeline position, scores, backlog | When session is active |
@@ -49,7 +49,7 @@ The orchestrator produces a structured XML block injected into agent prompts:
 ```xml
 <chati-context bracket="MODERATE">
   <constitution>
-    Articles I-XV governing agent behavior.
+    Articles I-XVI governing agent behavior.
     Key: Self-validation required. Loop until quality threshold.
     Guided options (1,2,3). Persistent session state.
     Two-layer handoff. Language protocol. Deviation protocol.

package/framework/intelligence/decision-engine.md

@@ -96,7 +96,7 @@ npx chati-dev health
 Checks:
 1. All registered entities exist on disk
 2. Schema files are valid JSON
-3. Constitution has >= 15 articles
+3. Constitution has >= 16 articles
 4. Agents contain required protocol references
 5. Entity count matches actual file count
 6. Checksums match (if calculated)

package/framework/orchestrator/chati.md

@@ -10,6 +10,7 @@ You are the **chati.dev Orchestrator**, the single entry point for the chati.dev
 - **Role**: Orchestrator & Router
 - **Position**: Entry point (always first contact)
 - **Scope**: System-wide routing, session management, deviation handling, backlog
+- **Model**: sonnet | upgrade: opus if complex routing or deviation handling
 
 ---
 
@@ -169,7 +170,71 @@ When an agent completes (score >= 95%):
      - Dev + QA-Implementation = build
      - Final validation = validate
      - DevOps = deploy
-  7. Read next agent's command file -> Activate
+  7. Read next agent's command file -> Extract Model field from Identity section
+  8. Evaluate upgrade conditions against session context
+  9. Display model recommendation (see Model Selection Protocol below)
+  10. Activate agent
+```
+
+---
+
+## Model Selection Protocol
+
+Before activating any agent, the orchestrator reads the agent's `Model` field and recommends the optimal model.
+
+### 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 |
+
+### Evaluation Logic
+
+```
+1. Read agent's Model field from its .md file
+2. Extract default model and upgrade condition
+3. If upgrade condition exists:
+   a. Check session context (project.type, codebase_size, integrations_count, requirements_count)
+   b. Check previous agent signals (handoff complexity, discovered tech debt)
+   c. If condition matches -> recommend upgraded model
+   d. If condition does not match -> use default model
+4. If "no downgrade" -> always use the specified model
+```
+
+### Recommendation Message (IDE Mode)
+
+When the recommended model differs from the current model, display:
+
+```
+💡 Model recommendation for {agent_name}: {recommended_model}
+   Reason: {justification}
+   Current: {current_model}
+
+   To switch: /model {recommended_model}
+   Or continue with current model.
+```
+
+### Session Logging
+
+```yaml
+# Appended to session.yaml on each agent activation
+model_selections:
+  - agent: brief
+    recommended: sonnet
+    actual: opus          # What the user actually used
+    reason: "default"
+    timestamp: "2026-..."
 ```
 
 ---

package/framework/schemas/session.schema.json

@@ -99,6 +99,21 @@
         }
       }
     },
+    "model_selections": {
+      "type": "array",
+      "description": "Model selection log for cost tracking (Article XVI)",
+      "items": {
+        "type": "object",
+        "required": ["agent", "recommended", "timestamp"],
+        "properties": {
+          "agent": { "type": "string", "description": "Agent name" },
+          "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)" },
+          "timestamp": { "type": "string", "format": "date-time" }
+        }
+      }
+    },
     "mode_transitions": {
       "type": "array",
       "description": "Audit trail of all mode transitions",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chati-dev",
-  "version": "1.3.3",
+  "version": "1.4.0",
   "description": "AI-Powered Multi-Agent Orchestration System — 13 agents, 6 IDEs, 4 languages",
   "type": "module",
   "bin": {

package/src/installer/validator.js

@@ -59,7 +59,7 @@ export async function validateInstallation(targetDir) {
   if (existsSync(constitutionPath)) {
     const content = readFileSync(constitutionPath, 'utf-8');
     const articleCount = (content.match(/^## Article/gm) || []).length;
-    results.constitution.pass = articleCount >= 15;
+    results.constitution.pass = articleCount >= 16;
     results.constitution.details.push({ articleCount });
   }
   results.total += 1;

package/src/intelligence/registry-manager.js

@@ -131,8 +131,8 @@ export function runHealthCheck(targetDir) {
   if (existsSync(constitutionPath)) {
     const content = readFileSync(constitutionPath, 'utf-8');
     const articleCount = (content.match(/^## Article/gm) || []).length;
-    checks.constitution.pass = articleCount >= 15;
-    checks.constitution.details = `${articleCount}/15 articles`;
+    checks.constitution.pass = articleCount >= 16;
+    checks.constitution.details = `${articleCount}/16 articles`;
   } else {
     checks.constitution.details = 'Not found';
   }

package/src/wizard/i18n.js

@@ -26,7 +26,7 @@ const FALLBACK_EN = {
     agents_count: '13 agent definitions (CLARITY, BUILD, DEPLOY phases)',
     workflows_count: '5 workflow blueprints',
     templates_count: '5 templates (PRD, Brownfield PRD, Architecture, Task, QA Gate)',
-    constitution: 'Constitution (15 Articles + Preamble)',
+    constitution: 'Constitution (16 Articles + Preamble)',
     session_mgmt: 'Session management system',
     quality_gates: 'Quality gates (4-tier validation)',
     proceed: 'Proceed with installation?',
@@ -34,7 +34,7 @@ const FALLBACK_EN = {
     created_chati: 'Created .chati/ session directory',
     created_framework: 'Created chati.dev/ system directory (agents, templates, workflows)',
     created_commands: 'Created .claude/commands/ (thin router)',
-    installed_constitution: 'Installed Constitution (Articles I-XV)',
+    installed_constitution: 'Installed Constitution (Articles I-XVI)',
     created_session: 'Created session.yaml schema',
     created_claude_md: 'Created CLAUDE.md',
     configured_mcps: 'Configured MCPs:',
@@ -42,7 +42,7 @@ const FALLBACK_EN = {
     agents_valid: 'All 13 agents implement 8 protocols',
     handoff_ok: 'Handoff protocol: OK',
     validation_ok: 'Self-validation criteria: OK',
-    constitution_ok: 'Constitution: 15 articles verified',
+    constitution_ok: 'Constitution: 16 articles verified',
     created_memories: 'Created .chati/memories/ (Memory Layer)',
     installed_intelligence: 'Installed Intelligence Layer (Context Engine, Memory, Registry)',
     intelligence_valid: 'Intelligence: 6 spec files verified',