@nomad-e/bluma-cli 0.0.38 → 0.0.40

package/LICENSE

@@ -4,14 +4,80 @@ http://www.apache.org/licenses/
 
 Copyright 2025 Alex Fonseca and NomadEngenuity contributors
 
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
-    http://www.apache.org/licenses/LICENSE-2.0
+1. Definitions.
 
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License.
+Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License.
+Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution.
+You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions.
+Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks.
+This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty.
+Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability.
+In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability.
+While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!)  The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.
+
+   Copyright 2025 Alex Fonseca and NomadEngenuity contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -16,19 +16,24 @@ BluMa CLI is an independent agent for automation and advanced software engineeri
 - [Overview](#overview)
 - [Key Features](#key-features)
 - [Requirements](#requirements)
+- [Architecture Diagram](#-architecture-diagram)
 - [Installation](#installation)
-- [How to Run](#how-to-run)
-- [Project Structure](#project-structure)
+- [Usage](#usage)
+  - [Examples](#-usage-examples)
+- [Configuration and Environment Variables](#configuration-and-environment-variables)
 - [Development and Build](#development-and-build)
 - [Extensibility: Tools and Plugins](#extensibility-tools-and-plugins)
 - [Tests](#tests)
-- [Configuration and Environment Variables](#configuration-and-environment-variables)
+- [Limitations / Next Steps](#️-limitations--next-steps)
+- [Security Notes](#-security-notes)
+- [Tech Stack Overview](#stack)
+- [Contributing](#-contributing)
 - [License](#license)
 
 ---
 
 ## <a name="overview"></a>Overview
-BluMa CLI is a modern CLI focused on automation, LLM collaboration, documentation, refactoring, running complex tasks, and integrating with external tools. It uses React (via Ink) for rich terminal interfaces and features context/conversation management, smart feedback, and interactive confirmation systems.
+BluMa CLI is a modular conversational agent and task automation framework focused on advanced software engineering workflows. It runs entirely in the terminal using React (via Ink) for a rich interactive UI, and is architected around a **UI layer** (`main.ts` + `App.tsx`) and an **agent layer** (`Agent` orchestrator + `BluMaAgent` core). It enables LLM-powered automation, documentation, refactoring, running complex development tasks, and integrating with both native and external tools. The system features persistent sessions, contextual reasoning, smart feedback, and an interactive confirmation system for controlled execution.
 
 ---
 
@@ -266,4 +271,287 @@ Advanced config files are located in `src/app/agent/config/`.
 ## <a name="license"></a>License
 Apache-2.0. Made by Alex Fonseca and NomadEngenuity contributors.
 
-Enjoy, hack, and—if possible—contribute!
+Enjoy, hack, and—if possible—contribute!
+
+---
+
+## 🏗 Architecture Diagram
+Below is a simplified diagram showing BluMa CLI's core architecture:
+```
+[ main.ts ] → [ App.tsx (UI Layer) ]
+       ↓
+[ Agent (Orchestrator) ]
+       ↓
+[ BluMaAgent (Core Loop & State) ]
+       ↓
+[ MCPClient / Tools / Native Tools / SubAgents ]
+       ↓
+[ External APIs & System Operations ]
+```
+This flow ensures a clean separation between presentation, orchestration, core logic, and integration layers.
+
+### Sequence Diagram
+```mermaid
+sequenceDiagram
+    participant UI as UI (main.ts + App.tsx)
+    participant Agent as Agent (Orchestrator)
+    participant Core as BluMaAgent (Core Loop)
+    participant MCP as MCPClient / Tools
+
+    UI->>Agent: Initialize(sessionId, eventBus)
+    Agent->>Core: initialize()
+    Core->>MCP: initialize tools
+    UI->>Agent: processTurn(userInput)
+    Agent->>Core: processTurn(content)
+    Core->>MCP: Get available tools & context
+    MCP-->>Core: Tool list & details
+    Core-->>Agent: Tool call request or LLM message
+    Agent-->>UI: backend_message (e.g., confirmation_request)
+    UI->>Agent: handleToolResponse()
+    Agent->>Core: handleToolResponse(decision)
+    Core->>MCP: Execute tool
+    MCP-->>Core: Tool result
+    Core-->>Agent: backend_message(done)
+    Agent-->>UI: Update history & UI state
+```
+
+---
+
+### Component Diagram
+```mermaid
+flowchart TD
+    subgraph UI["UI Layer"]
+        M["main.ts"]
+        A["App.tsx"]
+    end
+    subgraph AG["Agent Layer"]
+        AGN["Agent (Orchestrator)"]
+        CORE["BluMaAgent (Core Loop)"]
+    end
+    subgraph TOOLS["Tools & Integration"]
+        MCP["MCPClient"]
+        NT["Native Tools"]
+        SA["SubAgents"]
+    end
+    EXT["External APIs & FS"]
+
+    M --> A --> AGN --> CORE --> MCP --> NT
+    CORE --> SA
+    MCP --> EXT
+    NT --> EXT
+```
+
+---
+
+### Activity Diagram
+```mermaid
+flowchart TD
+    Start((Start)) --> Input[User Input in UI]
+    Input --> Processing{Command Type?}
+    Processing -->|Slash Command| SC[Handle Slash Command]
+    Processing -->|Normal Input| PT[processTurn]
+    SC --> Done((End))
+    PT --> LLM[Send to LLM]
+    LLM --> ToolCall{Tool Requested?}
+    ToolCall -->|No| Display[Display Assistant Message]
+    ToolCall -->|Yes| Confirm[Ask for Confirmation]
+    Confirm --> Decision{Decision}
+    Decision -->|Accept| Exec[Execute Tool]
+    Decision -->|Decline| Skip[Skip Execution]
+    Exec --> Result[Return Tool Result]
+    Skip --> Done
+    Result --> Done
+    Display --> Done
+```
+
+---
+
+### State Machine Diagram
+```mermaid
+stateDiagram-v2
+    [*] --> Idle
+    Idle --> Processing: User Input
+    Processing --> Awaiting_Confirmation: Tool Call Needs Approval
+    Awaiting_Confirmation --> Processing: User Accepts
+    Awaiting_Confirmation --> Idle: User Declines
+    Processing --> Completed: Task Completed
+    Processing --> Interrupted: User Interrupt
+    Completed --> Idle
+    Interrupted --> Idle
+```
+
+---
+
+### Deployment Diagram
+```mermaid
+graph TD
+    CLI["CLI (BluMa)"] --> LocalFS[("Local File System")]
+    CLI --> AzureOpenAI[("Azure OpenAI API")]
+    CLI --> GitHubAPI[("GitHub API")]
+    CLI --> NotionAPI[("Notion API")]
+    CLI --> OtherAPIs[("Other External APIs")]
+    CLI --> MCPServer[("MCP Server / Plugins")]
+```
+
+---
+
+### Data Flow Diagram
+```mermaid
+flowchart LR
+    U[User] --> UI[UI Layer]
+    UI --> Agent[Agent]
+    Agent --> Core[BluMaAgent]
+    Core --> MCP[MCPClient]
+    Core --> Sub[SubAgents]
+    MCP --> Tools[Native Tools & External APIs]
+    Sub --> Tools
+    Tools --> MCP
+    MCP --> Core
+    Core --> Agent
+    Agent --> UI
+    UI --> U
+```
+
+---
+
+## 💡 Usage Examples
+- **Run Initialization Command**
+```
+/init
+```
+Executes the `init` subagent to prepare the working environment.
+
+- **Confirm an Edit Operation**
+When the system prompts an `edit_tool` operation, review the preview and choose:
+```
+Accept | Decline | Accept Always
+```
+
+- **Live Overlay**
+During a long-running task, you can send hints:
+```
+[hint] Prefer small batch edits
+[constraint] Avoid editing src/app/ui/**
+```
+
+---
+
+## 🤝 Contributing
+We welcome contributions! For full details, read [CONTRIBUTING.md](CONTRIBUTING.md).
+
+### 📋 Prerequisites
+- **Node.js** >= 18 and **npm** >= 9 installed
+- Dependencies installed via `npm install`
+- Required environment variables configured (see *Configuration* section)
+
+### 🔄 Contribution Workflow
+1. **Fork** the repository
+2. **Clone** your fork locally
+3. Create a feature branch named according to [Conventional Commits](https://www.conventionalcommits.org/) (e.g., `feat/add-logging`)
+4. Commit changes with meaningful messages
+5. Push to your fork and open a Pull Request
+
+### 🛠 Code Standards
+- Follow TypeScript strict mode guidelines
+- Maintain style via ESLint and Prettier (`npm run lint`)
+- Keep functions short, modular, and documented with JSDoc
+- All business logic must have unit tests
+
+### 🧪 Testing Requirements
+- Run `npm test` and ensure all tests pass
+- Include new tests for any new functionality or bug fix
+- Validate integration tests when adding new tools or APIs
+
+### 🔍 Code Review Process
+- Minimum of 1 maintainer approval before merge
+- Resolve all review comments and passing CI before merge
+
+### 📄 Documentation
+- Update README.md or relevant Wiki pages when adding/removing features
+- Add or update CHANGELOG.md for notable changes
+
+---
+
+## ⚠️ Limitations / Next Steps
+- Current LLM integration optimised for Azure OpenAI; add more providers.
+- Logging verbosity could be made configurable.
+- Potential for richer plugin lifecycle (install/remove at runtime).
+- Improve error reporting in subagents.
+
+---
+
+## 🔒 Security Notes
+
+---
+
+## 🛠 Error Handling & Recovery Flows
+BluMa handles different classes of errors gracefully:
+- **Network/API Errors**: Retry logic with exponential backoff.
+- **Authentication Failures**: Immediate notification to user, requires updating environment variables.
+- **Tool Execution Errors**: Displayed with detailed message; execution can be retried or skipped.
+- **LLM/API Exceptions**: Fall back to safe mode and keep context intact.
+- **Session/History Save Failures**: Warn user and continue without losing core functionality.
+
+---
+
+## 📈 Metrics & Observability
+- **Performance Metrics**: Average response time, tokens used per request, tool execution times.
+- **Usage Tracking**: Number of commands executed, tool calls, sessions created.
+- **Logging**: Structured logs for all events.
+- Integration-ready with Prometheus/Grafana or external observability platforms.
+
+---
+
+## 🔐 Advanced Security Practices
+- Use secret management tools (Vault, AWS Secrets Manager) to store environment variables.
+- Apply principle of least privilege for API keys.
+- Validate and sanitize all user inputs to avoid prompt injection attacks.
+- Regularly rotate API keys.
+
+---
+
+## 🚀 Performance & Scalability
+- Optimize context window by pruning irrelevant history.
+- Batch related operations to reduce LLM calls.
+- Support for distributed execution or remote agent hosting.
+- Cache static responses where possible.
+
+---
+
+## 🔄 Development Cycle & CI/CD
+- **Testing**: `npm test` and `npm run test:watch` for development.
+- **Linting**: Enforce coding standards with ESLint/Prettier.
+- **CI/CD**: Recommended GitHub Actions or similar to run tests/build on push.
+- **Deployment**: Automatic packaging to npm or internal registry.
+
+---
+
+## 🗺 Roadmap & Release Notes
+**Upcoming:**
+- Multi-LLM provider support.
+- Web-based dashboard.
+- Richer subagent plugin APIs.
+
+**Release Notes**:
+- Follow [CHANGELOG.md](CHANGELOG.md) for version history.
+
+---
+
+## 🎯 Advanced Use Cases
+- Chain multiple tools with complex decision-making.
+- Build custom subagents for domain-specific automation.
+- Integrate with CI pipelines for automated code review and refactoring.
+
+---
+
+## 📏 Code Standards & Contribution Guidelines
+- Follow TypeScript strict mode.
+- Commit messages must follow Conventional Commits (`feat:`, `fix:`, `chore:`).
+- Keep functions short, modular and documented.
+- Add unit tests for all business logic.
+
+---
+- Protect your API keys: never commit `.env` files.
+- `edit_tool` can modify files — review previews before accepting.
+- Use restricted permissions for API tokens wherever possible.
+- If using on shared systems, ensure `.bluma-cli` config is private.

package/dist/main.js

@@ -850,7 +850,7 @@ var ConfirmationPrompt = ({ toolCalls, preview, onDecision }) => {
 // src/app/agent/agent.ts
 import OpenAI from "openai";
 import * as dotenv from "dotenv";
-import path9 from "path";
+import path10 from "path";
 import os7 from "os";
 
 // src/app/agent/tool_invoker.ts
@@ -1488,7 +1488,7 @@ var AdvancedFeedbackSystem = class {
 };
 
 // src/app/agent/bluma/core/bluma.ts
-import path8 from "path";
+import path9 from "path";
 
 // src/app/agent/session_manger/session_manager.ts
 import path7 from "path";
@@ -1624,12 +1624,17 @@ async function saveSessionHistory(sessionFile, history) {
 
 // src/app/agent/core/prompt/prompt_builder.ts
 import os5 from "os";
+import fs9 from "fs";
+import path8 from "path";
 var SYSTEM_PROMPT = `
-### IDENTITY AND OBJECTIVE
-You are BluMa, a fully **AUTONOMOUS** AI Software Engineer from NomadEngenuity. 
-Your single objective is to complete the user's request from end-to-end. 
-You operate with maximum precision, efficiency, and autonomy.
-Use a proprietary Large Language Model fine-tuned for programming and software engineering, optimized for code analysis, generation, and review.
+
+**Goal:** Operate as a fully autonomous AI software engineer capable of managing end-to-end software development and maintenance tasks \u2014 including coding, refactoring, testing, documentation, environment setup, and repository management \u2014 with no human intervention required unless explicitly requested.
+
+You are BluMa, a fully AUTONOMOUS AI Software Engineer from NomadEngenuity.
+Your sole objective is to complete the user's request from end to end, with maximum precision, efficiency, and autonomy.
+You operate as a CLI agent with full permission to create, modify, delete files, and execute system commands including Git and shell commands.
+You use a proprietary Large Language Model fine-tuned specifically for programming and software engineering, optimized for code analysis, generation, and review.
+You are an interactive CLI agent specializing in software engineering tasks. REMEMBER Your primary goal is to help users safely and efficiently, adhering strictly to the following instructions and utilizing your available tools.
 ---
 
 ### CORE DIRECTIVES
@@ -1643,6 +1648,16 @@ Use a proprietary Large Language Model fine-tuned for programming and software e
 
 ---
 
+## Software Engineering Tasks
+When asked to perform tasks such as fixing bugs, adding features, refactoring, or explaining code, follow this sequence:
+1. **Understand:** Think about the user's request and the relevant context of the codebase. Use 'count_file_lines' and 'read_file_lines' to understand the context and validate any assumptions you may have.
+2. **Plan:** Develop a coherent and reasoned plan (based on the understanding from step 1) for how you want to solve the user's task. As part of the plan, you should try to use a self-checking loop by writing unit tests, if relevant to the task. Use output logs or debug statements as part of this self-checking cycle to arrive at a solution.
+3. **Implement:** Use the tools available to act on the plan, strictly following the conventions established by the project (detailed in 'Core Mandates').
+4. Verify (Tests): If applicable and feasible, verify changes using the project's testing procedures. Identify the correct test commands and frameworks by examining the README or BluMa.md files, the build/package configuration (e.g., package.json), or existing test execution standards. NEVER assume standard test commands.
+5. Verify (Standards): VERY IMPORTANT: After making code changes, run the project-specific build, linting, and type-checking commands (e.g., tsc, npm run lint, ruff check) that you have identified for this project (or obtained from the user). This ensures code quality and adherence to standards. If you are unsure about these commands, you can ask the user if they would like you to run them and, if so, how.
+
+---
+
 ### CURRENT ENVIRONMENT CONTEXT
 <current_system_environment>
 - Operating System: {os_type} ({os_version})
@@ -1653,6 +1668,54 @@ Use a proprietary Large Language Model fine-tuned for programming and software e
 - Current Date: {current_date}
 </current_system_environment>
 
+---
+
+<agent_turn>
+
+1. RECEIVE TASK AND SEND INITIAL MESSAGE  
+- As soon as you receive the user task, IMMEDIATELY send a confirmation message in an informal but technical style.  
+- Example: "Got your task, I'll start analyzing and working on it right away."  
+- This message officially starts the turn, with no external interruptions allowed.
+
+2. OPEN AND USE THE REASONING NOTEBOOK  
+- Open and use the reasoning notebook according to the rules defined in \`<reasoning_rules>\`.  
+- Organize your entire reasoning and planning there.
+
+3. USE THE DYNAMIC AND REFLECTIVE PROBLEM-SOLVING TOOL  
+- Break down the task into **remaining_tasks** following this tool's guidelines.  
+- Use the **thought** field for detailed analysis, revisions, and reasoning.  
+- Keep the **remaining_tasks** checklist updated with the mandatory format (\u{1F5F9} done, \u2610 pending).  
+- Adjust total thoughts count as needed.  
+- Explore hypotheses, verify them via chain-of-thought, and recommend appropriate tools for each step.  
+- Never put future steps or to-do items inside **thought**, only in **remaining_tasks**.
+
+4. PROCESS REMAINING TASKS  
+- Execute the pending tasks from the **remaining_tasks** checklist one by one, updating the list and reasoning.  
+- Use recommended tools as per the reflective analysis.  
+- Do not finalize or deliver a final answer before completing all pending tasks.
+
+5. CLOSE THE TASK AND THE TURN  
+- When all **remaining_tasks** are done, notify the user clearly:  
+  "Task completed. There are no further pending actions."  
+- You MUST call the \`<agent_end_task_rules>\` tool to close the turn.  
+- Do not perform any action after calling this tool in the same turn.
+
+6. WAIT FOR NEW TASK  
+- After closing the turn, wait for the next task to start a new turn.
+</agent_turn>
+
+---
+
+### IMPORTANT RULES  
+- Sending the initial message is mandatory and marks the turn start.  
+- Using the reasoning notebook is mandatory.  
+- Breaking the task into **remaining_tasks** with the reflective problem-solving tool is mandatory.  
+- Never include future steps in the **thought** field, only in the **remaining_tasks** checklist.  
+- Calling \`<agent_end_task_rules>\` is mandatory to close the turn.  
+- Decline out-of-scope tasks professionally before calling \`<agent_end_task_rules>\`.  
+- Process only one task per turn, never multiple concurrently.
+
+
 ---
 
 ### TOOL-SPECIFIC RULES
@@ -1664,6 +1727,60 @@ Use a proprietary Large Language Model fine-tuned for programming and software e
 - Actively use notify for progress updates
 </message_rules>
 
+---
+
+The agent MUST ALWAYS use the prompt below called \`<reasoning_rules>\` to guide all their thinking and execution. This prompt sets clear rules for the use of their \u201Cmental laptop\u201D (called **reasoning_notebook**), which serves as their organized brain and the center of their reasoning.
+
+---
+
+<reasoning_rules>
+# YOUR THINKING ON A NOTEBOOK - MANDATORY USE
+CRITICAL: Your laptop (**reasoning_nootebook**) is your ORGANIZED MIND
+## IMPORTANT
+## NEVER PUT CHECKLISTS OR STEPS IN THE THOUGHT TEXT
+## ALWAYS USE A NOTEBOOK (Always for):
+- ANY task
+- Before starting development (plan first!)
+- Projects with multiple files (organize the structure)
+- Debugging sessions (monitor discoveries)
+- Extensive refactoring (map the changes)
+- Architectural decisions (think through the options)
+
+## HOW TO USE A NOTEBOOK:
+1. Start with **reasoning_nootebook**
+2. Break the task down into logical steps
+3. Plan the approach - Which files? What changes? What order?
+4. Track progress - Check off completed steps
+5. Write down decisions - Why did you choose this approach?
+6. Update continuously - Keep the notebook up to date
+
+## THE NOTEBOOK PREVENTS:
+- Acting "outside the box"
+- Forgetting task requirements
+- Losing control of complex workflows
+- Making unplanned changes
+- Ineffective approaches
+- Working without a clear roadmap
+- Jumping between unrelated subtasks
+</reasoning_rules>
+
+---
+
+<agent_rules>
+1. **NO EXCEPTIONS:** The agent MAY NOT start, continue, or complete any task without first opening and using the **reasoning_notebook** as described.
+2. **DO NOT SKIP:** If the agent encounters a complex, multi-phase, or code-intensive task, they MUST divide the work using the notebook.
+3. **DO NOT INCLUDE LISTS IN THOUGHTS:** Checklists, steps, or plans are prohibited in the free-thinking text; these must be organized within the notebook.
+4. **CONSTANT UPDATE:** The agent must keep the notebook always up to date, reflecting the actual status of the task and decisions.
+5. **COMMUNICATION:** Any explanation or justification provided to the user must be based on and aligned with the notebook input.
+</agent_rules>
+
+---
+
+
+<agent_end_task_rules>
+This tool is mandatory.
+You must use it to inform developer {username} that the task has been completed and that there are no further pending actions, in accordance with the objectives defined for the task.
+</agent_end_task_rules>
 
 ---
 
@@ -1708,17 +1825,56 @@ function getUnifiedSystemPrompt() {
     const placeholder = `{${key}}`;
     formattedPrompt = formattedPrompt.replace(new RegExp(placeholder, "g"), finalEnv[key]);
   }
+  const isGitRepo = checkIfGitRepository(finalEnv.workdir);
   const AUTONOMY_PROMPT = `
-  ### AUTONOMY MANDATE
-  You are explicitly authorized to operate with full autonomy. You will self-direct to complete the user's objective. Follow these rules strictly:
-  1) **NO CONFIRMATION:** Execute all planned steps without asking for user confirmation. You have full authority to create, modify, and delete files as needed to complete the task.
-  2) **DECOMPOSE AND EXECUTE:** For complex tasks, create a short, internal plan. Execute each step of the plan sequentially. Report progress via \`message_notify_user\`.
-  3) **ORCHESTRATE TOOLS:** Always start with non-destructive analysis (read, list files). When you call \`edit_tool\`, your arguments must be as precise as possible.
-  4) **SELF-VALIDATE AND RECOVER:** After each action, validate the outcome. If it fails, you are responsible for recovering. Reread files for updated context, adjust your plan, and retry.
-   `;
+---
+
+### AUTONOMY MANDATE
+
+You are explicitly authorized to operate with full autonomy. You will self-direct to complete the user's objective. Follow these rules strictly:
+1. **NO CONFIRMATION:** Execute all planned steps without asking for user confirmation. You have full authority to create, modify, delete files, and run CLI commands\u2014including Git commands and shell commands\u2014as needed to complete the task.
+2. **DECOMPOSE AND EXECUTE:** For complex tasks, create a short, internal plan. Execute each step of the plan sequentially. Report progress via \`message_notify_user\`.
+3. **ORCHESTRATE TOOLS:** Always start with non-destructive analysis (read, list files). When you call \`edit_tool\`, your arguments must be as precise as possible.
+4. **SELF-VALIDATE AND RECOVER:** After each action, validate the outcome. If it fails, you are responsible for recovering. Reread files for updated context, adjust your plan, and retry.
+
+---
+
+### GIT REPOSITORY
+- You is Inside Git Repository: ${isGitRepo ? "Yes" : "No"}
+
+---
+
+${isGitRepo ? `
+### GIT USAGE GUIDELINES
+- The current working (project) directory is being managed by a git repository.
+- When asked to commit changes or prepare a commit, always start by gathering information using shell commands:
+  - \`git status\` to ensure that all relevant files are tracked and staged, using \`git add ...\` as needed.
+  - \`git diff HEAD\` to review all changes (including unstaged changes) to tracked files in work tree since last commit.
+    - \`git diff --staged\` to review only staged changes when a partial commit makes sense or was requested by the user.
+  - \`git log -n 3\` to review recent commit messages and match their style (verbosity, formatting, signature line, etc.)
+- Combine shell commands whenever possible to save time/steps, e.g. \`git status && git diff HEAD && git log -n 3\`.
+- Always propose a draft commit message. Never just ask the user to give you the full commit message.
+- Prefer commit messages that are clear, concise, and focused more on "why" and less on "what".
+- Keep the user informed and ask for clarification or confirmation where needed.
+- After each commit, confirm that it was successful by running \`git status\`.
+- If a commit fails, never attempt to work around the issues without being asked to do so.
+- Never push changes to a remote repository without being asked explicitly by the user.
+` : ""}
+
+---
+
+`;
   return `${formattedPrompt}
 ${AUTONOMY_PROMPT}`;
 }
+function checkIfGitRepository(dirPath) {
+  const gitPath = path8.join(dirPath, ".git");
+  try {
+    return fs9.existsSync(gitPath) && fs9.lstatSync(gitPath).isDirectory();
+  } catch {
+    return false;
+  }
+}
 
 // src/app/agent/core/context-api/context_manager.ts
 function createApiContextWindow(fullHistory, maxTurns) {
@@ -1893,7 +2049,7 @@ var BluMaAgent = class {
 
 ${editData.error.display}`;
       }
-      const filename = path8.basename(toolArgs.file_path);
+      const filename = path9.basename(toolArgs.file_path);
       return createDiff(filename, editData.currentContent || "", editData.newContent);
     } catch (e) {
       return `An unexpected error occurred while generating the edit preview: ${e.message}`;
@@ -2412,7 +2568,7 @@ var SubAgentsBluMa = class {
 };
 
 // src/app/agent/agent.ts
-var globalEnvPath = path9.join(os7.homedir(), ".bluma-cli", ".env");
+var globalEnvPath = path10.join(os7.homedir(), ".bluma-cli", ".env");
 dotenv.config({ path: globalEnvPath });
 var Agent = class {
   sessionId;
@@ -3018,21 +3174,21 @@ var SlashCommands_default = SlashCommands;
 import updateNotifier from "update-notifier";
 import { readPackageUp } from "read-package-up";
 import { fileURLToPath as fileURLToPath3 } from "url";
-import path10 from "path";
-import fs9 from "fs";
+import path11 from "path";
+import fs10 from "fs";
 function findPackageJsonNearest(startDir) {
   let dir = startDir;
   for (let i = 0; i < 6; i++) {
-    const candidate = path10.join(dir, "package.json");
-    if (fs9.existsSync(candidate)) {
+    const candidate = path11.join(dir, "package.json");
+    if (fs10.existsSync(candidate)) {
       try {
-        const raw = fs9.readFileSync(candidate, "utf8");
+        const raw = fs10.readFileSync(candidate, "utf8");
         const parsed = JSON.parse(raw);
         if (parsed?.name && parsed?.version) return parsed;
       } catch {
       }
     }
-    const parent = path10.dirname(dir);
+    const parent = path11.dirname(dir);
     if (parent === dir) break;
     dir = parent;
   }
@@ -3045,15 +3201,15 @@ async function checkForUpdates() {
     }
     const binPath = process.argv?.[1];
     let pkg;
-    if (binPath && fs9.existsSync(binPath)) {
-      const candidatePkg = findPackageJsonNearest(path10.dirname(binPath));
+    if (binPath && fs10.existsSync(binPath)) {
+      const candidatePkg = findPackageJsonNearest(path11.dirname(binPath));
       if (candidatePkg?.name && candidatePkg?.version) {
         pkg = candidatePkg;
       }
     }
     if (!pkg) {
       const __filename = fileURLToPath3(import.meta.url);
-      const __dirname = path10.dirname(__filename);
+      const __dirname = path11.dirname(__filename);
       const result = await readPackageUp({ cwd: __dirname });
       pkg = result?.packageJson;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nomad-e/bluma-cli",
-  "version": "0.0.38",
+  "version": "0.0.40",
   "description": "BluMa independent agent for automation and advanced software engineering.",
   "author": "Alex Fonseca",
   "license": "Apache-2.0",