codingbuddy-rules 4.4.0 → 5.0.0

package/.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 |
@@ -39,6 +40,7 @@ Reusable workflows for consistent development practices.
 | legacy-modernization | Strangler fig pattern for incremental migration of legacy code | Modernizing old patterns, major version upgrades |
 | subagent-driven-development | Execute plans with independent tasks in current session | In-session plan execution |
 | systematic-debugging | Systematic approach before proposing fixes | Encountering bugs or failures |
+| cross-repo-issues | Detect, confirm, and create issues in upstream/related repositories with safety checks | Bug belongs upstream, dependency issue, fork-to-upstream reporting |
 | writing-plans | Create implementation plans before coding | Multi-step tasks with specs |
 
 ### Documentation & Communication
@@ -50,6 +52,13 @@ Reusable workflows for consistent development practices.
 | pr-review | Systematic, evidence-based PR review with anti-sycophancy principles | Conducting manual PR reviews |
 | prompt-engineering | Write and optimize prompts for AI tools and agent system prompts | AI tool instructions, MCP tool descriptions, agent prompts |
 
+### DevOps & Infrastructure
+
+| Skill | Description | When to Use |
+|-------|-------------|-------------|
+| cost-budget | Cost budget management with threshold alerts and auto-pause for autonomous workflows | Managing AI session costs, budget limits, taskMaestro wave budgets |
+| tmux-master | Background knowledge for tmux session/window/pane lifecycle, layout, communication, styling, and troubleshooting | Parallel agent execution, taskMaestro workflows, tmux automation |
+
 ### codingbuddy Specific
 
 | Skill | Description | When to Use |
@@ -57,6 +66,7 @@ Reusable workflows for consistent development practices.
 | agent-design | Design new specialist agent JSON definitions with schema, expertise, and system prompts | Adding new agents to codingbuddy |
 | mcp-builder | NestJS-based MCP server development with Tools/Resources/Prompts design | Building or extending MCP servers |
 | rule-authoring | Write unambiguous AI coding rules compatible across multiple AI tools | Creating rules for .ai-rules/ directories |
+| skill-creator | Create, eval, improve, and benchmark skills with measurable behavior-change tests | Creating new skills, testing skill effectiveness, optimizing underperforming skills |
 
 ## Skill Format
 
@@ -176,6 +186,10 @@ EOF
 │   └── SKILL.md
 │
 ├── [Workflow & Process]
+├── agent-discussion/
+│   └── SKILL.md
+├── cross-repo-issues/
+│   └── SKILL.md
 ├── context-management/
 │   └── SKILL.md
 ├── deployment-checklist/
@@ -214,11 +228,19 @@ EOF
 ├── prompt-engineering/
 │   └── SKILL.md
 │
+├── [DevOps & Infrastructure]
+├── cost-budget/
+│   └── SKILL.md
+├── tmux-master/
+│   └── SKILL.md
+│
 └── [codingbuddy Specific]
     ├── agent-design/
     │   └── SKILL.md
     ├── mcp-builder/
     │   └── SKILL.md
-    └── rule-authoring/
+    ├── rule-authoring/
+    │   └── SKILL.md
+    └── skill-creator/
         └── SKILL.md
 ```

package/.ai-rules/skills/agent-design/SKILL.md

@@ -267,3 +267,8 @@ ALL    → Cross-cutting agents (code-reviewer)
 - [ ] README.md updated with new agent
 - [ ] Added to relevant adapter configurations
 ```
+
+## Additional resources
+
+- [Agent JSON template](examples/agent-template.json) — Copy-and-adapt template with all required/optional fields and a design checklist
+- [Expertise definition guidelines](references/expertise-guidelines.md) — How to write differentiated expertise items, avoid overlaps, and validate quality

package/.ai-rules/skills/agent-design/examples/agent-template.json

@@ -0,0 +1,58 @@
+{
+  "_template_instructions": "Copy this file and replace all <placeholder> values. Remove this _template_instructions field. Save as packages/rules/.ai-rules/agents/<agent-name>.json (kebab-case filename).",
+
+  "name": "<Display Name>",
+  "description": "<One-sentence description of what this agent specializes in — be specific, not broad>",
+
+  "role": {
+    "title": "<Official Role Title>",
+    "type": "specialist",
+    "expertise": [
+      "<Specific Domain Expertise 1 — e.g., 'Zero-Downtime Schema Migrations'>",
+      "<Specific Domain Expertise 2 — e.g., 'Expand-Contract Migration Pattern'>",
+      "<Specific Domain Expertise 3 — e.g., 'Rollback Strategy Design'>",
+      "<Specific Domain Expertise 4 (optional)>",
+      "<Specific Domain Expertise 5 (optional)>"
+    ],
+    "responsibilities": [
+      "<Key responsibility 1 — what this agent actively does>",
+      "<Key responsibility 2 — what this agent actively does>",
+      "<Key responsibility 3 — what this agent actively does>"
+    ]
+  },
+
+  "context_files": [
+    ".ai-rules/rules/core.md",
+    ".ai-rules/rules/project.md"
+  ],
+
+  "modes": {
+    "planning": {
+      "activation": {
+        "trigger": "<When this agent activates in PLAN mode — e.g., 'When planning database schema migrations'>",
+        "auto_activate_conditions": [
+          "<Condition 1 — e.g., 'Schema change planning'>",
+          "<Condition 2 — e.g., 'Migration strategy design'>"
+        ]
+      }
+    },
+    "evaluation": {
+      "activation": {
+        "trigger": "<When this agent activates in EVAL mode — e.g., 'When evaluating migration safety and rollback readiness'>"
+      }
+    }
+  },
+
+  "_design_checklist": {
+    "_comment": "Remove this section from the final agent file. Use it during design to verify quality.",
+    "checks": [
+      "Domain is specific, not broad (e.g., 'Zero-Downtime Migrations' not 'Databases')",
+      "No significant overlap with existing agents (< 2 shared expertise items)",
+      "System prompt includes what this agent does NOT handle",
+      "3-7 expertise items, all specific and measurable",
+      "Filename follows kebab-case convention",
+      "Modes reflect actual usage patterns (PLAN, ACT, EVAL, or ALL)",
+      "JSON validates with: cat <file>.json | jq ."
+    ]
+  }
+}

