chati-dev 2.0.3 → 2.0.5

package/assets/logo.svg

@@ -35,8 +35,8 @@
   <ellipse cx="77" cy="100" rx="3.5" ry="2.5" fill="rgba(255,255,255,0.3)"/>
   <ellipse cx="133" cy="100" rx="3.5" ry="2.5" fill="rgba(255,255,255,0.3)"/>
 
-  <!-- "chati.dev" text inline -->
+  <!-- "Chati.dev" text inline -->
   <text x="210" y="122" font-family="ui-monospace,'SF Mono','Menlo','Consolas','Liberation Mono',monospace" font-weight="700" font-size="68" letter-spacing="-1">
-    <tspan fill="#e6edf3">chati</tspan><tspan fill="#4A90D9">.</tspan><tspan fill="#e6edf3">dev</tspan>
+    <tspan fill="#e6edf3">Chati</tspan><tspan fill="#4A90D9">.</tspan><tspan fill="#e6edf3">dev</tspan>
   </text>
 </svg>

package/framework/agents/build/dev.md

@@ -338,6 +338,19 @@ Rules:
 
 ---
 
+## Parallelization
+
+```
+This agent supports TASK-LEVEL parallelization (all modes):
+- Independent tasks (no shared file dependencies) MUST run in parallel terminals
+- Tasks with dependencies run sequentially within their dependency chain
+- Each parallel terminal gets isolated write scope per task
+- Orchestrator monitors all terminals and merges results after each batch
+- See Transition Logic step 4.5, Group 2 for details
+```
+
+---
+
 ## Input
 
 $ARGUMENTS

package/framework/agents/clarity/architect.md

@@ -362,7 +362,7 @@ Beyond self-validation (Protocol 5.1), the Architect agent enforces:
 
 ---
 
-## Parallelization Hints
+## Parallelization
 
 - **Can run in parallel with**: Detail agent and UX agent (all three activate post-Brief in parallel-eligible pipelines)
 - **Cannot run in parallel with**: Brief agent (upstream dependency), Phases agent (downstream dependency — requires architecture as input)

package/framework/agents/clarity/brief.md

@@ -215,7 +215,7 @@ agents:
     score: {calculated}
     criteria_count: 9
     completed_at: "{timestamp}"
-current_agent: detail  # (greenfield) or architect (brownfield)
+next_parallel_group: [detail, architect, ux]  # PARALLEL GROUP — see Transition Logic 4.5
 last_handoff: chati.dev/artifacts/handoffs/brief-handoff.md
 ```
 
@@ -226,7 +226,7 @@ last_handoff: chati.dev/artifacts/handoffs/brief-handoff.md
 **Greenfield:**
 ```
 Next steps:
-1. Continue to Detail/PRD agent (Recommended) — define WHAT we'll build
+1. Continue to Detail + Architect + UX in parallel (Recommended) — 3 agents run simultaneously
 2. Review the Brief report
 3. Adjust Brief content
 ```
@@ -234,7 +234,7 @@ Next steps:
 **Brownfield:**
 ```
 Next steps:
-1. Continue to Architect agent (Recommended) — understand existing constraints first
+1. Continue to Detail + Architect + UX in parallel (Recommended) — 3 agents run simultaneously
 2. Review the Brief report
 3. Adjust Brief content
 ```
@@ -444,7 +444,7 @@ On failure:
 
 ---
 
-## Parallelization Hints
+## Parallelization
 
 ```
 This agent is NOT parallelizable.

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

@@ -453,7 +453,7 @@ On failure:
 
 ---
 
-## Parallelization Hints
+## Parallelization
 
 ```
 This agent is NOT parallelizable.

package/framework/agents/clarity/detail.md

@@ -371,7 +371,7 @@ Beyond self-validation (Protocol 5.1), the Detail agent enforces:
 
 ---
 
-## Parallelization Hints
+## Parallelization
 
 - **Can run in parallel with**: Architect agent and UX agent (all three activate post-Brief in parallel-eligible pipelines)
 - **Cannot run in parallel with**: Brief agent (upstream dependency), Phases agent (downstream dependency — requires PRD as input)

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

@@ -370,7 +370,7 @@ On failure:
 
 ---
 
-## Parallelization Hints
+## Parallelization
 
 ```
 This agent is NOT parallelizable.

package/framework/agents/clarity/ux.md

@@ -392,7 +392,7 @@ Beyond self-validation (Protocol 5.1), the UX agent enforces:
 
 ---
 
