chore: setup copilot project instructions#683
Conversation
There was a problem hiding this comment.
Pull request overview
Adds GitHub Copilot “AI Agent Instructions” documentation to guide automated/code-assist changes across the Compass monorepo (project-level plus backend/frontend-specific context).
Changes:
- Introduces a project-level Copilot instructions document describing repo structure, stack, infra, CI/CD, and development guidelines.
- Adds backend-specific Copilot instructions covering server entrypoint, multi-agent architecture, DB layout, LLM/vector search integration, and testing commands.
- Adds frontend-specific Copilot instructions covering entrypoints, routing, chat architecture, state/auth/i18n/theming, env config, and testing commands.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
.github/copilot-instructions.md |
Project-wide Copilot guidance (structure/stack/infra/CI/dev guidelines). |
.github/copilot-instructions-backend.md |
Backend-specific Copilot guidance (FastAPI, agents, DBs, embeddings, tests). |
.github/copilot-instructions-frontend.md |
Frontend-specific Copilot guidance (React app structure, chat, env, tests). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - Tests alongside source files (`*_test.py`, `*.test.tsx`) | ||
| - No separate `tests/` directories | ||
| - Feature modules are self-contained with routes, services, models, and tests |
There was a problem hiding this comment.
This says there are no separate tests/ directories, but the repo contains dedicated test folders (e.g. backend/evaluation_tests/, backend/smoke_test/, frontend-new/test/smoke/). Please adjust this guideline (e.g., clarify that unit tests live alongside source, with smoke/e2e/evaluation tests in dedicated dirs).
| - Tests alongside source files (`*_test.py`, `*.test.tsx`) | |
| - No separate `tests/` directories | |
| - Feature modules are self-contained with routes, services, models, and tests | |
| - Unit tests live alongside source files (`*_test.py`, `*.test.tsx`) | |
| - Higher-level suites (smoke, e2e, evaluation) use dedicated test directories (e.g. `backend/evaluation_tests/`, `backend/smoke_test/`, `frontend-new/test/smoke/`) | |
| - Feature modules are self-contained with routes, services, models, and unit tests |
AGENTS.md
Outdated
|
|
||
| - Backend: see `backend/.env.example` | ||
| - Frontend: see env vars loaded in `frontend-new/src/envService.ts` | ||
| - Infrastructure: see `iac/env.template` for full reference |
There was a problem hiding this comment.
iac/env.template does not exist in this repo; the env template lives under iac/templates/env.template. Please fix this reference so contributors can find the correct file.
| - Infrastructure: see `iac/env.template` for full reference | |
| - Infrastructure: see `iac/templates/env.template` for full reference |
|
|
||
| ## Entry Point & Server | ||
|
|
||
| - **`backend/app/server.py`** — FastAPI application with async lifespan management. Initializes 4 MongoDB connections in parallel, validates environment, sets up CORS and Brotli middleware, and exposes the conversation API. |
There was a problem hiding this comment.
This claims the server “initializes 4 MongoDB connections in parallel”. In backend/app/server.py the DBs are obtained sequentially (4 awaits), and the parallel asyncio.gather runs index initialization for 3 DBs plus validate_taxonomy_model (not a fourth DB initialization). Please reword to match the actual startup behavior.
| - **`backend/app/server.py`** — FastAPI application with async lifespan management. Initializes 4 MongoDB connections in parallel, validates environment, sets up CORS and Brotli middleware, and exposes the conversation API. | |
| - **`backend/app/server.py`** — FastAPI application with async lifespan management. Obtains 4 MongoDB database handles, then runs index initialization for 3 of them in parallel alongside taxonomy model validation, validates environment, sets up CORS and Brotli middleware, and exposes the conversation API. |
| ## Vector Search & Embeddings | ||
|
|
||
| - **`backend/app/vector_search/`** — Template method pattern for occupation and skill search | ||
| - Embeds user input via Vertex AI (`textembedding-gecko` models) |
There was a problem hiding this comment.
The embeddings doc mentions Vertex AI “textembedding-gecko models”, but the backend is configured via EMBEDDINGS_MODEL_NAME (e.g. text-embedding-005 in backend/.env.example). Please update this to reflect the configurable model name (or correct the default) so the instructions stay accurate.
| - Embeds user input via Vertex AI (`textembedding-gecko` models) | |
| - Embeds user input via Vertex AI using the `EMBEDDINGS_MODEL_NAME` environment variable (see `backend/.env.example`, e.g. default `text-embedding-005`) |
| This is a monorepo with three main packages: | ||
|
|
||
| ``` | ||
| compass/ | ||
| ├── backend/ # Python/FastAPI REST API + multi-agent LLM system | ||
| ├── frontend-new/ # React/TypeScript SPA (chat UI) | ||
| ├── iac/ # Pulumi infrastructure-as-code (GCP) | ||
| └── .github/workflows # CI/CD pipelines | ||
| ``` |
There was a problem hiding this comment.
The repo structure snippet shows a compass/ top-level directory and also lists .github/workflows alongside the three packages. In this repo the top-level directories are backend/, frontend-new/, and iac/ directly at the root, so this tree (and the “three main packages” wording) is currently misleading. Please update the diagram/text to match the actual repository root layout.
.github/copilot-instructions.md
Outdated
| | LLM | Google Vertex AI (Gemini), structured output with Pydantic | | ||
| | Database | MongoDB (4 instances via Motor async driver) | | ||
| | Vector Search | MongoDB Atlas Search with Vertex AI embeddings | | ||
| | Frontend | React 18, TypeScript 5.4+, MUI 5, Webpack 5 | |
There was a problem hiding this comment.
Tech stack table lists "MUI 5", but frontend-new/package.json currently depends on @mui/material v7.x. Please update the stated MUI version (or make it version-agnostic) to avoid confusing guidance.
| | Frontend | React 18, TypeScript 5.4+, MUI 5, Webpack 5 | | |
| | Frontend | React 18, TypeScript 5.4+, MUI, Webpack 5 | |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 4 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| Compass is an AI-powered chatbot that helps job-seekers discover and articulate their skills using the ESCO (European Skills, Competences, Qualifications and Occupations) taxonomy. Users describe their work experiences in a conversational interface, and the system maps those experiences to standardized occupations and skills. | ||
|
|
||
| > **Terminology note**: "Agent" in this codebase refers to a **Compass conversation agent** — a backend Python class that handles one phase of the user's chat conversation (e.g., welcome, experience collection, skills exploration, farewell). These are *not* AI coding agents. See the [backend instructions](copilot-instructions-backend.md) for the full agent architecture. |
There was a problem hiding this comment.
The link to the backend instructions is incorrect. The file is located at instructions/backend.instructions.md, not copilot-instructions-backend.md. This broken link will prevent users from navigating to the backend-specific instructions.
| > **Terminology note**: "Agent" in this codebase refers to a **Compass conversation agent** — a backend Python class that handles one phase of the user's chat conversation (e.g., welcome, experience collection, skills exploration, farewell). These are *not* AI coding agents. See the [backend instructions](copilot-instructions-backend.md) for the full agent architecture. | |
| > **Terminology note**: "Agent" in this codebase refers to a **Compass conversation agent** — a backend Python class that handles one phase of the user's chat conversation (e.g., welcome, experience collection, skills exploration, farewell). These are *not* AI coding agents. See the [backend instructions](instructions/backend.instructions.md) for the full agent architecture. |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 4 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 6 out of 7 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| ## Entry Point & Server | ||
|
|
||
| - **`backend/app/server.py`** — FastAPI application with async lifespan management. Initializes 4 MongoDB connections in parallel, validates environment, sets up CORS and Brotli middleware, and exposes the conversation API. |
There was a problem hiding this comment.
backend/app/server.py does not initialize 4 MongoDB connections in parallel; it fetches 4 DB handles and then runs initialization for application/userdata/metrics plus taxonomy validation concurrently. Please adjust this sentence to reflect the actual startup behavior so the instructions remain accurate.
| - **`backend/app/server.py`** — FastAPI application with async lifespan management. Initializes 4 MongoDB connections in parallel, validates environment, sets up CORS and Brotli middleware, and exposes the conversation API. | |
| - **`backend/app/server.py`** — FastAPI application with async lifespan management. Fetches 4 MongoDB DB handles and then concurrently initializes the application/userdata/metrics databases and runs taxonomy validation, validates environment, sets up CORS and Brotli middleware, and exposes the conversation API. |
No description provided.