@desplega.ai/agent-swarm 1.20.0 → 1.51.2

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

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

@@ -0,0 +1,261 @@
+---
+name: review-pr
+description: Review a pull request (GitHub) or merge request (GitLab) and provide detailed feedback
+---
+
+# Review Pull Request / Merge Request
+
+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
+
+- `pr-number-or-url`: Either a PR number (e.g., `123`) or a full GitHub PR URL (e.g., `https://github.com/owner/repo/pull/123`)
+
+## Workflow
+
+### 1. Parse the Input
+
+If given a URL, extract the owner, repo, and PR number. If given just a number, use the current repository context.
+
+### 2. Ensure Repository is Cloned Locally
+
+Before reviewing, make sure the repository is cloned in your personal workspace:
+
+```bash
+# Clone to your personal workspace
+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
+```
+
+### 3. Checkout the PR Branch
+
+```bash
+gh pr checkout <pr-number>
+```
+
+### 4. Fetch PR Details
+
+```bash
+gh pr view <pr-number> --json title,body,author,headRefName,baseRefName,additions,deletions,changedFiles
+```
+
+### 5. Get the Diff
+
+```bash
+gh pr diff <pr-number>
+```
+
+### 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 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
+
+### 9. Provide Structured Feedback
+
+Format your review as:
+
+```markdown
+## PR Review: <title>
+
+### Summary
+<Brief summary of what this PR does>
+
+### Findings
+
+#### Critical Issues
+<List any blocking issues that must be fixed>
+
+#### Suggestions
+<Non-blocking improvements to consider>
+
+#### Positive Notes
+<Good patterns or practices observed>
+
+### Verdict
+<APPROVE | REQUEST_CHANGES | COMMENT>
+
+<Overall recommendation>
+```
+
+### 10. Optionally Post the Review
+
+If the user wants to post the review to GitHub:
+
+```bash
+gh pr review <pr-number> --approve --body "Your review message"
+# or
+gh pr review <pr-number> --request-changes --body "Your review message"
+# or
+gh pr review <pr-number> --comment --body "Your review message"
+```
+
+### 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:
+
+#### Get the Commit SHA
+
+First, get the latest commit SHA for the PR head:
+
+```bash
+COMMIT_SHA=$(gh pr view <pr-number> --json headRefOid --jq '.headRefOid')
+```
+
+#### Post an Inline Comment
+
+Use `gh api` to post a comment on a specific line:
+
+```bash
+gh api repos/<owner>/<repo>/pulls/<pr-number>/comments \
+  --method POST \
+  -f commit_id="$COMMIT_SHA" \
+  -f path="src/path/to/file.ts" \
+  -f line=42 \
+  -f side="RIGHT" \
+  -f body="Your inline comment here explaining the issue or suggestion."
+```
+
+**Parameters:**
+- `commit_id`: The SHA of the commit to comment on (use the PR head commit)
+- `path`: The relative path to the file being commented on
+- `line`: The line number in the diff to attach the comment to
+- `side`: Use `"RIGHT"` for the new code (additions), `"LEFT"` for removed code
+- `body`: The comment text (supports markdown)
+
+#### Example: Multiple Inline Comments
+
+```bash
+# Get commit SHA once
+COMMIT_SHA=$(gh pr view 123 --json headRefOid --jq '.headRefOid')
+
+# Comment on a potential bug
+gh api repos/owner/repo/pulls/123/comments \
+  --method POST \
+  -f commit_id="$COMMIT_SHA" \
+  -f path="src/utils/validate.ts" \
+  -f line=15 \
+  -f side="RIGHT" \
+  -f body="This could throw if \`input\` is undefined. Consider adding a null check."
+
+# Comment on a security concern
+gh api repos/owner/repo/pulls/123/comments \
+  --method POST \
+  -f commit_id="$COMMIT_SHA" \
+  -f path="src/api/handler.ts" \
+  -f line=28 \
+  -f side="RIGHT" \
+  -f body="⚠️ SQL injection risk: Use parameterized queries instead of string interpolation."
+```
+
+### 12. Re-reviewing and Resolving Comments
+
+When the PR author makes changes in response to your review:
+
+#### Re-review After Changes
+
+Check for new commits and re-review the updated code:
+
+```bash
+# Fetch latest changes
+git fetch origin
+gh pr checkout <pr-number>
+
+# View commits since your last review
+gh pr view <pr-number> --json commits --jq '.commits[-3:]'
+
+# See the full updated diff
+gh pr diff <pr-number>
+```
+
+#### Follow Up on Previous Comments
+
+When re-reviewing:
+- Check if your previous concerns have been addressed
+- Resolve comment threads that are now fixed
+- Add follow-up comments if changes need further refinement
+
+```bash
+# View existing review comments on the PR
+gh api repos/<owner>/<repo>/pulls/<pr-number>/comments --jq '.[].body'
+
+# Reply to a specific comment thread
+gh api repos/<owner>/<repo>/pulls/<pr-number>/comments/<comment-id>/replies \
+  --method POST \
+  -f body="Thanks, this looks good now!"
+```
+
+#### Resolve Conversations (via GitHub UI)
+
+Comment threads are typically resolved through the GitHub web interface:
+- Navigate to the PR's "Files changed" tab
+- Click "Resolve conversation" on addressed comments
+- This keeps the review history clean and shows progress
+
+#### Update Your Review Status
+
+After re-reviewing, update your overall review status:
+
+```bash
+# If all issues are addressed
+gh pr review <pr-number> --approve --body "All feedback addressed. LGTM!"
+
+# If some issues remain
+gh pr review <pr-number> --request-changes --body "A few items still need attention - see comments."
+```
+
+## Tips
+
+- Focus on substantive issues, not style nitpicks
+- Be constructive and explain why something is a problem
+- Acknowledge good work when you see it
+- If changes look good, say so clearly
+- Having the repo cloned allows you to run tests and verify changes work