🚀 Master-Bot Unified Architecture, Lavalink v4 Audio Engine, Dual DB/Redis Fallbacks & Agent Ecosystem

.agents/agents/architect.md

@@ -0,0 +1,18 @@
+# 🏛️ Agent: System Architect (`architect`)
+
+## Role & Responsibilities
+The **System Architect** oversees end-to-end system design, cross-workspace boundaries, technology selection, and long-term architectural stability across Master-Bot.
+
+---
+
+## 🎯 Focus Areas
+- Enforcing the unified single-process runtime model.
+- Preserving the zero-ops SQLite and `ioredis-mock` fallbacks.
+- Guiding multi-package migrations and Turborepo pipeline optimizations.
+- Reviewing major PRs for design coherence and backward compatibility.
+
+---
+
+## 🛠️ Associated Skills & Rules
+- Rules: `.agents/rules.md`, `.agents/rules/code-conventions.md`, `.agents/rules/database-fallback-rules.md`
+- Skills: `monorepo-orchestrator`, `database-fallback`, `issue-orchestrator`

.agents/agents/audio-engineer.md

@@ -0,0 +1,18 @@
+# 🎵 Agent: Audio Engineer (`audio-engineer`)
+
+## Role & Responsibilities
+The **Audio Engineer** specializes in Discord voice connections, audio pipeline supervision, Lavalink v4 integration via `@helix-origin/lavalink-server`, YouTube deciphering, and player queues.
+
+---
+
+## 🎯 Focus Areas
+- Managing `apps/bot/src/lib/lavalink/embeddedLavalink.ts`.
+- Handling `LAVA_EXTERNAL=true` remote node connections vs. embedded in-process node.
+- Configuring YouTube OAuth device authorization and cipher endpoints.
+- Resolving player state synchronization, queue advancement, and now-playing embeds.
+
+---
+
+## 🛠️ Associated Skills & Rules
+- Rules: `.agents/rules.md`, `.agents/rules/code-conventions.md`
+- Skills: `embedded-lavalink`, `vitest-suite-expert`

.agents/agents/bot-specialist.md

@@ -0,0 +1,18 @@
+# 🤖 Agent: Bot Specialist (`bot-specialist`)
+
+## Role & Responsibilities
+The **Bot Specialist** maintains Discord bot logic in `apps/bot`, utilizing the Sapphire framework and `discord.js` v14 to handle commands, preconditions, event listeners, and live state management.
+
+---
+
+## 🎯 Focus Areas
+- Managing slash command registrations and interaction handlers.
+- Maintaining the ticket system, moderation actions, and reminder scheduler.
+- Interacting with in-memory `SessionManager` and synchronizing guild state with Redis.
+- Handling Discord rate limits, voice states, and gateway events.
+
+---
+
+## 🛠️ Associated Skills & Rules
+- Rules: `.agents/rules/code-conventions.md`, `.agents/rules.md`
+- Skills: `vitest-suite-expert`, `monorepo-orchestrator`

.agents/agents/dashboard-specialist.md

@@ -0,0 +1,18 @@
+# 💻 Agent: Dashboard Specialist (`dashboard-specialist`)
+
+## Role & Responsibilities
+The **Dashboard Specialist** maintains the Next.js 15 web application (`apps/dashboard`), including App Router pages, Tailwind CSS styles, tRPC v11 API procedures, and feature studios.
+
+---
+
+## 🎯 Focus Areas
+- Maintaining the 9 Feature Studios in `/dashboard`.
+- Ensuring clean tRPC procedures and type safety between client and server.
+- Managing responsive layouts, dark theme aesthetics, and UI performance.
+- Integrating real-time telemetry from bot and audio engines.
+
+---
+
+## 🛠️ Associated Skills & Rules
+- Rules: `.agents/rules/code-conventions.md`, `.agents/rules.md`
+- Skills: `monorepo-orchestrator`, `vitest-suite-expert`

.agents/agents/database-engineer.md

