chore: revert back to initial instructions for the most part

agents/ollama.ts

@@ -22,8 +22,6 @@ async function buildMcpClient(mcpServerUrl: string): Promise<Client> {
     { capabilities: {} },
   );
   const transport = new StreamableHTTPClientTransport(new URL(mcpServerUrl));
-  // @ts-expect-error — StreamableHTTPClientTransport.sessionId is string|undefined but Transport
-  // expects string; this is an @modelcontextprotocol/sdk internal type mismatch, not our bug.
   await client.connect(transport);
   return client;
 }

package.json

@@ -13,7 +13,7 @@
     "@ark/util": "0.56.0",
     "@clack/prompts": "^1.2.0",
     "@go-gitea/sdk.js": "^0.2.1",
-    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@standard-schema/spec": "1.1.0",
     "@types/node": "^24.7.2",
     "@types/semver": "^7.7.1",

pnpm-lock.yaml

@@ -24,8 +24,8 @@ importers:
         specifier: ^0.2.1
         version: 0.2.1(@octokit/core@7.0.6)
       '@modelcontextprotocol/sdk':
-        specifier: ^1.26.0
+        specifier: ^1.29.0
-        version: 1.26.0(zod@4.3.6)
+        version: 1.29.0(zod@4.3.6)
       '@standard-schema/spec':
         specifier: 1.1.0
         version: 1.1.0
@@ -437,30 +437,14 @@ packages:
     peerDependencies:
       hono: ^4
 
-  '@hono/node-server@1.19.9':
-    resolution: {integrity: sha512-vHL6w3ecZsky+8P5MD+eFfaGTyCeOHUIFYMGpQGbrBTSmNNoxv0if69rEZ5giu36weC5saFuznL411gRX7bJDw==}
-    engines: {node: '>=18.14.1'}
-    peerDependencies:
-      hono: ^4
-
   '@jridgewell/sourcemap-codec@1.5.5':
     resolution: {integrity: sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==}
 
   '@mixmark-io/domino@2.2.0':
     resolution: {integrity: sha512-Y28PR25bHXUg88kCV7nivXrP2Nj2RueZ3/l/jdx6J9f8J4nsEGcgX0Qe6lt7Pa+J79+kPiJU3LguR6O/6zrLOw==}
 
-  '@modelcontextprotocol/sdk@1.26.0':
+  '@modelcontextprotocol/sdk@1.29.0':
-    resolution: {integrity: sha512-Y5RmPncpiDtTXDbLKswIJzTqu2hyBKxTNsgKqKclDbhIgg1wgtf1fRuvxgTnRfcnxtvvgbIEcqUOzZrJ6iSReg==}
+    resolution: {integrity: sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ==}
-    engines: {node: '>=18'}
-    peerDependencies:
-      '@cfworker/json-schema': ^4.1.1
-      zod: ^3.25 || ^4.0
-    peerDependenciesMeta:
-      '@cfworker/json-schema':
-        optional: true
-
-  '@modelcontextprotocol/sdk@1.27.1':
-    resolution: {integrity: sha512-sr6GbP+4edBwFndLbM60gf07z0FQ79gaExpnsjMGePXqFcSSb7t6iscpjk9DhFhwd+mTEQrzNafGP8/iGGFYaA==}
     engines: {node: '>=18'}
     peerDependencies:
       '@cfworker/json-schema': ^4.1.1
@@ -722,9 +706,6 @@ packages:
       ajv:
         optional: true
 
-  ajv@8.17.1:
-    resolution: {integrity: sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==}
-
   ajv@8.18.0:
     resolution: {integrity: sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==}
 
@@ -810,10 +791,6 @@ packages:
     resolution: {integrity: sha512-TG2hpqe4ELx54QER/S3HQ9SRVnQnGBtKUz5bLQWtYAQ+o6GpgMs6sYUvaiJjVxb+UXwhRhAEP3m7LbsIZ77Hmw==}
     engines: {node: '>= 0.8'}
 
