Skip to content

feat(skills): add agent-discussion terminal formatter skill #875

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JeremyDev87 merged 1 commit into from
Mar 22, 2026
Merged

feat(skills): add agent-discussion terminal formatter skill #875

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions packages/rules/.ai-rules/skills/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ Reusable workflows for consistent development practices.

| Skill | Description | When to Use |
|-------|-------------|-------------|
| agent-discussion | Terminal formatter for multi-agent debate output with severity badges and consensus indicators | Rendering parallel agent findings, code review debates, EVAL summaries |
| context-management | Preserve critical decisions across sessions and context compaction | Long tasks, multi-session work, PLAN→ACT→EVAL transitions |
| deployment-checklist | Pre-deploy validation, health checks, rollback planning | Before every staging/production deployment |
| dispatching-parallel-agents | Handle 2+ independent tasks without shared state | Parallel task execution |
Expand Down Expand Up @@ -183,6 +184,8 @@ EOF
│ └── SKILL.md
│
├── [Workflow & Process]
├── agent-discussion/
│ └── SKILL.md
├── context-management/
│ └── SKILL.md
├── deployment-checklist/
Expand Down
199 changes: 199 additions & 0 deletions packages/rules/.ai-rules/skills/agent-discussion/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,199 @@
---
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

1. **Box width** — Adapt to terminal width, minimum 50 characters
2. **Text wrapping** — Wrap long lines inside box boundaries with proper indentation
3. **Ordering** — Sort findings by severity: CRITICAL > HIGH > MEDIUM > LOW > INFO
4. **Grouping** — Group by topic when multiple agents comment on the same code location
5. **Deduplication** — If two agents report the same issue, merge into one block with both agent names
6. **Evidence format** — Always include `file:line` reference when available
7. **Spacing** — One blank line between agent blocks, two blank lines before consensus/summary blocks
Loading