swarm-engine 1.1.1 → 1.38.0

package/skills/swarm-output-style/SKILL.md

@@ -9,77 +9,183 @@ description: |
 
 # Swarm Output Style Guide
 
-## Plan Presentation
+All orchestration output follows this guide. The goal: the user should always know what's happening, what it costs, and what to do next.
 
-When presenting an orchestration plan, use this format:
+## 1. Pre-flight Plan (MANDATORY before any agent spawns)
 
+Show this BEFORE creating any team or spawning any agent. The user must approve before tokens are spent.
+
+Use `swarm-box.py` for the header, then markdown tables for the detail:
+
+```bash
+python3 ~/.claude/scripts/swarm-box.py <<'BOX'
+title: SWARM ORCHESTRATION — [Task Name]
+title: Pattern: [name]  │  Repo: [repo]
+title: [scope summary]
+BOX
+```
+
+Then show phase details as markdown tables:
+
+```
+### Phase 1: [Name] -- [parallel/sequential] (~[time])
+| Agent | Model | Focus |
+|-------|-------|-------|
+| `agent-name` | [model] | [what this agent will do] |
+
+Proceed?
+```
+
+Cost estimates use these rough defaults per agent type:
+- Researcher (mid tier): ~5K tokens, ~$0.04
+- Implementer (expensive tier): ~15K tokens, ~$0.19
+- Reviewer (expensive tier): ~8K tokens, ~$0.10
+- Tester (expensive tier): ~10K tokens, ~$0.13
+- Debugger (expensive tier): ~12K tokens, ~$0.15
+
+## 2. Phase Transition Banners
+
+**MANDATORY**: Use `python3 ~/.claude/scripts/swarm-box.py` via Bash tool for ALL box-drawing output. NEVER hand-draw boxes.
+
+Phase start banner:
+```bash
+python3 ~/.claude/scripts/swarm-box.py <<'BOX'
+title: PHASE 1 · Research | ⏱ 0:00
+3 agents · sonnet · read-only
+BOX
+```
+
+Phase completion summary:
+```bash
+python3 ~/.claude/scripts/swarm-box.py <<'BOX'
+title: PHASE 2 · Implement · COMPLETE | ⏱ ~10 min
+---
+✓ implementer-core    — 40 new tests, graph modules done
+✓ implementer-wiring  — engine/runner/learner wired
+✓ implementer-docs    — docs.html + llms-full.txt updated
+BOX
 ```
-## Orchestration Plan
 
-**Task**: [1-line description]
-**Pattern**: [pattern name]
-**Agents**: [count] | **Phases**: [count] | **Est. cost**: ~$[amount]
+## 3. Agent Completion Lines
 
-### Phase 1: [Name] — parallel
-| Agent | Role | Model | Focus |
-|-------|------|-------|-------|
-| `name` | type | model | what they do |
+As each agent finishes, append a single line:
 
-### Phase 2: [Name] — sequential (depends on Phase 1)
-| Agent | Role | Model | Focus |
-|-------|------|-------|-------|
-| `name` | type | model | what they do |
+```
+  `agent-name`    [done]  [duration] | ~[tokens] tokens | [1-line summary of what they found/did]
 ```
 
-## Progress Updates
+If an agent errors:
 
-Keep compact. One line per agent with status:
 ```
-agent-name    [working]  current action
-agent-name    [done]     completed in 12s
-agent-name    [idle]     waiting for Phase 2
+  `agent-name`    [error]  [duration] | [1-line error description]
 ```
 
-Do NOT dump raw agent output into progress updates. Summarize.
+Do NOT dump raw agent output. Summarize the key finding in one line.
 
-## Agent Reports
+## 4. Phase Summary (between phases)
 
-Each agent includes a Meta block. When aggregating:
-- Lead with the overall result (pass/fail/concerns)
-- Group findings by severity (critical > important > suggestion)
-- Include file:line references
-- Keep it scannable — bullet points, not paragraphs
+After all agents in a phase complete, summarize before moving on:
 
-## Final Summary
+```
+**Phase [N] complete** -- [duration] | ~[tokens] tokens | ~$[cost]
 
+Key findings:
+- [finding 1 with file:line reference if applicable]
+- [finding 2]
+
+Proceeding to Phase [N+1] -- [name]
 ```
-## Summary
 
