| name | agent-discussion |
| description | Use when rendering multi-agent debate, discussion, or review output in the terminal. Formats agent opinions with severity badges, colored identifiers, evidence blocks, and consensus indicators using box drawing characters. |
| user-invocable | false |
Agent Discussion Formatter
Overview
When multiple specialist agents contribute opinions, findings, or recommendations, raw text output becomes unreadable. This skill defines a structured terminal format that makes agent debates scannable, severity-aware, and action-oriented.
Core principle: Every agent contribution must be visually distinct, severity-tagged, and traceable to evidence.
Iron Law:
NEVER MIX AGENT OUTPUTS INTO UNSTRUCTURED PROSE — ALWAYS USE THE BOX FORMAT
When to Use
- Rendering output from parallel specialist agents (security, accessibility, performance, etc.)
- Displaying code review findings from multiple reviewers
- Presenting debate/discussion between agents with differing opinions
- Summarizing consensus or disagreement across agent recommendations
- EVAL mode consolidated output
Use this ESPECIALLY when:
- 3+ agents contribute findings on the same topic
- Agents disagree and the user needs to see both sides
- Severity levels vary across findings
When NOT to Use
- Single agent output (no debate to format)
- Non-terminal output (HTML, JSON API responses)
- Log-style sequential output where ordering matters more than structure
Format Specification
Agent Contribution Block
Each agent's finding is rendered in a box with metadata:
┌─ {emoji} {agent-name} ─────────────────────────┐
│ {SEVERITY} [{LEVEL}]: {title} │
│ {description spanning multiple lines with │
│ proper indentation and wrapping} │
│ │
│ Evidence: {file:line — code or observation} │
│ Recommendation: {actionable next step} │
└──────────────────────────────────────────────────┘
Agent Identifiers
Each agent type has a fixed emoji prefix for visual scanning:
| Agent | Emoji | Color Hint |
|---|
| security-specialist | 🔒 | Red |
| accessibility-specialist | ♿ | Blue |
| performance-specialist | ⚡ | Yellow |
| code-quality-specialist | 📏 | Green |
| architecture-specialist | 🏛️ | Purple |
| test-strategy-specialist | 🧪 | Cyan |
| event-architecture-specialist | 📨 | Orange |
| integration-specialist | 🔗 | Teal |
| observability-specialist | 📊 | Gray |
| migration-specialist | 🔄 | Magenta |
| seo-specialist | 🔍 | Lime |
| ui-ux-design-specialist | 🎨 | Pink |
| documentation-specialist | 📝 | White |
| code-reviewer | 👀 | Indigo |
Severity Badges
Severity levels with visual indicators:
| Level | Badge | Meaning |
|---|
| CRITICAL | 🔴 CRITICAL | Must fix before merge — security vulnerability, data loss risk |
| HIGH | 🟠 HIGH | Should fix before merge — significant quality or correctness issue |
| MEDIUM | 🟡 MEDIUM | Should fix soon — maintainability, performance, or minor risk |
| LOW | 🟢 LOW | Nice to have — style, optimization, minor improvement |
| INFO | ℹ️ INFO | Observation — no action required, context for the team |
Example: Single Finding
┌─ 🔒 security-specialist ──────────────────────────┐
│ 🟠 HIGH: SQL injection risk in user input handling │
│ │
│ Raw string concatenation used to build SQL query │
│ without parameterization. User-controlled input │
│ flows directly into the query string. │
│ │
│ Evidence: api/users.ts:42 │
│ const q = `SELECT * FROM users WHERE id=${input}` │
│ Recommendation: Use parameterized queries │
│ const q = `SELECT * FROM users WHERE id=$1` │
└─────────────────────────────────────────────────────┘
Example: Multiple Agents on Same Topic
┌─ 🔒 security-specialist ──────────────────────────┐
│ 🔴 CRITICAL: Unauthenticated endpoint exposed │
│ │
│ The /api/admin/users endpoint has no auth guard. │
│ Any client can list all user records including PII. │
│ │
│ Evidence: api/admin/users.ts:12 — no @UseGuards() │
│ Recommendation: Add AuthGuard and RolesGuard │
└─────────────────────────────────────────────────────┘
┌─ 📏 code-quality-specialist ───────────────────────┐
│ 🟡 MEDIUM: Missing input validation │
│ │
│ Query parameters parsed without validation. │
│ Unexpected types could cause runtime errors. │
│ │
│ Evidence: api/admin/users.ts:18 — raw req.query │
│ Recommendation: Add Zod/class-validator schema │
└─────────────────────────────────────────────────────┘
Consensus & Disagreement
Consensus Indicator
When agents agree, show a consensus block:
╔══════════════════════════════════════════════════════╗
║ ✅ CONSENSUS (3/3 agents agree) ║
║ ║
║ Auth guard must be added to /api/admin/* endpoints. ║
║ Agents: 🔒 security, 📏 code-quality, 🏛️ architecture ║
╠══════════════════════════════════════════════════════╣
║ Priority: CRITICAL — unanimously recommended ║
╚══════════════════════════════════════════════════════╝
Disagreement Indicator
When agents disagree, show the split:
╔══════════════════════════════════════════════════════╗
║ ⚖️ SPLIT OPINION (2 vs 1) ║
║ ║
║ Topic: Should we add request-level caching? ║
║ ║
║ FOR (2): ║
║ ⚡ performance — reduces DB load by ~40% ║
║ 🏛️ architecture — fits existing cache layer ║
║ ║
║ AGAINST (1): ║
║ 🔒 security — cache invalidation risks stale ║
║ auth state for permission changes ║
║ ║
║ Recommendation: Proceed with cache, add TTL < 60s ║
╚══════════════════════════════════════════════════════╝
Summary Block
At the end of a multi-agent discussion, render a summary:
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ 📋 DISCUSSION SUMMARY ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
┃ Agents: 4 participated ┃
┃ Findings: 7 total ┃
┃ 🔴 CRITICAL: 1 ┃
┃ 🟠 HIGH: 2 ┃
┃ 🟡 MEDIUM: 3 ┃
┃ 🟢 LOW: 1 ┃
┃ Consensus: 2 items agreed ┃
┃ Disputes: 1 split opinion ┃
┃ ┃
┃ Action required: Fix 1 CRITICAL + 2 HIGH before ┃
┃ merge. Review 1 split opinion with team. ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
Rendering Rules
- Box width — Adapt to terminal width, minimum 50 characters
- Text wrapping — Wrap long lines inside box boundaries with proper indentation
- Ordering — Sort findings by severity: CRITICAL > HIGH > MEDIUM > LOW > INFO
- Grouping — Group by topic when multiple agents comment on the same code location
- Deduplication — If two agents report the same issue, merge into one block with both agent names
- Evidence format — Always include
file:line reference when available
- Spacing — One blank line between agent blocks, two blank lines before consensus/summary blocks
