Jeena
a5b3f46eae
Initial project structure with manifest configured for foreground audio service, AudioTrack-based playback, and background operation. Includes Gradle wrapper, dependency catalog, placeholder icons, and build instructions for Arch Linux.
94 lines
3.7 KiB
Markdown
94 lines
3.7 KiB
Markdown
# 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
|