-## Parallelization Hints
+## Parallelization
 
 - **Can run in parallel with**: Detail agent and Architect agent (all three activate post-Brief in parallel-eligible pipelines)
 - **Cannot run in parallel with**: Brief agent (upstream dependency), Phases agent (downstream dependency — requires UX specification as input)

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/orchestrator/chati.md

@@ -158,6 +158,7 @@ brownfield-wu -> Brief -> Architect -> Detail -> UX -> Phases -> Tasks -> QA-Pla
 | devops | chati.dev/agents/deploy/devops.md |
 
 ### Transition Logic
+
 ```
 When an agent completes (score >= 95%):
   1. Agent generates handoff at chati.dev/artifacts/handoffs/{agent-name}-handoff.md
@@ -170,17 +171,124 @@ When an agent completes (score >= 95%):
      - Dev + QA-Implementation = build
      - Final validation = validate
      - DevOps = deploy
-  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
+  7. Activate agent using Hybrid Activation Protocol (see below)
+```
+
+---
+
+## Hybrid Activation Protocol
+
+The orchestrator uses TWO activation modes depending on the agent type:
+
+### Interactive Agents (run IN-CONVERSATION)
+
+These agents require human interaction and run in the same terminal as the orchestrator:
+- **greenfield-wu** — needs user description of the project
+- **brownfield-wu** — needs user guidance on codebase
+- **brief** — needs iterative requirement extraction with user
+
+For interactive agents:
+```
+1. Read the agent's .md file from the Agent Location Map
+2. Display model recommendation (see Model Map below)
+3. Load agent context into the conversation
+4. User interacts with the agent directly
+5. Agent completes, generates handoff, orchestrator continues
+```
+
+### Autonomous Agents (run in SEPARATE TERMINALS)
+
+All other agents run in separate Claude Code processes with the correct model:
+- **detail**, **architect**, **ux**, **phases**, **tasks**
+- **qa-planning**, **dev**, **qa-implementation**, **devops**
+
+For autonomous agents:
+```
+1. Use the Bash tool to spawn the agent in a separate terminal:
+
+   node packages/chati-dev/src/terminal/run-agent.js \
+     --agent {agent_name} \
+     --task-id {primary_task_id} \
+     --project-dir {absolute_project_path} \
+     --previous-agent {previous_agent_name} \
+     --timeout 600000
+
+2. Wait for the JSON output
+
+3. Parse the result:
+   - If "status": "complete" → Save handoff, continue to next agent
+   - If "status": "needs_input" → Read "needs_input_question", ask the user,
+     then re-run with --additional-context "{user_response}"
+   - If "status": "error" → Apply Recovery Protocol (retry up to 2 times)
+   - If retries exhausted → Fall back to in-conversation activation
+
+4. Update session.yaml with completion data
+```
+
+### Parallel Group Execution
+
+  ╔══════════════════════════════════════════════════════════════╗
+  ║ PARALLELIZATION CHECK (MANDATORY — DO NOT SKIP)             ║
+  ║                                                             ║
+  ║ GROUP 1 — Clarity Phase (after Brief completes):            ║
+  ║   Agents: [detail, architect, ux]                           ║
+  ║   ALL run in parallel via separate terminals                ║
+  ║                                                             ║
+  ║ GROUP 2 — Build Phase (Dev agent tasks):                    ║
+  ║   Independent tasks ALWAYS run in parallel                  ║
+  ║   Tasks with dependencies = sequential within chain         ║
+  ╚══════════════════════════════════════════════════════════════╝
+
+When the next agent is part of a parallel group, use:
+
+```
+node packages/chati-dev/src/terminal/run-parallel.js \
+  --agents detail,architect,ux \
+  --task-ids {task_id_detail},{task_id_architect},{task_id_ux} \
+  --project-dir {absolute_project_path} \
+  --previous-agent brief \
+  --timeout 900000
+```
+
+Parse the consolidated JSON output:
+- If all agents completed → merged handoff ready, continue to next sequential agent
+- If partial failure → present failed agents to user with options:
+  1. Retry failed agents only
+  2. Continue with partial results
+  3. Fall back to sequential execution for failed agents
+
+### Sequential Fallback
+
+If terminal spawning fails (claude CLI not found, system error, etc.):
+```
+1. Log the failure
+2. Fall back to in-conversation activation (read agent .md file, become agent)
+3. Record in session.yaml:
+   terminal_fallback:
+     agent: {name}
+     reason: "{error_message}"
+     timestamp: "{now}"
+4. Continue pipeline normally
+```
+
+### Needs-Input Relay Pattern
+
+When a spawned agent needs user input:
+```
+1. Agent returns status: "needs_input" in JSON output
+2. Agent includes question in "needs_input_question" field
+3. Orchestrator reads the question
+4. Orchestrator presents question to user (in their language)
+5. User responds
+6. Orchestrator re-spawns agent with --additional-context "{user_response}"
+7. Repeat until agent completes or max 3 relay cycles
 ```
 
 ---
 
 ## Model Selection Protocol
 
