hablas-ai 1.3.19 → 1.3.20

package/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.3.20] — 2026-06-12 · Stable Runtime Recovery
+
+### Changed
+- Removed public mode-era commands from the stable CLI surface:
+  - `hablas build`
+  - `hablas design`
+  - `hablas ask`
+  - `/mode`
+- Re-centered the product around a **single command surface**:
+  - `hablas`
+  - `hablas run "..."`
+- Replaced visible mode thinking with an internal unified runtime model based on:
+  - `executionPath: direct | team`
+  - `taskKind: conversation | analysis | implementation`
+- Updated the interactive REPL and non-interactive `run` command to enter through the unified runtime path first.
+- Simplified setup and help messaging to match the stable mental model.
+
+### Removed
+- Hidden gate-based routing from the active stable-line code path.
+- Gate defaults from agent model configuration.
+- Gate mindset registration from the built-in mindset registry.
+
+### Added
+- Unified runtime regression smoke tests covering:
+  - direct casual handling
+  - direct quick questions
+  - team analysis routing
+  - continuity routing
+  - one-step delivery routing
+- Stable runtime recovery documentation in:
+  - `docs/stable-runtime-recovery-plan-2026-06-12.md`
+
+### Verified
+- `npm test` passes
+- `npm run build` passes
+- CLI help no longer exposes removed public mode commands
+
 ## [1.0.0] — 2026-05-31 · **First Public Release**
 
 The first formal, polished, production-ready release of Hablas CLI. Months of

package/README.md

@@ -4,12 +4,12 @@
 
 **Premium multi-agent AI coding agent for your terminal**
 
