@trygentic/agentloop 0.19.0-alpha.11 → 0.21.0-alpha.11

package/README.md

@@ -388,7 +388,6 @@ The AgentLoop daemon allows you to run the orchestrator as a persistent backgrou
 | `/orchestrator run --infinite` | Run continuously, watching for new tasks |
 | `/orchestrator generate <description>` | Generate AGILE tasks from a project description |
 | `/orchestrator status` | Show current orchestrator status |
-| `/orchestrator agents` | Live agent monitoring with real-time status |
 | `/orchestrator kanban` | Open interactive kanban board |
 | `/orchestrator stop` | Stop the running orchestrator |
 | `/orchestrator clear` | Clear all tasks for the current project |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trygentic/agentloop",
-  "version": "0.19.0-alpha.11",
+  "version": "0.21.0-alpha.11",
   "description": "AI-powered autonomous coding agent",
   "bin": {
     "agentloop": "./bin/agentloop"
@@ -9,8 +9,8 @@
     "postinstall": "node ./scripts/postinstall.mjs"
   },
   "optionalDependencies": {
-    "@trygentic/agentloop-darwin-arm64": "0.19.0-alpha.11",
-    "@trygentic/agentloop-linux-x64": "0.19.0-alpha.11"
+    "@trygentic/agentloop-darwin-arm64": "0.21.0-alpha.11",
+    "@trygentic/agentloop-linux-x64": "0.21.0-alpha.11"
   },
   "engines": {
     "node": ">=18.0.0"

package/templates/agents/electron-engineer/electron-engineer.bt.json

@@ -0,0 +1,7 @@
+{
+  "name": "electron-engineer-tree",
+  "description": "Electron-specialized engineer behavior tree that inherits the base engineer workflow.",
+  "version": "1.0.0",
+  "format": "json",
+  "extends": "engineer"
+}

package/templates/agents/electron-engineer/electron-engineer.md

@@ -0,0 +1,46 @@
+---
+name: electron-engineer
+extends: engineer
+scope: worktree
+triggeredByColumns:
+  - in-progress
+description: >-
+  Engineer specialized for Electron startup, preload, and renderer work.
+  Inherits the base engineer workflow and adds Electron-specific runtime
+  guardrails and verification requirements.
+---
+
+# Electron Engineer
+
+You are an implementation agent for Electron applications. Follow all base `engineer` instructions, plus the Electron startup guardrails below.
+
+## Electron Startup Guardrails
+
+Apply these whenever a task touches Electron main/preload/renderer startup, boot wiring, or desktop scripts.
+
+1. Dist root correctness:
+   - Prefer `dist/desktop` as the desktop dist root when present.
+   - Treat `dist/src` as legacy fallback only; do not hardcode new startup logic to `dist/src/...`.
+2. Preload compatibility:
+   - Ensure preload script parses and runs in Electron (`contextBridge` wiring installs without runtime errors).
+   - Any preload parse/runtime failure is a release blocker.
+3. Renderer reachability expectations:
+   - If QA expects an HTTP renderer URL, do not assume `data:`/`file:` renderers are acceptable unless the QA flow explicitly supports embedded transport.
+   - Verify required renderer env wiring (for example `AGENTLOOP_DESKTOP_RENDERER_URL`) when startup depends on it.
+4. React dependency and cache hygiene:
+   - Keep `react` and `react-dom` versions aligned.
+   - If behavior looks stale after dependency changes, invalidate/rebuild renderer bundle cache.
+
+## Required Verification Commands
+
+Run these before handoff for Electron startup-related tasks:
+
+1. `npm run build:ts-only`
+2. `npm run desktop:dev` (or `node scripts/desktop-dev.mjs` if that is the repo-standard launch path)
+
+## Failure Signatures (Must Be Absent Before Handoff)
+
+- `Failed to resolve module specifier`
+- `Cannot find module` (desktop renderer/preload path)
+- `[desktop-preload] bridge install failed`
+- `Invalid hook call` (or mixed React version symptoms)

package/templates/agents/engineer/engineer.bt.json

@@ -19,6 +19,51 @@
           "call": "FetchTaskContext",
           "comment": "Load task details, comments, and determine if this is a QA rejection re-work"
         },
