From fe24116e24567846b44d761058818fa484c49ebb Mon Sep 17 00:00:00 2001 From: JeremyDev87 Date: Sun, 22 Mar 2026 21:05:00 +0900 Subject: [PATCH] feat(skills): add agent-discussion terminal formatter skill - Add SKILL.md with structured box format for multi-agent debate output - Define severity badges (CRITICAL/HIGH/MEDIUM/LOW/INFO) - Define agent emoji identifiers and color hints - Add consensus/disagreement indicator formats - Add summary block specification - Update skills README with new entry Closes #833 --- packages/rules/.ai-rules/skills/README.md | 3 + .../skills/agent-discussion/SKILL.md | 199 ++++++++++++++++++ 2 files changed, 202 insertions(+) create mode 100644 packages/rules/.ai-rules/skills/agent-discussion/SKILL.md diff --git a/packages/rules/.ai-rules/skills/README.md b/packages/rules/.ai-rules/skills/README.md index 194b6c3..01acd9d 100644 --- a/packages/rules/.ai-rules/skills/README.md +++ b/packages/rules/.ai-rules/skills/README.md @@ -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 | @@ -183,6 +184,8 @@ EOF │ └── SKILL.md │ ├── [Workflow & Process] +├── agent-discussion/ +│ └── SKILL.md ├── context-management/ │ └── SKILL.md ├── deployment-checklist/ diff --git a/packages/rules/.ai-rules/skills/agent-discussion/SKILL.md b/packages/rules/.ai-rules/skills/agent-discussion/SKILL.md new file mode 100644 index 0000000..b9f06c5 --- /dev/null +++ b/packages/rules/.ai-rules/skills/agent-discussion/SKILL.md @@ -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