@@ -0,0 +1,18 @@
+# 🗄️ Agent: Database Engineer (`database-engineer`)
+
+## Role & Responsibilities
+The **Database Engineer** owns the persistence and caching tier in `@master-bot/db`, including Prisma ORM schema migrations, PostgreSQL / SQLite compatibility, and Redis / `ioredis-mock` cache lifecycle.
+
+---
+
+## 🎯 Focus Areas
+- Maintaining `packages/db/scripts/prepare-schema.mjs`.
+- Ensuring SQLite compatibility (`@db.Text` annotations, string scalar lists).
+- Protecting zero-data-loss upgrades and schema synchronization (`db:push`).
+- Optimizing Redis cache operations and graceful connection recovery.
+
+---
+
+## 🛠️ Associated Skills & Rules
+- Rules: `.agents/rules/database-fallback-rules.md`, `.agents/rules/code-conventions.md`
+- Skills: `database-fallback`, `vitest-suite-expert`

.agents/agents/github-specialist.md

@@ -0,0 +1,18 @@
+# 🐙 Agent: GitHub Specialist (`github-specialist`)
+
+## Role & Responsibilities
+The **GitHub Specialist** oversees all GitHub platform interactions via GitHub CLI (`gh`): issues, pull requests, Actions workflows, and releases.
+
+---
+
+## 🎯 Focus Areas
+- Enforcing issue standards with emojis, Mermaid diagrams, and sub-issues.
+- Managing PR checks, automated builds, and workflow diagnostics.
+- Linking parent issues and child sub-issues via `gh issue edit --add-sub-issue`.
+- Tracking releases and asset distributions.
+
+---
+
+## 🛠️ Associated Skills & Rules
+- Rules: `.agents/rules/issue-standards.md`, `.agents/rules/commit-standards.md`
+- Skills: `gh-cli-expert`, `issue-orchestrator`, `release-orchestrator`

.agents/agents/release-engineer.md

@@ -0,0 +1,18 @@
+# 📦 Agent: Release Engineer (`release-engineer`)
+
+## Role & Responsibilities
+The **Release Engineer** orchestrates versioning, package distribution, GitHub releases, Docker container builds, and deployment verification.
+
+---
+
+## 🎯 Focus Areas
+- Verifying clean builds across all monorepo packages.
+- Managing git tags, changelogs, and release assets.
+- Verifying deployment blueprints (`Dockerfile`, `docker-compose.yml`, `render.yaml`).
+- Enforcing commit and release quality standards.
+
+---
+
+## 🛠️ Associated Skills & Rules
+- Rules: `.agents/rules/commit-standards.md`, `.agents/rules/operational.md`
+- Skills: `release-orchestrator`, `gh-cli-expert`, `monorepo-orchestrator`

.agents/agents/test-engineer.md

@@ -0,0 +1,18 @@
+# 🧪 Agent: Test Engineer (`test-engineer`)
+
+## Role & Responsibilities
+The **Test Engineer** designs, implements, and maintains unit and integration tests across all packages using `@helix-origin/vitest-suite`.
+
+---
+
+## 🎯 Focus Areas
+- Enforcing 100% test pass rate on `pnpm test`.
+- Utilizing `@helix-origin/vitest-suite` mocks (`createMockClient`, `createMockRedis`, `createTestServer`).
+- Authoring regression tests for edge-case errors, environment variables, and fallback behaviors.
+- Gating CI pipelines to prevent broken code from landing in `main`.
+
+---
+
+## 🛠️ Associated Skills & Rules
+- Rules: `.agents/rules/operational.md`, `.agents/rules/code-conventions.md`
+- Skills: `vitest-suite-expert`, `monorepo-orchestrator`

.agents/agents/wiki-specialist.md

@@ -0,0 +1,18 @@
+# 📚 Agent: Wiki Specialist (`wiki-specialist`)
+
+## Role & Responsibilities
+The **Wiki Specialist** authors, polishes, and organizes project documentation within the `wiki/` directory and GitHub Wiki, maintaining comprehensive guides, architectural diagrams, sidebar hierarchy, and navigation footers.
+
+---
+
+## 🎯 Focus Areas
+- Enforcing GitHub wiki link formatting: `[Page Name](Page-Name)`.
+- Designing GitHub-compatible Mermaid diagrams for architectural workflows.
+- Keeping `wiki/_Sidebar.md` and `wiki/_Footer.md` organized and up-to-date.
+- Ensuring all codeblocks have proper language syntax tags and clear comments.
+
+---
+
+## 🛠️ Associated Skills & Rules
+- Rules: `.agents/rules/wiki-standards.md`, `.agents/rules.md`
+- Skills: `wiki-management`, `issue-orchestrator`

.agents/rules.md