-  cors@2.8.5:
-    resolution: {integrity: sha512-KIHbLJqu73RGr/hnbrO9uBeixNGuvSQjul/jdFvS/KFSIH1hWVd1ng7zOHx+YrEfInLG7q4n6GHQ9cDtxv/P6g==}
-    engines: {node: '>= 0.10'}
-
   cors@2.8.6:
     resolution: {integrity: sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw==}
     engines: {node: '>= 0.10'}
@@ -933,12 +910,6 @@ packages:
     resolution: {integrity: sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA==}
     engines: {node: '>=12.0.0'}
 
-  express-rate-limit@8.2.1:
-    resolution: {integrity: sha512-PCZEIEIxqwhzw4KF0n7QF4QqruVTcF73O5kFKUnGOyjbCCgizBBiFaYpd/fnBLUMPw/BWw9OsiN7GgrNYr7j6g==}
-    engines: {node: '>= 16'}
-    peerDependencies:
-      express: '>= 4.11'
-
   express-rate-limit@8.3.0:
     resolution: {integrity: sha512-KJzBawY6fB9FiZGdE/0aftepZ91YlaGIrV8vgblRM3J8X+dHx/aiowJWwkx6LIGyuqGiANsjSwwrbb8mifOJ4Q==}
     engines: {node: '>= 16'}
@@ -1067,10 +1038,6 @@ packages:
     resolution: {integrity: sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ==}
     engines: {node: '>= 0.4'}
 
-  hono@4.12.0:
-    resolution: {integrity: sha512-NekXntS5M94pUfiVZ8oXXK/kkri+5WpX2/Ik+LVsl+uvw+soj4roXIsPqO+XsWrAw20mOzaXOZf3Q7PfB9A/IA==}
-    engines: {node: '>=16.9.0'}
-
   hono@4.12.5:
     resolution: {integrity: sha512-3qq+FUBtlTHhtYxbxheZgY8NIFnkkC/MR8u5TTsr7YZ3wixryQ3cCwn3iZbg8p8B88iDBBAYSfZDS75t8MN7Vg==}
     engines: {node: '>=16.9.0'}
@@ -1083,10 +1050,6 @@ packages:
     resolution: {integrity: sha512-Kpk9Sm7NmI+RHhnj6OIWDI1d6fIoFAtFt9RLaTMRlg/8w49juAStsrBgp0Dp4OdxdVbRIeKhtCUvoi/RuAhO4g==}
     engines: {node: '>= 0.6'}
 
-  http-errors@2.0.0:
-    resolution: {integrity: sha512-FtwrG/euBzaEjYeRqOgly7G0qviiXoJWnvEH2Z1plBdXgbyjv34pHTSb9zoeHMyDy33+DWy5Wt9Wo+TURtOYSQ==}
-    engines: {node: '>= 0.8'}
-
   http-errors@2.0.1:
     resolution: {integrity: sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==}
     engines: {node: '>= 0.8'}
@@ -1098,10 +1061,6 @@ packages:
     resolution: {integrity: sha512-eKCa6bwnJhvxj14kZk5NCPc6Hb6BdsU9DZcOnmQKSnO1VKrfV0zCvtttPZUsBvjmNDn8rpcJfpwSYnHBjc95MQ==}
     engines: {node: '>=18.18.0'}
 
-  iconv-lite@0.7.0:
-    resolution: {integrity: sha512-cf6L2Ds3h57VVmkZe+Pn+5APsT7FpqJtEhhieDCvrE2MK5Qk9MyffgQyuxQTm6BChfeZNtcOLHp9IcWRVcIcBQ==}
-    engines: {node: '>=0.10.0'}
-
   iconv-lite@0.7.2:
     resolution: {integrity: sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw==}
     engines: {node: '>=0.10.0'}
@@ -1112,10 +1071,6 @@ packages:
   inherits@2.0.4:
     resolution: {integrity: sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==}
 
-  ip-address@10.0.1:
-    resolution: {integrity: sha512-NWv9YLW4PoW2B7xtzaS3NCot75m6nK7Icdv0o3lfMceJVRfSoQwqD4wEH5rLwoKJwUiZ/rfpiVBhnaF0FK4HoA==}
-    engines: {node: '>= 12'}
-
   ip-address@10.1.0:
     resolution: {integrity: sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q==}
     engines: {node: '>= 12'}
