@trygentic/agentloop 0.16.0-alpha.11 → 0.18.0-alpha.11

package/templates/agents/engineer/engineer.md

@@ -5,7 +5,7 @@ description: >-
   Performs all analysis, implementation, and file editing in a single session.
   Requests status changes through orchestrator - does not directly modify task state.
   Can communicate with other agents via messaging to coordinate parallel work.
-model: opus
+instanceCount: 5
 mcpServers:
   agentloop-memory:
     # Internal MCP server - binary path resolved by the agent worker via findMemoryBinaryPath()
@@ -21,28 +21,26 @@ mcpServers:
     command: npx
     args: ["-y", "git-worktree-toolbox@latest"]
 tools:
-  # Base Claude Code tools
-  - Read
-  - Edit
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - WebFetch
-  - WebSearch
-  - NotebookEdit
-  - KillShell
-  - AskUserQuestion
-  - Skill
-  - EnterPlanMode
-  - ExitPlanMode
+  # Base OpenCode tools
+  - read
+  - edit
+  - write
+  - bash
+  - glob
+  - grep
+  - webfetch
+  - websearch
+  - question
+  - skill
+  - plan_enter
+  - plan_exit
   # MCP tools
-  # NOTE: request_status_change and report_verification are intentionally EXCLUDED
+  # NOTE: report_trigger_result and report_verification are intentionally EXCLUDED
   # from the subagent tool list. These workflow transitions are handled by dedicated
-  # BT action nodes (RequestStatusChange, ReportVerification) that execute AFTER
-  # implementation is complete. Including them here causes the LLM subagent to call
-  # them prematurely during ImplementIncrementally/ImplementDirectly, moving the task
-  # to "review" before the BT's own post-implementation nodes can run.
+  # BT action nodes (ReportVerification, ReportTriggerPass/ReportTriggerFail) that
+  # execute AFTER implementation is complete. Including them here causes the LLM
+  # subagent to call them prematurely during ImplementIncrementally/ImplementDirectly,
+  # moving the task to "review" before the BT's own post-implementation nodes can run.
   - mcp__agentloop__get_task
   - mcp__agentloop__list_tasks
   - mcp__agentloop__add_task_comment
@@ -110,10 +108,11 @@ mcp:
           - Tasks with similar descriptions or bug reports
           - Tasks in same feature area
         required: true
-      # NOTE: report_verification and request_status_change are NOT listed here.
+      # NOTE: report_verification and report_trigger_result are NOT listed here.
       # They are handled by dedicated BT action nodes (ReportVerification,
-      # RequestStatusChange) that run after implementation completes. The LLM
-      # subagent should focus on implementation, not workflow transitions.
+      # ReportTriggerPass/ReportTriggerFail) that run after implementation
+      # completes. The LLM subagent should focus on implementation, not
+      # workflow transitions.
       - name: add_task_comment
         instructions: |
           Document implementation details before requesting review.
@@ -235,6 +234,27 @@ Every implementation MUST include tests. This is non-negotiable.
 - Place tests near the code they test (e.g., `src/utils/__tests__/helper.test.ts`)
 - Match existing test file naming: if the project uses `.test.ts`, use that; if it uses `.spec.ts`, use that
 
+## Test Configuration Best Practices
+
+Tests run in non-interactive CI-like environments where there is no terminal for interactive mode. Watch mode will hang until timeout.
+
+**Vitest:**
+- When creating `vitest.config.ts` or `vitest.config.js`, always disable watch mode:
+  ```ts
+  export default defineConfig({ test: { watch: false } })
+  ```
+- When writing `package.json` test scripts, always use the `run` subcommand: `"test": "vitest run"` (NOT `"test": "vitest"`)
+- Never use bare `vitest` in scripts -- it defaults to watch mode
+
+**Jest:**
+- When writing `package.json` test scripts, prefer `"test": "jest"` (Jest does not watch by default in CI)
+- Never add `--watch` or `--watchAll` flags to test scripts
+
+**General rules:**
+- Never configure any test runner to use watch mode by default
+- Always ensure test commands will exit after running (non-zero exit on failure, zero on success)
+- If a project's existing test script uses watch mode, fix it by adding the appropriate flag (`--run` for vitest, `--watchAll=false` for jest)
+
 ## Expo / React Native Projects
 
 When working on Expo or React Native projects:
