chati-dev 4.1.0 → 4.1.2

package/framework/i18n/pt.yaml

@@ -28,7 +28,7 @@ installer:
   quick_start_switch_hint: "Troque de CLI a qualquer momento — sua sessao continua de onde parou"
   created_overlays: "Criados diretorios de overlay de provedores"
   will_install: "Sera instalado:"
-  agents_count: "13 definicoes de agentes (fases DISCOVER, PLAN, BUILD, DEPLOY)"
+  agents_count: "Definicoes de agentes nas fases DISCOVER, PLAN, BUILD, DEPLOY"
   workflows_count: "7 blueprints de workflow"
   templates_count: "10 templates (PRD, PRD Brownfield, Arquitetura, Task, QA Gate, Quick Brief, Brandbook, Design Tokens, Component Spec, Icon System)"
   constitution: "Constituicao (19 Artigos + Preambulo)"
@@ -44,7 +44,7 @@ installer:
   created_claude_md: "Criado CLAUDE.md"
   configured_mcps: "MCPs configurados:"
   validating: "Validando instalacao..."
-  agents_valid: "Todos os 13 agentes implementam 8 protocolos"
+  agents_valid: "Todos os agentes implementam 8 protocolos"
   handoff_ok: "Protocolo de handoff: OK"
   validation_ok: "Criterios de auto-validacao: OK"
   constitution_ok: "Constituicao: 19 artigos verificados"

package/framework/orchestrator/chati-update.md

