opalacoder 0.1.3__tar.gz → 0.1.5__tar.gz

opalacoder-0.1.5/.claude/rules/RULES.md

@@ -0,0 +1,20 @@
+# Regras para Analises dadas Questões do Usuário
+1. **Relevância**: As análises devem ser diretamente relevantes à questão do usuário, abordando os pontos específicos levantados e evitando informações desnecessárias.
+
+2. Nunca levante hipóteses ou suposições sem base sólida. Se a questão do usuário for ambígua, peça esclarecimentos antes de fornecer uma análise. Realize testes para validar/excluir/confirmar hipóteses, e baseie suas análises nos resultados desses testes. Não invente testes fáceis de passar ou que não testem o que você diz que testam.
+
+# Regras de Diagnóstico de Testes
+1. **Cobertura de Código**: Assegure-se de que os testes cubram pelo menos 80% do código, incluindo casos de borda e cenários de falha.
+
+2. **Isolamento**: Cada teste deve ser independente e não depender de outros testes ou do estado global. Use mocks e stubs para isolar as unidades de código.
+
+2. **Repetibilidade**: Os testes devem produzir os mesmos resultados em execuções subsequentes, independentemente da ordem de execução ou do ambiente.
+
+3. **Clareza**: Os testes devem ser claros e fáceis de entender. Use nomes descritivos para os testes e organize-os de maneira lógica.
+
+
+# Regras de Organização de Testes
+Nunca gere arquivos de teste soltos na raiz do projeto. Use o diretório `tests/` para organizar os testes por funcionalidade ou módulo.
+
+# Regras de Nomenclatura de Testes
+Siga a convenção de nomenclatura `test_<nome_da_funcionalidade>.py` para arquivos de teste. Dentro dos arquivos, nomeie as funções de teste com o prefixo `test_` seguido de uma descrição clara do que está sendo testado, por exemplo, `test_calculo_soma()`.

{opalacoder-0.1.3 → opalacoder-0.1.5}/.claude/settings.json

@@ -11,7 +11,8 @@
       "Bash(python -m pytest tests/ -q --ignore=tests/test_planner_output.py --ignore=tests/test_agent_config.py -k \"not llm and asyncio\")",
       "Bash(python -m pytest tests/ -q --ignore=tests/test_planner_output.py --ignore=tests/test_agent_config.py -k \"not llm\")",
       "Bash(python -m pytest tests/test_workflow_pipeline.py tests/test_verification_strategies.py -q -k \"asyncio or \\(not llm\\)\")",
