chati-dev 2.0.4 → 2.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (124) hide show
  1. package/README.md +48 -36
  2. package/framework/agents/{clarity → planning}/architect.md +1 -1
  3. package/framework/agents/{clarity → planning}/brief.md +1 -1
  4. package/framework/agents/{clarity → planning}/brownfield-wu.md +1 -1
  5. package/framework/agents/{clarity → planning}/detail.md +1 -1
  6. package/framework/agents/{clarity → planning}/greenfield-wu.md +1 -1
  7. package/framework/agents/{clarity → planning}/phases.md +1 -1
  8. package/framework/agents/{clarity → planning}/tasks.md +1 -1
  9. package/framework/agents/{clarity → planning}/ux.md +1 -1
  10. package/framework/agents/quality/qa-planning.md +5 -5
  11. package/framework/constitution.md +6 -6
  12. package/framework/context/governance.md +3 -3
  13. package/framework/context/quality.md +1 -1
  14. package/framework/context/root.md +1 -1
  15. package/framework/data/entity-registry.yaml +9 -9
  16. package/framework/domains/agents/qa-implementation.yaml +1 -1
  17. package/framework/domains/constitution.yaml +2 -2
  18. package/framework/domains/global.yaml +1 -1
  19. package/framework/hooks/mode-governance.js +5 -5
  20. package/framework/hooks/model-governance.js +38 -18
  21. package/framework/hooks/prism-engine.js +1 -1
  22. package/framework/hooks/session-digest.js +1 -1
  23. package/framework/i18n/en.yaml +1 -3
  24. package/framework/i18n/es.yaml +1 -3
  25. package/framework/i18n/fr.yaml +1 -3
  26. package/framework/i18n/pt.yaml +1 -3
  27. package/framework/intelligence/context-engine.md +3 -3
  28. package/framework/orchestrator/chati.md +148 -78
  29. package/framework/quality-gates/planning-gate.md +1 -1
  30. package/framework/schemas/context.schema.json +1 -1
  31. package/framework/schemas/session.schema.json +3 -3
  32. package/framework/tasks/architect-api-design.md +1 -1
  33. package/framework/tasks/architect-consolidate.md +1 -1
  34. package/framework/tasks/architect-db-design.md +1 -1
  35. package/framework/tasks/architect-design.md +1 -1
  36. package/framework/tasks/architect-security-review.md +1 -1
  37. package/framework/tasks/architect-stack-selection.md +1 -1
  38. package/framework/tasks/brief-consolidate.md +1 -1
  39. package/framework/tasks/brief-constraint-identify.md +1 -1
  40. package/framework/tasks/brief-extract-requirements.md +1 -1
  41. package/framework/tasks/brief-stakeholder-map.md +1 -1
  42. package/framework/tasks/brief-validate-completeness.md +1 -1
  43. package/framework/tasks/brownfield-wu-architecture-map.md +1 -1
  44. package/framework/tasks/brownfield-wu-deep-discovery.md +1 -1
  45. package/framework/tasks/brownfield-wu-dependency-scan.md +1 -1
  46. package/framework/tasks/brownfield-wu-migration-plan.md +1 -1
  47. package/framework/tasks/brownfield-wu-report.md +1 -1
  48. package/framework/tasks/brownfield-wu-risk-assess.md +1 -1
  49. package/framework/tasks/detail-acceptance-criteria.md +1 -1
  50. package/framework/tasks/detail-consolidate.md +1 -1
  51. package/framework/tasks/detail-edge-case-analysis.md +1 -1
  52. package/framework/tasks/detail-expand-prd.md +1 -1
  53. package/framework/tasks/detail-nfr-extraction.md +1 -1
  54. package/framework/tasks/greenfield-wu-analyze-empty.md +1 -1
  55. package/framework/tasks/greenfield-wu-report.md +1 -1
  56. package/framework/tasks/greenfield-wu-scaffold-detection.md +1 -1
  57. package/framework/tasks/greenfield-wu-tech-stack-assess.md +1 -1
  58. package/framework/tasks/orchestrator-deviation.md +3 -3
  59. package/framework/tasks/orchestrator-escalate.md +2 -2
  60. package/framework/tasks/orchestrator-handoff.md +6 -6
  61. package/framework/tasks/orchestrator-health.md +1 -1
  62. package/framework/tasks/orchestrator-mode-switch.md +20 -20
  63. package/framework/tasks/orchestrator-resume.md +6 -6
  64. package/framework/tasks/orchestrator-route.md +7 -7
  65. package/framework/tasks/orchestrator-status.md +8 -8
  66. package/framework/tasks/orchestrator-suggest-mode.md +13 -13
  67. package/framework/tasks/phases-breakdown.md +1 -1
  68. package/framework/tasks/phases-dependency-mapping.md +1 -1
  69. package/framework/tasks/phases-mvp-scoping.md +1 -1
  70. package/framework/tasks/qa-impl-regression-check.md +2 -2
  71. package/framework/tasks/qa-planning-consolidate.md +3 -3
  72. package/framework/tasks/qa-planning-coverage-plan.md +1 -1
  73. package/framework/tasks/qa-planning-gate-define.md +7 -7
  74. package/framework/tasks/qa-planning-risk-matrix.md +1 -1
  75. package/framework/tasks/qa-planning-test-strategy.md +1 -1
  76. package/framework/tasks/tasks-acceptance-write.md +1 -1
  77. package/framework/tasks/tasks-consolidate.md +1 -1
  78. package/framework/tasks/tasks-decompose.md +1 -1
  79. package/framework/tasks/tasks-estimate.md +1 -1
  80. package/framework/tasks/ux-a11y-check.md +1 -1
  81. package/framework/tasks/ux-component-map.md +1 -1
  82. package/framework/tasks/ux-consolidate.md +1 -1
  83. package/framework/tasks/ux-user-flow.md +1 -1
  84. package/framework/tasks/ux-wireframe.md +1 -1
  85. package/framework/workflows/brownfield-discovery.yaml +7 -7
  86. package/framework/workflows/brownfield-fullstack.yaml +9 -9
  87. package/framework/workflows/brownfield-service.yaml +5 -5
  88. package/framework/workflows/brownfield-ui.yaml +5 -5
  89. package/framework/workflows/greenfield-fullstack.yaml +9 -9
  90. package/package.json +2 -2
  91. package/scripts/bundle-framework.js +1 -1
  92. package/scripts/health-check.js +8 -8
  93. package/scripts/populate-entity-registry.js +1 -1
  94. package/scripts/validate-agents.js +1 -1
  95. package/scripts/validate-tasks.js +1 -1
  96. package/src/autonomy/autonomous-gate.js +1 -1
  97. package/src/autonomy/progress-reporter.js +9 -9
  98. package/src/config/mcp-configs.js +16 -85
  99. package/src/context/engine.js +2 -2
  100. package/src/context/layers/l1-global.js +3 -3
  101. package/src/dashboard/layout.js +7 -7
  102. package/src/dashboard/renderer.js +2 -2
  103. package/src/gates/g1-planning-complete.js +9 -9
  104. package/src/installer/core.js +11 -11
  105. package/src/installer/templates.js +1 -1
  106. package/src/installer/validator.js +8 -8
  107. package/src/intelligence/registry-manager.js +4 -4
  108. package/src/memory/session-digest.js +1 -1
  109. package/src/orchestrator/agent-selector.js +10 -10
  110. package/src/orchestrator/intent-classifier.js +4 -4
  111. package/src/orchestrator/pipeline-manager.js +3 -3
  112. package/src/orchestrator/pipeline-state.js +1 -1
  113. package/src/orchestrator/session-manager.js +3 -3
  114. package/src/tasks/executor.js +1 -1
  115. package/src/tasks/loader.js +1 -1
  116. package/src/terminal/handoff-parser.js +127 -0
  117. package/src/terminal/index.js +9 -0
  118. package/src/terminal/prompt-builder.js +313 -0
  119. package/src/terminal/run-agent.js +248 -0
  120. package/src/terminal/run-parallel.js +238 -0
  121. package/src/terminal/spawner.js +29 -18
  122. package/src/wizard/i18n.js +1 -3
  123. package/src/wizard/index.js +10 -15
  124. package/src/wizard/questions.js +7 -70