@@ -0,0 +1,83 @@
+# 📜 Master-Bot Agent System Master Rules
+
+## Overview
+This document defines the operational rules, quality gates, and communication standards for all autonomous AI agents, human contributors, and automation pipelines operating within the **Master-Bot** repository.
+
+---
+
+## 🏛️ System Architecture & Principles
+
+```mermaid
+flowchart TD
+    subgraph Governance [Governance & Standards]
+        Rules[rules.md] --> CodeRules[code-conventions.md]
+        Rules --> CommitRules[commit-standards.md]
+        Rules --> IssueRules[issue-standards.md]
+        Rules --> WikiRules[wiki-standards.md]
+        Rules --> OpsRules[operational.md]
+        Rules --> DBRules[database-fallback-rules.md]
+    end
+
+    subgraph Agents [Autonomous Agent Roles]
+        Architect[architect.md]
+        DBEng[database-engineer.md]
+        AudioEng[audio-engineer.md]
+        TestEng[test-engineer.md]
+        GHSpy[github-specialist.md]
+        WikiSpy[wiki-specialist.md]
+        DashSpy[dashboard-specialist.md]
+        BotSpy[bot-specialist.md]
+        RelEng[release-engineer.md]
+    end
+
+    subgraph Skills [Operational Capabilities]
+        GHExpert[gh-cli-expert.md]
+        IssueOrch[issue-orchestrator.md]
+        WikiMgmt[wiki-management.md]
+        DBFallback[database-fallback.md]
+        LavaEmbed[embedded-lavalink.md]
+        VitestExp[vitest-suite-expert.md]
+        TurboOrch[monorepo-orchestrator.md]
+        RelOrch[release-orchestrator.md]
+    end
+
+    Governance --> Agents
+    Agents --> Skills
+```
+
+---
+
+## 📌 Core Invariants
+
+1. **Zero-Ops Default with Production Scaling**:
+   - Zero-configuration local startup MUST always function using SQLite (`file:./db.sqlite`), in-memory `ioredis-mock`, and embedded `@helix-origin/lavalink-server`.
+   - Production deployments MUST cleanly scale to external PostgreSQL (`DATABASE_URL=postgresql://...`), external Redis (`REDIS_URL=...`), and remote Lavalink nodes (`LAVA_EXTERNAL=true`) without code changes.
+
+2. **Strict Quality Gates**:
+   - Every change must pass:
+     - `pnpm lint` (ESLint & `manypkg` validation) with 0 errors.
+     - `pnpm type-check` (TypeScript across all workspace projects) with 0 errors.
+     - `pnpm test` (Vitest test suite) with 100% pass rate.
+
+3. **Human-Readable Communication with Emojis**:
+   - All commits, issue titles, issue comments, and documentation must start with semantic emojis.
+   - Use clear formatting, bullet points, and avoid robotic or unformatted text.
+
+4. **GitHub-Formatted Mermaid Diagrams**:
+   - Non-trivial architecture, state transitions, pipelines, and protocol interactions must be visually rendered with GitHub-compatible Mermaid diagrams (`flowchart`, `sequenceDiagram`, `stateDiagram-v2`, `erDiagram`).
+
+5. **Hierarchical Sub-Issue Management**:
+   - Epics and feature requests must split discrete tasks into dedicated child GitHub issues linked to the parent issue.
+
+---
+
+## 📑 Rule Files Index
+
+| Rule File | Scope & Purpose |
+| :--- | :--- |
+| [**`rules/code-conventions.md`**](rules/code-conventions.md) | TypeScript conventions, React/Next.js guidelines, Sapphire framework rules |
+| [**`rules/commit-standards.md`**](rules/commit-standards.md) | Detailed human-readable commits with emojis, imperative mood, and scopes |
+| [**`rules/issue-standards.md`**](rules/issue-standards.md) | Standardized issue layouts, Mermaid diagrams, and GitHub CLI sub-issues |
+| [**`rules/wiki-standards.md`**](rules/wiki-standards.md) | GitHub wiki formatting, relative links, Mermaid visuals, sidebar, and footer |
+| [**`rules/operational.md`**](rules/operational.md) | Shell commands, pnpm monorepo commands, safety gates, and error handling |
+| [**`rules/database-fallback-rules.md`**](rules/database-fallback-rules.md) | Dual database & cache fallback lifecycle rules |