Add AGENTS.md for AI coding agents constrained by contribution+AI gui…

[miqui]

…delines

• no schema changes are needed for this pull request

[miqui]

Please refer to : https://agents.md/. This should explain the impetus for this PR.

Verify important: We have not merged (but it is ready ) the AI policy for the this project. I drafted this AGENTS.md file so that it follows our AI policy once it is officially merged. Adding agentic governance to the project so that future contributions are easier to manager by our human maintainers.

AGENTS.md provide a single, predictable place to read project instructions before they act.

[miqui]

in WIP: forgot to consider: https://github.com/OAI/OpenAPI-Style-Guide

[miqui]

Note the below is a test flow for someone contributing a PR to fix a typo:

The active dev branches are v3.1-dev, v3.2-dev, and v3.3-dev. Here's the workflow for a typo fix, per this repo's contribution process and AGENTS.md:

1. Find where the typo lives. Check src/oas.md on the earliest active dev branch that has the typo — start with v3.1-dev. You target the earliest line because maintainers merge dev branches forward (3.1 → 3.2 → 3.3), so the fix propagates automatically. Never edit versions/*.md — those are published artifacts.
2. Skip the issue. A typo is an "obviously small" change, so you can go straight to a PR — no issue or discussion needed. It's editorial, so it's fine even for a patch line.
3. Branch from the right base (working from your fork):
git fetch origin
git checkout -b fix-typo origin/v3.1-dev   # or whichever earliest branch has it
4. Make the smallest possible edit to src/oas.md — fix the typo, don't reflow paragraphs or touch surrounding wording.
5. Validate:
npm install
npm run build-src        # runs markdownlint first, then builds
5. Then open deploy-preview/oas.html in a browser and eyeball the affected section. (You're on WSL, which is the recommended environment for these scripts.)
6. Open the PR against the same dev branch (e.g., v3.1-dev, not main). Keep it to the single typo fix. Write the PR description yourself — under the repo's AI policy I shouldn't draft it for direct posting — and if AI helped find or fix the typo, add the short disclosure line from AGENTS.md.
7. Expect two TSC approvals, since anything touching src/oas.md requires them (vs. one approval for other files).

As you can see in the output from Claude Code (but AGENTS.md is a standard for all AI agents) it is guiding the contributor properly and makes him/her a more effective and easier for PR reviews.

[miqui]

test:

[miqui]

test: fixing a defect in scripts/schema-publish.sh

I'll read AGENTS.md and locate schema-publish.sh to describe the exact flow it prescribes.

  Searched for 2 patterns, read 1 file, listed 1 directory, ran 1 shell command

Here's the flow AGENTS.md prescribes for fixing a defect in scripts/schema-publish.sh, walking through the doc's sections in the order an agent would apply them:

1. Classify the change and pick the branch. The "Where changes go" table maps this directly: schema-publish.sh is a script, so it falls under "Repo docs, scripts, workflows → Support files → main". It is not a "schema change tied to spec work," so no vX.Y-dev branch is involved. The agent would branch off main (not the current miqui-add-agents.md branch).

2. Check the gates. None of the "Hard rules" or "Stop and ask first" triggers fire — no versions/ edit, no patch-line schema requirement, no discussion/PR text drafting, and the target branch isn't ambiguous. So the agent proceeds without pausing.

3. Apply the working rules. Smallest complete fix for the defect only, one logical change set, no opportunistic reformatting of the rest of the script, and the branch/file choice (main, scripts/schema-publish.sh) gets stated in handoff notes.

4. Validate. The Validation section says any change touching "schemas, scripts, or tests" must run npm test (100% coverage gate). Since schema-publish.sh is executed by npm run build-src (I confirmed in package.json), running build-src is also the natural way to exercise the fixed script end-to-end, then inspect the output it produces.

5. Disclose. The agent's role ends at draft material — the human submitter opens the PR, writes/owns the description, and includes the AI-assistance disclosure wording from AGENTS.md.

Two observations from testing the doc against this scenario:

- The npm test instruction is slightly misleading for this file. The vitest suites live in tests/md2html and tests/schema, and c8 coverage measures JavaScript — a bash script isn't covered by vitest at all. "New code paths need tests" can't literally be satisfied for a .sh fix. An agent following the doc strictly would run npm test (fine, it catches regressions in what the script feeds), but the 100%-coverage framing implies an obligation that doesn't apply here. A clause like "shell scripts are verified via build-src output, not the coverage gate" would remove the ambiguity.
- The validation bullets key off src/oas.md vs. "schemas, scripts, tests," but only the first says to run build-src. For a script that is part of build-src, running it is clearly the right verification, but the doc doesn't say so — an agent could technically stop at npm test. Making the second bullet "also run npm test and build-src if the script participates in the build" would close that gap.

Overall the doc routes this scenario cleanly — branch choice, scope, and disclosure are unambiguous; only the validation guidance leaves room for interpretation.

Note the response from the agent. In this case Claude CLI.

model: fable 5, sonnet 5, sonnet 4.6

afaik, this is correct

[miqui]

another test: proposing a wording change to latest version of the OpenAPI specifcation itself. the change is intended to clarify wording in the specification.

This scenario exercises the spec-text path of AGENTS.md. Let me check which dev branches are actually active so the flow is concrete.

Ran 1 shell command

 Bash(git -C /home/miqui/development/OpenAPI-Specification branch -r | grep -E 'v[0-9.]+-dev'; grep -A10 -i "active branches" /home/miqui/development/OpenAPI-Specification/CONTRIBUTING.md | head -20)
origin/v3.1-dev
origin/v3.2-dev
origin/v3.3-dev
### Active branches

The current active specification releases are:

| Version | Branch | Notes |
| ------- | ------ | ----- |
| 3.1.3 | `v3.1-dev` | active patch release line |
| 3.2.1 | `v3.2-dev` | active patch release line |
| 3.3.0 | `v3.3-dev` | minor release in development |
| 4.0.0 | [OAI/sig-moonwalk](https://github.com/OAI/sig-moonwalk) | [discussions only](https://github.com/OAI/sig-moonwalk/discussions) |

Here's the flow for "clarify wording in the latest version of the spec" — this one exercises the hard rules more than the last scenario did:

1. Hard rule Add urls to links #1 fires immediately and redirects the target. The naive reading of "latest version of the specification itself" points at the newest file in versions/ — which is exactly what the doc forbids editing. AGENTS.md redirects to src/oas.md on a dev branch, and its typo example anticipates this precise trap: the fix goes where the text lives in active development, "even though that is where the typo was noticed."

2. Classify the change: editorial, not normative. A wording clarification lands on the allowed side of the patch-line boundary example ("rewording ... to clarify which value is editorial"). That means: no proposal process required, and patch release lines are legal targets. The agent's one obligation here is to verify the clarification doesn't smuggle in a new requirement — if it does, it's minor-release scope and moves to v3.3-dev with schema updates if needed.

3. Pick the branch — and note the doc says earliest, not latest. Active lines are v3.1-dev (3.1.3), v3.2-dev (3.2.1), and v3.3-dev (3.3.0). The rule is the earliest active branch that contains the text, so the agent greps src/oas.md on each: present in v3.1-dev → target v3.1-dev; introduced in 3.2 → v3.2-dev; new in 3.3 → v3.3-dev. If the wording differs materially across branches, that's a genuine "target branch is ambiguous" case and the Stop-and-ask section says to pause for human guidance.

4. Edit under the working rules. Smallest complete change, no reflowing surrounding paragraphs, prose matched to style-guide.md, clean under spec.markdownlint.yaml.

5. Validate. npm run validate-markdown as the fast loop while editing, then npm run build-src and a browser inspection of deploy-preview/oas.html — the doc mandates this for any src/oas.md change. npm test isn't required since no schemas, scripts, or tests are touched.

6. Hand off. Notes state the branch and file choice and the reasoning (e.g., "text exists in v3.1-dev, targeting there per earliest-active-branch rule"). The human opens the PR, authors the description, and includes the AI-assistance disclosure.

Test observations:

• The doc handles this scenario's main trap well. "Latest version" naturally pulls toward versions/, and both the hard rule and the worked example redirect it correctly. The tension between the user saying "latest" and the doc requiring "earliest active branch containing the text" is exactly the kind of thing the example resolves — this is the strongest part of the doc.
• One gap: forward-porting is unaddressed. After the fix lands on v3.1-dev, an agent has no guidance on whether the same clarification needs separate PRs to v3.2-dev/v3.3-dev or whether maintainers merge forward. CONTRIBUTING.md may cover it, but a one-line pointer in AGENTS.md ("earliest branch only; changes are merged forward by maintainers" — or whatever the actual process is) would prevent an agent from either opening redundant PRs or leaving the human wondering.
• Minor: "earliest relevant" requires the agent to diff the text across three branches to decide. That's fine, but the doc could say explicitly "grep each active dev branch for the text" so agents don't just assume the oldest line.

Note the response from the agent. In this case Claude CLI.

model: fable 5, sonnet 5, sonnet 4.6

afaik, this is correct

[miqui]

@ralfhandl any thoughts?