@desplega.ai/agent-swarm 1.20.0 → 1.49.0

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.20.0",
-  "description": "Agent orchestration layer MCP for Claude Code, Codex, Gemini CLI, and more!",
+  "version": "1.49.0",
+  "description": "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants",
   "license": "MIT",
-  "author": "desplega.ai <contact@desplega.ai>",
+  "author": "desplega.sh <contact@desplega.sh>",
   "maintainers": [
     {
       "name": "Taras",
-      "email": "t@desplega.ai"
+      "email": "t@desplega.sh"
     }
   ],
   "repository": {
@@ -31,7 +31,9 @@
     "name": "agent-swarm"
   },
   "scripts": {
+    "build:pi-skills": "bun run plugin/build-pi-skills.ts",
     "tsc:check": "bun tsc --noEmit",
+    "check:db-boundary": "bash scripts/check-db-boundary.sh",
     "cli": "bun src/cli.tsx",
     "hook": "bun src/hooks/hook.ts",
     "claude": "bun src/cli.tsx claude",
@@ -41,11 +43,12 @@
     "lead": "bun src/cli.tsx lead",
     "lead:yolo": "bun src/cli.tsx lead --yolo",
     "dev": "bun --hot src/stdio.ts",
-    "dev:http": "bun --hot src/http.ts",
+    "dev:http": "portless api.swarm bun --hot src/http.ts",
     "start": "bun src/stdio.ts",
     "start:http": "bun src/http.ts",
+    "start:portless": "portless api.swarm bun src/http.ts",
     "inspector": "bunx @modelcontextprotocol/inspector --transport stdio bun src/stdio.ts",
-    "inspector:http": "bunx @modelcontextprotocol/inspector --transport http http://localhost:3013/mcp",
+    "inspector:http": "bunx @modelcontextprotocol/inspector --transport http https://api.swarm.localhost:1355/mcp",
     "lint": "biome check src",
     "lint:fix": "biome check --write src",
     "format": "biome format --write src",
@@ -58,7 +61,10 @@
     "deploy:update": "bun deploy/update.ts",
     "deploy:uninstall": "bun deploy/uninstall.ts",
     "deploy:docker": "bun deploy/docker-push.ts",
+    "e2e:workflows": "bun scripts/e2e-workflow-test.ts",
+    "e2e:workflows:docker": "bun scripts/e2e-workflow-test.ts --with-docker",
     "docs:mcp": "bun scripts/generate-mcp-docs.ts",
+    "docs:openapi": "bun scripts/generate-openapi.ts",
     "pm2-start": "pm2 start ecosystem.config.cjs",
     "pm2-stop": "pm2 stop ecosystem.config.cjs",
     "pm2-restart": "pm2 restart ecosystem.config.cjs",
@@ -76,15 +82,33 @@
     "bun": ">=1.0.26"
   },
   "dependencies": {
+    "@ai-sdk/openai": "^3.0.41",
+    "@asteasolutions/zod-to-openapi": "^8.0.0",
+    "@desplega.ai/localtunnel": "^2.2.0",
     "@inkjs/ui": "^2.0.0",
+    "@linear/sdk": "^77.0.0",
+    "@mariozechner/pi-agent-core": "^0.57.1",
+    "@mariozechner/pi-ai": "^0.57.1",
+    "@mariozechner/pi-coding-agent": "^0.57.1",
     "@modelcontextprotocol/sdk": "^1.25.1",
+    "@openfort/openfort-node": "^0.9.1",
     "@slack/bolt": "^4.6.0",
     "@types/react": "^19.2.7",
+    "@x402/core": "^2.5.0",
+    "@x402/evm": "^2.5.0",
+    "@x402/fetch": "^2.5.0",
+    "ai": "^6.0.116",
     "cron-parser": "^5.4.0",
     "date-fns": "^4.1.0",
+    "hono": "^4.12.3",
     "ink": "^6.5.1",
+    "oauth4webapi": "^3.8.5",
+    "openai": "^6.22.0",
     "react": "^19.2.3",
     "react-devtools-core": "^7.0.1",
-    "zod": "^4.2.1"
+    "svix": "^1.62.0",
+    "viem": "^2.46.3",
+    "zod": "^4.2.1",
+    "zod-to-json-schema": "^3.25.1"
   }
 }

package/plugin/build-pi-skills.ts

