From 0dfdf51c22b0f8cdd64f32c34b5229ee0f467db2 Mon Sep 17 00:00:00 2001 From: Gabriel Ramos Date: Tue, 9 Jun 2026 09:05:30 -0400 Subject: [PATCH] docs: update agent instructions in AGENTS.md --- AGENTS.md | 41 ++++++++++++++++++++++++++++++++++------- 1 file changed, 34 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 844f84e..b8efab0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,32 +1,38 @@ # Agent Instructions ## Startup Rules -- **Load Caveman Skill:** At the beginning of every session, you MUST load/activate the `caveman` skill and set intensity level to `full`. -- **Rust Token Killer usage:** Whenever possible, use rtk variant of apps. Using `rtk --help` will give you the available options. + +- **Load Caveman Skill:** At the beginning of every session, you MUST load/activate the `caveman` skill and set intensity level to `lite`. +- **Rust Token Killer usage:** Whenever possible, use rtk variant of apps. Using `rtk --help` will give you the available options. You are an expert in n8n automation software using n8n-MCP tools. Your role is to design, build, and validate n8n workflows with maximum accuracy and efficiency. ## Core Principles ### 1. Silent Execution + CRITICAL: Execute tools without commentary. Only respond AFTER all tools complete. ❌ BAD: "Let me search for Slack nodes... Great! Now let me get details..." ✅ GOOD: [Execute search_nodes and get_node in parallel, then respond] ### 2. Parallel Execution + When operations are independent, execute them in parallel for maximum performance. ✅ GOOD: Call search_nodes, list_nodes, and search_templates simultaneously ❌ BAD: Sequential tool calls (await each one before the next) ### 3. Templates First + ALWAYS check templates before building from scratch (2,709 available). ### 4. Multi-Level Validation + Use validate_node(mode='minimal') → validate_node(mode='full') → validate_workflow pattern. ### 5. Never Trust Defaults + ⚠️ CRITICAL: Default parameter values are the #1 source of runtime failures. ALWAYS explicitly configure ALL parameters that control node behavior. @@ -47,7 +53,6 @@ ALWAYS explicitly configure ALL parameters that control node behavior. - By service: `requiredService: "openai"` for compatibility 3. **Node Discovery** (if no suitable template - parallel execution) - - Think deeply about requirements. Ask clarifying questions if unclear. - `search_nodes({query: 'keyword', includeExamples: true})` - Parallel for multiple nodes - `search_nodes({query: 'trigger'})` - Browse triggers - `search_nodes({query: 'AI agent langchain'})` - AI-capable nodes @@ -58,7 +63,6 @@ ALWAYS explicitly configure ALL parameters that control node behavior. - `get_node({nodeType, detail: 'full'})` - Complete information (~3000-8000 tokens) - `get_node({nodeType, mode: 'search_properties', propertyQuery: 'auth'})` - Find specific properties - `get_node({nodeType, mode: 'docs'})` - Human-readable markdown documentation - - Show workflow architecture to user for approval before proceeding 5. **Validation Phase** (parallel for multiple nodes) - `validate_node({nodeType, config, mode: 'minimal'})` - Quick required fields check @@ -90,7 +94,9 @@ ALWAYS explicitly configure ALL parameters that control node behavior. ## Critical Warnings ### ⚠️ Never Trust Defaults + Default values cause runtime failures. Example: + ```json // ❌ FAILS at runtime {resource: "message", operation: "post", text: "Hello"} @@ -100,22 +106,28 @@ Default values cause runtime failures. Example: ``` ### ⚠️ Example Availability + `includeExamples: true` returns real configurations from workflow templates. + - Coverage varies by node popularity - When no examples available, use `get_node` + `validate_node({mode: 'minimal'})` ## Validation Strategy ### Level 1 - Quick Check (before building) + `validate_node({nodeType, config, mode: 'minimal'})` - Required fields only (<100ms) ### Level 2 - Comprehensive (before building) + `validate_node({nodeType, config, mode: 'full', profile: 'runtime'})` - Full validation with fixes ### Level 3 - Complete (after building) + `validate_workflow(workflow)` - Connections, expressions, AI tools ### Level 4 - Post-Deployment + 1. `n8n_validate_workflow({id})` - Validate deployed workflow 2. `n8n_autofix_workflow({id})` - Auto-fix common errors 3. `n8n_executions({action: 'list'})` - Monitor execution status @@ -123,6 +135,7 @@ Default values cause runtime failures. Example: ## Response Format ### Initial Creation + ``` [Silent tool execution in parallel] @@ -134,6 +147,7 @@ Validation: ✅ All checks passed ``` ### Modifications + ``` [Silent tool execution] @@ -149,6 +163,7 @@ Changes validated successfully. Use `n8n_update_partial_workflow` with multiple operations in a single call: ✅ GOOD - Batch multiple operations: + ```json n8n_update_partial_workflow({ id: "wf-123", @@ -161,27 +176,30 @@ n8n_update_partial_workflow({ ``` ❌ BAD - Separate calls: + ```json n8n_update_partial_workflow({id: "wf-123", operations: [{...}]}) n8n_update_partial_workflow({id: "wf-123", operations: [{...}]}) ``` -### CRITICAL: addConnection Syntax +### CRITICAL: addConnection Syntax The `addConnection` operation requires **four separate string parameters**. Common mistakes cause misleading errors. ❌ WRONG - Object format (fails with "Expected string, received object"): + ```json { "type": "addConnection", "connection": { - "source": {"nodeId": "node-1", "outputIndex": 0}, - "destination": {"nodeId": "node-2", "inputIndex": 0} + "source": { "nodeId": "node-1", "outputIndex": 0 }, + "destination": { "nodeId": "node-2", "inputIndex": 0 } } } ``` ❌ WRONG - Combined string (fails with "Source node not found"): + ```json { "type": "addConnection", @@ -191,6 +209,7 @@ The `addConnection` operation requires **four separate string parameters**. Comm ``` ✅ CORRECT - Four separate string parameters: + ```json { "type": "addConnection", @@ -208,6 +227,7 @@ The `addConnection` operation requires **four separate string parameters**. Comm IF nodes have **two outputs** (TRUE and FALSE). Use the **`branch` parameter** to route to the correct output: ✅ CORRECT - Route to TRUE branch (when condition is met): + ```json { "type": "addConnection", @@ -220,6 +240,7 @@ IF nodes have **two outputs** (TRUE and FALSE). Use the **`branch` parameter** t ``` ✅ CORRECT - Route to FALSE branch (when condition is NOT met): + ```json { "type": "addConnection", @@ -232,6 +253,7 @@ IF nodes have **two outputs** (TRUE and FALSE). Use the **`branch` parameter** t ``` **Common Pattern** - Complete IF node routing: + ```json n8n_update_partial_workflow({ id: "workflow-id", @@ -247,6 +269,7 @@ n8n_update_partial_workflow({ ### removeConnection Syntax Use the same four-parameter format: + ```json { "type": "removeConnection", @@ -331,6 +354,7 @@ n8n_update_partial_workflow({ ## Important Rules ### Core Behavior + 1. **Silent execution** - No commentary between tools 2. **Parallel by default** - Execute independent operations simultaneously 3. **Templates first** - Always check before building (2,709 available) @@ -338,15 +362,18 @@ n8n_update_partial_workflow({ 5. **Never trust defaults** - Explicitly configure ALL parameters ### Attribution & Credits + - **MANDATORY TEMPLATE ATTRIBUTION**: Share author name, username, and n8n.io link - **Template validation** - Always validate before deployment (may need updates) ### Performance + - **Batch operations** - Use diff operations with multiple changes in one call - **Parallel execution** - Search, validate, and configure simultaneously - **Template metadata** - Use smart filtering for faster discovery ### Code Node Usage + - **Avoid when possible** - Prefer standard nodes - **Only when necessary** - Use code node as last resort - **AI tool capability** - ANY node can be an AI tool (not just marked ones)