chati-dev 1.3.2 → 1.4.0

package/README.md

@@ -0,0 +1,331 @@
+<div align="center">
+<br>
+<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. 16 articles. 6 IDEs. 4 languages. Structured vibe coding.</em>
+</div>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/chati-dev"><img src="https://img.shields.io/npm/v/chati-dev?color=blue&label=npm" alt="npm"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node.js"></a>
+  <a href="#architecture"><img src="https://img.shields.io/badge/agents-13-purple.svg" alt="Agents"></a>
+  <a href="#supported-ides"><img src="https://img.shields.io/badge/IDEs-6-orange.svg" alt="IDEs"></a>
+  <a href="#internationalization"><img src="https://img.shields.io/badge/i18n-EN%20%7C%20PT%20%7C%20ES%20%7C%20FR-informational.svg" alt="i18n"></a>
+  <a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/contributions-welcome-brightgreen.svg" alt="Contributions Welcome"></a>
+</p>
+
+---
+
+A structured, agent-driven orchestration system that coordinates **13 specialized AI agents** across the full software development lifecycle — from requirements gathering to deployment. Every decision is traceable, every artifact is validated, every session persists.
+
+## Why chati.dev?
+
+### The Problem
+
+AI-assisted development today suffers from three critical issues:
+
+1. **Context Loss** — AI forgets decisions across sessions, leading to inconsistent implementations
+2. **Planning Gaps** — Jumping straight to code without structured requirements leads to rework
+3. **System Leakage** — Users accidentally "fall out" of agent systems into generic AI mode
+
+### The Solution
+
+chati.dev introduces **Agent-Driven Development**: a pipeline of 13 specialized agents where each agent owns a specific phase, produces validated artifacts, and hands off context to the next agent. An Intelligence Layer ensures context is never lost, knowledge persists across sessions, and the user never accidentally leaves the system.
+
+```
+CLARITY (planning)  →  Quality Gate  →  BUILD  →  Quality Gate  →  DEPLOY
+  8 agents               QA-Planning     Dev        QA-Impl        DevOps
+```
+
+### Key Innovations
+
+| Innovation | Description |
+|------------|-------------|
+| **Structured Agent Pipeline** | 13 agents with defined missions, validated outputs, and handoff protocols |
+| **Self-Validating Agents** | Binary pass/fail criteria per agent. Quality gates at planning and implementation |
+| **Context Engine** | 4 context brackets (FRESH → CRITICAL) with 5 injection layers. Autonomous recovery |
+| **Memory Layer** | 4 cognitive sectors. Persistent knowledge across sessions with attention scoring |
+| **Framework Registry** | Entity catalog with decision engine (REUSE/ADAPT/CREATE) for brownfield analysis |
+| **Session Lock** | Once activated, user stays in system until explicit exit. Zero accidental leakage |
+| **IDE-Agnostic** | Works with 6 IDEs through a thin router pattern |
+
+---
+
+## Quick Start
+
+### Install
+
+```bash
+npx chati-dev init
+```
+
+The wizard guides you through language, project type, IDE selection, and MCP configuration.
+
+### Activate
+
+```
+/chati
+```
+
+The orchestrator loads your session, detects where you left off, and routes you to the right agent. You stay inside the system until you explicitly exit.
+
+### Monitor
+
+```bash
+npx chati-dev status          # One-time snapshot
+npx chati-dev status --watch  # Auto-refresh every 5s
+```
+
+### Exit & Resume
+
+```
+/chati exit     # Save session and exit
+/chati          # Resume exactly where you left off
+```
+
+---
+
+## Architecture
+
+### 13 Agents, 4 Categories
+
+| Category | Agents | Purpose |
+|----------|--------|---------|
+| **CLARITY** | Greenfield WU, Brownfield WU, Brief, Detail (PRD), Architect, UX, Phases, Tasks | Planning & Requirements |
+| **Quality** | QA-Planning, QA-Implementation | Validation & Gates |
+| **BUILD** | Dev | Implementation |
+| **DEPLOY** | DevOps | Shipping |
+
+### Pipeline Flow
+
+```
+User Request
+    │
+    ▼
+┌─────────────────────────────────────────────────┐
+│  ORCHESTRATOR (/chati)                          │
+│  Routes to correct agent, manages session       │
+│  Session Lock: user stays in system             │
+└─────────────────────────────────────────────────┘
+    │
+    ▼
+┌─────────────────── CLARITY ─────────────────────┐
+│                                                  │
+│  WU → Brief → Detail(PRD) → Architect → UX      │
+│       → Phases → Tasks                           │
+│                                                  │
+└──────────────────────────────────────────────────┘
+    │
+    ▼
+┌─────────────────── QUALITY ─────────────────────┐
+│  QA-Planning (traceability validation, ≥95%)     │
+└──────────────────────────────────────────────────┘
+    │
+    ▼
+┌─────────────────── BUILD ───────────────────────┐
+│  Dev (implementation + self-validation)           │
+└──────────────────────────────────────────────────┘
+    │
+    ▼
+┌─────────────────── QUALITY ─────────────────────┐
+│  QA-Implementation (tests + SAST + code review)  │
+└──────────────────────────────────────────────────┘
+    │
+    ▼
+┌─────────────────── DEPLOY ──────────────────────┐
+│  DevOps (git + deploy + docs)                    │
+└──────────────────────────────────────────────────┘
+```
+
+### Intelligence Layer (V7.1)
+
+The Intelligence Layer operates transparently behind the pipeline:
+
+| System | What it does |
+|--------|-------------|
+| **Context Engine** | Detects context depletion across 4 brackets. Reduces injection layers as context fills. Autonomous recovery via Smart Continuation or Session Spawn. |
+| **Memory Layer** | Captures decisions, patterns, and lessons learned. Persists across sessions. 4 cognitive sectors (Episodic, Semantic, Procedural, Reflective). Attention scoring with natural decay. |
+| **Framework Registry** | Catalogs all 48 system artifacts. Decision engine for brownfield analysis: REUSE existing artifacts, ADAPT with modifications, or CREATE new. |
+| **Session Lock** | Locks the session on `/chati` activation. All messages routed through orchestrator. Exit only via `/chati exit`. Prevents accidental context leakage. |
+
+### Universal Protocols
+
+Every agent follows 8 universal protocols:
+
+| Protocol | Purpose |
+|----------|---------|
+| 5.1 Dynamic Self-Validation | Binary pass/fail criteria per agent |
+| 5.2 Loop Until Done | Iterate until quality threshold met |
+| 5.3 Guided Options | Always present 1, 2, 3 choices |
+| 5.4 Persistence | Session state survives restarts |
+| 5.5 Two-Layer Handoff | Structured context transfer between agents |
+| 5.6 Language Protocol | Interaction in user lang, artifacts in English |
+| 5.7 Deviation Protocol | Handle scope changes mid-pipeline |
+| 5.8 Interaction Model | Agent-driven with power user escape hatch |
+
+### Constitution
+
+The system is governed by a **16-article Constitution** that enforces agent behavior, quality standards, security, and system integrity. Key articles:
+
+| Article | Governance |
+|---------|-----------|
+| I-IV | Agent governance, quality standards, memory & context, security |
+| V-VII | Communication protocol, design system, English-only documentation |
+| VIII-X | Two-layer handoff, agent-driven interaction, dynamic self-validation |
+| 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 |
+
+---
+
+## Supported IDEs
+
+| IDE | Router Pattern |
+|-----|---------------|
+| **Claude Code** | `.claude/commands/chati.md` → orchestrator |
+| **VS Code** | `.vscode/chati.md` → orchestrator |
+| **AntiGravity** | Platform agent config → orchestrator |
+| **Cursor** | `.cursor/rules/chati.md` → orchestrator |
+| **Gemini CLI** | `.gemini/agents/chati.md` → orchestrator |
+| **GitHub Copilot** | `.github/copilot/chati.md` → orchestrator |
+
+---
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `npx chati-dev init` | Initialize new project with wizard |
+| `npx chati-dev install` | Install into existing project |
+| `npx chati-dev status` | Show project dashboard |
+| `npx chati-dev status --watch` | Auto-refresh dashboard every 5s |
+| `npx chati-dev check-update` | Check for system updates |
+| `npx chati-dev upgrade` | Upgrade to latest version |
+| `npx chati-dev upgrade --version X.Y.Z` | Upgrade to specific version |
+| `npx chati-dev memory stats` | Show memory statistics (total, by agent/sector/tier) |
+| `npx chati-dev memory list` | List memories (--agent, --sector, --tier filters) |
+| `npx chati-dev memory search <query>` | Search memories by tags or content |
+| `npx chati-dev memory clean` | Clean expired/session memories (--dry-run) |
+| `npx chati-dev context` | Show context bracket advisory |
+| `npx chati-dev registry stats` | Show entity registry statistics |
+| `npx chati-dev registry check` | Validate entity registry against filesystem |
+| `npx chati-dev health` | Comprehensive system health check (5 checks) |
+| `npx chati-dev changelog` | View changelog |
+| `npx chati-dev --reconfigure` | Reconfigure installation |
+
+### Orchestrator Commands (inside active session)
+
+| Command | Description |
+|---------|-------------|
+| `/chati` | Start or resume session |
+| `/chati status` | Show pipeline status |
+| `/chati help` | Show available commands |
+| `/chati resume` | Resume from continuation file |
+| `/chati exit` | Save session and exit |
+
+---
+
+## Project Structure
+
+```
+your-project/
+├── .chati/
+│   ├── session.yaml              # Session state (auto-managed)
+│   ├── memories/                 # Memory Layer storage (gitignored)
+│   └── continuation/             # Context recovery files
+├── .claude/
+│   └── commands/
+│       └── chati.md              # Thin router → orchestrator
+├── CLAUDE.md                     # IDE entry point (auto-updated)
+├── chati.dev/
+│   ├── orchestrator/             # Main orchestrator
+│   ├── agents/                   # 13 agent definitions
+│   │   ├── clarity/              # 8 planning agents
+│   │   ├── quality/              # 2 quality gate agents
+│   │   ├── build/                # Dev agent
+│   │   └── deploy/               # DevOps agent
+│   ├── workflows/                # 5 workflow blueprints
+│   ├── templates/                # 5 artifact templates
+│   ├── schemas/                  # JSON schemas for validation
+│   ├── intelligence/             # Context Engine, Memory Layer, Decision Engine
+│   ├── frameworks/               # Decision heuristics, quality dims
+│   ├── quality-gates/            # Planning & implementation gates
+│   ├── patterns/                 # Elicitation patterns
+│   ├── data/                     # Entity registry
+│   ├── i18n/                     # EN, PT, ES, FR translations
+│   ├── migrations/               # Version migration scripts
+│   ├── constitution.md           # 16 Articles + Preamble
+│   └── config.yaml               # System configuration
+├── chati.dev/artifacts/          # Generated during pipeline
+│   ├── 0-WU/
+│   ├── 1-Brief/
+│   ├── 2-PRD/
+│   ├── 3-Architecture/
+│   ├── 4-UX/
+│   ├── 5-Phases/
+│   ├── 6-Tasks/
+│   ├── 7-QA-Planning/
+│   ├── 8-Validation/
+│   └── handoffs/
+└── packages/
+    └── chati-dev/                # CLI installer (npx chati-dev)
+```
+
+---
+
+## Internationalization
+
+The installer and agent interactions support 4 languages:
+
+| Language | Code | Status |
+|----------|------|--------|
+| **English** | `en` | Default |
+| **Portugues** | `pt` | Full support |
+| **Espanol** | `es` | Full support |
+| **Francais** | `fr` | Full support |
+
+Artifacts are always generated in English for portability and team collaboration.
+
+---
+
+## Upgrade System
+
+```bash
+npx chati-dev check-update                # Check for updates
+npx chati-dev upgrade                      # Upgrade to latest
+npx chati-dev upgrade --version 1.2.1      # Specific version
+```
+
+Upgrades include automatic backup, migrations, validation, and config merging. Rollback on failure.
+
+---
+
+## Prerequisites
+
+- **Node.js** >= 18.0.0
+- **npm** >= 9.0.0
+- A supported IDE with AI assistant capabilities
+
+---
+
+## Contributing
+
+We welcome contributions from agents, templates, workflows, intelligence data, translations, and CLI improvements. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Security
+
+For security concerns, please see our [Security Policy](SECURITY.md).
+
+## License
+
+This project is licensed under the MIT License — see [LICENSE](LICENSE) for details.
+
+---
+
+<p align="center">
+  <sub>Built with structure, validated by agents, governed by constitution.</sub><br>
+  <sub>chati.dev &copy; 2026</sub>
+</p>

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.2 — 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.2",
+  "version": "1.4.0",
   "description": "AI-Powered Multi-Agent Orchestration System — 13 agents, 6 IDEs, 4 languages",
   "type": "module",
   "bin": {
@@ -8,6 +8,12 @@
     "chati-dev": "bin/chati.js"
   },
   "main": "src/wizard/index.js",
+  "exports": {
+    ".": "./src/wizard/index.js",
+    "./installer": "./src/installer/core.js",
+    "./dashboard": "./src/dashboard/renderer.js",
+    "./upgrade": "./src/upgrade/checker.js"
+  },
   "files": [
     "bin/",
     "src/",
@@ -48,10 +54,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.7.0",
-    "blessed": "^0.1.81",
     "chalk": "^5.3.0",
-    "cli-progress": "^3.12.0",
-    "fs-extra": "^11.2.0",
     "js-yaml": "^4.1.0",
     "ora": "^8.0.1",
     "semver": "^7.6.0"

package/scripts/bundle-framework.js

@@ -55,4 +55,13 @@ for (const file of rootFiles) {
 }
 
 console.log('Framework bundled to:', DEST);
+
+// Copy README from monorepo root so npm displays it
+const readmeSrc = join(MONOREPO_ROOT, 'README.md');
+const readmeDest = join(PACKAGE_ROOT, 'README.md');
+if (existsSync(readmeSrc)) {
+  cpSync(readmeSrc, readmeDest);
+  console.log('README.md copied to package.');
+}
+
 console.log('Done.');

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',