@desplega.ai/agent-swarm 1.85.0 → 1.86.0

package/templates/schedules/weekly-dependabot-triage/content.md

@@ -0,0 +1,45 @@
+# Weekly Dependency Triage
+
+Review dependency update PRs, group safe patches, and flag risky upgrades.
+
+## Schedule
+
+```json
+{
+  "cron": "40 3 * * 0",
+  "timezone": "UTC",
+  "agentRole": "lead",
+  "enabled": true
+}
+```
+
+## Scheduled Task
+
+This is the full task prompt the schedule runs on each fire — including the accumulated operational learnings baked into it. Adapt the swarm-specific references (channel IDs, agent names, repo paths) to your environment before enabling.
+
+Triage dependabot PRs from https://github.com/desplega-ai/desplega.ai/pulls
+
+## Instructions
+
+1. **List all open dependabot PRs** in desplega-ai/desplega.ai using `gh pr list`
+2. **Only paths we care about**: `/be` and `/new-fe`. Close all other dependabot PRs (ones that don't touch these paths).
+3. **DO NOT touch non-dependabot PRs** — leave them as-is.
+4. **Create two unified PRs** that merge all dependabot bumps into one PR each:
+   - One for `/be` changes — branch name format: `YYYY-MM-DD-dependabot-be` (use today's date)
+   - One for `/new-fe` changes — branch name format: `YYYY-MM-DD-dependabot-fe` (use today's date)
+   - Each unified PR should be based on latest `main` and include all the dependency bumps from the individual dependabot PRs for that path.
+   - After creating the unified PRs, close the individual dependabot PRs that were merged into them.
+5. **Return the URLs** of the two final unified PRs.
+6. If there are no open dependabot PRs, just report that and complete.
+
+## Approach
+
+- Clone the repo, checkout main, pull latest
+- For each path (be, new-fe): create a branch, cherry-pick or merge the dependabot changes, push, create PR
+- Close individual dependabot PRs after unifying
+- Be careful: some dependabot PRs may have conflicts — handle gracefully
+
+## Important
+- The PR title should be descriptive, e.g. "chore(be): consolidate dependabot bumps YYYY-MM-DD"
+- Add @tarasyarema as reviewer on both PRs
+- Post the final PR URLs back to Slack

package/templates/schema.ts

@@ -35,3 +35,29 @@ export interface TemplateResponse {
     heartbeatMd: string;
   };
 }
+
+export type AgentAssetKind = "skill" | "schedule" | "workflow";
+export type AgentAssetCategory = "skills" | "schedules" | "workflows";
+
+export interface AgentAssetConfig {
+  kind: AgentAssetKind;
+  name: string;
+  displayName: string;
+  slug: string;
+  title: string;
+  description: string;
+  version: string;
+  category: AgentAssetCategory;
+  placeholders: string[];
+  runAllSeedersCandidate: boolean;
+  /** Marks an asset as an essential, recommended-for-every-swarm building block. */
+  must?: boolean;
+  tags: string[];
+}
+
+export interface AgentAssetResponse {
+  config: AgentAssetConfig;
+  body: string;
+}
+
+export const ASSET_CATEGORIES: AgentAssetCategory[] = ["skills", "schedules", "workflows"];

package/templates/skills/agentmail-sending/config.json

@@ -0,0 +1,13 @@
+{
+  "kind": "skill",
+  "name": "agentmail-sending",
+  "displayName": "AgentMail Sending",
+  "slug": "agentmail-sending",
+  "title": "AgentMail Sending",
+  "description": "Generic rules for sending email through an agent-accessible mailbox API.",
+  "version": "1.0.0",
+  "category": "skills",
+  "placeholders": ["COMPANY_SIGNATURE"],
+  "runAllSeedersCandidate": false,
+  "tags": ["email", "communications"]
+}

package/templates/skills/agentmail-sending/content.md

@@ -0,0 +1,48 @@
+# AgentMail Sending Rules
+
+These rules are MANDATORY for all agents sending email via AgentMail. Violating them will result in blank emails reaching real people.
+
+## Rule 1: TEXT ONLY — Never Pass `html` Parameter
+
+**AgentMail has a critical bug (as of 2026-03-25):** When both `text` and `html` parameters are passed to `send_message` or `reply_to_message`, the HTML body content is silently dropped. The resulting email has an empty `<div dir="ltr"></div>`. Email clients (Gmail, etc.) prefer the HTML version over plain text, so recipients see a completely blank email.
+
+**What to do:**
+- ONLY pass the `text` parameter
+- NEVER pass the `html` parameter
+- This applies to BOTH `send_message` and `reply_to_message`
+
+**Why this matters:** This bug caused real outbound prospect emails to arrive blank, burning contacts permanently. It is not a cosmetic issue — it's a data loss / reputation issue.
+
+## Rule 2: Always BCC t@desplega.ai on Outbound Emails
+
+All outbound emails to external recipients (anyone outside @agent-swarm.dev) MUST include `t@desplega.ai` as BCC. This gives the human founder visibility into what emails the swarm is sending.
+
+**How:**
+```
+send_message({
+  inboxId: "lead@agent-swarm.dev",
+  to: ["recipient@example.com"],
+  bcc: ["t@desplega.ai"],
+  subject: "...",
+  text: "..."
+})
+```
+
+**Exception:** Internal emails between agent inboxes (@agent-swarm.dev) or to t@desplega.ai / e@desplega.ai directly do NOT need BCC.
+
+## Rule 3: Always Include Signature
+
+Use the `email-signature` skill to append the proper plain text signature to every outgoing email. See that skill for the template.
+
+## Rule 4: Human Approval Before Sending to Prospects
+
+Never send outreach/cold emails to external prospects without explicit human approval. Draft the emails, present them for review, and only send after receiving "approved" or equivalent confirmation.
+
+## Summary Checklist
+
+Before every `send_message` or `reply_to_message` call:
+- [ ] Only `text` param, NO `html` param
+- [ ] BCC `t@desplega.ai` if recipient is external
+- [ ] Plain text signature appended
+- [ ] Human-approved if it's outreach/cold email
+

package/templates/skills/artifacts/config.json

@@ -0,0 +1,13 @@
+{
+  "kind": "skill",
+  "name": "artifacts",
+  "displayName": "Artifacts",
+  "slug": "artifacts",
+  "title": "Artifacts",
+  "description": "Store logs, screenshots, exports, and generated files as durable task artifacts.",
+  "version": "1.0.0",
+  "category": "skills",
+  "placeholders": [],
+  "runAllSeedersCandidate": true,
+  "tags": ["artifacts", "evidence", "qa"]
+}

package/templates/skills/artifacts/content.md

@@ -0,0 +1,87 @@
+# Artifacts
+
+Artifacts are files, screenshots, recordings, logs, and reports that outlive a session and can be referenced by other agents, humans, or future tasks. The agent-swarm supports two artifact stores: **agent-fs** (structured, searchable, shareable) and the **shared workspace filesystem** (`/workspace/shared/`).
+
+## When to Create Artifacts
+
+- Your task produces a deliverable humans should review (report, screenshot, recording, data export).
+- Another agent or future session needs to pick up where you left off.
+- You want to attach evidence to a PR, Linear ticket, or Slack message.
+- The output is too large for `store-progress.output`.
+
+## Agent-fs (Preferred for Human-Shareable Artifacts)
+
+agent-fs is a persistent, searchable file system shared across the swarm.
+
+```bash
+# Write to personal drive
+agent-fs write thoughts/research/2026-05-28-topic.md --content "..." -m "description"
+
+# Write to shared drive (humans + other agents can see)
+agent-fs --org 648a5f3c-35c8-4f11-8673-b89de52cd6bd write \
+  thoughts/c06cca59-187e-4aa6-8472-8ac6caf177af/research/2026-05-28-topic.md \
+  --content "..." -m "research findings"
+```
+
+Verify the write succeeded (agent-fs writes can fail silently with empty payloads):
+```bash
+agent-fs stat <path> --json | jq '.size'
+# If size < 200 bytes on a non-trivial artifact, the write FAILED — re-do it.
+```
+
+### Sharing agent-fs files with humans
+
+Build the URL from the live host env var:
+```
+${AGENT_FS_LIVE_URL}/file/~/<org_id>/<drive_id>/<file_path>
+```
+
+`AGENT_FS_LIVE_URL` defaults to `https://live.agent-fs.dev`. Get `org_id` and `drive_id` from `agent-fs stat <path> --json`.
+
+## Shared Filesystem
+
+For non-text artifacts or files other agents need to access during the same session:
+
+- `/workspace/shared/downloads/<agent-id>/` — downloaded files
+- `/workspace/shared/misc/<agent-id>/` — other shared files
+
+## Binary Artifacts (PNG, MP4)
+
+**agent-fs write is text-only and mangles binaries** (inserts UTF-8 replacement characters). For PNG/MP4 uploads use the binary upload path:
+
+```bash
+# Use binary-safe upload, NOT agent-fs write
+# For QA screenshots: use qa-use's built-in screenshot capture
+# For custom screenshots: Playwright, ffmpeg, or system screenshot tools
+```
+
+For QA screenshots attached to PRs, see the QA evidence convention in TOOLS.md.
+
+## Naming Conventions
+
+Name paths predictably by task, date, and artifact type:
+
+```
+thoughts/<agent-id>/research/YYYY-MM-DD-<topic>.md
+thoughts/<agent-id>/plans/YYYY-MM-DD-<topic>.md
+thoughts/<agent-id>/qa/<topic>-screenshots/<filename>.png
+misc/<agent-id>/<task-id>-<description>.ext
+```
+
+## Attaching Artifacts
+
+- **PR body:** Embed `![caption](live.agent-fs.dev/file/~/...)` image URLs as markdown.
+- **Slack messages:** Link to agent-fs URLs (they're public, no auth required).
+- **`store-progress`:** Use the `attachments` field with `kind: "agent-fs"` and the path.
+- **Linear comments:** Paste the live.agent-fs.dev URL in the comment body.
+
+## What NOT to Store in Artifacts
+
+- Secrets, API keys, OAuth tokens
+- Raw customer data without approval
+- Oversized files without approval (check file size before uploading)
+- Ephemeral progress notes (put those in `store-progress.progress` instead)
+
+## Trade-offs
+
+**agent-fs vs shared filesystem:** agent-fs is persistent, versioned, and searchable across sessions. The shared filesystem is faster for same-session handoffs between agents but doesn't survive container restarts. Use agent-fs for anything that needs to outlive the current session or be reviewed by humans.

package/templates/skills/browser-use-cloud/config.json

@@ -0,0 +1,13 @@
+{
+  "kind": "skill",
+  "name": "browser-use-cloud",
+  "displayName": "Browser Use Cloud",
+  "slug": "browser-use-cloud",
+  "title": "Browser Use Cloud",
+  "description": "Run browser automation tasks with bounded polling and explicit artifacts.",
+  "version": "1.0.0",
+  "category": "skills",
+  "placeholders": ["BROWSER_USE_API_KEY"],
+  "runAllSeedersCandidate": false,
+  "tags": ["browser", "automation", "qa"]
+}

package/templates/skills/browser-use-cloud/content.md

@@ -0,0 +1,155 @@
+# Browser Use Cloud (universal IP-block / web-UI workaround)
+
+The swarm container runs on a datacenter IP. A lot of public sites — YouTube,
+Cloudflare-protected pages, login walls — block that IP outright. When direct
+HTTP (curl, WebFetch, yt-dlp, `youtube-transcript-api`) returns a bot
+challenge or a JS-only shell, the cleanest fallback is **Browser Use Cloud**
+— a hosted real-browser service that runs an LLM-driven agent inside Chrome.
+It loads pages, clicks things, scrolls, reads the DOM, and returns the
+extracted content as text. Different IP, full JS, real browser fingerprint.
+
+## When to use this vs. alternatives
+
+| Situation | Use this? |
+|---|---|
+| YouTube transcript / metadata | **Yes.** YouTube blocks the swarm IP for `yt-dlp`, `youtube-transcript-api`, and the free transcript sites (Cloudflare). Browser Use is the only path without cookies. |
+| Cloudflare-protected site (`youtubetranscript.com`, `youtubetotranscript.com`, similar) | **Yes.** WebFetch returns the JS challenge HTML. Browser Use solves the challenge automatically. |
+| Login-walled content the user authorizes you to access | **Yes** — pass the credentials in the task prompt; Browser Use can fill forms. |
+| Plain server-rendered HTML | **No.** Use `curl` / WebFetch — Browser Use is overkill and ~$0.05+/task. |
+| Site has a public API or RSS | **No.** Always prefer the API. |
+| `steipete/summarize` on a non-IP-blocked URL | **No.** Use summarize directly — it's free and faster. |
+
+`steipete/summarize` is installed in the swarm (`npm i -g @steipete/summarize`)
+and works fine for non-IP-blocked URLs and local files. It fails on YouTube
+from the swarm because every YouTube-extraction path it uses (`web` caption
+fetch, `yt-dlp` audio download, `apify` if no token) hits the same datacenter
+IP wall.
+
+## Auth & base URL
+
+- **Base URL:** `https://api.browser-use.com/api/v2`
+- **Auth header:** `X-Browser-Use-API-Key: <key>` (NOT `Authorization: Bearer`
+  — that returns 404 on all endpoints, easy time-sink)
+- **Stored in swarm config:** key `BROWSER_USE_API_KEY` (global, secret).
+  Fetch via `get-config key=BROWSER_USE_API_KEY includeSecrets=true`.
+
+## Core endpoints
+
+| Endpoint | Purpose |
+|---|---|
+| `POST /api/v2/tasks` | Create a task. Body: `{"task": "<natural-language instructions>"}`. Returns `{id, sessionId}`. |
+| `GET /api/v2/tasks/{id}` | Poll status + output. Fields: `status` (`started` → `finished` / `failed`), `steps[]`, `output` (the agent's final answer as a string). |
+| `GET /api/v2/tasks` | List recent tasks (useful to inspect prior runs / patterns). |
+
+The v1 endpoints (`/api/v1/...`) return `{"detail":"Not Found"}` — **always
+use v2**.
+
+## Quickstart — YouTube transcript
+
+```bash
+K=$(swarm-get-config BROWSER_USE_API_KEY)   # or pull via get-config MCP tool
+
+# 1. Create the task
+TASK=$(curl -s -X POST "https://api.browser-use.com/api/v2/tasks" \
+  -H "X-Browser-Use-API-Key: $K" \
+  -H "Content-Type: application/json" \
+  -d '{"task":"Open https://www.youtube.com/watch?v=VIDEO_ID . Dismiss any cookie/consent dialog. Note the video title and channel name. Open the transcript: click \"...more\" in the description, then click \"Show transcript\" (or use the three-dot menu under the video and choose \"Show transcript\"). The transcript panel will appear on the right. Scroll the transcript panel fully to the bottom so every line loads. Then extract and output the COMPLETE transcript text verbatim, all lines, in order. Also output the video title and channel at the top."}')
+
+TASK_ID=$(echo "$TASK" | jq -r .id)
+echo "task: $TASK_ID"
+
+# 2. Poll until finished (typical: 2-4 minutes for a ~15min video)
+while true; do
+  R=$(curl -s "https://api.browser-use.com/api/v2/tasks/$TASK_ID" \
+    -H "X-Browser-Use-API-Key: $K")
+  S=$(echo "$R" | jq -r .status)
+  echo "$(date +%H:%M:%S) status=$S steps=$(echo "$R" | jq '.steps | length')"
+  [ "$S" = "finished" ] || [ "$S" = "failed" ] && break
+  sleep 30
+done
+
+# 3. Extract output — note: \n in the JSON is the literal two chars "\\n",
+#    not a newline. Unescape before writing to disk.
+echo "$R" | jq -r '.output' | python3 -c "import sys; sys.stdout.write(sys.stdin.read().replace('\\\\n','\n'))" \
+  > /workspace/personal/tmp/transcript.md
+```
+
+**Polling cadence:** 30s is plenty. A 10-15min YouTube video transcript run
+takes ~2-4 min and ~15-20 agent steps. Don't busy-poll faster — every poll
+costs a request and Browser Use rate-limits aggressively.
+
+## Writing good task prompts
+
+The Browser Use agent is an LLM driving a browser — it follows instructions
+literally and sometimes loops if the page changes mid-task. Give it:
+
+1. **Exact start URL** — full `https://...` link, not "search for X".
+2. **Pre-emptive dismissals** — "Dismiss any cookie/consent dialog" prevents
+   it from getting stuck on EU cookie banners.
+3. **A concrete click path** with fallbacks — `"click 'Show transcript' (or
+   use the three-dot menu under the video and choose 'Show transcript')"` —
+   sites move things around; give it two ways.
+4. **Explicit scroll instructions** for lazy-loaded content — `"scroll the
+   transcript panel fully to the bottom so every line loads"`. Without this
+   you get the first ~50 lines and silent truncation.
+5. **The exact output format** — `"output the COMPLETE transcript text
+   verbatim, all lines, in order"`. If you want JSON, say "respond with valid
+   JSON only, no prose".
+6. **Don't ask it to summarize** unless that's the goal. You want the raw
+   content; do the LLM work yourself in a separate step with full control of
+   the model.
+
+## Output shape gotchas
+
+- `output` is a **single string**. Multi-line content has `\n` *escaped as
+  two characters* inside that string (because the API returns JSON). When you
+  pipe to a file, unescape with `replace('\\n', '\n')` or `printf '%b'` —
+  otherwise the file looks like one giant line of `\n[0:01]...\n[0:03]...`.
+- `steps` is an array of `{action, nextGoal, ...}` — useful for debugging a
+  failed run, ignore on success.
+- If `status: failed`, look at the last step's `error` field. Common cause:
+  the agent couldn't find the click target (page changed, A/B test, region
+  variation) — refine the click path and re-run.
+
+## Cost & limits
+
+- **Paid per task.** Roughly $0.05-$0.15 per task in practice; longer tasks
+  with more steps cost more. Don't loop this; use it once you've actually
+  hit a block.
+- **Rate-limited.** Don't fire >1 task per ~10s.
+- **No streaming.** You always poll for the final `output`.
+
+## Worked example (the one that prompted this skill)
+
+Task: get the transcript for `https://www.youtube.com/watch?v=t-G67yKAHBQ`.
+
+What failed first:
+- `yt-dlp` (all `--extractor-args "youtube:player_client=..."` variants: `tv`,
+  `ios`, `web_safari`, `mweb`, `android`): all returned "Sign in to confirm
+  you're not a bot".
+- `youtube-transcript-api` (Python lib): `RequestBlocked` — same IP issue.
+- `summarize "<url>" --extract --youtube web|auto|yt-dlp`: failed too — its
+  `web` mode hits YouTube's HTML directly (gets the JS shell footer), and
+  `yt-dlp` mode chains the same blocked tool.
+- `curl` + `WebFetch` against `youtubetranscript.com` /
+  `youtubetotranscript.com` / `tactiq`: Cloudflare interstitial / App Check
+  rejection / 403.
+
+What worked:
+- One Browser Use Cloud task with the prompt above. ~17 steps, ~3 min,
+  returned a clean 17.7 KB timestamped transcript ("How to Build a
+  Self-Improving Company with AI", YC Root Access).
+
+## Tips
+
+- **Always save the `output` to a file under `/workspace/...`** before
+  uploading to Slack — `slack-upload-file` will not read `/tmp/`. Use
+  `/workspace/personal/tmp/` or `/workspace/shared/misc/<your-agent-id>/`.
+- **For long videos** (>1h), warn the user this takes ~10 min and costs more
+  per run. Consider chunking by timestamp range if you only need part of it.
+- **For non-YouTube sites**, the same recipe applies — just change the URL
+  and the click path. Browser Use is the swarm's general "I need a real
+  browser" tool.
+- **Don't store the API key in scripts you commit.** Pull it fresh from
+  `get-config` each run.
+

package/templates/skills/desloppify/config.json

@@ -0,0 +1,13 @@
+{
+  "kind": "skill",
+  "name": "desloppify",
+  "displayName": "Code Health Scan",
+  "slug": "desloppify",
+  "title": "Code Health Scan",
+  "description": "Run a multi-language code health scan and publish prioritized findings.",
+  "version": "1.0.0",
+  "category": "skills",
+  "placeholders": ["REPO_URL"],
+  "runAllSeedersCandidate": false,
+  "tags": ["code-quality", "audit", "reporting"]
+}

package/templates/skills/desloppify/content.md

@@ -0,0 +1,201 @@
+# desloppify — Code-health scan workflow (swarm edition)
+
+`desloppify` is a multi-language codebase health scanner (peteromallet/desloppify). This skill is the swarm-adapted SKILL.md: it codifies the **install recipe with the tree-sitter pin**, the surface-only **scan → status → next → triage** workflow we run for repos like `agent-swarm`, and the **publish-to-agent-fs** step so humans (Eze) can see the findings.
+
+> **Default mode for swarm workers: surface-only.** Run Phase 1 + early Phase 2, publish a memo to agent-fs, stop. Do **not** run Phase 3 (queue-grinding refactors) unless the task explicitly asks.
+
+## When to use this skill
+
+- A task asks you to run desloppify, do a code-health scan, get a health score, or surface debt themes on a repo.
+- A task references `peteromallet/desloppify` or the upstream `docs/SKILL.md`.
+- You need to triage tech debt on a TS / Python / multi-lang repo (agent-swarm, landing, agent-swarm-landing, desplega-ai, etc.).
+
+If the task is "fix this one bug" or "rename X" → not this skill. Desloppify is for batch debt-surfacing, not point fixes.
+
+## Step 1 — Detect
+
+```bash
+command -v desloppify >/dev/null 2>&1 && desloppify --version || echo "NOT INSTALLED"
+```
+
+If `--version` prints cleanly, **also verify the tree-sitter pin** (a busted pin is worse than no install — the scan crashes mid-run):
+
+```bash
+pipx runpip desloppify show tree-sitter-language-pack | grep Version
+# Expect: Version: 1.6.2 (or anything < 1.8)
+# If 1.8.x → see Step 3 (re-pin).
+```
+
+## Step 2 — Install (first run only)
+
+Use `pipx`. This is the working recipe verified in PR #463 (Dockerfile.worker) and across multiple sprite smokes:
+
+```bash
+pipx install 'desloppify[full]==0.9.15'
+pipx inject --force desloppify 'tree-sitter-language-pack<1.8'
+
+# Verify the pin landed:
+pipx runpip desloppify show tree-sitter-language-pack | grep Version
+# → must show 1.6.2 (or another <1.8)
+```
+
+**Why the pin:** `tree-sitter-language-pack` 1.8.0 has an ABI mismatch with `tree-sitter` that crashes desloppify in `cohesion.py:52` → `extractors.py:90` with a `TypeError`. Upstream fix is [peteromallet/desloppify#605](https://github.com/peteromallet/desloppify/pull/605) — open, unmerged. Until that ships, we cap locally. (See task `616b4bba-43de-40b5-af3b-4e219b622218` for the full repro.)
+
+If `pipx` isn't installed: `python3 -m pip install --user pipx && python3 -m pipx ensurepath` and start a new shell. If `pipx install` fails with build errors, jump to **Sprite escape hatch** below.
+
+## Step 3 — Re-pin (installed but broken)
+
+If desloppify is on PATH but `tree-sitter-language-pack` is ≥ 1.8, you do **not** need a full reinstall:
+
+```bash
+pipx inject --force desloppify 'tree-sitter-language-pack<1.8'
+pipx runpip desloppify show tree-sitter-language-pack | grep Version
+```
+
+The `--force` is required — without it pipx refuses to downgrade. Confirm the version drops, then scan.
+
+## Step 4 — Scan
+
+Clone or `cd` into the target repo. For TS repos you usually don't need `node_modules` for the scan, but if a finding requires resolving imports, run `bun install` (or `npm install`) first.
+
+**Monorepo note:** if the repo has multiple programs in sibling folders (e.g. `frontend/`, `backend/`), scan each separately — never scan the parent:
+
+```bash
+desloppify --lang typescript scan --path ./frontend
+desloppify --lang python      scan --path ./backend
+```
+
+Single-program repo:
+
+```bash
+desloppify scan --path .
+```
+
+Capture **exit code**, **duration**, and any warnings. A clean run is exit 0 with no traceback. Typical scan time: 30–90s for ~200K LOC.
+
+## Step 5 — Status + next + triage
+
+```bash
+desloppify status                          # overall / strict / objective / verified scores + dimension health
+desloppify next --count 15                 # top-priority execution items (cluster-aware)
+desloppify show --status open --count 50   # broader open backlog if you want to slice manually
+```
+
+What to capture for the memo:
+
+- **Status snapshot** — overall, strict, objective, verified scores. Note if subjective is at 0% (unassessed) — that means the strict number is a measurement artifact, not a reflection of reality.
+- **Item counts by detector** — `desloppify status` shows this. Look for which detectors dominate (test_coverage, smells, duplication, security, orphaned, …).
+- **Top 10–15 findings** from `next` — identifier · kind · severity · the one-line "why".
+- **Your themes** (2–4 bullets) — what jumps out across the findings. E.g. "godfile in src/be/db.ts", "MCP-tool boilerplate dup cluster", "UI mega-pages with 20+ hooks". Use your own read, not `desloppify plan triage --complete`.
+- **Phase 3 candidates** (2–3) — what you'd nominate to actually grind, if asked.
+- **False positives** — anything desloppify flagged that's actually intentional in the swarm context (CLI entrypoints, deferred-registration MCP tools, dynamically loaded plugins, sanity fixtures, etc.).
+
+**Do not** run `desloppify plan triage --complete`, `desloppify plan commit-log record`, or any Phase 3 commands in surface-only mode. Those mutate desloppify's local state and create commitments we don't intend to follow through on.
+
+## Step 6 — Publish findings to agent-fs
+
+Save the scan memo so Eze and the swarm can see it. Use the shared org (`648a5f3c-35c8-4f11-8673-b89de52cd6bd`) and namespace the path under your own agent ID:
+
+```bash
+DATE=$(date +%Y-%m-%d)
+agent-fs --org 648a5f3c-35c8-4f11-8673-b89de52cd6bd write \
+  thoughts/$AGENT_ID/research/$DATE-desloppify-<repo>-scan.md \
+  --content "$(cat <<'EOF'
+# desloppify scan — <repo> @ <SHA>
+
+## Install + scan
+- recipe: pipx install desloppify[full]==0.9.15 + tree-sitter pin
+- exit: 0 / duration: 47s / 919 files / 210K LOC
+
+## Status
+overall <N>/100 · strict <N>/100 · objective <N>/100 · verified <N>/100
+dimension health: File X% · Code Y% · Dup Z% · Security S% · Test T%
+
+## Top 10–15 findings
+- src/be/db.ts · godfile · T1 · 9441 LOC / complexity 457 / 48 issues
+- ...
+
+## Themes
+1. ...
+2. ...
+
+## Phase 3 candidates
+1. Split src/be/db.ts by domain
+2. ...
+
+## False positives (don't act on)
+- src/cli.tsx (CLI entrypoint)
+- ...
+EOF
+)" -m "desloppify scan memo for <repo>"
+```
+
+Also drop a private copy at `/workspace/personal/memory/desloppify-<repo>-scan-$DATE.md` so it's indexed for future memory-search.
+
+## Step 7 — Slack reply (if the task came from Slack)
+
+Single concise reply on the originating thread (use `slack-reply` with your taskId). Include:
+
+- ✅/❌ + scan exit + duration
+- Status snapshot (overall / strict / objective / dimension health)
+- Top themes (2–4 bullets)
+- Phase 3 candidates (2–3)
+- agent-fs path to the full memo
+- False positives flagged
+
+**Slack block limit is 3000 chars per message.** If your reply trips `invalid_blocks`, split into Part 1 / Part 2. Don't try to cram everything into one message — readability > brevity.
+
+## Sprite escape hatch — when local pipx is broken
+
+If `pipx install` fails (system-package conflicts, missing build deps, weird Python ABI), or your worker container's desloppify install is corrupt and re-pinning doesn't help, **spin a fresh sprite** instead of fighting the local env. See the `sprite-cli` skill for full details.
+
+```bash
+sprite create desloppify-scan
+sprite exec -s desloppify-scan -- bash -c '
+  set -e
+  sudo apt-get update -qq
+  sudo apt-get install -y pipx python3-venv git
+  pipx ensurepath
+  export PATH="$HOME/.local/bin:$PATH"
+  pipx install "desloppify[full]==0.9.15"
+  pipx inject --force desloppify "tree-sitter-language-pack<1.8"
+  pipx runpip desloppify show tree-sitter-language-pack | grep Version
+  git clone --depth=1 https://github.com/desplega-ai/<repo>.git /tmp/repo
+  cd /tmp/repo
+  desloppify scan --path .
+  desloppify status
+  desloppify next --count 15
+'
+# … capture output, then:
+sprite destroy desloppify-scan --force
+```
+
+**Always destroy the sprite when done.** Sprites are paid resources.
+
+## Stop conditions
+
+- If desloppify crashes despite a verified `<1.8` pin → STOP, paste the traceback, escalate. Don't bisect tree-sitter versions further.
+- If the scan produces 0 findings → suspect a `--path` problem (you may be scanning a parent dir of a monorepo). Re-scan with explicit per-program paths.
+- If the worker is asked to "fix the findings" → that's Phase 3. Confirm scope with the requester before doing it — Phase 3 is queue-grinding refactors and we historically do *not* default to it.
+
+## Quick reference (cheat sheet)
+
+```bash
+# Detect + install (idempotent)
+command -v desloppify || { pipx install 'desloppify[full]==0.9.15' && pipx inject --force desloppify 'tree-sitter-language-pack<1.8'; }
+pipx runpip desloppify show tree-sitter-language-pack | grep Version  # must be <1.8
+
+# Surface workflow
+desloppify scan --path .
+desloppify status
+desloppify next --count 15
+
+# Publish + report
+agent-fs --org 648a5f3c-35c8-4f11-8673-b89de52cd6bd write thoughts/$AGENT_ID/research/$(date +%F)-desloppify-<repo>-scan.md --content "..." -m "scan memo"
+# slack-reply on the originating thread
+```
+
+## Upstream reference
+
+Full Phase 3 / review workflow / plan commands are in the upstream SKILL.md: <https://github.com/peteromallet/desloppify/blob/main/docs/SKILL.md>. Reach for it when you're explicitly asked to grind the queue (rare). Default swarm mode stops after the memo + Slack reply.
+

package/templates/skills/exa-search/config.json

@@ -0,0 +1,13 @@
+{
+  "kind": "skill",
+  "name": "exa-search",
+  "displayName": "Exa Search",
+  "slug": "exa-search",
+  "title": "Exa Search",
+  "description": "Use web search APIs for cited research without over-fetching irrelevant pages.",
+  "version": "1.0.0",
+  "category": "skills",
+  "placeholders": ["EXA_API_KEY"],
+  "runAllSeedersCandidate": false,
+  "tags": ["research", "search", "web"]
+}