@desplega.ai/agent-swarm 1.58.0 → 1.59.0

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.58.0",
+    "version": "1.59.0",
     "description": "Multi-agent orchestration API for Claude Code, Codex, and Gemini CLI. Enables task distribution, agent communication, and service discovery.\n\nMCP tools are documented separately in [MCP.md](./MCP.md)."
   },
   "servers": [
@@ -2879,6 +2879,41 @@
                       "type": "boolean",
                       "default": true
                     },
+                    "guidelines": {
+                      "type": [
+                        "object",
+                        "null"
+                      ],
+                      "properties": {
+                        "prChecks": {
+                          "type": "array",
+                          "items": {
+                            "type": "string"
+                          }
+                        },
+                        "mergeChecks": {
+                          "type": "array",
+                          "items": {
+                            "type": "string"
+                          }
+                        },
+                        "allowMerge": {
+                          "type": "boolean",
+                          "default": false
+                        },
+                        "review": {
+                          "type": "array",
+                          "items": {
+                            "type": "string"
+                          }
+                        }
+                      },
+                      "required": [
+                        "prChecks",
+                        "mergeChecks",
+                        "review"
+                      ]
+                    },
                     "createdAt": {
                       "type": "string"
                     },
@@ -2959,6 +2994,41 @@
                   },
                   "autoClone": {
                     "type": "boolean"
+                  },
+                  "guidelines": {
+                    "type": [
+                      "object",
+                      "null"
+                    ],
+                    "properties": {
+                      "prChecks": {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      },
+                      "mergeChecks": {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      },
+                      "allowMerge": {
+                        "type": "boolean",
+                        "default": false
+                      },
+                      "review": {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      }
+                    },
+                    "required": [
+                      "prChecks",
+                      "mergeChecks",
+                      "review"
+                    ]
                   }
                 }
               }
@@ -2998,6 +3068,41 @@
                       "type": "boolean",
                       "default": true
                     },
+                    "guidelines": {
+                      "type": [
+                        "object",
+                        "null"
+                      ],
+                      "properties": {
+                        "prChecks": {
+                          "type": "array",
+                          "items": {
+                            "type": "string"
+                          }
+                        },
+                        "mergeChecks": {
+                          "type": "array",
+                          "items": {
+                            "type": "string"
+                          }
+                        },
+                        "allowMerge": {
+                          "type": "boolean",
+                          "default": false
+                        },
+                        "review": {
+                          "type": "array",
+                          "items": {
+                            "type": "string"
+                          }
+                        }
+                      },
+                      "required": [
+                        "prChecks",
+                        "mergeChecks",
+                        "review"
+                      ]
+                    },
                     "createdAt": {
                       "type": "string"
                     },
@@ -3187,6 +3292,41 @@
                             "type": "boolean",
                             "default": true
                           },
+                          "guidelines": {
+                            "type": [
+                              "object",
+                              "null"
+                            ],
+                            "properties": {
+                              "prChecks": {
+                                "type": "array",
+                                "items": {
+                                  "type": "string"
+                                }
+                              },
+                              "mergeChecks": {
+                                "type": "array",
+                                "items": {
+                                  "type": "string"
+                                }
+                              },
+                              "allowMerge": {
+                                "type": "boolean",
+                                "default": false
+                              },
+                              "review": {
+                                "type": "array",
+                                "items": {
+                                  "type": "string"
+                                }
+                              }
+                            },
+                            "required": [
+                              "prChecks",
+                              "mergeChecks",
+                              "review"
+                            ]
+                          },
                           "createdAt": {
                             "type": "string"
                           },
@@ -3246,6 +3386,41 @@
                   },
                   "autoClone": {
                     "type": "boolean"
+                  },
+                  "guidelines": {
+                    "type": [
+                      "object",
+                      "null"
+                    ],
+                    "properties": {
+                      "prChecks": {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      },
+                      "mergeChecks": {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      },
+                      "allowMerge": {
+                        "type": "boolean",
+                        "default": false
+                      },
+                      "review": {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      }
+                    },
+                    "required": [
+                      "prChecks",
+                      "mergeChecks",
+                      "review"
+                    ]
                   }
                 },
                 "required": [
@@ -3289,6 +3464,41 @@
                       "type": "boolean",
                       "default": true
                     },
