feat(error-handling): add error escalation protocol to agent templates

moazbuilds · moazbuilds · commit 1a2a3adabef1 · 2025-12-11T18:24:01.000+02:00
Add standardized error escalation protocol across all agent templates to ensure consistent error handling
Include new error-escalation.md shared instruction file
Update placeholder configuration to include error escalation template path
diff --git a/config/placeholders.js b/config/placeholders.js
@@ -22,5 +22,6 @@ module.exports = {
     smart_anchor: path.join('prompts', 'templates', 'codemachine', 'shared-instructions', 'smart-anchor.md'),
     command_constraints: path.join('prompts', 'templates', 'codemachine', 'shared-instructions', 'command-constraints.md'),
     atomic_generation: path.join('prompts', 'templates', 'codemachine', 'shared-instructions', 'atomic-generation.md'),
+    error_escalation: path.join('prompts', 'templates', 'codemachine', 'shared-instructions', 'error-escalation.md'),
   }
 };
diff --git a/prompts/templates/codemachine/main-agents/00-init.md b/prompts/templates/codemachine/main-agents/00-init.md
@@ -16,4 +16,6 @@
     .codemachine/template.json
     ```
 
-**Constraint:** All commands must be safe to run in any repository state, including a newly initialized repository with no commits (an "unborn branch") or a repository in a "detached HEAD" state.
+**Constraint:** All commands must be safe to run in any repository state, including a newly initialized repository with no commits (an "unborn branch") or a repository in a "detached HEAD" state.
+
+{error_escalation}
diff --git a/prompts/templates/codemachine/main-agents/01-principal-analyst.md b/prompts/templates/codemachine/main-agents/01-principal-analyst.md
@@ -124,4 +124,6 @@ The generated artifact **MUST** adhere to the specified assertions count range f
 - Each assertion block should be 15-40 lines.
 - Always include: Observation, Architectural Impact, Default Assumption & Required Action.
 - Solution paths should be presented as clear, mutually exclusive alternatives (Path A, Path B, Tier 1, etc.).
-- The focus must remain on architecturally significant variables.
+- The focus must remain on architecturally significant variables.
+
+{error_escalation}
diff --git a/prompts/templates/codemachine/main-agents/02-blueprint-orchestrator.md b/prompts/templates/codemachine/main-agents/02-blueprint-orchestrator.md
@@ -104,10 +104,17 @@ Your primary directive is successful execution. If anomalies occur, you must fol
 *   **Specific Edge Cases:**
     *   **File System Errors:** If any `ls` command or file system check returns a permission error or other system-level failure, **STOP** immediately and escalate. Report the system error you received.
 
+*   **Command Execution Failures:**
+    *   If the `codemachine run` command fails to execute (command not found, syntax errors, shell errors), do **NOT** attempt to debug or try alternative approaches.
+    *   **STOP IMMEDIATELY** and use the error escalation protocol. Write to behavior.json with action "error" and include the exact error message.
+
 <br>
 
 **6. Constraints**
 
 *   **No Complex Debugging:** Do not analyze the content of files or attempt to debug *why* an agent failed. Your role is to execute, check for files, read summaries, and follow the failure protocol.
 *   **Speed and Specificity:** Your reactions must be fast and limited to the scope of this protocol. Do not introduce any steps not explicitly mentioned.
-*   **Cost Efficiency:** Your purpose is to avoid unnecessary costs. Adhere strictly to the "Resilience Protocol" and the single-retry limit.
+*   **Cost Efficiency:** Your purpose is to avoid unnecessary costs. Adhere strictly to the "Resilience Protocol" and the single-retry limit.
+*   **No Alternative Behaviors:** If commands fail, escalate immediately via the error protocol. Do not attempt workarounds, alternative commands, or creative solutions.
+
+{error_escalation}
diff --git a/prompts/templates/codemachine/main-agents/03-planning-agent.md b/prompts/templates/codemachine/main-agents/03-planning-agent.md
@@ -64,6 +64,8 @@ The plan must follow this specific structure and include all the detailed fields
 
 {command_constraints}
 
+{error_escalation}
+
 {atomic_generation}
 
 ## 5. Iteration Plan
diff --git a/prompts/templates/codemachine/main-agents/04-task-breakdown-agent.md b/prompts/templates/codemachine/main-agents/04-task-breakdown-agent.md
@@ -9,6 +9,8 @@ You MUST follow these steps in the exact order specified. Do not proceed to the
 
 {command_constraints}
 
+{error_escalation}
+
 ---
 
 ### **Workflow**
diff --git a/prompts/templates/codemachine/main-agents/05-context-manager-agent.md b/prompts/templates/codemachine/main-agents/05-context-manager-agent.md
@@ -56,4 +56,6 @@ You are an **AI Technical Lead Analyst**. Your purpose is to act as a senior dev
 
 ### **Output Specification for `context.md`**
 
-{context_output_format}
+{context_output_format}
+
+{error_escalation}
diff --git a/prompts/templates/codemachine/main-agents/06-code-generation-agent.md b/prompts/templates/codemachine/main-agents/06-code-generation-agent.md
@@ -74,6 +74,8 @@ You are an expert developer working collaboratively on a project. Given the foll
 6. Follow the design instructions.
 7. After completing the implementation, update any relevant documentation (README files, API docs, inline comments, etc.) to reflect the changes made.
 
+{error_escalation}
+
 ## Contextual Information:
 
 {context}
diff --git a/prompts/templates/codemachine/main-agents/07-task-validation-agent.md b/prompts/templates/codemachine/main-agents/07-task-validation-agent.md
@@ -73,6 +73,8 @@ Your Verification and Correction Process:
 
 **Do not simply report issues - take action to resolve them until the code fully meets all acceptance criteria.**
 
+{error_escalation}
+
 ## Contextual Information:
 
 {context}
diff --git a/prompts/templates/codemachine/main-agents/08-runtime-preparation-agent.md b/prompts/templates/codemachine/main-agents/08-runtime-preparation-agent.md
@@ -76,6 +76,8 @@ Follow the detailed instructions for each script:
 
 ---
 
+{error_escalation}
+
 ## Contextual Information:
 
 Codebase
diff --git a/prompts/templates/codemachine/shared-instructions/error-escalation.md b/prompts/templates/codemachine/shared-instructions/error-escalation.md
@@ -0,0 +1,36 @@
+#### **Error Escalation Protocol**
+
+When you encounter a critical error that prevents you from completing your task, you **MUST** escalate by writing to the behavior file. **DO NOT** just report errors in chat - the workflow cannot detect chat messages.
+
+**Critical errors include:**
+- Missing required files or dependencies that cannot be resolved
+- Permission denied errors that block execution
+- Invalid or corrupted input data
+- Unrecoverable system failures
+- Configuration errors that prevent task completion
+
+**To escalate an error**, you **MUST** write to `.codemachine/memory/behavior.json`:
+
+```json
+{
+  "action": "error",
+  "reason": "<Clear description of the error with relevant details>"
+}
+```
+
+**MANDATORY:** You must use the Write tool to create this file. Reporting errors in your text response is NOT sufficient - the workflow only reads behavior.json.
+
+**Guidelines for error reasons:**
+- Be specific about what failed and why
+- Include the file path or resource that caused the error
+- Include relevant error messages when helpful
+
+**Example:**
+```json
+{
+  "action": "error",
+  "reason": "Cannot proceed: Required file 'src/config.ts' not found. Database configuration is missing."
+}
+```
+
+**IMPORTANT:** Only use error escalation for truly blocking issues. Attempt recovery or alternative approaches first before escalating.
diff --git a/prompts/templates/codemachine/sub-agents/architecture/01-founder-architect.md b/prompts/templates/codemachine/sub-agents/architecture/01-founder-architect.md
@@ -22,6 +22,8 @@ You are not responsible for creating detailed diagrams or the full architecture
 
 {command_constraints}
 
+{error_escalation}
+
 {atomic_generation}
 
 You **MUST** follow this process without deviation:
diff --git a/prompts/templates/codemachine/sub-agents/architecture/02-structural-data-architect.md b/prompts/templates/codemachine/sub-agents/architecture/02-structural-data-architect.md
@@ -21,6 +21,8 @@ You **MUST** strictly adhere to the decisions made in the `foundation` document,
 
 {command_constraints}
 
+{error_escalation}
+
 {atomic_generation}
 
 1.  **Adhere to Foundation:** All your work **MUST** be consistent with the `foundation` document. The Architectural Style and Technology Stack you list must be copied directly from it. The components you diagram must be the ones named in the foundation.
diff --git a/prompts/templates/codemachine/sub-agents/architecture/03-behavior-architect.md b/prompts/templates/codemachine/sub-agents/architecture/03-behavior-architect.md
@@ -23,6 +23,8 @@ You **MUST** strictly adhere to the components, APIs, and data entities defined
 
 {command_constraints}
 
+{error_escalation}
+
 {atomic_generation}
 
 1.  **Adhere to Foundation:** All your work **MUST** be consistent with the `foundation` document. The API style, components, and data entities you describe must be the ones defined there. Do not invent new components.
diff --git a/prompts/templates/codemachine/sub-agents/architecture/04-operational-architect.md b/prompts/templates/codemachine/sub-agents/architecture/04-operational-architect.md
@@ -25,6 +25,8 @@ You **MUST** strictly adhere to the decisions made in the `foundation` document,
 
 {command_constraints}
 
+{error_escalation}
+
 {atomic_generation}
 
 1.  **Adhere to Foundation:** All your work **MUST** be consistent with the `foundation` document. The Cloud Platform and Containerization choices are mandatory.
diff --git a/prompts/templates/codemachine/sub-agents/architecture/05-ui-ux-architect.md b/prompts/templates/codemachine/sub-agents/architecture/05-ui-ux-architect.md
@@ -23,6 +23,8 @@ You **MUST** strictly adhere to the decisions made in the `foundation` document,
 
 {command_constraints}
 
+{error_escalation}
+
 {atomic_generation}
 
 1.  **Context-Aware Execution:** First, analyze the inputs to determine if a UI is required.
diff --git a/prompts/templates/codemachine/sub-agents/architecture/06-file-assembler.md b/prompts/templates/codemachine/sub-agents/architecture/06-file-assembler.md
@@ -19,6 +19,8 @@ You are **not** a file reader or an analyst. You are a **command executor and te
 
 {command_constraints}
 
+{error_escalation}
+
 {atomic_generation}
 
 You **MUST** follow this three-step process exactly. Do not deviate, add steps, or use alternative methods.

Original file line number	Diff line number	Diff line change
`@@ -22,5 +22,6 @@ module.exports = {`
`22`	`22`	`smart_anchor: path.join('prompts', 'templates', 'codemachine', 'shared-instructions', 'smart-anchor.md'),`
`23`	`23`	`command_constraints: path.join('prompts', 'templates', 'codemachine', 'shared-instructions', 'command-constraints.md'),`
`24`	`24`	`atomic_generation: path.join('prompts', 'templates', 'codemachine', 'shared-instructions', 'atomic-generation.md'),`
	`25`	`+ error_escalation: path.join('prompts', 'templates', 'codemachine', 'shared-instructions', 'error-escalation.md'),`
`25`	`26`	`}`
`26`	`27`	`};`