LlamaCasty/AGENTS.md

AGENTS — how to work in this repo

This file is auto-read at the start of every session. The project keeps its memory as a linked map of markdown files — read it before doing anything.

⚠️ CRITICAL: The Good Dog Rule

BEFORE any planning or coding, follow this rule:

ONE integration test per change.

When the user asks for changes that would involve multiple integration tests:

1. Identify the ONE specific use case/test they want to work on
2. Focus ONLY on the single use case until it's complete and tests pass

A good dog learns one trick perfectly before learning the next.

No feature branches pre-1.0 (decided 2026-08-24): solo dev, pre-1.0 — all work lands directly on main, committed and pushed per work unit. No taskNN-* branches, no PRs. The scope discipline above is about test focus, not git mechanics.

MUST read the architecture guide before planning or modifying the codebase: ai.md (+ schema.md for the memory-map conventions).

MUST read the coding guide before writing tests or code: the Working rules in this file — this repo has no CODING.md; conventions live here and in ai.md.

Onboarding (in order)

1. schema.md — the memory-map conventions (what lives where, how to keep it true).
2. ai.md — the AI guide: architecture, patterns, decisions, current state.
3. TASKS.md — the task queue + authoritative YouTube API research.
4. HANDOFF.md — current operational state: what's in flight, landmines, next step.
5. <dir>/index.md — the index for any directory you're about to touch.

If HANDOFF.md exists, trust it as current state — no fsck, no branch hunting, no file-scanning to re-derive what it already states, unless it points at a problem.

Working rules

• Never work without the map. If the map contradicts the code, the code wins and the map gets fixed in the same change (stale facts are corrected, not appended).
• Every feature change ships with its memory update in the SAME commit: ai.md for architecture/patterns, TASKS.md for status, index files when layout changes. No code commit without its docs — a follow-up "docs backfill" commit is a broken rule, not a style.
• Rewrite HANDOFF.md at session end, compaction, or any interruption. Never end a session with uncommitted work unrecorded — the handoff names the branch, the dirty files, and why it stopped.
• The first time a fact costs a hunt (secrets path, DB path, port, recovery source), record it in ai.md/indexes/HANDOFF.md so the next session never re-hunts it.
• Follow existing conventions — MVVM, RelayCommand for actions, ViewModelBase.SetProperty<T>(), all styles in Themes/Controls.xaml (merged once in App.xaml; never duplicate per-window).
• Do not add comments unless the code needs them; do not expand the task queue on your own — work only what the user queues.
• Response style: no default planning template. Do the work, then report what changed and what's next. No "Plans & Pitfalls", pros/cons tables, or step-by-step plans unless the user asks for a plan first (see ai.md).
• No-Fluff Mode is available on request — unpadded, ruthless review that argues rather than reassures (see ai.md). Optional, never the default.

Scope Lock

BEFORE editing any file, declare the exact file list for the task. Every file you touch must be either in that list OR you must state the specific dependency that requires it (e.g. "method X's signature changed, callers must update"). No "while I'm here" edits. No refactoring. No style tweaks. If you spot a problem in a file you're already editing, note it in HANDOFF.md as a follow-up — do not fix it in this change.

The commit d2114c7 touched 11 files across 4 layers because the AI decided to refactor the world. This rule exists because of that incident.

Before editing a file — git history scan

git log --oneline -5 -- <file>

If the file hasn't been touched in many commits and the current task doesn't directly require changing it, that is a red flag — stop and justify the edit or don't make it. A stable file touched by an unrelated task is a bug, not a feature.

Pre-commit audit

Before every commit, run scripts/scope-check.sh with the declared file list. If any file appears in git diff but not in the declared scope, either justify it or revert the change. The script enforces what the rule demands.

./scripts/scope-check.sh "Models/Scene.cs" "ViewModels/MainViewModel.cs" "MainWindow.xaml"

Build

From WSL, ALWAYS use the Windows dotnet host — Linux dotnet re-downloads the windowsdesktop.app.* packs over the slow 9p bridge and re-restores twice (WPF _wpftmp), and --no-restore right after an interrupted restore produces bogus NETSDK1064 errors. See ai.md → Run for the exact commands and why.

"/mnt/c/Program Files/dotnet/dotnet.exe" build "C:\Users\gramp\Documents\Code\projects\ytLive\ytLive.csproj"
"/mnt/c/Program Files/dotnet/dotnet.exe" vstest "C:\Users\gramp\Documents\Code\projects\ytLive\ytLive.Tests\bin\Debug\net8.0-windows10.0.19041.0\ytLive.Tests.dll"

Keep it at 0 warnings. Running requires Windows. On a silent startup crash, read %APPDATA%\ytLlive\startup.log (Helpers/AppLog.cs writes checkpoints and unhandled exceptions there).