-**Status**: [COMPLETE / NEEDS CHANGES / FAILED]
+Only ask for explicit approval at the Research-to-Implement transition (where cost jumps). Other transitions proceed automatically.
 
-### What was done
-- [bullet points]
+## 5. Error Recovery (when agents fail or return low confidence)
 
-### Key decisions
-- [bullet points]
+Surface structured options, don't just stop:
 
-### Metrics
-Agents: [N] | Phases: [N] | Duration: [time] | Est. cost: ~$[amount]
 ```
+**Agent issue**: `agent-name` -- [description of problem]
+
+Options:
+1. **Retry** with [adjusted parameters]
+2. **Skip** and proceed to next phase
+3. **Abort** orchestration
+
+Choice (1-3) or describe a different approach >
+```
+
+For low-confidence results:
+
+```
+**Low confidence**: `agent-name` flagged uncertainty about [specific thing]
+
+Options:
+1. **Accept** and note as a risk
+2. **Spawn** a targeted agent to investigate further
+3. **Flag** for manual review in the summary
+```
+
+## 6. Post-Completion Summary (MANDATORY)
+
+**MANDATORY**: Use `python3 ~/.claude/scripts/swarm-box.py` via the Bash tool. NEVER hand-draw boxes — they will always be misaligned.
+
+### How to use swarm-box.py
+
+Call via Bash tool with a heredoc. The script auto-pads all lines to identical display width.
+
+```bash
+python3 ~/.claude/scripts/swarm-box.py <<'BOX'
+title: ORCHESTRATION COMPLETE | STATUS: PASS
+---
+
+Phases: 4  │  Agents: 8  │  Duration: ~14 min
+
+[What Changed]
+20 files changed, +3,838 lines
+
+Tests:   53 new (987 → 1041), 64 files, all green
+Memory:  purge, prune, get, delete CLI commands
+Docs:    Knowledge Graph section on swarmengine.dev
+Version: 1.3.0 → 1.31.0
+Branch:  feat/execution-knowledge-graph → main
+[/]
+
+[Review Gate]
+reviewer-correctness  PASS (2 important → fixed)
+reviewer-convention   PASS (1 important → fixed)
+fixer                 6/6 findings resolved
+[/]
+
+Next: npm publish (run npm publish when ready)
+
+BOX
+```
+
+### Input format
+
+| Line type | Syntax | Renders as |
+|-----------|--------|------------|
+| Header | `title: TEXT` | `║  TEXT  ║` (top of box) |
+| Separator | `---` | `╠═══════╣` |
+| Sub-box start | `[Label]` | `║  ┌─ Label ──┐ ║` |
+| Sub-box end | `[/]` | `║  └──────────┘ ║` |
+| Content (inside sub-box) | plain text | `║  │  text  │ ║` |
+| Content (outside sub-box) | plain text | `║  text  ║` |
+| Blank line | empty line | `║  ║` |
+
+### Rules
+
+- **EVERY box in swarm output MUST be generated by `swarm-box.py`** — phase banners, completion summaries, pre-flight plan headers, error recovery boxes. No exceptions.
+- The script guarantees all lines have identical display width (verified internally).
+- Copy-paste the script output directly into your response.
+- If the script is unavailable, fall back to markdown tables — never hand-draw box characters.
 
 ## Anti-Patterns (DO NOT)
 
+- Do NOT spawn agents before showing the pre-flight plan
 - Do NOT dump raw agent transcripts into the summary
-- Do NOT use emoji in structured output (alignment issues in terminals)
-- Do NOT repeat the original task description in every status update
-- Do NOT show agent Meta blocks to the user — synthesize them
-- Do NOT use vague language ("various improvements") — be specific
-- Do NOT include timestamps in every line — only in the activity feed
-
-## Color Conventions (for terminal output)
-
-When outputting to terminal:
-- **Bold** for section headers
-- Agent names in their role color (blue=researcher, green=implementer, yellow=reviewer)
-- Status badges: `[working]` `[done]` `[idle]` `[error]`
-- Keep lines under 80 characters for terminal compatibility
+- Do NOT use emoji in structured output
+- Do NOT repeat the full task description in every status update
+- Do NOT show agent Meta blocks to the user -- synthesize them
+- Do NOT use vague language ("various improvements") -- be specific
+- Do NOT include timestamps on every line -- only in phase banners
+- Do NOT ask "proceed?" after every phase -- only at Research-to-Implement transition