chati-dev 2.0.4 → 2.0.6

package/README.md

@@ -3,15 +3,13 @@
 <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. 17 articles. 6 IDEs. 4 languages. 849 tests. Structured vibe coding.</em>
+<em>Structured vibe coding for Full Stack Development.</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%3D20.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=".github/CONTRIBUTING.md"><img src="https://img.shields.io/badge/contributions-welcome-brightgreen.svg" alt="Contributions Welcome"></a>
 </p>
@@ -35,7 +33,7 @@ AI-assisted development today suffers from three critical issues:
 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
+PLANNING (planning)  →  Quality Gate  →  BUILD  →  Quality Gate  →  DEPLOY
   8 agents               QA-Planning     Dev        QA-Impl        DevOps
 ```
 
@@ -51,7 +49,7 @@ CLARITY (planning)  →  Quality Gate  →  BUILD  →  Quality Gate  →  DEPLO
 | **Session Lock** | Once activated, user stays in system until explicit exit. Zero accidental leakage |
 | **Hooks System** | 5 Claude Code hooks — constitution guard, mode governance, model governance, context injection, session digest |
 | **Execution Modes** | Autonomous and human-in-the-loop modes with safety net (5 triggers) and circuit breaker |
-| **Multi-Terminal** | Parallel agent execution with write-scope isolation (Detail + Architect + UX simultaneously) |
+| **Multi-Terminal** | Autonomous agents spawn in separate `claude -p` terminals with dedicated models. Parallel groups (Detail + Architect + UX) with write-scope isolation |
 | **IDE-Agnostic** | Works with 6 IDEs through a thin router pattern |
 
 ---
@@ -64,7 +62,7 @@ CLARITY (planning)  →  Quality Gate  →  BUILD  →  Quality Gate  →  DEPLO
 npx chati-dev init
 ```
 
-The wizard guides you through language, project type, IDE selection, and MCP configuration.
+The wizard guides you through language and project type, then auto-configures Claude Code with the required MCPs.
 
 ### Activate
 
@@ -96,7 +94,7 @@ npx chati-dev status --watch  # Auto-refresh every 5s
 
 | Category | Agents | Purpose |
 |----------|--------|---------|
-| **CLARITY** | Greenfield WU, Brownfield WU, Brief, Detail (PRD), Architect, UX, Phases, Tasks | Planning & Requirements |
+| **PLANNING** | 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 |
@@ -108,40 +106,53 @@ User Request
     │
     ▼
 ┌─────────────────────────────────────────────────┐
-│  ORCHESTRATOR (/chati)                          │
-│  Routes to correct agent, manages session       │
-│  Session Lock: user stays in system             │
+│  ORCHESTRATOR (/chati) — Main Terminal           │
+│  Routes to correct agent, manages session        │
+│  Session Lock: user stays in system              │
 └─────────────────────────────────────────────────┘
     │
-    ▼
-┌─────────────────── CLARITY ─────────────────────┐
-│                                                  │
-│  WU → Brief → Detail(PRD) → Architect → UX      │
-│       → Phases → Tasks                           │
-│                                                  │
-└──────────────────────────────────────────────────┘
+    ├── In-conversation ──┐
+    │                     ▼
+    │   ┌─── PLANNING (interactive) ───┐
+    │   │  WU → Brief                 │
+    │   └─────────────────────────────┘
     │
-    ▼
-┌─────────────────── QUALITY ─────────────────────┐
-│  QA-Planning (traceability validation, ≥95%)     │
-└──────────────────────────────────────────────────┘
+    ├── Spawns terminals ──────────────────────────┐
+    │                                               ▼
+    │   ┌─── PLANNING (autonomous) ─── Parallel ───┐
+    │   │  Detail (opus) ──┐                       │
+    │   │  Architect (opus)├── run simultaneously  │
+    │   │  UX (sonnet) ────┘                       │
+    │   │  → Phases → Tasks                        │
+    │   └──────────────────────────────────────────┘
     │
-    ▼
-┌─────────────────── BUILD ───────────────────────┐
-│  Dev (implementation + self-validation)           │
-└──────────────────────────────────────────────────┘
+    ├── Spawns terminal ──┐
+    │                     ▼
+    │   ┌─── QUALITY ─────────────────────────────┐
+    │   │  QA-Planning (opus) — ≥95% threshold     │
+    │   └──────────────────────────────────────────┘
     │
