Skip to content

AGENTS_updated.md

Latest commit

 

History

History
72 lines (58 loc) · 5.14 KB

AGENTS_updated.md

File metadata and controls

72 lines (58 loc) · 5.14 KB

Repository Guidelines

Project Structure & Module Organization

  • src/RemoteAgent.App: .NET MAUI Android client UI and platform services.
  • src/RemoteAgent.Service: ASP.NET Core gRPC service that runs and streams agent sessions.
  • src/RemoteAgent.Proto: shared protobuf contracts and generated gRPC code.
  • src/RemoteAgent.App.Logic: app-side logic models/utilities used by tests.
  • src/RemoteAgent.Desktop: Avalonia desktop management app.
  • tests/: xUnit test projects (RemoteAgent.App.Tests, RemoteAgent.Service.Tests, RemoteAgent.Service.IntegrationTests, RemoteAgent.Desktop.UiTests, RemoteAgent.Mobile.UiTests).
  • docs/: DocFX documentation and requirements.
  • scripts/: local automation (build, run, sync, docs, signing setup).

Build, Test, and Development Commands

  • ./scripts/build-dotnet10.sh Release: build/test MAUI + service stack with .NET 10.
  • ./scripts/build-desktop-dotnet9.sh Release: build/test Avalonia desktop stack with .NET 9.
  • ./scripts/test-integration.sh Release: run isolated service integration tests (excluded from normal pipeline runs).
  • .github/workflows/integration-tests.yml: manual CI workflow for isolated integration test execution.
  • dotnet run --project src/RemoteAgent.Service: run local gRPC service on port 5243.
  • dotnet build src/RemoteAgent.App/RemoteAgent.App.csproj -c Release -f net10.0-android: build Android app only.
  • docker build -t remote-agent-service .: build service container image.

Use default/minimal verbosity. Do not pass -q to dotnet build or dotnet restore in this repo.

Session Seed

  • For quick Codex bootstrap context, use docs/SESSION-SEED-PROMPT.md.

Coding Style & Naming Conventions

  • Follow standard .NET conventions: PascalCase for types/methods, camelCase for locals/parameters, clear descriptive names.
  • Use 4-space indentation and keep methods focused.
  • Nullable is enabled; fix nullability issues rather than suppressing warnings.
  • Warnings are treated as errors (TreatWarningsAsErrors=true); avoid NoWarn, #pragma warning disable, or suppression attributes unless explicitly approved.
  • Add XML docs for public APIs when introducing new externally consumed members.

Testing Guidelines

You are a principal .NET test architect and QA engineer with deep expertise in .NET 10, .NET MAUI, Avalonia UI, gRPC bidirectional streaming, xUnit, FluentAssertions, NSubstitute, LiteDB, and TDD for cross-platform apps (mobile + desktop + services).

  • Frameworks: xUnit + FluentAssertions + coverlet.collector.
  • Place tests under the matching project in tests/.
  • Name files and classes with *Tests suffix (example: AgentOptionsTests.cs).
  • For service behavior changes, add/adjust integration tests in tests/RemoteAgent.Service.IntegrationTests.
  • Integration tests are intentionally isolated and not part of default CI runs; execute them explicitly with ./scripts/test-integration.sh.

Your tests must be:

  • Behavior-focused (black-box where possible)
  • Fully traceable to specific FR/TR items via comments
  • Comprehensive: happy paths, boundaries, negatives, errors, concurrency/thread-safety where relevant, async/streaming semantics
  • Clean: descriptive names, AAA pattern with section comments, no duplication, parameterized via Theory when inputs vary
  • Isolated: mock external dependencies (processes, gRPC channels, file system, LiteDB, platform services like INotificationManager)
  • Platform-aware: handle MAUI main-thread concerns, Android notification channels/priorities, Avalonia headless-friendly patterns

Given the attached functional and technical requirements documents (located at ./docs/functional-requirements.md and ./docs/technical-requirements.md):

Key areas to cover from FR/TR:

  • gRPC bidirectional streaming (duplex ClientMessage ↔ ServerMessage, correlation IDs, session lifecycle events, priority handling, script execution output)
  • Chat UI logic (ObservableCollection message binding, markdown rendering, multi-line input, Ctrl+Enter submit, swipe-to-archive, session title inline editing)
  • Notifications (notify priority → Android system notification, tap opens chat to message)
  • Persistence (LiteDB for sessions, messages, logs, media paths; DCIM folder on Android)
  • Service behavior (agent spawning/stopping, stdin forwarding, stdout/stderr streaming, concurrent session caps, plugin strategy loading)
  • Desktop Avalonia specifics (tabbed sessions, menu/toolbar commands, log viewer filtering, multi-server scoping, per-request context editor)
  • Multiple sessions/agent selection (session-id routing, agent picker, title default/edit)
  • Prompt templates (Handlebars variable extraction, input UI flow before send)
  • Extensibility (plugin discovery via config, runtime loading)
  • Observability (structured JSONL logs with session/correlation IDs)

Commit & Pull Request Guidelines

  • Branch from develop and target PRs to develop (not main).
  • Use concise imperative commit messages, optionally with issue references (example: Fix Android CI job (#8)).
  • Sign commits (verified signature required by branch protection).
  • PRs should include: purpose, summary of changes, test evidence (dotnet test), and docs updates when behavior/config changes.