# AGENTS.md — Agent Working Guide for Pacer

## Purpose
This file explains how AI agents should work with the Pacer project. Follow these rules
consistently across sessions, as different agents may work on different themes or user stories.

## Agent Environment
- Runs inside a Docker container with `sudo` rights
- Install any required tools via `sudo pacman -S <package>` or `paru -S <package>` (AUR)
- No need to ask the user to install dependencies — just install them as needed

## Project Structure

```
Pacer/
├── AGENTS.md                 ← this file
├── BACKLOG.md                ← all user stories and acceptance criteria
├── README.md                 ← build instructions for humans
├── gradlew                   ← always use this to build, never system gradle
├── gradle/
│   ├── libs.versions.toml    ← single source of truth for all dependency versions
│   └── wrapper/
├── settings.gradle.kts
├── build.gradle.kts          ← root build file (apply false only)
└── app/
    ├── build.gradle.kts      ← module build file
    └── src/
        ├── main/
        │   ├── AndroidManifest.xml
        │   ├── kotlin/net/jeena/pacer/   ← all Kotlin source files
        │   └── res/
        ├── test/kotlin/net/jeena/pacer/          ← unit tests
        └── androidTest/kotlin/net/jeena/pacer/   ← instrumented tests
```

## Package Name
All Kotlin source files use the package prefix `net.jeena.pacer`.

## Naming Conventions
- Activities: `*Activity.kt` (e.g., `MainActivity.kt`)
- Services: `*Service.kt` (e.g., `PacerService.kt`)
- Composables: `*Screen.kt` for full screens, `*Component.kt` for reusable UI
- ViewModels: `*ViewModel.kt`

## Code Rules (Never Violate)
- Kotlin only — no Java files
- All UI via Jetpack Compose — no XML layouts
- **No audio focus requests anywhere** — app must play alongside AntennaPod without interruption
- Use `AudioTrack` directly for audio — not `MediaPlayer` or `ExoPlayer`
- `minSdk = 24` — use version checks for APIs above this
- Single-activity architecture — do not add new Activities for new screens
- All dependency versions in `gradle/libs.versions.toml` — never hardcode versions

## How to Use the BACKLOG

Stories are identified as `US-XX` in BACKLOG.md, grouped by Theme.

### Workflow Per User Story
1. Read the acceptance criteria for the target story in BACKLOG.md.
2. For TDD stories (US-03, US-04, US-13, US-14): write the failing test first.
3. Implement the minimum code to satisfy acceptance criteria.
4. Verify: `./gradlew lint` passes, `./gradlew test` passes.

### TDD Stories
For US-03, US-04, US-13:
- Commit failing test first: `test(US-XX): add failing test for <feature>`
- Then implement and commit: `feat(US-XX): implement <feature>`

### Commit Message Convention
```
<type>(US-XX): <short description>

Types: feat, fix, test, refactor, docs, chore
Example: feat(US-03): generate 880 Hz sine wave with AudioTrack
```

## Build Commands

```bash
./gradlew assembleDebug        # build debug APK
./gradlew test                 # run unit tests
./gradlew connectedAndroidTest # run instrumented tests (requires device)
./gradlew lint                 # run lint checks
./gradlew installDebug         # install on connected device
./gradlew clean assembleDebug  # clean build
```

Output APK: `app/build/outputs/apk/debug/app-debug.apk`

## Key Architecture Notes
- Background audio uses `HandlerThread` for the scheduling loop (battery-efficient)
- `WAKE_LOCK` + foreground service keeps audio alive through Doze mode
- `foregroundServiceType="mediaPlayback"` is required on Android 14+ (already in manifest)
- Do not add new dependencies without a user story requiring them