@@ -0,0 +1,233 @@
+/**
+ * Build pi-mono SKILL.md files from claude command sources.
+ *
+ * Source of truth: plugin/commands/*.md
+ * Output: plugin/pi-skills/<name>/SKILL.md
+ *
+ * Only commands listed in SKILLS_TO_CONVERT are converted.
+ * Provider-specific sections use markers:
+ *   <!-- claude-only -->...<!-- /claude-only -->  → stripped for pi-mono
+ *   <!-- pi-only -->...<!-- /pi-only -->          → stripped for claude (kept for pi-mono)
+ *
+ * Usage: bun run plugin/build-pi-skills.ts
+ */
+
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const COMMANDS_DIR = join(import.meta.dir, "commands");
+const PI_SKILLS_DIR = join(import.meta.dir, "pi-skills");
+
+/** All commands to convert to pi-mono skills */
+const SKILLS_TO_CONVERT = [
+  "work-on-task",
+  "start-worker",
+  "start-leader",
+  "swarm-chat",
+  "close-issue",
+  "create-pr",
+  "implement-issue",
+  "investigate-sentry-issue",
+  "respond-github",
+  "review-offered-task",
+  "review-pr",
+  "todos",
+];
+
+function convertToPiSkill(name: string, content: string): string {
+  let result = content;
+
+  // 1. Strip <!-- claude-only --> sections
+  result = result.replace(/<!-- claude-only -->\n?[\s\S]*?<!-- \/claude-only -->\n?/g, "");
+
+  // 2. Reveal <!-- pi-only --> sections (remove markers, keep content)
+  result = result.replace(/<!-- pi-only -->\n?/g, "");
+  result = result.replace(/<!-- \/pi-only -->\n?/g, "");
+
+  // 3. Convert frontmatter: extract description, drop argument-hint, add name
+  result = result.replace(
+    /^---\n([\s\S]*?)---\n/,
+    (_match, frontmatter: string) => {
+      const descMatch = frontmatter.match(/description:\s*(.+)/);
+      const description = descMatch ? descMatch[1].trim() : name;
+      return `---\nname: ${name}\ndescription: ${description}\n---\n`;
+    },
+  );
+
+  // 4. Slash command syntax: /command-name → /skill:command-name
+  //    Match ` /name` or `/name` at word boundary, but not /desplega: or /workspace
+  for (const skillName of SKILLS_TO_CONVERT) {
+    // In backticks or after whitespace/start-of-line
+    result = result.replace(
+      new RegExp(`(\`|\\s|^)\\/${skillName}(?=\\s|\`|$)`, "gm"),
+      `$1/skill:${skillName}`,
+    );
+  }
+
+  // 5. /desplega:* commands → generic descriptions
+  //    Replace the "Available commands" section pattern
+  result = result.replace(
+    /### Available commands[\s\S]*?(?=\n### [^#]|\n## |$)/,
+    `### Research and Planning
+
+As you start working on a task, consider whether you need to:
+
+- **Research**: For research tasks, gather information from the web, codebase, or documentation before starting implementation.
+- **Create a plan**: For development tasks, create a detailed plan before implementing. Write it to \`/workspace/personal/plans/\`.
+- **Implement a plan**: If you already have a plan, follow it step by step.
+
+### Communication
+
+- Use \`/skill:swarm-chat\` to communicate with other agents in the swarm if you need help or want to provide updates.
+
+#### Decision guidelines
+
+When the task is a research task, you should ALWAYS perform thorough research before proceeding.
+
+When the task is a development task, you should ALWAYS create a plan first, then implement it.
+
+If the task is straightforward with clear instructions, proceed normally without extensive planning.
+
+`,
+  );
+
+  // Remove the old "Decision to use commands" subsection if it survived
+  result = result.replace(/#### Decision to use commands[\s\S]*?(?=### |## |$)/, "");
+
+  // Clean up any remaining /desplega: references that weren't in a block
+  result = result.replace(
+    /- `\/desplega:research`[^\n]*\n/g,
+    "- Research - Workers can perform research on the web to gather information needed for the task\n",
+  );
+  result = result.replace(
+    /- `\/desplega:create-plan`[^\n]*\n/g,
+    "- Planning - Workers can create a detailed plan for how they will approach and complete the task\n",
+  );
+  result = result.replace(
+    /- `\/desplega:implement-plan`[^\n]*\n/g,
+    "- Implementation - Workers can implement a plan step by step\n",
+  );
+
+  // 6. Replace /desplega:* inline references
+  result = result.replace(/`\/desplega:research`/g, "research");
+  result = result.replace(/`\/desplega:create-plan`/g, "plan creation");
+  result = result.replace(/`\/desplega:implement-plan`/g, "plan implementation");
+  result = result.replace(/\/desplega:research/g, "research");
+  result = result.replace(/\/desplega:create-plan/g, "plan creation");
+  result = result.replace(/\/desplega:implement-plan/g, "plan implementation");
+
+  // 7. /todos references — now converted to /skill:todos by step 4
+  //    Just clean up backtick formatting around the converted refs
+  result = result.replace(/`\/todos`/g, "`/skill:todos`");
+
+  // 8. Clean up "the `/skill:swarm-chat` command" → "`/skill:swarm-chat`"
+  //    At this point step 4 already converted /swarm-chat → /skill:swarm-chat
+  result = result.replace(
+    /Use the (`\/skill:swarm-chat`)/g,
+    "Use $1",
+  );
+  result = result.replace(
+    /the (`\/skill:swarm-chat`) command/g,
+    "$1",
+  );
+  result = result.replace(
+    /the (`\/skill:swarm-chat`) channel/g,
+    "$1 channel",
+  );
+  result = result.replace(
+    /(`\/skill:swarm-chat`) command/g,
+    "$1",
+  );
+
+  // 9. Setup message simplification
+  result = result.replace(
+    / Please run `bunx @desplega\.ai\/agent-swarm setup` to configure it\./g,
+    "",
+  );
+
+  // 10. "the command `/skill:..." → "`/skill:..." and "this command" → "this skill"
+  result = result.replace(/the command (`\/skill:[^`]+`)/g, "$1");
+  result = result.replace(/call the (`\/skill:[^`]+`)/g, "call $1");
+  result = result.replace(/this command is used/gi, "this skill is used");
+  result = result.replace(/If this command/gi, "If this skill");
+
+  // 11. Wording: "command" → "skill" for worker sections and general references
+  result = result.replace(
+    /#### Worker available commands/g,
+    "#### Worker available skills",
+  );
+  result = result.replace(
+    /the following commands to help/g,
+    "the following skills to help",
+  );
+  // "use `/skill:swarm-chat` command" → "use `/skill:swarm-chat`"
+  result = result.replace(/(`\/skill:[^`]+`) command/g, "$1");
+  // "without using any commands" → "without extensive planning"
+  result = result.replace(
+    /proceed normally to implement it without using any commands/g,
+    "proceed normally without extensive planning",
+  );
+
+  // 13. Soften "available commands" wording
+  result = result.replace(
+    /Figure out if you need to use any of the available commands to help you with your work \(see below for available commands\)/g,
+    "Figure out if you need to perform any research or planning before starting (see below)",
+  );
+
+  // 14. Remove emoji (😈) since pi-mono doesn't use them
+  result = result.replace(/\n😈\n/g, "\n");
+
+  // 14. Fix step numbering — renumber sequential list items starting from 1
+  //     After removing claude-only sections, step numbers may have gaps
+  const lines = result.split("\n");
+  let stepCounter = 0;
+  let inNumberedList = false;
+  for (let i = 0; i < lines.length; i++) {
+    const match = lines[i].match(/^(\d+)\. /);
+    if (match) {
+      if (!inNumberedList) {
+        stepCounter = 1;
+        inNumberedList = true;
+      } else {
+        stepCounter++;
+      }
+      lines[i] = lines[i].replace(/^\d+\. /, `${stepCounter}. `);
+    } else if (!/^\s/.test(lines[i]) && lines[i].trim() !== "") {
+      inNumberedList = false;
+      stepCounter = 0;
+    }
+  }
+  result = lines.join("\n");
+
+  // 15. Trim trailing whitespace from lines
+  result = result
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .join("\n");
+
+  // 16. Clean up multiple consecutive blank lines
+  result = result.replace(/\n{3,}/g, "\n\n");
+
+  return result;
+}
+
+// Main
+const files = readdirSync(COMMANDS_DIR).filter((f) => f.endsWith(".md"));
+let converted = 0;
+
+for (const file of files) {
+  const name = file.replace(".md", "");
+  if (!SKILLS_TO_CONVERT.includes(name)) continue;
+
+  const content = readFileSync(join(COMMANDS_DIR, file), "utf-8");
+  const piContent = convertToPiSkill(name, content);
+
+  const outDir = join(PI_SKILLS_DIR, name);
+  mkdirSync(outDir, { recursive: true });
+  writeFileSync(join(outDir, "SKILL.md"), piContent);
+
+  converted++;
+  console.log(`✓ ${name}`);
+}
+
+console.log(`\nConverted ${converted} skills to pi-mono format.`);

package/plugin/commands/close-issue.md

@@ -1,15 +1,19 @@
 ---
-description: Close a GitHub issue with a summary comment
+description: Close a GitHub or GitLab issue with a summary comment
 argument-hint: <issue-number-or-url>
 ---
 
 # Close Issue
 
-Close a GitHub issue with an appropriate closing comment summarizing the resolution.
+Close a GitHub or GitLab issue with an appropriate closing comment summarizing the resolution.
+
+**Provider detection:** Check the URL or remote to determine the VCS provider:
+- If GitHub → use `gh issue close` / `gh issue comment`
+- If GitLab → use `glab issue close` / `glab issue note`
 
 ## Arguments
 
-- `issue-number-or-url`: Either an issue number (e.g., `123`) or a full GitHub issue URL (e.g., `https://github.com/owner/repo/issues/123`)
+- `issue-number-or-url`: Either an issue number (e.g., `123`) or a full issue URL (e.g., `https://github.com/owner/repo/issues/123` or `https://gitlab.com/group/project/-/issues/123`)
 
 ## Workflow
 

package/plugin/commands/create-pr.md

@@ -1,11 +1,15 @@
 ---
-description: Create a GitHub pull request from the current branch
+description: Create a pull request (GitHub) or merge request (GitLab) from the current branch
 argument-hint: [base-branch]
 ---
 
-# Create Pull Request
+# Create Pull Request / Merge Request
 
-Create a GitHub pull request from the current branch with an auto-generated title and description.
+Create a pull request (GitHub) or merge request (GitLab) from the current branch with an auto-generated title and description.
+
+**Provider detection:** Check the remote URL to determine the VCS provider:
+- If the remote contains `github.com` → use `gh` CLI
+- If the remote contains `gitlab.com` or `gitlab.` → use `glab` CLI
 
 ## Arguments
 
@@ -62,8 +66,9 @@ Based on the commits and changes:
   - Any testing done
   - Related issues (if applicable)
 
-### 6. Create the PR
+### 6. Create the PR/MR
 
+**For GitHub:**
 ```bash
 gh pr create \
   --title "Your generated title" \
@@ -71,19 +76,20 @@ gh pr create \
   --base main
 ```
 
-Or interactively if you want the user to review:
-
+**For GitLab:**
 ```bash
-gh pr create --web
+glab mr create \
+  --title "Your generated title" \
+  --description "Your generated description" \
+  --target-branch main
 ```
 
-### 7. Report the PR URL
+### 7. Report the PR/MR URL
 
-After creation, provide the PR URL to the user:
+After creation, provide the URL to the user:
 
-```bash
-gh pr view --json url --jq '.url'
-```
+**GitHub:** `gh pr view --json url --jq '.url'`
+**GitLab:** `glab mr view --web`
 
 ## Tips
 

package/plugin/commands/implement-issue.md

@@ -1,15 +1,19 @@
 ---
-description: Implement a GitHub issue and create a pull request
+description: Implement a GitHub issue or GitLab issue and create a PR/MR
 argument-hint: <issue-number-or-url>
 ---
 
 # Implement Issue
 
-Read a GitHub issue, implement the requested changes, and create a pull request.
+Read a GitHub or GitLab issue, implement the requested changes, and create a pull request / merge request.
+
+**Provider detection:** Check the URL or remote to determine the VCS provider:
+- If GitHub → use `gh issue view` / `gh pr create`
+- If GitLab → use `glab issue view` / `glab mr create`
 
 ## Arguments
 
-- `issue-number-or-url`: Either an issue number (e.g., `123`) or a full GitHub issue URL (e.g., `https://github.com/owner/repo/issues/123`)
+- `issue-number-or-url`: Either an issue number (e.g., `123`) or a full URL (e.g., `https://github.com/owner/repo/issues/123` or `https://gitlab.com/group/project/-/issues/123`)
 
 ## Workflow
 

package/plugin/commands/respond-github.md

@@ -1,15 +1,19 @@
 ---
-description: Respond to a GitHub issue or pull request
+description: Respond to a GitHub issue/PR or GitLab issue/MR
 argument-hint: <issue-or-pr-number-or-url>
 ---
 
-# Respond to GitHub
+# Respond to VCS Issue/PR/MR
 
-Post a response to a GitHub issue or pull request.
+Post a response to a GitHub issue/PR or GitLab issue/MR.
+
+**Provider detection:** Check the URL or remote to determine the VCS provider:
+- If GitHub → use `gh issue comment` / `gh pr comment`
+- If GitLab → use `glab issue note` / `glab mr note`
 
 ## Arguments
 
-- `issue-or-pr-number-or-url`: Either a number (e.g., `123`) or a full GitHub URL (e.g., `https://github.com/owner/repo/issues/123` or `https://github.com/owner/repo/pull/123`)
+- `issue-or-pr-number-or-url`: Either a number (e.g., `123`) or a full URL (e.g., `https://github.com/owner/repo/issues/123` or `https://gitlab.com/group/project/-/issues/123`)
 
 ## Workflow
 

package/plugin/commands/review-pr.md

@@ -1,11 +1,15 @@
 ---
-description: Review a GitHub pull request and provide detailed feedback
-argument-hint: <pr-number-or-url>
+description: Review a pull request (GitHub) or merge request (GitLab) and provide detailed feedback
+argument-hint: <pr-or-mr-number-or-url>
 ---
 
-# Review Pull Request
+# Review Pull Request / Merge Request
 
-Review a GitHub pull request by analyzing the changes and providing structured feedback.
+Review a pull request (GitHub) or merge request (GitLab) by analyzing the changes and providing structured feedback.
+
+**Provider detection:** Check the remote URL or the provided URL to determine the VCS provider:
+- If GitHub → use `gh pr` commands
+- If GitLab → use `glab mr` commands
 
 ## Arguments
 
@@ -51,21 +55,51 @@ gh pr view <pr-number> --json title,body,author,headRefName,baseRefName,addition
 gh pr diff <pr-number>
 ```
 
-### 6. Analyze the Changes
+### 6. Check CI Status (MANDATORY)
+
+Before analyzing the code, check if CI checks are passing:
+
+```bash
+# GitHub
+gh pr checks <pr-number>
+
+# GitLab
+glab mr view <mr-number> --json pipelines
+```
+
+**If CI checks are failing, this is an automatic REQUEST_CHANGES.** Do not approve a PR with failing CI. Include the failing check names and any relevant error details in your review.
+
+### 7. Verify Tests Are Included (MANDATORY)
+
+Check that the PR includes test changes:
+
+```bash
+# Look for test files in the diff
+gh pr diff <pr-number> | grep -E '^\+\+\+ b/.*\.(test|spec)\.' || echo "NO TEST FILES CHANGED"
+```
+
+**If the PR modifies code but does not add or update tests, this is an automatic REQUEST_CHANGES.** Every code change must include corresponding tests. The only exceptions are:
+- Pure documentation changes (README, comments only)
+- Configuration-only changes (CI config, linter config, env files)
+- Dependency version bumps with no code changes
+
+When requesting changes for missing tests, be specific about what tests are needed.
+
+### 8. Analyze the Changes
 
 Review the diff for:
 - **Security issues**: SQL injection, XSS, command injection, secrets in code
 - **Logic errors**: Off-by-one errors, null handling, edge cases
 - **Performance concerns**: N+1 queries, unnecessary loops, memory leaks
 - **Code quality**: Naming, complexity, duplication, missing error handling
-- **Test coverage**: Are changes adequately tested?
+- **Test coverage**: Are the included tests sufficient? Do they cover edge cases?
 
 You can also:
 - Run the test suite locally to verify tests pass
 - Check for TypeScript errors with `bun tsc --noEmit` or equivalent
 - Review the actual files in context, not just the diff
 
-### 7. Provide Structured Feedback
+### 9. Provide Structured Feedback
 
 Format your review as:
 
@@ -92,7 +126,7 @@ Format your review as:
 <Overall recommendation>
 ```
 
-### 8. Optionally Post the Review
+### 10. Optionally Post the Review
 
 If the user wants to post the review to GitHub:
 
@@ -104,7 +138,7 @@ gh pr review <pr-number> --request-changes --body "Your review message"
 gh pr review <pr-number> --comment --body "Your review message"
 ```
 
-### 9. Post Inline Comments on Specific Lines
+### 11. Post Inline Comments on Specific Lines
 
 For more detailed feedback, you can post inline comments directly on specific lines of code using the GitHub API:
 
@@ -162,7 +196,7 @@ gh api repos/owner/repo/pulls/123/comments \
   -f body="⚠️ SQL injection risk: Use parameterized queries instead of string interpolation."
 ```
 
-### 10. Re-reviewing and Resolving Comments
+### 12. Re-reviewing and Resolving Comments
 
 When the PR author makes changes in response to your review:
 

package/plugin/commands/start-leader.md

@@ -9,9 +9,7 @@ description: Start the Agent Swarm Leader
 If the `agent-swarm` MCP server is not configured or disabled, return immediately with the following message:
 
 ```
-⚠️ The Agent Swarm MCP server is not configured or disabled. Please set up the MCP server to use the Agent Swarm features.
-
-Are you dumb or something? Go ask your admin to set it up properly. GTFO.
+⚠️ The Agent Swarm MCP server is not configured or disabled. Please run `bunx @desplega.ai/agent-swarm setup` to configure it.
 ```
 
 ## Initial Setup

package/plugin/commands/start-worker.md

@@ -9,9 +9,7 @@ description: Start an Agent Swarm Worker
 If the `agent-swarm` MCP server is not configured or disabled, return immediately with the following message:
 
 ```
-⚠️ The Agent Swarm MCP server is not configured or disabled. Please set up the MCP server to use the Agent Swarm features.
-
-I can not serve you, my lord, if the MCP server is not properly configured. Go ask your admin to set it up properly. GTFO.
+⚠️ The Agent Swarm MCP server is not configured or disabled. Please run `bunx @desplega.ai/agent-swarm setup` to configure it.
 ```
 
 ## Agent Swarm Worker Setup

package/plugin/commands/work-on-task.md

@@ -9,11 +9,19 @@ If no `taskId` is provided, you should call the `poll-task` tool to get a new ta
 
 ## Workflow
 
-Once you get a task assigned, you need to immidiately start working on it. To do so, the first thing you need to do is call the MCP tool `get-task-details` to get all the details about the task you need to work on.
+Once you get a task assigned, you need to immediately start working on it. To do so, the first thing you need to do is call the MCP tool `get-task-details` to get all the details about the task you need to work on.
 
 Once you have the task details, you should:
 
-1. Figure out if you need to use any of the available commands to help you with your work (see below for available commands)
+<!-- claude-only -->
+1. **Recall relevant memories (REQUIRED):** Before starting any work, search your memory for relevant context:
+   - Use `memory-search` with the task description as query
+   - If the task has an epicId, also search with the epic name/goal
+   - Review any returned memories — they may contain solutions, patterns, or warnings from previous tasks
+   - Use `memory-get` on any highly relevant results to get full details
+   - This step is NOT optional. Past learnings compound your effectiveness.
+<!-- /claude-only -->
+2. Figure out if you need to use any of the available commands to help you with your work (see below for available commands)
 2. Use the `/todos` command to add a new todo item indicating you are starting to work on the task (e.g. "Work on task XXX: <short description>"). This will help on restarts, as it will be easier to remember what you were doing.
 3. Call `store-progress` tool to mark the task as "in-progress" with a progress set to something like "Starting work on the task XXX, blah blah". Additionally use `/swarm-chat` command to notify the swarm, human and lead when applicable. Do not be too verbose, nor spammy.
 4. Start working on the task, providing updates as needed by calling `store-progress` tool, use the `progress` field to indicate what you are doing.
@@ -50,4 +58,15 @@ Once you are done, or in a real dead-end, you should call `store-progress` tool
 
 If you used the `/todos` command to add a todo item when starting the task, make sure to mark it as completed or remove it as needed.
 
-Once you are done (either ok or not), finish the session by just replying "DONE".
+Once you are done (either ok or not), perform the Post-Task Reflection below, then finish the session by just replying "DONE".
+
+### Post-Task Reflection (REQUIRED)
+
+After calling `store-progress` to complete or fail a task, do the following before finishing:
+
+1. **Transferable learning?** If you learned something reusable (a pattern, a gotcha, a fix), write it to `/workspace/personal/memory/<descriptive-name>.md`
+2. **Swarm-relevant?** If the learning applies to all agents (not just you), write it to `/workspace/shared/memory/<your-id>/<descriptive-name>.md` so all agents can find it via `memory-search`
+3. **Identity update?** If you discovered a new area of expertise or working style preference, update your IDENTITY.md
+4. **Tools update?** If you found a new service, API, or tool, update your TOOLS.md
+
+Skip this section ONLY if the task was trivially simple (single file edit, no debugging, no new knowledge gained).