Skip to content

[WIP]: Create AGENTS.md repository guidelines document with comprehensive development rules and context #1898

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
open-swe wants to merge 1 commit into
base: develop
Choose a base branch
from
Open

[WIP]: Create AGENTS.md repository guidelines document with comprehensive development rules and context #1898

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 86 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
<general_rules>
- **Service Organization**: When creating new backend services, place them in `backend/LexBoxApi/Services/` and follow the namespace pattern `LexBoxApi.Services`. Always check if a similar service already exists before creating a new one.
- **Controller Organization**: When creating new API controllers, place them in `backend/LexBoxApi/Controllers/` and follow the namespace pattern `LexBoxApi.Controllers`. Controllers should be thin and delegate business logic to services.
- **Frontend Components**: When creating new UI components, place them in `frontend/src/lib/components/` organized by feature or functionality. Always check existing components before creating duplicates.
- **Task Automation**: Use Taskfile commands for all development workflows:
- `task up` - Start full development environment with Tilt
- `task api` - Backend-only development
- `task ui` - Frontend-only development
- `task test:unit` - Run backend unit tests
- `task fw-lite-web` - Run FwLite web application
- **Code Formatting**:
- Backend: Follow .NET conventions defined in `.editorconfig` (4-space indentation for C#)
- Frontend: Use ESLint and Prettier (2-space indentation, single quotes, 120 char line width)
- Run `pnpm run lint` and `pnpm run format` for frontend code quality
Comment on lines +13 to +14
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Adjust frontend indentation documentation to match actual Prettier configuration.

The documentation claims 2-space indentation is explicitly configured, but the PR's automated review noted that 2-space indentation is actually the Prettier default for TypeScript/Svelte files, not an explicit .prettierrc setting. The .prettierrc only explicitly sets singleQuote and printWidth (120 char).

Apply this diff to correct the indentation claim:

  - **Code Formatting**: 
    - Backend: Follow .NET conventions defined in `.editorconfig` (4-space indentation for C#)
-   - Frontend: Use ESLint and Prettier (2-space indentation, single quotes, 120 char line width)
+   - Frontend: Use ESLint and Prettier (single quotes, 120 char line width, default 2-space indentation for TypeScript/Svelte)

Committable suggestion skipped: line range outside the PR's diff.

🤖 Prompt for AI Agents 
In AGENTS.md around lines 13 to 14, the docs incorrectly state that 2-space
indentation is explicitly configured for the frontend; update the text to
reflect that the Prettier config only sets singleQuote and printWidth (120) and
that 2-space indentation is Prettier’s default for TypeScript/Svelte rather than
an explicit .prettierrc setting, and then adjust the sentence to remove the
claim of an explicit indentation setting while keeping the rest of the
lint/format instructions intact.

- **Namespace Conventions**: Follow established patterns:
- Backend services: `LexBoxApi.Services`, `FwHeadless.Services`, `LexCore.*`
- Backend controllers: `LexBoxApi.Controllers`, `FwHeadless.Controllers`
- Test namespaces: `Testing.*`, `*.Tests`
- **Database Migrations**: Use Entity Framework migrations via `task api:add-migration -- "MigrationName"` and `task api:db-update`
</general_rules>

<repository_structure>
- **Multi-Service Architecture**: LexBox is a complex linguistic application with multiple interconnected services:
- `backend/LexBoxApi/` - Main .NET 9.0 API (GraphQL, REST, authentication)
- `backend/FwHeadless/` - FieldWorks headless service for linguistic data processing
- `backend/SyncReverseProxy/` - Proxy service for Mercurial sync operations
- `backend/LexCore/` - Shared core library (entities, interfaces, utilities)
- `backend/LexData/` - Data access layer with Entity Framework
- `backend/FwLite/` - FieldWorks Lite application (Maui + Web)
- **Frontend Structure**:
- `frontend/src/routes/` - SvelteKit file-based routing with authenticated/unauthenticated route groups
- `frontend/src/lib/components/` - Reusable UI components organized by feature
- `frontend/viewer/` - Separate FwLite viewer application with its own build system
- **Infrastructure**:
- `deployment/` - Kubernetes configurations for local, staging, and production environments
- `Tiltfile` - Local development orchestration with Docker and Kubernetes
- `hgweb/` - Mercurial web interface configuration
- `otel/` - OpenTelemetry collector configuration for monitoring
- **Additional Services**:
- `platform.bible-extension/` - Platform.Bible extension for integration
- `docs/` - Platform-specific developer setup guides
</repository_structure>

<dependencies_and_installation>
- **Prerequisites**:
- .NET SDK 9.0 for backend development
- Node.js >=20 and PNPM >=9 for frontend development
- Docker Desktop with Kubernetes enabled for local development
- Taskfile for task automation
- Tilt for development orchestration
- **Backend Dependencies**: Use `dotnet restore` in backend projects or `task api:dotnet -- restore`
- **Frontend Dependencies**: Use `pnpm install` in frontend directory or `task ui:install`
- **Initial Setup**: Run `task setup` to configure the development environment, including:
- Git configuration and submodule initialization
- Kubernetes namespace setup
- Test data download
- Local environment file creation
- **Development Environment**:
- `task up` starts the full stack with Tilt orchestration
- Docker Desktop manages containers and Kubernetes cluster
- Local services run on localhost with port forwarding for API access
</dependencies_and_installation>

<testing_instructions>
- **Backend Testing**:
- Framework: xUnit with categorized tests (Unit, Integration, FlakyIntegration)
- Run unit tests: `task test:unit` (excludes database and integration tests)
- Run integration tests: `task test:integration`
- Test organization: `backend/Testing/` with subdirectories by service/component
- Database tests require running infrastructure via `task test:unit-with-db`
Comment on lines +66 to +70
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Test categories list is incomplete and inaccurate.

The PR's automated review identified that the actual test categories in the repository differ from what's documented here. The repository uses Integration, FlakyIntegration, RequiresDb, and Slow category attributes, plus unit tests (no category attribute, run by default). The documentation currently omits RequiresDb and Slow, which are used in the codebase.

Apply this diff to correct the test categories:

- **Backend Testing**:
  - Framework: xUnit with categorized tests (Unit, Integration, FlakyIntegration)
+ **Backend Testing**:
+  - Framework: xUnit with categorized tests
+    - No category attribute: Unit tests (run by default with `task test:unit`)
+    - `Integration`: Integration tests (run with `task test:integration`)
+    - `FlakyIntegration`: Flaky integration tests
+    - `RequiresDb`: Tests requiring database (run with `task test:unit-with-db`)
+    - `Slow`: Slow-running tests

Committable suggestion skipped: line range outside the PR's diff.

🤖 Prompt for AI Agents 
In AGENTS.md around lines 66 to 70, the documented test categories are
incomplete: update the list to match the repository by replacing the current
categories with "Integration", "FlakyIntegration", "RequiresDb", and "Slow", and
clarify that unit tests have no category attribute and run by default; also
ensure the commands note that unit tests exclude database/integration tests and
that database tests require running infrastructure via `task test:unit-with-db`.

- **Frontend Testing**:
Comment on lines +70 to +71
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Clarify the distinction between unit, unit-with-db, and integration test commands.

The current text mentions task test:unit-with-db but doesn't clearly explain why or when to use each test command. Developers need to understand that test:unit-with-db is specifically for running tests marked with the RequiresDb trait.

Apply this diff to clarify the test command usage:

- **Backend Testing**:
  - Framework: xUnit with categorized tests (Unit, Integration, FlakyIntegration)
-  - Run unit tests: `task test:unit` (excludes database and integration tests)
+  - Run unit tests: `task test:unit` (excludes database, integration, and slow tests)
+  - Run database-dependent tests: `task test:unit-with-db` (runs tests marked with `RequiresDb`)

Committable suggestion skipped: line range outside the PR's diff.

🤖 Prompt for AI Agents 
In AGENTS.md around lines 70-71, the docs mention `task test:unit-with-db` but
don't explain the difference between test commands; update the text to clarify
that `task test:unit` runs pure unit tests, `task test:unit-with-db` runs unit
tests annotated with the RequiresDb trait against local/test DB infrastructure,
and `task test:integration` runs broader integration tests spanning services;
briefly state when to use each (use unit for fast isolated logic, unit-with-db
when a DB mock is insufficient and tests require real DB access, integration for
end-to-end scenarios) and include the `task test:unit-with-db` invocation note
about running infrastructure via `task test:unit-with-db`.

- E2E Testing: Playwright for end-to-end browser tests
- Run: `pnpm run test` or `task ui:playwright-tests`
- Configuration: `playwright.config.ts`
- Unit Testing: Vitest for component and utility testing
- Run: `pnpm run test:unit`
- Test files located in `frontend/tests/` and `frontend/viewer/tests/`
Comment on lines +75 to +77
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Clarify Vitest scope and location in the frontend architecture.

The current documentation implies that Vitest is used for general frontend unit testing, but the automated review found that Vitest exists only in frontend/viewer/ for that specific viewer application. The main frontend uses Playwright for E2E testing. This distinction is critical for developers to understand which testing tool applies to different parts of the codebase.

Apply this diff to clarify the Vitest and testing split:

- **Frontend Testing**:
  - E2E Testing: Playwright for end-to-end browser tests
    - Run: `pnpm run test` or `task ui:playwright-tests`
    - Configuration: `playwright.config.ts`
-  - Unit Testing: Vitest for component and utility testing
+  - Unit Testing: Vitest for FwLite viewer component and utility testing
    - Run: `pnpm run test:unit`
+    - Note: Vitest is configured in `frontend/viewer/` for the separate viewer application
+    - Main frontend components use Playwright for E2E testing; no dedicated unit test framework for general components

Committable suggestion skipped: line range outside the PR's diff.

🤖 Prompt for AI Agents 
In AGENTS.md around lines 75 to 77, the documentation incorrectly implies Vitest
is used across the frontend; update the text to explicitly state that Vitest is
only used for unit testing in frontend/viewer/ (with test files in
frontend/viewer/tests/ and run via pnpm run test:unit from that package), and
note that the main frontend uses Playwright for end-to-end testing (with its own
test commands and locations), so readers understand the split between Vitest
(viewer unit tests) and Playwright (main frontend E2E).

- **FwLite Testing**:
- .NET tests: `dotnet test FwLiteOnly.slnf` for FwLite-specific tests
- Separate test projects: `*.Tests` projects within `backend/FwLite/`
- **Test Categories**: Backend tests use attributes like `[Trait("Category", "Integration")]` to organize test execution
- **Browser Testing**: Playwright tests can be run with `--ui` flag for interactive debugging
</testing_instructions>

<pull_request_formatting>
</pull_request_formatting>
Comment on lines +85 to +86
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Remove or fill the empty <pull_request_formatting> section.

The section is empty and provides no guidance to developers. Either add content describing pull request formatting conventions or remove the section entirely.

Consider either:

  1. Adding PR formatting guidelines (commit message conventions, PR title/description format, change documentation, etc.), or
  2. Removing the empty section entirely.
-<pull_request_formatting>
-</pull_request_formatting>

or fill with appropriate content about PR conventions.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
<pull_request_formatting>
</pull_request_formatting>
🤖 Prompt for AI Agents 
In AGENTS.md around lines 85-86 the <pull_request_formatting> section is empty;
either remove that empty section tag or replace it with a concise PR formatting
guideline. If removing, delete the tag and any surrounding placeholder text; if
filling, add a short checklist describing expected PR title format, description
template, commit message style, required changelog/labels, reviewers, and
testing/CI requirements. Ensure whichever option you choose keeps the file
consistent with surrounding Markdown structure and references.