docs: create AGENTS.md with CI-enforced rules for coding agents

[sergio-sisternes-epam]

Summary

Creates AGENTS.md at the repository root -- the single authoritative entry point for AI coding agents working in this repository.

Closes #695

What this file provides

A concise, machine-scannable contract covering every CI-enforced rule that agents could violate:

Section	What it covers
Setup	Exact uv sync and verification commands
Before Every Commit	5-step checklist with copy-pasteable lint commands
Code Conventions	YAML I/O rule, path portability, path security, console output, ASCII encoding
CLI Conventions	Help text standards, docs sync requirement
Testing Conventions	Directory structure, mock rules, CI command
Security	CodeQL, secrets policy, path traversal guards
PR Hygiene	Branch naming, CHANGELOG, test script policy
Per-Module Rules	Pointer table to all 6 .github/instructions/*.instructions.md files

Design decisions

1. Top-level entry point, not a duplicate -- AGENTS.md contains directives and points to .github/instructions/ for detailed per-module rules. No content duplication.

2. ASCII-only -- the entire file stays within printable ASCII (U+0020-U+007E), consistent with the encoding rules it documents.

3. 103 lines -- concise and scannable. Agents get rules, not rationale.

4. CLI docs path corrected -- issue [FEATURE] Create root AGENTS.md documenting all CI-enforced rules for coding agents #695 referenced docs/cli-reference.md which doesn't exist. Used the actual path: docs/src/content/docs/reference/cli-commands.md.

5. .gitignore updated -- AGENTS.md was in .gitignore (local development section). Added !/AGENTS.md negation to track the root file while keeping subdirectory AGENTS.md files ignored.

Changes

File	Change
AGENTS.md	New file (103 lines)
.gitignore	Added !/AGENTS.md negation pattern
CHANGELOG.md	Added entry under [Unreleased] > Added

Validation

• All referenced paths in AGENTS.md exist in the repository
• File is ASCII-only (verified with grep -Pn '[^\x09\x0a\x0d\x20-\x7e]')
• All 3,790 unit tests pass (uv run pytest tests/unit tests/test_console.py -n auto --dist worksteal)
• CHANGELOG entry follows Keep a Changelog format

[Copilot]

Pull request overview

Adds a repository-root AGENTS.md intended to be the authoritative, agent-readable checklist of CI-enforced rules and conventions for working in this codebase (closing #695), and ensures it is tracked and documented.

Changes:

• Add new AGENTS.md with setup steps, pre-commit checklist, and pointers to .github/instructions/*.
• Update .gitignore to unignore /AGENTS.md while keeping other AGENTS.md files ignored.
• Add a changelog entry under ## [Unreleased].

Reviewed changes

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

File	Description
AGENTS.md	New agent contract/checklist and pointers to detailed instruction files.
.gitignore	Ensures the root AGENTS.md is tracked despite a broader ignore pattern.
CHANGELOG.md	Records the addition of AGENTS.md under Unreleased/Added.

[danielmeppiel]

Apm Review Panel — REQUEST CHANGES (revised: dogfood-first)

Updated 2026-04-20: original two-condition ask superseded by the dogfood-first reframe below. Sergio, sincere apology for the goalpost shift — see context at the bottom of this comment.

Synthesis after a second pass with the panel: the right move is bigger than "swap one hand-authored file for another." APM exists to compile one source into N agent-tool formats. This repo should prove that on its own contributing guide.

The dogfood-first ask

1. Move the contributing-instructions content into .apm/instructions/contributing.md (or split into focused files under .apm/instructions/). Single source of truth — the same primitive we ship to every APM user.

2. Let apm compile generate the agent-tool files, not human keyboards:

   Output	Reader(s)	APM today
   AGENTS.md	Codex CLI, Cursor, Aider, OpenAI Codex, Copilot (root fallback)	Already supported
   CLAUDE.md	Claude Code (highest-share agent tool)	Already supported
   .github/instructions/*.instructions.md	GitHub Copilot (scoped, applyTo:)	Already supported
   .github/copilot-instructions.md	GitHub Copilot (root prose)	GAP — see apm compile should emit .github/copilot-instructions.md (dogfood gap) #792

3. Delete .github/copilot-instructions.md as a hand-authored file once compile fills the same role. Single source, zero drift, self-evident dogfooding on every PR.

4. Inline fix: the Setup section's uv sync --extra dev --extra build is the CI command. Default for contributors should be uv sync --extra dev; mention --extra build only as "if you need to build the release binary."

Why the reframe

Three things made the panel pivot:

Format fragmentation isn't slowing down. AGENTS.md is OpenAI-aligned. CLAUDE.md is Claude Code (highest market share). Copilot reads scoped .github/instructions/*.instructions.md (most powerful) plus root AGENTS.md. New agent tools ship every quarter. Picking a winner ages badly. APM's whole reason to exist is "don't pick — compile."

APM already supports two of the three formats out of the box. apm compile emits AGENTS.md and CLAUDE.md from .apm/instructions/. We're literally one compile target away (#792, filed as good first issue) from making this PR a one-line .apm/instructions/contributing.md add that generates everything downstream.

The release-notes story changes shape entirely. Original PR: "APM the OSS project ships an AGENTS.md." Revised PR: "APM the OSS project ships its contributing guide as .apm/instructions/contributing.md and compiles it into AGENTS.md, CLAUDE.md, AND .github/copilot-instructions.md — the README claim is now provable on our own repository." Every contributor watches the demo on their next PR.

Suggested sequence

1. Land apm compile should emit .github/copilot-instructions.md (dogfood gap) #792 first (apm compile → .github/copilot-instructions.md). Small lift, well-scoped, good first issue.
2. Rebase this PR on top: introduce .apm/instructions/contributing.md, run apm compile, commit the generated AGENTS.md + CLAUDE.md + regenerated .github/copilot-instructions.md, delete the hand-authored copilot-instructions content (it now lives in the compile source).
3. Add a CI staleness check (apm compile --check or equivalent) so generated files can never drift from the source.
4. Reframe CHANGELOG: "APM now compiles its own contributing guide. One source, three agent-tool outputs."

To Sergio

I owe you an apology. My first pass on this PR asked for a content port; my second pass asked for the legacy file deleted; this third pass moves the goalposts again to "use APM itself for this." That's three iterations of feedback and I'm aware that's painful.

The reason I think it's worth the third iteration: the original direction was right — close issue #695 — but the implementation shape of "hand-author another instructions file" is the exact problem APM was built to solve. If we ship that shape, every reviewer who reads our repo sees a contradiction. Whereas if we ship the dogfood shape, every reviewer sees the proof.

If you'd rather hand off, ping me and I'll take it from here. If you want to stay with it, #792 is the prerequisite — happy to pair on it or have a maintainer pick it up so this PR isn't blocked on it for long.

Either way, thank you for the patience and for raising the issue in the first place. Closing #695 is the right outcome; just need to land it as a proof-of-product rather than a doc add.

---

Earlier panel feedback (still partially applies):

• Original two-condition ask: port content from .github/copilot-instructions.md + delete the legacy file. Subsumed by the dogfood ask above (the same content moves, just into .apm/instructions/ instead of AGENTS.md).
• --extra build setup-hint fix still applies as-is.

[danielmeppiel]

Strategic REQUEST CHANGES — full reasoning in the panel verdict above (#754 (comment)).

TL;DR: don't hand-author AGENTS.md. Move the contributing-instructions content into .apm/instructions/contributing.md and let apm compile generate AGENTS.md, CLAUDE.md, and .github/copilot-instructions.md (the last one is the dogfood gap I just filed as #792, marked good-first-issue). Then delete .github/copilot-instructions.md as a hand-authored file.

Sequence: land #792 first (small lift), rebase this PR on top so it ships as proof-of-product rather than a doc add. Release-notes story becomes 'APM now compiles its own contributing guide — one source, three agent-tool outputs.'

Plus one inline fix: the Setup section's uv sync --extra dev --extra build is the CI command. Default for human contributors should be uv sync --extra dev (--extra build only when building the release binary).

Sergio — apology for the third iteration of feedback shift is in the panel comment. Offer to hand off stands. Either way, thank you for raising #695 in the first place; closing it is the right outcome.

[sergio-sisternes-epam]

Closing in favour of the dogfood-first approach.

After re-reading the panel review and #792, hand-authoring AGENTS.md is the wrong shape for this repo — every reviewer who opens our tree would see APM's core value prop (one source, many agent-tool outputs) contradicted on the front page.

Instead of splitting the work into "land #792, then port AGENTS.md content," I'd like to go one step further and turn microsoft/apm's entire existing primitive surface (.github/instructions/*, .github/prompts/*, .github/chatmodes/*, .github/skills/*, .github/agents/*, plus the contributing prose currently in .github/copilot-instructions.md) into a first-class APM package — the apm-for-apm package. That package becomes:

• The proof-of-product demo every contributor sees on their next PR.
• The reference implementation other repos can copy-paste from.
• The forcing function for apm compile should emit .github/copilot-instructions.md (dogfood gap) #792 (without .github/copilot-instructions.md as a compile target, the package can't fully replace what's in-tree today).

Will draft a fresh issue scoping that package (structure, compile targets, dependencies on #792, CI staleness guard, migration plan) and link it here once it's up. #695 stays open as the "root AGENTS.md exists" outcome — it'll close automatically when the new package lands and apm install generates AGENTS.md from the compiled primitives.

Sergio closing this PR; happy to pick up #792 as the prerequisite or pair on it.