codehava-agent-kit 1.0.0 → 2.0.0

package/templates/.agent/skills/discord-bot-architect/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: discord-bot-architect
+description: "Specialized skill for building production-ready Discord bots. Covers Discord.js (JavaScript) and Pycord (Python), gateway intents, slash commands, interactive components, rate limiting, and sharding."
+risk: unknown
+source: "vibeship-spawner-skills (Apache 2.0)"
+date_added: "2026-02-27"
+---
+
+# Discord Bot Architect
+
+## Patterns
+
+### Discord.js v14 Foundation
+
+Modern Discord bot setup with Discord.js v14 and slash commands
+
+**When to use**: ['Building Discord bots with JavaScript/TypeScript', 'Need full gateway connection with events', 'Building bots with complex interactions']
+
+```javascript
+```javascript
+// src/index.js
+const { Client, Collection, GatewayIntentBits, Events } = require('discord.js');
+const fs = require('node:fs');
+const path = require('node:path');
+require('dotenv').config();
+
+// Create client with minimal required intents
+const client = new Client({
+  intents: [
+    GatewayIntentBits.Guilds,
+    // Add only what you need:
+    // GatewayIntentBits.GuildMessages,
+    // GatewayIntentBits.MessageContent,  // PRIVILEGED - avoid if possible
+  ]
+});
+
+// Load commands
+client.commands = new Collection();
+const commandsPath = path.join(__dirname, 'commands');
+const commandFiles = fs.readdirSync(commandsPath).filter(f => f.endsWith('.js'));
+
+for (const file of commandFiles) {
+  const filePath = path.join(commandsPath, file);
+  const command = require(filePath);
+  if ('data' in command && 'execute' in command) {
+    client.commands.set(command.data.name, command);
+  }
+}
+
+// Load events
+const eventsPath = path.join(__dirname, 'events');
+const eventFiles = fs.readdirSync(eventsPath).filter(f => f.endsWith('.js'));
+
+for (const file of eventFiles) {
+  const filePath = path.join(eventsPath, file);
+  const event = require(filePath);
+  if (event.once) {
+    client.once(event.name, (...args) => event.execute(...args));
+  } else {
+    client.on(event.name, (...args) => event.execute(...args));
+  }
+}
+
+client.login(process.env.DISCORD_TOKEN);
+```
+
+```javascript
+// src/commands/ping.js
+const { SlashCommandBuilder } = require('discord.js');
+
+module.exports = {
+  data: new SlashCommandBuilder()
+    .setName('ping')
+    .setDescription('Replies with Pong!'),
+
+  async execute(interaction) {
+    const sent = await interaction.reply({
+      content: 'Pinging...',
+      fetchReply: true
+    });
+
+    const latency = sent.createdTimestamp - interaction.createdTimestamp;
+    await interaction.editReply(`Pong! Latency: ${latency}ms`);
+  }
+};
+```
+
+```javascript
+// src/events/interactionCreate.js
+const { Events } = require('discord.js');
+
+module.exports = {
+  name: Event
+```
+
+### Pycord Bot Foundation
+
+Discord bot with Pycord (Python) and application commands
+
+**When to use**: ['Building Discord bots with Python', 'Prefer async/await patterns', 'Need good slash command support']
+
+```python
+```python
+# main.py
+import os
+import discord
+from discord.ext import commands
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# Configure intents - only enable what you need
+intents = discord.Intents.default()
+# intents.message_content = True  # PRIVILEGED - avoid if possible
+# intents.members = True          # PRIVILEGED
+
+bot = commands.Bot(
+    command_prefix="!",  # Legacy, prefer slash commands
+    intents=intents
+)
+
+@bot.event
+async def on_ready():
+    print(f"Logged in as {bot.user}")
+    # Sync commands (do this carefully - see sharp edges)
+    # await bot.sync_commands()
+
+# Slash command
+@bot.slash_command(name="ping", description="Check bot latency")
+async def ping(ctx: discord.ApplicationContext):
+    latency = round(bot.latency * 1000)
+    await ctx.respond(f"Pong! Latency: {latency}ms")
+
+# Slash command with options
+@bot.slash_command(name="greet", description="Greet a user")
+async def greet(
+    ctx: discord.ApplicationContext,
+    user: discord.Option(discord.Member, "User to greet"),
+    message: discord.Option(str, "Custom message", required=False)
+):
+    msg = message or "Hello!"
+    await ctx.respond(f"{user.mention}, {msg}")
+
+# Load cogs
+for filename in os.listdir("./cogs"):
+    if filename.endswith(".py"):
+        bot.load_extension(f"cogs.{filename[:-3]}")
+
+bot.run(os.environ["DISCORD_TOKEN"])
+```
+
+```python
+# cogs/general.py
+import discord
+from discord.ext import commands
+
+class General(commands.Cog):
+    def __init__(self, bot):
+        self.bot = bot
+
+    @commands.slash_command(name="info", description="Bot information")
+    async def info(self, ctx: discord.ApplicationContext):
+        embed = discord.Embed(
+            title="Bot Info",
+            description="A helpful Discord bot",
+            color=discord.Color.blue()
+        )
+        embed.add_field(name="Servers", value=len(self.bot.guilds))
+        embed.add_field(name="Latency", value=f"{round(self.bot.latency * 1000)}ms")
+        await ctx.respond(embed=embed)
+
+    @commands.Cog.
+```
+
+### Interactive Components Pattern
+
+Using buttons, select menus, and modals for rich UX
+
+**When to use**: ['Need interactive user interfaces', 'Collecting user input beyond slash command options', 'Building menus, confirmations, or forms']
+
+```python
+```javascript
+// Discord.js - Buttons and Select Menus
+const {
+  SlashCommandBuilder,
+  ActionRowBuilder,
+  ButtonBuilder,
+  ButtonStyle,
+  StringSelectMenuBuilder,
+  ModalBuilder,
+  TextInputBuilder,
+  TextInputStyle
+} = require('discord.js');
+
+module.exports = {
+  data: new SlashCommandBuilder()
+    .setName('menu')
+    .setDescription('Shows an interactive menu'),
+
+  async execute(interaction) {
+    // Button row
+    const buttonRow = new ActionRowBuilder()
+      .addComponents(
+        new ButtonBuilder()
+          .setCustomId('confirm')
+          .setLabel('Confirm')
+          .setStyle(ButtonStyle.Primary),
+        new ButtonBuilder()
+          .setCustomId('cancel')
+          .setLabel('Cancel')
+          .setStyle(ButtonStyle.Danger),
+        new ButtonBuilder()
+          .setLabel('Documentation')
+          .setURL('https://discord.js.org')
+          .setStyle(ButtonStyle.Link)  // Link buttons don't emit events
+      );
+
+    // Select menu row (one per row, takes all 5 slots)
+    const selectRow = new ActionRowBuilder()
+      .addComponents(
+        new StringSelectMenuBuilder()
+          .setCustomId('select-role')
+          .setPlaceholder('Select a role')
+          .setMinValues(1)
+          .setMaxValues(3)
+          .addOptions([
+            { label: 'Developer', value: 'dev', emoji: '💻' },
+            { label: 'Designer', value: 'design', emoji: '🎨' },
+            { label: 'Community', value: 'community', emoji: '🎉' }
+          ])
+      );
+
+    await interaction.reply({
+      content: 'Choose an option:',
+      components: [buttonRow, selectRow]
+    });
+
+    // Collect responses
+    const collector = interaction.channel.createMessageComponentCollector({
+      filter: i => i.user.id === interaction.user.id,
+      time: 60_000  // 60 seconds timeout
+    });
+
+    collector.on('collect', async i => {
+      if (i.customId === 'confirm') {
+        await i.update({ content: 'Confirmed!', components: [] });
+        collector.stop();
+      } else if (i.custo
+```
+
+## Anti-Patterns
+
+### ❌ Message Content for Commands
+
+**Why bad**: Message Content Intent is privileged and deprecated for bot commands.
+Slash commands are the intended approach.
+
+### ❌ Syncing Commands on Every Start
+
+**Why bad**: Command registration is rate limited. Global commands take up to 1 hour
+to propagate. Syncing on every start wastes API calls and can hit limits.
+
+### ❌ Blocking the Event Loop
+
+**Why bad**: Discord gateway requires regular heartbeats. Blocking operations
+cause missed heartbeats and disconnections.
+
+## ⚠️ Sharp Edges
+
+| Issue | Severity | Solution |
+|-------|----------|----------|
+| Issue | critical | ## Acknowledge immediately, process later |
+| Issue | critical | ## Step 1: Enable in Developer Portal |
+| Issue | high | ## Use a separate deploy script (not on startup) |
+| Issue | critical | ## Never hardcode tokens |
+| Issue | high | ## Generate correct invite URL |
+| Issue | medium | ## Development: Use guild commands |
+| Issue | medium | ## Never block the event loop |
+| Issue | medium | ## Show modal immediately |
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/templates/.agent/skills/dispatching-parallel-agents/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: dispatching-parallel-agents
+description: "Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies"
+risk: unknown
+source: community
+date_added: "2026-02-27"
+---
+
+# Dispatching Parallel Agents
+
+## Overview
+
+When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
+
+**Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.
+
+## When to Use
+```dot
+digraph when_to_use {
+    "Multiple failures?" [shape=diamond];
+    "Are they independent?" [shape=diamond];
+    "Single agent investigates all" [shape=box];
+    "One agent per problem domain" [shape=box];
+    "Can they work in parallel?" [shape=diamond];
+    "Sequential agents" [shape=box];
+    "Parallel dispatch" [shape=box];
+
+    "Multiple failures?" -> "Are they independent?" [label="yes"];
+    "Are they independent?" -> "Single agent investigates all" [label="no - related"];
+    "Are they independent?" -> "Can they work in parallel?" [label="yes"];
+    "Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
+    "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
+}
+```
+
+**Use when:**
+- 3+ test files failing with different root causes
+- Multiple subsystems broken independently
+- Each problem can be understood without context from others
+- No shared state between investigations
+
+**Don't use when:**
+- Failures are related (fix one might fix others)
+- Need to understand full system state
+- Agents would interfere with each other
+
+## The Pattern
+
+### 1. Identify Independent Domains
+
+Group failures by what's broken:
+- File A tests: Tool approval flow
+- File B tests: Batch completion behavior
+- File C tests: Abort functionality
+
+Each domain is independent - fixing tool approval doesn't affect abort tests.
+
+### 2. Create Focused Agent Tasks
+
+Each agent gets:
+- **Specific scope:** One test file or subsystem
+- **Clear goal:** Make these tests pass
+- **Constraints:** Don't change other code
+- **Expected output:** Summary of what you found and fixed
+
+### 3. Dispatch in Parallel
+
+```typescript
+// In Claude Code / AI environment
+Task("Fix agent-tool-abort.test.ts failures")
+Task("Fix batch-completion-behavior.test.ts failures")
+Task("Fix tool-approval-race-conditions.test.ts failures")
+// All three run concurrently
+```
+
+### 4. Review and Integrate
+
+When agents return:
+- Read each summary
+- Verify fixes don't conflict
+- Run full test suite
+- Integrate all changes
+
+## Agent Prompt Structure
+
+Good agent prompts are:
+1. **Focused** - One clear problem domain
+2. **Self-contained** - All context needed to understand the problem
+3. **Specific about output** - What should the agent return?
+
+```markdown
+Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:
+
+1. "should abort tool with partial output capture" - expects 'interrupted at' in message
+2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
+3. "should properly track pendingToolCount" - expects 3 results but gets 0
+
+These are timing/race condition issues. Your task:
+
+1. Read the test file and understand what each test verifies
+2. Identify root cause - timing issues or actual bugs?
+3. Fix by:
+   - Replacing arbitrary timeouts with event-based waiting
+   - Fixing bugs in abort implementation if found
+   - Adjusting test expectations if testing changed behavior
+
+Do NOT just increase timeouts - find the real issue.
+
+Return: Summary of what you found and what you fixed.
+```
+
+## Common Mistakes
+
+**❌ Too broad:** "Fix all the tests" - agent gets lost
+**✅ Specific:** "Fix agent-tool-abort.test.ts" - focused scope
+
+**❌ No context:** "Fix the race condition" - agent doesn't know where
+**✅ Context:** Paste the error messages and test names
+
+**❌ No constraints:** Agent might refactor everything
+**✅ Constraints:** "Do NOT change production code" or "Fix tests only"
+
+**❌ Vague output:** "Fix it" - you don't know what changed
+**✅ Specific:** "Return summary of root cause and changes"
+
+## When NOT to Use
+
+**Related failures:** Fixing one might fix others - investigate together first
+**Need full context:** Understanding requires seeing entire system
+**Exploratory debugging:** You don't know what's broken yet
+**Shared state:** Agents would interfere (editing same files, using same resources)
+
+## Real Example from Session
+
+**Scenario:** 6 test failures across 3 files after major refactoring
+
+**Failures:**
+- agent-tool-abort.test.ts: 3 failures (timing issues)
+- batch-completion-behavior.test.ts: 2 failures (tools not executing)
+- tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)
+
+**Decision:** Independent domains - abort logic separate from batch completion separate from race conditions
+
+**Dispatch:**
+```
+Agent 1 → Fix agent-tool-abort.test.ts
+Agent 2 → Fix batch-completion-behavior.test.ts
+Agent 3 → Fix tool-approval-race-conditions.test.ts
+```
+
+**Results:**
+- Agent 1: Replaced timeouts with event-based waiting
+- Agent 2: Fixed event structure bug (threadId in wrong place)
+- Agent 3: Added wait for async tool execution to complete
+
+**Integration:** All fixes independent, no conflicts, full suite green
+
+**Time saved:** 3 problems solved in parallel vs sequentially
+
+## Key Benefits
+
+1. **Parallelization** - Multiple investigations happen simultaneously
+2. **Focus** - Each agent has narrow scope, less context to track
+3. **Independence** - Agents don't interfere with each other
+4. **Speed** - 3 problems solved in time of 1
+
+## Verification
+
+After agents return:
+1. **Review each summary** - Understand what changed
+2. **Check for conflicts** - Did agents edit same code?
+3. **Run full suite** - Verify all fixes work together
+4. **Spot check** - Agents can make systematic errors
+
+## Real-World Impact
+
+From debugging session (2025-10-03):
+- 6 failures across 3 files
+- 3 agents dispatched in parallel
+- All investigations completed concurrently
+- All fixes integrated successfully
+- Zero conflicts between agent changes