-    ▼
-┌─────────────────── QUALITY ─────────────────────┐
-│  QA-Implementation (tests + SAST + code review)  │
-└──────────────────────────────────────────────────┘
+    ├── Spawns terminal(s) ┐
+    │                      ▼
+    │   ┌─── BUILD ───────────────────────────────┐
+    │   │  Dev (opus) — parallel for independent   │
+    │   └──────────────────────────────────────────┘
     │
-    ▼
-┌─────────────────── DEPLOY ──────────────────────┐
-│  DevOps (git + deploy + docs)                    │
-└──────────────────────────────────────────────────┘
+    ├── Spawns terminal ──┐
+    │                     ▼
+    │   ┌─── QUALITY ─────────────────────────────┐
+    │   │  QA-Implementation (opus) — tests + SAST │
+    │   └──────────────────────────────────────────┘
+    │
+    └── Spawns terminal ──┐
+                          ▼
+        ┌─── DEPLOY ──────────────────────────────┐
+        │  DevOps (sonnet) — git + deploy + docs   │
+        └──────────────────────────────────────────┘
 ```
 
+Each spawned terminal runs as a separate `claude -p --model <model>` process with its own context window, write-scope isolation, and structured handoff output.
+
 ### Intelligence Layer
 
 The Intelligence Layer operates transparently behind the pipeline:
@@ -177,7 +188,7 @@ The system is governed by a **17-article Constitution** that enforces agent beha
 | 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 |
+| XI | Mode governance (planning/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 |
@@ -255,7 +266,7 @@ your-project/
 ├── chati.dev/
 │   ├── orchestrator/             # Main orchestrator
 │   ├── agents/                   # 13 agent definitions
-│   │   ├── clarity/              # 8 planning agents
+│   │   ├── planning/              # 8 planning agents
 │   │   ├── quality/              # 2 quality gate agents
 │   │   ├── build/                # Dev agent
 │   │   └── deploy/               # DevOps agent
@@ -287,7 +298,8 @@ your-project/
 │   ├── 8-Validation/
 │   └── handoffs/
 └── packages/
-    └── chati-dev/                # CLI installer (npx chati-dev)
+    └── chati-dev/                # CLI + runtime engine (npx chati-dev)
+        └── src/terminal/         # Multi-terminal spawner, monitor, collector
 ```
 
 ---

package/framework/agents/{clarity → planning}/architect.md

@@ -8,7 +8,7 @@ You are the **Architect Agent**, responsible for defining HOW the system will be
 
 - **Role**: Technical Design & Data Architecture Specialist
 - **Pipeline Position**: 4th (greenfield, after Detail) or 3rd (brownfield, after Brief)
-- **Category**: CLARITY
+- **Category**: PLANNING
 - **Question Answered**: HOW will we build it?
 - **Duration**: 45-90 min
 - **Ratio**: 50% Human / 50% AI

package/framework/agents/{clarity → planning}/brief.md

@@ -8,7 +8,7 @@ You are the **Brief Agent**, responsible for extracting and structuring the core
 
 - **Role**: Problem Extraction Specialist
 - **Pipeline Position**: 2nd agent (after WU)
-- **Category**: CLARITY
+- **Category**: PLANNING
 - **Question Answered**: WHAT is the problem?
 - **Duration**: 30-60 min
 - **Ratio**: 90% Human / 10% AI

package/framework/agents/{clarity → planning}/brownfield-wu.md

@@ -8,7 +8,7 @@ You are the **Brownfield WU Agent**, responsible for comprehensive discovery of
 
 - **Role**: Technical + Operational Discovery Agent
 - **Pipeline Position**: 1st agent (brownfield projects)
-- **Category**: CLARITY
+- **Category**: PLANNING
 - **Question Answered**: HOW does it work today? (both code and operations)
 - **Duration**: 1-4h depending on codebase size
 - **Ratio**: 40% Human / 60% AI

package/framework/agents/{clarity → planning}/detail.md