@@ -1146,9 +1101,6 @@ packages:
     resolution: {integrity: sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ==}
     hasBin: true
 
-  jose@6.1.3:
-    resolution: {integrity: sha512-0TpaTfihd4QMNwrz/ob2Bp7X04yuxJkjRGi4aKmOqwhov54i6u79oCv7T+C7lo70MKH6BesI3vscD1yb/yzKXQ==}
-
   jose@6.2.0:
     resolution: {integrity: sha512-xsfE1TcSCbUdo6U07tR0mvhg0flGxU8tPLbF03mirl2ukGQENhUg4ubGYQnhVH0b5stLlPM+WOqDkEl1R1y5sQ==}
 
@@ -1293,10 +1245,6 @@ packages:
     engines: {node: '>=22.0.0'}
     hasBin: true
 
-  pkce-challenge@5.0.0:
-    resolution: {integrity: sha512-ueGLflrrnvwB3xuo/uGob5pd5FN7l0MsLf0Z87o/UQmRtwjvfylfc9MurIxRAWywCYTgrvpXBcqjV4OfCYGCIQ==}
-    engines: {node: '>=16.20.0'}
-
   pkce-challenge@5.0.1:
     resolution: {integrity: sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ==}
     engines: {node: '>=16.20.0'}
@@ -1331,10 +1279,6 @@ packages:
     resolution: {integrity: sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg==}
     engines: {node: '>= 0.6'}
 
-  raw-body@3.0.1:
-    resolution: {integrity: sha512-9G8cA+tuMS75+6G/TzW8OtLzmBDMo8p1JRxN5AZ+LAp8uxGA8V8GZm4GQ4/N5QNQEnLmg6SS7wyuSmbKepiKqA==}
-    engines: {node: '>= 0.10'}
-
   raw-body@3.0.2:
     resolution: {integrity: sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA==}
     engines: {node: '>= 0.10'}
@@ -1416,10 +1360,6 @@ packages:
     resolution: {integrity: sha512-OpZ3zP+jT1PI7I8nemJX4AKmAX070ZkYPVWV/AaKTJl+tXCTGyVdC1a4SL8RUQYEwk/f34ZX8UTykN68FwrqAA==}
     engines: {node: '>= 0.6'}
 
-  statuses@2.0.1:
-    resolution: {integrity: sha512-RwNA9Z/7PrK06rYLIzFMlaF+l73iwpzsqRIFgbMLbTcLD6cOao82TaWefPXQvB2fOC4AjuYSEndS7N/mTCbkdQ==}
-    engines: {node: '>= 0.8'}
-
   statuses@2.0.2:
     resolution: {integrity: sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==}
     engines: {node: '>= 0.8'}
@@ -1880,37 +1820,11 @@ snapshots:
     dependencies:
       hono: 4.12.5
 
-  '@hono/node-server@1.19.9(hono@4.12.0)':
-    dependencies:
-      hono: 4.12.0
-
   '@jridgewell/sourcemap-codec@1.5.5': {}
 
   '@mixmark-io/domino@2.2.0': {}
 
-  '@modelcontextprotocol/sdk@1.26.0(zod@4.3.6)':
+  '@modelcontextprotocol/sdk@1.29.0(zod@4.3.6)':
-    dependencies:
-      '@hono/node-server': 1.19.9(hono@4.12.0)
-      ajv: 8.17.1
-      ajv-formats: 3.0.1(ajv@8.17.1)
-      content-type: 1.0.5
-      cors: 2.8.5
-      cross-spawn: 7.0.6
-      eventsource: 3.0.7
-      eventsource-parser: 3.0.6
-      express: 5.2.1
-      express-rate-limit: 8.2.1(express@5.2.1)
-      hono: 4.12.0
-      jose: 6.1.3
-      json-schema-typed: 8.0.2
-      pkce-challenge: 5.0.0
-      raw-body: 3.0.1
-      zod: 4.3.6
-      zod-to-json-schema: 3.25.1(zod@4.3.6)
-    transitivePeerDependencies:
-      - supports-color
-
-  '@modelcontextprotocol/sdk@1.27.1(zod@4.3.6)':
     dependencies:
       '@hono/node-server': 1.19.11(hono@4.12.5)
       ajv: 8.18.0
