chore: OSS community hygiene + Claude Code setup

[ramseymcgrath]

Summary

Two related cleanups bundled in one PR for context: tightening the project's open-source surface as outside contribution picks up, and wiring first-class Claude Code support so the codebase's domain knowledge (PCIe spec, Vivado quirks, donor-ID invariants) is available to any contributor without leaking into individual setups.

Commits are split logically:

• chore(github): harden OSS community files for external contributors — security policy, README Discord badge, CODEOWNERS, PR template, issue templates, CONTRIBUTING.rst → .md rename, stale AUTHORS.rst removal.
• chore(claude): wire CLAUDE.md, project skills, safety agent, and hooks — CLAUDE.md, two project-specific skills, a hardware-safety subagent, protection + ruff hooks, GitHub MCP server, .gitignore housekeeping.
• chore(github): route issue-chooser open-ended bucket to Discord — sends questions / hardware-compat / brainstorming traffic to the support Discord instead of GitHub Discussions, so the issue chooser doesn't depend on Discussions being enabled.

What changes (community files)

• SECURITY.md rewritten. The prior body ("add an issue pls") was actively wrong for a PCIe/DMA firmware tool — vulns now route through GitHub Security Advisories with email fallback, defined SLAs, and an explicit in-scope / out-of-scope section.
• README.md — Discord badge no longer embeds a personal user ID; it's now a clean shields.io badge linking to the support server invite.
• .github/CODEOWNERS — added, default to @ramseymcgrath, with explicit entries for .github/, src/, build scripts, and docs. Will auto-request review on PRs going forward.
• .github/PULL_REQUEST_TEMPLATE.md — includes a "blast radius" section calling out firmware / VFIO / build changes that warrant extra review.
• .github/ISSUE_TEMPLATE/feature_request.md + config.yml — adds a focused feature-request template and a chooser config that disables blank issues and routes users to Security Advisories, docs, or the support Discord where appropriate.
• CONTRIBUTING.rst → CONTRIBUTING.md — file body was already markdown; the extension just confused tooling. MANIFEST.in updated to match.
• AUTHORS.rst deleted — it listed only the original author while the repo now has ~10 contributors. GitHub's contributor list is the source of truth.

What changes (Claude Code setup)

• CLAUDE.md at repo root, structured for both audiences:
  • Top half: helping installers/users — platform/install-path/root-access flow, symptom-cause-fix table for the recurring errors, links to docs site / Discord / Security Advisories.
  • Bottom half: helping developers — env setup, test commands, architectural map, protected files (src/_version.py, lib/voltcyclone-fpga/), code conventions (no placeholder donor IDs, argv-list subprocess, log_*_safe helpers, Jinja2 SV pitfalls), and pointers to the in-repo tooling below.
• .claude/skills/vivado-log-analyzer/ — Python script that extracts only actionable ERROR / CRITICAL WARNING / timing / DRC / resource-exhaustion lines from Vivado logs so failed-build diagnoses fit in context. Auto-invokes on Vivado failures; runnable directly:

  python3 .claude/skills/vivado-log-analyzer/scripts/analyze.py path/to/vivado.log

• .claude/skills/new-board-target/ — user-only walkthrough for registering a new FPGA board (BOARD_CONFIGS entry, discovery verification, tests, e2e dry-run, common pitfalls).
• .claude/agents/hardware-safety-reviewer.md — domain-specific reviewer scoped to src/device_clone/, src/pci_capability/, src/templates/sv/, src/templating/timing_constraints/, src/vivado_handling/. Complements generic code review with PCIe-spec / donor-propagation / DMA-safety / SV-template checks; explicitly stays out of style commentary.
• .claude/settings.json — two hooks:
  • PreToolUse blocks edits to src/_version.py (setuptools-scm autogen) and lib/voltcyclone-fpga/ (git submodule) — protects against silent regressions where edits don't persist.
  • PostToolUse runs ruff check --fix on edited .py files.