@@ -8,7 +8,7 @@ You are the **Detail Agent**, responsible for transforming the Brief into a form
 
 - **Role**: Product Specification & Requirements Analyst
 - **Pipeline Position**: 3rd (greenfield) or 4th (brownfield, after Architect)
-- **Category**: CLARITY
+- **Category**: PLANNING
 - **Question Answered**: WHAT will we build?
 - **Duration**: 45-90 min
 - **Ratio**: 70% Human / 30% AI

package/framework/agents/{clarity → planning}/greenfield-wu.md

@@ -8,7 +8,7 @@ You are the **Greenfield WU Agent**, responsible for understanding HOW the user
 
 - **Role**: Operational Discovery Agent
 - **Pipeline Position**: 1st agent (greenfield projects)
-- **Category**: CLARITY
+- **Category**: PLANNING
 - **Question Answered**: HOW does it work today?
 - **Duration**: 15-30 min
 - **Ratio**: 70% Human / 30% AI

package/framework/agents/{clarity → planning}/phases.md

@@ -8,7 +8,7 @@ You are the **Phases Agent**, responsible for breaking the PRD into development
 
 - **Role**: Roadmap & Execution Planning Specialist
 - **Pipeline Position**: 6th (after UX)
-- **Category**: CLARITY
+- **Category**: PLANNING
 - **Question Answered**: WHEN will we build it?
 - **Duration**: 20-40 min
 - **Ratio**: 60% Human / 40% AI

package/framework/agents/{clarity → planning}/tasks.md

@@ -8,7 +8,7 @@ You are the **Tasks Agent**, responsible for breaking phases into atomic, execut
 
 - **Role**: Work Breakdown & Task Definition Specialist
 - **Pipeline Position**: 7th (after Phases)
-- **Category**: CLARITY
+- **Category**: PLANNING
 - **Question Answered**: WHO does WHAT specifically?
 - **Duration**: 30-60 min
 - **Ratio**: 50% Human / 50% AI

package/framework/agents/{clarity → planning}/ux.md

@@ -8,7 +8,7 @@ You are the **UX Agent**, responsible for defining HOW the product will look and
 
 - **Role**: User Experience & Design System Specialist
 - **Pipeline Position**: 5th (after Architect in both flows)
-- **Category**: CLARITY
+- **Category**: PLANNING
 - **Question Answered**: HOW will it look/feel?
 - **Duration**: 30-60 min
 - **Ratio**: 60% Human / 40% AI

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

@@ -1,6 +1,6 @@
 # QA-Planning Agent — Traceability Validation
 
-You are the **QA-Planning Agent**, the quality gate between CLARITY (planning) and BUILD (implementation). You validate traceability across all planning artifacts and the rigor of each agent's self-defined criteria. Nothing proceeds to BUILD without your approval.
+You are the **QA-Planning Agent**, the quality gate between PLANNING (planning) and BUILD (implementation). You validate traceability across all planning artifacts and the rigor of each agent's self-defined criteria. Nothing proceeds to BUILD without your approval.
 
 ---
 
@@ -31,7 +31,7 @@ Validate that every Brief problem traces through to a testable task, no requirem
 
 ## On Activation
 
-1. Read ALL CLARITY artifacts:
+1. Read ALL PLANNING artifacts:
    - `chati.dev/artifacts/0-WU/` (wu report)
    - `chati.dev/artifacts/1-Brief/brief-report.md`
    - `chati.dev/artifacts/2-PRD/prd.md`
@@ -48,7 +48,7 @@ Validate that every Brief problem traces through to a testable task, no requirem
 
 ### Step 1: Collect All Artifacts
 ```
-Read every CLARITY artifact and extract:
+Read every PLANNING artifact and extract:
 - Brief problems list
 - PRD requirements list (FR-XXX, NFR-XXX)
 - Architecture components
@@ -109,7 +109,7 @@ Scan ALL artifacts for: [TODO], [TBD], [PLACEHOLDER], [FIXME], {TBD}
 ### Step 3: Validate Criteria Quality (Checks & Balances)
 
 ```
-For each agent that completed CLARITY:
+For each agent that completed PLANNING:
   1. Read their self-validation criteria from handoff
   2. Assess criteria rigor:
      - Are criteria BINARY (pass/fail)? Not subjective?