-Local-first · Cloud-compatible · Watch the team work in front of you
+Local-first · Cloud-compatible · One command surface · Internal specialist coordination
 
 *by [Abdulmoin Hablas](https://portfolio-monopoly63s-projects.vercel.app/)*
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-1.0.0-gold.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-1.3.20-gold.svg)](CHANGELOG.md)
 [![Node.js](https://img.shields.io/badge/Node.js-20%2B-green.svg)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.5-blue.svg)](https://www.typescriptlang.org)
 
@@ -19,47 +19,47 @@ Local-first · Cloud-compatible · Watch the team work in front of you
 
 ## ✦ Overview
 
-**Hablas** is a multi-agent AI development system that runs in your terminal.
-Unlike single-model assistants, Hablas leads a **team of specialists** —
-Emma (Product), Bob (Architect), Alex (Engineer), David (Analyst) — and
-**you watch them collaborate live**, in character, while Hablas (the Team
-Leader) remains your single point of contact.
+**Hablas** is a terminal AI development system with a **single user-facing agent** and an **internal team of specialists**.
 
-It runs **locally via Ollama**, or against **any OpenAI-compatible API**
-(NVIDIA NIM, OpenAI, Groq, Together, OpenRouter, and more).
+You talk only to **Hablas**. Internally, Hablas can coordinate:
+- **Emma** for product framing and requirements
+- **Bob** for architecture and systems design
+- **Alex** for implementation and debugging
+- **David** for research and supporting analysis
 
-### ✨ What makes v1.0.0 different
+The current stable direction is intentionally simple:
+- no visible mode system
+- no hidden theatrical router persona
+- one unified runtime that decides, internally and honestly, between:
+  - **direct leader handling** for simple turns
+  - **coordinated team execution** for serious engineering work
 
-- **Live Team Theatre** — see the team handoff tasks, think, run tools,
-  and review each other's work in real time, with an executive-silver TUI.
-- **Hablas-only conversation** — you talk to one leader; the rest is theatre.
-- **Persona-faithful** — each agent stays in their distinctive voice
-  (Hablas is INTJ-direct, Bob is methodical, Alex is pragmatic, …).
-- **Token-bounded dialogue** — the inter-agent chat is capped and
-  gracefully falls back to deterministic lines when offline.
+Hablas runs **locally via Ollama**, or against **any OpenAI-compatible API**
+including **NVIDIA NIM**, OpenAI, Groq, Together, OpenRouter, and others.
+
+### ✨ Stable-line principles
+
+- **Single command surface** — use `hablas` interactively or `hablas run "..."` non-interactively.
+- **Architectural honesty** — routing is internal runtime behavior, not a public mode maze.
+- **Leader-first UX** — the user speaks to Hablas only; specialists stay internal.
+- **Real execution paths** — direct turns use the main agentic loop; coordinated turns use the internal team.
+- **Continuity-aware** — unfinished project requests can stay on the team path and reuse context.
+- **One-step delivery support** — requests like “finished project, no questions” preserve a dedicated internal flag.
 
 ### Key Features
 
-- **Multi-Agent System** — 5 specialized agents with their own mindsets
-  and (optionally) their own models per role.
-- **T-shirt Sizing** — XS/S/M/L/XL routing so a "hi" doesn't trigger a plan.
-- **Plan Approval** — for L/XL tasks, you approve / edit / skip before exec.
-- **Dual Provider** — Ollama (local), NVIDIA NIM, or any
-  OpenAI-compatible API. Switch live with `/provider`.
-- **Dynamic Model Discovery** — `/models` lists everything your API exposes.
-- **Agentic Loop** — multi-step tool execution with auto-retry,
-  smart abort, and recovery hints.
-- **15+ Built-in Tools** — file ops, shell, codebase search, web search,
-  web scraping, PDF reading, code execution, bug detection, and more.
-- **Smart Context** — project-aware prompts, memory with categories and
-  importance decay, shared notebook, auto-injection of mentioned files.
-- **Premium TUI** — executive-silver theme, spinners, progress, plan
-  boxes, session summaries.
-- **Three-tier safety** — `safe / confirm / dangerous` per tool.
-- **Ctrl+C UX** — single = cancel current op, double = exit cleanly.
-- **Auto Mode** — `--auto` skips tool confirmations for scripting
-  (plan approval still required).
-- **Checkpoints & Undo** — `/checkpoint save|restore`, `/undo`.
+- **Unified Runtime** — one internal runtime decides `direct` vs `team` execution.
+- **Multi-Agent Coordination** — Hablas can internally orchestrate Emma, Bob, Alex, and David.
+- **Dual Provider** — Ollama (local), NVIDIA NIM, or any OpenAI-compatible API.
+- **Dynamic Model Discovery** — `/models` lists everything your provider exposes.
+- **Agentic Loop** — multi-step tool execution with retries, tool safety, and recovery hints.
+- **Built-in Tools** — file ops, shell, codebase search, web search, scraping, PDF reading, code execution, and more.
+- **Smart Context** — project-aware prompts, persistent memory, shared notebook, and file auto-injection.
+- **Premium TUI** — executive-silver terminal UI with team rendering and status components.
+- **Three-tier safety** — `safe / confirm / dangerous` tool policy behavior.
+- **Ctrl+C UX** — single press cancels the current op, double press exits cleanly.
+- **Auto Mode** — `--auto` skips tool confirmations when appropriate.
+- **Checkpoints & Undo** — `/checkpoint ...`, `/undo ...`.
 - **Team Mode** — optional Supabase + Git-based locks and presence sync.
 
 ---
@@ -71,7 +71,7 @@ git clone https://github.com/Monopoly63/mobile-bot.git
 cd mobile-bot/flowagent
 npm install
 npm run build
-npm link        # exposes the `hablas` command globally
+npm link
 ```
 
 ### Requirements
@@ -82,7 +82,11 @@ npm link        # exposes the `hablas` command globally
   - An **OpenAI-compatible API** key
   - **NVIDIA NIM** API key
 
-First run launches a setup wizard. You can re-run it anytime with `hablas --setup`.
+First run launches a setup wizard. You can re-run it anytime with:
+
+```bash
+hablas --setup
+```
 
 ---
 
@@ -92,7 +96,10 @@ First run launches a setup wizard. You can re-run it anytime with `hablas --setu
 # Interactive REPL
 hablas
 
-# One-shot command
+# Interactive REPL with auto-confirm for tools
+hablas --auto
+
+# One-shot unified runtime execution
 hablas run "refactor src/auth.ts to use bcrypt"
 
 # Generate a commit message from staged changes
@@ -107,6 +114,27 @@ hablas doctor
 
 ---
 
+## ✦ Mental Model
+
+Hablas no longer exposes public modes like `build`, `design`, or `ask`.
+
+Instead, every request goes through one internal runtime:
+
+1. **User input**
+2. **Unified runtime routing**
+3. **Direct leader path** *or* **coordinated team path**
+4. **Final answer from Hablas**
+
+Examples:
+
+- `hi` → direct reply
+- `what is the current version of this project?` → direct reply
+- `design the architecture for auth` → team analysis path
+- `continue the unfinished flower store project` → team continuity path
+- `just give me the finished project in one step no questions` → team one-step delivery path
+
+---
+
 ## ✦ Commands Reference
 
 ### Core Slash Commands
@@ -117,7 +145,7 @@ hablas doctor
 | `/about` · `/version` | Identity & version info |
 | `/team` · `/agents` | Team roster · multi-agent system status |
 | `/agents on\|off\|status\|models` | Toggle and inspect agents |
-| `/delegate <agent> <task>` | Manually assign a task to one agent |
+| `/delegate <agent> <task>` | Manually assign a task to one visible specialist |
 | `/mindset <name>` · `/mindsets` | Switch / list agent mindsets |
 | `/clear` · `/history [n]` | Reset context · show recent turns |
 | `/status` · `/quit` | Show status · exit |
@@ -127,7 +155,7 @@ hablas doctor
 | Command | Description |
 |---|---|
 | `/model [name]` | Show or switch the active model |
-| `/models [page\|query]` | Browse available models (paged + search) |
+| `/models [page\|query]` | Browse available models |
 | `/provider [ollama\|nvidia\|custom\|test]` | Switch / test the provider |
 | `/addmodel` · `/listmodels` · `/usemodel <name>` · `/removemodel <name>` | Manage saved provider profiles |
 
@@ -149,18 +177,18 @@ hablas doctor
 | Command | Description |
 |---|---|
 | `/memory [set\|del\|search\|clear]` | Persistent project memory |
-| `/learn "<preference>"` | Teach the agent a preference (importance: 9) |
+| `/learn "<preference>"` | Teach the agent a preference |
 | `/context [set\|get\|del\|decisions\|clear]` | Cross-agent shared notebook |
-| `/plan status\|finish\|next\|reset` | Inspect the active plan |
+| `/plan status\|finish\|next\|reset` | Inspect the active plan state if one exists |
 
 ### Plugins & Diagnostics
 
 | Command | Description |
 |---|---|
-| `/plugins [enable\|disable]` | Manage plugins (~/.hablas/plugins/) |
+| `/plugins [enable\|disable]` | Manage plugins (`~/.hablas/plugins/`) |
 | `/alias [set\|del]` | Custom command aliases |
 | `/doctor` | System diagnostics |
-| `/session save\|list` | Save/load conversation state |
+| `/session save\|list\|load` | Save/load conversation state |
 
 ---
 
@@ -172,12 +200,12 @@ hablas doctor
 | `-p, --project <path>` | Set the working directory |
 | `--provider <ollama\|custom\|nvidia>` | Choose LLM provider |
 | `--api-url <url>` · `--api-key <key>` | Configure custom/NVIDIA provider |
-| `--auto` | Skip tool confirmations (plan approval still required) |
+| `--auto` | Skip tool confirmations where allowed |
 | `--timeout <ms>` | Per-request timeout (default 120000) |
 | `--theme <dark\|light\|galaxy\|ocean\|forest>` | UI theme |
 | `--team --user <name> --team-key <pwd>` | Enable Team Mode |
 | `--setup` | Run the first-time wizard |
-| `hablas run "<prompt>"` | Non-interactive single shot |
+| `hablas run "<prompt>"` | Non-interactive unified runtime execution |
 | `hablas commit` · `pr` · `changelog` | Git intelligence sub-commands |
 | `hablas info` · `doctor` · `security` · `stats` | Project insights |
 | `hablas api --port 8080` | Start the REST API server |
@@ -191,10 +219,10 @@ hablas doctor
 | `read_file`, `list_dir`, `get_file_info` | Read filesystem | safe |
 | `write_file`, `edit_file`, `patch_file`, `append_to_file`, `search_and_replace` | Mutate files | confirm |
 | `delete_file`, `move_file`, `create_dir` | Manage paths | dangerous / confirm |
-| `run_command` | Shell execution (with timeout + blocklist) | dangerous |
-| `search_codebase` | Ripgrep-style search | safe |
+| `run_command` | Shell execution (timeout + blocklist) | dangerous |
+| `search_codebase` | Codebase search | safe |
 | `detect_bugs` | Static analysis | safe |
-| `web_search` | DuckDuckGo search | safe |
+| `web_search` | Web search | safe |
 | `scrape_url`, `extract_links` | HTML scraping | safe |
 | `read_pdf`, `pdf_metadata` | PDF reading | safe |
 | `execute_code` | Sandboxed code execution | confirm |
@@ -203,7 +231,7 @@ hablas doctor
 
 ## ✦ Configuration
 
-Config lives at **`~/.hablas/config.json`**. Sub-files:
+Config lives at **`~/.hablas/config.json`**.
 
 | File | Purpose |
 |---|---|
@@ -217,25 +245,18 @@ Config lives at **`~/.hablas/config.json`**. Sub-files:
 
 ---
 
-## ✦ The Multi-Agent Team
+## ✦ The Internal Team
 
-| Agent | Title | Role | Voice |
-|---|---|---|---|
-| **★ Hablas** | Team Leader | Coordination, planning, synthesis, the only one you talk to | INTJ, authoritative, terse |
-| **◆ Emma** | Product Manager | Requirements, PRDs, user stories | Calm, structured |
-| **◆ Bob** | Architect | System design, schemas, contracts, peer-reviews Alex | Methodical, principled |
-| **◆ Alex** | Engineer | Implementation, debugging, tests | Pragmatic, action-biased |
-| **◆ David** | Data Analyst | Research, documentation, comparisons | Factual, evidence-driven |
-
-Routing is automatic and complexity-aware (T-shirt sizing):
-
-| Size | Trigger | Behavior |
+| Agent | Title | Primary Responsibility |
 |---|---|---|
-| **XS** | Greetings, casual chat | Hablas replies directly, no tools |
-| **S** | Single clear question | Single agent, no plan |
-| **M** | Single focused task | Live theatre, one specialist + Hablas synthesis |
-| **L** | Multi-step, multi-concern | Plan → approval → live theatre with peer review |
-| **XL** | Full system / feature | XL plan (Emma writes PRD first) → approval → full theatre |
+| **★ Hablas** | Team Leader | User interface, routing, synthesis, final delivery |
+| **◆ Emma** | Product Manager | Requirements, framing, PRDs, scope |
+| **◆ Bob** | Architect | Architecture, structure, trade-offs |
+| **◆ Alex** | Engineer | Implementation, debugging, code changes |
+| **◆ David** | Data Analyst | Research, comparisons, supporting analysis |
+
+The user speaks to **Hablas only**.
+The rest of the team is an internal execution system.
 
 ---
 
@@ -245,10 +266,13 @@ Routing is automatic and complexity-aware (T-shirt sizing):
 # Read, then edit
 > read src/auth.ts and add JWT validation
 
-# Multi-step (triggers L flow)
-> design and implement a /users endpoint with tests
+# Architecture-heavy request
+> design the architecture for a /users endpoint with tests and clear module boundaries
+
+# Continuity request
+> continue the unfinished flower store project from the previous PRD
 
-# Specific agent
+# Specific visible specialist
 > /delegate bob design the cache layer for the search API
 
 # Git workflow
@@ -265,14 +289,14 @@ Routing is automatic and complexity-aware (T-shirt sizing):
 
 ## ✦ Architecture
 
-```
+```text
 src/
-├── repl/          REPL loop, slash commands, TUI, live theatre
-├── agents/        Orchestrator, conductor, runner, channel, dialogue
-├── planner/       T-shirt sizing, plan lifecycle, task queue
-├── llm/           Unified provider (Ollama/Custom/NVIDIA), tool parser v2
+├── repl/          REPL loop, slash commands, terminal rendering
+├── agents/        Agent runner, conductor, channel, shared execution engine
+├── runtime/       Unified router, contracts, planner, state, reviewer
+├── llm/           Unified provider layer (Ollama/Custom/NVIDIA)
 ├── mindset/       Per-agent system prompts
-├── tools/         Tool registry + 15 built-in tools
+├── tools/         Tool registry + built-in tools
 ├── context/       Session, memory, shared notebook, auto-inject
 ├── config/        Defaults + JSON loader
 ├── collaboration/ Optional Team Mode (Supabase + Git locks)
@@ -284,21 +308,42 @@ src/
 └── utils/         logger, diff, tokens
 ```
 
-74 TypeScript files, ~21,000 LOC, `strict` mode, zero `@ts-ignore`,
-zero unused locals/parameters.
+Stable-line architecture focus:
+- **one runtime entry**
+- **direct vs team execution path**
+- **single leader UX**
+- **no public mode system**
 
 ---
 
 ## ✦ Development
 
 ```bash
-npm install        # install deps
-npm run build      # tsc → dist/
-npm run lint       # tsc --noEmit
-npm test           # run the channel unit tests
-npm run dev -- run "your prompt"  # dev mode without build
+npm install
+npm run build
+npm run lint
+npm test
+npm run dev -- run "your prompt"
 ```
 
+Current automated verification includes:
+- agent channel tests
+- execution parity tests
+- unified runtime routing regression tests
+
+---
+
+## ✦ Documentation Notes
+
+Some older design documents in `docs/` describe intermediate runtime experiments
+such as visible modes or hidden gate-based routing.
+
+For the current stable direction, start with:
+- `docs/stable-runtime-recovery-plan-2026-06-12.md`
+
+Treat older redesign / migration docs as **historical context**, not as the
+current product surface.
+
 ---
 
 ## ✦ Author