This document serves as a guide for AI agents interacting with the Melodee solution. It outlines the project structure, coding standards, and available resources to ensure consistent and high-quality contributions.
Melodee is a comprehensive music and media management system built with .NET (C#) and Blazor. It includes features like Party Mode, Jukebox functionality, and media library management.
This repository contains a suite of configuration files designed to guide AI behavior, located in the .github/ directory.
Before editing, open the most relevant instruction file(s) under .github/instructions/.
- Security-sensitive changes (auth, tokens, cookies, file paths, external URLs, anything user-supplied):
security-and-owasp.instructions.md - Performance-sensitive changes (hot paths, DB queries, streaming, large collections):
performance-optimization.instructions.md - Code review output (reviewing PRs/patches):
code-review-generic.instructions.md - Docs (any
*.md):markdown.instructions.md - Playwright tests:
These files define the specific coding standards, architectural guidelines, and best practices for the project. Agents MUST adhere to these instructions when working on relevant parts of the codebase.
- ASP.NET & Blazor:
- Languages:
- Data & ORM:
- Quality & Testing:
- Architecture & Best Practices:
- Infrastructure:
Specialized agent definitions for specific tasks. Use these personas to adopt the appropriate mindset and toolset.
See: .github/agents/
expert-dotnet-software-engineer.agent.md: General purpose high-level .NET engineering.csharp-dotnet-janitor.agent.md: Cleanup and maintenance.debug.agent.md: Dedicated debugging specialist.dotnet-upgrade.agent.md: For handling framework upgrades.tdd-red.agent.md: TDD Phase 1 - Write failing test.tdd-green.agent.md: TDD Phase 2 - Make it pass.tdd-refactor.agent.md: TDD Phase 3 - Clean up.se-security-reviewer.agent.md: Security implementation and review.playwright-tester.agent.md: End-to-end testing with Playwright.
Reusable prompts for common tasks to ensure consistency.
See: .github/prompts/
- Code Generation:
- Reviews:
- Playwright:
GitHub Actions workflows defining the build and test pipelines.
See: .github/workflows/
dotnet.yml: Main .NET build and test pipeline.codeql.yml: Security scanning.localization.yml: Localization checks.
- Context awareness: Before generating code, always check
.github/instructions/for relevant guidelines. For example, if editing a Blazor component, consultblazor.instructions.md. - Persona adoption: When assigned a specific task type (e.g., "Refactor this"), check if a matching agent persona exists in
.github/agents/(e.g.,tdd-refactor.agent.md) and align your behavior with it. - Prompt utilization: If asked to write documentation or tests, check
.github/prompts/to see if a prompt exists to standardize output format (e.g.csharp-docs.prompt.md).
- Read and follow applicable instruction files under
.github/instructions/. - Prefer self-explanatory code; comment only to explain why (see
self-explanatory-code-commenting.instructions.md). - Default to secure patterns (see
security-and-owasp.instructions.md), especially around input handling and secrets. - Avoid obvious performance regressions (see
performance-optimization.instructions.md). - Add/update tests for behavior changes, and run the smallest relevant test suite.
IMPORTANT: The /docs directory is reserved for the Jekyll-based public documentation site (GitHub Pages). DO NOT place internal documentation, implementation notes, session summaries, or test guides in /docs.
| Document Type | Location | Notes |
|---|---|---|
| Public user docs | /docs/pages/ |
Jekyll-formatted, visible at melodee.org |
| Implementation notes | /design/docs/ |
Internal technical documentation |
| Session summaries | /design/docs/ |
AI session summaries and fix docs |
| Requirements specs | /design/requirements/ |
Feature requirements and specifications |
| Testing guides | /design/testing/ |
Manual test walkthroughs, coverage reports |
| Runbooks | /design/runbooks/ |
Operational debugging guides |
| ADRs | /design/adr/ |
Architecture Decision Records |
| Chart data | /design/charts/ |
JSON data files for music charts |
When creating public-facing documentation (user guides, API docs):
- Create files in
/docs/pages/ - Use Jekyll front matter format
- Update
/docs/_data/toc.ymlfor navigation
Example front matter:
---
title: Feature Name
description: Brief description of the feature
tags:
- feature
- configuration
---When creating internal documentation (implementation notes, debugging guides):
- Create files in the appropriate
/design/subdirectory - Use standard Markdown (no Jekyll front matter required)
- Name files descriptively:
feature-name-description.md
Auto-generated guide for AI collaboration.