Kanbn4droid/AGENTS.md

AGENTS.md

This file is for agentic coding assistants working in this repository. It captures build/test commands and code conventions observed in the codebase.

Project Snapshot

• Name: Kanbn4Droid
• Platform: Android app (Kotlin, XML views, coroutines)
• Build system: Gradle Kotlin DSL (*.gradle.kts)
• Module layout: single app module :app
• Namespace/application id: space.hackenslacker.kanbn4droid.app
• Compile/target SDK: 35
• Min SDK: 29
• Java/Kotlin target: 17

Environment Prerequisites

• Java 17 installed and available on PATH
• Android SDK command-line tools installed
• Android SDK packages:
  • platforms;android-35
  • build-tools;35.0.0
  • platform-tools
• If SDK is not auto-detected, copy local.properties.example to local.properties and set sdk.dir

Source of Truth for Commands

• Prefer Gradle wrapper (./gradlew) over system Gradle
• Most Android tasks should be run with explicit module prefix when possible (:app:<task>)
• Discover tasks with: ./gradlew tasks --all

Build / Lint / Test Commands

Core Daily Commands

• List tasks: ./gradlew tasks --all
• Clean: ./gradlew clean
• Build everything in app module: ./gradlew :app:build
• Build debug APK: ./gradlew :app:assembleDebug
• Install debug APK on connected device/emulator: ./gradlew :app:installDebug

Lint

• Run default lint: ./gradlew :app:lint
• Run debug lint explicitly: ./gradlew :app:lintDebug
• Run release lint explicitly: ./gradlew :app:lintRelease
• Auto-fix safe lint issues: ./gradlew :app:lintFix

Unit Tests (JVM)

• Run all unit tests (all variants): ./gradlew :app:test
• Run debug unit tests: ./gradlew :app:testDebugUnitTest
• Run release unit tests: ./gradlew :app:testReleaseUnitTest

Run a Single Unit Test (important)

• Single test class:
  • ./gradlew :app:testDebugUnitTest --tests "space.hackenslacker.kanbn4droid.app.boards.BoardsViewModelTest"
• Single test method:
  • ./gradlew :app:testDebugUnitTest --tests "space.hackenslacker.kanbn4droid.app.boards.BoardsViewModelTest.createBoardSuccessEmitsNavigateEvent"
• Pattern match within class/package:
  • ./gradlew :app:testDebugUnitTest --tests "space.hackenslacker.kanbn4droid.app.boarddetail.*"

Instrumentation Tests (device/emulator required)

• Run all connected debug instrumentation tests:
  • ./gradlew :app:connectedDebugAndroidTest
• Equivalent aggregate task:
  • ./gradlew :app:connectedAndroidTest

Run a Single Instrumentation Test (important)

• Single instrumentation test class:
  • ./gradlew :app:connectedDebugAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=space.hackenslacker.kanbn4droid.app.BoardsFlowTest
• Single instrumentation test method:
  • ./gradlew :app:connectedDebugAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=space.hackenslacker.kanbn4droid.app.BoardsFlowTest#pullToRefreshWorks

Repository-Local Rules (Cursor/Copilot)

• Checked for Cursor rules in .cursor/rules/ and .cursorrules: none found
• Checked for Copilot instructions in .github/copilot-instructions.md: none found
• Therefore, no additional repo-local AI instruction files are currently enforced beyond this document
• If those files are added later, treat them as higher-priority guidance and update this AGENTS.md

Architecture and Code Organization

• UI is Activity-driven (not Compose)
• Feature folders under app/src/main/java/space/hackenslacker/kanbn4droid/app/: auth/, boards/, boarddetail/, carddetail/
• Typical layering:
  • Activity handles view binding and user interaction wiring
  • ViewModel holds UI state and events (StateFlow + SharedFlow)
  • Repository/data source handles session and API calls
  • API client encapsulates HTTP + response parsing

Kotlin Style Guidelines (observed conventions)

Formatting

• Follow Kotlin official code style (gradle.properties: kotlin.code.style=official)
• Use 4-space indentation
• Use trailing commas in multiline argument lists/constructors where already used
• Keep functions focused; prefer extraction for repeated logic
• Avoid unnecessary comments; use clear naming instead

Imports

• Do not use wildcard imports
• Keep imports grouped (platform/library/project), matching existing file style
• Remove unused imports
• Prefer explicit imports for readability in large files

Types and API design

• Prefer immutable val; use var only when mutation is required
• Use data classes for immutable UI/domain models
• Use sealed interfaces/classes for event/result hierarchies (BoardsUiEvent, mutation results)
• Keep nullability explicit; avoid nullable types unless required by API/domain
• Return domain/result wrappers instead of throwing for expected failures

Naming

• Packages: lowercase, dot-separated (space.hackenslacker...)
• Classes/interfaces/objects: PascalCase
• Functions/properties/locals: camelCase
• Constants: UPPER_SNAKE_CASE (private const val ...)
• Test method names: descriptive camelCase phrases that state behavior

Coroutines and threading

• Use viewModelScope.launch for ViewModel async work
• Use withContext(Dispatchers.IO) or injected IO dispatcher for blocking/network work
• Keep dispatcher injection points testable (repositories already do this)
• Avoid blocking calls on main thread

State and events

• Model screen state as immutable data class in ViewModel
• Update state via copy semantics (state.copy(...)), often with MutableStateFlow.update
• Use one-off events via SharedFlow rather than state flags for navigation/toasts/dialog alerts
• Keep rendering deterministic from current state

Error handling

• Prefer explicit result types (BoardsApiResult, AuthResult) over exceptions for normal failure paths
• Surface user-visible messages through UI events/state
• Validate user input early (blank checks, URL normalization) before network calls

Android/UI conventions

• Keep user-facing text in res/values/strings.xml when practical
• Use Material components already present in the project
• Keep Activity responsibilities focused on binding and orchestration, not business logic
• Respect existing navigation via explicit intents and extras constants

Testing Conventions

• Unit tests live in app/src/test/... and use JUnit4 + coroutines test utilities
• Instrumentation tests live in app/src/androidTest/... and use Espresso/Intents
• Prefer fakes/in-memory stores for API/session dependencies in tests
• In coroutine tests:
  • set/reset main dispatcher in @Before/@After
  • use runTest and advanceUntilIdle()
• Keep tests behavior-focused (arrange -> act -> assert)