@@ -229,7 +229,7 @@ agents:
     criteria_count: {total checks performed}
     completed_at: "{timestamp}"
 project:
-  state: build  # Transition from clarity to build
+  state: build  # Transition from planning to build
 current_agent: dev
 ```
 

package/framework/constitution.md

@@ -6,7 +6,7 @@ Chati.dev is a planning-first AI-assisted orchestration system that coordinates
 
 ### 4 Core Principles
 
-1. **Clarity Before Code**: Never write code without understanding the problem, the users, and the constraints. The CLARITY phase exists because assumptions are the root cause of failed projects.
+1. **Planning Before Code**: Never write code without understanding the problem, the users, and the constraints. The PLANNING phase exists because assumptions are the root cause of failed projects.
 
 2. **Short Iterations**: Deliver value in small, verifiable increments. Every agent validates its own output before passing forward. Every quality gate catches issues early.
 
@@ -242,17 +242,17 @@ The pipeline operates in three execution modes that control agent permissions. M
 
 | Mode | States | Read Scope | Write Scope |
 |------|--------|------------|-------------|
-| **clarity** | clarity | Entire project (codebase + chati.dev/) | `chati.dev/` and `.chati/` only |
+| **planning** | planning | Entire project (codebase + chati.dev/) | `chati.dev/` and `.chati/` only |
 | **build** | build, validate | Entire project | Entire project |
 | **deploy** | deploy | Entire project | Entire project + infra/CI operations |
 
 ### Enforcement Rules
 
-1. In `clarity` mode, agents MAY read any file in the project (essential for brownfield-wu)
-2. In `clarity` mode, agents MUST NOT write/edit files outside `chati.dev/` and `.chati/`
+1. In `planning` mode, agents MAY read any file in the project (essential for brownfield-wu)
+2. In `planning` mode, agents MUST NOT write/edit files outside `chati.dev/` and `.chati/`
 3. Transition to `build` requires QA-Planning score >= 95% (Article II)
 4. Transition to `deploy` requires QA-Implementation APPROVED
-5. Backward transition from `build` to `clarity` is permitted when QA-Implementation classifies an issue as `spec` or `architecture` (not `code`)
+5. Backward transition from `build` to `planning` is permitted when QA-Implementation classifies an issue as `spec` or `architecture` (not `code`)
 6. Mode overrides require explicit user confirmation and are logged in session.yaml
 
 **Enforcement: BLOCK** — Write operations outside permitted scope are rejected.
@@ -383,7 +383,7 @@ The system SHALL support two execution modes that govern the degree of human inv
 2. Mode suggestion is computed from project context (risk score). The mode-suggester evaluates: project type, task complexity, risk domains, project history, and recent gotchas. A risk score > 50 suggests human-in-the-loop.
 
 3. Quality gate thresholds are conservative by default:
-   - **qa-planning**: 95% minimum (gates clarity-to-build transition)
+   - **qa-planning**: 95% minimum (gates planning-to-build transition)
    - **qa-implementation**: 90% minimum (gates build-to-deploy transition)
    - **All other agents**: 90% minimum
    - Scores below threshold trigger escalation regardless of execution mode.

package/framework/context/governance.md

@@ -3,9 +3,9 @@
 Extracted from `chati.dev/constitution.md` (17 Articles). Read the full constitution for complete rules.
 
 ## Mode Governance (Article XI)
-- **3 modes**: clarity (read all, write chati.dev/ only), build (full access), deploy (full + infra)
-- **Autonomous transitions**: clarity->build (QA-Planning >= 95%), build->validate (dev done), validate->deploy (QA-Impl approved)
-- **Backward transitions**: build/validate->clarity when QA finds spec/architecture issues
+- **3 modes**: planning (read all, write chati.dev/ only), build (full access), deploy (full + infra)
+- **Autonomous transitions**: planning->build (QA-Planning >= 95%), build->validate (dev done), validate->deploy (QA-Impl approved)
+- **Backward transitions**: build/validate->planning when QA finds spec/architecture issues
 
 ## Context Bracket (Article XII)
 - 4 brackets: FRESH, MODERATE, DEPLETED, CRITICAL

package/framework/context/quality.md

@@ -10,7 +10,7 @@
 Scores within 5 points below threshold trigger REVIEW (human confirmation required even in autonomous mode).
 
 ## 5 Pipeline Gates
-1. **Planning Complete** — All CLARITY agents finished
+1. **Planning Complete** — All PLANNING agents finished
 2. **QA Planning** — QA-Planning agent validates plan coherence (95% threshold)
 3. **Implementation** — Dev agent completes all tasks
 4. **QA Implementation** — Tests pass, SAST clean, coverage adequate (90% threshold)

package/framework/context/root.md

@@ -15,7 +15,7 @@
 
 ## Pipeline
 ```
