Repo Health

repo-health

The repository-cornerstone skill. Owns the canon for the community-health files that bootstrap any code repository:

• README.md — the front door (Standard Readme spec).
• LICENSE — the legal contract (routed to choosealicense.com; doc-master does not pick).
• CONTRIBUTING.md — how external contributors propose changes.
• CODE_OF_CONDUCT.md — behavioral norms (Contributor Covenant 3.0 default; 2.1 fallback).
• SECURITY.md — vulnerability reporting policy.
• SUPPORT.md — where users go for help (often optional for small repos).
• .github/ templates — issue / PR / CODEOWNERS / FUNDING / CITATION.
• REUSE 3.3 + SPDX — per-file copyright and license metadata.

Each cornerstone has a reference file with the structure, common failure modes, and routing notes. This SKILL.md is the lean entry point — load the references on demand.

Diagnostic first — do not auto-create

doc-master applies the four-question diagnostic to every cornerstone before recommending creation:

1. Audience — who reads this, in what situation? (Drive-by contributor? Security researcher? Confused user? Compliance auditor?) 2. Does it exist already? — many repos already have an equivalent under a different name or location. Find first, write second. 3. Where does it go? — top-level, .github/, docs/? Each cornerstone has a conventional home. 4. Who owns it? — a named human or alias. "The team" is not an owner. CODEOWNERS exists because ownership matters.

If any answer is "no" or "we don't know," do not create the file yet. Most small repos do not need SUPPORT.md, do not need FUNDING.yml, do not need a per-file REUSE header. Cargo-culting cornerstones produces docs nobody reads and nobody updates — the same anti-padding rule that governs ADRs.

What to recommend by default

For any code repository visible outside the originating team:

How to run a bootstrap or audit

When the user asks to set up repository docs:

1. Inventory what already exists (README*, LICENSE*, CONTRIBUTING*, CODE_OF_CONDUCT*, SECURITY*, SUPPORT*, .github/). 2. For each cornerstone, run the four-question diagnostic. 3. Recommend create / merge / leave-alone, one file at a time. Do not bulk-generate. 4. For files that should be created, load the matching reference; produce a draft with placeholders the user fills in. Never invent maintainer names, contact aliases, license choices, or SLA windows. 5. License selection is routed, not made. The skill names common defaults (MIT, Apache-2.0, BSD-3-Clause, GPL-3.0, MPL-2.0) and points to choosealicense.com; the human decides.

When the user asks to audit repository docs:

1. Same inventory. 2. For each cornerstone present, compare to the canon and flag drift / missing sections / stale dates / single-maintainer contact lines. 3. For each cornerstone absent, ask whether the four-question diagnostic answers it into existence — most "missing" SUPPORT.md and FUNDING.yml cases should stay missing. 4. Produce a numbered KEEP / REWRITE / CREATE / DELETE list. Do not bulk-rewrite.

Hard rules

• doc-master does not pick a license. Routing to choosealicense.com is mandatory. The skill names common defaults; the human chooses.
• Code of Conduct contact is a shared alias, never a single email. conduct@example.org, community@…, a moderation team — never a personal inbox. Bus factor of one is a refusal condition.
• SECURITY.md contact is a shared alias or coordinated channel (GitHub Security Advisories, a named program, security@…). Refuse a single-maintainer email.
• Anti-padding. Every recommended file passes the four-question diagnostic. If the four questions cannot be answered, the file should not exist.
• One finding per turn. When auditing, the skill mirrors adr-critique / markdown-style: line-referenced, verbatim quote, named rule, proposed rewrite, per-finding approval.

Routing — what this skill does not own

• Markdown form — once a cornerstone exists, lint it via markdown-style (/doc-lint).
• ADRs for architectural decisions — doc-diagnostic / adr-drafting. "We adopted REUSE" may be an ADR; the per-file REUSE headers themselves are not.
• Changelog — ../doc-diagnostic/references/changelog-canon.md.
• Runbooks / postmortems / open-questions register — ../doc-diagnostic/references/{runbook,postmortem,open-questions}-canon.md.
• AGENTS.md for AI-agent context — ../doc-diagnostic/references/agentic-docs-canon.md.

Examples

<example> <user_query>I just started a new open-source project. What docs do I need at the repo root?</user_query> <response>The opensource.guide four-file canon: README.md, LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md. Add SECURITY.md if the code processes untrusted input. SUPPORT.md is usually overkill for a new project. Loading repo-health; we'll go file by file with the four-question diagnostic. License selection routes to choosealicense.com — I do not pick.</response> </example>

