docs: add CONTRIBUTORS.md issues-only policy (#1517)

[cliffhall]

Closes #1517.
Closes #1595.

Summary

Adds a root CONTRIBUTORS.md documenting the contribution policy: we accept issues, not pull requests. Maintainers handle design and implementation through the prompt-driven workflow described in AGENTS.md. Contributors who have already built a change locally are asked to share the prompt they used, not a diff.

The doc covers every requirement from the issue:

• Policy statement — issues only; external PRs are not merged; maintainers own design/implementation.
• How to report a bug / request a feature — open a well-scoped issue on the right version board. Includes a version → base-branch → project-board → label table (v1 / v1.5 / v2) plus a "Label by version" note mirroring the convention in AGENTS.md. (Added in the latest commit — the table is now actually present; see docs: complete CONTRIBUTORS.md with the version-board/label table (satisfies #1517 req #2) #1595.)
• If you've already fixed it locally — don't send a diff; share the prompt(s), before/after behavior, and how you verified.
• What makes a good issue / prompt submission — reproduction or use case, expected vs. actual, affected client (Web / TUI / CLI), and exact prompt text.
• Rationale — explains the prompt-driven workflow so the policy reads as intentional, with a welcoming tone.
• Cross-reference — adds a "Contributing" section to AGENTS.md linking to CONTRIBUTORS.md. (There is no root README.md in this repo, so AGENTS.md is the cross-reference point — the issue allows "README.md and/or AGENTS.md".)

Notes

• Docs-only change to root files; no client code is touched, so the build/test gates don't apply (no root-level prettier scope covers these files either; the markdown was formatted with prettier manually).
• The optional follow-up (a CONTRIBUTING.md redirect / PR template to steer would-be PR authors) is left for a separate issue if desired.

🤖 Generated with Claude Code

https://claude.ai/code/session_01S3fTN8H3R8YV4yUGvZjYnX

[cliffhall]

@claude review

[claude]

Claude finished @cliffhall's task in 1m 55s —— View job

---

Code Review — CONTRIBUTORS.md issues-only policy

• Read changed files (CONTRIBUTORS.md, .github/pull_request_template.md, AGENTS.md)
• Verify links, anchors, and merge cleanliness
• Provide review feedback

---

This is a clean, well-written docs-only change. The prose is clear, welcoming, and covers every requirement from #1517. The PR-template comment + visible blockquote is a nice touch, and the "Maintainers: delete this template body" note keeps it out of the maintainer workflow's way. I verified the mechanics that are easy to get wrong:

• ✅ Relative link in the template — ../blob/v2/main/CONTRIBUTORS.md correctly resolves from a PR page (/…/pull/1537 → /…/blob/v2/main/CONTRIBUTORS.md).
• ✅ Anchor link — #what-makes-a-good-issue-or-prompt-submission matches the generated heading slug.
• ✅ AGENTS.md cross-reference — confirmed there's no root README.md (only AGENTS.md/CLAUDE.md), so AGENTS.md is the right anchor point per the issue's "README.md and/or AGENTS.md".
• ✅ PR's own diff is +106/-0 — the only AGENTS.md change is the 7-line "Contributing" section; no content is reverted. (The branch is behind v2/main, so a raw tree-diff shows unrelated drift in the "Base Branches"/"Project Status" sections, but that's just the stale base — GitHub's merge inserts the +7 lines cleanly since the PR doesn't touch those regions. Worth a rebase/merge from v2/main before landing to be safe.)

One substantive suggestion — file naming

The biggest opportunity is the filename. GitHub gives CONTRIBUTING.md first-class treatment that CONTRIBUTORS.md does not:

• It auto-surfaces a "Guidelines" link on the New issue and New pull request pages, and counts toward the repo's Community Standards checklist.
• CONTRIBUTORS.md is a well-established convention for a list of people who contributed (e.g. all-contributors), not a policy doc — which is a slight semantic mismatch. The file's own H1 is even # Contributing to MCP Inspector.

Since the entire goal here is to steer would-be authors before they open a PR, CONTRIBUTING.md would get that steering for free at exactly the moment it matters. Options:

1. Rename CONTRIBUTORS.md → CONTRIBUTING.md (and update the two references in the PR template + the AGENTS.md link), or
2. Keep this file and add a short CONTRIBUTING.md that redirects to it (the PR body already flags this as a possible follow-up) — but a single canonical file is simpler.

Rename to CONTRIBUTING.md →

Minor / optional

• The blockquote in the PR template says "read CONTRIBUTORS.md before continuing" while the HTML comment above it gives the same guidance — some redundancy, but harmless and arguably good (the comment is invisible in the rendered description, so the blockquote is what most people actually see).
• No action needed, but note that AGENTS.md on v2/main has diverged (v1.5 marked frozen, InspectorClient merge described as done). Rebasing this branch will avoid any confusion when reviewing the merged result.

Nothing here is blocking — the change does exactly what the issue asked. The naming point is the only one I'd genuinely recommend acting on.
• chore/1517-contributors-md

[cliffhall]

Thanks for the review. Addressing the one substantive point:

Filename CONTRIBUTORS.md vs CONTRIBUTING.md — keeping CONTRIBUTORS.md for this PR. Issue #1517 explicitly specifies CONTRIBUTORS.md as the deliverable, and its Notes list a CONTRIBUTING.md redirect as an optional follow-up rather than part of this scope. The GitHub first-class-treatment argument is valid and worth doing, but as a separate follow-up so this PR lands exactly what the issue asked for. Happy to open that follow-up issue if wanted.

The remaining items (PR-template blockquote redundancy, base-branch divergence) you flagged as non-blocking / no-action — agreed. The branch will get a merge from v2/main before landing per your rebase note.

[cliffhall]

@claude review

[claude]

Claude finished @cliffhall's task in 1m 22s —— View job

---

Code Review — CONTRIBUTORS.md issues-only policy (re-review)

• Read changed files (CONTRIBUTORS.md, .github/pull_request_template.md, AGENTS.md)
• Verify links, anchors, table, and merge cleanliness against v2/main
• Post review feedback

---

Re-reviewed the current state after your response on the filename point. Keeping CONTRIBUTORS.md for this PR is a reasonable call — #1517 names that file as the deliverable and lists the CONTRIBUTING.md redirect as an optional follow-up. Landing exactly what the issue asked and splitting the GitHub-surfacing improvement into its own issue is the right scoping. 👍

Everything checks out mechanically:

• ✅ Version table is present and well-formed (CONTRIBUTORS.md:46–50) — closes docs: complete CONTRIBUTORS.md with the version-board/label table (satisfies #1517 req #2) #1595. Renders cleanly, and the v1/v1.5/v2 → base-branch → board → label mapping matches AGENTS.md. Nice touch marking v1.5 frozen and steering "when in doubt, target v2."
• ✅ Anchor link — #what-makes-a-good-issue-or-prompt-submission (CONTRIBUTORS.md:36) matches the generated slug for the ## What makes a good issue or prompt submission heading.
• ✅ PR-template relative link — ../blob/v2/main/CONTRIBUTORS.md resolves correctly from a PR page (/…/pull/N → /…/blob/v2/main/CONTRIBUTORS.md). The HTML-comment absolute URL is also correct.
• ✅ AGENTS.md cross-reference — the new ## Contributing section (AGENTS.md:76–81) links to ./CONTRIBUTORS.md, and I confirmed v2/main has no ## Contributing section yet, so this is a clean additive merge with no conflict.

One thing to watch before landing (non-blocking)

git merge-base origin/v2/main HEAD returns nothing — this branch and v2/main share no common ancestor (unrelated histories), which is why a raw tree-diff shows drift. Two consequences for the eventual merge:

1. Your PR's AGENTS.md ## Project Status and Direction is stale relative to v2/main. On v2/main that section already says v1.5 is frozen and that "The Launcher, TUI, CLI, and InspectorClient from v1.5/main have been merged into v2/main." Your branch still has the older wording (v1.5 not frozen, merge described as future). Since your PR only adds the ## Contributing section and doesn't touch Project Status, a clean merge from v2/main should keep the newer text — but with unrelated histories, eyeball the merged AGENTS.md to be sure the Project Status section isn't duplicated or reverted.

2. Per your note, you're merging v2/main in before landing — that's the right move and will resolve the above.

Minor / optional (not blocking)

• Slight tension worth a glance: CONTRIBUTORS.md:9 states the blanket policy "We accept issues, not pull requests," while AGENTS.md (both branches) still says v1/main is "accepting bug fixes and minor improvement PRs." Your table softens v1 to "bug fixes and minor improvements only," so the two aren't flatly contradictory — but a reader comparing the two docs might notice. Fine to leave as-is or align in a follow-up.

Nothing here blocks. The change does exactly what #1517 and #1595 asked, and the mechanics (table, anchors, links, additive merge) are all correct.
• chore/1517-contributors-md

[cliffhall]

📋 AGENTS.md audit for this PR: #1595 (comment) (posted on the linked issue #1595).

[cliffhall]

ℹ️ Superseded by #1604. This PR was briefly retargeted onto and merged into the Wave-1 rollup 1579-wave-1 during review, but the CONTRIBUTORS docs have since been pulled back out of that rollup (they're unrelated to the #1510 Wave-1 decomposition). The work now lands on its own standalone PR #1604 → v2/main with clean history. Track it there.