TOOLS FIRST GUIDELINES GORKA.instructions

---
applyTo: '**'
description: 'Tools First - Guidelines for preferring specialized tools over CLI commands across all Gorka agents.'
---

---
title: "Tools First - Preference Guidelines"
date: "2025-07-24"
last_updated: "2025-07-24T19:21:26+02:00"
author: "@bohdan-shulha"
timezone: "Europe/Warsaw"
status: "approved"
version: "1.0.0"
document_type: "instructions"
---

# Tools First - Preference Guidelines for Gorka Agents

## Core Principle

### 1. **CRITICAL: Always Prefer Tools Over CLI Commands**
- **Primary Rule**: When both a specialized tool and CLI command can accomplish the same task, ALWAYS choose the tool
- **Tools are Superior**: They provide better error handling, structured output, and integration
- **CLI as Fallback**: Use CLI commands ONLY when no suitable tool exists
- **Consistency**: All agents must follow this principle uniformly

### 2. **Tool-First Decision Matrix**

| Task Type | Preferred Approach | Fallback |
|-----------|-------------------|----------|
| **Git Operations** | `git_diff`, `git_status`, `git_log` tools | `runCommands` for unsupported git operations |
| **File Operations** | `editFiles`, `codebase`, `search` tools | `runCommands` for complex file system operations |
| **Code Analysis** | `problems`, `usages`, `findTestFiles` tools | `runCommands` for specialized analysis scripts |
| **Project Management** | `runTasks`, `runTests` tools | `runCommands` for custom build scripts |
| **Workspace Setup** | `secondbrain-cli components install` | Manual file creation only if CLI unavailable |
| **Time Operations** | `get_current_time` tool | Never use CLI date commands |
| **Memory Operations** | Memory MCP tools | Never use CLI for data persistence |
| **Documentation** | `fetch`, specialized research tools | `runCommands` for file system navigation only |

## Tool Categories and Preferences

### 3. **Version Control Operations**