Enable external references in AGENTS.md

[almirsarajcic]

Resolves #832.

Thought I'd need to learn TypeScript for this, but simple English suffices. 🤷

Experimented for a while with different system prompts, and this one was the most concise one that worked.

Here are two examples:

A real-world example from one of my projects.

https://dev.opencode.ai/s/hmPNhxY6

AGENTS.md:

# AGENTS.md

@codegen/rules/RULES.md - read the file immediately - CRITICAL
then load any referenced file inside it on a need-to-know basis

codegen/rules/RULES.md:

# Rules Index

Say "HELLO" at the start of every message!

This directory provides centralized development rules for any repository that includes these rules via symbolic link. Works with Claude Code and other AI assistants.

## Rule System Structure

Each rule file contains specific guidance for different aspects of development. Rules are organized by domain and responsibility:

- **@phoenix.md** - Phoenix framework development, LiveView, contexts, schemas, generators, PubSub, database operations
- **@elixir-code-generation.md** - Elixir code quality, specs, types, proper patterns, avoiding redundancy
- **@elixir-readability.md** - Code formatting, sorting, pipe usage, variable naming, structure organization
- **@elixir-error-handling.md** - Error patterns, exception handling, validation approaches
- **@elixir-ci.md** - Testing, CI failures, code coverage, formatting issues, database test problems
- **@git.md** - Read-only git operations, viewing repository state, prohibited write operations
- **@planning.md** - Feature planning, development plans, documentation, project stages organization
- **@project-structure.md** - Directory organization, file naming, module placement conventions
- **@javascript-code-generation.md** - JavaScript/TypeScript patterns, LiveView hooks, frontend development
- **@i18n.md** - Internationalization patterns, gettext workflow, translation management
- **@github-workflows.md** - GitHub workflows with CI/CD patterns, GitHub Actions, deployment automation
- **@wallaby.md** - Browser testing, end-to-end testing, ChromeDriver usage
- **@npm-packages.md** - Package management, JavaScript dependencies in Phoenix projects
- **@comments.md** - Code documentation, when to add comments, documentation standards

...

codegen/rules/github-workflows.md:

# GitHub Workflows

Use for GitHub workflow and CI/CD pipeline configuration and usage.

- Update workflows exclusively by editing `.github/github_workflows.ex` file.
- After changing file `.github/github_workflows.ex` make sure to run `mix github_workflows.generate` command so that files in the `.github/workflows` directory reflect those changes.
- Remove directory `.github/workflows` before running `mix github_workflows.generate` to ensure stale workflows are removed after changing workflows in the input file.
- Prettier does not share steps with Elixir jobs, so don't refactor it to call `elixir_job/2` function.

https://dev.opencode.ai/s/hmPNhxY6

A simple one that I used to test this initially while working on this PR.

https://dev.opencode.ai/s/z1hfn6W1

AGENTS.md:

Use the following files to know how to handle various tasks:
@rules/general.md - everyday interactions
@rules/elixir.md - writing Elixir code

rules/elixir.md:

mention you're an Alchemist when writing Elixir code

rules/general.md:

respond only in uppercase letters (scream)

With a more elaborate system prompt, I was able to have uppercase, but it's too much of the space in the context window wasted on just file references.

https://dev.opencode.ai/s/55t579g1

# AGENTS.md File References (CRITICAL)
IMPORTANT: AGENTS.md files use @ symbols to reference external instruction files. You MUST handle these references properly:

When you see lines like:
- @rules/general.md - everyday interactions
- @path/to/file.md - specific domain rules

You MUST:
1. IMMEDIATELY read these referenced files using the Read tool when the current task relates to their description
2. Treat the content of referenced files as if it were directly included in AGENTS.md
3. Follow @ references RECURSIVELY - if a referenced file contains more @ references, read those too (up to 5 levels deep)
4. Track which files you've loaded to avoid circular references

Example: If the user asks you to write Elixir code and AGENTS.md contains "@rules/elixir.md - writing Elixir code", you MUST read rules/elixir.md BEFORE writing any Elixir code. The rules in that file are MANDATORY to follow.

This is NOT optional - these referenced files contain critical instructions that you must follow for the project.

However, with that in anthropic.txt, the other example didn't work until I explicitly mentioned that wasn't the way we deal with GitHub workflows.

https://dev.opencode.ai/s/H80UKiOk

so in the end I think I should just write better rule files descriptions to make Claude load them when necessary.

[thdxr]

hey we're avoiding messing with system prompts from anthropic - it's unclear how introducing changes impacts behavior