@@ -10,15 +10,13 @@ installer:
10
10
  brownfield: "Brownfield (integracion con proyecto existente)"
11
11
  detected_brownfield: "Detectado package.json y src/ en el directorio actual"
12
12
  suggestion_brownfield: "Sugerencia: Brownfield"
13
- select_ides: "Seleccione IDE(s) para configuracion de Chati.dev:"
14
- select_mcps: "Seleccione MCPs para instalar (nivel de proyecto):"
15
13
  confirmation_title: "Resumen de Instalacion"
16
14
  project_label: "Proyecto"
17
15
  language_label: "Idioma"
18
16
  ides_label: "IDEs"
19
17
  mcps_label: "MCPs"
20
18
  will_install: "Se instalara:"
21
- agents_count: "13 definiciones de agentes (fases CLARITY, BUILD, DEPLOY)"
19
+ agents_count: "13 definiciones de agentes (fases PLANNING, BUILD, DEPLOY)"
22
20
  workflows_count: "5 blueprints de workflow"
23
21
  templates_count: "5 templates (PRD, PRD Brownfield, Arquitectura, Task, QA Gate)"
24
22
  constitution: "Constitucion (17 Articulos + Preambulo)"
@@ -10,15 +10,13 @@ installer:
10
10
  brownfield: "Brownfield (integration avec un projet existant)"
11
11
  detected_brownfield: "Detecte package.json et src/ dans le repertoire actuel"
12
12
  suggestion_brownfield: "Suggestion: Brownfield"