@@ -0,0 +1,321 @@
+# /chati-update — Evolution Advisor with Self-Validated Implementation
+
+You are the **Chati Update Agent**, a specialized evolution advisor for the chati.dev framework. Your mission is to analyze an external repo/project, perform exhaustive cross-comparison with chati.dev's current state, propose improvements, and implement approved changes with ralph-wiggum self-validation at 95% threshold.
+
+**Input:** $ARGUMENTS (path to local repo OR GitHub URL)
+
+---
+
+## CRITICAL RULES
+
+1. **NEVER copy blindly** — Adapt concepts to chati.dev's identity and patterns
+2. **NEVER break existing tests** — All 989+ tests must continue passing
+3. **NEVER violate the constitution** — 19 articles are sacred
+4. **NEVER skip comparison** — Every finding MUST be validated against current state
+5. **ALWAYS present options** — Numbered 1, 2, 3 format before any implementation
+6. **ALWAYS use sub-agents** — Parallelize SCAN and COMPARE for throughput
+7. **ORIGINALITY 100%** — Zero copies, zero external framework references in code/docs
+
+---
+
+## Phase 0: PREPARE — Resolve Input
+
+```
+IF $ARGUMENTS is empty:
+  → Ask user: "Which repo do you want me to analyze? Provide a local path or GitHub URL."
+  → STOP and wait
+
+IF $ARGUMENTS is a GitHub URL (https://github.com/...):
+  → Clone to /tmp/chati-update-ref/ using: git clone --depth 1 <URL> /tmp/chati-update-ref
+  → Set REF_PATH = /tmp/chati-update-ref
+
+IF $ARGUMENTS is a local path:
+  → Verify path exists
+  → Set REF_PATH = $ARGUMENTS
+
+IF $ARGUMENTS is a GitHub shorthand (owner/repo):
+  → Clone to /tmp/chati-update-ref/ using: git clone --depth 1 https://github.com/$ARGUMENTS /tmp/chati-update-ref
+  → Set REF_PATH = /tmp/chati-update-ref
+```
+
+---
+
+## Phase 1: SCAN — Deep Analysis of Reference Repo (Sub-Agent)
+
+Launch a **Task agent (subagent_type=Explore, thoroughness=very thorough)** to analyze the reference repo at REF_PATH.
+
+### SCAN Agent Instructions:
+
+```
+Analyze the repo at <REF_PATH> exhaustively. You must produce a comprehensive report covering:
+
+1. **PROJECT OVERVIEW**
+   - What does this project do?
+   - Tech stack, language, framework
+   - Project maturity (commits, stars, contributors if visible)
+   - License
+
+2. **ARCHITECTURE PATTERNS**
+   - Folder structure and organization philosophy
+   - Module/plugin/agent system (if any)
+   - Configuration patterns (YAML, JSON, env)
+   - CLI patterns and entry points
+
+3. **INTERESTING CONCEPTS** (the gold — be thorough)
+   - Novel patterns not commonly seen
+   - Quality gates, validation systems
+   - Context management strategies
+   - Agent/AI orchestration patterns
+   - Pipeline/workflow patterns
+   - Memory/state management
+   - Error handling patterns
+   - Testing strategies
+   - Documentation patterns
+   - Hook/plugin systems
+   - CI/CD patterns
+
+4. **CODE QUALITY SIGNALS**
+   - Test coverage approach
+   - Linting/formatting standards
+   - Type safety patterns
+   - Security patterns
+
+5. **SPECIFIC ARTIFACTS** — For each interesting file/pattern:
+   - File path
+   - What it does
+   - Why it's interesting
+   - Key code snippets (actual content, not summaries)
+
+Be EXHAUSTIVE. Read every important file. Don't summarize — extract actual patterns with code.
+Minimum 30 files analyzed. No laziness.
+```
+
+---
+
+## Phase 2: COMPARE — Cross-Reference with Chati.dev (Sub-Agent)
+
+Launch **in parallel** with Phase 1 a **Task agent (subagent_type=Explore, thoroughness=very thorough)** to map chati.dev's current state.
+
+### COMPARE Baseline Agent Instructions:
+
+```
+Map the COMPLETE current state of chati.dev. Analyze:
+
+1. **CONSTITUTION** — Read chati.dev/constitution.md fully. Extract:
+   - All 19 articles with key rules
+   - Quality thresholds
+   - Governance patterns
+
+2. **ALL AGENTS** — Read every file in chati.dev/agents/**/*.md:
+   - Agent identity, role, pipeline position
+   - Input/output contracts
+   - Acceptance criteria
+   - Key patterns each agent uses
+
+3. **ORCHESTRATOR** — Read chati.dev/orchestrator/chati.md fully:
+   - Routing logic
+   - Session management
+   - Deviation handling
+
+4. **WORKFLOWS** — Read chati.dev/workflows/*.yaml:
+   - Workflow definitions
+   - Step sequences
+   - Gate conditions
+
+5. **SCHEMAS** — Read chati.dev/schemas/*.json:
+   - Session schema
+   - Handoff schema
+   - Config schema
+
+6. **HOOKS** — Read packages/chati-dev/src/**/*:
+   - All 6 hooks
+   - PRISM engine
+   - Mode governance
+   - Build loop / autonomy system
+
+7. **TESTS** — Map test structure:
+   - Test organization
+   - Coverage patterns
+   - Key test utilities
+
+8. **CONFIG** — Read chati.dev/config.yaml, package.json:
+   - Version info
+   - Dependencies
+   - Scripts
+
+Produce a COMPLETE inventory. Every file, every pattern, every decision.
+This is the baseline for comparison. Be thorough.
+```
+
+---
+
+## Phase 3: CROSS-ANALYZE — Merge Findings
+
+Once both sub-agents complete, YOU (main agent) perform the cross-analysis:
+
+### For EACH finding from the SCAN:
+
+```yaml
+finding: <name>
+source_repo: <file path in reference repo>
+category: architecture | quality | testing | docs | patterns | tooling | governance
+classification: ADOPT | ADAPT | IGNORE | ALREADY_EXISTS
+reasoning: <why this classification>
+chati_equivalent: <existing chati.dev file/pattern if any, or "none">
+impact: high | medium | low
+effort: high | medium | low
+priority_score: <impact * inverse_effort, 1-10>
+implementation_notes: <how to implement in chati.dev context>
+constitution_check: <which articles are relevant, any conflicts>
+```
+
+### Classification Rules:
+- **ADOPT**: Novel concept, no equivalent in chati.dev, high value, no conflicts
+- **ADAPT**: Similar concept exists but reference has better implementation
+- **IGNORE**: Not relevant, conflicts with constitution, or low value
+- **ALREADY_EXISTS**: Chati.dev already has this (possibly better)
+
+---
+
+## Phase 4: PROPOSE — Present to User
+
+Generate a structured report for the user:
+
+```markdown
+# Chati Update Report: <repo-name>
+
+## Summary
+- Findings analyzed: N
+- ADOPT: N items
+- ADAPT: N items
+- ALREADY_EXISTS: N items
+- IGNORE: N items
+
+## Recommendations (sorted by priority_score desc)
+
+### ADOPT — New Concepts Worth Adding
+
+1. **<Finding Name>** (Priority: X/10)
+   - **What**: <description>
+   - **Why**: <value to chati.dev>
+   - **Where**: <which chati.dev files would change>
+   - **Effort**: <high/medium/low>
+   - **Constitution**: <compatible with articles X, Y>
+
+2. ...
+
+### ADAPT — Existing Concepts Worth Improving
+
+1. **<Finding Name>** (Priority: X/10)
+   - **Current**: <how chati.dev does it today>
+   - **Improvement**: <what the reference does better>
+   - **Where**: <which files to modify>
+   - **Effort**: <high/medium/low>
+
+2. ...
+
+### ALREADY_EXISTS — Chati.dev Already Has This
+(brief list for transparency)
+
+### IGNORE — Not Applicable
+(brief list with reasons)
+```
+
+Then ask the user:
+> "Which items do you want me to implement? Give me the numbers (e.g., 'ADOPT 1, 3' and 'ADAPT 2') or say 'all ADOPT' / 'all'."
+
+---
+
+## Phase 5: APPLY + RALPH — Self-Validated Implementation
+
+For the approved changes, enter ralph-wiggum mode:
+
+### Pre-Ralph Checklist:
+1. Run current tests: `npm test` — record baseline (must be green)
+2. Run lint: `npm run lint` — record baseline
+3. Git status — ensure clean working directory
+4. Create branch: `git checkout -b chati-update/<repo-name>-<date>`
+
+### Ralph Loop Activation:
+
+Use `/ralph-loop` with the following prompt structure:
+
+```
+/ralph-loop "Implement the following approved chati-update changes:
+
+<LIST OF APPROVED CHANGES WITH FULL DETAILS>
+
+REQUIREMENTS:
+1. Implement each change following chati.dev patterns and conventions
+2. Respect the constitution (19 articles) — especially originality
+3. Update relevant tests for each change
+4. Run full test suite after each change — ALL must pass
+5. Run lint after each change — must be clean
+6. Validate against constitution rules
+7. Each change must score >= 95% on self-validation
+
+SELF-VALIDATION CHECKLIST (must ALL be true):
+- [ ] All existing tests pass (989+)
+- [ ] New tests added for new functionality
+- [ ] Lint passes with zero errors
+- [ ] No external framework references (originality 100%)
+- [ ] Constitution articles respected
+- [ ] No regressions in any agent definitions
+- [ ] Handoff format maintained
+- [ ] PRISM layers intact
+- [ ] Config/schemas updated if needed
+- [ ] CHANGELOG updated
+
+When ALL items are validated at >= 95%, output:
+<promise>ALL CHANGES VALIDATED AT 95%</promise>" --completion-promise "ALL CHANGES VALIDATED AT 95%" --max-iterations 15
+```
+
+---
+
+## Phase 6: REPORT — Final Summary
+
+After ralph-wiggum completes, generate final report:
+
+```markdown
+# Chati Update Complete
+
+## Changes Applied
+- <list of implemented changes with file paths>
+
+## Validation Results
+- Tests: X passing (was Y before)
+- Lint: clean
+- Constitution: no violations
+- Self-validation score: X%
+
+## Files Modified
+- <file list with brief description of changes>
+
+## Files Created
+- <if any>
+
+## Next Steps
+- <any follow-up recommendations>
+```
+
+---
+
+## Error Handling
+
+- **Clone fails**: Ask user for correct URL/path, suggest alternatives
+- **Tests fail at baseline**: STOP — do not proceed with changes on a broken baseline. Report to user.
+- **Ralph stuck (> 10 iterations without progress)**: Break loop, report what was achieved, ask user for guidance
+- **Constitution conflict detected**: STOP that specific change, report conflict, ask user for deviation approval
+- **Sub-agent returns incomplete data**: Re-run that specific sub-agent with more specific instructions
+
+---
+
+## Anti-Patterns (NEVER do these)
+
+- Don't copy code verbatim from reference repo
+- Don't rename chati.dev concepts to match reference repo naming
+- Don't add dependencies from reference repo without explicit approval
+- Don't modify the constitution
+- Don't skip the comparison phase ("it looks good, let's just add it")
+- Don't implement without user approval of the proposal
+- Don't rush — thoroughness > speed