-Before activating any agent, the orchestrator reads the agent's `Model` field and recommends the optimal model.
+Model selection is **enforced by construction**: the orchestrator passes `--model` to the spawned terminal. For interactive agents, the model is recommended to the user.
 
 ### Model Map (Quick Reference)
 
@@ -199,30 +307,19 @@ Before activating any agent, the orchestrator reads the agent's `Model` field an
 | 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:
+### Enforcement
 
 ```
-💡 Model recommendation for {agent_name}: {recommended_model}
-   Reason: {justification}
-   Current: {current_model}
+For autonomous agents (spawned terminals):
+  → Model is AUTOMATICALLY selected and passed via --model flag
+  → No user intervention needed
+  → Correct model guaranteed by the prompt builder
 
-   To switch: /model {recommended_model}
-   Or continue with current model.
+For interactive agents (in-conversation):
+  → Display model recommendation to user:
+    💡 Model recommendation for {agent_name}: {recommended_model}
+       To switch: /model {recommended_model}
+  → Model governance hook provides defense-in-depth validation
 ```
 
 ### Session Logging
@@ -230,10 +327,11 @@ When the recommended model differs from the current model, display:
 ```yaml
 # Appended to session.yaml on each agent activation
 model_selections:
-  - agent: brief
-    recommended: sonnet
-    actual: opus          # What the user actually used
-    reason: "default"
+  - agent: detail
+    recommended: opus
+    actual: opus
+    mode: terminal          # terminal | in-conversation
+    reason: "no downgrade"
     timestamp: "2026-..."
 ```
 
@@ -862,6 +960,7 @@ Level 4 - Graceful Degradation:
 ### Autonomous Mode
 ```
 - Execute pipeline transitions silently when gates pass (score >= 95%)
+- Spawn parallel agent groups automatically (Detail + Architect + UX after Brief; independent Dev tasks in parallel)
 - Auto-resolve simple deviations (redirect to correct agent)
 - Pause only on:
   - Quality gate failure (score < 95%)
@@ -886,25 +985,28 @@ Present suggestion with reasoning. User always has final say.
 
 ---
 
-## Parallelization Hints
+## Parallelization Rules
 
 ### Parallelizable Agent Groups
 ```
-Group 1 (post-Brief):
+Group 1 (post-Brief) — MANDATORY PARALLEL:
   - Detail + Architect + UX
-  - Can run in 3 parallel terminals
+  - MUST run in 3 parallel terminals (autonomous mode)
+  - SHOULD offer parallel option (human-in-the-loop mode)
   - Each writes to isolated artifact directories
-  - Orchestrator collects and merges results
+  - Orchestrator MUST collect and merge ALL handoffs before proceeding to Phases
 
-Group 2 (Dev tasks):
-  - Independent dev tasks can run in N parallel terminals
-  - Each terminal has isolated write scope
+Group 2 (Dev tasks) — MANDATORY PARALLEL:
+  - Independent dev tasks MUST run in N parallel terminals (all modes)
+  - Each terminal has isolated write scope per task
   - Orchestrator monitors and collects results
+  - Tasks with no shared file dependencies run simultaneously
+  - Tasks with dependencies run sequentially within their chain
 
-NOT parallelizable:
+NOT parallelizable (always sequential):
   - WU (needs user interaction)
   - Brief (needs user interaction)
-  - Phases (depends on Detail + Architect + UX)
+  - Phases (depends on Detail + Architect + UX results)
   - Tasks (depends on Phases)
   - QA-Planning (validates everything)
   - QA-Implementation (validates everything)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chati-dev",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "description": "AI-Powered Multi-Agent Orchestration System — 13 agents, 6 IDEs, 4 languages",
   "type": "module",
   "bin": {
@@ -45,12 +45,12 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/ogabrielalonso/chati-dev.git",
+    "url": "https://github.com/ogabrielalonso/Chati.dev.git",
     "directory": "packages/chati-dev"
   },
