FeedFlow Copilot Instructions

Development instructions for FeedFlow, a multi-platform RSS reader built with Kotlin Multiplatform, Compose Multiplatform, and SwiftUI. Targets Android, iOS, macOS, Windows, and Linux.

Project Structure

Module Organization

`core/` - Core domain models and utilities shared across all platforms

`shared/` - Main business logic, repositories, view models, and data layer

`sharedUI/` - Compose UI components shared across Android and Desktop

`database/` - SQLDelight database implementation

`i18n/` - Internationalization resources

`feedSync/` - Feed synchronization modules (Dropbox, FreshRSS, iCloud, etc)

`androidApp/` - Android-specific app implementation

`iosApp/` - iOS app with SwiftUI

`desktopApp/` - Desktop app for Windows, Linux, and macOS

`website/` - Hugo-based website

Build Commands

Verification & Testing

1. Run all checks (tests + linting):

```bash

./gradlew detekt allTests --quiet --console=plain

```

2. Run static analysis only:

```bash

./gradlew detekt --quiet --console=plain

```

3. Run all tests:

```bash

./gradlew test --quiet --console=plain

```

4. Format iOS code:

```bash

.scripts/ios-format.sh

```

5. Regenerate i18n translations:

```bash

.scripts/refresh-translations.sh

```

Platform-Specific Builds

**Android:**

```bash

./gradlew :androidApp:assembleGooglePlayDebug --quiet --console=plain

.scripts/run-android.sh # Install and launch on device/emulator

```

**Desktop:**

```bash

./gradlew desktopApp:run --quiet --console=plain

```

**iOS (Simulator):**

```bash

mcp__XcodeBuildMCP__build_sim_name_proj projectPath: "/Users/mg/Workspace/feedflow/feed-flow/iosApp/FeedFlow.xcodeproj" scheme: "FeedFlow" simulatorName: "iPhone 17 Pro"

```

Alternative project paths (always use the first one that exists):

`/Users/mg/Workspace/feedflow/feed-flow-2/iosApp/FeedFlow.xcodeproj`

`/Users/marco.gomiero/Workspace/tmp/feed-flow/iosApp/FeedFlow.xcodeproj`

Use `-quiet` flag when building with xcodebuild. If errors occur, re-run without `-quiet` for details.

Initial Setup

Copy dummy configuration files before building from scratch:

```bash

Android

cp config/dummy-google-services.json androidApp/src/debug/google-services.json

cp config/dummy-google-services.json androidApp/src/release/google-services.json

iOS

cp config/dummy-google-service.plist iosApp/GoogleService-Info-dev.plist

cp config/dummy-google-service.plist iosApp/GoogleService-Info.plist

cp iosApp/Assets/Config.xcconfig.template iosApp/Assets/Config.xcconfig

```

Build Verification Process

CRITICAL: After making code changes:

1. Build the project for the platform you modified

2. Fix all compilation errors before proceeding

3. Only build for the platform you're working on to save time

Testing

Follow the comprehensive testing guide at `.ai/TESTING.md`.

Key principles:

All tests extend `KoinTestBase` for dependency injection

Use Turbine for Flow testing

Prefer fakes over mocking libraries

Use data generators from `shared/src/commonTest/.../test/generators/`

For sync service tests, use the `feedSync/test-utils` module

If you touch or create business logic, write thorough unit tests

Development Guidelines

General Rules

DO NOT write comments for every function or class. Only comment when code is not self-explanatory.

DO NOT excessively use try/catch blocks. Use them at top callers or bottom callers as appropriate.

ALWAYS run gradle tasks with: `--quiet --console=plain`

NEVER add hardcoded strings. Always use i18n resources from `i18n/src/commonMain/resources/locale/values-[language]/`

NEVER translate languages yourself. Add only English strings; professionals handle translations later.

After adding new translations, run `.scripts/refresh-translations.sh` to regenerate Kotlin code

iOS Development

ALWAYS build with xcodebuild using `-quiet` flag

Project supports iOS 26 SDK (June 2025) with iOS 18 minimum deployment target. Use `#available` checks for iOS 26+ APIs.

Break types into separate Swift files (avoid multiple structs/classes/enums in one file)

Never use `ObservableObject`; always prefer `@Observable` classes

Never use `Task.sleep(nanoseconds:)`; always use `Task.sleep(for:)`

Avoid `AnyView` unless absolutely required

Avoid force unwraps and force `try` unless unrecoverable

Git Commit Messages

Use simple, one-liner commit messages

DO NOT include phase numbers ("Phase 1", "Phase 2")

DO NOT add "Generated with Claude Code" attribution

DO NOT add "Co-Authored-By: Claude" attribution

Example: `git commit -m "Add foundation for unified article parsing system"`

Pre-Handoff Checklist

Before handing off work:

1. Run `./gradlew detekt --quiet --console=plain` (skip if only Swift files modified)

2. Run `.scripts/ios-format.sh` (only if iOS app was modified)

3. Fix any issues found during the above steps

FeedFlow Copilot Instructions

FeedFlow Copilot Instructions

Project Structure

Module Organization

Build Commands

Verification & Testing

Platform-Specific Builds

Initial Setup

Android

iOS

Build Verification Process

Testing

Development Guidelines

General Rules

iOS Development

Git Commit Messages

Pre-Handoff Checklist

Reviews (0)