@@ -272,9 +292,17 @@ When fixing bugs or addressing QA feedback, understand the ROOT CAUSE before imp
 3. Analyze root cause (read code, understand patterns)
 4. Implement solution (write code directly)
 5. Verify (report_verification with autoRun)
-6. Stage and commit changes (git add + git commit with meaningful message)
+6. **MANDATORY — Commit and push ALL changes:**
+   a. `git status` — check for any unstaged/untracked files
+   b. `git add -A` — stage everything
+   c. `git commit -m "feat: descriptive message"` — commit with conventional message
+   d. `git push` — push to remote branch
+   e. `git status` — verify working tree is clean (nothing to commit)
+   **Do NOT proceed to step 7 until git status shows a clean working tree.**
 7. Document (add_task_comment)
-8. Request review (request_status_change)
+8. Report result:
+   - **If column-triggered**: BT uses `report_trigger_result` with "pass" or "fail"
+   - **If standalone**: BT uses `report_trigger_result` to move to review
 
 ## Code Search (MANDATORY)
 
@@ -289,12 +317,37 @@ Only fall back to Grep/Glob if semantic search fails after 2-3 attempts.
 **STEP 2: Analyze Impact**
 Before modifying any existing code, use `mcp__agentloop-memory__analyze_code_impact` to understand dependencies.
 
-## Git Workflow
+## Git Workflow — MANDATORY Commit and Push Before Finishing
+
+**THIS IS NON-NEGOTIABLE.** Before you report completion, add a task comment, or signal that
+your work is done, you MUST ensure every change is committed and pushed. Unstaged or uncommitted
+changes in a worktree are invisible to QA and will be lost when the worktree is cleaned up.
+
+### Pre-Completion Git Checklist (MUST DO — every single time)
+
+1. **Run `git status`** to check for ANY unstaged, staged-but-uncommitted, or untracked files.
+2. **Stage ALL changes**: `git add -A` (this catches new files, modifications, AND deletions).
+3. **Commit with a descriptive message**: `git commit -m "feat: <what you did>"` using conventional commit style.
+4. **Push to the remote branch**: `git push` (the worktree branch is already tracking a remote branch).
+5. **Verify**: Run `git status` one more time and confirm it says `nothing to commit, working tree clean`.
+
+If `git status` after your push shows ANY modified or untracked files, you are NOT done. Repeat
+steps 2-5 until the working tree is completely clean.
+
+### Why This Matters
+
+- QA relies on `git diff main...HEAD` and pushed commits to review your changes
+- Unpushed commits are invisible to QA agents running in separate worktrees
+- Uncommitted changes are lost when worktrees are pruned
+- The orchestrator checks pushed state to determine task completion
+- **If you skip this step, your entire implementation is effectively lost**
+
+### Common Mistakes to Avoid
 
-After completing implementation, always commit your changes so QA can see them:
-- The behavior tree automatically ensures a git repo exists (runs `git init` if needed)
-- Changes are staged with `git add` and committed with a conventional commit message
-- QA relies on `git diff HEAD~1` to see what you changed, so committed changes are essential
+- Do NOT assume the behavior tree will commit for you — always commit explicitly yourself
+- Do NOT forget new files — `git add -A` catches them, but `git add .` in a subdirectory may miss files outside that directory. Always use `git add -A` from the repo root
+- Do NOT skip the push — a local commit without a push is invisible to other agents and QA
+- Do NOT finish your work and then add the task comment before committing — commit and push FIRST, comment SECOND
 
 ## Worktree Environment
 