+                    "guidelines": {
+                      "type": [
+                        "object",
+                        "null"
+                      ],
+                      "properties": {
+                        "prChecks": {
+                          "type": "array",
+                          "items": {
+                            "type": "string"
+                          }
+                        },
+                        "mergeChecks": {
+                          "type": "array",
+                          "items": {
+                            "type": "string"
+                          }
+                        },
+                        "allowMerge": {
+                          "type": "boolean",
+                          "default": false
+                        },
+                        "review": {
+                          "type": "array",
+                          "items": {
+                            "type": "string"
+                          }
+                        }
+                      },
+                      "required": [
+                        "prChecks",
+                        "mergeChecks",
+                        "review"
+                      ]
+                    },
                     "createdAt": {
                       "type": "string"
                     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.58.0",
+  "version": "1.59.0",
   "description": "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants",
   "license": "MIT",
   "author": "desplega.sh <contact@desplega.sh>",

package/plugin/commands/create-pr.md

@@ -22,13 +22,15 @@ You should be working in a repository cloned to `/workspace/personal/<repo-name>
 ## Workflow
 
 1. **Verify state** — confirm you're in a git repo, not on main/master, and have commits to push.
-2. **Push the branch** — `git push -u origin HEAD`
-3. **Gather context** — review commit messages and changed files since diverging from base.
-4. **Generate title and description:**
+2. **Run PR checks (MANDATORY)** — Run ALL checks listed in the "PR Checks" section of your Repository Guidelines. Run each command/task sequentially. If ANY check fails, fix the issue and re-run until all pass. If no guidelines are defined, check the project's CLAUDE.md for a pre-PR checklist and run those. Do NOT proceed until all checks pass.
+3. **Push the branch** — `git push -u origin HEAD`
+4. **Gather context** — review commit messages and changed files since diverging from base.
+5. **Generate title and description:**
    - **Title**: Concise summary (conventional commit style if the repo uses it)
    - **Description**: Summary of changes, notable items, testing done, related issues
-5. **Create the PR/MR** using `gh pr create` or `glab mr create`.
-6. **Report** the PR/MR URL.
+6. **Create the PR/MR** using `gh pr create` or `glab mr create`.
+7. **Check CI status** — After creating the PR, wait ~30 seconds, then check CI with `gh pr checks <pr-number>` (GitHub) or `glab mr view --json pipelines` (GitLab). If any check is failing, investigate the failure, fix it, push the fix, and re-check. Repeat until CI is green.
+8. **Report** the PR/MR URL and CI status.
 
 ## Tips
 

package/plugin/commands/implement-issue.md

@@ -37,14 +37,18 @@ If given a URL, extract owner, repo, and issue number. Fetch issue details (titl
 
 Keep changes focused on what the issue requests. Avoid scope creep.
 
-### 4. Commit and Push
+### 4. Quality Checks, Commit, and Push
 
-Commit with a message referencing the issue (e.g., `Fix #123: <description>`). Use conventional commit style if the repo uses it. Push with `git push -u origin HEAD`.
+1. **Run PR checks (MANDATORY)** — Run ALL checks from the "PR Checks" section of your Repository Guidelines. Fix any failures before proceeding. If no guidelines are defined, check the project's CLAUDE.md for a pre-PR checklist.
+2. **Commit** with a message referencing the issue (e.g., `Fix #123: <description>`). Use conventional commit style if the repo uses it.
+3. **Push** with `git push -u origin HEAD`.
 
 ### 5. Create the PR
 
 Create the PR with a descriptive title and body including: summary of changes, key changes list, testing done, and `Fixes #<issue-number>` to auto-close the issue on merge.
 
+After creating the PR, check CI status with `gh pr checks` (GitHub) or `glab mr view --json pipelines` (GitLab). If CI fails, fix the issues, push, and re-check until green.
+
 ### 6. Report Back
 
 Provide the PR URL, summary of changes, and any caveats. Optionally comment on the original issue linking the PR.
@@ -56,4 +60,3 @@ Provide the PR URL, summary of changes, and any caveats. Optionally comment on t
 - One issue = one PR
 - If the issue is too large, break it into smaller PRs
 - If unclear, use `/respond-github` to ask for clarification
-- Run linters and tests before creating the PR

package/plugin/commands/review-pr.md

@@ -28,6 +28,12 @@ Check CI with `gh pr checks <pr-number>` (or `glab mr view --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 error details in your review.
 
+### 2b. Review Repository Guidelines
+
+Check the "Review Guidance" section of your Repository Guidelines for repo-specific review instructions (e.g., "check README.md", "enforce camelCase in specific directories"). Apply these instructions during your review below.
+
+Also note the repo's **Merge Policy** — check `allowMerge` and `mergeChecks` before approving or merging. If `allowMerge` is false, do NOT merge — only review and approve/request changes.
+
 ### 3. Verify Tests Are Included (MANDATORY)
 
 Check that the PR includes test changes. **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.

package/plugin/commands/user-management.md

@@ -0,0 +1,119 @@
+---
+description: "How to manage the user registry — creating users for new Slack/GitHub/GitLab identities, managing aliases, resolving users across platforms. Use when a new human interacts with the swarm or when user identity needs updating."
+argument-hint: [action]
+---
+
+# User Management
+
+Manage the swarm's user registry — creating, updating, resolving, and listing users. Users link human identities across platforms (Slack, GitHub, GitLab, Linear, email) so the swarm can track who requested work.
+
+## When to Create Users
+
+Create a new user when:
+- An **unknown Slack user** sends a message to the swarm (no `resolveUser` match for their `slackUserId`)
+- An **unknown GitHub user** opens an issue or PR that triggers a task
+- An **unknown GitLab user** creates an issue or MR
+- An **unknown Linear user** is assigned to or creates a synced issue
+- A human explicitly asks to be registered
+
+**Do NOT** create duplicate users. Always call `resolve-user` first to check if the person already exists under a different platform identity.
+
+## Tools
+
+Two MCP tools handle user management:
+
+### `resolve-user` — Find an existing user
+
+Looks up a user by any platform identity. Use this BEFORE creating a new user.
+
+```
+resolve-user with:
+  slackUserId: "U12345"       # Slack member ID
+  # OR
+  githubUsername: "octocat"    # GitHub username
+  # OR
+  gitlabUsername: "octocat"    # GitLab username
+  # OR
+  linearUserId: "uuid"        # Linear user UUID
+  # OR
+  email: "user@example.com"   # Primary email or alias
+  # OR
+  name: "Jane Doe"            # Fuzzy name search (least specific)
+```
+
+Priority order: platform IDs > email > name. Platform IDs are exact matches; email checks aliases (case-insensitive); name is substring match.
+
+### `manage-user` — CRUD operations
+
+```
+# Create a new user
+manage-user with:
+  action: "create"
+  name: "Jane Doe"                          # Required
+  email: "jane@company.com"                 # Optional
+  role: "engineering lead"                  # Optional, free-form
+  slackUserId: "U12345"                     # Optional
+  githubUsername: "janedoe"                 # Optional
+  gitlabUsername: "janedoe"                 # Optional
+  linearUserId: "uuid-from-linear"          # Optional
+  emailAliases: ["jane.doe@company.com"]    # Optional
+  timezone: "America/New_York"              # Optional
+  notes: "Prefers async communication"      # Optional
+
+# List all users
+manage-user with:
+  action: "list"
+
+# Get a specific user
+manage-user with:
+  action: "get"
+  userId: "<uuid>"
+
+# Update a user (only send fields to change)
+manage-user with:
+  action: "update"
+  userId: "<uuid>"
+  githubUsername: "new-username"
+
+# Delete a user
+manage-user with:
+  action: "delete"
+  userId: "<uuid>"
+```
+
+## Workflow: New Slack User
+
+1. Receive a message from an unknown Slack user (e.g., `slackUserId: "U_NEW123"`)
+2. Call `resolve-user` with `slackUserId: "U_NEW123"` — returns null
+3. Get the user's Slack profile (name, email) via `slack-read` or from the message metadata
+4. Call `resolve-user` with `email: "<their-email>"` — check if they exist under a different platform
+5. If found: call `manage-user` with `action: "update"` to add their `slackUserId`
+6. If not found: call `manage-user` with `action: "create"` including name, email, and slackUserId
+
+## Workflow: New GitHub User
+
+1. Receive a webhook from an unknown GitHub user (e.g., `githubUsername: "octocat"`)
+2. Call `resolve-user` with `githubUsername: "octocat"` — returns null
+3. Call `manage-user` with `action: "create"` including at minimum `name` and `githubUsername`
+4. If you know their email (from the webhook payload), include it
+
+## Workflow: Linking Identities
+
+When you discover a known user is also active on another platform:
+
+1. Call `resolve-user` to find them by their known identity
+2. Call `manage-user` with `action: "update"` to add the new platform identity
+
+Example: You know "Jane" by Slack ID, and discover her GitHub username:
+```
+resolve-user slackUserId: "U_JANE"  → returns user with id "abc-123"
+manage-user action: "update" userId: "abc-123" githubUsername: "janedoe"
+```
+
+## Important Notes
+
+- `manage-user` is **lead-only** — workers cannot use it for any action (the lead check happens before action dispatch). Workers must use `resolve-user` for lookups.
+- `slackUserId`, `githubUsername`, `gitlabUsername`, and `linearUserId` have **unique constraints** — duplicates will error.
+- Deleting a user clears `requestedByUserId` on all their associated tasks (sets to null).
+- Email aliases are case-insensitive for resolution.
+- The `preferredChannel` field defaults to `"slack"` and can be `"slack"`, `"email"`, `"github"`, or `"gitlab"`.

package/plugin/pi-skills/create-pr/SKILL.md

@@ -22,13 +22,15 @@ You should be working in a repository cloned to `/workspace/personal/<repo-name>
 ## Workflow
 
 1. **Verify state** — confirm you're in a git repo, not on main/master, and have commits to push.
-2. **Push the branch** — `git push -u origin HEAD`
-3. **Gather context** — review commit messages and changed files since diverging from base.
-4. **Generate title and description:**
+2. **Run PR checks (MANDATORY)** — Run ALL checks listed in the "PR Checks" section of your Repository Guidelines. Run each command/task sequentially. If ANY check fails, fix the issue and re-run until all pass. If no guidelines are defined, check the project's CLAUDE.md for a pre-PR checklist and run those. Do NOT proceed until all checks pass.
+3. **Push the branch** — `git push -u origin HEAD`
+4. **Gather context** — review commit messages and changed files since diverging from base.
+5. **Generate title and description:**
    - **Title**: Concise summary (conventional commit style if the repo uses it)
    - **Description**: Summary of changes, notable items, testing done, related issues
-5. **Create the PR/MR** using `gh pr create` or `glab mr create`.
-6. **Report** the PR/MR URL.
+6. **Create the PR/MR** using `gh pr create` or `glab mr create`.
+7. **Check CI status** — After creating the PR, wait ~30 seconds, then check CI with `gh pr checks <pr-number>` (GitHub) or `glab mr view --json pipelines` (GitLab). If any check is failing, investigate the failure, fix it, push the fix, and re-check. Repeat until CI is green.
+8. **Report** the PR/MR URL and CI status.
 
 ## Tips
 

package/plugin/pi-skills/implement-issue/SKILL.md

@@ -37,14 +37,18 @@ If given a URL, extract owner, repo, and issue number. Fetch issue details (titl
 
 Keep changes focused on what the issue requests. Avoid scope creep.
 
-### 4. Commit and Push
+### 4. Quality Checks, Commit, and Push
 
-Commit with a message referencing the issue (e.g., `Fix #123: <description>`). Use conventional commit style if the repo uses it. Push with `git push -u origin HEAD`.
+1. **Run PR checks (MANDATORY)** — Run ALL checks from the "PR Checks" section of your Repository Guidelines. Fix any failures before proceeding. If no guidelines are defined, check the project's CLAUDE.md for a pre-PR checklist.
+2. **Commit** with a message referencing the issue (e.g., `Fix #123: <description>`). Use conventional commit style if the repo uses it.
+3. **Push** with `git push -u origin HEAD`.
 
 ### 5. Create the PR
 
 Create the PR with a descriptive title and body including: summary of changes, key changes list, testing done, and `Fixes #<issue-number>` to auto-close the issue on merge.
 
+After creating the PR, check CI status with `gh pr checks` (GitHub) or `glab mr view --json pipelines` (GitLab). If CI fails, fix the issues, push, and re-check until green.
+
 ### 6. Report Back
 
 Provide the PR URL, summary of changes, and any caveats. Optionally comment on the original issue linking the PR.
@@ -56,4 +60,3 @@ Provide the PR URL, summary of changes, and any caveats. Optionally comment on t
 - One issue = one PR
 - If the issue is too large, break it into smaller PRs
 - If unclear, use `/skill:respond-github` to ask for clarification
-- Run linters and tests before creating the PR

package/plugin/pi-skills/review-pr/SKILL.md

@@ -28,6 +28,12 @@ Check CI with `gh pr checks <pr-number>` (or `glab mr view --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 error details in your review.
 
+### 2b. Review Repository Guidelines
+
+Check the "Review Guidance" section of your Repository Guidelines for repo-specific review instructions (e.g., "check README.md", "enforce camelCase in specific directories"). Apply these instructions during your review below.
+
+Also note the repo's **Merge Policy** — check `allowMerge` and `mergeChecks` before approving or merging. If `allowMerge` is false, do NOT merge — only review and approve/request changes.
+
 ### 3. Verify Tests Are Included (MANDATORY)
 
 Check that the PR includes test changes. **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.

package/plugin/pi-skills/user-management/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: user-management
+description: "How to manage the user registry — creating users for new Slack/GitHub/GitLab identities, managing aliases, resolving users across platforms. Use when a new human interacts with the swarm or when user identity needs updating."
+---
+
+# User Management
+
+Manage the swarm's user registry — creating, updating, resolving, and listing users. Users link human identities across platforms (Slack, GitHub, GitLab, Linear, email) so the swarm can track who requested work.
+
+## When to Create Users
+
+Create a new user when:
+- An **unknown Slack user** sends a message to the swarm (no `resolveUser` match for their `slackUserId`)
+- An **unknown GitHub user** opens an issue or PR that triggers a task
+- An **unknown GitLab user** creates an issue or MR
+- An **unknown Linear user** is assigned to or creates a synced issue
+- A human explicitly asks to be registered
+
+**Do NOT** create duplicate users. Always call `resolve-user` first to check if the person already exists under a different platform identity.
+
+## Tools
+
+Two MCP tools handle user management:
+
+### `resolve-user` — Find an existing user
+
+Looks up a user by any platform identity. Use this BEFORE creating a new user.
+
+```
+resolve-user with:
+  slackUserId: "U12345"       # Slack member ID
+  # OR
+  githubUsername: "octocat"    # GitHub username
+  # OR
+  gitlabUsername: "octocat"    # GitLab username
+  # OR
+  linearUserId: "uuid"        # Linear user UUID
+  # OR
+  email: "user@example.com"   # Primary email or alias
+  # OR
+  name: "Jane Doe"            # Fuzzy name search (least specific)
+```
+
+Priority order: platform IDs > email > name. Platform IDs are exact matches; email checks aliases (case-insensitive); name is substring match.
+
+### `manage-user` — CRUD operations
+
+```
+# Create a new user
+manage-user with:
+  action: "create"
+  name: "Jane Doe"                          # Required
+  email: "jane@company.com"                 # Optional
+  role: "engineering lead"                  # Optional, free-form
+  slackUserId: "U12345"                     # Optional
+  githubUsername: "janedoe"                 # Optional
+  gitlabUsername: "janedoe"                 # Optional
+  linearUserId: "uuid-from-linear"          # Optional
+  emailAliases: ["jane.doe@company.com"]    # Optional
+  timezone: "America/New_York"              # Optional
+  notes: "Prefers async communication"      # Optional
+
+# List all users
+manage-user with:
+  action: "list"
+
+# Get a specific user
+manage-user with:
+  action: "get"
+  userId: "<uuid>"
+
+# Update a user (only send fields to change)
+manage-user with:
+  action: "update"
+  userId: "<uuid>"
+  githubUsername: "new-username"
+
+# Delete a user
+manage-user with:
+  action: "delete"
+  userId: "<uuid>"
+```
+
+## Workflow: New Slack User
+
+1. Receive a message from an unknown Slack user (e.g., `slackUserId: "U_NEW123"`)
+2. Call `resolve-user` with `slackUserId: "U_NEW123"` — returns null
+3. Get the user's Slack profile (name, email) via `slack-read` or from the message metadata
+4. Call `resolve-user` with `email: "<their-email>"` — check if they exist under a different platform
+5. If found: call `manage-user` with `action: "update"` to add their `slackUserId`
+6. If not found: call `manage-user` with `action: "create"` including name, email, and slackUserId
+
+## Workflow: New GitHub User
+
+1. Receive a webhook from an unknown GitHub user (e.g., `githubUsername: "octocat"`)
+2. Call `resolve-user` with `githubUsername: "octocat"` — returns null
+3. Call `manage-user` with `action: "create"` including at minimum `name` and `githubUsername`
+4. If you know their email (from the webhook payload), include it
+
+## Workflow: Linking Identities
+
+When you discover a known user is also active on another platform:
+
+1. Call `resolve-user` to find them by their known identity
+2. Call `manage-user` with `action: "update"` to add the new platform identity
+
+Example: You know "Jane" by Slack ID, and discover her GitHub username:
+```
+resolve-user slackUserId: "U_JANE"  → returns user with id "abc-123"
+manage-user action: "update" userId: "abc-123" githubUsername: "janedoe"
+```
+
+## Important Notes
+
+- `manage-user` is **lead-only** — workers cannot use it for any action (the lead check happens before action dispatch). Workers must use `resolve-user` for lookups.
+- `slackUserId`, `githubUsername`, `gitlabUsername`, and `linearUserId` have **unique constraints** — duplicates will error.
+- Deleting a user clears `requestedByUserId` on all their associated tasks (sets to null).
+- Email aliases are case-insensitive for resolution.
+- The `preferredChannel` field defaults to `"slack"` and can be `"slack"`, `"email"`, `"github"`, or `"gitlab"`.