+        {
+          "type": "action",
+          "call": "LoadProjectSpecifications",
+          "comment": "Load current-phase specification documents from .agentloop/specifications/ so engineer work is grounded in the active planning context"
+        },
+        {
+          "type": "selector",
+          "comment": "Summarize current-phase specifications if available so implementation stays scoped but informed",
+          "children": [
+            {
+              "type": "sequence",
+              "children": [
+                {
+                  "type": "condition",
+                  "call": "HasProjectSpecifications",
+                  "comment": "Only summarize if current-phase specifications were loaded"
+                },
+                {
+                  "type": "llm-action",
+                  "name": "SummarizeProjectSpecifications",
+                  "prompt": "Distill the following current-phase project specification documents into a compact implementation brief for an engineer. Extract ONLY what is explicitly stated.\n\n## Raw Specifications\n{{projectSpecifications}}\n\n## Output Format\nProduce a structured summary covering ONLY sections that have explicit information:\n\n### Phase Goal\nWhat this phase is trying to deliver.\n\n### Required Technologies\nList every explicitly required runtime, framework, UI library, state/store layer, test stack, and infrastructure dependency. Copy exact names.\n\n### Required File Paths And Modules\nList every explicit path, directory, component, module, or artifact named in the specs.\n\n### Implementation Constraints\nList architectural boundaries, banned substitutions, process-boundary rules, and UX constraints.\n\n### Acceptance Criteria\nList the concrete testable success conditions.\n\n### Non-Goals\nList what the phase explicitly does not include.\n\nBe exhaustive on details but terse on prose. Do not widen scope beyond the described phase.",
+                  "contextKeys": ["projectSpecifications"],
+                  "outputSchema": {
+                    "type": "object",
+                    "properties": {
+                      "summary": {
+                        "type": "string",
+                        "description": "Structured implementation-focused summary of current-phase specifications"
+                      }
+                    },
+                    "required": ["summary"]
+                  },
+                  "outputKey": "projectSpecSummary",
+                  "temperature": 0.1,
+                  "allowedTools": []
+                }
+              ]
+            },
+            {
+              "type": "action",
+              "call": "NoOp",
+              "comment": "Continue without spec summarization if no current-phase specs are available"
+            }
+          ]
+        },
         {
           "type": "selector",
           "comment": "Check for incoming agent messages (non-critical: continue even if unavailable)",
@@ -101,14 +146,16 @@
                         {
                           "type": "llm-action",
                           "name": "AnalyzeQAFeedbackAndFix",
-                          "prompt": "You are an engineer agent handling a QA rejection. The task was previously submitted for review but QA found issues that need to be fixed.\n\nTask: {{taskDescription}}\n\nQA Feedback and Previous Comments:\n{{taskComments}}\n\nCodebase Context:\n{{codebaseContext}}\n\nPrevious Analysis (if any):\n{{taskAnalysis}}\n\n## CRITICAL: YOU MUST MAKE CODE CHANGES\nQA found issues during actual app testing (E2E/runtime). This means the current code has bugs that MUST be fixed with code changes. DO NOT just run unit tests and conclude nothing needs fixing. Unit tests passing does NOT mean runtime errors are fixed \u2014 QA tests the actual running app and found real problems.\n\nIf unit tests pass but QA reported runtime errors, that means:\n- The unit tests don't cover the failing scenario, OR\n- The bug only manifests at runtime (wrong imports, missing props, incorrect component rendering, etc.)\n\nYou MUST:\n1. Read the QA feedback carefully to understand the EXACT runtime error\n2. Find the root cause in the source code (not just the test code)\n3. Make actual code changes to fix the issue\n4. If the bug isn't obvious, add a NEW test that reproduces the QA-reported failure\n5. Verify your fix with tests\n\nDO NOT conclude 'no changes needed' \u2014 QA rejected this task because something is broken. Find it and fix it.\n\n**Codebase Exploration Strategy (FOLLOW THIS ORDER):**\n1. FIRST use agentloop-memory MCP tools for intelligent code discovery (the code graph was already indexed):\n   - `mcp__agentloop-memory__semantic_search` \u2014 find relevant code by natural language description\n   - `mcp__agentloop-memory__query` \u2014 combined semantic + structural search\n   - `mcp__agentloop-memory__find_similar_code` \u2014 find existing patterns similar to what you need\n   - `mcp__agentloop-memory__list_file_entities` \u2014 enumerate functions, classes, and exports in a file\n   - `mcp__agentloop-memory__list_entity_relationships` \u2014 trace imports, references, and dependencies\n   - `mcp__agentloop-memory__analyze_code_impact` \u2014 understand what depends on code you plan to change\n2. THEN use Read to examine specific file contents, and Grep/Glob for targeted text searches or file pattern matching\n3. If agentloop-memory tools fail or return no results after 2-3 attempts, fall back to Grep/Glob\n\nIMPORTANT: Each change must include the full 'code' field with the complete file content to write. Address ALL QA feedback - partial fixes will result in another rejection.\n\nYou MUST produce at least one code change. If you cannot find the exact bug, at minimum add a regression test that verifies the scenario QA reported.",
+                          "prompt": "You are an engineer agent handling a QA rejection. The task was previously submitted for review but QA found issues that need to be fixed.\n\n{{#if projectSpecSummary}}\n## Project Specification Summary\n{{projectSpecSummary}}\n\nYour implementation MUST use the specific technologies, file paths, data storage approaches, and constraints described above. These specifications are authoritative — do not substitute alternative libraries, patterns, or approaches unless the specs are technically impossible to implement.\n{{else if projectSpecifications}}\n## Project Specifications (Raw)\n{{projectSpecifications}}\n\nYour implementation MUST use the specific technologies, file paths, and constraints described above. These specifications are authoritative.\n{{/if}}\n\nTask: {{taskDescription}}\n\nQA Feedback and Previous Comments:\n{{taskComments}}\n\nCodebase Context:\n{{codebaseContext}}\n\nPrevious Analysis (if any):\n{{taskAnalysis}}\n\n## CRITICAL: YOU MUST MAKE CODE CHANGES\nQA found issues during actual app testing (E2E/runtime). This means the current code has bugs that MUST be fixed with code changes. DO NOT just run unit tests and conclude nothing needs fixing. Unit tests passing does NOT mean runtime errors are fixed \u2014 QA tests the actual running app and found real problems.\n\nIf unit tests pass but QA reported runtime errors, that means:\n- The unit tests don't cover the failing scenario, OR\n- The bug only manifests at runtime (wrong imports, missing props, incorrect component rendering, etc.)\n\nYou MUST:\n1. Read the QA feedback carefully to understand the EXACT runtime error\n2. Find the root cause in the source code (not just the test code)\n3. Make actual code changes to fix the issue\n4. If the bug isn't obvious, add a NEW test that reproduces the QA-reported failure\n5. Verify your fix with tests\n\nDO NOT conclude 'no changes needed' \u2014 QA rejected this task because something is broken. Find it and fix it.\n\n**Codebase Exploration Strategy (FOLLOW THIS ORDER):**\n1. FIRST use agentloop-memory MCP tools for intelligent code discovery (the code graph was already indexed):\n   - `mcp__agentloop-memory__semantic_search` \u2014 find relevant code by natural language description\n   - `mcp__agentloop-memory__query` \u2014 combined semantic + structural search\n   - `mcp__agentloop-memory__find_similar_code` \u2014 find existing patterns similar to what you need\n   - `mcp__agentloop-memory__list_file_entities` \u2014 enumerate functions, classes, and exports in a file\n   - `mcp__agentloop-memory__list_entity_relationships` \u2014 trace imports, references, and dependencies\n   - `mcp__agentloop-memory__analyze_code_impact` \u2014 understand what depends on code you plan to change\n2. THEN use Read to examine specific file contents, and Grep/Glob for targeted text searches or file pattern matching\n3. If agentloop-memory tools fail or return no results after 2-3 attempts, fall back to Grep/Glob\n\nIMPORTANT: Each change must include the full 'code' field with the complete file content to write. Address ALL QA feedback - partial fixes will result in another rejection.\n\nYou MUST produce at least one code change. If you cannot find the exact bug, at minimum add a regression test that verifies the scenario QA reported.",
                           "minTurns": 5,
                           "contextKeys": [
                             "taskDescription",
                             "taskTitle",
                             "taskComments",
                             "codebaseContext",
-                            "taskAnalysis"
+                            "taskAnalysis",
+                            "projectSpecifications",
+                            "projectSpecSummary"
                           ],
                           "subagent": "engineer",
                           "maxTurns": 50,
@@ -235,12 +282,14 @@
                         {
                           "type": "llm-action",
                           "name": "AnalyzeTask",
-                          "prompt": "You are an engineer agent analyzing a task. Examine the task requirements and the codebase context provided. Determine the complexity of the task and identify which files will likely need to be modified.\n\nTask: {{taskDescription}}\n\n{{taskComments}}\n\nIMPORTANT: Only reference files and directories that appear in the codebase context. Do NOT guess or hallucinate file paths that are not listed there.\n\nIf this task was previously rejected by QA, pay close attention to the feedback in the comments above. Address ALL issues mentioned by QA in your implementation.\n\nIMPORTANT: Always plan to include tests for your implementation. Use the project's EXISTING test framework \u2014 check codebase context for test runner, test scripts, and existing test files. Do NOT add a new test framework or test runner configuration (no jest.config, vitest.config, etc.). Follow the naming conventions and import patterns found in existing test files.\n\nProvide a thorough analysis of what needs to be done, including what tests you will create.",
+                          "prompt": "You are an engineer agent analyzing a task. Examine the task requirements and the codebase context provided. Determine the complexity of the task and identify which files will likely need to be modified.\n\n{{#if projectSpecSummary}}\n## Project Specification Summary\n{{projectSpecSummary}}\n\nYour implementation MUST use the specific technologies, file paths, data storage approaches, and constraints described above. These specifications are authoritative — do not substitute alternative libraries, patterns, or approaches unless the specs are technically impossible to implement.\n{{else if projectSpecifications}}\n## Project Specifications (Raw)\n{{projectSpecifications}}\n\nYour implementation MUST use the specific technologies, file paths, and constraints described above. These specifications are authoritative.\n{{/if}}\n\nTask: {{taskDescription}}\n\n{{taskComments}}\n\nIMPORTANT: Only reference files and directories that appear in the codebase context. Do NOT guess or hallucinate file paths that are not listed there.\n\nIf this task was previously rejected by QA, pay close attention to the feedback in the comments above. Address ALL issues mentioned by QA in your implementation.\n\nIMPORTANT: Always plan to include tests for your implementation. Use the project's EXISTING test framework \u2014 check codebase context for test runner, test scripts, and existing test files. Do NOT add a new test framework or test runner configuration (no jest.config, vitest.config, etc.). Follow the naming conventions and import patterns found in existing test files.\n\nProvide a thorough analysis of what needs to be done, including what tests you will create.",
                           "contextKeys": [
                             "taskDescription",
                             "taskTitle",
                             "codebaseContext",
-                            "taskComments"
+                            "taskComments",
+                            "projectSpecifications",
+                            "projectSpecSummary"
                           ],
                           "outputSchema": {
                             "type": "object",
@@ -314,12 +363,14 @@
                               "child": {
                                 "type": "llm-action",
                                 "name": "ImplementDirectly",
-                                "prompt": "Implement the task directly. Generate the code changes needed.\n\nTask: {{taskDescription}}\nAnalysis: {{taskAnalysis}}\n\n{{taskComments}}\n\nIf this task was previously rejected by QA, make sure your implementation addresses ALL the issues mentioned in their feedback.\n\nYou already have codebase context, task analysis, and task details in your context. Start implementing immediately \u2014 do NOT return empty changes or claim you need more exploration.\n\n**Codebase Exploration Strategy (FOLLOW THIS ORDER):**\n1. FIRST use agentloop-memory MCP tools for intelligent code discovery (the code graph was already indexed):\n   - `mcp__agentloop-memory__semantic_search` \u2014 find relevant code by natural language description (e.g., search for concepts, function purposes, feature areas)\n   - `mcp__agentloop-memory__query` \u2014 combined semantic + structural search for broader discovery\n   - `mcp__agentloop-memory__find_similar_code` \u2014 find existing patterns similar to what you need to implement\n   - `mcp__agentloop-memory__list_file_entities` \u2014 enumerate functions, classes, and exports in a specific file\n   - `mcp__agentloop-memory__list_entity_relationships` \u2014 trace imports, references, and dependencies between entities\n   - `mcp__agentloop-memory__analyze_code_impact` \u2014 understand what depends on code you plan to change (blast radius)\n2. THEN use Read to examine specific file contents, and Grep/Glob for targeted text searches or file pattern matching\n3. If agentloop-memory tools fail or return no results after 2-3 attempts, fall back to Grep/Glob\n\nIMPORTANT: Always include test files alongside your implementation. Create at least one test file that verifies the core functionality. Use the project's EXISTING test framework and test runner \u2014 check codebase context for what test framework the project uses, what test scripts are available, and how existing test files are structured. Do NOT install or configure a new test framework (no jest.config.js, no vitest.config.ts, etc.). Follow the naming conventions, import patterns, and directory structure of existing test files in the project.\n\n**CRITICAL: Read Before Edit Rule:**\nYou MUST call the `read` tool on any existing file BEFORE calling `edit` on it. The edit tool validates that you've read the file first. If you skip the read, the edit will fail with \"You must read file X before overwriting it.\" For new files, use the `write` tool instead of `edit`.\n\nProvide the implementation with file paths and complete code content for each file.\n\nIMPORTANT: Each change must include the full 'code' field with the complete file content to write. Include both implementation files AND test files in the changes array. You MUST produce at least one file change.\n\n**Test Configuration Rules (CRITICAL):**\n- Tests run in a non-interactive CI-like environment. NEVER configure tests to use watch mode.\n- When creating vitest.config.ts/js, always set `test: { watch: false }` or use `defineConfig({ test: { watch: false } })`.\n- When writing package.json test scripts with vitest, ALWAYS use `\"test\": \"vitest run\"` (NOT `\"test\": \"vitest\"`).\n- For jest, always include `--watchAll=false` in the test script if needed.\n- Never add `--watch` or `--watchAll` flags to test scripts.",
+                                "prompt": "Implement the task directly. Generate the code changes needed.\n\n{{#if projectSpecSummary}}\n## Project Specification Summary\n{{projectSpecSummary}}\n\nYour implementation MUST use the specific technologies, file paths, data storage approaches, and constraints described above. These specifications are authoritative — do not substitute alternative libraries, patterns, or approaches unless the specs are technically impossible to implement.\n{{else if projectSpecifications}}\n## Project Specifications (Raw)\n{{projectSpecifications}}\n\nYour implementation MUST use the specific technologies, file paths, and constraints described above. These specifications are authoritative.\n{{/if}}\n\nTask: {{taskDescription}}\nAnalysis: {{taskAnalysis}}\n\n{{taskComments}}\n\nIf this task was previously rejected by QA, make sure your implementation addresses ALL the issues mentioned in their feedback.\n\nYou already have codebase context, task analysis, and task details in your context. Start implementing immediately \u2014 do NOT return empty changes or claim you need more exploration.\n\n**Codebase Exploration Strategy (FOLLOW THIS ORDER):**\n1. FIRST use agentloop-memory MCP tools for intelligent code discovery (the code graph was already indexed):\n   - `mcp__agentloop-memory__semantic_search` \u2014 find relevant code by natural language description (e.g., search for concepts, function purposes, feature areas)\n   - `mcp__agentloop-memory__query` \u2014 combined semantic + structural search for broader discovery\n   - `mcp__agentloop-memory__find_similar_code` \u2014 find existing patterns similar to what you need to implement\n   - `mcp__agentloop-memory__list_file_entities` \u2014 enumerate functions, classes, and exports in a specific file\n   - `mcp__agentloop-memory__list_entity_relationships` \u2014 trace imports, references, and dependencies between entities\n   - `mcp__agentloop-memory__analyze_code_impact` \u2014 understand what depends on code you plan to change (blast radius)\n2. THEN use Read to examine specific file contents, and Grep/Glob for targeted text searches or file pattern matching\n3. If agentloop-memory tools fail or return no results after 2-3 attempts, fall back to Grep/Glob\n\nIMPORTANT: Always include test files alongside your implementation. Create at least one test file that verifies the core functionality. Use the project's EXISTING test framework and test runner \u2014 check codebase context for what test framework the project uses, what test scripts are available, and how existing test files are structured. Do NOT install or configure a new test framework (no jest.config.js, no vitest.config.ts, etc.). Follow the naming conventions, import patterns, and directory structure of existing test files in the project.\n\n**CRITICAL: Read Before Edit Rule:**\nYou MUST call the `read` tool on any existing file BEFORE calling `edit` on it. The edit tool validates that you've read the file first. If you skip the read, the edit will fail with \"You must read file X before overwriting it.\" For new files, use the `write` tool instead of `edit`.\n\nProvide the implementation with file paths and complete code content for each file.\n\nIMPORTANT: Each change must include the full 'code' field with the complete file content to write. Include both implementation files AND test files in the changes array. You MUST produce at least one file change.\n\n**Test Configuration Rules (CRITICAL):**\n- Tests run in a non-interactive CI-like environment. NEVER configure tests to use watch mode.\n- When creating vitest.config.ts/js, always set `test: { watch: false }` or use `defineConfig({ test: { watch: false } })`.\n- When writing package.json test scripts with vitest, ALWAYS use `\"test\": \"vitest run\"` (NOT `\"test\": \"vitest\"`).\n- For jest, always include `--watchAll=false` in the test script if needed.\n- Never add `--watch` or `--watchAll` flags to test scripts.",
                                 "contextKeys": [
                                   "taskDescription",
                                   "taskAnalysis",
                                   "codebaseContext",
-                                  "taskComments"
+                                  "taskComments",
+                                  "projectSpecifications",
+                                  "projectSpecSummary"
                                 ],
                                 "subagent": "engineer",
                                 "maxTurns": 500,
@@ -444,12 +495,14 @@
                                   {
                                     "type": "llm-action",
                                     "name": "CreateImplementationPlan",
-                                    "prompt": "Create a detailed implementation plan for this complex task.\n\nTask: {{taskDescription}}\nAnalysis: {{taskAnalysis}}\n\n{{taskComments}}\n\nIMPORTANT: Only reference files and directories that appear in the codebase context. Do NOT guess or hallucinate file paths that are not listed there. Adapt your plan to match the actual project layout.\n\nIf this task was previously rejected by QA, incorporate their feedback into your plan.\n\nIMPORTANT: Include test creation as part of your implementation steps. Each step that creates functionality should have a corresponding test step or include tests within it.\n\nBreak down the implementation into clear steps with dependencies.",
+                                    "prompt": "Create a detailed implementation plan for this complex task.\n\n{{#if projectSpecSummary}}\n## Project Specification Summary\n{{projectSpecSummary}}\n\nYour implementation MUST use the specific technologies, file paths, data storage approaches, and constraints described above. These specifications are authoritative — do not substitute alternative libraries, patterns, or approaches unless the specs are technically impossible to implement.\n{{else if projectSpecifications}}\n## Project Specifications (Raw)\n{{projectSpecifications}}\n\nYour implementation MUST use the specific technologies, file paths, and constraints described above. These specifications are authoritative.\n{{/if}}\n\nTask: {{taskDescription}}\nAnalysis: {{taskAnalysis}}\n\n{{taskComments}}\n\nIMPORTANT: Only reference files and directories that appear in the codebase context. Do NOT guess or hallucinate file paths that are not listed there. Adapt your plan to match the actual project layout.\n\nIf this task was previously rejected by QA, incorporate their feedback into your plan.\n\nIMPORTANT: Include test creation as part of your implementation steps. Each step that creates functionality should have a corresponding test step or include tests within it.\n\nBreak down the implementation into clear steps with dependencies.",
                                     "contextKeys": [
                                       "taskDescription",
                                       "taskAnalysis",
                                       "codebaseContext",
-                                      "taskComments"
+                                      "taskComments",
+                                      "projectSpecifications",
+                                      "projectSpecSummary"
                                     ],
                                     "outputSchema": {
                                       "type": "object",
@@ -518,13 +571,15 @@
                                   {
                                     "type": "llm-action",
                                     "name": "ImplementIncrementally",
-                                    "prompt": "Execute the implementation plan step by step.\n\nPlan: {{implementationPlan}}\nTask: {{taskDescription}}\n\n{{taskComments}}\n\nGenerate all the code changes according to the plan. Make sure to address any QA feedback from previous attempts.\n\nYou already have the codebase context, task analysis, and implementation plan in your context. Start implementing immediately \u2014 do NOT return empty changes or claim you need more exploration.\n\n**Codebase Exploration Strategy (FOLLOW THIS ORDER):**\n1. FIRST use agentloop-memory MCP tools for intelligent code discovery (the code graph was already indexed):\n   - `mcp__agentloop-memory__semantic_search` \u2014 find relevant code by natural language description (e.g., search for concepts, function purposes, feature areas)\n   - `mcp__agentloop-memory__query` \u2014 combined semantic + structural search for broader discovery\n   - `mcp__agentloop-memory__find_similar_code` \u2014 find existing patterns similar to what you need to implement\n   - `mcp__agentloop-memory__list_file_entities` \u2014 enumerate functions, classes, and exports in a specific file\n   - `mcp__agentloop-memory__list_entity_relationships` \u2014 trace imports, references, and dependencies between entities\n   - `mcp__agentloop-memory__analyze_code_impact` \u2014 understand what depends on code you plan to change (blast radius)\n2. THEN use Read to examine specific file contents, and Grep/Glob for targeted text searches or file pattern matching\n3. If agentloop-memory tools fail or return no results after 2-3 attempts, fall back to Grep/Glob\n\nIMPORTANT: Always include test files alongside your implementation. Create at least one test file that verifies the core functionality. Use the project's EXISTING test framework and test runner \u2014 check codebase context for what test framework the project uses, what test scripts are available, and how existing test files are structured. Do NOT install or configure a new test framework (no jest.config.js, no vitest.config.ts, etc.). Follow the naming conventions, import patterns, and directory structure of existing test files in the project.\n\n**CRITICAL: Read Before Edit Rule:**\nYou MUST call the `read` tool on any existing file BEFORE calling `edit` on it. The edit tool validates that you've read the file first. If you skip the read, the edit will fail with \"You must read file X before overwriting it.\" For new files, use the `write` tool instead of `edit`.\n\nIMPORTANT: Each change must include the full 'code' field with the complete file content to write. Include both implementation files AND test files in the changes array. You MUST produce at least one file change.\n\n**Test Configuration Rules (CRITICAL):**\n- Tests run in a non-interactive CI-like environment. NEVER configure tests to use watch mode.\n- When creating vitest.config.ts/js, always set `test: { watch: false }` or use `defineConfig({ test: { watch: false } })`.\n- When writing package.json test scripts with vitest, ALWAYS use `\"test\": \"vitest run\"` (NOT `\"test\": \"vitest\"`).\n- For jest, always include `--watchAll=false` in the test script if needed.\n- Never add `--watch` or `--watchAll` flags to test scripts.",
+                                    "prompt": "Execute the implementation plan step by step.\n\n{{#if projectSpecSummary}}\n## Project Specification Summary\n{{projectSpecSummary}}\n\nYour implementation MUST use the specific technologies, file paths, data storage approaches, and constraints described above. These specifications are authoritative — do not substitute alternative libraries, patterns, or approaches unless the specs are technically impossible to implement.\n{{else if projectSpecifications}}\n## Project Specifications (Raw)\n{{projectSpecifications}}\n\nYour implementation MUST use the specific technologies, file paths, and constraints described above. These specifications are authoritative.\n{{/if}}\n\nPlan: {{implementationPlan}}\nTask: {{taskDescription}}\n\n{{taskComments}}\n\nGenerate all the code changes according to the plan. Make sure to address any QA feedback from previous attempts.\n\nYou already have the codebase context, task analysis, and implementation plan in your context. Start implementing immediately \u2014 do NOT return empty changes or claim you need more exploration.\n\n**Codebase Exploration Strategy (FOLLOW THIS ORDER):**\n1. FIRST use agentloop-memory MCP tools for intelligent code discovery (the code graph was already indexed):\n   - `mcp__agentloop-memory__semantic_search` \u2014 find relevant code by natural language description (e.g., search for concepts, function purposes, feature areas)\n   - `mcp__agentloop-memory__query` \u2014 combined semantic + structural search for broader discovery\n   - `mcp__agentloop-memory__find_similar_code` \u2014 find existing patterns similar to what you need to implement\n   - `mcp__agentloop-memory__list_file_entities` \u2014 enumerate functions, classes, and exports in a specific file\n   - `mcp__agentloop-memory__list_entity_relationships` \u2014 trace imports, references, and dependencies between entities\n   - `mcp__agentloop-memory__analyze_code_impact` \u2014 understand what depends on code you plan to change (blast radius)\n2. THEN use Read to examine specific file contents, and Grep/Glob for targeted text searches or file pattern matching\n3. If agentloop-memory tools fail or return no results after 2-3 attempts, fall back to Grep/Glob\n\nIMPORTANT: Always include test files alongside your implementation. Create at least one test file that verifies the core functionality. Use the project's EXISTING test framework and test runner \u2014 check codebase context for what test framework the project uses, what test scripts are available, and how existing test files are structured. Do NOT install or configure a new test framework (no jest.config.js, no vitest.config.ts, etc.). Follow the naming conventions, import patterns, and directory structure of existing test files in the project.\n\n**CRITICAL: Read Before Edit Rule:**\nYou MUST call the `read` tool on any existing file BEFORE calling `edit` on it. The edit tool validates that you've read the file first. If you skip the read, the edit will fail with \"You must read file X before overwriting it.\" For new files, use the `write` tool instead of `edit`.\n\nIMPORTANT: Each change must include the full 'code' field with the complete file content to write. Include both implementation files AND test files in the changes array. You MUST produce at least one file change.\n\n**Test Configuration Rules (CRITICAL):**\n- Tests run in a non-interactive CI-like environment. NEVER configure tests to use watch mode.\n- When creating vitest.config.ts/js, always set `test: { watch: false }` or use `defineConfig({ test: { watch: false } })`.\n- When writing package.json test scripts with vitest, ALWAYS use `\"test\": \"vitest run\"` (NOT `\"test\": \"vitest\"`).\n- For jest, always include `--watchAll=false` in the test script if needed.\n- Never add `--watch` or `--watchAll` flags to test scripts.",
                                     "contextKeys": [
                                       "implementationPlan",
                                       "taskDescription",
                                       "taskAnalysis",
                                       "codebaseContext",
-                                      "taskComments"
+                                      "taskComments",
+                                      "projectSpecifications",
+                                      "projectSpecSummary"
                                     ],
                                     "subagent": "engineer",
                                     "maxTurns": 500,
@@ -1198,6 +1253,8 @@
     "isQARejection": false,
     "hasQAFeedback": false,
     "codebaseContext": null,
+    "projectSpecifications": null,
+    "projectSpecSummary": null,
     "codeGraphIndexed": false,
     "appliedChanges": [],
     "stagedFiles": [],

package/templates/agents/engineer/engineer.md

@@ -12,14 +12,14 @@ mcpServers:
     # Non-critical: if binary not found, server is omitted and BT IndexCodeGraph falls back to NoOp
     command: internal
     env:
-      MCP_EMBEDDING_ENABLED: "false"
+      MCP_EMBEDDING_ENABLED: 'false'
   agentloop:
     # Internal MCP server - handled by the agent worker
     # Command/args not needed as it's started programmatically
     command: internal
   git-worktree-toolbox:
     command: npx
-    args: ["-y", "git-worktree-toolbox@latest"]
+    args: ['-y', 'git-worktree-toolbox@latest']
 tools:
   # Base OpenCode tools
   - read
@@ -218,6 +218,7 @@ You are an implementation agent responsible for analyzing codebases and writing
 Every implementation MUST include tests. This is non-negotiable.
 
 **Requirements:**
+
 - Create at least one test file that verifies core functionality
 - Use the project's EXISTING test framework and test runner. Check the codebase context for the test runner command, test scripts in package.json, and existing test file patterns
 - Do NOT install or configure a new test framework. Never create jest.config.js, vitest.config.ts, or similar test configuration files
@@ -225,11 +226,13 @@ Every implementation MUST include tests. This is non-negotiable.
 - Test files should be included in the same commit as implementation files
 
 **What to test:**
+
 - Happy path: Does the feature work as expected?
 - Edge cases: What happens with empty inputs, large inputs, invalid data?
 - Error handling: Are errors caught and reported appropriately?
 
 **Test organization:**
+
 - Follow the project's existing test conventions — look at existing `__tests__/` directories and test file naming patterns
 - 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
@@ -239,6 +242,7 @@ Every implementation MUST include tests. This is non-negotiable.
 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 } })
@@ -247,10 +251,12 @@ Tests run in non-interactive CI-like environments where there is no terminal for
 - 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)
@@ -260,6 +266,7 @@ Tests run in non-interactive CI-like environments where there is no terminal for
 When working on Expo or React Native projects:
 
 **Testing conventions:**
+
 - Tests typically use `jest-expo` preset with Jest
 - Run tests with `npx jest` from the project directory (NOT `npm test` unless a valid test script exists)
 - Follow the existing test patterns in the project — if tests use `--transform='{}'` for pure logic tests, maintain that pattern
@@ -267,6 +274,7 @@ When working on Expo or React Native projects:
 - Common test file locations: `src/__tests__/`, `__tests__/`, `tests/`
 
 **Monorepo awareness:**
+
 - If the project has subdirectories like `frontend/`, `backend/`, `web/`, ensure you run tests from the correct subdirectory
 - Check the root `package.json` test script — it may delegate to a subdirectory (e.g., `cd frontend && npx jest`)
 - When writing completion comments, always specify the test directory in the [TEST_SETUP] block
@@ -276,10 +284,12 @@ When working on Expo or React Native projects:
 When fixing bugs or addressing QA feedback, understand the ROOT CAUSE before implementing.
 
 **Bad approach** (surface-level):
+
 - QA says "Button doesn't work" → Just add onClick handler
 - Build fails → Comment out failing code
 
 **Good approach**:
+
 1. Analyze the codebase to understand WHY the issue exists
 2. Look for patterns - is this issue repeated elsewhere?
 3. Understand component architecture before changing it
@@ -304,6 +314,43 @@ When fixing bugs or addressing QA feedback, understand the ROOT CAUSE before imp
    - **If column-triggered**: BT uses `report_trigger_result` with "pass" or "fail"
    - **If standalone**: BT uses `report_trigger_result` to move to review
 
+## Runtime QA Edge Cases
+
+Before handing work back to QA, explicitly check for these failure modes when the task touches app startup, runtime boundaries, test detection, or build scripts:
+
+### 1. Build Output Path Mismatch
+
+- Do not assume runtime entrypoints live at `dist/<path>`.
+- Verify the actual emitted files after build, for example whether the project outputs to `dist/src/...` instead of `dist/...`.
+- Make sure `package.json` scripts, runtime entrypoints, and smoke scripts point at the files that are actually emitted.
+- If QA launches the app via a script, run that same script yourself before finishing.
+
+### 2. Task-Based Port Consistency
+
+- If the repo uses task-based ports, make sure the engineer and QA use the same derived port.
+- After starting the app, verify reachability with a real network check such as `curl` against the expected URL.
+- Do not treat a running PID as sufficient evidence that startup succeeded.
+
+### 3. Tool Output Shape Assumptions
+
+- Do not assume tool responses are always plain strings or arrays.
+- When working on agent/runtime logic, account for object-shaped tool payloads such as:
+  - `content`
+  - `stdout`
+  - `output`
+  - `matches`
+  - `files`
+- If detection logic depends on tool output parsing, add regression tests covering both simple and object-shaped responses.
+
+### 4. Review-Facing Verification
+
+- For runtime tasks, run the exact QA-relevant path, not just unit tests:
+  - the real launch script
+  - the real build command
+  - the real smoke path
+- If the task is a scaffold, verify that it still presents visible UI or startup evidence rather than assuming “placeholder” means “not testable yet.”
+- In the task comment, include the concrete launch command, URL/port, and any environment variables QA needs.
+
 ## Code Search (MANDATORY)
 
 **STEP 0: Reindex (MANDATORY FIRST STEP)**
@@ -355,6 +402,7 @@ You are working in an isolated git worktree for this task. The orchestrator crea
 worktree automatically on a dedicated feature branch (e.g., `task/{taskId}-{title}`).
 
 **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
 - YOU are responsible for committing and pushing — do not rely on the behavior tree to do it for you

package/templates/agents/orchestrator/orchestrator.md

@@ -125,8 +125,9 @@ mcp:
           Check existing tasks first to avoid duplicates.
       - name: create_subproject
         instructions: |
-          Create a subproject to group related tasks for a feature or body of work.
-          Provide a descriptive name and summary.
+          ONLY for manually grouping/organizing EXISTING tasks into a named container.
+          Do NOT use this when a user asks you to build, create, or implement something.
+          When the user wants work done, ALWAYS use delegate_work instead.
           Use list_subprojects first to check if a relevant subproject already exists.
       - name: list_subprojects
         instructions: |