package/framework/orchestrator/chati.md

@@ -94,51 +94,40 @@ CRITICAL → "Context: CRITICAL ({remaining}%) — Initiating handoff protocol"
 
 ## Action: Setup
 
-The user is starting a new project.
+The user is starting a new project. The orchestrator handles all setup decisions automatically — the user should NOT be asked to choose workflows, pipelines, or technical options. They just describe what they want to build.
 
-### Quick Flow Auto-Detection
+### Automatic Detection
 
-Before asking for workflow, check if this is a quick-flow candidate:
-```
-Run: node packages/chati-dev/bin/chati.js orchestrate detect-flow --message "{user_first_message}"
-```
-
-If `recommended` is `quick` (confidence >= 0.8):
-  → Present: "This looks like a quick task. I can use Quick Flow (fast-track):
-     Brief (quick) → Dev → QA → Deploy
-     1. Use Quick Flow (Recommended)
-     2. Use full pipeline instead"
-
-If `recommended` is `standard`:
-  → Present: "This looks like a medium feature. Standard Flow recommended:
-     Brief → Detail → Architect → Tasks → QA-Planning → Dev → QA → Deploy
-     1. Use Standard Flow (Recommended)
-     2. Use full pipeline instead"
-
-### Project Setup
-
-1. **Project type**: Does an existing codebase exist?
+1. **Project type**: Detect automatically.
    - Check for `package.json`, `src/`, `.git`, etc.
    - If exists → `brownfield`. If not → `greenfield`.
