Add Copilot instructions and AGENTS.md guide for repository

[Copilot]

Configures GitHub Copilot agent instructions per best practices to provide context-aware code suggestions aligned with repository conventions.

Changes

• Created .github/copilot-instructions.md documenting:

  • Tech stack: Java 21, Spring Boot 3.5.0, Maven, PostgreSQL, WebSockets, JWT, OAuth 2.0, Redis
  • Build/test commands: mvn clean install, mvn spring-boot:run, mvn test
  • Project structure: Auth module (lowercase controllers/, services/) vs core module (capitalized Controllers/, Services/)
  • API conventions: /api/auth and /api base paths, standard HTTP status codes
  • Security patterns: JWT for API auth, OAuth 2.0 for social login, token/session-based WebSocket auth
  • Database: Flyway migration patterns (V{number}__{description}.sql)
  • Code patterns: Lombok annotations (@Slf4j), Spring conventions, validation with @Valid
  • Environment variables: Corrected to use underscores (GOOGLE_CLIENT_ID, GOOGLE_SECRET_ID)

• Created AGENTS.md (in root directory) following the agents.md open format:

  • Simple purpose statement: "A guide for AI coding agents working on this repository"
  • Setup commands: Maven commands for install, run, test, and coverage
  • Tech stack: Java 21, Spring Boot, PostgreSQL, JWT, OAuth 2.0, WebSocket, Redis, Maven
  • Code style: Lombok usage, Spring Boot conventions, dependency injection, validation
  • Project structure: Auth and core module organization with naming conventions
  • Database migrations: Flyway location, naming convention, and rules
  • API conventions: Endpoint patterns and HTTP status codes
  • WebSocket: Real-time messaging configuration
  • Security: JWT, OAuth 2.0, environment variables (corrected to use underscores)
  • Testing: Location, frameworks (JUnit 5, Mockito, Spring Boot Test)

The AGENTS.md format is concise and practical, following the open standard used by 60k+ open-source projects, making it compatible with various AI coding tools including GitHub Copilot, Cursor, VS Code, Zed, and many others.

These configurations enable Copilot to maintain consistency with existing patterns when suggesting code changes and provide specialized assistance for different development tasks.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>✨ Set up Copilot instructions</issue_title>
<issue_description>Configure instructions for this repository as documented in Best practices for Copilot coding agent in your repository.

</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes ✨ Set up Copilot instructions #39

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[fred-maina]

@copilot Also add an AGENTS.md find more info here https://agents.md

[Copilot]

@copilot Also add an AGENTS.md find more info here https://agents.md

Added AGENTS.md with 8 specialized custom agents for the repository (commit e8c388d). The file defines experts for Spring Boot, Database Migrations, WebSocket, Security, Testing, REST API, Maven, and Code Review tasks.

[fred-maina]

@copilot Place this on root and get more info from https://agents.md/
On why this file exists and where to place it and what to put in

[Copilot]

@copilot Place this on root and get more info from https://agents.md/
On why this file exists and where to place it and what to put in

Moved AGENTS.md to root directory (commit 1b54fa5). Added documentation explaining:

• Why it exists: Defines custom AI agents for GitHub Copilot Workspace with specialized domain knowledge
• Where to place it: Root directory for automatic discovery by AI tools
• What to put in it: Agent definitions with specializations and repository-specific context

The file now includes an "About This File" section with purpose, location guidance, usage instructions, and maintenance guidelines.

[fred-maina]

Remove the about this file just write its purpose. Use this AGENTS.md
A simple, open format for guiding coding agents,
used by over 60k open-source projects.

Think of AGENTS.md as a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project.

Explore Examples
View on GitHub

AGENTS.md

Setup commands

• Install deps: pnpm install
• Start dev server: pnpm dev
• Run tests: pnpm test

Code style

• TypeScript strict mode
• Single quotes, no semicolons
• Use functional patterns where possible
  Why AGENTS.md?
  README.md files are for humans: quick starts, project descriptions, and contribution guidelines.

AGENTS.md complements this by containing the extra, sometimes detailed context coding agents need: build steps, tests, and conventions that might clutter a README or aren’t relevant to human contributors.

We intentionally kept it separate to:

Give agents a clear, predictable place for instructions.

Keep READMEs concise and focused on human contributors.

Provide precise, agent-focused guidance that complements existing README and docs.

Rather than introducing another proprietary file, we chose a name and format that could work for anyone. If you’re building or using coding agents and find this helpful, feel free to adopt it.

One AGENTS.md works across many agents
Your agent definitions are compatible with a growing ecosystem of AI coding agents and tools:

Semgrep
Windsurf logo
Windsurf
from Cognition
goose
Gemini CLI
from Google
Jules
from Google
Ona logo
Ona
Codex
from OpenAI
VS Code logo
VS Code
Zed
Devin logo
Devin
from Cognition
Factory
Semgrep
Windsurf logo
Windsurf
from Cognition
goose
Gemini CLI
from Google
Jules
from Google
Ona logo
Ona
Codex
from OpenAI
VS Code logo
VS Code
Zed
Devin logo
Devin
from Cognition
Factory
Kilo Code
Cursor
Warp
Amp
Autopilot & Coded Agents
from UiPath
RooCode
Coding agent
from GitHub Copilot
opencode
Aider
Phoenix
Kilo Code
Cursor
Warp
Amp
Autopilot & Coded Agents
from UiPath
RooCode
Coding agent
from GitHub Copilot
opencode
Aider
Phoenix
View all supported agents
Examples

Sample AGENTS.md file

Dev environment tips

• Use pnpm dlx turbo run where <project_name> to jump to a package instead of scanning with ls.
• Run pnpm install --filter <project_name> to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
• Use pnpm create vite@latest <project_name> -- --template react-ts to spin up a new React + Vite package with TypeScript checks ready.
• Check the name field inside each package's package.json to confirm the right name—skip the top-level one.

Testing instructions

• Find the CI plan in the .github/workflows folder.
• Run pnpm turbo run test --filter <project_name> to run every check defined for that package.
• From the package root you can just call pnpm test. The commit should pass all tests before you merge.
• To focus on one step, add the Vitest pattern: pnpm vitest run -t "<test name>".
• Fix any test or type errors until the whole suite is green.
• After moving files or changing imports, run pnpm lint --filter <project_name> to be sure ESLint and TypeScript rules still pass.
• Add or update tests for the code you change, even if nobody asked.

PR instructions

• Title format: [<project_name>] <Title>
• Always run pnpm lint and pnpm test before committing.
  openai/codex
  General-purpose CLI tooling for AI coding agents.

Rust
Contributor avatarContributor avatarContributor avatar

• 271
  apache/airflow
  Platform to programmatically author, schedule, and monitor workflows.

Python
Contributor avatarContributor avatarContributor avatar

• 4023
  temporalio/sdk-java
  Java SDK for Temporal, workflow orchestration defined in code.

Java
Contributor avatarContributor avatarContributor avatar

• 115
  PlutoLang/Pluto
  A superset of Lua 5.4 with a focus on general-purpose programming.

C++
Contributor avatarContributor avatarContributor avatar

• 8
  View 60k+ examples on GitHub
  How to use AGENTS.md?

1. Add AGENTS.md
   Create an AGENTS.md file at the root of the repository. Most coding agents can even scaffold one for you if you ask nicely.
2. Cover what matters
   Add sections that help an agent work effectively with your project. Popular choices:

Project overview
Build and test commands
Code style guidelines
Testing instructions
Security considerations
3. Add extra instructions
Commit messages or pull request guidelines, security gotchas, large datasets, deployment steps: anything you’d tell a new teammate belongs here too.
4. Large monorepo? Use nested AGENTS.md files for subprojects
Place another AGENTS.md inside each package. Agents automatically read the nearest file in the directory tree, so the closest one takes precedence and every subproject can ship tailored instructions. For example, at time of writing the main OpenAI repo has 88 AGENTS.md files.
About
AGENTS.md emerged from collaborative efforts across the AI software development ecosystem, including OpenAI Codex, Amp, Jules from Google, Cursor, and Factory.

We’re committed to helping maintain and evolve this as an open format that benefits the entire developer community, regardless of which coding agent you use.

FAQ
Are there required fields?
No. AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide.
What if instructions conflict?
The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything.
Will the agent run testing commands found in AGENTS.md automatically?
Yes—if you list them. The agent will attempt to execute relevant programmatic checks and fix failures before finishing the task.
Can I update it later?
Absolutely. Treat AGENTS.md as living documentation.
How do I migrate existing docs to AGENTS.md?
Rename existing files to AGENTS.md and create symbolic links for backward compatibility:

mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md
How do I configure Aider?
Configure Aider to use AGENTS.md in .aider.conf.yml:

read: AGENTS.md
How do I configure Gemini CLI?
Configure Gemini CLI to use AGENTS.md in .gemini/settings.json:

{ "contextFileName": "AGENTS.md" }
AGENTS.md
An open community standard stewarded by the Agentic AI Foundation (AAIF)

[Copilot]

Simplified AGENTS.md following the agents.md format (commit c501e6d). Removed the "About This File" section and restructured with concise, practical sections: Setup commands, Tech stack, Code style, Project structure, Database migrations, API conventions, WebSocket, Security, and Testing. Also fixed environment variable names to use underscores (commit 3100eff).