@@ -2148,21 +2062,10 @@ snapshots:
       mime-types: 3.0.2
       negotiator: 1.0.0
 
-  ajv-formats@3.0.1(ajv@8.17.1):
-    optionalDependencies:
-      ajv: 8.17.1
-
   ajv-formats@3.0.1(ajv@8.18.0):
     optionalDependencies:
       ajv: 8.18.0
 
-  ajv@8.17.1:
-    dependencies:
-      fast-deep-equal: 3.1.3
-      fast-uri: 3.1.0
-      json-schema-traverse: 1.0.0
-      require-from-string: 2.0.2
-
   ajv@8.18.0:
     dependencies:
       fast-deep-equal: 3.1.3
@@ -2253,11 +2156,6 @@ snapshots:
       depd: 2.0.0
       keygrip: 1.1.0
 
-  cors@2.8.5:
-    dependencies:
-      object-assign: 4.1.1
-      vary: 1.1.2
-
   cors@2.8.6:
     dependencies:
       object-assign: 4.1.1
@@ -2424,11 +2322,6 @@ snapshots:
 
   expect-type@1.3.0: {}
 
-  express-rate-limit@8.2.1(express@5.2.1):
-    dependencies:
-      express: 5.2.1
-      ip-address: 10.0.1
-
   express-rate-limit@8.3.0(express@5.2.1):
     dependencies:
       express: 5.2.1
@@ -2483,7 +2376,7 @@ snapshots:
 
   fastmcp@3.34.0(arktype@2.2.0):
     dependencies:
-      '@modelcontextprotocol/sdk': 1.27.1(zod@4.3.6)
+      '@modelcontextprotocol/sdk': 1.29.0(zod@4.3.6)
       '@standard-schema/spec': 1.1.0
       execa: 9.6.1
       file-type: 21.3.0
@@ -2597,8 +2490,6 @@ snapshots:
     dependencies:
       function-bind: 1.1.2
 
-  hono@4.12.0: {}
-
   hono@4.12.5: {}
 
   http-assert@1.5.0:
@@ -2614,14 +2505,6 @@ snapshots:
       statuses: 1.5.0
       toidentifier: 1.0.1
 
-  http-errors@2.0.0:
-    dependencies:
-      depd: 2.0.0
-      inherits: 2.0.4
-      setprototypeof: 1.2.0
-      statuses: 2.0.1
-      toidentifier: 1.0.1
-
   http-errors@2.0.1:
     dependencies:
       depd: 2.0.0
@@ -2636,10 +2519,6 @@ snapshots:
 
   human-signals@8.0.1: {}
 
-  iconv-lite@0.7.0:
-    dependencies:
-      safer-buffer: 2.1.2
-
   iconv-lite@0.7.2:
     dependencies:
       safer-buffer: 2.1.2
@@ -2648,8 +2527,6 @@ snapshots:
 
   inherits@2.0.4: {}
 
-  ip-address@10.0.1: {}
-
   ip-address@10.1.0: {}
 
   ipaddr.js@1.9.1: {}
@@ -2667,8 +2544,6 @@ snapshots:
   jiti@2.6.1:
     optional: true
 
-  jose@6.1.3: {}
-
   jose@6.2.0: {}
 
   json-schema-traverse@1.0.0: {}
@@ -2805,8 +2680,6 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  pkce-challenge@5.0.0: {}
-
   pkce-challenge@5.0.1: {}
 
   postcss@8.5.6:
@@ -2839,13 +2712,6 @@ snapshots:
 
   range-parser@1.2.1: {}
 
-  raw-body@3.0.1:
-    dependencies:
-      bytes: 3.1.2
-      http-errors: 2.0.0
-      iconv-lite: 0.7.0
-      unpipe: 1.0.0
-
   raw-body@3.0.2:
     dependencies:
       bytes: 3.1.2
@@ -2973,8 +2839,6 @@ snapshots:
 
   statuses@1.5.0: {}
 
-  statuses@2.0.1: {}
-
   statuses@2.0.2: {}
 
   std-env@3.10.0: {}

tsconfig.json

