Introducing AGENTS.md #48
+63
−1
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,61 @@ | ||
| # Agent Instructions Practices for ROOST Projects | ||
|
|
||
|
|
||
| ## Part 1: The AGENTS.md Standard | ||
|
|
||
| [AGENTS.md](https://github.com/agentsmd/agents.md) is an open format for guiding AI coding agents, governed by the [Agentic AI Foundation](https://aaif.io) under the Linux Foundation. It is supported by GitHub Copilot, OpenAI Codex, Cursor, Gemini/Jules, Claude Code, and others. | ||
|
|
||
| Where `README.md` is for humans, `AGENTS.md` is for machines. | ||
|
|
||
| ### File setup | ||
| - Place an `AGENTS.md` at the repo root alongside `README.md`. | ||
| - Create symlinks for tools that use their own filenames: `ln -s AGENTS.md CLAUDE.md` and `ln -s AGENTS.md .github/copilot-instructions.md`. | ||
| - For monorepos, place additional `AGENTS.md` files in subdirectories. Agents read the nearest file in the directory tree; the closest one takes precedence. | ||
|
There was a problem hiding this comment. i assume you should also remember to symlink these files as well to the appropriate spot |
||
|
|
||
| ### Recommended content | ||
| The standard is schema-free using plain Markdown and any headings you like. The community consensus is to cover: | ||
| - Setup and build commands | ||
| - Testing instructions | ||
| - Code style guidelines | ||
| - Project structure | ||
| - Security considerations | ||
| - PR and commit guidelines | ||
|
|
||
| ### Principles from the standard | ||
| - Lead with commands, not explanations. | ||
| - Treat `AGENTS.md` as living documentation. Update it as conventions change. | ||
| - The nearest `AGENTS.md` to the edited file wins; explicit user prompts override everything. | ||
|
|
||
| ### Related: Agent Skills | ||
| The `.agents/skills/` directory is an adjacent open standard for packaging specialized agent capabilities (scripts, templates, reference docs) as reusable SKILL.md files. ROOST may adopt skills for specialized workflows in the future; this is out of scope for now. | ||
|
|
||
| --- | ||
|
|
||
| ## Part 2: ROOST-Specific Requirements | ||
|
|
||
| ROOST repos must include an `AGENTS.md` that covers the full development lifecycle. This ensures contributors' agents produce work that meets project standards from the first attempt. | ||
|
|
||
| ### Minimum content by SDLC area | ||
|
|
||
| | Area | What to include | Priority | | ||
|
There was a problem hiding this comment. Very minor style comment: group rows by priority (so P0s at the top) and alphabetize within priority to help make sure all of the most important pieces are specified. I realize this breaks convention with the README file |
||
| | ------- | --------- | -------- | | ||
| | Architecture | Key directories, module boundaries, where new code belongs. Point to reference files, flag legacy files to avoid | P0 | | ||
| | Design | API conventions, data model conventions | P1 | | ||
| | Build and run | Exact commands to install deps, build, and start the project | P0 | | ||
| | Testing | Commands for unit tests, integration tests, lint, type checks. Both single-file and full-suite | P0 | | ||
| | Code style | Language version, framework version. Reference linter/formatter config | P1 | | ||
| | Code review | PR expectations: small diffs, descriptive titles, test coverage, changelog entries if applicable | P1 | | ||
|
There was a problem hiding this comment. Thoughts on making this a P0? It seems important to have consistent information in PRs since this is an OSS project There was a problem hiding this comment. +1, stuff like change log is also commonly forgotten |
||
| | CI | Which CI checks run on PRs and how to run them locally before pushing | P0 | | ||
| | CD | Release process, semver tagging convention, environments. What agents must not touch (e.g. production deploy scripts, release signing) | P1 | | ||
| | Security | No secrets in code, no disabling lint rules, check new packages for CVEs. Link to `SECURITY.md` if present | P0 | | ||
| | Dependencies | Rules for adding new deps (license, review process). What requires human approval | P1 | | ||
|
|
||
|
There was a problem hiding this comment. Suggest adding some guidance on things not to do like:
|
||
| ### ROOST guiding principles | ||
|
|
||
| | Item | Description/Notes | | ||
| | ------- | --------- | | ||
| | Commands over prose | Agents act on commands. Prefer `npm run test -- path/to/file` over descriptive paragraphs | | ||
| | Same review bar | PRs authored with agent assistance are held to the same standards as any other PR | | ||
| | Boundaries with alternatives | When stating a restriction, always provide the alternative path | | ||
| | Iterate over time | Start minimal. When you give agents the same instruction twice, add it to the file | | ||
| | Contributors update AGENTS.md | When a contributor finds a gap, they are encouraged to update `AGENTS.md` as part of their PR | | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nice, this is something i was going to suggest though wasn't sure if it worked or not. looks like it does!!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
symlinks can be challenging Git + symlink behavior varies by configuration and OS - so using them in this way can lead to inconsistent experiences for developers.
That said - I think this is a reasonable approach for now and we can always look at alternatives if it becomes a problem in future.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This has worked for me. If there are better methods, please let me know and I can update.
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I did some googling. Looks like the problem in Windows. There is no clean option. I will wait to get some additional thoughts.