<example> <user_query>Should I write an ADR for "we adopted the Contributor Covenant 3.0"?</user_query> <response>No — that's a CODE_OF_CONDUCT.md adoption, not an ADR. Default to Contributor Covenant 3.0 (four-rung Enforcement Ladder); 2.1 is the older still-valid fallback. Contact line must be a shared alias, not a single maintainer. Loading repo-health reference code-of-conduct-canon.md.</response> </example>

<example> <user_query>Audit our community-health files.</user_query> <response>Loading repo-health. Inventory first, then four-question diagnostic per file, then a numbered KEEP / REWRITE / CREATE / DELETE list. I'll flag single-maintainer contact lines in SECURITY.md / CODE_OF_CONDUCT.md as refusal conditions.</response> </example>

<example> <user_query>Do I need a CITATION.cff?</user_query> <response>If the repo is research software or expects academic citation: yes — CITATION.cff is the converged format. Otherwise no. references/templates-canon.md for the schema.</response> </example>

References

• references/readme-canon.md — Standard Readme spec; nine canonical sections.
• references/license-routing.md — common license defaults and the routing rule (doc-master does not pick).
• references/contributing-canon.md — CONTRIBUTING.md structure, Conventional Commits 1.0, DCO.
• references/code-of-conduct-canon.md — Contributor Covenant 3.0 default with 2.1 fallback; Enforcement Ladder; shared-alias rule.
• references/security-canon.md — SECURITY.md sections; private-reporting channels; response-window floor.
• references/support-canon.md — SUPPORT.md channels; when most repos can skip it.
• references/templates-canon.md — .github/ISSUE_TEMPLATE/*.yml, PULL_REQUEST_TEMPLATE.md, CODEOWNERS, FUNDING.yml, CITATION.cff.
• references/reuse-spdx-canon.md — REUSE 3.3 per-file headers, LICENSES/ folder, REUSE.toml, .license sidecars; SPDX identifier catalog.

CODE_OF_CONDUCT canon — Contributor Covenant

doc-master's default Code of Conduct is the Contributor Covenant. The canonical home is contributor-covenant.org.

Version recommendation

• Default: Contributor Covenant 3.0 (contributor-covenant.org/version/3/0/code_of_conduct/).
• Older still-valid fallback: Contributor Covenant 2.1 (contributor-covenant.org/version/2/1/code_of_conduct/).

The Covenant is the most widely adopted open-source Code of Conduct, and the version published at the canonical URL is the one to reference. doc-master defaults to 3.0; 2.1 remains acceptable when the project has not yet adopted 3.0 or has commitments tied to the 2.1 text.

What changed in 3.0 (worth knowing)

Two structural changes matter when adopting or upgrading:

1. Four-rung Enforcement Ladder. 3.0 names four explicit consequence levels, in escalating severity:

• Warning — a private clarification of the boundary.
• Time-limited cooldown — a temporary, bounded suspension from interaction.
• Temporary Suspension — a longer, project-wide suspension.
• Permanent Ban — removal from the project community.

The ladder gives moderators a calibrated set of responses rather than the binary "ban or do nothing." 2. Explicit Encouraged vs Restricted behaviors. 3.0 separates the encouraged behaviors (empathy, kindness, accepting constructive feedback) from the restricted behaviors (harassment, doxxing, sustained disruption) into distinct sections. This is clearer than the 2.x mixed list and makes the document scannable.

The pledge, the scope, the attribution, and the enforcement-process scaffolding are otherwise consistent with 2.x.

Adoption checklist

When adding CODE_OF_CONDUCT.md to a repo:

1. Use the verbatim text of the chosen version. Do not paraphrase. Do not edit out clauses you find awkward. The whole point of adopting a community-shared Code is that it is the same text across projects. 2. Place the file at the repo root (CODE_OF_CONDUCT.md). GitHub also accepts .github/CODE_OF_CONDUCT.md. 3. Fill in the contact line. The Covenant template has a placeholder for "report concerns to ..." — this is the only line you customize. It is a shared alias, not a single maintainer's personal inbox. See "Hard rules" below. 4. Link from `README.md` and link from `CONTRIBUTING.md`. 5. Document the moderation process internally — who reads the alias, how reports are triaged, what the response SLA is, who decides on enforcement actions. The Covenant defines the ladder; the project defines the who and how. 6. Date and version. A line in your README or in the Code of Conduct itself naming the version (e.g., "This project adopts Contributor Covenant 3.0, adopted 2026-05-21.") makes upgrades auditable.

Hard rules

• Contact line is a shared alias, never a single maintainer's personal email.
• Good: conduct@example.org, community@…, a private moderation channel, a coordinated GitHub team.
• Bad: alice@personal.example (bus factor of one; a malicious actor can target one human).
• doc-master refuses to write a contact line resolving to a single individual. This is non-negotiable — community-health depends on the reporting channel surviving any one departure or compromise.
• Do not edit the substantive text. Customize only the contact line.
• Do not promise enforcement timelines the project cannot meet. "We respond within 24 hours" sets an expectation. Either commit and budget for it, or omit.

Canonical skeleton

# Contributor Covenant Code of Conduct

(Use the verbatim text from https://www.contributor-covenant.org/version/3/0/code_of_conduct/.)

...

## Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at **conduct@example.org**.

All complaints will be reviewed and investigated promptly and fairly.

## Enforcement Ladder

(Verbatim from the 3.0 source: Warning → Time-limited cooldown → Temporary Suspension → Permanent Ban.)

## Attribution

This Code of Conduct is adapted from the Contributor Covenant, version 3.0, available at https://www.contributor-covenant.org/version/3/0/code_of_conduct/.

Common failure modes

Routing — when this is not the answer

• Behavioral norms specific to contribution mechanics (not community behavior) → CONTRIBUTING.md.
• Security disclosure policy → SECURITY.md. (These are different — Code of Conduct covers conduct; SECURITY covers vulnerability reporting.)
• Internal moderation playbook → not in the public repo. Keep that in an ops-private location.
• Trademark / branding enforcement → TRADEMARKS.md if the project has one.

CONTRIBUTING canon

The canonical structure for CONTRIBUTING.md. The file lives at the repo root (GitHub also accepts .github/CONTRIBUTING.md). It is the on-ramp for external contributors — the document that answers "I want to propose a change; what do I do?"

What CONTRIBUTING is, and is not

Recommended structure

1. How to propose a change — issue first vs PR first; whether RFCs are required for big changes; where discussions happen (issues, discussions, chat). 2. Local development quickstart — clone, install, run tests, run linter, run the project. Three to ten commands maximum. Link to deeper setup docs if needed. 3. PR checklist — what every PR must include before it gets reviewed:

• Tests for new behavior.
• Documentation update (README, docs, code comments).
• Changelog entry under ## [Unreleased] (see ../../doc-diagnostic/references/changelog-canon.md).
• Linter / formatter passes.
• Conventional Commits message (if adopted; see below).

4. Link to `CODE_OF_CONDUCT.md` — explicit, by name. Contributors are bound by it. 5. Link to `SECURITY.md` — security issues do not go in public issue trackers; they go through the security channel. 6. Commit-message convention — adopt one and link to its spec. The default doc-master suggests is Conventional Commits 1.0 (conventionalcommits.org) — feat:, fix:, docs:, refactor:, etc. The skill names this as a default and routes the human to the spec; it does not bundle the spec. 7. DCO or CLA, if used:

• DCO (Developer Certificate of Origin) — git commit -s adds the Signed-off-by: trailer; the project enforces it via a bot. Lightweight, no separate signing event.
• CLA (Contributor License Agreement) — separate signing flow; required by some large projects and corporate-stewarded foundations. Heavier; deters drive-by contributions; appropriate when patent / copyright assignment matters.

8. Review and merge expectations — who reviews, how long until a first response, how merges happen (squash, merge, rebase). 9. Release cadence (optional) — when releases happen, who cuts them.

What does not belong here

• Coding style and formatting — these go in the linter / formatter config (.eslintrc, pyproject.toml, rustfmt.toml, .editorconfig). CONTRIBUTING.md says "run npm run lint" and links to the config; it does not enumerate rules.
• Architecture documentation — link to docs/ and the decision log. Do not duplicate.
• Marketing prose — strip "Welcome! We're so excited to have you!" The contributor wants the procedure, not a greeting.
• Behavioral norms — those are in CODE_OF_CONDUCT.md. CONTRIBUTING links to it; does not restate.

Canonical skeleton

````md

Contributing

Thanks for your interest in contributing.

All participants are bound by the Code of Conduct. Please read it before opening an issue or PR.

If you have found a security vulnerability, do not open a public issue. See SECURITY.md for the private reporting channel.

How to propose a change

• Small bug fix / typo: open a PR directly.
• New feature or behavior change: open an issue first to discuss the scope.
• Architectural change: see docs/adr/ for our Architecture Decision Records and the proposal process there.

Local development

git clone https://example.com/org/project.git
cd project
make install
make test

Pull request checklist

Every PR must:

• Include tests for new behavior or a fix.
• Update documentation that the change affects.
• Add an entry to CHANGELOG.md under ## [Unreleased].
• Pass the linter (make lint).
• Use a Conventional Commits 1.0 message: feat:, fix:, docs:, etc.
• Be signed off (git commit -s) -- we use the Developer Certificate of Origin.

Review

• A maintainer will respond within five business days.
• Two approvals are required for merge.
• PRs are merged with squash; the squash message is the PR title (Conventional Commits format).

````

Common failure modes

Routing — when this is not the answer

• Code of Conduct → code-of-conduct-canon.md.
• Security disclosure → security-canon.md.
• Per-file licensing → reuse-spdx-canon.md.
• An architectural-decision proposal flow → ../../doc-diagnostic (ADR / RFC routing).

LICENSE — routing, not picking

doc-master does not pick a license for users. Licensing is a legal decision with downstream consequences (compatibility, patent grants, copyleft propagation, contributor expectations); the right answer depends on the project, the contributors, the consumers, and sometimes legal counsel.

The skill's job is to route the user to:

1. choosealicense.com — the GitHub-maintained guide, intentionally narrow but high-quality. 2. The full SPDX license catalog — spdx.org/licenses/ — when the project needs a license not covered by choosealicense.

Common defaults — naming only, not recommending

doc-master will name these in conversation, with one-line summaries. The human picks.

This list is descriptive, not prescriptive. The skill names options; the human picks based on goals, ecosystem expectations, contributor base, and legal advice.

What goes in the repo

• A top-level LICENSE (or LICENSE.md, or LICENSE.txt) file with the verbatim license text. Do not summarize; do not paraphrase. GitHub's licensee tool and most compliance scanners depend on the exact text matching the SPDX-listed canonical form.
• A short License section in README.md that names the license and links to the LICENSE file (see readme-canon.md).
• For per-file licensing metadata (multi-license repos, third-party imports): an SPDX-License-Identifier: header on each source file. See reuse-spdx-canon.md for the REUSE 3.3 convention.

When the choice is not obvious — escalate

• Mixed licensing across the codebase (vendored third-party libraries with their own licenses): the project picks its own license for its own code; vendored code retains its license. Track the combination via REUSE / SBOM.
• Patents are a concern (cryptography, ML models, specific algorithms): prefer Apache-2.0 over MIT for the explicit patent grant.
• Strong-copyleft ecosystem expectations (Linux kernel modules, GNU tools): pick within the GPL family.
• Compliance regimes (GPL-only enterprise, MIT-only consumer): match the regime.
• Datasets, documentation, configuration (not source code): consider CC0 for public domain or CC-BY-4.0 for attribution. These are not OSI-approved for software.

When the choice is unclear, doc-master surfaces the question to the architect / project owner and declines to guess.

What this file does not cover

• Choosing for the user. Choosealicense.com is the public guide; legal counsel is the private one.
• Drafting custom licenses. Avoid. Use an SPDX-listed license.
• License compatibility analysis (can I combine GPL-2.0 and Apache-2.0?). Refer to FSF / OSI / SPDX compatibility documentation.
• Trademark policy. Trademarks are separate from copyright. Some projects publish a TRADEMARKS.md alongside LICENSE.

Routing — what to load next

• Per-file SPDX headers / REUSE compliance → reuse-spdx-canon.md.
• README license section → readme-canon.md.
• A decision to change the project's license → almost certainly an ADR, because relicensing affects every downstream consumer and contributor.

README canon — Standard Readme

The canonical structure for README.md. doc-master's reference is the Standard Readme spec (currently v1.3.0), github.com/RichardLitt/standard-readme. It collects the converged community structure for README files in open-source software projects.

A README is the front door. The single most common failure is that it forgets it has a job: someone unfamiliar with the project arrives, has a question, and either finds the answer in the first thirty seconds or leaves.

Required and optional sections (Standard Readme)

The spec defines nine canonical sections. They appear in this order. Required unless marked optional.

1. Title — exactly the project name, as a single H1 at the top. No marketing strapline in the H1 itself; put the strapline in a one-line "short description" immediately below. 2. Badges (optional) — build status, version, license, coverage. Place above the long description or just below the short one. Avoid badge soup; pick three or four that earn their pixel cost. 3. Short description — one or two sentences immediately under the title. The reader who reads no further still knows what this is. 4. Long description (optional) — Background. The "why does this exist" paragraph. Skip if the short description is sufficient. 5. Table of Contents (optional) — required for any README that exceeds one screen of laptop scroll. Auto-generate where the renderer supports [TOC]; otherwise hand-maintain. 6. Install — exactly how to install / build / set up. Copy-pasteable commands. Cover the common case in the body; link out to detailed installation guides if any. 7. Usage — minimal example that does something useful. The "your first ten minutes" demo. Not a manual. 8. API (optional) — only when the project is a library / SDK and the README is the documentation of last resort. Otherwise link to a separate API reference. 9. Maintainers — named humans (or aliases). Without this, contributors do not know whom to talk to. 10. Contributing — short paragraph that links to CONTRIBUTING.md. Names the Code of Conduct. 11. License — short section that names the license (e.g., "MIT © 2026 Project Authors") and links to the `LICENSE` file. The license section in the README does not replace the LICENSE file; it points to it.

Sections may be empty or absent if the four-question diagnostic explains why. (A repo with no installable artifact does not need an Install section, for example — but should have a one-line "How to use this repo" note instead.)

Common failure modes

Canonical skeleton

````md

project-name

 

One- or two-sentence description of what this project does.

(Optional longer Background paragraph.)

Table of Contents

• Install
• Usage
• API
• Maintainers
• Contributing
• License

Install

git clone https://example.com/org/project.git
cd project
make install

Usage

project --help

A minimal end-to-end example here.

API

(Optional. Link to detailed reference under docs/.)

Maintainers

• @alice
• @bob
• maintainers@example.org

Contributing

PRs welcome. See CONTRIBUTING.md. All participants are bound by the Code of Conduct.

License

MIT © 2026 The Project Authors. ````

Routing -- when this is not enough

• A long manual, multi-language SDK, deep operational docs → link out to a documentation site (Diátaxis-organized) from the README; do not stuff it all here.
• Compliance / regulatory documentation → separate /docs/compliance/ directory; README links to it.
• Per-file licensing metadata → reuse-spdx-canon.md (REUSE 3.3).
• Security disclosure policy → security-canon.md (SECURITY.md).

REUSE 3.3 + SPDX canon — per-file licensing metadata

The canonical reference for REUSE 3.3 (the per-file licensing convention) and the SPDX License List (the canonical identifier catalog).

• REUSE 3.3 specification: reuse.software/spec-3.3/.
• SPDX License List: spdx.org/licenses/.
• SPDX specification (REUSE depends on SPDX 2.3): spdx.dev.

What REUSE solves

A repository typically aggregates code under multiple licenses (own code, vendored libraries, third-party imports, configuration, documentation, assets). The single top-level LICENSE file cannot describe per-file reality. REUSE prescribes a convention that makes per-file licensing machine-verifiable:

1. Every file has a license. No "we forgot to think about this." 2. The license is named with an SPDX identifier, not a paraphrase. 3. Copyright is attributed. Not optional. 4. The full license texts live in `LICENSES/` — one file per license, SPDX-named. 5. A `reuse lint` tool can verify the whole repo mechanically.

The four mechanisms (pick per file)

1. SPDX headers inside the file

For source files that support comments, add two lines near the top:

// SPDX-FileCopyrightText: 2026 The Project Authors
// SPDX-License-Identifier: Apache-2.0

The exact comment syntax depends on the language. Both lines are required. The license identifier must be from the SPDX list.

Multiple copyright holders → multiple SPDX-FileCopyrightText: lines. Multi-license files → SPDX-license expression (Apache-2.0 OR MIT).

2. .license sidecar file

For files that cannot carry comments (binaries, images, fonts, generated artifacts, PDFs):

• Create a sidecar at <file>.license containing the same two SPDX lines.
• Example: logo.png plus logo.png.license.

3. REUSE.toml bulk declaration

For groups of files that all share the same copyright and license, add a REUSE.toml at the repo root:

version = 1

[[annotations]]
path = "docs/**"
SPDX-FileCopyrightText = "2026 The Project Authors"
SPDX-License-Identifier = "CC-BY-4.0"

[[annotations]]
path = "vendor/lib-foo/**"
SPDX-FileCopyrightText = "2024 The Foo Authors"
SPDX-License-Identifier = "BSD-3-Clause"

REUSE.toml is the modern format (REUSE 3.x); older .reuse/dep5 (Debian DEP-5) is being phased out.

4. LICENSES/ directory

The repo root contains a LICENSES/ directory with one file per license used anywhere in the project, SPDX-named:

LICENSES/
  Apache-2.0.txt
  MIT.txt
  CC-BY-4.0.txt
  BSD-3-Clause.txt

Each file contains the verbatim canonical license text. Do not paraphrase. Get the text from spdx.org/licenses/.

When to adopt REUSE

The four-question diagnostic applies. doc-master recommends REUSE when:

• The repo aggregates multi-license content (project code + vendored libraries + assets under different licenses).
• The project ships to environments requiring SBOM (Software Bill of Materials) — government, healthcare, certain commercial customers.
• The project wants machine-verifiable license compliance in CI.
• The project is funded under terms that require explicit copyright attribution.

For a single-author hobby project with one license, REUSE is overkill. The top-level LICENSE plus an SPDX-License-Identifier: on each source file is plenty.

The CI gate

pipx install reuse
reuse lint

This passes when every file in the repo is covered (via header, sidecar, or REUSE.toml) and every named license has a text in LICENSES/. Add it to CI to prevent license drift.

Common failure modes

What this canon does not cover

• Picking a license. Routes to license-routing.md.
• SPDX expression syntax (Apache-2.0 WITH LLVM-exception, complex AND/OR/WITH). See spdx.github.io/spdx-spec/SPDX-license-expressions/.
• SBOM generation. SPDX 2.3 / 3.0 supports SBOM; REUSE adoption is a strong foundation for SBOM output, but generation is a separate tooling concern (CycloneDX, syft, etc.).
• License compatibility analysis. Different question; refer to OSI / FSF / SPDX guidance.

Routing — when this is not the answer

• "Which license do we pick?" → license-routing.md.
• "How do we document our top-level project license?" → readme-canon.md + a top-level LICENSE.
• "We are adopting REUSE as a project-wide commitment" → potentially an ADR, because it imposes a CI gate and a per-file convention with operational cost.

SECURITY canon

The canonical structure for SECURITY.md. The file lives at the repo root (GitHub also accepts .github/SECURITY.md). It tells a security researcher how to responsibly disclose a vulnerability — and what to expect after they do.

What SECURITY.md is, and is not

Required sections

A doc-master SECURITY.md has these sections:

1. Supported Versions — a small table naming which versions receive security fixes. Reporters need to know whether their finding is in scope. 2. Reporting a Vulnerability — the private channel. Strongly preferred:

• GitHub Security Advisories (https://github.com/<org>/<repo>/security/advisories/new) — built-in, supports coordinated disclosure, no infrastructure to maintain.
• A named shared alias (security@example.org, psirt@…).
• A coordinated-disclosure program (HackerOne, Bugcrowd, an internal program with a public page).
• Refuse a single-maintainer email as the contact. Bus factor of one is unacceptable for security reports.

3. Expected Response Window — concrete numbers. doc-master's floor is one human-week (five business days) for open-source projects. If the team cannot meet that, the project's security posture is the problem; either staff it or be honest about the longer window. 4. Scope — what is in scope (the codebase, the deployed service, specific components) and what is out (third-party dependencies that should be reported upstream, social engineering, denial of service, etc.). 5. Attribution & Disclosure — how researchers are credited (CVE, advisory acknowledgments, a public hall of fame), the embargo window, the disclosure-timing policy (e.g., "we publish 30 days after a fix ships or 90 days from report, whichever is earlier").

Optional:

• Safe harbor — a public commitment not to pursue legal action against good-faith researchers acting within the policy.
• Reward program — bounty amounts, scope, exclusions. Most small projects do not have one and that is fine.
• PGP key / Signal contact — for the very small number of reporters who need it.

Hard rules

• Single-maintainer email is refused. doc-master will not draft a SECURITY.md whose contact line resolves to one individual's personal inbox. Use GitHub Security Advisories or a shared alias.
• The response-window floor is one human-week. Cannot make that? Then the SECURITY.md needs to be honest about a longer window, not omit the window entirely.
• Public issues are forbidden for vulnerabilities. State this explicitly. Reporters following responsible disclosure norms still need a reminder.
• No "best effort" weasel words on response. Either commit to a window or don't publish one. Reporters interpret "best effort" as "ignore."

Canonical skeleton

# Security Policy

## Supported Versions

| Version | Supported |
|---------|-----------|
| 1.x     | yes       |
| 0.x     | no        |

## Reporting a Vulnerability

Please **do not open a public GitHub issue** for security vulnerabilities.

Use one of these channels:

- **Preferred:** [open a security advisory](https://github.com/example-org/example-repo/security/advisories/new) on GitHub.
- **Alternative:** email `security@example.org`. This alias is monitored by the security team; replies are confidential.

Please include:

- A description of the issue and the affected component / version.
- Steps to reproduce, including a proof-of-concept where safe.
- The impact you observed and the impact you believe is possible.
- Any preliminary mitigations.

## Response Window

We acknowledge security reports within **five business days**. We aim to publish a fix and advisory within **30 days** of a confirmed report; complex issues may take longer, and we will communicate ETA updates if so.

## Scope

In scope:

- This codebase and its released artifacts.
- The official deployed service at `example.com`.

Out of scope:

- Third-party dependencies -- please report upstream. We will track the fix.
- Social-engineering and physical-security testing.
- Denial-of-service findings without a novel vector.

## Disclosure

We follow coordinated disclosure. Public disclosure happens after a fix ships or 90 days from the original report, whichever is earlier. Reporters are credited in the advisory unless they request otherwise.

## Safe Harbor

We will not pursue legal action against researchers acting in good faith within this policy.

Common failure modes

Routing — when this is not the answer

• Behavioral norms → CODE_OF_CONDUCT.md.
• Support / how-to-get-help → SUPPORT.md (support-canon.md).
• A specific vulnerability advisory → GitHub Security Advisory or equivalent. SECURITY.md is the policy; advisories are the events.
• Postmortem of a security incident → ../../doc-diagnostic/references/postmortem-canon.md, with blameless framing.
• A decision to adopt a coordinated-disclosure program → may be an ADR if the program imposes architectural constraints (logging, rate-limiting, audit trails).

SUPPORT canon

The canonical structure for SUPPORT.md. The file lives at the repo root (GitHub also accepts .github/SUPPORT.md). It tells a user looking for help where to go.

Most small repos do not need this file

The four-question diagnostic applies bluntly:

• Audience — who specifically reads SUPPORT.md? Usually: a user who tried to file an issue and was redirected.
• Does it exist already? — yes, usually. The README's "support" or "community" section is sufficient for most projects.
• Where does it go? — SUPPORT.md at root, but only when it earns its own file.
• Owner — who keeps the list of channels current?

For a small repo with one issue tracker and no Discussions / chat / commercial offering, a one-line "How to get help" link in the README is enough. Adding SUPPORT.md to that repo is documentation padding.

doc-master recommends SUPPORT.md when:

• The repo has multiple channels (issues, Discussions, Discord / Slack / Matrix, mailing list, paid support) and routing matters.
• The issue tracker is being misused for support questions that should go elsewhere.
• The project has a commercial support tier worth naming.
• The project participates in multiple communities (Stack Overflow tag, language ecosystem chat) and wants to direct different question types to different homes.

If none of these apply, skip the file.

Recommended structure (when the file is justified)

1. What this file is for — one line. "Looking for help? Here's where to go." 2. The channel map — a small table:

• Bug reports → GitHub Issues with a link to the template.
• Feature requests → GitHub Discussions / Issues with the right template, or a roadmap pointer.
• Usage questions → Discussions / Stack Overflow tag / community chat.
• Real-time chat → Discord / Slack / Matrix invite link.
• Security issues → SECURITY.md (private channel, not here).
• Paid / commercial support → vendor URL, if applicable.

3. Expected cadence — what response time, if any, is realistic per channel. Be honest. Community channels are best-effort. 4. What we cannot help with — out-of-scope questions, with a redirect (e.g., "we don't troubleshoot your specific build setup; ask in the language community").

Canonical skeleton

# Support

Looking for help? Pick the right channel.

| Need                          | Channel                                                                |
|-------------------------------|------------------------------------------------------------------------|
| Report a bug                  | [GitHub Issues](https://github.com/example-org/repo/issues) -- use the bug template. |
| Request a feature             | [GitHub Discussions → Ideas](https://github.com/example-org/repo/discussions/categories/ideas). |
| Ask a usage question          | [GitHub Discussions → Q&A](https://github.com/example-org/repo/discussions/categories/q-a). |
| Real-time chat                | [Project Discord](https://discord.gg/example).                          |
| Report a vulnerability        | See [SECURITY.md](SECURITY.md). Do not use any public channel for this. |
| Commercial support            | <vendor URL or "not available">                                         |

## Cadence

- Issues: a maintainer triages within five business days.
- Discussions: community-answered. Maintainers chime in when they can.
- Chat: best-effort, no SLA.

## What we cannot help with

- Custom build setups specific to your environment -- ask in the language community.
- Production-incident handholding without a commercial support tier.

Common failure modes

Routing — when this is not the answer

• Security disclosure → security-canon.md.
• Bug-report mechanics → templates-canon.md (issue templates).
• "What does this project do?" → README.
• "How do I contribute?" → CONTRIBUTING.md.

Templates canon — .github/ files

Repository templates that GitHub (and most equivalent forges) recognize. Each is optional and earns its place via the four-question diagnostic. Cargo-culting a .github/ directory full of empty templates is documentation padding.

Issue templates — .github/ISSUE_TEMPLATE/

Two formats are supported:

• Markdown templates (.github/ISSUE_TEMPLATE/<name>.md) — older format, free-form Markdown with a YAML front matter. Still supported but largely superseded.
• Issue-form templates (.github/ISSUE_TEMPLATE/<name>.yml) — preferred. Structured form with typed inputs (text, dropdown, checkboxes, textarea). Produces better-formatted issues and lets the project enforce required fields.

Recommended set

Most projects benefit from two or three templates:

• Bug report — fields: summary, version, reproduction steps, expected vs actual, environment.
• Feature request — fields: problem, proposed solution, alternatives, additional context.
• Question — only if Discussions are not enabled. With Discussions on, redirect questions there via config.yml.

Add a .github/ISSUE_TEMPLATE/config.yml to control "blank issue" behavior and link to non-issue channels (Discussions, security, chat):

blank_issues_enabled: false
contact_links:
  - name: Question / discussion
    url: https://github.com/example-org/repo/discussions
    about: Ask usage questions in Discussions.
  - name: Security vulnerability
    url: https://github.com/example-org/repo/security/advisories/new
    about: Report a security issue privately. Do not open a public issue.

Common failures

• No templates → contributors free-form, maintainers re-ask the same questions.
• Too many templates → triage cost; contributors pick wrong.
• Form fields without `required: true` → key info still missing.
• Markdown templates that pretend to be forms → migrate to issue-form .yml.

Pull-request template — .github/PULL_REQUEST_TEMPLATE.md

A single file at .github/PULL_REQUEST_TEMPLATE.md (multiple templates are supported via .github/PULL_REQUEST_TEMPLATE/ directory, but most projects use one).

Keep it short. The template should mirror the PR checklist in CONTRIBUTING.md:

## Summary

(One paragraph: what does this change and why.)

## Type of change

- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation
- [ ] Refactor / internal

## Checklist

- [ ] Tests added / updated.
- [ ] Documentation updated.
- [ ] `CHANGELOG.md` entry added under `## [Unreleased]`.
- [ ] `make lint` passes locally.
- [ ] Conventional Commits message (`feat:`, `fix:`, `docs:`, ...).
- [ ] Signed off (`git commit -s`).

## Related issues / ADRs

(Link issues this resolves and any ADRs touched.)

A bloated PR template is itself a failure mode — every field is a tax on the contributor.

CODEOWNERS — .github/CODEOWNERS or CODEOWNERS at repo root

A small file that maps path patterns to reviewers (users or teams). GitHub uses it to auto-request reviews when a PR touches a path.

# Default
*                       @example-org/maintainers

# Per-area
/docs/                  @example-org/docs-team
/security/              @example-org/security-team
/services/payments/     @example-org/payments-team

Hard rules:

• Owners must be teams or aliases, not single users (bus factor).
• Patterns are evaluated last-match-wins — order matters.
• The file is itself a decision record of who owns what. Audit it on every team change.

FUNDING.yml — .github/FUNDING.yml

Tells GitHub to render a "Sponsor" button. Only useful when the project actually accepts donations.

github: [example-org]
patreon: example
open_collective: example
custom: ["https://example.org/donate"]

Most projects do not need this. Add only when the project has a real funding channel, not aspirationally.

CITATION.cff — CITATION.cff at repo root

The converged format for academic citation of software. CFF (Citation File Format) is YAML; GitHub renders a "Cite this repository" button from it.

Required for research software, academic-cited tools, datasets-as-code, and anything used in published work that benefits from a canonical citation. Not needed for most application code.

cff-version: 1.2.0
message: "If you use this software, please cite it as below."
title: "Example Project"
version: 1.4.0
date-released: 2026-05-21
authors:
  - family-names: Doe
    given-names: Jane
    orcid: https://orcid.org/0000-0000-0000-0000
repository-code: "https://github.com/example-org/repo"
license: MIT

The schema lives at citation-file-format.github.io.

Discussions, wiki, Pages — out of scope here

These are GitHub features, not files in the repo. The repo-health skill names them as routing targets (SUPPORT.md, README), not as files to author.

Common failure modes across templates

Routing — what each template points to

• Issue template config.yml → SECURITY.md (vulnerabilities), Discussions (questions), SUPPORT.md (help).
• PR template → CONTRIBUTING.md (checklist source of truth).
• CODEOWNERS → no public doc; internal team / alias list.
• FUNDING.yml → no public doc; just the funding URL.
• CITATION.cff → optional inclusion in README ("How to cite") with a short summary.