13
- select_ides: "Selectionnez IDE(s) pour la configuration de Chati.dev:"
14
- select_mcps: "Selectionnez les MCPs a installer (niveau projet):"
15
13
  confirmation_title: "Resume de l'Installation"
16
14
  project_label: "Projet"
17
15
  language_label: "Langue"
18
16
  ides_label: "IDEs"
19
17
  mcps_label: "MCPs"
20
18
  will_install: "Sera installe:"
21
- agents_count: "13 definitions d'agents (phases CLARITY, BUILD, DEPLOY)"
19
+ agents_count: "13 definitions d'agents (phases PLANNING, BUILD, DEPLOY)"
22
20
  workflows_count: "5 blueprints de workflow"
23
21
  templates_count: "5 templates (PRD, PRD Brownfield, Architecture, Task, QA Gate)"
24
22
  constitution: "Constitution (17 Articles + Preambule)"
@@ -10,15 +10,13 @@ installer:
10
10
  brownfield: "Brownfield (integracao com projeto existente)"
11
11
  detected_brownfield: "Detectado package.json e src/ no diretorio atual"
12
12
  suggestion_brownfield: "Sugestao: Brownfield"
13
- select_ides: "Selecione IDE(s) para configuracao do Chati.dev:"
14
- select_mcps: "Selecione MCPs para instalar (nivel de projeto):"
15
13
  confirmation_title: "Resumo da Instalacao"
16
14
  project_label: "Projeto"
17
15
  language_label: "Idioma"
18
16
  ides_label: "IDEs"
19
17
  mcps_label: "MCPs"
20
18
  will_install: "Sera instalado:"
21
- agents_count: "13 definicoes de agentes (fases CLARITY, BUILD, DEPLOY)"
19
+ agents_count: "13 definicoes de agentes (fases PLANNING, BUILD, DEPLOY)"
22
20
  workflows_count: "5 blueprints de workflow"
23
21
  templates_count: "5 templates (PRD, PRD Brownfield, Arquitetura, Task, QA Gate)"
24
22
  constitution: "Constituicao (17 Artigos + Preambulo)"
@@ -26,7 +26,7 @@ The orchestrator injects context through 5 hierarchical layers:
26
26
  | Layer | Name | Source | When Active |
27
27
  |-------|------|--------|-------------|
28
28
  | **L0** | Constitution | `chati.dev/constitution.md` (Articles I-XVI) | ALWAYS (non-negotiable) |
29
- | **L1** | Mode + Global | `config.yaml` + mode governance (clarity/build/deploy) | ALWAYS |
29
+ | **L1** | Mode + Global | `config.yaml` + mode governance (planning/build/deploy) | ALWAYS |
30
30
  | **L2** | Agent Scope | `chati.dev/agents/{agent}/` — mission, inputs, outputs, criteria | When agent is active |
31
31
  | **L3** | Pipeline State | `.chati/session.yaml` — pipeline position, scores, backlog | When session is active |
32
32
  | **L4** | Task Context | Active artifact + previous agent's handoff | When task is active |
@@ -53,11 +53,11 @@ The orchestrator produces a structured XML block injected into agent prompts:
53
53
  Key: Self-validation required. Loop until quality threshold.
54
54
  Guided options (1,2,3). Persistent session state.
55
55
  Two-layer handoff. Language protocol. Deviation protocol.
56
- Mode governance (clarity/build/deploy).
56
+ Mode governance (planning/build/deploy).
57
57
  Context brackets. Memory governance. Registry governance.
58
58
  </constitution>
59
59
 
60
- <mode>clarity</mode>
60
+ <mode>planning</mode>
61
61
 
62
62
  <agent name="brief" mission="Extract user requirements in 5 structured phases">
63
63
  <inputs>WU artifact, user access</inputs>
@@ -96,7 +96,7 @@ If not already set in session.yaml:
96
96
  project:
97
97
  name: "{detected or asked}"
98
98
  type: greenfield | brownfield
99
- state: clarity
99
+ state: planning
100
100
  execution_mode: interactive
101
101
  current_agent: greenfield-wu | brownfield-wu
102
102
  language: "{detected}"
@@ -106,8 +106,8 @@ user_level_confidence: 0.0
106
106
 
107
107
  #### 3d. Route to First Agent
108
108
  ```
109
- If greenfield -> Read chati.dev/agents/clarity/greenfield-wu.md -> Activate
110
- If brownfield -> Read chati.dev/agents/clarity/brownfield-wu.md -> Activate
109
+ If greenfield -> Read chati.dev/agents/planning/greenfield-wu.md -> Activate
110
+ If brownfield -> Read chati.dev/agents/planning/brownfield-wu.md -> Activate
111
111
  ```
112
112
 
113
113
  ### Step 5: Session Resume
@@ -144,71 +144,151 @@ brownfield-wu -> Brief -> Architect -> Detail -> UX -> Phases -> Tasks -> QA-Pla
144
144
  ### Agent Location Map
