Skip to content

chore: add AGENTS.md files#2608

Merged
fortuna merged 9 commits intomasterfrom
add-agents-md
Feb 23, 2026
Merged

chore: add AGENTS.md files#2608
fortuna merged 9 commits intomasterfrom
add-agents-md

Conversation

@fortuna
Copy link
Collaborator

@fortuna fortuna commented Aug 21, 2025

I'm hoping this will make it easier to use AI agents.

@fortuna fortuna requested a review from a team as a code owner August 21, 2025 23:18
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull Request Overview

This PR adds documentation files for AI agents across the Outline monorepo to improve development workflow and onboarding. The documentation provides structural overviews, build instructions, and development guidelines for each major component.

  • Added AGENTS.md files to root directory and three main components (client, server_manager, infrastructure)
  • Documented directory structures, key technologies, and build/test commands for each component
  • Provided comprehensive guide for the custom npm run action build system

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File Description
AGENTS.md Root-level guide introducing the monorepo structure and common npm run action commands
client/AGENTS.md Client-specific documentation covering Electron, Cordova, and web development workflows
server_manager/AGENTS.md Server Manager documentation for web and Electron app development
infrastructure/AGENTS.md Infrastructure documentation explaining the build system and action creation

Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.

@fortuna fortuna marked this pull request as draft August 21, 2025 23:19
Copy link
Contributor

@daniellacosse daniellacosse left a comment

Choose a reason for hiding this comment

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

This is a good start. FYI, you've also been using github copilot - I don't think it supports AGENTS.md (they only crawl the files they're told to crawl), but I think you can add a file at .github/copilot-instructions.md and simply point it to the AGENTS.md file. Something like this to start:

# Copilot Instructions

## Project Overview
This project contains an architectural overview and rules of conduct in several `AGENTS.md` files.

## File Locations
- `AGENTS.md`
- `cilent/AGENTS.md`
- `infrastruction/AGENTS.md`
- `server_manager/AGENTS.md`

## Expectations
Always reference `AGENTS.md` for guidance on:
- Project structure
- Common concepts
- Technologies uesd
- Additional reosources

@fortuna
Copy link
Collaborator Author

fortuna commented Aug 22, 2025

Thanks for the feedback. I put this in draft because I realized that there's too much overlap with the README files. I don't think it makes sense to maintain both.

I think a better approach will be to cleanup the READMEs to make it more helpful for both humans and AI, and create symlinks from AGENTS.md to the README.

I haven't been using copilot to generate code, so it doesn't matter much to me, but we could also add the copilot file as a symlink.

@daniellacosse
Copy link
Contributor

Thanks for the feedback. I put this in draft because I realized that there's too much overlap with the README files. I don't think it makes sense to maintain both.

I think a better approach will be to cleanup the READMEs to make it more helpful for both humans and AI, and create symlinks from AGENTS.md to the README.

I haven't been using copilot to generate code, so it doesn't matter much to me, but we could also add the copilot file as a symlink.

I like this approach for now, though I think people have been decoupling them because it allows human-facing documentation to be warmer/fuller (more human-friendly) while agent-facing documentation can be specifically optimized for LLMs (sometimes with weirdly specific or redundant phrasing they respond better to)

- Replace README symlinks with proper AI agent guidance in root,
  client/, server_manager/, and infrastructure/
- Covers build system, commands, architecture, product concepts,
  and links to subdirectory AGENTS.md files for incremental disclosure

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
fortuna and others added 3 commits February 22, 2026 14:26
Client is fully on Lit; server_manager still has legacy Polymer
components in /www/ui_components/ being migrated.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
@fortuna fortuna removed the request for review from jyyi1 February 22, 2026 19:33
@fortuna fortuna marked this pull request as ready for review February 22, 2026 19:33
@fortuna fortuna requested a review from a team as a code owner February 22, 2026 19:33
fortuna and others added 3 commits February 22, 2026 14:34
- Fix "ommitted" typo in AGENTS.md
- Add per-platform packaging output formats and notes to AGENTS.md
- Add missing testing section to README.md

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
@fortuna
Copy link
Collaborator Author

fortuna commented Feb 22, 2026

@ohnorobo this is ready for review. I've fixed a bunch of things and improved it.

Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull request overview

Copilot reviewed 7 out of 10 changed files in this pull request and generated 2 comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@fortuna fortuna enabled auto-merge (squash) February 23, 2026 16:26
@fortuna fortuna disabled auto-merge February 23, 2026 16:27
@fortuna fortuna merged commit 6affaf2 into master Feb 23, 2026
23 checks passed
@fortuna fortuna deleted the add-agents-md branch February 23, 2026 16:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants