@desplega.ai/agent-swarm 1.85.0 → 1.86.0

package/templates/skills/x-api-interactions/content.md

@@ -0,0 +1,109 @@
+# X API Interactions (Twitter API v2)
+
+## Authentication
+
+Use OAuth 1.0a for all write operations (POST). Bearer tokens are read-only.
+
+Credentials are stored in swarm config:
+- `X_API_KEY` — Consumer key
+- `X_API_SECRET` — Consumer secret
+- `X_ACCESS_TOKEN` — Access token
+- `X_ACCESS_TOKEN_SECRET` — Access token secret
+
+Retrieve with `get-config` tool.
+
+## OAuth 1.0a Signing
+
+The Twitter API v2 requires OAuth 1.0a signature for POST requests. Use a library or construct manually:
+
+```bash
+# Using node with oauth-1.0a package
+node -e "
+const OAuth = require('oauth-1.0a');
+const crypto = require('crypto');
+
+const oauth = OAuth({
+  consumer: { key: process.env.X_API_KEY, secret: process.env.X_API_SECRET },
+  signature_method: 'HMAC-SHA1',
+  hash_function: (base, key) => crypto.createHmac('sha1', key).update(base).digest('base64')
+});
+
+const token = { key: process.env.X_ACCESS_TOKEN, secret: process.env.X_ACCESS_TOKEN_SECRET };
+const url = 'https://api.x.com/2/tweets';
+const method = 'POST';
+
+const auth = oauth.authorize({ url, method }, token);
+const header = oauth.toHeader(auth);
+console.log(header.Authorization);
+"
+```
+
+## Pre-Check: Conversation Restrictions (CRITICAL)
+
+Before attempting a reply, **always check the target tweet's reply_settings**:
+
+```bash
+curl -s "https://api.x.com/2/tweets/{TWEET_ID}?tweet.fields=reply_settings" \
+  -H "Authorization: Bearer $X_BEARER_TOKEN"
+```
+
+Response includes `reply_settings`:
+- `everyone` — Anyone can reply
+- `mentionedUsers` — Only mentioned users can reply (unless @desplegalabs is mentioned)
+- `following` — Only followers can reply (unless the author follows @desplegalabs)
+
+**If reply_settings is NOT "everyone", do NOT attempt the reply.** Report back that the tweet has conversation restrictions. Quote tweets may also be restricted on such tweets.
+
+## Posting a Tweet
+
+```bash
+curl -X POST "https://api.x.com/2/tweets" \
+  -H "Authorization: $OAUTH_HEADER" \
+  -H "Content-Type: application/json" \
+  -d '{"text": "Your tweet text"}'
+```
+
+## Posting a Reply
+
+```bash
+curl -X POST "https://api.x.com/2/tweets" \
+  -H "Authorization: $OAUTH_HEADER" \
+  -H "Content-Type: application/json" \
+  -d '{"text": "Your reply text", "reply": {"in_reply_to_tweet_id": "TWEET_ID"}}'
+```
+
+## Posting a Quote Tweet
+
+```bash
+curl -X POST "https://api.x.com/2/tweets" \
+  -H "Authorization: $OAUTH_HEADER" \
+  -H "Content-Type: application/json" \
+  -d '{"text": "Your quote text", "quote_tweet_id": "TWEET_ID"}'
+```
+
+## Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| **402 CreditsDepleted** | Monthly API credits exhausted | **STOP immediately.** Do NOT retry. Save generated content to agent-fs for later manual posting. Report to Slack. Mark task as failed. Taras must top up credits at developer.x.com. |
+| 403 Forbidden on reply | Conversation restrictions | Pre-check reply_settings |
+| 403 Forbidden on quote | Quote restrictions | Report back, don't retry |
+| 401 Unauthorized | Bad OAuth signature | Verify credentials, check timestamp |
+| 429 Too Many Requests | Rate limit | Wait and retry after reset time |
+
+**IMPORTANT: 402 CreditsDepleted is NOT retryable.** Both media-attached and text-only tweets fail with this error. Do not waste context trying alternative posting methods — the issue is account-level, not request-level.
+
+## Account Info
+
+- **Account:** @desplegalabs
+- **User ID:** 2027510506601488384
+
+## Workflow
+
+1. Get credentials from swarm config
+2. **Pre-check** target tweet's reply_settings (if replying)
+3. Construct OAuth 1.0a signature
+4. POST the tweet/reply/quote
+5. If 402, STOP — save content to agent-fs and report (credits depleted)
+6. If 403, report the restriction — do NOT retry blindly
+

package/templates/workflows/autopilot/config.json

@@ -0,0 +1,13 @@
+{
+  "kind": "workflow",
+  "name": "autopilot",
+  "displayName": "Autopilot Feature Pipeline",
+  "slug": "autopilot",
+  "title": "Autopilot Feature Pipeline",
+  "description": "Research, review, plan, implement, and verify a feature request through staged agents.",
+  "version": "1.0.0",
+  "category": "workflows",
+  "placeholders": ["REPO_URL"],
+  "runAllSeedersCandidate": true,
+  "tags": ["workflow", "implementation", "review"]
+}

package/templates/workflows/autopilot/content.md

@@ -0,0 +1,58 @@
+# Autopilot Feature Pipeline
+
+Use this workflow as a canonical feature delivery pipeline. Customize roles and checks for your swarm.
+
+```json
+{
+  "name": "Autopilot feature pipeline",
+  "description": "Research, plan, implement, and verify a feature request.",
+  "triggerSchema": {
+    "type": "object",
+    "required": ["request"],
+    "properties": {
+      "request": { "type": "string" },
+      "repoUrl": { "type": "string" }
+    }
+  },
+  "nodes": [
+    {
+      "id": "research",
+      "type": "agent-task",
+      "config": {
+        "role": "researcher",
+        "task": "Research this request for {{repoUrl}}: {{request}}. Return constraints, relevant files, risks, and suggested implementation approach."
+      },
+      "next": ["plan"]
+    },
+    {
+      "id": "plan",
+      "type": "agent-task",
+      "inputs": { "research": "research" },
+      "config": {
+        "role": "reviewer",
+        "task": "Create a focused implementation plan using the research output. Include files to touch, tests to run, and likely edge cases."
+      },
+      "next": ["implement"]
+    },
+    {
+      "id": "implement",
+      "type": "agent-task",
+      "inputs": { "plan": "plan" },
+      "config": {
+        "role": "coder",
+        "task": "Implement the plan for {{repoUrl}}. Keep the diff scoped, run relevant checks, and prepare a PR summary."
+      },
+      "next": ["verify"]
+    },
+    {
+      "id": "verify",
+      "type": "agent-task",
+      "inputs": { "implementation": "implement" },
+      "config": {
+        "role": "reviewer",
+        "task": "Review the implementation output. Verify tests/checks, identify residual risks, and recommend merge readiness."
+      }
+    }
+  ]
+}
+```

package/templates/workflows/linear-drain-loop/config.json

@@ -0,0 +1,21 @@
+{
+  "kind": "workflow",
+  "name": "linear-drain-loop",
+  "displayName": "Linear Drain Loop",
+  "slug": "linear-drain-loop",
+  "title": "Linear Drain Loop",
+  "description": "Break down a Linear parent issue and process ready child issues through workers.",
+  "version": "1.0.0",
+  "category": "workflows",
+  "placeholders": [
+    "LINEAR_PROJECT_ID",
+    "REPO_URL"
+  ],
+  "runAllSeedersCandidate": false,
+  "tags": [
+    "workflow",
+    "linear",
+    "triage"
+  ],
+  "must": true
+}

package/templates/workflows/linear-drain-loop/content.md

@@ -0,0 +1,72 @@
+# Linear Drain Loop
+
+A two-node issue-triage and dispatch workflow. The lead agent reviews child issues under a parent issue in Linear (or any tracker), categorizes them by readiness, and dispatches implementation tasks for those that are ready. Blocked or ambiguous items are surfaced for human review rather than auto-dispatched.
+
+## Configuration
+
+```json
+{
+  "name": "Linear drain loop",
+  "description": "Drain ready child issues from a parent issue.",
+  "triggerSchema": {
+    "type": "object",
+    "required": ["parentIssueKey"],
+    "properties": {
+      "parentIssueKey": { "type": "string" },
+      "projectId": { "type": "string" },
+      "repoUrl": { "type": "string" }
+    }
+  },
+  "nodes": [
+    {
+      "id": "triage",
+      "type": "agent-task",
+      "config": {
+        "role": "lead",
+        "task": "Review child issues under {{parentIssueKey}} in project {{projectId}}. Identify ready, blocked, duplicate, and needs-human-decision items."
+      },
+      "next": ["dispatch"]
+    },
+    {
+      "id": "dispatch",
+      "type": "agent-task",
+      "inputs": { "triage": "triage" },
+      "config": {
+        "role": "lead",
+        "task": "For ready items only, create or assign implementation tasks against {{repoUrl}}. Leave a tracker comment summarizing what was dispatched."
+      }
+    }
+  ]
+}
+```
+
+## What It Does
+
+A two-node pipeline:
+
+1. **Triage node (lead):** Reads all child issues under `parentIssueKey` in the given `projectId`. Classifies each as: ready (has acceptance criteria, unblocked), blocked (waiting on another issue or external dependency), duplicate (same scope as an existing issue), or needs-human-decision (ambiguous scope or missing spec).
+
+2. **Dispatch node (lead):** Takes the triage output and creates or assigns implementation tasks **only for ready items**. Posts a tracker comment summarizing what was dispatched and what was skipped.
+
+Blocked and ambiguous items are explicitly left alone — the dispatch node surfaces them in the comment for human follow-up rather than guessing.
+
+## When to Use
+
+- Weekly sprint grooming: run against a milestone or epic to drain everything that's ready
+- After a planning session: turn a batch of newly-specified issues into assigned tasks
+- Continuous drain: schedule this workflow daily against a backlog parent issue to keep work flowing automatically
+
+## Customization Notes
+
+- **`projectId`** is optional but strongly recommended — without it the triage agent may search the wrong project.
+- **`repoUrl`** is used by the dispatch node when creating implementation tasks. Pass the target repo where code changes will land.
+- **Add a notification node:** Extend with a third `agent-task` or `slack-post` node that pings a channel with the dispatch summary.
+- **Filter by label:** Modify the triage node's task prompt to only consider issues with a specific label (e.g., `"Only triage issues labelled 'ready-for-dev'"`) to avoid pulling in issues outside your sprint.
+
+## Trade-offs
+
+**Linear-specific prompt:** The triage and dispatch node tasks reference Linear concepts (issues, projects, comments). If your tracker is Jira or GitHub Issues, rephrase the task prompts — the workflow shape is tracker-agnostic but the agent prompts are not.
+
+**No iteration:** This is a single-pass drain. Issues that become ready after the run are not picked up until the workflow runs again. Pair with a daily schedule trigger for continuous drain.
+
+**Human-in-the-loop for ambiguous items:** By design, needs-human-decision items are not auto-dispatched. If your team wants a fully automated drain, strengthen the `ready` criteria in the triage prompt so fewer items land in the ambiguous bucket.

package/templates/workflows/ralph-loop/config.json

@@ -0,0 +1,13 @@
+{
+  "kind": "workflow",
+  "name": "ralph-loop",
+  "displayName": "Iterative Review Loop",
+  "slug": "ralph-loop",
+  "title": "Iterative Review Loop",
+  "description": "Run an implement-review-fix loop until verification passes or a human decision is needed.",
+  "version": "1.0.0",
+  "category": "workflows",
+  "placeholders": ["REPO_URL"],
+  "runAllSeedersCandidate": false,
+  "tags": ["workflow", "review", "iteration"]
+}

package/templates/workflows/ralph-loop/content.md

@@ -0,0 +1,75 @@
+# Iterative Review Loop
+
+A bounded implement → review loop. A coder agent implements the task and reports the diff; a reviewer agent checks it and returns PASS or a blocking fix list. Use this when you want automated quality control with a clear exit condition rather than open-ended implementation.
+
+## Configuration
+
+```json
+{
+  "name": "Iterative review loop",
+  "description": "Implement, review, and revise until accepted or blocked.",
+  "triggerSchema": {
+    "type": "object",
+    "required": ["task"],
+    "properties": {
+      "task": { "type": "string" },
+      "repoUrl": { "type": "string" },
+      "maxIterations": { "type": "number" }
+    }
+  },
+  "nodes": [
+    {
+      "id": "implement",
+      "type": "agent-task",
+      "config": {
+        "role": "coder",
+        "task": "Implement this task in {{repoUrl}}: {{task}}. Run focused checks and report the diff."
+      },
+      "next": ["review"]
+    },
+    {
+      "id": "review",
+      "type": "agent-task",
+      "inputs": { "implementation": "implement" },
+      "config": {
+        "role": "reviewer",
+        "task": "Review the implementation. Return PASS when ready, otherwise list blocking fixes only."
+      }
+    }
+  ]
+}
+```
+
+## What It Does
+
+A two-node implement → review loop:
+
+1. **Implement node (coder):** Takes the `task` description and `repoUrl`, produces a working implementation, runs focused checks (lint, types, relevant tests), and reports the diff.
+
+2. **Review node (reviewer):** Reads the implementation output, checks correctness and quality, and returns either `PASS` (implementation is accepted) or a list of blocking fixes only (no nitpicks — only what must change before this can ship).
+
+The `maxIterations` parameter is declarative: the reviewer signals PASS when done. The workflow engine handles the iteration ceiling.
+
+**Note:** In the current workflow schema, looping back is not native — the review node does not automatically re-trigger the implement node. To iterate, re-trigger the workflow with the reviewer's feedback as the new `task` input, or extend with a `workflow-iterate` skill pattern.
+
+## When to Use
+
+- Small, well-defined tasks where one round of review is usually sufficient
+- Automated code review before a PR is created — coder implements, reviewer checks
+- Pair-programming simulation: two agents, different roles, single pass
+- Quality gates on generated content (docs, configs, scripts) that need independent verification before delivery
+
+## Customization Notes
+
+- **`maxIterations`** is passed in but not natively enforced by the two-node shape. It's a hint to the agents — include it in the implement node's task prompt if you want the coder to self-limit attempts.
+- **Pin `agentId`** on the implement node to a coder-capable agent with repo access. Pin the review node to a reviewer-capable agent that can reason about code quality.
+- **Add a PR creation node:** Extend with a third agent-task node that takes the reviewer's PASS output and creates a pull request via `gh pr create`.
+- **Add structured output to the review node:** Use `outputSchema: { "type": "object", "properties": { "verdict": { "type": "string", "enum": ["PASS", "FAIL"] }, "fixes": { "type": "array" } } }` to make the verdict machine-readable for downstream automation.
+
+## Trade-offs
+
+**No native loop:** This workflow is a single implement → review pass. True multi-iteration requires re-triggering or a more complex DAG. Use the `workflow-iterate` skill if you need the lead agent to drive multiple rounds based on reviewer feedback.
+
+**Reviewer quality matters:** The review node's output is only as good as the reviewer agent's judgment. For high-stakes code, add a second reviewer node or route to a human-in-the-loop step before the PASS verdict is accepted.
+
+**Scope creep risk:** Coder agents sometimes expand scope beyond the `task` description. Constrain with explicit instructions: `"Only implement exactly what is described. Do not refactor surrounding code."`