@@ -15,12 +15,12 @@
     "verbatimModuleSyntax": true,
     "esModuleInterop": true,
     "resolveJsonModule": true,
-    "exactOptionalPropertyTypes": true,
+    "exactOptionalPropertyTypes": false,
     "forceConsistentCasingInFileNames": true,
     "stripInternal": true,
     "moduleDetection": "force",
     "useUnknownInCatchVariables": true,
-    "noEmit": true
+    "noEmit": true,
   },
-  "exclude": ["dist"]
+  "exclude": ["dist"],
 }

utils/instructions.ts

@@ -1,6 +1,11 @@
 // changes to prompt assembly should be reflected in documentation
 import { execSync } from "node:child_process";
-import { type AgentId, formatMcpToolRef, shockbotMcpName, type PayloadEvent } from "../external.ts";
+import {
+  type AgentId,
+  formatMcpToolRef,
+  shockbotMcpName,
+  type PayloadEvent,
+} from "../external.ts";
 import type { Mode } from "../modes.ts";
 import type { ResolvedPayload } from "./payload.ts";
 
@@ -37,7 +42,10 @@ function buildRuntimeContext(ctx: InstructionsContext): string {
   let gitStatus: string | undefined;
   try {
     gitStatus =
-      execSync("git status --short", { encoding: "utf-8", stdio: "pipe" }).trim() || "(clean)";
+      execSync("git status --short", {
+        encoding: "utf-8",
+        stdio: "pipe",
+      }).trim() || "(clean)";
   } catch {
     // git not available
   }
@@ -57,27 +65,33 @@ function buildRuntimeContext(ctx: InstructionsContext): string {
     gitea_actor: process.env.GITHUB_ACTOR,
   };
 
-  const filtered = Object.fromEntries(Object.entries(data).filter(([_, v]) => v !== undefined));
+  const filtered = Object.fromEntries(
+    Object.entries(data).filter(([_, v]) => v !== undefined),
+  );
   return encodePlain(filtered);
 }
 
 function buildEventTitle(event: PayloadEvent): string {
-  const trimmedTitle = typeof event.title === "string" ? event.title.trim() : "";
+  const trimmedTitle =
+    typeof event.title === "string" ? event.title.trim() : "";
   if (!trimmedTitle) return "";
-  const prefix = event.issue_number ? `${event.is_pr ? "PR" : "Issue"} #${event.issue_number}` : "";
+  const prefix = event.issue_number
+    ? `${event.is_pr ? "PR" : "Issue"} #${event.issue_number}`
+    : "";
   return prefix ? `${prefix} ("${trimmedTitle}")` : `("${trimmedTitle}")`;
 }
 
 function buildEventMetadata(event: PayloadEvent): string {
   const { title: _t, body: _b, trigger, ...rest } = event;
-  const restWithTrigger = trigger === "workflow_dispatch" ? rest : { trigger, ...rest };
+  const restWithTrigger =
+    trigger === "workflow_dispatch" ? rest : { trigger, ...rest };
   if (Object.keys(restWithTrigger).length === 0) return "";
   return encodePlain(restWithTrigger as Record<string, unknown>);
 }
 
 function getShellInstructions(
   shell: ResolvedPayload["shell"],
-  t: (name: string) => string
+  t: (name: string) => string,
 ): string {
   switch (shell) {
     case "disabled":
@@ -100,7 +114,7 @@ function getFileInstructions(): string {
 function getStandaloneModeInstructions(
   trigger: string,
   t: (name: string) => string,
-  outputSchema?: Record<string, unknown> | undefined
+  outputSchema?: Record<string, unknown> | undefined,
 ): string {
   if (trigger !== "unknown") return "";
 
@@ -159,8 +173,12 @@ Eagerly inspect the MCP tools available to you via the \`${shockbotMcpName}\` MC
 function buildEventContext(ctx: PromptContext): string {
   const isPr = ctx.payload.event.is_pr === true;
   const relatedLabel = isPr ? "--- related PR ---" : "--- related issue ---";
-  const titlePart = ctx.eventTitle ? `${relatedLabel}\n\n${ctx.eventTitle}` : "";
+  const titlePart = ctx.eventTitle
-  const metadataPart = ctx.eventMetadata ? `--- event context ---\n\n${ctx.eventMetadata}` : "";
+    ? `${relatedLabel}\n\n${ctx.eventTitle}`
+    : "";
+  const metadataPart = ctx.eventMetadata
+    ? `--- event context ---\n\n${ctx.eventMetadata}`
+    : "";
   const content = [titlePart, metadataPart].filter(Boolean).join("\n\n");
   if (!content) return "";
   return `************* EVENT CONTEXT *************\n\n${content}`;
@@ -175,14 +193,18 @@ You are a diligent, detail-oriented, no-nonsense software engineering agent. You
 ## Persona
 
 - Careful, to-the-point, and kind. You only say things you know to be true.
-- Strong bias toward minimalism: no dead code, no premature abstractions, no speculative features.
+- Do not break up sentences with hyphens. Use emdashes.
+- Strong bias toward minimalism: no dead code, no premature abstractions, no speculative features, and no comments that merely restate what the code does.
 - Code is focused, elegant, and production-ready.
+- Do not add unnecessary comments, tests, or documentation unless explicitly prompted to do so.
+- Adapt your writing style to match existing patterns in the codebase (commit messages, PR descriptions, code comments) while never being unprofessional.
+- Use backticks liberally for inline code (e.g. \`z.string()\`) even in headers.
 
 ## Environment
 
 - Non-interactive: complete tasks autonomously without asking follow-up questions.
 - Running inside a Gitea Actions ephemeral environment. All processes and resources will be cleaned up at the end of the run.
-- When details are missing, prefer the most common convention unless repo-specific patterns exist.
+- When details are missing, prefer the most common convention unless repo-specific patterns exist. Fail with an explicit error only if critical information is missing (e.g. user asks to review a PR but does not provide a link or ID).
 
 ${priorityOrder}
 
@@ -196,21 +218,26 @@ MCP servers provide tools you can call. Inspect your available MCP servers at st
 
 ### Git
 
-Use \`${t("git")}\` for local git commands (status, log, add, commit, checkout, branch, merge, etc.). When reviewing a PR, do NOT re-derive the PR diff via \`git diff <base>..<head>\` — the diffPath returned by \`${t("checkout_pr")}\` is authoritative. For operations requiring remote authentication, use the dedicated MCP tools:
+Use \`${t("git")}\` for local git commands (status, log, add, commit, checkout, branch, merge, etc.). When reviewing a PR, do NOT re-derive the PR diff via \`git diff <base>..<head>\` — the diffPath returned by \`${t("checkout_pr")}\` is authoritative. \`git log\` and \`git diff --stat\` are fine for commit-range overview; \`git diff\` / \`git diff --cached\` are fine for inspecting your *own* uncommitted changes. For operations requiring remote authentication, use the dedicated MCP tools:
 - \`${t("push_branch")}\` - push current or specified branch
 - \`${t("git_fetch")}\` - fetch refs from remote
 - \`${t("checkout_pr")}\` - checkout a PR branch (fetches and configures push for forks)
-- \`${t("delete_branch")}\` - delete a remote branch
+- \`${t("delete_branch")}\` - delete a remote branch (requires push: enabled)
+- \`${t("push_tags")}\` - push tags (requires push: enabled)
 
 Rules:
-- All code changes must be pushed to a pull request (new or existing) before the run ends. This environment is ephemeral — unpushed work is lost permanently.
+- All code changes must be pushed to a pull request (new or existing) before the run ends. This environment is ephemeral — unpushed work is lost permanently. \`git status\` must be clean when you finish.
-- Protected branches (default branch) are blocked from direct pushes in restricted mode.
+- Protected branches (default branch) are blocked from direct pushes in restricted mode. Do not use \`git push\` directly — it will fail without credentials.
-- Never push commits directly to the default branch. Always create a feature branch following the pattern: \`shockbot/<issue-number>-<kebab-case-description>\`.
+- Do not attempt to configure git credentials manually — the ${shockbotMcpName} server handles all authentication internally.
-- Never add co-author trailers to commit messages.
+- Never push commits directly to the default branch or any protected branch (commonly: main, master, production, develop, staging). Always create a feature branch following the pattern: \`pullfrog/<issue-number>-<kebab-case-description>\` (e.g., \`pullfrog/123-fix-login-bug\`).
+- Never add co-author trailers (e.g., "Co-authored-by" or "Co-Authored-By") to commit messages.
+- Untracked files from tests or tooling (e.g. \`coverage/\`) often remain *after* your last commit and still block \`${t("push_branch")}\` — delete them, extend \`.gitignore\`, or only add files that truly belong in the repo.
+- \`${t("push_branch")}\` runs the repository's optional **prepush** hook (commonly tests or lint) — best-effort. On failure the output is returned, the hook is latched off, and every subsequent \`${t("push_branch")}\` call this run skips it. If the failure is unrelated to your changes (pre-existing breakage, env-dependent test, flaky check), just call \`${t("push_branch")}\` again. If it could be a real bug in your code, ${ctx.payload.shell === "disabled" ? `fix it from the failure output (shell is disabled, so you can't re-run the hook)` : `re-run the hook via the shell tool to iterate — \`${t("push_branch")}\` itself won't re-run it`}. Don't describe the failure as an infrastructure "timeout" unless the tool output clearly shows one.
+- If push or PR creation fails, \`${t("report_progress")}\` must summarize using the **actual** error from the tool. Do not substitute vague causes unless they match what failed.
 
 ### Gitea
 
-Use MCP tools from ${shockbotMcpName} for all Gitea operations. Never use the \`gh\` CLI — it is not authenticated. The MCP tools handle authentication and enforce permissions.
+Use MCP tools from ${shockbotMcpName} for all Gitea operations. Never use the \`gh\` CLI — it is not authenticated and will fail. The MCP tools handle authentication and enforce permissions.
 
 ${getShellInstructions(ctx.payload.shell, t)}
 
@@ -222,27 +249,50 @@ ${getStandaloneModeInstructions(ctx.payload.event.trigger, t, ctx.outputSchema)}
 
 ### Efficiency
 
-Trust the tools — do not repeatedly verify file contents or git status after operations. Only verify if you encounter an actual error.
+Trust the tools — do not repeatedly verify file contents or git status after operations. If a tool reports success, proceed to the next step. Only verify if you encounter an actual error. Exception: right before \`${t("push_branch")}\`, ensure the working tree is clean — that tool rejects dirty trees, and tests you ran earlier often leave untracked output.
 
 ### Parallel tool execution
 
-For maximum efficiency, invoke all relevant independent tools simultaneously in a single turn rather than sequentially. Emit multiple tool calls in the same assistant message for independent calls.
+For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously in a single assistant turn rather than sequentially. The dominant failure mode is grep → read → read → read → read across separate turns when one round trip would do. Always parallelize when calls are independent:
+- reading multiple files (especially after a grep returns candidates)
+- multiple greps with different patterns
+- glob + grep + read combos
+- listing multiple directories
+- inspecting multiple MCP tools or resources
+
+Do NOT parallelize operations that depend on prior output (e.g. create a file then read it), or ordered stateful mutations. Edits are not parallelizable — sequence those normally.
+
+Emit multiple \`tool_use\` blocks in the same assistant message for independent calls — the runtime executes them concurrently. Do not wait for one tool result before issuing the next independent call.
+
+### Command execution
+
+Never use \`sleep\` to wait for commands to complete. Commands run synchronously — when the shell tool returns, the command has finished.
 
 ### Commenting style
 
-When posting comments via ${shockbotMcpName}, write as a professional team member would. Your final comments should be polished and actionable.
+When posting comments via ${shockbotMcpName}, write as a professional team member would. Your final comments should be polished and actionable — do not include intermediate reasoning like "I'll now look at the code" or "Let me respond to the question."
+
+When embedding images (e.g. uploaded screenshots) in comments or PR bodies, always use markdown image syntax: \`![description](url)\`. Never paste a naked URL — it will not render as an image.
 
 ### Progress reporting
 
-Call \`report_progress\` exactly once at the end of every run with a brief final summary (1-3 sentences) unless the mode guidance instructs otherwise. Never call it for intermediate status updates.
+**Task list**: at the start of every run, create an internal task list based on the steps in your current mode. Update it as you complete each step. The system automatically renders this list to the progress comment — you do not need to call \`report_progress\` for this.
+
+**\`report_progress\`**: call this exactly once at the end of every run with a brief final summary (1-3 sentences) unless the mode guidance instructs otherwise. Never call it for intermediate status updates (e.g., "Checking for changes...", "Starting review...") — the task list handles live progress automatically. Calling \`report_progress\` replaces the task list with your summary and preserves the current task list in a collapsible section. Keep the summary concise — do not repeat what the task list already shows. Focus on the outcome (what was accomplished, links to artifacts) rather than listing individual steps. If something failed, include the tool's error text even when that makes the summary longer.
+
+Never use \`create_issue_comment\` for task progress — that creates duplicate comments and leaves the progress comment stuck in its initial state. \`create_issue_comment\` is only for standalone comments unrelated to your current task. Plan output (initial post AND revisions) goes through \`report_progress\` — see the Plan mode guidance for details.
 
 ### If you get stuck
 
-If you cannot complete a task due to missing information or an unrecoverable error, post a comment via ${shockbotMcpName} explaining what blocked you and what would unblock you.
+If you cannot complete a task due to missing information, ambiguity, or an unrecoverable error:
+1. Do not silently fail or produce incomplete work
+2. Post a comment via ${shockbotMcpName} explaining what blocked you and what information or action would unblock you
+3. Make your blocker comment specific and actionable (e.g., "I need the database schema to proceed" not "I'm stuck")
+4. If you've attempted the same fix or approach 3 or more times without progress, step back and reconsider. Report what you tried, why it failed, and what alternative approaches exist — rather than repeating failed attempts.
 
 ### Agent context files
 
-Check for an AGENTS.md file. If it exists, read it and follow the instructions unless they conflict with the Security, System or Mode instructions above.`;
+Check for an AGENTS.md file or an agent-specific equivalent that applies to you. If it exists, read it and follow the instructions unless they conflict with the Security, System or Mode instructions above.`;
 }
 
 interface TocEntry {
@@ -304,7 +354,9 @@ function assembleFullPrompt(ctx: {
   return rawFull.trim().replace(/\n{3,}/g, "\n\n");
 }
 
-export function resolveInstructions(ctx: InstructionsContext): ResolvedInstructions {
+export function resolveInstructions(
+  ctx: InstructionsContext,
+): ResolvedInstructions {
   const pctx = buildPromptContext(ctx);
 
   const task = buildTaskSection(pctx);
@@ -313,11 +365,21 @@ export function resolveInstructions(ctx: InstructionsContext): ResolvedInstructi
   const system = buildSystemBody(pctx);
 
   const tocEntries: TocEntry[] = [];
-  if (task) tocEntries.push({ label: "YOUR TASK", description: "what to accomplish" });
+  if (task)
-  tocEntries.push({ label: "PROCEDURE", description: "mode selection and execution steps" });
+    tocEntries.push({ label: "YOUR TASK", description: "what to accomplish" });
+  tocEntries.push({
+    label: "PROCEDURE",
+    description: "mode selection and execution steps",
+  });
   if (eventContext)
-    tocEntries.push({ label: "EVENT CONTEXT", description: "related PR/issue data" });
+    tocEntries.push({
-  tocEntries.push({ label: "SYSTEM", description: "persona, security, tools, workflow rules" });
+      label: "EVENT CONTEXT",
+      description: "related PR/issue data",
+    });
+  tocEntries.push({
+    label: "SYSTEM",
+    description: "persona, security, tools, workflow rules",
+  });
   tocEntries.push({ label: "RUNTIME", description: "environment metadata" });
 
   const toc = buildToc(tocEntries);
@@ -331,7 +393,9 @@ export function resolveInstructions(ctx: InstructionsContext): ResolvedInstructi
     runtime: pctx.runtime,
   });
 
-  const event = [pctx.eventTitle, pctx.eventMetadata].filter(Boolean).join("\n\n---\n\n");
+  const event = [pctx.eventTitle, pctx.eventMetadata]
+    .filter(Boolean)
+    .join("\n\n---\n\n");
 
   return {
     full,