Imported from BerAxz/Centra-App (
AGENTS.md). Install upstream withnpx skills add BerAxz/Centra-App. Copyright stays with the author.
Centra - Agent Instructions
1. Project Overview
Centra is an Android application focused on helping users reduce distractions and organize their time.
The application is completely local/offline.
There is NO backend, NO user account, NO authentication server, NO cloud synchronization and NO external database.
The application has three main areas:
- Agenda
- Pomodoro
- Focus
The project is an existing Android/Kotlin/Gradle application that originally was called FocusColors.
The existing Focus functionality is already implemented and must be preserved.
2. Core Product Philosophy
Centra exists to reduce distractions, not to create more stimulation.
The UI must therefore be:
- Minimal
- Calm
- Functional
- Low stimulation
- Easy to understand
- Fast
- Offline-first
- Free of unnecessary animations
- Free of gamification
- Free of gradients
- Free of excessive colors
Do not introduce visually noisy UI patterns.
Avoid:
- Excessive animations
- Large colorful cards
- Gradients
- Excessive shadows
- Excessive rounded containers
- Gamification
- Badges everywhere
- Decorative elements without functional purpose
- Excessive notifications
The interface should feel like a calm productivity tool.
3. Technology
Use:
- Kotlin
- Gradle Kotlin DSL
- Jetpack Compose
- Material 3
- Room
- DataStore
- Kotlin Coroutines
- Flow
- ViewModel
- Navigation Compose
Prefer Android Jetpack libraries.
Do not introduce a backend.
Do not introduce Firebase unless explicitly requested.
Do not introduce Supabase.
Do not introduce PostgreSQL.
Do not introduce Retrofit unless a future feature explicitly requires an external API.
4. Architecture
Use a clean, maintainable architecture.
Preferred structure:
presentation/ domain/ data/
Feature-based organization is preferred when appropriate.
For example:
app/ src/main/kotlin/com/centra/app/
core/
data/
domain/
feature/
agenda/
habits/
events/
pomodoro/
focus/
navigation/
ui/
Do not create an unnecessary number of abstraction layers.
The architecture should remain understandable to a single developer.
5. Database
Use Room for structured application data.
Use DataStore for small application settings.
Do NOT use SharedPreferences for new structured data.
Existing SharedPreferences values may be migrated if necessary.
Room entities will include concepts such as:
- Habit
- HabitCategory
- HabitSchedule
- HabitCompletion
- FixedEvent
- FixedEventSchedule
Pomodoro settings may be stored using DataStore unless there is a strong architectural reason to store them in Room.
6. Habits
A habit is an activity the user wants to perform repeatedly.
A habit must support:
- Name
- Description (optional)
- Category
- Start time
- End time
- Days of week
- Start date
- Optional end date
- Notification configuration
- Active/inactive state
Habits repeat weekly by default.
A user may delete a habit.
Deleting a habit must NOT accidentally delete unrelated habits or events.
Habit completion must be tracked per occurrence/date.
Do not store a single boolean "completed" on the Habit entity.
Instead, track completion by date.
Example:
Habit: "Study Software Engineering"
Occurrences:
2026-08-18 -> completed 2026-08-20 -> not completed 2026-08-22 -> completed
This allows future statistics and streak calculations.
7. Habit Categories
Provide default categories:
- Universidad
- Ejercicio
- Salud
- Personal
- Trabajo
- Hogar
- Otros
Users can create custom categories.
Users can edit and delete custom categories where safe.
Do not allow deleting a category to silently destroy habits.
When necessary, reassign affected habits to "Otros" or require the user to choose another category.
Category colors must be subtle.
8. Fixed Events
Events represent scheduled activities that are not necessarily habits.
Examples:
- University classes
- Meetings
- Lunch
- Appointments
- Work
- Personal activities
Events support:
- Name
- Description (optional)
- Start time
- End time
- Days of week
- Start date
- Optional end date
- Notification configuration
Events repeat weekly by default.
Events are displayed in the calendar.
Events do not have completion state by default.
Do not mix Event and Habit concepts in the database.
9. Calendar
The calendar is the MAIN SCREEN of Centra.
When the application opens, it must open directly on the weekly calendar.
The current day must always be visually emphasized.
The current week should be shown by default.
The calendar must support:
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday
- Sunday
The calendar should allow horizontal scrolling on small screens.
The current day should have a subtle but clearly visible visual emphasis.
Do not use excessively strong colors.
The current day may be emphasized through:
- Slightly stronger background
- Border
- Subtle fill
- Stronger header text
The calendar must show both:
- Habits
- Fixed events
10. Calendar Interaction
The user must be able to tap an empty calendar time slot.
When tapping an empty slot:
Show options:
- Add habit
- Add event
The selected date and time should be prefilled in the creation form.
Example:
User taps:
Monday 18:00
The habit creation screen should automatically contain:
Day: Monday Start time: 18:00
The user can then modify everything else.
11. Calendar Block Interaction
When tapping an existing habit block, show actions:
- Mark as completed
- Edit
- Delete
- Cancel
The user must be able to edit all relevant habit information.
Do not implement drag-and-drop editing.
Changing a habit schedule must happen through the edit form.
For fixed events, tapping the event should allow:
- Edit
- Delete
- Cancel
12. Completion
A habit can be completed directly from the calendar.
Completing a habit should provide subtle visual feedback.
Do not use excessive animations.
Completed habits should remain visible but visually indicate completion.
Do not hide completed habits automatically.
13. List View
The calendar must have a list alternative.
The user can switch views using a three-dot overflow menu.
Menu options:
- Calendar view
- List view
List view must show BOTH:
- Habits
- Events
Items should be sorted chronologically.
The list should be grouped by day.
Example:
Monday
08:30 Engineering Data 08:30 - 10:40
14:30 Project 14:30 - 16:30
18:00 Study 18:00 - 20:00
The current day should be emphasized.
14. Navigation
Main sections:
- Agenda
- Pomodoro
- Focus
Agenda is the default screen.
Do not use excessive navigation levels.
The user should be able to access all major sections quickly.
15. Pomodoro
Pomodoro is completely independent from habits and events.
Do NOT associate Pomodoro sessions with habits.
Pomodoro must support configurable:
- Focus duration
- Short break duration
- Long break duration
- Number of focus sessions before long break
The user must be able to select:
Automatic mode Manual mode
Automatic mode:
Focus -> short break -> focus -> short break -> focus -> long break -> repeat
Manual mode:
The timer stops at the end of each phase and the user decides when to start the next phase.
16. Pomodoro UI
The Pomodoro timer must be minimal.
Prefer a circular progress indicator.
Example concept:
24:37
(circle)
FOCUS
[Pause]
The circle should visually empty/fill according to remaining time.
The remaining time must also be displayed numerically.
Avoid unnecessary visual elements.
17. Pomodoro Notifications
When a Pomodoro phase ends:
- Play a sound
- Vibrate
- Show a notification when appropriate
This applies to:
Focus -> Break
Break -> Focus
The behavior must work even when the application is not in the foreground.
Use Android-appropriate scheduling/background mechanisms.
Do not rely exclusively on a Compose coroutine that only works while the screen is active.
18. Notifications
Habits and events may have notifications.
The user can configure how long before the scheduled time the notification appears.
Examples:
- At time
- 5 minutes before
- 10 minutes before
- 15 minutes before
- 30 minutes before
- 1 hour before
The user should be able to disable notifications.
Notifications must not be spammy.
19. Focus Module
The existing FocusColors functionality is considered stable functionality.
It includes:
- Grayscale mode
- Application blocking
- UsageEvents monitoring
- ForegroundService
- BlockerOverlayActivity
- App selection
- WRITE_SECURE_SETTINGS
- PACKAGE_USAGE_STATS
- SYSTEM_ALERT_WINDOW
DO NOT rewrite this functionality unless absolutely necessary.
DO NOT replace the existing blocking mechanism with another mechanism.
DO NOT remove required permissions.
DO NOT change its behavior simply for architectural cleanliness.
The primary goal is to integrate the existing functionality into Centra.
Regression prevention is more important than refactoring elegance.
20. Existing Focus Files
Existing files may include:
- MainActivity.kt
- AppListActivity.kt
- BlockerOverlayActivity.kt
- BlockerService.kt
- AppUtils.kt
- AppPreferences.kt
Before changing these files:
- Read them.
- Understand their current behavior.
- Identify dependencies.
- Check the AndroidManifest.
- Check Gradle configuration.
- Check how permissions are requested.
- Check how the foreground service works.
Do not modify them blindly.
21. Grayscale
The grayscale functionality must continue using the existing mechanism.
WRITE_SECURE_SETTINGS is privileged and requires ADB.
Do not attempt to replace it with an inferior implementation.
Do not remove the existing ADB setup documentation.
22. Permissions
Preserve existing permissions.
New permissions may only be added when required by an implemented feature.
Every new permission must have:
- A clear reason
- Correct Android implementation
- User-facing explanation when appropriate
Do not request unnecessary permissions.
23. UI
Use Material 3 and Jetpack Compose.
Keep the visual language consistent.
Suggested visual principles:
- Light neutral background
- Dark neutral text
- Subtle category colors
- Minimal borders
- Minimal shadows
- Small number of icons
- Consistent spacing
- Consistent typography
Avoid visual stimulation.
24. Responsive Calendar
The calendar must be usable on phones.
Do not attempt to squeeze seven columns into an unreadable width.
Use horizontal scrolling when necessary.
The current day should remain discoverable.
The default initial horizontal position should center the current day as much as reasonably possible.
25. Forms
Creation and editing must use forms.
Forms should validate:
- Required name
- Valid start/end time
- End time after start time
- At least one selected day
- Valid date range
Show clear validation messages.
Do not silently correct invalid user input.
26. Testing
Every major feature must have tests.
At minimum:
- Repository tests
- ViewModel tests
- Database tests
- Habit scheduling tests
- Completion tests
- Calendar mapping tests
- Pomodoro state tests
Focus functionality should be regression tested where practical.
Do not declare a feature complete only because the project compiles.
27. Build Verification
After meaningful changes:
Run:
./gradlew test
and when appropriate:
./gradlew assembleDebug
Resolve compilation errors before continuing.
Do not leave known compilation errors for the next phase.
28. Code Quality
Prefer:
- Small functions
- Explicit names
- Immutable state
- StateFlow
- Coroutines
- Repository pattern where useful
- ViewModels
- Dependency injection only if it adds real value
Avoid:
- God classes
- Massive composables
- Global mutable state
- Hardcoded database access in UI
- Hardcoded application package names
- Duplicated business logic
29. Dependency Policy
Do not add libraries simply because they are popular.
Before adding a dependency:
- Check whether Android/Jetpack already provides the functionality.
- Check whether the dependency is necessary.
- Check compatibility with the current project.
- Check maintenance status if external.
- Explain why it is being added.
Avoid unnecessary calendar libraries if a custom Compose calendar can be implemented cleanly.
30. Git Safety
Do not delete existing working functionality.
Before large refactors:
- Inspect git status.
- Inspect current changes.
- Prefer small commits.
- Keep changes logically grouped.
Do not reset or discard user changes without explicit permission.
31. Working Method
Do not implement the entire project in one pass.
Work phase by phase according to:
docs/implementation-plan.md
At the beginning of each phase:
- Read the relevant documentation.
- Inspect the existing implementation.
- Identify affected files.
- Create a plan.
- Implement.
- Test.
- Review.
- Report remaining issues.
Do not begin the next phase if the current phase has unresolved critical problems.
32. Important Rule
The agent must not make product decisions when the documentation already specifies behavior.
If something is genuinely ambiguous and affects architecture or data behavior:
STOP and ask the developer.
Do not invent behavior for important domain decisions.
For minor UI implementation details, choose the simplest solution consistent with Centra's design philosophy.
33. Definition of Done
A feature is complete only when:
- It compiles.
- Relevant tests pass.
- The UI works.
- Data persists after restarting the app.
- Edge cases are handled.
- Existing Focus functionality still works.
- No unrelated functionality was broken.
- The implementation matches the documentation.