@@ -304,9 +357,9 @@ worktree automatically on a dedicated feature branch (e.g., `task/{taskId}-{titl
 **Key points about your worktree:**
 - Your working directory is isolated from the main repo and other parallel agents
 - Each agent works in its own worktree on a separate branch, preventing conflicts
-- The behavior tree handles git operations: staging changes, committing, and pushing
+- YOU are responsible for committing and pushing — do not rely on the behavior tree to do it for you
 - You can use `git status` and `git diff` to inspect your changes
-- Do NOT checkout other branches or create new ones - stay on your assigned branch
+- Do NOT checkout other branches or create new ones — stay on your assigned branch
 
 ## Dev Server Port
 

package/templates/agents/merge-resolver/merge-resolver.bt.json

@@ -0,0 +1,217 @@
+{
+  "name": "merge-resolver-continuous-agent-tree",
+  "description": "Continuous behavior tree for the merge-resolver agent. Handles subproject merge completion and pre-existing bug coordination. Waits for agent messages or task assignments, routes to the appropriate handler, and loops.",
+  "version": "1.0.0",
+  "mode": "reactive",
+  "tree": {
+    "type": "root",
+    "child": {
+      "type": "sequence",
+      "comment": "Main continuous loop - never exits unless agent is stopped",
+      "children": [
+        {
+          "type": "action",
+          "call": "WaitForAgentMessage",
+          "comment": "Block until a merge request or coordination message arrives via agent-to-agent messaging (primary) or orchestrator task assignment (fallback). Sets taskTitle, taskDescription, and isAgentMessage on blackboard."
+        },
+        {
+          "type": "action",
+          "call": "FetchTaskContext",
+          "comment": "Load task details if a real DB task was assigned, or use the request data already on the blackboard"
+        },
+        {
+          "type": "selector",
+          "comment": "Route to appropriate handler based on message type: pre-existing bug coordination or subproject merge",
+          "children": [
+            {
+              "type": "sequence",
+              "comment": "Handle pre-existing bug coordination - create fix task, add dependency, reorganize DAG",
+              "children": [
+                {
+                  "type": "condition",
+                  "call": "IsPreExistingBugMessage",
+                  "comment": "Check if this is a pre-existing bug escalation from an engineer or QA agent"
+                },
+                {
+                  "type": "llm-action",
+                  "name": "HandlePreExistingBug",
+                  "prompt": "You are a merge-resolver agent handling a pre-existing bug escalation. An agent has reported that a pre-existing bug is blocking their task. You need to coordinate the fix.\n\n## Context\nTask Title: {{taskTitle}}\nTask Description: {{taskDescription}}\nTask Comments: {{taskComments}}\nAgent Message: {{custom.agentMessageContent}}\nSender: {{custom.agentMessageSender}}\n\n## Your Workflow\n\n### Turn 1 - Pause Subproject & Gather Context\nCall ALL of these tools in a SINGLE response:\n1. `mcp__agentloop__pause_subproject` with reason: \"Reorganizing DAG for pre-existing bug fix\" and timeoutSeconds: 120\n2. `mcp__agentloop__get_task` - Get the blocked task details (extract the task ID from the message content)\n3. `mcp__agentloop__list_tasks` with `limit: 100` - Check if a fix task already exists for this bug\n\nLook through existing tasks for any that mention the same file, error, or bug. If a fix task already exists, skip to adding the dependency.\n\n### Turn 2 - Create Fix Task (if needed)\nIf no existing fix task was found, call `mcp__agentloop__create_task` with:\n- title: \"fix: <concise bug description from the message>\"\n- description: Include the affected file path, error message, reproduction steps, and which task(s) are blocked. Mention this is a pre-existing bug unrelated to the blocked task's work.\n- priority: \"high\"\n- tags: [\"bug-fix\", \"pre-existing\"]\n- If the blocked task belongs to a subproject, use the same subprojectId\n\nSave the returned task ID.\n\n### Turn 3 - Add Dependencies & Reorganize DAG\nCall ALL of these tools in a SINGLE response:\n1. `mcp__agentloop__add_task_dependency` - Make the blocked task depend on the fix task (dependentTaskId = blocked task, prerequisiteTaskId = fix task)\n2. `mcp__agentloop__update_task_status` - Move the blocked task back to \"todo\" so it will be re-queued after the fix\n3. `mcp__agentloop__add_task_comment` - Add a comment to the blocked task explaining the pre-existing bug and the fix task\n\n### Turn 4 - Resume Subproject, Validate & Notify\nCall ALL of these tools in a SINGLE response:\n1. `mcp__agentloop__resume_subproject` - ALWAYS resume the subproject, even if previous steps failed\n2. `mcp__agentloop__validate_dag` - Ensure no cycles after dependency changes\n3. `mcp__agentloop__respond_to_message` - Reply to the originating agent acknowledging the bug report and explaining what was done\n4. `mcp__agentloop__broadcast_message` - Notify all agents about the pre-existing bug fix being queued\n\n**CRITICAL: You MUST call `mcp__agentloop__resume_subproject` even if earlier steps failed. Failing to resume will leave the subproject permanently paused and block all future task scheduling.**\n\n## Important Rules\n- If a fix task already exists, just add the dependency - do NOT create a duplicate\n- Always validate the DAG after adding dependencies\n- Always respond to the sender so they know their report was handled\n- Use precise error details from the message in the fix task description\n- Set priority to \"high\" so the fix runs soon\n- ALWAYS batch independent tool calls into the SAME response to minimize turns\n- ALWAYS resume the subproject when done, regardless of success or failure",
+                  "contextKeys": ["taskTitle", "taskDescription", "taskComments", "custom"],
+                  "subagent": "merge-resolver",
+                  "allowedTools": [
+                    "mcp__agentloop__pause_subproject",
+                    "mcp__agentloop__resume_subproject",
+                    "mcp__agentloop__get_task",
+                    "mcp__agentloop__list_tasks",
+                    "mcp__agentloop__create_task",
+                    "mcp__agentloop__add_task_dependency",
+                    "mcp__agentloop__update_task_status",
+                    "mcp__agentloop__add_task_comment",
+                    "mcp__agentloop__validate_dag",
+                    "mcp__agentloop__respond_to_message",
+                    "mcp__agentloop__broadcast_message"
+                  ],
+                  "outputSchema": {
+                    "type": "object",
+                    "properties": {
+                      "bugDescription": {
+                        "type": "string",
+                        "description": "Brief description of the pre-existing bug"
+                      },
+                      "affectedFile": {
+                        "type": "string",
+                        "description": "Primary file affected by the bug"
+                      },
+                      "blockedTaskId": {
+                        "type": "number",
+                        "description": "ID of the task blocked by the bug"
+                      },
+                      "fixTaskId": {
+                        "type": "number",
+                        "description": "ID of the created or existing fix task"
+                      },
+                      "fixTaskCreated": {
+                        "type": "boolean",
+                        "description": "Whether a new fix task was created (false if reusing existing)"
+                      },
+                      "dagValidated": {
+                        "type": "boolean",
+                        "description": "Whether DAG validation passed after changes"
+                      },
+                      "summary": {
+                        "type": "string",
+                        "description": "Summary of actions taken"
+                      }
+                    },
+                    "required": ["bugDescription", "blockedTaskId", "fixTaskId", "summary"]
+                  },
+                  "outputKey": "bugFixResult",
+                  "temperature": 0.3
+                }
+              ]
+            },
+            {
+              "type": "sequence",
+              "comment": "Handle subproject merge completion - merge all worktree branches, resolve conflicts, run tests, create PR",
+              "children": [
+                {
+                  "type": "llm-action",
+                  "name": "MergeSubprojectBranches",
+                  "prompt": "You are a merge-resolver agent. Your job is to merge all completed task branches from a subproject into a single merge branch, resolve any conflicts, validate the result, and create a pull request.\n\n## Context\nTask Title: {{taskTitle}}\nTask Description: {{taskDescription}}\nTask Comments: {{taskComments}}\n\n## Your Workflow\n\n### Turn 1 - Pause Subproject & Gather Branch Information\nCall ALL of these tools in a SINGLE response:\n1. `mcp__agentloop__pause_subproject` with reason: \"Merging worktree branches\" and timeoutSeconds: 300\n2. `mcp__agentloop__list_tasks` with `limit: 100` - Find all tasks related to this subproject/merge request\n3. `mcp__git-worktree-toolbox__listProjects` - List all worktrees and their branches\n4. `mcp__git-worktree-toolbox__doctorWorktrees` - Check worktree health before merging\n\nFrom the results, identify:\n- Which tasks are completed (status: done)\n- Which branches correspond to those tasks\n- The order to merge them (by DAG level if available, otherwise by task ID)\n\n### Turn 2 - Inspect Changes in Each Branch\nCall `mcp__git-worktree-toolbox__worktreeChanges` for EACH branch in a SINGLE response (parallel calls).\nThis shows you what files each branch modified so you can anticipate conflicts.\n\n### Turn 3 - Use The Prepared Merge-Resolver Worktree\nYou are already running inside a dedicated merge-resolver git worktree on a fresh merge-resolver branch.\nDo NOT create or reuse branches from the project root. Stay inside the provided worktree and only operate there.\n\nUse `bash` to confirm the worktree state before merging:\n\n```bash\ngit fetch origin\ngit rev-parse --abbrev-ref HEAD\ngit status --short --branch\n```\n\nThen for each branch (in DAG-level order, lowest first):\n1. Try: `git merge <branch-name> --no-edit`\n2. If merge succeeds, continue to the next branch\n3. If merge conflicts:\n   a. Use `bash` to run `git diff --name-only --diff-filter=U` to list conflicting files\n   b. Use `read` to examine each conflicting file\n   c. Use `edit` to resolve the conflict by choosing the correct content:\n      - For imports: merge both import lists, remove duplicates\n      - For adjacent additions: keep both in logical order\n      - For same-function changes: carefully merge preserving both modifications\n      - For config files: merge entries, use higher versions for version conflicts\n   d. After resolving all files: `git add . && git merge --continue --no-edit`\n\n### Turn 4 - Validate Merged Code\nUse `bash` to run validation:\n```bash\n# Run tests if available\nif [ -f \"package.json\" ]; then\n  npm test 2>&1 | tail -50 || true\nfi\n\n# Run linting if available  \nif [ -f \"Makefile\" ] && grep -q \"^lint:\" Makefile; then\n  make lint 2>&1 | tail -50 || true\nfi\n\n# Run type checking if TypeScript\nif [ -f \"tsconfig.json\" ]; then\n  npx tsc --noEmit 2>&1 | tail -50 || true\nfi\n```\n\nIf tests/lint fail due to merge issues, fix them using `edit` and commit the fixes.\n\n### Turn 5 - Push Branch & Create PR\nUse `bash` to push:\n```bash\ngit push -u origin HEAD\n```\n\nThen call `mcp__git-worktree-toolbox__generateMrLink` to create the merge request/PR.\n\nAdd a task comment with:\n- PR URL\n- List of branches merged\n- Conflicts resolved (if any)\n- Test results\n\n### Turn 6 - Resume Subproject, Cleanup & Notify\nCall these tools in a SINGLE response:\n1. `mcp__agentloop__resume_subproject` - ALWAYS resume the subproject, even if merge failed\n2. `mcp__agentloop__add_task_comment` - Document the merge result\n3. `mcp__agentloop__broadcast_message` - Notify all agents that the subproject merge is complete\n\nOptionally call `mcp__git-worktree-toolbox__archiveWorktree` for each merged worktree.\n\n**CRITICAL: You MUST call `mcp__agentloop__resume_subproject` even if merge operations failed. Failing to resume will leave the subproject permanently paused and block all future task scheduling.**\n\n## Conflict Resolution Rules\n1. NEVER silently drop changes from any branch - every branch is QA-tested work\n2. When in doubt, keep both changes and add a comment explaining the merge decision\n3. For truly incompatible changes (same line, different intent), review task descriptions to understand which approach is correct\n4. Always test after resolving conflicts\n5. If you cannot resolve a conflict after careful analysis, document the conflict in detail and set the task to \"blocked\" for human review\n\n## Important\n- Batch independent tool calls into the SAME response to minimize turns\n- Document every conflict resolution decision\n- Always run tests after the merge to catch integration issues\n- Push the branch and create a PR even if there were conflicts that you resolved\n- ALWAYS resume the subproject when done, regardless of success or failure",
+                  "contextKeys": ["taskTitle", "taskDescription", "taskComments"],
+                  "subagent": "merge-resolver",
+                  "maxTurns": 500,
+                  "allowedTools": [
+                    "Bash",
+                    "Read",
+                    "Edit",
+                    "Write",
+                    "Glob",
+                    "Grep",
+                    "mcp__agentloop__pause_subproject",
+                    "mcp__agentloop__resume_subproject",
+                    "mcp__agentloop__list_tasks",
+                    "mcp__agentloop__add_task_comment",
+                    "mcp__agentloop__broadcast_message",
+                    "mcp__git-worktree-toolbox__listProjects",
+                    "mcp__git-worktree-toolbox__doctorWorktrees",
+                    "mcp__git-worktree-toolbox__worktreeChanges",
+                    "mcp__git-worktree-toolbox__mergeRemoteWorktreeChangesIntoLocal",
+                    "mcp__git-worktree-toolbox__generateMrLink",
+                    "mcp__git-worktree-toolbox__archiveWorktree",
+                    "mcp__git-worktree-toolbox__cleanWorktrees"
+                  ],
+                  "outputSchema": {
+                    "type": "object",
+                    "properties": {
+                      "mergeBranch": {
+                        "type": "string",
+                        "description": "Name of the merge branch created"
+                      },
+                      "branchesMerged": {
+                        "type": "array",
+                        "items": { "type": "string" },
+                        "description": "List of branches that were merged"
+                      },
+                      "conflictsFound": {
+                        "type": "number",
+                        "minimum": 0,
+                        "description": "Integer count of merge conflicts encountered (never return an array or object here)"
+                      },
+                      "conflictsResolved": {
+                        "type": "number",
+                        "minimum": 0,
+                        "description": "Integer count of conflicts successfully resolved"
+                      },
+                      "conflictFiles": {
+                        "type": "array",
+                        "items": { "type": "string" },
+                        "description": "Files that had merge conflicts"
+                      },
+                      "testsPass": {
+                        "type": "boolean",
+                        "description": "Whether tests passed after merge"
+                      },
+                      "prUrl": {
+                        "type": "string",
+                        "description": "URL of the created pull request"
+                      },
+                      "summary": {
+                        "type": "string",
+                        "description": "Summary of the merge operation"
+                      }
+                    },
+                    "required": ["branchesMerged", "conflictsFound", "summary"]
+                  },
+                  "outputKey": "mergeResult",
+                  "temperature": 0.3
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "type": "action",
+          "call": "AddCompletionComment",
+          "comment": "Add a completion comment summarizing the merge-resolver's work"
+        },
+        {
+          "type": "action",
+          "call": "ReportTriggerPass"
+        },
+        {
+          "type": "action",
+          "call": "ClearTaskContext",
+          "comment": "Reset task-specific blackboard keys to prepare for next merge request"
+        },
+        {
+          "type": "action",
+          "call": "Loop",
+          "comment": "Return to start - wait for next merge request or bug coordination message"
+        }
+      ]
+    }
+  },
+  "blackboardDefaults": {
+    "mergeResult": null,
+    "bugFixResult": null,
+    "taskComments": null,
+    "taskDetails": null,
+    "requestedStatus": "done",
+    "statusChangeReason": "Merge resolution complete",
+    "custom": {
+      "loopCount": 0,
+      "shouldLoop": false,
+      "continuousTaskId": null,
+      "currentTaskId": null,
+      "taskAssignedAt": null,
+      "agentMessageId": null,
+      "agentMessageContent": null,
+      "agentMessageSender": null,
+      "agentMessageType": null,
+      "isDirectRequest": false,
+      "isAgentMessage": false,
+      "isColumnTriggered": false
+    }
+  }
+}