-CLARITY: WU -> Brief -> Detail -> Architect -> UX -> Phases -> Tasks -> QA-Planning
+PLANNING: WU -> Brief -> Detail -> Architect -> UX -> Phases -> Tasks -> QA-Planning
 BUILD:   Dev -> QA-Implementation
 DEPLOY:  DevOps
 ```

package/framework/data/entity-registry.yaml

@@ -19,7 +19,7 @@ entities:
       adaptability: 0.2
 
     greenfield-wu:
-      path: chati.dev/agents/clarity/greenfield-wu.md
+      path: chati.dev/agents/planning/greenfield-wu.md
       type: agent
       purpose: "Analyze greenfield project context, constraints, and technology landscape"
       keywords: [greenfield, analysis, context, technology, constraints]
@@ -27,7 +27,7 @@ entities:
       adaptability: 0.5
 
     brownfield-wu:
-      path: chati.dev/agents/clarity/brownfield-wu.md
+      path: chati.dev/agents/planning/brownfield-wu.md
       type: agent
       purpose: "Deep discovery of existing codebase — architecture, patterns, debt, dependencies"
       keywords: [brownfield, discovery, codebase, architecture, debt]
@@ -35,7 +35,7 @@ entities:
       adaptability: 0.5
 
     brief:
-      path: chati.dev/agents/clarity/brief.md
+      path: chati.dev/agents/planning/brief.md
       type: agent
       purpose: "Extract and structure user requirements through 5 elicitation phases"
       keywords: [requirements, elicitation, brief, functional, non-functional]
@@ -43,7 +43,7 @@ entities:
       adaptability: 0.4
 
     detail:
-      path: chati.dev/agents/clarity/detail.md
+      path: chati.dev/agents/planning/detail.md
       type: agent
       purpose: "Transform Brief into formal PRD with complete specifications"
       keywords: [prd, specification, detail, formal, requirements]
@@ -51,7 +51,7 @@ entities:
       adaptability: 0.4
 
     architect:
-      path: chati.dev/agents/clarity/architect.md
+      path: chati.dev/agents/planning/architect.md
       type: agent
       purpose: "Design technical architecture, make technology decisions, define system boundaries"
       keywords: [architecture, technology, design, patterns, boundaries]
@@ -59,7 +59,7 @@ entities:
       adaptability: 0.3
 
     ux:
-      path: chati.dev/agents/clarity/ux.md
+      path: chati.dev/agents/planning/ux.md
       type: agent
       purpose: "Design user experience, interaction flows, and interface structure"
       keywords: [ux, design, interaction, flows, interface, wireframes]
@@ -67,7 +67,7 @@ entities:
       adaptability: 0.5
 
     phases:
-      path: chati.dev/agents/clarity/phases.md
+      path: chati.dev/agents/planning/phases.md
       type: agent
       purpose: "Decompose PRD into development phases with MVP-first strategy"
       keywords: [phases, decomposition, mvp, planning, milestones]
@@ -75,7 +75,7 @@ entities:
       adaptability: 0.4
 
     tasks:
-      path: chati.dev/agents/clarity/tasks.md
+      path: chati.dev/agents/planning/tasks.md
       type: agent
       purpose: "Create executable tasks with acceptance criteria from phase definitions"
       keywords: [tasks, acceptance-criteria, executable, given-when-then]
@@ -85,7 +85,7 @@ entities:
     qa-planning:
       path: chati.dev/agents/quality/qa-planning.md
       type: agent
-      purpose: "Validate traceability and consistency across all clarity artifacts"
+      purpose: "Validate traceability and consistency across all planning artifacts"
       keywords: [qa, traceability, consistency, validation, quality-gate]
       dependencies: [qa-gate-template, planning-gate, session-schema]
       adaptability: 0.3

package/framework/domains/agents/qa-implementation.yaml

@@ -39,5 +39,5 @@ rules:
     priority: high
 
   - id: qai-backward
-    text: "If spec/architecture issues found, trigger backward transition to clarity mode."
+    text: "If spec/architecture issues found, trigger backward transition to planning mode."
     priority: high

package/framework/domains/constitution.yaml

@@ -5,7 +5,7 @@ summary: >
   Constitution governance: self-validation required (loop until quality >= 95%),
   guided options (1,2,3 format), persistent session state, two-layer handoff,
   language protocol (interaction=user lang, artifacts=English),
-  deviation protocol, mode governance (clarity/build/deploy),
+  deviation protocol, mode governance (planning/build/deploy),
   context brackets, memory governance, registry governance,
   session lock, model governance.
 
@@ -53,7 +53,7 @@ rules:
     priority: high
 
   - id: art-xi
-    text: "Mode governance: clarity (read all, write chati.dev/), build (full), deploy (full + infra)."
+    text: "Mode governance: planning (read all, write chati.dev/), build (full), deploy (full + infra)."
     priority: critical
 
   - id: art-xii

package/framework/domains/global.yaml

@@ -19,7 +19,7 @@ rules:
     priority: normal
 
 modes:
-  clarity:
+  planning:
     writeScope: "chati.dev/"
     allowedActions:
       - read_any_file

package/framework/hooks/mode-governance.js

@@ -3,7 +3,7 @@
  * Mode Governance Hook — PreToolUse (Write/Edit)
  *
  * BLOCKS write operations outside the scope of the current mode:
- * - clarity mode: can only write to chati.dev/ and .chati/
+ * - planning mode: can only write to chati.dev/ and .chati/
  * - build mode: can write anywhere
  * - deploy mode: can write anywhere + infra
  *
@@ -14,9 +14,9 @@ import { existsSync, readFileSync } from 'fs';
 import { join, relative, isAbsolute } from 'path';
 
 const MODE_SCOPES = {
-  clarity: {
+  planning: {
     allowed: ['chati.dev/', '.chati/', 'chati.dev/artifacts/'],
-    description: 'Clarity mode: write only to chati.dev/ and .chati/',
+    description: 'Planning mode: write only to chati.dev/ and .chati/',
   },
   build: {
     allowed: ['*'],
@@ -30,11 +30,11 @@ const MODE_SCOPES = {
 
 function getCurrentMode(projectDir) {
   const sessionPath = join(projectDir, '.chati', 'session.yaml');
-  if (!existsSync(sessionPath)) return 'clarity'; // Default to most restrictive
+  if (!existsSync(sessionPath)) return 'planning'; // Default to most restrictive
 
   const raw = readFileSync(sessionPath, 'utf-8');
   const match = raw.match(/^\s*mode:\s*(.+)$/m);
-  return match ? match[1].trim().replace(/^["']|["']$/g, '') : 'clarity';
+  return match ? match[1].trim().replace(/^["']|["']$/g, '') : 'planning';
 }
 
 function isPathAllowed(filePath, projectDir, mode) {

package/framework/hooks/model-governance.js

@@ -5,37 +5,57 @@
  * Validates that the model being used matches the agent's assignment.
  * Constitution Article XVI enforcement.
  *
- * Model assignments (from agent definitions):
- * - orchestrator: opus
- * - brief, detail, phases, tasks: sonnet
- * - architect, dev: sonnet | upgrade: opus if complex
- * - ux: sonnet
- * - qa-planning, qa-implementation: sonnet
- * - devops: sonnet
- * - greenfield-wu, brownfield-wu: sonnet
+ * Model assignments (from orchestrator spec — Model Map):
+ * - orchestrator: sonnet | upgrade: opus if complex routing
+ * - greenfield-wu: haiku | upgrade: sonnet if multi-stack
+ * - brownfield-wu: opus | no downgrade
+ * - brief: sonnet | upgrade: opus if 10+ integrations
+ * - detail: opus | no downgrade
+ * - architect: opus | no downgrade
+ * - ux: sonnet | upgrade: opus if design system from scratch
+ * - phases: sonnet | upgrade: opus if 20+ requirements
+ * - tasks: sonnet | upgrade: opus if 50+ tasks
+ * - qa-planning: opus | no downgrade
+ * - qa-implementation: opus | no downgrade
+ * - dev: opus | no downgrade
+ * - devops: sonnet | upgrade: opus if multi-env
  *
- * This hook is advisory — it warns but does not block.
+ * This hook is advisory in IDE mode — it warns but does not block.
  */
 
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 
 const AGENT_MODELS = {
-  orchestrator: 'opus',
-  'greenfield-wu': 'sonnet',
-  'brownfield-wu': 'sonnet',
+  orchestrator: 'sonnet',
+  'greenfield-wu': 'haiku',
+  'brownfield-wu': 'opus',
   brief: 'sonnet',
-  detail: 'sonnet',
-  architect: 'sonnet',
+  detail: 'opus',
+  architect: 'opus',
   ux: 'sonnet',
   phases: 'sonnet',
   tasks: 'sonnet',
-  'qa-planning': 'sonnet',
-  'qa-implementation': 'sonnet',
-  dev: 'sonnet',
+  'qa-planning': 'opus',
+  'qa-implementation': 'opus',
+  dev: 'opus',
   devops: 'sonnet',
 };
 
+/**
+ * Upgrade conditions per agent. When context matches, the model
+ * should be upgraded to the specified target.
+ */
+const UPGRADE_CONDITIONS = {
+  orchestrator: { to: 'opus', condition: 'complex routing or deviation handling' },
+  'greenfield-wu': { to: 'sonnet', condition: 'multi-stack or enterprise' },
+  brief: { to: 'opus', condition: '10+ integrations' },
+  ux: { to: 'opus', condition: 'design system from scratch' },
+  phases: { to: 'opus', condition: '20+ requirements' },
+  tasks: { to: 'opus', condition: '50+ tasks' },
+  devops: { to: 'opus', condition: 'multi-environment or IaC' },
+};
+
 function getCurrentAgent(projectDir) {
   const sessionPath = join(projectDir, '.chati', 'session.yaml');
   if (!existsSync(sessionPath)) return null;
@@ -71,6 +91,6 @@ async function main() {
   }
 }
 
-export { AGENT_MODELS, getCurrentAgent };
+export { AGENT_MODELS, UPGRADE_CONDITIONS, getCurrentAgent };
 
 main();

package/framework/hooks/prism-engine.js

@@ -27,7 +27,7 @@ function readSessionState(projectDir) {
   };
 
   return {
-    mode: extract('mode') || 'clarity',
+    mode: extract('mode') || 'planning',
     currentAgent: extract('current_agent') || null,
     workflow: extract('workflow') || null,
     pipelinePosition: extract('pipeline_position') || null,

package/framework/hooks/session-digest.js

@@ -21,7 +21,7 @@ function extractDigest(projectDir) {
 
   return {
     timestamp: new Date().toISOString(),
-    mode: extract('mode') || 'clarity',
+    mode: extract('mode') || 'planning',
     currentAgent: extract('current_agent') || 'none',
     pipelinePosition: extract('pipeline_position') || 'unknown',
     workflow: extract('workflow') || 'unknown',

package/framework/i18n/en.yaml

@@ -10,15 +10,13 @@ installer:
   brownfield: "Brownfield (existing project integration)"
   detected_brownfield: "Detected package.json and src/ in current directory"
   suggestion_brownfield: "Suggestion: Brownfield"
-  select_ides: "Select IDE(s) for Chati.dev configuration:"
-  select_mcps: "Select MCPs to install (project-level):"
   confirmation_title: "Installation Summary"
   project_label: "Project"
   language_label: "Language"
   ides_label: "IDEs"
   mcps_label: "MCPs"
   will_install: "Will install:"
-  agents_count: "13 agent definitions (CLARITY, BUILD, DEPLOY phases)"
+  agents_count: "13 agent definitions (PLANNING, BUILD, DEPLOY phases)"
   workflows_count: "5 workflow blueprints"
   templates_count: "5 templates (PRD, Brownfield PRD, Architecture, Task, QA Gate)"
   constitution: "Constitution (17 Articles + Preamble)"