145
145
  | Agent | File |
146
146
  |-------|------|
147
- | greenfield-wu | chati.dev/agents/clarity/greenfield-wu.md |
148
- | brownfield-wu | chati.dev/agents/clarity/brownfield-wu.md |
149
- | brief | chati.dev/agents/clarity/brief.md |
150
- | detail | chati.dev/agents/clarity/detail.md |
151
- | architect | chati.dev/agents/clarity/architect.md |
152
- | ux | chati.dev/agents/clarity/ux.md |
153
- | phases | chati.dev/agents/clarity/phases.md |
154
- | tasks | chati.dev/agents/clarity/tasks.md |
147
+ | greenfield-wu | chati.dev/agents/planning/greenfield-wu.md |
148
+ | brownfield-wu | chati.dev/agents/planning/brownfield-wu.md |
149
+ | brief | chati.dev/agents/planning/brief.md |
150
+ | detail | chati.dev/agents/planning/detail.md |
151
+ | architect | chati.dev/agents/planning/architect.md |
152
+ | ux | chati.dev/agents/planning/ux.md |
153
+ | phases | chati.dev/agents/planning/phases.md |
154
+ | tasks | chati.dev/agents/planning/tasks.md |
155
155
  | qa-planning | chati.dev/agents/quality/qa-planning.md |
156
156
  | dev | chati.dev/agents/build/dev.md |
157
157
  | qa-implementation | chati.dev/agents/quality/qa-implementation.md |
158
158
  | devops | chati.dev/agents/deploy/devops.md |
159
159
 
160
160
  ### Transition Logic
161
+
161
162
  ```
162
163
  When an agent completes (score >= 95%):
163
164
  1. Agent generates handoff at chati.dev/artifacts/handoffs/{agent-name}-handoff.md
164
165
  2. Agent updates session.yaml (status: completed, score, completed_at)
165
166
  3. Agent updates CLAUDE.md with current state
166
167
  4. Orchestrator identifies next agent from pipeline
168
+ 5. Update session.yaml: current_agent = next_agent
169
+ 6. Update project.state if crossing macro-phase boundary:
170
+ - WU through QA-Planning = planning
171
+ - Dev + QA-Implementation = build
172
+ - Final validation = validate
173
+ - DevOps = deploy
174
+ 7. Activate agent using Hybrid Activation Protocol (see below)
175
+ ```
176
+
177
+ ---
178
+
179
+ ## Hybrid Activation Protocol
180
+
181
+ The orchestrator uses TWO activation modes depending on the agent type:
182
+
183
+ ### Interactive Agents (run IN-CONVERSATION)
184
+
185
+ These agents require human interaction and run in the same terminal as the orchestrator:
186
+ - **greenfield-wu** — needs user description of the project
187
+ - **brownfield-wu** — needs user guidance on codebase
188
+ - **brief** — needs iterative requirement extraction with user
189
+
190
+ For interactive agents:
191
+ ```
192
+ 1. Read the agent's .md file from the Agent Location Map
193
+ 2. Display model recommendation (see Model Map below)
194
+ 3. Load agent context into the conversation
195
+ 4. User interacts with the agent directly
196
+ 5. Agent completes, generates handoff, orchestrator continues
197
+ ```
198
+
199
+ ### Autonomous Agents (run in SEPARATE TERMINALS)
200
+
201
+ All other agents run in separate Claude Code processes with the correct model:
202
+ - **detail**, **architect**, **ux**, **phases**, **tasks**
203
+ - **qa-planning**, **dev**, **qa-implementation**, **devops**
204
+
205
+ For autonomous agents:
206
+ ```
207
+ 1. Use the Bash tool to spawn the agent in a separate terminal:
208
+
209
+ node packages/chati-dev/src/terminal/run-agent.js \
210
+ --agent {agent_name} \
211
+ --task-id {primary_task_id} \
212
+ --project-dir {absolute_project_path} \
213
+ --previous-agent {previous_agent_name} \
214
+ --timeout 600000
215
+
216
+ 2. Wait for the JSON output
217
+
218
+ 3. Parse the result:
219
+ - If "status": "complete" → Save handoff, continue to next agent
220
+ - If "status": "needs_input" → Read "needs_input_question", ask the user,
221
+ then re-run with --additional-context "{user_response}"
222
+ - If "status": "error" → Apply Recovery Protocol (retry up to 2 times)
223
+ - If retries exhausted → Fall back to in-conversation activation
224
+
225
+ 4. Update session.yaml with completion data
226
+ ```
227
+
228
+ ### Parallel Group Execution
167
229
 
168
230
  ╔══════════════════════════════════════════════════════════════╗
169
- 4.5. PARALLELIZATION CHECK (MANDATORY — DO NOT SKIP)
170
- ║ ║
171
- ║ Before activating next agent, check parallel eligibility: ║
231
+ ║ PARALLELIZATION CHECK (MANDATORY — DO NOT SKIP)
172
232
  ║ ║
173
- ║ GROUP 1 — Clarity Phase (after Brief completes):
233
+ ║ GROUP 1 — Planning Phase (after Brief completes):
174
234
  ║ Agents: [detail, architect, ux] ║
175
- AUTONOMOUS: Spawn all 3 simultaneously (default)
176
- ║ HUMAN-IN-THE-LOOP: Offer parallel option (recommended) ║
177
- ║ Write scopes: ║
178
- ║ detail → chati.dev/artifacts/2-PRD/ ║
179
- ║ architect → chati.dev/artifacts/3-Architecture/ ║
180
- ║ ux → chati.dev/artifacts/4-UX/ ║
181
- ║ → Merge ALL handoffs before proceeding to Phases ║
235
+ ALL run in parallel via separate terminals
182
236
  ║ ║
183
237
  ║ GROUP 2 — Build Phase (Dev agent tasks): ║
184
- ALL MODES: Independent tasks ALWAYS run in parallel
185
- Analyze task dependency graph from tasks.md
186
- ║ → Tasks with no shared file deps = parallel ║
187
- ║ → Tasks with deps = sequential within their chain ║
188
- ║ → Each terminal gets isolated write scope per task ║
189
- ║ → Merge results after each parallel batch ║
190
- ║ ║
191
- ║ If next agent is NOT in a parallel group: ║
192
- ║ → Continue with sequential activation (step 5) ║
238
+ ║ Independent tasks ALWAYS run in parallel
239
+ Tasks with dependencies = sequential within chain
193
240
  ╚══════════════════════════════════════════════════════════════╝
194
241
 
195
- 5. Update session.yaml: current_agent = next_agent
196
- 6. Update project.state if crossing macro-phase boundary:
197
- - WU through QA-Planning = clarity
198
- - Dev + QA-Implementation = build
199
- - Final validation = validate
200
- - DevOps = deploy
201
- 7. Read next agent's command file -> Extract Model field from Identity section
202
- 8. Evaluate upgrade conditions against session context
203
- 9. Display model recommendation (see Model Selection Protocol below)
204
- 10. Activate agent
242
+ When the next agent is part of a parallel group, use:
243
+
244
+ ```
245
+ node packages/chati-dev/src/terminal/run-parallel.js \
246
+ --agents detail,architect,ux \
247
+ --task-ids {task_id_detail},{task_id_architect},{task_id_ux} \
248
+ --project-dir {absolute_project_path} \
249
+ --previous-agent brief \
250
+ --timeout 900000
251
+ ```
252
+
253
+ Parse the consolidated JSON output:
254
+ - If all agents completed → merged handoff ready, continue to next sequential agent
255
+ - If partial failure → present failed agents to user with options:
256
+ 1. Retry failed agents only
257
+ 2. Continue with partial results
258
+ 3. Fall back to sequential execution for failed agents
259
+
260
+ ### Sequential Fallback
261
+
262
+ If terminal spawning fails (claude CLI not found, system error, etc.):
263
+ ```
264
+ 1. Log the failure
265
+ 2. Fall back to in-conversation activation (read agent .md file, become agent)
266
+ 3. Record in session.yaml:
267
+ terminal_fallback:
268
+ agent: {name}
269
+ reason: "{error_message}"
270
+ timestamp: "{now}"
271
+ 4. Continue pipeline normally
272
+ ```
273
+
274
+ ### Needs-Input Relay Pattern
275
+
276
+ When a spawned agent needs user input:
277
+ ```
278
+ 1. Agent returns status: "needs_input" in JSON output
279
+ 2. Agent includes question in "needs_input_question" field
280
+ 3. Orchestrator reads the question
281
+ 4. Orchestrator presents question to user (in their language)
282
+ 5. User responds
283
+ 6. Orchestrator re-spawns agent with --additional-context "{user_response}"
284
+ 7. Repeat until agent completes or max 3 relay cycles
205
285
  ```
206
286
 
207
287
  ---
208
288
 
209
289
  ## Model Selection Protocol
210
290
 
211
- Before activating any agent, the orchestrator reads the agent's `Model` field and recommends the optimal model.
291
+ Model selection is **enforced by construction**: the orchestrator passes `--model` to the spawned terminal. For interactive agents, the model is recommended to the user.
212
292
 
213
293
  ### Model Map (Quick Reference)
214
294
 
@@ -227,30 +307,19 @@ Before activating any agent, the orchestrator reads the agent's `Model` field an
227
307
  | qa-implementation | opus | no downgrade |
228
308
  | devops | sonnet | opus if multi-environment or IaC |
229
309
 