package/.ai-rules/skills/agent-design/references/expertise-guidelines.md

@@ -0,0 +1,112 @@
+# Agent Expertise Definition Guidelines
+
+How to define clear, differentiated expertise items for codingbuddy specialist agents.
+
+## The Expertise Quality Spectrum
+
+| Level | Example | Verdict |
+|-------|---------|---------|
+| Too broad | "Databases" | Rejected — could mean anything |
+| Too vague | "Backend development" | Rejected — overlaps with many agents |
+| Right level | "PostgreSQL Query Plan Optimization" | Accepted — specific, testable |
+| Right level | "Zero-Downtime Schema Migrations" | Accepted — clear domain boundary |
+| Too narrow | "PostgreSQL 15.2 BRIN index tuning" | Risky — might be too version-specific |
+
+## Writing Expertise Items
+
+### Formula
+
+```
+[Technique/Pattern] + [Domain/Technology] + [Qualifier (optional)]
+```
+
+**Examples:**
+- "Expand-Contract Migration Pattern" (technique + domain)
+- "React Server Component Performance Profiling" (technique + technology)
+- "OWASP Top 10 Vulnerability Assessment" (standard + domain)
+- "Zero-Downtime Blue-Green Deployments" (qualifier + technique)
+
+### Rules
+
+1. **3-7 items per agent** — fewer than 3 means the agent is too narrow; more than 7 means it's too broad
+2. **Each item is independently meaningful** — someone reading just the expertise list should understand the agent's domain
+3. **No overlapping items within the same agent** — if two items cover similar ground, merge them
+4. **Use established terminology** — reference known patterns, standards, and methodologies
+
+## Differentiation Matrix
+
+Before adding an agent, compare expertise against existing agents:
+
+```
+New Agent Expertise          Existing Agent Expertise       Overlap?
+─────────────────────────    ─────────────────────────      ────────
+API Rate Limiting            API Gateway Patterns           PARTIAL → ok if boundaries clear
+REST API Versioning          GraphQL Schema Evolution       NO → different domains
+Error Response Standards     Error Handling Patterns         YES → merge or split
+```
+
+**Overlap thresholds:**
+- 0-1 shared items: Safe to add
+- 2 shared items: Review carefully, ensure boundaries are clear
+- 3+ shared items: Merge agents or fundamentally redesign scope
+
+## Expertise vs. Responsibilities
+
+| | Expertise | Responsibilities |
+|---|-----------|------------------|
+| **What** | Knowledge domains the agent has | Actions the agent takes |
+| **Format** | Noun phrases (domain areas) | Verb phrases (active duties) |
+| **Count** | 3-7 items | 2-4 items |
+| **Example** | "Container Orchestration Patterns" | "Design Kubernetes deployment manifests" |
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|-------------|---------|-----|
+| "Best practices" | Meaningless without context | Name the specific practice |
+| "General development" | Every agent does this | What SPECIFIC development? |
+| "Code review" | Too broad — review for what? | "Security-focused code review" |
+| "Testing" | Every engineer tests | "Property-based testing strategies" |
+| "Architecture" | Name the architecture concern | "Event-driven architecture design" |
+| Tool names alone ("Docker") | Knowing a tool isn't expertise | "Container image optimization" |
+
+## Expertise Validation Checklist
+
+For each expertise item, verify:
+
+```
+- [ ] Could I write a 30-minute talk about JUST this item?
+- [ ] Is this clearly different from the other items in this agent?
+- [ ] Would another agent's expertise NOT cover this?
+- [ ] Can I name 3 concrete tasks that require this specific expertise?
+- [ ] Is this stable enough to last 6+ months without rewording?
+```
+
+## Tier-Specific Guidance
+
+### Primary Agents (type: "primary")
+
+Used as the main agent in a workflow mode. Expertise should be broad enough to lead a mode but focused on a methodology:
+
+```json
+"expertise": [
+  "Solution Architecture Design",
+  "Technology Selection and Trade-off Analysis",
+  "System Integration Planning",
+  "Scalability and Performance Architecture"
+]
+```
+
+### Specialist Agents (type: "specialist")
+
+Called in parallel for domain reviews. Expertise should be deep and narrow:
+
+```json
+"expertise": [
+  "OWASP Top 10 Vulnerability Assessment",
+  "Authentication and Authorization Patterns",
+  "Secrets Management and Rotation",
+  "Security Header Configuration",
+  "Dependency Vulnerability Scanning"
+]
+```

package/.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