@desplega.ai/agent-swarm 1.20.0 → 1.49.0

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

@@ -0,0 +1,90 @@
+---
+name: close-issue
+description: Close a GitHub or GitLab issue with a summary comment
+---
+
+# Close Issue
+
+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 issue URL (e.g., `https://github.com/owner/repo/issues/123` or `https://gitlab.com/group/project/-/issues/123`)
+
+## Workflow
+
+### 1. Parse the Input
+
+If given a URL, extract the owner, repo, and issue number. If given just a number, use the current repository context.
+
+### 2. Ensure Repository is Cloned Locally
+
+Make sure the repository is available in your personal workspace:
+
+```bash
+REPO_PATH=/workspace/personal/<repo-name>
+
+if [ ! -d "$REPO_PATH" ]; then
+  gh repo clone <owner>/<repo> "$REPO_PATH"
+fi
+
+cd "$REPO_PATH"
+```
+
+### 3. Get Issue Details
+
+```bash
+gh issue view <issue-number> --json title,body,author,labels,comments
+```
+
+### 4. Understand the Context
+
+Review:
+- What was the original issue about?
+- What work was done to resolve it?
+- Were there any related PRs or commits?
+
+Check for related PRs:
+
+```bash
+gh pr list --search "fixes #<issue-number>" --json number,title,state
+```
+
+### 5. Generate Closing Comment
+
+Write a closing comment that includes:
+- Brief summary of what was done
+- Reference to any PRs that addressed the issue
+- Any follow-up items or notes
+
+### 6. Post Comment and Close
+
+```bash
+# Add the closing comment
+gh issue comment <issue-number> --body "Your closing comment"
+
+# Close the issue
+gh issue close <issue-number>
+```
+
+Or combine with a reason:
+
+```bash
+gh issue close <issue-number> --comment "Your closing comment" --reason completed
+```
+
+## Closing Reasons
+
+- `completed` - The issue was resolved
+- `not_planned` - Won't fix / out of scope / duplicate
+
+## Tips
+
+- Always explain why the issue is being closed
+- Reference specific PRs or commits when applicable
+- If closing as "not planned", explain the reasoning
+- Be respectful - someone took time to report the issue

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

@@ -0,0 +1,99 @@
+---
+name: create-pr
+description: Create a pull request (GitHub) or merge request (GitLab) from the current branch
+---
+
+# Create Pull Request / Merge Request
+
+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
+
+- `base-branch` (optional): The branch to merge into (defaults to `main` or the repo's default branch)
+
+## Prerequisites
+
+You should be working in a repository cloned to `/workspace/personal/<repo-name>`.
+
+## Workflow
+
+### 1. Verify Working Directory
+
+Ensure you're in a git repository:
+
+```bash
+git rev-parse --is-inside-work-tree
+```
+
+### 2. Check Branch Status
+
+```bash
+# Get current branch
+git branch --show-current
+
+# Ensure we're not on main/master
+# Ensure there are commits to push
+git log origin/main..HEAD --oneline
+```
+
+### 3. Push the Branch
+
+```bash
+git push -u origin HEAD
+```
+
+### 4. Gather Context for PR Description
+
+```bash
+# Get commit messages since diverging from base
+git log origin/main..HEAD --pretty=format:"%s%n%b"
+
+# Get changed files
+git diff --stat origin/main..HEAD
+```
+
+### 5. Generate PR Title and Description
+
+Based on the commits and changes:
+- **Title**: Concise summary of the changes (use conventional commit style if the repo uses it)
+- **Description**:
+  - Summary of what changed and why
+  - List of notable changes
+  - Any testing done
+  - Related issues (if applicable)
+
+### 6. Create the PR/MR
+
+**For GitHub:**
+```bash
+gh pr create \
+  --title "Your generated title" \
+  --body "Your generated description" \
+  --base main
+```
+
+**For GitLab:**
+```bash
+glab mr create \
+  --title "Your generated title" \
+  --description "Your generated description" \
+  --target-branch main
+```
+
+### 7. Report the PR/MR URL
+
+After creation, provide the URL to the user:
+
+**GitHub:** `gh pr view --json url --jq '.url'`
+**GitLab:** `glab mr view --web`
+
+## Tips
+
+- Link related issues using `Fixes #123` or `Closes #123` in the description
+- Include a test plan if the changes are significant
+- Keep PRs focused - one logical change per PR
+- If the branch has many commits, consider summarizing the overall change rather than listing each commit

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

@@ -0,0 +1,135 @@
+---
+name: implement-issue
+description: Implement a GitHub issue or GitLab issue and create a PR/MR
+---
+
+# Implement Issue
+
+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 URL (e.g., `https://github.com/owner/repo/issues/123` or `https://gitlab.com/group/project/-/issues/123`)
+
+## Workflow
+
+### 1. Parse the Input
+
+If given a URL, extract the owner, repo, and issue number. If given just a number, use the current repository context.
+
+### 2. Fetch Issue Details
+
+```bash
+gh issue view <issue-number> --json number,title,body,labels,comments
+```
+
+Read and understand:
+- What is being requested?
+- Are there acceptance criteria?
+- Any technical details or constraints mentioned?
+- Check comments for additional context or clarifications
+
+### 3. Ensure Repository is Cloned
+
+Clone the repository to your personal workspace if not already present:
+
+```bash
+REPO_PATH=/workspace/personal/<repo-name>
+
+if [ ! -d "$REPO_PATH" ]; then
+  gh repo clone <owner>/<repo> "$REPO_PATH"
+fi
+
+cd "$REPO_PATH"
+git fetch origin
+git checkout main
+git pull origin main
+```
+
+### 4. Create a Feature Branch
+
+```bash
+# Use a descriptive branch name based on the issue
+git checkout -b fix/issue-<number>-<short-description>
+
+# Examples:
+# git checkout -b fix/issue-123-add-dark-mode
+# git checkout -b fix/issue-456-fix-login-redirect
+```
+
+### 5. Implement the Changes
+
+This is the core work. Based on the issue:
+
+1. **Understand the codebase** - Explore relevant files, understand existing patterns
+2. **Plan your approach** - Consider using plan creation for complex changes
+3. **Write the code** - Implement the requested functionality
+4. **Test your changes** - Run existing tests, add new tests if appropriate
+5. **Verify it works** - Manual verification where possible
+
+Keep changes focused on what the issue requests. Avoid scope creep.
+
+### 6. Commit Your Changes
+
+```bash
+# Stage your changes
+git add -A
+
+# Commit with a message referencing the issue
+git commit -m "Fix #<issue-number>: <short description>
+
+<longer description if needed>"
+```
+
+Use conventional commit style if the repo uses it (e.g., `feat:`, `fix:`, `docs:`).
+
+### 7. Push the Branch
+
+```bash
+git push -u origin HEAD
+```
+
+### 8. Create the Pull Request
+
+```bash
+gh pr create \
+  --title "<descriptive title>" \
+  --body "## Summary
+<Brief description of what this PR does>
+
+## Changes
+- <List key changes>
+
+## Testing
+- <How you tested the changes>
+
+Fixes #<issue-number>"
+```
+
+The `Fixes #<number>` syntax will auto-close the issue when the PR is merged.
+
+### 9. Report Back
+
+Provide the user with:
+- PR URL
+- Summary of changes made
+- Any notes or caveats
+
+Optionally, comment on the original issue:
+
+```bash
+gh issue comment <issue-number> --body "I've created a PR to address this: <PR-URL>"
+```
+
+## Tips
+
+- Read the issue thoroughly before starting - misunderstanding wastes time
+- Check if there are related issues or existing PRs
+- Keep PRs focused - one issue = one PR
+- If the issue is too large, consider breaking it into smaller PRs
+- If you get stuck or the issue is unclear, use `/skill:respond-github` to ask for clarification
+- Run linters and tests before creating the PR

package/plugin/pi-skills/investigate-sentry-issue/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: investigate-sentry-issue
+description: Investigate and triage a Sentry error issue
+---
+
+# Investigate Sentry Issue
+
+Investigate a Sentry issue to understand the error, gather context, and prepare for fixing or triaging.
+
+## Prerequisites
+
+Environment variables `SENTRY_AUTH_TOKEN` and `SENTRY_ORG` must be set (they are pre-configured in the worker environment).
+
+Verify authentication:
+```bash
+sentry-cli info
+```
+
+## Arguments
+
+- `sentry-issue-url-or-id`: Either a Sentry issue URL (e.g., `https://sentry.io/organizations/myorg/issues/123456/`) or just the issue ID (e.g., `123456`)
+
+## Workflow
+
+### 1. Parse the Sentry URL
+
+If given a URL, extract the issue ID:
+```bash
+# URL format: https://sentry.io/organizations/{org}/issues/{issue_id}/
+# Extract issue_id from the URL path
+```
+
+### 2. Get Issue Overview
+
+Use `sentry-cli` to list the issue:
+```bash
+sentry-cli issues list --id <issue-id>
+```
+
+### 3. Get Detailed Issue Information
+
+For more context, use the REST API:
+```bash
+curl -s "https://sentry.io/api/0/organizations/${SENTRY_ORG}/issues/<issue-id>/" \
+  -H "Authorization: Bearer ${SENTRY_AUTH_TOKEN}" | jq
+```
+
+This returns:
+- Error title and metadata
+- First/last seen timestamps
+- Event count and user impact
+- Assigned user and status
+
+### 4. Get Full Stacktrace
+
+The recommended event provides the best debugging context:
+```bash
+curl -s "https://sentry.io/api/0/organizations/${SENTRY_ORG}/issues/<issue-id>/events/recommended/" \
+  -H "Authorization: Bearer ${SENTRY_AUTH_TOKEN}" | jq
+```
+
+Key fields in the response:
+- `.entries[] | select(.type == "exception")` - The exception with stacktrace
+- `.entries[] | select(.type == "breadcrumbs")` - Actions leading to the error
+- `.tags` - Environment, browser, OS info
+- `.context` - Custom context data
+
+### 5. Extract Stacktrace Frames
+
+To see the actual stack:
+```bash
+curl -s "https://sentry.io/api/0/organizations/${SENTRY_ORG}/issues/<issue-id>/events/recommended/" \
+  -H "Authorization: Bearer ${SENTRY_AUTH_TOKEN}" | \
+  jq '.entries[] | select(.type == "exception") | .data.values[].stacktrace.frames'
+```
+
+### 6. Analyze and Report
+
+Based on the stacktrace and context:
+1. Identify the failing file and line number
+2. Understand the error type and message
+3. Review breadcrumbs for the sequence of events
+4. Check tags for environment-specific issues
+
+### 7. Take Action (if appropriate)
+
+**Resolve an issue:**
+```bash
+sentry-cli issues resolve <issue-id>
+```
+
+**Mute an issue:**
+```bash
+sentry-cli issues mute <issue-id>
+```
+
+**Unresolve an issue:**
+```bash
+sentry-cli issues unresolve <issue-id>
+```
+
+## Common CLI Commands
+
+```bash
+# Verify authentication
+sentry-cli info
+
+# List unresolved issues
+sentry-cli issues list --query "is:unresolved"
+
+# List recent issues (last 2 days)
+sentry-cli issues list --query "lastSeen:-2d"
+
+# List issues matching a message
+sentry-cli issues list --query "message:undefined"
+
+# Bulk resolve issues
+sentry-cli issues resolve <id1> <id2> <id3>
+```
+
+## Search Query Syntax
+
+Use these filters with `--query`:
+
+| Filter | Example | Description |
+|--------|---------|-------------|
+| `is:` | `is:unresolved`, `is:resolved` | Issue status |
+| `lastSeen:` | `lastSeen:-2d` | Seen within time range |
+| `message:` | `message:undefined` | Match error message |
+| `issue.category:` | `issue.category:error` | Error category |
+
+## Tips
+
+- Always get the recommended event first - it's curated for debugging
+- Use `jq` to filter large JSON responses
+- Check breadcrumbs to understand user actions before the error
+- Look at tags for environment info (browser, OS, etc.)
+- If investigating from a Slack alert, the issue URL is in the alert message

package/plugin/pi-skills/respond-github/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: respond-github
+description: Respond to a GitHub issue/PR or GitLab issue/MR
+---
+
+# Respond to VCS Issue/PR/MR
+
+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 URL (e.g., `https://github.com/owner/repo/issues/123` or `https://gitlab.com/group/project/-/issues/123`)
+
+## Workflow
+
+### 1. Parse the Input
+
+If given a URL, extract:
+- Owner and repo
+- Whether it's an issue or PR (from the URL path)
+- The number
+
+If given just a number, use the current repository context and check if it's an issue or PR.
+
+### 2. Ensure Repository is Cloned Locally
+
+Make sure the repository is available in your personal workspace:
+
+```bash
+REPO_PATH=/workspace/personal/<repo-name>
+
+if [ ! -d "$REPO_PATH" ]; then
+  gh repo clone <owner>/<repo> "$REPO_PATH"
+fi
+
+cd "$REPO_PATH"
+```
+
+### 3. Get Full Context
+
+For issues:
+```bash
+gh issue view <number> --json title,body,author,labels,comments,state
+```
+
+For PRs:
+```bash
+gh pr view <number> --json title,body,author,comments,state,reviews
+```
+
+### 4. Understand What's Being Asked
+
+Read through:
+- The original issue/PR description
+- All comments in the thread
+- Any specific questions or requests
+
+If this is a task from agent-swarm with `@agent-swarm` mention, focus on what was asked in that mention.
+
+### 5. Formulate Your Response
+
+Consider:
+- What specific question or request needs addressing?
+- Do you need to provide code examples?
+- Should you ask clarifying questions?
+- Is this something you can resolve, or do you need human input?
+
+### 6. Post the Response
+
+For issues:
+```bash
+gh issue comment <number> --body "Your response"
+```
+
+For PRs:
+```bash
+gh pr comment <number> --body "Your response"
+```
+
+## Response Guidelines
+
+- Be helpful and constructive
+- If you don't know something, say so
+- Provide code examples when relevant
+- Use markdown formatting for readability
+- Keep responses focused and concise
+- If you've completed work, link to the relevant PR or commit
+
+## Tips
+
+- Check if there's already a PR addressing an issue before responding
+- If asked to implement something, consider whether to respond first or just do it
+- For complex requests, acknowledge receipt and outline your plan
+- Tag relevant people with `@username` if needed

package/plugin/pi-skills/review-offered-task/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: review-offered-task
+description: Review a task that has been offered to you and decide whether to accept or reject it
+---
+
+# Review Offered Task
+
+You have been offered a task. Your job is to review it and decide whether to accept or reject it based on your capabilities and current workload.
+
+## Workflow
+
+1. **Get task details**: Call the `get-task-details` tool with the provided `taskId` to understand what the task involves.
+
+2. **Evaluate the task**: Consider:
+   - Does this task match your capabilities?
+   - Do you have the necessary context or access to complete it?
+   - Is the task description clear enough to proceed?
+
+3. **Make a decision**:
+   - **Accept**: If you can complete this task, call `task-action` with `action: "accept"` and `taskId: "<taskId>"`. Then immediately use `/skill:work-on-task <taskId>` to start working on it.
+   - **Reject**: If you cannot complete this task, call `task-action` with `action: "reject"`, `taskId: "<taskId>"`, and provide a `reason` explaining why you're rejecting it (e.g., "Task requires Python expertise which I don't have", "Task description is too vague").
+
+## Example Accept Flow
+
+```
+1. get-task-details taskId="abc-123"
+2. [Review the task details]
+3. task-action action="accept" taskId="abc-123"
+4. /skill:work-on-task abc-123
+```
+
+## Example Reject Flow
+
+```
+1. get-task-details taskId="abc-123"
+2. [Review the task details]
+3. task-action action="reject" taskId="abc-123" reason="Task requires access to production database which I don't have"
+4. Reply "DONE" to end the session
+```
+
+## Important Notes
+
+- Always provide a clear reason when rejecting a task - this helps the lead agent reassign it appropriately
+- If you accept, you must immediately start working on the task using `/skill:work-on-task`
+- If you reject, the task returns to the unassigned pool for reassignment