@desplega.ai/agent-swarm 1.148.0 → 1.149.0

package/templates/skills/comms/config.json

@@ -0,0 +1,18 @@
+{
+  "category": "skills",
+  "description": "Re-express something so it lands — re-explain your last reply in plain casual language, show the current topic visually (diagram, code-shape sketch, HTML artifact), do both at once, or rewrite artifact text into unambiguous ASD-STE100 English. Use when the user runs /desplega:comms, types /bro, says 'say it simpler', 'bro what', 'I don't follow', 'show me', 'draw this', 'visualize', 'disambiguate this', or 'STE100 rewrite'. Not for creative or marketing copy.",
+  "displayName": "Comms",
+  "kind": "skill",
+  "name": "comms",
+  "placeholders": [],
+  "runAllSeedersCandidate": true,
+  "slug": "comms",
+  "systemDefault": true,
+  "tags": [
+    "ai-toolbox",
+    "agents",
+    "workflow"
+  ],
+  "title": "Comms",
+  "version": "1.0.0"
+}

package/templates/skills/comms/content.md

@@ -0,0 +1,74 @@
+# /comms — make it land
+
+Merged from three MIT sources: [bro-skill](https://github.com/luchasarie/bro-skill) (Simpler), the local show-me skill (Visual), and [asd-ste100-skill](https://github.com/desplega-ai/asd-ste100-skill) (Precise).
+
+One skill, three base modes plus a joint one. Pick from the **target** of the request, not from the wording alone.
+
+## Dispatch
+
+| Target of the request | Mode |
+|---|---|
+| Your own previous message — "simpler", "bro what", "didn't get it", "rephrase" | **Simpler** |
+| A concept, flow, architecture, or change — "show me", "draw", "diagram", "what does this look like" | **Visual** |
+| Your previous message AND it describes structure (a flow, a tree, an architecture, a sequence) — or the user asks for both ("simpler, and draw it") | **Joint** |
+| Artifact text a machine or reader must parse without a back-channel — tool description, error message, prompt, doc paragraph — "disambiguate", "rewrite", "STE" | **Precise** |
+
+Dispatch rules:
+
+- If the request names a mode, obey it.
+- If the target is your previous message and it is plain prose, use Simpler. If it describes structure, prefer Joint — a small visual usually lands faster than more words.
+- Never mix registers: no casual flavor in Precise output, no STE flatness in Simpler output. Precise never combines with the other modes.
+- If there is nothing to re-express (no previous message, no artifact, no topic), say so in one line.
+
+## Mode: Simpler
+
+Re-explain YOUR most recent assistant message like you're explaining it to a smart friend over a beer.
+
+1. **Re-explain, don't re-answer.** Never answer a new question, never add new information, never use tools. You are only re-expressing what you already said.
+2. **Simpler, not necessarily shorter.** The goal is "impossible to misunderstand", not "fewer words". Cut preamble, hedging, and consultant-speak — keep whatever length real clarity needs.
+3. **Facts survive verbatim.** Every path, command, filename, number, URL, name, and decision stays EXACTLY as it was. Simplify the explanation around the facts, never the facts themselves.
+4. **Light casual flavor.** Direct and informal ("basically...", "the point is...", "ok so..."). A touch of personality — don't turn it into a meme.
+5. **Same language.** If the original message was in another language, the simpler version stays in that language.
+6. **Flatten structure.** Drop headers and ceremony. Tables become plain sentences. Keep a short list only if the original genuinely had multiple parts.
+
+## Mode: Visual
+
+Help the user understand the current topic visually. Skip the preamble and keep prose brief. Pick the smallest view that makes the key point clear:
+
+- **Pseudocode** for logic or an algorithm.
+- **Call tree** for runtime control flow.
+- **Component tree** for UI structure, including the state and module boundaries that matter.
+- **Shallow file tree** for file responsibility or a broad refactor.
+- **Mermaid** for component interaction, control flow, or data flow.
+- **`diff`** when the point is what changes and the surrounding shape already exists — diff the tree or pseudocode itself, not raw code. Match the diff shape to the topic.
+- **Whole code block** when most of it is new, when omitted context would hide ownership or order, or when the user needs a copyable target shape.
+- **One focused HTML file** for a visual UI, layout, state comparison, or concept too dense for Mermaid — a diagram, infographic, or short slide deck. Match the product's colors, type, spacing, and components; use real labels and data; support desktop and mobile. Then `Bash(open path/to/comms-{description}.html)`.
+
+Place each visual next to the short text it supports. Keep only the calls, files, props, states, and boundaries needed to answer the current question. Use one shape, maybe several — never all. Concrete example shapes: `references/visual-shapes.md`.
+
+**Delivery:** write the visual explanation to `/tmp/YYYY-MM-DD-HHMM-comms-<topic>.md` and open it with `file-review` (via Bash, `run_in_background: true`, `timeout: 600000`) — it rich-renders the markdown and lets the user leave inline comments; process their comments when the window closes. If `file-review` is not on PATH, put the visual in chat instead. Keep `Bash(open ...)` for HTML artifacts. Skip file-review only for a single small visual that reads fine in chat.
+
+## Mode: Joint
+
+Simpler + Visual in one document: Simpler-mode prose with Visual-mode shapes placed right after the sentence each one supports. Follow both rule sets — casual register for the words, smallest-view discipline for the visuals. Deliver via file-review, like Visual mode.
+
+## Mode: Precise
+
+Rewrite the given text under ASD-STE100 structural discipline so no reader — human or agent — can misparse it. Full rule tables, sub-mode detail, and process: `references/ste-rules.md`.
+
+Core rules:
+
+- Active voice. Simple tenses ("we received", not "we have received").
+- One instruction per sentence. ≤20 words for instructions, ≤25 for descriptions.
+- No semicolons. No phrasal verbs ("start", not "spin up"). No noun stacks over 3 words. No dropped words.
+- One name per thing — never rotate synonyms for the same referent.
+- Verb over nominalization ("analyze the log", not "perform an analysis of the log").
+- **Keep every hedge and qualifier.** "May have failed" never becomes "failed". A rewrite that changes confidence is a different claim, not a simplification.
+- Never add a fact the source did not state.
+
+Two sub-modes:
+
+- **Strict** — tool descriptions, error messages, prompts, procedures, safety text: every rule.
+- **STE-flavored** — READMEs, PR text, explanatory prose: structural rules in full, lexical rules advisory.
+
+Output: the rewritten text and nothing else — no preamble, no mode announcement, no change summary. If you deliberately kept a longer phrasing to preserve precision, add one line prefixed `Kept as-is:`. When asked to "show the diff" or "explain the changes", output the before/after rule table from `references/ste-rules.md` instead.

package/templates/skills/comms/files/references/ste-rules.md

@@ -0,0 +1,73 @@
+# Precise mode — ASD-STE100 rules
+
+Condensed from [asd-ste100-skill](https://github.com/desplega-ai/asd-ste100-skill) (MIT), which encodes the rule categories of ASD-STE100 Issue 9 (Jan 2025).
+
+This encodes the standard's rule *categories*, not ASD's ~900-word approved dictionary (free to obtain, not free to redistribute). Structural rules are checkable from the description alone — apply them with confidence. Lexical rules depend on the dictionary — apply them as a direction of travel, and never imply dictionary compliance.
+
+## Structural rules — apply these
+
+| Rule | Do | Don't |
+|---|---|---|
+| Active voice | "The agent deletes the file." | "The file is deleted (by the agent)." — unless the actor is genuinely unknown or irrelevant |
+| No phrasal verbs | "Remove the panel." / "Start the job." | "Take off the panel." / "Spin up the job." |
+| One instruction per sentence | "Open the file. Read line 3." | "Open the file and read line 3, then check if it matches." |
+| Sentence length | ≤20 words for instructions, ≤25 for descriptions | Long compound/subordinate-clause sentences |
+| No semicolons | Split into separate sentences | Any semicolon at all |
+| Noun clusters | ≤3 words stacked as a noun phrase | 4+ word noun stacks ("high pressure fuel pump inlet valve assembly") |
+| No ellipsis | Keep subject, verb, and article explicit | Drop words to save space ("Files not backed up will be lost" → ambiguous which files) |
+| Keep modality | "The request **may have** failed." stays "may have" | Promote a hedge to a fact, or invent a certainty the source did not state |
+| Paragraph limits | One topic per paragraph, ≤6 sentences | Multi-topic paragraphs |
+| Lists for sequences | Numbered/bulleted list for 3+ steps or conditions | A sequence buried in one prose sentence |
+
+## Lexical rules — direction of travel only
+
+| Rule | Do | Don't |
+|---|---|---|
+| One word, one meaning | Pick one verb for one action and reuse it every time | Rotate synonyms ("check"/"verify"/"confirm") for the same action |
+| One part of speech per word | "Apply oil to the valve" (oil = noun) | "Oil the valve" (oil = verb) |
+| Verb, not noun | "Analyze the log." | "Perform an analysis of the log." |
+| Domain terms | Keep needed technical terms; define each once if not common English | Jargon never defined |
+
+## Simple tenses — one exception
+
+STE permits infinitive, imperative, simple present, simple past, simple future, and past participle as adjective. It excludes present perfect: "we received the report", not "we have received the report". Exception: where the compound form carries information the simple form cannot — current relevance ("the job has completed" = output available now), or a hedge like "may have failed" — keep it and flag the departure.
+
+## Scan checklist
+
+Scan for all six before rewriting. Each is mechanical — you can point at the exact word that breaks it.
+
+1. **Synonym rotation** — the same thing has several names ("the user", "the customer", "the client"). Fix: one name, every time.
+2. **Hedge stacking** — qualifiers pile up until nothing is asserted ("it is important to note that this may potentially help to improve"). Fix: state the claim or delete it.
+3. **Nominalization** — an action frozen into a noun ("perform an analysis of"). Fix: use the verb.
+4. **Marketing adjectives** — seamless, robust, powerful, blazing-fast. Fix: delete, or replace with the measurement that earns the claim.
+5. **Run-on sentences** — ideas joined by semicolons or em dashes. Fix: one idea per sentence.
+6. **Soft phrasal verbs** — spin up, reach out, dive into, kick off. Fix: the single plain verb (start, contact, read, begin).
+
+## Process
+
+1. Pick the sub-mode (Strict or STE-flavored). Keep the choice internal unless asked.
+2. Read the input once for meaning before rewriting anything.
+3. Walk it sentence by sentence; flag every violation. In STE-flavored, flag lexical rules but do not enforce them.
+4. Rewrite each flagged sentence, preserving the original meaning exactly. If a rewrite would drop necessary precision (a safety condition, scope qualifier, number), keep the longer phrasing and flag it. Check modality before committing — a shorter sentence that upgrades a hedge to a fact is a different claim. Never add a fact the source did not state.
+5. Output the rewritten text alone. If the input already complies, say so — do not force changes.
+
+## Diff table format (on request)
+
+When asked to "show the diff" / "which rules did it break" / "before/after":
+
+```markdown
+| Rule violated | Original | Simplified |
+|---|---|---|
+| Present perfect tense | "We have received your request." | "We received your request." |
+| Noun cluster (4+ words) | "the agent task queue priority handler" | "the handler that sets task-queue priority" |
+
+Mode: Strict. 7 violations found.
+```
+
+Follow with one line naming anything deliberately not simplified, and why.
+
+## Boundaries
+
+- Not a certified STE authoring tool — a clarity tool inspired by the standard. For aerospace-grade compliance, check word-by-word against the official dictionary from [asd-ste100.org](https://www.asd-ste100.org/STE_downloads.html).
+- Fixes form, not substance: a hollow paragraph rewritten under these rules is a clean hollow paragraph. Say so instead of polishing it.
+- Stop when the sentence is unambiguous, not when it is shortest.

package/templates/skills/comms/files/references/visual-shapes.md

@@ -0,0 +1,112 @@
+# Visual mode — example shapes
+
+Concrete examples for each view the Visual mode can produce. Source: the show-me skill (bundled into this skill).
+
+Logic or an algorithm as pseudocode:
+
+```text
+on(save)
+  if content is unchanged
+    return cached result
+  write new content
+  return fresh result
+```
+
+Runtime control flow as a call tree:
+
+```text
+submitForm
+  createSession
+    persistPrompt
+    launchAgent
+  navigateToSession
+```
+
+UI structure as a component tree, including state and module boundaries that matter:
+
+```tsx
+<SessionPage> (apps/example/src/routes/session.tsx)
+  useSessionEvents()
+  <SessionToolbar>
+    <RunSkillButton> (packages/ui)
+```
+
+File responsibility or a broad refactor as a shallow file tree:
+
+```text
+src/
+├── commands/       # parses user actions
+├── sessions/       # owns session state
+└── transport/      # sends API requests
+```
+
+Component interaction, control flow, or data flow with Mermaid:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant UI
+    participant Daemon
+    User->>UI: choose command
+    UI->>Daemon: send expanded prompt
+    Daemon-->>UI: stream result
+```
+
+`diff` shapes — match the diff to the topic.
+
+Component change:
+
+```diff
+ <SessionPage>
+   useSessionEvents()
+   <SessionToolbar>
++    <RunSkillButton />
+   <SessionTimeline>
++    <SkillResultCard />
+```
+
+File-layout change:
+
+```diff
+ src/
+ ├── commands/
++│   └── show-me.ts       # expands the slash command
+ ├── sessions/
+-└── transport.ts
++└── transport/
++    ├── client.ts
++    └── stream.ts
+```
+
+Call-tree change:
+
+```diff
+ submitForm
+   createSession
+     persistPrompt
++    expandSkillMention
+     launchAgent
+-  navigateToSession
++  navigateToSession
++    subscribeToEvents
+```
+
+State or control-flow change:
+
+```diff
+ on(save)
+-  write content
++  if content is unchanged
++    return cached result
++  write new content
++  invalidate cache
+```
+
+Whole block when most of it is new or a copyable target shape is needed:
+
+```ts
+function expandSkill(command: string): string {
+  const skillName = command.slice(1)
+  return `use the ${skillName} skill`
+}
+```

package/templates/skills/swarm-scripts/SKILL.md

@@ -37,7 +37,7 @@ The swarm ships named scripts at global scope. Each one replaces a multi-step to
 | `task-context-gathering` | `{ taskId, queries: [...] }` | the task plus a deduplicated multi-query memory recall |
 | `smart-recall` | `{ queries: [...] }` | multi-query memory recall without the task |
 | `memory-dedup-check` | `{ text, threshold? }` | near-duplicates before you store a memory |
-| `delegate` | `{ agentName, task, parentTaskId? }` | a subtask for an agent by name, returns `{ taskId }` |
+| `delegate` | `{ agentName, task, routingReason, parentTaskId? }` | a subtask for an agent by name, returns `{ taskId }` |
 | `wait-for-task` | `{ taskId }` | waits up to about 25 s for a terminal state, returns `{ done, status, output }`; call again while `done` is false |
 | `get-child-outputs` | `{ parentTaskId }` | every child with status and output |
 | `complete-task` | `{ taskId, output }` | finish a task from inside a script |
@@ -74,6 +74,7 @@ export default async function (args: z.infer<typeof argsSchema>, ctx: ScriptCont
 ### What `ctx` holds
 
 - `ctx.swarm.*`: the swarm SDK. `task_get`, `task_send`, `task_storeProgress`, `task_action`, `task_list`, `slack_reply`, `memory_search`, `memory_store`, `kv_get`, `kv_getOrNull`, `kv_set`, `kv_delete`, `kv_incr`, `kv_list`, `swarm_get`, `agent_info`, `db_query`, and more. `kv_getOrNull` returns the entry, `null` on a missing key, and throws on other errors.
+- `ctx.swarm.task_send` requires `routingReason` whenever `agentId` is present. Use `human_pinned` for an explicit/configured choice, `skill` for a role or specialization match, `continuity` for the same worker/session, `reroute_fault` for a fault handoff, or `overflow` for capacity/pool escalation. Omit both `agentId` and routing fields for the pool.
 - `ctx.swarm.config`: `apiKey`, `agentId`, `mcpBaseUrl`, and `ctx.swarm.config.get("KEY")` for user config values. All are `Redacted` wrappers that stringify to `<redacted>`. Never unwrap one into a return value, a log line, or a request body you build by hand.
 - `ctx.api.<slug>` and `ctx.mcp.<slug>`: typed clients for registered connections. They exist only for registered connections. Introspect with `Object.keys(ctx.api ?? {})` and `Object.keys(ctx.mcp ?? {})`.
 - `ctx.stdlib`: `fetch`, `fetchJson` (retries, 30 s timeout), `grep`, `glob`, `table`, `Redacted`.
@@ -81,7 +82,7 @@ export default async function (args: z.infer<typeof argsSchema>, ctx: ScriptCont
 
 ### Durable workflow scripts
 
-`launch-script-run` runs a script as a durable, journaled run with a different `ctx`: `ctx.run` (`id`, `agentId`, `args`) and `ctx.step.rawLlm(label, config)`, `ctx.step.agentTask(label, config)`, `ctx.step.swarmScript(label, config)`, plus `ctx.swarm.*`, `ctx.stdlib`, `ctx.logger`. Durable runs have no `ctx.api`, no `ctx.mcp`, and no `ctx.swarm.config`. Call a connection from an inner script through `ctx.step.swarmScript`. See the `script-workflows` skill.
+`launch-script-run` runs a script as a durable, journaled run with a different `ctx`: `ctx.run` (`id`, `agentId`, `args`) and `ctx.step.rawLlm(label, config)`, `ctx.step.agentTask(label, config)`, `ctx.step.swarmScript(label, config)`, plus `ctx.swarm.*`, `ctx.stdlib`, `ctx.logger`. Durable runs have no `ctx.api`, no `ctx.mcp`, and no `ctx.swarm.config`. A configured `ctx.step.agentTask` `agentId` records `human_pinned` unless `routingReason` is supplied. Call a connection from an inner script through `ctx.step.swarmScript`. See the `script-workflows` skill.
 
 ## Inline script pattern
 

package/templates/skills/swarm-scripts/content.md

@@ -32,7 +32,7 @@ The swarm ships named scripts at global scope. Each one replaces a multi-step to
 | `task-context-gathering` | `{ taskId, queries: [...] }` | the task plus a deduplicated multi-query memory recall |
 | `smart-recall` | `{ queries: [...] }` | multi-query memory recall without the task |
 | `memory-dedup-check` | `{ text, threshold? }` | near-duplicates before you store a memory |
-| `delegate` | `{ agentName, task, parentTaskId? }` | a subtask for an agent by name, returns `{ taskId }` |
+| `delegate` | `{ agentName, task, routingReason, parentTaskId? }` | a subtask for an agent by name, returns `{ taskId }` |
 | `wait-for-task` | `{ taskId }` | waits up to about 25 s for a terminal state, returns `{ done, status, output }`; call again while `done` is false |
 | `get-child-outputs` | `{ parentTaskId }` | every child with status and output |
 | `complete-task` | `{ taskId, output }` | finish a task from inside a script |
@@ -69,6 +69,7 @@ export default async function (args: z.infer<typeof argsSchema>, ctx: ScriptCont
 ### What `ctx` holds
 
 - `ctx.swarm.*`: the swarm SDK. `task_get`, `task_send`, `task_storeProgress`, `task_action`, `task_list`, `slack_reply`, `memory_search`, `memory_store`, `kv_get`, `kv_getOrNull`, `kv_set`, `kv_delete`, `kv_incr`, `kv_list`, `swarm_get`, `agent_info`, `db_query`, and more. `kv_getOrNull` returns the entry, `null` on a missing key, and throws on other errors.
+- `ctx.swarm.task_send` requires `routingReason` whenever `agentId` is present. Use `human_pinned` for an explicit/configured choice, `skill` for a role or specialization match, `continuity` for the same worker/session, `reroute_fault` for a fault handoff, or `overflow` for capacity/pool escalation. Omit both `agentId` and routing fields for the pool.
 - `ctx.swarm.config`: `apiKey`, `agentId`, `mcpBaseUrl`, and `ctx.swarm.config.get("KEY")` for user config values. All are `Redacted` wrappers that stringify to `<redacted>`. Never unwrap one into a return value, a log line, or a request body you build by hand.
 - `ctx.api.<slug>` and `ctx.mcp.<slug>`: typed clients for registered connections. They exist only for registered connections. Introspect with `Object.keys(ctx.api ?? {})` and `Object.keys(ctx.mcp ?? {})`.
 - `ctx.stdlib`: `fetch`, `fetchJson` (retries, 30 s timeout), `grep`, `glob`, `table`, `Redacted`.
@@ -76,7 +77,7 @@ export default async function (args: z.infer<typeof argsSchema>, ctx: ScriptCont
 
 ### Durable workflow scripts
 
-`launch-script-run` runs a script as a durable, journaled run with a different `ctx`: `ctx.run` (`id`, `agentId`, `args`) and `ctx.step.rawLlm(label, config)`, `ctx.step.agentTask(label, config)`, `ctx.step.swarmScript(label, config)`, plus `ctx.swarm.*`, `ctx.stdlib`, `ctx.logger`. Durable runs have no `ctx.api`, no `ctx.mcp`, and no `ctx.swarm.config`. Call a connection from an inner script through `ctx.step.swarmScript`. See the `script-workflows` skill.
+`launch-script-run` runs a script as a durable, journaled run with a different `ctx`: `ctx.run` (`id`, `agentId`, `args`) and `ctx.step.rawLlm(label, config)`, `ctx.step.agentTask(label, config)`, `ctx.step.swarmScript(label, config)`, plus `ctx.swarm.*`, `ctx.stdlib`, `ctx.logger`. Durable runs have no `ctx.api`, no `ctx.mcp`, and no `ctx.swarm.config`. A configured `ctx.step.agentTask` `agentId` records `human_pinned` unless `routingReason` is supplied. Call a connection from an inner script through `ctx.step.swarmScript`. See the `script-workflows` skill.
 
 ## Inline script pattern