-      "Bash(python -m pytest tests/ -x -q)"
+      "Bash(python -m pytest tests/ -x -q)",
+      "Bash(python -c \"from opalacoder.cli_commands import _registry, REPLState; print\\('OK'\\); print\\([k for k in _registry._cmds]\\)\")"
     ],
     "additionalDirectories": [
       "/home/gilzamir"

{opalacoder-0.1.3 → opalacoder-0.1.5}/CLAUDE.md

@@ -21,8 +21,7 @@ Key things to understand from that repo:
 
 ## Project Context
 
-Read `ARCH_SUMMARY.md` before making changes. It contains the current project status,
-known issues, and decisions already made. Do not re-litigate what is documented there.
+Read `docs/specs` before making changes. It contains the current project status, known issues, and decisions already made. Do not re-litigate what is documented there.
 
 ## Build & Test Commands
 Run tests on tests dir after you implement a new feature.

{opalacoder-0.1.3 → opalacoder-0.1.5}/GEMINI.md

@@ -21,8 +21,7 @@ Key things to understand from that repo:
 
 ## Project Context
 
-Read `ARCH_SUMMARY.md` before making changes. It contains the current project status,
-known issues, and decisions already made. Do not re-litigate what is documented there.
+Read `docs/specs` before making changes. It contains the current project status, known issues, and decisions already made. Do not re-litigate what is documented there.
 
 ## Build & Test Commands
 Run tests on tests dir after you implement a new feature.

opalacoder-0.1.5/PKG-INFO

@@ -0,0 +1,288 @@
+Metadata-Version: 2.4
+Name: opalacoder
+Version: 0.1.5
+Summary: Autonomous coding agent with interactive planning and modular execution
+Project-URL: Homepage, https://github.com/gilzamir/OpalaCoder
+Project-URL: Bug Tracker, https://github.com/gilzamir/OpalaCoder/issues
+Author-email: Gil Zamir <gilzamir@example.com>
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: agenticblocks-io>=0.8.37
+Requires-Dist: chromadb>=0.4.0
+Requires-Dist: instructor>=1.15.1
+Requires-Dist: litellm>=1.40.0
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pywebview>=4.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tree-sitter-language-pack>=1.8.0
+Requires-Dist: tree-sitter>=0.25.0
+Provides-Extra: embeddings
+Requires-Dist: sentence-transformers>=3.0.0; extra == 'embeddings'
+Description-Content-Type: text/markdown
+
+# OpalaCoder
+
+**OpalaCoder** is an autonomous coding agent built on the **[AgenticBlocks.IO](https://github.com/gilzamir/agenticblocks)** framework. It features a project-centric context model and a modular, skills-oriented architecture optimized to run efficiently with local LLMs.
+
+---
+
+## Core Architecture & Features
+
+### 1. Project-Centric Context
+All operations happen within a named project mapped to a fixed directory. This grounds the agent's workspace, scopes file/terminal access, maintains SQLite-based project memory, and keeps LLM context windows small and focused.
+
+### 2. MemGPT Chat Orchestrator
+The main entry point is a persistent **MemGPT Chat Orchestrator** (`MemGPTAgentBlock`). Rather than running a static intent classifier, the orchestrator converses with the user, manages long-term memory, and dynamically routes complex tasks by invoking active skills via tool-calling (`run_skill`).
+
+### 3. Skills-Oriented Design (Anthropic Standard)
+Capabilities are defined as modular **skills** (defined via `SKILL.md` declarations and optional Level 3 python/bash scripts).
+- **Opt-in Activation**: Projects declare active skills in a local `skills.yaml` file.
+- **Ephemeral Sub-Agents**: When a skill is invoked, the orchestrator spawns a focused sub-agent (`LLMAgentBlock`) dedicated to executing that skill's workflow.
+- **Dialogue Interceptor**: The sub-agent communicates directly with the user, and an interceptor synchronizes the exchange back to the orchestrator's memory.
+
+### 4. Code Generation (`implement-feature` Skill)
+Software development and bug-fixing tasks are handled by the default `implement-feature` skill, running a structured Plan → Execute → Verify loop:
+- **Interactive Planning**: Generates high-level task plans and refines them based on user feedback.
+- **Shadow Git Checkout**: Automatically checkpoints code to an isolated repository (`.opalacoder/.git`) before plan execution, allowing instant rollback via `/undo`.
+- **Auto-Linting**: Validates changes using syntax checkers (`node --check`, `py_compile`) after each file edit, letting the worker self-correct syntax errors autonomously.
+
+### 5. Web-Based IDE GUI (Cross-Platform)
+OpalaCoder features an integrated desktop GUI built using React, Vite, and `pywebview`:
+- **Cross-Platform Support**: Works seamlessly on Linux and Windows. If `pywebview` is not available, it automatically falls back to hosting a local web server and launching the interface in your default browser.
+- **Integrated Terminal**: Includes a real-time xterm.js terminal with shell/PTY integration for running and inspecting commands natively.
+- **Git Source Control Sidebar**: A dedicated panel that tracks file modifications (color-coded as Modified/Untracked/Deleted) and provides a commit interface.
+- **Global Settings Panel**: Customize the editor font size, tab size, and word wrapping, with dynamic toggle support for Light and Dark themes.
+- **About Tab**: Version tracking (currently `0.1.5 alfa`), licensing, and developer details in the settings panel.
+
+### 6. Persistent Projects and CLI Commands
+
+| Command | Description |
+|---|---|
+| `/help` | Show available commands |
+| `/clear` | Clear memory and history of the current project |
+| `/rename <name>` | Rename the active project |
+| `/list` | List all saved projects |
+| `/load <name>` | Load an existing project |
+| `/delete <name>` | Delete a project (optionally deletes its directory) |
+| `/skills` | List available skills and active ones for the project |
+| `/addskill <name>` / `/rmskill <name>` | Add or remove skills |
+| `/undo` | Revert the last agent change via shadow VCS |
+| `/commit <msg>` | Manually commit to the shadow git |
+| `/exit` / `/quit` | Exit the application |
+
+### 7. Modular Architecture
+
+```text
+opalacoder/
+├── cli.py                  Entrypoint, project loading, REPL loop
+├── memgpt_runtime.py       MemGPT chat orchestrator and run_skill tool integration
+├── agents.py               Agent creation helper functions
+├── config.py               Global settings loader and CLI parser
+├── skills.py               Skill loading, selection, and routing
+├── project.py              SQLite project management and state
+├── vcs.py                  Shadow git strategies (auto, hybrid, agent-driven, none)
+├── ide_server.py           Asynchronous HTTP and REST server hosting the IDE GUI
+├── agent_stdin.py          JSON stdin/stdout protocol server for remote control
+├── code_index.py           Multi-language symbol index (SQLite-backed, incremental)
+├── vector_index.py         Vector index of chunks for semantic code lookup
+└── tools.py                Shared tool definitions (run_command, memory APIs)
+```
+
+---
+
+## Requirements
+
+### 1. Core & CLI Requirements
+- **Python 3.11+**
+- **[agenticblocks](https://github.com/gilzamir/agenticblocks)** (install from source)
+- **Local SQLite support** (standard in python)
+- **Local LLM Engine (Recommended: Ollama 0.24.0+)** with models available:
+  - **Default & Alternative models**: `ministral-3:14b` (or `gemma4:latest`, `mistral-nemo:latest`)
+  - Any model supported by [litellm](https://docs.litellm.ai) works.
+
+> [!TIP]
+> **Hardware Acceleration & GPU Drivers:**
+> To run large models (like `gemma4` or `ministral-3:14b`) efficiently on local backends (such as Ollama), it is highly recommended to use GPU hardware acceleration.
+> - **NVIDIA GPUs**: Ensure you have official **NVIDIA Drivers** and the **CUDA Toolkit** installed so that Ollama can offload model layers to GPU VRAM.
+> - **AMD & Apple Silicon**: Ollama also supports ROCm (AMD) and Metal (Apple Silicon) natively. Make sure your local setup is utilizing GPU acceleration to avoid slow CPU execution times.
+
+### 2. Web IDE / GUI Requirements
+- **Desktop Window Mode (Optional)**: Launches a native app window using `pywebview`.
+  - **Windows**: Works out of the box using Windows Webview2 (Edge).
+  - **Linux**: Requires **WebKit2GTK** python bindings (specifically `python3-gi` and `gir1.2-webkit2-4.1`) or **Qt5/Qt6** (PyQt/PySide) installed on the system.
+  - **Browser Fallback**: If desktop window dependencies are missing, OpalaCoder automatically starts the IDE server and opens it in your default web browser (`http://127.0.0.1:3000`).
+- **Frontend Development (Optional)**: If you intend to compile the React/Vite frontend source code under `gui_src/`, you will need **Node.js 18+** and **npm**. (Compiled assets are already bundled in default packages).
+
+---
+
+## Installation
+
+Try:
+
+```bash
+pip install opalacoder
+```
+
+```bash
+git clone https://github.com/gilzamir/OpalaCoder
+cd OpalaCoder
+
+python -m venv .env
+source .env/bin/activate          # Linux/macOS
+# .env\Scripts\activate           # Windows
+
+# Install agenticblocks from source first
+pip install -e /path/to/agenticblocks
+
+# Install OpalaCoder dependencies
+pip install -r requirements.txt
+```
+
+### Environment Variables (Optional)
+
+```env
+# Override default model (any litellm-supported string)
+OPALA_MODEL=ollama/ministral-3:14b
+```
+
+---
+
+## How to Run
+
+OpalaCoder supports three main execution modes:
+
+### 1. Interactive CLI REPL (Default)
+Starts the standard CLI terminal planner/execution loop:
+```bash
+source .env/bin/activate
+python main.py                        # default (plan mode)
+python main.py --mode auto            # run without interruptions
+python main.py --mode edit            # confirm sensitive operations
+python main.py --model ollama/gemma4  # override model
+python main.py --db /path/to/db       # custom database path
+python main.py --version
+python main.py --help
+```
+
+### 2. Web-Based IDE GUI
+Launches the integrated React desktop application. It opens as a local app window (via `pywebview`) or falls back to your web browser:
+```bash
+source .env/bin/activate
+python main.py --gui
+```
+
+### 3. Stdin/Stdout JSON Protocol Server
+Launches the agent in background headless mode, communicating via single-line JSON messages:
+```bash
+source .env/bin/activate
+python main.py --stdin
+```
+
+---
+
+## Compiling Frontend GUI (Optional)
+
+If you are developing or making changes to the React GUI, you can recompile the assets:
+```bash
+cd gui_src
+npm install
+npm run build
+```
+This builds the SPA bundle and saves it directly into the Python package distribution at `opalacoder/gui/`.
+
+## Project Flow
+
+```text
+main() or `--gui` (server mode)
+  │
+  ├── startup_menu() ───────── Load/Create project, discover skills (via skills.yaml)
+  │
+  └── repl_loop() ──────────── Instantiate MemGPT chat-orchestrator
+        │
+        ├── User enters command (e.g. `/help`, `/undo`) ── Dispatched to CLI commands
+        │
+        └── User enters demand ────────────────────────── MemGPT.run(user_input)
+              │
+              ├── Direct chat (greetings, project status, general questions)
+              │
+              └── Request matches active skill ───────────── run_skill(name, context)
+                    │
+                    ├── Instantiate ephemeral sub-agent (LLMAgentBlock)
+                    ├── Sub-agent loads SKILL.md and Level 3 scripts (e.g. implement-feature)
+                    ├── Sub-agent executes with tools, talks to user (dialogue interceptor)
+                    └── Return result to MemGPT orchestrator
+```
+
+---
+
+## Configuration (`agents.yaml`)
+
+The main configuration file. Key fields and role overrides:
+
+```yaml
+default: ollama/ministral-3:14b      # default model for all agents
+alternative: ollama/ministral-3:14b  # model for complex tasks
+
+llm_defaults:
+  temperature: 1.0
+  max_tokens: 8128
+  num_ctx: 8192
+
+agents:
+  # The fixed chat-orchestrator of the skills-oriented architecture.
+  memgpt:
+    temperature: 1.0
+    num_ctx: 16384
+    max_heartbeats: 20
+
+  # drives the plan→execute→review loop inside the implement-feature skill
+  orchestrator:
+    temperature: 1.0
+    num_ctx: 16384
+    max_heartbeats: 20
+    strategy: workflow
+
+  # executes each task command with code editing tools
+  worker:
+    temperature: 1.0
+    max_tokens: 8128
+    num_ctx: 16384
+    reasoning_effort: "none"  # Must stay "none" for tool-calling integration
+```
+
+Full per-agent overrides for `temperature`, `max_tokens`, `num_ctx`, `reasoning_effort`, and `debug` are supported for every agent role.
+
+---
+
+## Benchmark
+
+A JS bug-fix benchmark is included in `scripts/`:
+
+```bash
+# Collect instances from GitHub (requires gh CLI authenticated)
+python scripts/collect_jsbench.py --limit 50 --out datasets/jsbench
+
+# Evaluate OpalaCoder on collected instances
+python scripts/eval_jsbench.py --limit 10
+```
+
+Results are written to `datasets/jsbench_results.json` with per-instance pass/fail and a summary fix rate.
+
+---
+
+## Build & Test
+
+```bash
+python -m pytest tests/ -q
+```
+
+---
+
+## License
+
+MIT

opalacoder-0.1.5/README.md

@@ -0,0 +1,261 @@
+# OpalaCoder
+
+**OpalaCoder** is an autonomous coding agent built on the **[AgenticBlocks.IO](https://github.com/gilzamir/agenticblocks)** framework. It features a project-centric context model and a modular, skills-oriented architecture optimized to run efficiently with local LLMs.
+
+---
+
+## Core Architecture & Features
+
+### 1. Project-Centric Context
+All operations happen within a named project mapped to a fixed directory. This grounds the agent's workspace, scopes file/terminal access, maintains SQLite-based project memory, and keeps LLM context windows small and focused.
+
+### 2. MemGPT Chat Orchestrator
+The main entry point is a persistent **MemGPT Chat Orchestrator** (`MemGPTAgentBlock`). Rather than running a static intent classifier, the orchestrator converses with the user, manages long-term memory, and dynamically routes complex tasks by invoking active skills via tool-calling (`run_skill`).
+
+### 3. Skills-Oriented Design (Anthropic Standard)
+Capabilities are defined as modular **skills** (defined via `SKILL.md` declarations and optional Level 3 python/bash scripts).
+- **Opt-in Activation**: Projects declare active skills in a local `skills.yaml` file.
+- **Ephemeral Sub-Agents**: When a skill is invoked, the orchestrator spawns a focused sub-agent (`LLMAgentBlock`) dedicated to executing that skill's workflow.
+- **Dialogue Interceptor**: The sub-agent communicates directly with the user, and an interceptor synchronizes the exchange back to the orchestrator's memory.
+
+### 4. Code Generation (`implement-feature` Skill)
+Software development and bug-fixing tasks are handled by the default `implement-feature` skill, running a structured Plan → Execute → Verify loop:
+- **Interactive Planning**: Generates high-level task plans and refines them based on user feedback.
+- **Shadow Git Checkout**: Automatically checkpoints code to an isolated repository (`.opalacoder/.git`) before plan execution, allowing instant rollback via `/undo`.
+- **Auto-Linting**: Validates changes using syntax checkers (`node --check`, `py_compile`) after each file edit, letting the worker self-correct syntax errors autonomously.
+
+### 5. Web-Based IDE GUI (Cross-Platform)
+OpalaCoder features an integrated desktop GUI built using React, Vite, and `pywebview`:
+- **Cross-Platform Support**: Works seamlessly on Linux and Windows. If `pywebview` is not available, it automatically falls back to hosting a local web server and launching the interface in your default browser.
+- **Integrated Terminal**: Includes a real-time xterm.js terminal with shell/PTY integration for running and inspecting commands natively.
+- **Git Source Control Sidebar**: A dedicated panel that tracks file modifications (color-coded as Modified/Untracked/Deleted) and provides a commit interface.
+- **Global Settings Panel**: Customize the editor font size, tab size, and word wrapping, with dynamic toggle support for Light and Dark themes.
+- **About Tab**: Version tracking (currently `0.1.5 alfa`), licensing, and developer details in the settings panel.
+
+### 6. Persistent Projects and CLI Commands
+
+| Command | Description |
+|---|---|
+| `/help` | Show available commands |
+| `/clear` | Clear memory and history of the current project |
+| `/rename <name>` | Rename the active project |
+| `/list` | List all saved projects |
+| `/load <name>` | Load an existing project |
+| `/delete <name>` | Delete a project (optionally deletes its directory) |
+| `/skills` | List available skills and active ones for the project |
+| `/addskill <name>` / `/rmskill <name>` | Add or remove skills |
+| `/undo` | Revert the last agent change via shadow VCS |
+| `/commit <msg>` | Manually commit to the shadow git |
+| `/exit` / `/quit` | Exit the application |
+
+### 7. Modular Architecture
+
+```text
+opalacoder/
+├── cli.py                  Entrypoint, project loading, REPL loop
+├── memgpt_runtime.py       MemGPT chat orchestrator and run_skill tool integration
+├── agents.py               Agent creation helper functions
+├── config.py               Global settings loader and CLI parser
+├── skills.py               Skill loading, selection, and routing
+├── project.py              SQLite project management and state
+├── vcs.py                  Shadow git strategies (auto, hybrid, agent-driven, none)
+├── ide_server.py           Asynchronous HTTP and REST server hosting the IDE GUI
+├── agent_stdin.py          JSON stdin/stdout protocol server for remote control
+├── code_index.py           Multi-language symbol index (SQLite-backed, incremental)
+├── vector_index.py         Vector index of chunks for semantic code lookup
+└── tools.py                Shared tool definitions (run_command, memory APIs)
+```
+
+---
+
+## Requirements
+
+### 1. Core & CLI Requirements
+- **Python 3.11+**
+- **[agenticblocks](https://github.com/gilzamir/agenticblocks)** (install from source)
+- **Local SQLite support** (standard in python)
+- **Local LLM Engine (Recommended: Ollama 0.24.0+)** with models available:
+  - **Default & Alternative models**: `ministral-3:14b` (or `gemma4:latest`, `mistral-nemo:latest`)
+  - Any model supported by [litellm](https://docs.litellm.ai) works.
+
+> [!TIP]
+> **Hardware Acceleration & GPU Drivers:**
+> To run large models (like `gemma4` or `ministral-3:14b`) efficiently on local backends (such as Ollama), it is highly recommended to use GPU hardware acceleration.
+> - **NVIDIA GPUs**: Ensure you have official **NVIDIA Drivers** and the **CUDA Toolkit** installed so that Ollama can offload model layers to GPU VRAM.
+> - **AMD & Apple Silicon**: Ollama also supports ROCm (AMD) and Metal (Apple Silicon) natively. Make sure your local setup is utilizing GPU acceleration to avoid slow CPU execution times.
+
+### 2. Web IDE / GUI Requirements
+- **Desktop Window Mode (Optional)**: Launches a native app window using `pywebview`.
+  - **Windows**: Works out of the box using Windows Webview2 (Edge).
+  - **Linux**: Requires **WebKit2GTK** python bindings (specifically `python3-gi` and `gir1.2-webkit2-4.1`) or **Qt5/Qt6** (PyQt/PySide) installed on the system.
+  - **Browser Fallback**: If desktop window dependencies are missing, OpalaCoder automatically starts the IDE server and opens it in your default web browser (`http://127.0.0.1:3000`).
+- **Frontend Development (Optional)**: If you intend to compile the React/Vite frontend source code under `gui_src/`, you will need **Node.js 18+** and **npm**. (Compiled assets are already bundled in default packages).
+
+---
+
+## Installation
+
+Try:
+
+```bash
+pip install opalacoder
+```
+
+```bash
+git clone https://github.com/gilzamir/OpalaCoder
+cd OpalaCoder
+
+python -m venv .env
+source .env/bin/activate          # Linux/macOS
+# .env\Scripts\activate           # Windows
+
+# Install agenticblocks from source first
+pip install -e /path/to/agenticblocks
+
+# Install OpalaCoder dependencies
+pip install -r requirements.txt
+```
+
+### Environment Variables (Optional)
+
+```env
+# Override default model (any litellm-supported string)
+OPALA_MODEL=ollama/ministral-3:14b
+```
+
+---
+
+## How to Run
+
+OpalaCoder supports three main execution modes:
+
+### 1. Interactive CLI REPL (Default)
+Starts the standard CLI terminal planner/execution loop:
+```bash
+source .env/bin/activate
+python main.py                        # default (plan mode)
+python main.py --mode auto            # run without interruptions
+python main.py --mode edit            # confirm sensitive operations
+python main.py --model ollama/gemma4  # override model
+python main.py --db /path/to/db       # custom database path
+python main.py --version
+python main.py --help
+```
+
+### 2. Web-Based IDE GUI
+Launches the integrated React desktop application. It opens as a local app window (via `pywebview`) or falls back to your web browser:
+```bash
+source .env/bin/activate
+python main.py --gui
+```
+
+### 3. Stdin/Stdout JSON Protocol Server
+Launches the agent in background headless mode, communicating via single-line JSON messages:
+```bash
+source .env/bin/activate
+python main.py --stdin
+```
+
+---
+
+## Compiling Frontend GUI (Optional)
+
+If you are developing or making changes to the React GUI, you can recompile the assets:
+```bash
+cd gui_src
+npm install
+npm run build
+```
+This builds the SPA bundle and saves it directly into the Python package distribution at `opalacoder/gui/`.
+
+## Project Flow
+
+```text
+main() or `--gui` (server mode)
+  │
+  ├── startup_menu() ───────── Load/Create project, discover skills (via skills.yaml)
+  │
+  └── repl_loop() ──────────── Instantiate MemGPT chat-orchestrator
+        │
+        ├── User enters command (e.g. `/help`, `/undo`) ── Dispatched to CLI commands
+        │
+        └── User enters demand ────────────────────────── MemGPT.run(user_input)
+              │
+              ├── Direct chat (greetings, project status, general questions)
+              │
+              └── Request matches active skill ───────────── run_skill(name, context)
+                    │
+                    ├── Instantiate ephemeral sub-agent (LLMAgentBlock)
+                    ├── Sub-agent loads SKILL.md and Level 3 scripts (e.g. implement-feature)
+                    ├── Sub-agent executes with tools, talks to user (dialogue interceptor)
+                    └── Return result to MemGPT orchestrator
+```
+
+---
+
+## Configuration (`agents.yaml`)
+
+The main configuration file. Key fields and role overrides:
+
+```yaml
+default: ollama/ministral-3:14b      # default model for all agents
+alternative: ollama/ministral-3:14b  # model for complex tasks
+
+llm_defaults:
+  temperature: 1.0
+  max_tokens: 8128
+  num_ctx: 8192
+
+agents:
+  # The fixed chat-orchestrator of the skills-oriented architecture.
+  memgpt:
+    temperature: 1.0
+    num_ctx: 16384
+    max_heartbeats: 20
+
+  # drives the plan→execute→review loop inside the implement-feature skill
+  orchestrator:
+    temperature: 1.0
+    num_ctx: 16384
+    max_heartbeats: 20
+    strategy: workflow
+
+  # executes each task command with code editing tools
+  worker:
+    temperature: 1.0
+    max_tokens: 8128
+    num_ctx: 16384
+    reasoning_effort: "none"  # Must stay "none" for tool-calling integration
+```
+
+Full per-agent overrides for `temperature`, `max_tokens`, `num_ctx`, `reasoning_effort`, and `debug` are supported for every agent role.
+
+---
+
+## Benchmark
+
+A JS bug-fix benchmark is included in `scripts/`:
+
+```bash
+# Collect instances from GitHub (requires gh CLI authenticated)
+python scripts/collect_jsbench.py --limit 50 --out datasets/jsbench
+
+# Evaluate OpalaCoder on collected instances
+python scripts/eval_jsbench.py --limit 10
+```
+
+Results are written to `datasets/jsbench_results.json` with per-instance pass/fail and a summary fix rate.
+
+---
+
+## Build & Test
+
+```bash
+python -m pytest tests/ -q
+```
+
+---
+
+## License
+
+MIT