pacer/AGENTS.md

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

./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