• .mcp.json — shared GitHub MCP server. Contributors using Claude Code pick this up automatically (needs $GITHUB_PERSONAL_ACCESS_TOKEN in env).
• .gitignore — keeps .claude/settings.local.json (personal permissions) and transient .claude/.cache/ out of the tree while tracking the shared config above.

Required GitHub settings change (not in code)

One repo setting should be flipped for SECURITY.md to work as intended — admin-level, not committable:

• Enable private vulnerability reporting (Settings → Code security → Private vulnerability reporting). This is what makes the "Report a vulnerability" button appear on the Security tab that SECURITY.md links to.

(Discussions does not need to be enabled — the issue chooser now routes open-ended questions to the support Discord.)

Test plan

• .claude/settings.json validates as JSON; .mcp.json validates as JSON.
• PreToolUse hook regex smoke-tested against three paths: blocks src/_version.py, blocks lib/voltcyclone-fpga/EnigmaX1/foo.sv, allows src/device_clone/board_config.py.
• vivado-log-analyzer/scripts/analyze.py compiles cleanly and produces correctly bucketed output on a synthetic Vivado log covering all six failure categories.
• Confirm CI is green (consolidated-ci, security, e2e workflows).
• After merge, verify the GitHub Security Advisories link in SECURITY.md resolves (requires private vulnerability reporting to be enabled — see above).
• After merge, confirm CODEOWNERS auto-requests reviewer on the next PR touching src/.

Notes

• .cleanthat/ is not touched. The cleanthat[bot] is active on this repo per the contributor list, so the config is live, not dead. (Confirmed: it ran on this PR and reformatted .mcp.json and .claude/settings.json — semantically equivalent, rebased in.) If you ever want to remove it, uninstall the GitHub App first, then delete the directory.
• The .github/copilot-instructions.md file is gitignored, so its contents are not surfaced in CLAUDE.md. If anything in that local file is worth promoting to the shared CLAUDE.md, that's a follow-up.

[Copilot]

Pull request overview

This PR bundles open-source community hygiene improvements (security policy, templates, CODEOWNERS, contribution docs) with a first-class Claude Code setup so contributors have shared project context and tooling.

Changes:

• Hardened OSS/community surface: updated SECURITY.md, added CODEOWNERS, PR template, and GitHub issue templates; removed stale AUTHORS.rst.
• Renamed contribution guide to CONTRIBUTING.md and updated packaging manifest accordingly.
• Added Claude Code configuration (CLAUDE.md, skills, safety agent, hooks, MCP server config) and .gitignore entries for local Claude state.

Reviewed changes

Copilot reviewed 15 out of 17 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
SECURITY.md	Updates supported-versions and private vulnerability reporting guidance.
README.md	Replaces Discord badge with a shields.io badge linking to the support server.
MANIFEST.in	Updates packaged docs to include CONTRIBUTING.md and drop AUTHORS.rst.
CONTRIBUTING.md	Adds/renames contributing guide content and badges.
CLAUDE.md	Adds repo-wide Claude/AI assistant guidance for users and developers.
AUTHORS.rst	Removes outdated contributors file.
.mcp.json	Adds shared GitHub MCP server configuration for Claude Code.
.gitignore	Ignores Claude user-local settings and cache directories.
.github/PULL_REQUEST_TEMPLATE.md	Adds PR template with risk/blast-radius checklist.
.github/ISSUE_TEMPLATE/feature_request.md	Adds feature request issue template.
.github/ISSUE_TEMPLATE/config.yml	Configures issue chooser and routes security reports privately.
.github/CODEOWNERS	Adds code ownership rules for key repo areas.
.claude/skills/vivado-log-analyzer/SKILL.md	Documents a Vivado log summarization skill.
.claude/skills/vivado-log-analyzer/scripts/analyze.py	Implements Vivado log/report summarizer script.
.claude/skills/new-board-target/SKILL.md	Documents workflow for adding new FPGA board targets.
.claude/settings.json	Adds Claude Code hooks for protected paths and ruff autofix on edits.
.claude/agents/hardware-safety-reviewer.md	Adds a domain-focused hardware safety review agent spec.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!