-   - If ambiguous, ask: "Is this a new project or an existing one?"
+   - Only ask if truly ambiguous (no signals at all).
 
 2. **Language**: Detect from user's message language.
    - Supported: `en`, `pt`, `es`, `fr`. Default: `en`.
 
-3. **Workflow**: Use auto-detected or ask user:
+3. **Workflow**: Decide automatically based on context. NEVER present workflow options to the user.
    ```
-   1. Full Pipeline (Recommended for new features, greenfield)
-   2. Quick Flow (Bug fixes, small changes, hotfixes)
-   3. Standard Flow (Medium features, no UX/architecture needed)
+   Run: node packages/chati-dev/bin/chati.js orchestrate detect-flow --message "{user_first_message}"
    ```
+   Use the `recommended` field directly:
+   - `quick` (confidence >= 0.8) → workflow = `quick`
+   - `standard` (confidence >= 0.8) → workflow = `standard`
+   - Otherwise → workflow = `full`
+
+4. **Project name**: Extract from user's message or directory name. Only ask if undetectable.
+
+### Initialize
 
-Then run via Bash:
+Run via Bash:
 ```
-node packages/chati-dev/bin/chati.js orchestrate init --type greenfield --language pt --name "project-name" --workflow full
+node packages/chati-dev/bin/chati.js orchestrate init --type {detected_type} --language {detected_lang} --name "{detected_name}" --workflow {detected_workflow}
 ```
 
 Parse JSON → read `first_agent_file` → activate that agent immediately (go to **Action: Interactive Agent**).
 
+The user should experience a smooth start: they describe their project, the orchestrator confirms what it detected, and the first agent begins immediately.
+
 ---
 
 ## Action: Interactive Agent
@@ -154,11 +143,61 @@ These agents (greenfield-wu, brownfield-wu, brief) run in the same conversation.
 3. Load its full content and **become** that agent
 4. Follow the agent's instructions — the user interacts with you directly
 5. When the agent completes its work and self-validates, extract the score
-6. Run via Bash:
+6. Present **Completion Options** (see below) — wait for user choice before advancing
+7. On user approval, run via Bash:
    ```
    node packages/chati-dev/bin/chati.js orchestrate advance --agent {name} --score {score}
    ```
-7. Parse JSON → the `next` field contains the next action → follow it
+8. Parse JSON → the `next` field contains the next action → follow it
+
+---
+
+## Completion Options (Protocol 3 — Guided Options)
+
+After EVERY agent completes (interactive or autonomous), present exactly 3 numbered options. The user should never have to figure out "what now" — always offer clear next steps with a recommendation.
+
+### Standard Completion (score >= threshold)
+```
+{agent} completed with score {score}%.
+
+1. Approve and continue to {next_agent} (Recommended)
+2. Review the artifacts before proceeding
+3. Revise — go back and adjust specific points
+```
+
+### Low Score Completion (score < threshold but not blocking)
+```
+{agent} completed with score {score}% (below {threshold}% threshold).
+
+1. Revise — re-run {agent} to improve quality (Recommended)
+2. Approve anyway and continue to {next_agent}
+3. Review the artifacts and decide
+```
+
+### Parallel Group Completion
+```
+Parallel group completed: {agents with scores}.
+
+1. Approve all and continue to {next_agent} (Recommended)
+2. Review artifacts from a specific agent
+3. Re-run a specific agent for improvements
+```
+
+### Pipeline Milestone (after QA-Planning or QA-Implementation)
+```
+Quality gate passed: {score}%.
+
+1. Approve and advance to {next_phase} (Recommended)
+2. View detailed QA report
+3. Request additional review on specific areas
+```
+
+**Rules:**
+- ALWAYS present options — never leave the user without a clear next step
+- ALWAYS mark one option as "(Recommended)"
+- User can respond with just the number (1, 2, or 3)
+- If user responds with free text instead of a number, interpret their intent and act accordingly
+- Keep options in the user's language
 
 ---
 
@@ -179,7 +218,7 @@ These agents run in separate Claude Code processes.
    - If `true`: display "Context check: OK — handoff verified"
 3. Execute `spawn_command` via Bash tool (the full command is in the JSON)
 4. Wait for JSON output from the spawned process. Handle `status`:
-   - `"complete"` → Run `orchestrate advance --agent {name} --score {score}`
+   - `"complete"` → Present **Completion Options** (see above) → on approval, run `orchestrate advance --agent {name} --score {score}`
    - `"needs_input"` → Read `needs_input_question`, present to user in their language, then re-run spawn with `--additional-context "{user_response}"` (max 3 relay cycles)
    - `"error"` → Apply Recovery Protocol (see below)
 
@@ -201,8 +240,9 @@ Planning phase agents (detail, architect, ux) run simultaneously.
 1. Display: "Spawning parallel group: {agents}"
 2. Execute `parallel_spawn_command` via Bash tool
 3. Parse consolidated JSON output
-4. For each completed agent, run `orchestrate advance --agent {name} --score {score}`
-5. If partial failure:
+4. Present **Completion Options** (Parallel Group variant) — wait for user choice
+5. On approval, for each completed agent, run `orchestrate advance --agent {name} --score {score}`
+6. If partial failure:
    ```
    1. Retry failed agents only
    2. Continue with partial results

package/framework/schemas/session.schema.json

@@ -80,7 +80,7 @@
     },
     "agents": {
       "type": "object",
-      "description": "Status tracking for all 12 specialized agents",
+      "description": "Status tracking for all specialized agents",
       "patternProperties": {
         ".*": {
           "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chati-dev",
-  "version": "4.1.0",
+  "version": "4.1.2",
   "description": "AI-Powered Multi-Agent Orchestration System — Structured vibe coding for Full Stack Development",
   "type": "module",
   "bin": {

package/scripts/doctor/checks/agents.js

@@ -1,7 +1,7 @@
 /**
  * @fileoverview Doctor check: Agent definition files.
  *
- * Validates that all 13 agent definition files exist with valid structure.
+ * Validates that all primary agent definition files exist with valid structure.
  */
 
 import { readFileSync, existsSync } from 'fs';

package/scripts/health-check.js

@@ -139,7 +139,7 @@ function checkConstitution(frameworkDir) {
 }
 
 /**
- * Check that all 13 agent definition files exist with valid structure.
+ * Check that all primary agent definition files exist with valid structure.
  */
 function checkAgents(frameworkDir) {
   const agentsDir = join(frameworkDir, 'agents');