-  "homepage": "https://github.com/ogabrielalonso/chati-dev#readme",
+  "homepage": "https://github.com/ogabrielalonso/Chati.dev#readme",
   "bugs": {
-    "url": "https://github.com/ogabrielalonso/chati-dev/issues"
+    "url": "https://github.com/ogabrielalonso/Chati.dev/issues"
   },
   "dependencies": {
     "@clack/prompts": "^0.7.0",

package/src/terminal/handoff-parser.js

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview Parse structured handoff data from spawned agent output.
+ *
+ * Agents running in separate `claude -p` terminals include a
+ * <chati-handoff> block in their output. This module extracts
+ * and parses that block so the orchestrator can read the results.
+ */
+
+/**
+ * Parse the <chati-handoff> block from agent stdout.
+ *
+ * @param {string} output - Full stdout from the agent process
+ * @returns {{ found: boolean, handoff: object|null, rawOutput: string }}
+ */
+export function parseAgentOutput(output) {
+  if (!output || typeof output !== 'string') {
+    return { found: false, handoff: null, rawOutput: '' };
+  }
+
+  const match = output.match(/<chati-handoff>([\s\S]*?)<\/chati-handoff>/);
+  if (!match) {
+    return { found: false, handoff: null, rawOutput: output };
+  }
+
+  const content = match[1].trim();
+  const handoff = parseHandoffFields(content);
+
+  return { found: true, handoff, rawOutput: output };
+}
+
+/**
+ * Parse YAML-like key-value fields from the handoff block content.
+ *
+ * Supports:
+ *   scalar: value
+ *   list:
+ *     - item1
+ *     - item2
+ *   map:
+ *     key1: value1
+ *     key2: value2
+ *
+ * @param {string} content - Content inside <chati-handoff> tags
+ * @returns {object} Parsed handoff data
+ */
+function parseHandoffFields(content) {
+  const result = {
+    status: 'unknown',
+    score: null,
+    summary: '',
+    outputs: [],
+    decisions: {},
+    blockers: [],
+    needs_input_question: null,
+  };
+
+  const lines = content.split('\n');
+  let currentKey = null;
+  let currentType = null; // 'list' | 'map'
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+
+    // Check if this is a list item (  - value)
+    const listMatch = trimmed.match(/^-\s+(.+)/);
+    if (listMatch && currentKey && currentType === 'list') {
+      if (Array.isArray(result[currentKey])) {
+        result[currentKey].push(listMatch[1].trim());
+      }
+      continue;
+    }
+
+    // Check if this is a map item (  key: value) under a map key
+    const mapMatch = trimmed.match(/^(\w[\w_-]*):\s+(.+)/);
+    if (mapMatch && currentKey && currentType === 'map') {
+      if (typeof result[currentKey] === 'object' && !Array.isArray(result[currentKey])) {
+        result[currentKey][mapMatch[1]] = mapMatch[2].trim();
+      }
+      continue;
+    }
+
+    // Top-level key: value
+    const kvMatch = trimmed.match(/^(\w[\w_-]*):\s*(.*)/);
+    if (kvMatch) {
+      const key = kvMatch[1];
+      const value = kvMatch[2].trim();
+
+      // Known list keys
+      if (['outputs', 'blockers'].includes(key)) {
+        currentKey = key;
+        currentType = 'list';
+        // If value is inline (not empty), treat as single item
+        if (value && value !== '') {
+          result[key] = [value];
+          currentKey = null;
+          currentType = null;
+        }
+        continue;
+      }
+
+      // Known map keys
+      if (['decisions'].includes(key)) {
+        currentKey = key;
+        currentType = 'map';
+        continue;
+      }
+
+      // Scalar keys
+      currentKey = null;
+      currentType = null;
+
+      if (key === 'status') {
+        result.status = value || 'unknown';
+      } else if (key === 'score') {
+        const num = parseInt(value, 10);
+        result.score = isNaN(num) ? null : num;
+      } else if (key === 'summary') {
+        result.summary = value || '';
+      } else if (key === 'needs_input_question') {
+        result.needs_input_question = value === 'null' || value === '' ? null : value;
+      }
+    }
+  }
+
+  return result;
+}

package/src/terminal/index.js

@@ -28,3 +28,12 @@ export {
   getReadScope,
   buildIsolationEnv,
 } from './isolation.js';
+
+export {
+  buildAgentPrompt,
+  AGENT_FILE_MAP,
+} from './prompt-builder.js';
+
+export {
+  parseAgentOutput,
+} from './handoff-parser.js';