230
- ### Evaluation Logic
231
-
232
- ```
233
- 1. Read agent's Model field from its .md file
234
- 2. Extract default model and upgrade condition
235
- 3. If upgrade condition exists:
236
- a. Check session context (project.type, codebase_size, integrations_count, requirements_count)
237
- b. Check previous agent signals (handoff complexity, discovered tech debt)
238
- c. If condition matches -> recommend upgraded model
239
- d. If condition does not match -> use default model
240
- 4. If "no downgrade" -> always use the specified model
241
- ```
242
-
243
- ### Recommendation Message (IDE Mode)
244
-
245
- When the recommended model differs from the current model, display:
310
+ ### Enforcement
246
311
 
247
312
  ```
248
- 💡 Model recommendation for {agent_name}: {recommended_model}
249
- Reason: {justification}
250
- Current: {current_model}
313
+ For autonomous agents (spawned terminals):
314
+ Model is AUTOMATICALLY selected and passed via --model flag
315
+ No user intervention needed
316
+ → Correct model guaranteed by the prompt builder
251
317
 
252
- To switch: /model {recommended_model}
253
- Or continue with current model.
318
+ For interactive agents (in-conversation):
319
+ Display model recommendation to user:
320
+ 💡 Model recommendation for {agent_name}: {recommended_model}
321
+ To switch: /model {recommended_model}
322
+ → Model governance hook provides defense-in-depth validation
254
323
  ```
255
324
 
256
325
  ### Session Logging
@@ -258,10 +327,11 @@ When the recommended model differs from the current model, display:
258
327
  ```yaml
259
328
  # Appended to session.yaml on each agent activation
260
329
  model_selections:
261
- - agent: brief
262
- recommended: sonnet
263
- actual: opus # What the user actually used
264
- reason: "default"
330
+ - agent: detail
331
+ recommended: opus
332
+ actual: opus
333
+ mode: terminal # terminal | in-conversation
334
+ reason: "no downgrade"
265
335
  timestamp: "2026-..."
266
336
  ```
267
337
 
@@ -274,7 +344,7 @@ model_selections:
274
344
  Before any agent writes a file, the orchestrator validates the operation against the current mode:
275
345
 
276
346
  ```
277
- If project.state == "clarity":
347
+ If project.state == "planning":
278
348
  ALLOW write to: chati.dev/**, .chati/**
279
349
  BLOCK write to: everything else
280
350
  ALLOW read: everything (essential for brownfield-wu codebase analysis)
@@ -294,13 +364,13 @@ If project.state == "deploy":
294
364
  Mode transitions are AUTOMATIC based on quality gate results. The orchestrator executes the transition when the trigger condition is met.
295
365
 
296
366
  ```
297
- clarity -> build:
367
+ planning -> build:
298
368
  TRIGGER: qa-planning agent completes with score >= 95%
299
369
  ACTION:
300
370
  1. Update project.state = "build"
301
371
  2. Log transition in session.yaml mode_transitions:
302
372
  - timestamp: "{now}"
303
- from: clarity
373
+ from: planning
304
374
  to: build
305
375
  trigger: "qa-planning completed with score {score}%"
306
376
  type: automatic
@@ -333,12 +403,12 @@ deploy -> completed:
333
403
  ### Backward Transitions
334
404
 
335
405
  ```
336
- build/validate -> clarity:
406
+ build/validate -> planning:
337
407
  TRIGGER: qa-implementation classifies issue as:
338
408
  - issue_type: "spec" (requirement gap, ambiguity, conflict)
339
409
  - issue_type: "architecture" (design flaw, missing component)
340
410
  ACTION:
341
- 1. Update project.state = "clarity"
411
+ 1. Update project.state = "planning"
342
412
  2. Log backward transition in mode_transitions:
343
413
  - type: backward
344
414
  reason: "{QA finding description}"
@@ -362,8 +432,8 @@ When user requests to skip phases (e.g., "I need to code this NOW"):
362
432
  ```
363
433
  1. Orchestrator detects intent to change mode
364
434
  2. Inform user of current state and what will be skipped:
365
- "You're in CLARITY mode. Skipping to BUILD will bypass:
366
- - {list of pending CLARITY agents}
435
+ "You're in PLANNING mode. Skipping to BUILD will bypass:
436
+ - {list of pending PLANNING agents}
367
437
  Artifacts from these agents will not be generated."
368
438
  3. Request explicit confirmation
369
439
  4. If confirmed:
@@ -375,7 +445,7 @@ When user requests to skip phases (e.g., "I need to code this NOW"):
375
445
  - Mark skipped agents as "skipped" in session.yaml (not "completed")
376
446
  - Continue with target agent
377
447
  5. After override session completes, suggest:
378
- "You skipped CLARITY phases. Want to go back and complete planning?"
448
+ "You skipped PLANNING phases. Want to go back and complete planning?"
379
449
  ```
380
450
 
381
451
  ---
@@ -480,7 +550,7 @@ Display project status dashboard:
480
550
  Phase: {state} Mode: {execution_mode}
481
551
  Language: {language} IDE: {ides}
482
552
 
483
- CLARITY:
553
+ PLANNING:
484
554
  WU: {score} Brief: {score} Detail: {score} Arch: {score}
485
555
  UX: {score} Phases: {score} Tasks: {score} QA-P: {score}
486
556
 
@@ -686,7 +756,7 @@ If agent fails repeatedly:
686
756
  ### Exclusive (only the orchestrator can do this)
687
757
  - Route user messages to agents
688
758
  - Activate/deactivate agents
689
- - Execute mode transitions (clarity -> build -> validate -> deploy)
759
+ - Execute mode transitions (planning -> build -> validate -> deploy)
690
760
  - Manage session lock (activate/deactivate)
691
761
  - Handle deviations and re-routing
692
762
  - Manage backlog items
@@ -868,7 +938,7 @@ Level 4 - Graceful Degradation:
868
938
  1. **Single Entry Point**: The orchestrator is the ONLY way users interact with Chati.dev. No agent is directly accessible.
869
939
  2. **Transparent Routing**: Users should understand which agent is active and why, but never need to manage agents directly.
870
940
  3. **State Preservation**: Every state change is logged in session.yaml. No action is lossy.
871
- 4. **Fail-Safe Defaults**: When uncertain, default to the most restrictive mode (clarity) and the safest agent.
941
+ 4. **Fail-Safe Defaults**: When uncertain, default to the most restrictive mode (planning) and the safest agent.
872
942
  5. **Progressive Disclosure**: Show complexity only when the user needs it. Start simple, reveal depth on demand.
873
943
  6. **Pipeline Respect**: Never skip pipeline steps without explicit user consent and documented risk.
874
944
  7. **Language Fidelity**: Interaction always in user's language. Artifacts always in English. No exceptions.
@@ -1,7 +1,7 @@
1
1
  # Planning Quality Gate
2
2
 
3
3
  ## Purpose
4
- Validates traceability and consistency across all CLARITY artifacts before allowing transition to BUILD phase.
4
+ Validates traceability and consistency across all PLANNING artifacts before allowing transition to BUILD phase.
5
5
 
6
6
  ## When
7
7
  After Tasks agent completes, before Dev agent starts.
@@ -14,7 +14,7 @@
14
14
  "description": "Summarized constitution content (always injected, L0 layer)"
15
15
  },
16
16
  "mode": {
17
- "enum": ["clarity", "build", "deploy"],
17
+ "enum": ["planning", "build", "deploy"],
18
18
  "description": "Current execution mode from session state (L1 layer)"
19
19
  },
20
20
  "agent": {
@@ -11,7 +11,7 @@
11
11
  "properties": {
12
12
  "name": { "type": "string", "description": "Project name" },
13
13
  "type": { "enum": ["greenfield", "brownfield"], "description": "Project type" },
14
- "state": { "enum": ["clarity", "build", "validate", "deploy", "completed"], "description": "Current pipeline macro-phase" }
14
+ "state": { "enum": ["planning", "build", "validate", "deploy", "completed"], "description": "Current pipeline macro-phase" }
15
15
  }
16
16
  },
17
17
  "execution_mode": {
@@ -122,8 +122,8 @@
122
122
  "required": ["timestamp", "from", "to", "trigger"],
123
123
  "properties": {
124
124
  "timestamp": { "type": "string", "format": "date-time" },
125
- "from": { "enum": ["clarity", "build", "validate", "deploy", "completed"] },
126
- "to": { "enum": ["clarity", "build", "validate", "deploy", "completed"] },
125
+ "from": { "enum": ["planning", "build", "validate", "deploy", "completed"] },
126
+ "to": { "enum": ["planning", "build", "validate", "deploy", "completed"] },
127
127
  "trigger": { "type": "string", "description": "What caused the transition (agent completion, override, backward)" },
128
128
  "type": { "enum": ["automatic", "backward", "override"], "description": "Transition classification" },
129
129
  "skipped_agents": {
@@ -2,7 +2,7 @@
2
2
  id: architect-api-design
3
3
  agent: architect
4
4
  trigger: architect-stack-selection
5
- phase: clarity
5
+ phase: planning
6
6
  requires_input: false
7
7
  parallelizable: false
8
8
  outputs: [api-design.yaml]
@@ -2,7 +2,7 @@
2
2
  id: architect-consolidate
3
3
  agent: architect
4
4
  trigger: architect-security-review
5
- phase: clarity
5
+ phase: planning
6
6
  requires_input: false
7
7
  parallelizable: false
8
8
  outputs: [architecture-final.yaml]
@@ -2,7 +2,7 @@
2
2
  id: architect-db-design
3
3
  agent: architect
4
4
  trigger: architect-api-design
5
- phase: clarity
5
+ phase: planning
6
6
  requires_input: false
7
7
  parallelizable: false
8
8
  outputs: [db-design.yaml]
@@ -2,7 +2,7 @@
2
2
  id: architect-design
3
3
  agent: architect
4
4
  trigger: detail
5
- phase: clarity
5
+ phase: planning
6
6
  requires_input: false
7
7
  parallelizable: true
8
8
  outputs: [architecture.yaml]
@@ -2,7 +2,7 @@
2
2
  id: architect-security-review
3
3
  agent: architect
4
4
  trigger: architect-db-design
5
- phase: clarity
5
+ phase: planning
6
6
  requires_input: false
7
7
  parallelizable: false
8
8
  outputs: [security-review.yaml]
@@ -2,7 +2,7 @@
2
2
  id: architect-stack-selection
3
3
  agent: architect
4
4
  trigger: architect-design
5
- phase: clarity
5
+ phase: planning
6
6
  requires_input: false
7
7
  parallelizable: false
8
8
  outputs: [stack-selection.yaml]
@@ -2,7 +2,7 @@
2
2
  id: brief-consolidate
3
3
  agent: brief
4
4
  trigger: brief-constraint-identify
5
- phase: clarity
5
+ phase: planning
6
6
  requires_input: false
7
7
  parallelizable: false
8
8
  outputs: [brief.yaml]
@@ -2,7 +2,7 @@
2
2
  id: brief-constraint-identify
3
3
  agent: brief
4
4
  trigger: brief-stakeholder-map
5
- phase: clarity
5
+ phase: planning
6
6
  requires_input: true
7
7
  parallelizable: false
8
8
  outputs: [constraints.yaml]
@@ -2,7 +2,7 @@
2
2
  id: brief-extract-requirements
3
3
  agent: brief
4
4
  trigger: orchestrator
5
- phase: clarity
5
+ phase: planning
6
6
  requires_input: true
7
7
  parallelizable: false
8
8
  outputs: [requirements-raw.yaml]
@@ -2,7 +2,7 @@
2
2
  id: brief-stakeholder-map
3
3
  agent: brief
4
4
  trigger: brief-validate-completeness
5
- phase: clarity
5
+ phase: planning
6
6
  requires_input: true
7
7
  parallelizable: false
8
8
  outputs: [stakeholder-map.yaml]
@@ -2,7 +2,7 @@
2
2
  id: brief-validate-completeness
3
3
  agent: brief
4
4
  trigger: brief-extract-requirements
5
- phase: clarity
5
+ phase: planning
6
6
  requires_input: true
7
7
  parallelizable: false
8
8
  outputs: [validation-report.yaml]
@@ -2,7 +2,7 @@
2
2
  id: brownfield-wu-architecture-map
3
3
  agent: brownfield-wu
4
4
  trigger: brownfield-wu-dependency-scan
5
- phase: clarity
5
+ phase: planning
6
6
  requires_input: false
7
7
  parallelizable: true
8
8
  outputs: [architecture-map.yaml]
@@ -2,7 +2,7 @@
2
2
  id: brownfield-wu-deep-discovery
3
3
  agent: brownfield-wu
4
4
  trigger: orchestrator
5
- phase: clarity
5
+ phase: planning
6
6
  requires_input: false
7
7
  parallelizable: false
8
8
  outputs: [discovery.yaml]
@@ -2,7 +2,7 @@
2
2
  id: brownfield-wu-dependency-scan
3
3
  agent: brownfield-wu
4
4
  trigger: brownfield-wu-deep-discovery
5
- phase: clarity
5
+ phase: planning
6
6
  requires_input: false
7
7
  parallelizable: true
8
8
  outputs: [dependencies.yaml]
@@ -2,7 +2,7 @@
2
2
  id: brownfield-wu-migration-plan
3
3
  agent: brownfield-wu
4
4
  trigger: brownfield-wu-risk-assess
5
- phase: clarity
5
+ phase: planning
6
6
  requires_input: true
7
7
  parallelizable: false
8
8
  outputs: [migration-plan.yaml]
@@ -2,7 +2,7 @@
2
2
  id: brownfield-wu-report
3
3
  agent: brownfield-wu
4
4
  trigger: brownfield-wu-migration-plan
5
- phase: clarity
5
+ phase: planning
6
6
  requires_input: false
7
7
  parallelizable: false
8
8
  outputs: [wu-report.yaml]
@@ -2,7 +2,7 @@
2
2
  id: brownfield-wu-risk-assess
3
3
  agent: brownfield-wu
4
4
  trigger: brownfield-wu-architecture-map
5
- phase: clarity
5
+ phase: planning
6
6
  requires_input: false
7
7
  parallelizable: false
8
8
  outputs: [risk-assessment.yaml]
@@ -2,7 +2,7 @@
2
2
  id: detail-acceptance-criteria
3
3
  agent: detail
4
4
  trigger: detail-edge-case-analysis
5
- phase: clarity
5
+ phase: planning
6
6
  requires_input: false
7
7
  parallelizable: false
8
8
  outputs: [acceptance-criteria.yaml]