Oss Readiness

OSS Readiness — Public Release Gate

Audit a repository for open-source release basics. Scaffold missing public docs/templates. Generate AI-friendly docs (llms.txt, llms-full.txt). Validate CI. Sync version references.

Portability Rules

This skill must stay harness-agnostic and maintainer-agnostic:

• Accept natural-language prompts and slash-command shorthand as equivalent entry points.
• Keep AGENTS.md as the canonical agent-instructions file when one is scaffolded.
• Treat harness-specific files such as CLAUDE.md, .cursorrules, .windsurfrules, codex.md, or .opencode/config as optional aliases/mirrors — never the only supported path.
• Use placeholders in generated files. Never hardcode links, social handles, org names, or contact methods from this repository.
• Never invent maintainer contact channels. If the project does not provide one, leave a clear placeholder or omit the optional section.

Required Capabilities

The skill still works without shell tooling. Shell commands are accelerators, not requirements.

Entry Points

Use either natural language or shorthand. Route both to the same workflow.

Template Variables

Scaffolded files should use these placeholders until the target repo values are known:

If a value is unknown, keep the placeholder or omit the optional block. Never substitute repo-specific defaults from this skill repository.

Stack Detection

Detect project type to customize audit logic:

# Package manager / language hints
IS_NPM=$(test -f package.json && echo true || echo false)
IS_CARGO=$(test -f Cargo.toml && echo true || echo false)
IS_PYTHON=$(test -f pyproject.toml -o -f setup.py && echo true || echo false)
IS_GO=$(test -f go.mod && echo true || echo false)

# Library/package vs app (heuristics)
# npm: package.json has "main" or "exports"
# cargo: Cargo.toml has [lib]
# python: pyproject has build metadata / published package info
# go: cmd/ often implies app; library repos may omit it

Checklist Summary (23 items)

BLOCKING (12) — must fix before public release

WARN (11) — recommended

Full detection logic + fix actions → references/checklist.md

Scoring

SCORE = (blocking_pass / blocking_total) * 70 + (warn_pass / warn_total) * 30

A = score >= 90 AND 0 blocking failures
B = score >= 75 AND 0 blocking failures
C = score >= 60 (some blocking failures)
D = score >= 40
F = score < 40

Any blocking failure caps grade at C maximum.

Audit Output Format

═══════════════════════════════════════════════════════════════
 OSS READINESS — {org}/{repo}
 Version: {version} | Type: {npm|cargo|pip|go|app}
 Grade: {A-F} | Score: {0-100}
═══════════════════════════════════════════════════════════════

 BLOCKING
 ┌────────────────────────────────┬──────────┬───────────────────────┐
 │ Item                           │ Status   │ Note                  │
 ├────────────────────────────────┼──────────┼───────────────────────┤
 │ LICENSE                        │ PASS     │ MIT detected          │
 │ README.md                      │ WARN     │ Missing: usage, API   │
 │ llms.txt                       │ FAIL     │ Not found             │
 └────────────────────────────────┴──────────┴───────────────────────┘

 RECOMMENDED
 ┌────────────────────────────────┬──────────┬───────────────────────┐
 │ AGENTS.md                      │ FAIL     │ Not found             │
 │ Agent aliases                  │ WARN     │ AGENTS.md only        │
 └────────────────────────────────┴──────────┴───────────────────────┘

 BLOCKING failures: 2 — must fix before public release
 Warnings: 1 — recommended

 Run `scaffold missing OSS files` or `/oss fix` to scaffold missing files.
 Run `generate llms.txt` or `/oss llms` to create llms docs.
═══════════════════════════════════════════════════════════════

Scaffold Order

1. Detect stack (npm/cargo/python/go/app)
2. Run full checklist → identify missing items
3. Present: "Missing N BLOCKING + M WARN items. Scaffold all? [all / blocking only / pick]"
4. For each item:
   a. LICENSE → ask user for license type (MIT/Apache-2.0/ISC/GPL-3.0/BSD-3-Clause)
   b. README.md → scaffold from template placeholders
   c. CONTRIBUTING.md → fill template with repo + branch strategy
   d. SECURITY.md → fill template with repo + reporting channel placeholders
   e. CODE_OF_CONDUCT.md → fill Contributor Covenant template + conduct contact placeholder
   f. AGENTS.md → analyze repo, generate canonical instructions file
   g. Optional aliases → ask which harness aliases to create from AGENTS.md
   h. llms.txt + llms-full.txt → route to llms generation flow
   i. Issue templates → create .github/ISSUE_TEMPLATE/
   j. PR template → create .github/pull_request_template.md
   k. GitHub description/topics → update via `gh` when available
   l. CI workflows → generate starter workflow(s) based on stack
5. Report scaffolded files
6. Suggest re-running the audit before commit/push

Error Handling

References

• Checklist — full detection + fix logic for all 23 items
• LLMs Generation — llms.txt + llms-full.txt algorithm
• Version Sync — version detection + doc bumping
• CI Validation — CI pipeline rules + starter workflows
• Release Messaging — title, opening-summary, and announcement-quality rubric for public OSS releases

Templates

All scaffold templates live in templates/. Keep them generic and placeholder-driven.

OSS Readiness

Open-source/public release readiness skill: audit repos for OSS basics, scaffold missing release docs/templates, generate llms.txt + llms-full.txt, validate CI, and sync version references.

Install

npx skills add bntvllnt/agent-skills --skill oss-readiness

Global:

npx skills add bntvllnt/agent-skills --skill oss-readiness -g

Quick Start

Use natural language or slash-command shorthand:

• audit OSS readiness
• scaffold missing OSS files
• generate llms.txt
• bump stale version refs in docs
• check OSS CI readiness
• audit release messaging
• /oss
• /oss fix
• /oss llms
• /oss bump
• /oss ci

What It Covers

• Release docs: README.md, CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md
• AI docs: llms.txt, llms-full.txt
• Repo hygiene: .gitignore, changelog, issue/PR templates, topics, description
• CI checks: test/lint coverage, optional publish workflow for libraries
• Agent instructions: canonical AGENTS.md plus optional harness-specific aliases
• Release messaging: title quality, dominant-change selection, and opening-summary quality for public release notes or announcements

Portability

This skill is designed to work across agent harnesses:

• AGENTS.md is the canonical instructions file when scaffolded
• CLAUDE.md, .cursorrules, codex.md, .opencode/config, etc. are optional aliases
• Generated templates use placeholders instead of maintainer-specific links or handles
• Shell tooling (git, gh, node, python) is optional — helpful, not required

Reading Order

• Home/router: oss-readiness/SKILL.md
• Audit + scaffold logic: oss-readiness/references/checklist.md
• LLM docs generation: oss-readiness/references/llms-generation.md
• Version sync: oss-readiness/references/version-sync.md
• CI validation: oss-readiness/references/ci-validation.md
• Release messaging: oss-readiness/references/release-messaging.md
• Scaffold templates: oss-readiness/templates/

Requirements

• Any agent that supports SKILL.md frontmatter + Markdown routing
• Optional CLI helpers: git, gh, grep, find, jq, node, or python
• Optional validator: skills-ref validate ./oss-readiness

OSS Readiness Checklist

Detection logic, fix actions, and README quality sub-checks for all 23 items.

Placeholder Policy

Scaffolded files must stay portable:

• Use placeholders such as {PROJECT_REPO_URL}, {COMMUNITY_SUPPORT_URL}, {SECURITY_REPORTING_URL}, {CODE_OF_CONDUCT_CONTACT}, and {MAINTAINER_CONTACT_URL} until the target repo provides real values.
• Do not hardcode maintainer links, social handles, org names, or inboxes from this skill repository.
• Prefer an explicitly provided private security channel. If none exists, leave a placeholder and flag it for maintainer input.

Optional Release Messaging Checks

Run these when there is a concrete release draft, release tag, or announcement draft to evaluate.

These checks are advisory and not part of the 23-item OSS basics score unless the user explicitly asks for release-messaging review.

24. Release Title Matches the Dominant Change

• Detection: inspect the latest draft release / release notes / announcement headline
• Pass:
• title is specific
• title is outcome-first
• title is brief
• title reflects the dominant user-facing change
• title is truthful, not inflated
• Fail examples:
• Updates
• Workflow improvements
• Internal fixes
• Fix: rewrite the title around the main external outcome, not the most recent internal task

25. Opening Summary Reinforces the Title

• Detection: inspect the first 1-3 sentences or first bullets of the release notes / announcement
• Pass:
• opening lines reinforce the same story as the title
• the dominant change appears immediately
• vague filler does not lead the announcement
• opening lines are legible out of context in link previews or screenshots
• Fail examples:
• title says Faster local inference but opening lines lead with dependency upgrades
• title says Code review, supercharged but opening lines lead with generic workflow cleanup
• Fix: reorder and rewrite the opening summary so the dominant change is visible first

Use references/release-messaging.md for the cross-platform rubric.

BLOCKING Items (12)

For each item, provide: detection command, pass/fail criteria, and fix action.

1. LICENSE

• Detection: test -f LICENSE -o -f LICENSE.md -o -f LICENSE.txt
• Pass: file exists and is non-empty
• Fix: ask user for license type (MIT, Apache-2.0, ISC, GPL-3.0, BSD-3-Clause). Never default.

2. README.md Exists

• Detection: test -f README.md && test -s README.md
• Pass: file exists and >100 bytes
• Fix: scaffold from templates/README.md.

3. README.md Quality

Sub-checks (parse README.md content):

4. CONTRIBUTING.md

• Detection: test -f CONTRIBUTING.md
• Pass: file exists and >100 bytes
• Fix: scaffold from templates/CONTRIBUTING.md, fill placeholders.

5. .gitignore

• Detection: test -f .gitignore
• Pass: file exists
• Fix: generate stack-appropriate ignores (node_modules, dist, .venv, .env*, target artifacts, etc.).

6. No Secrets in Repo

• Detection:

  git ls-files | grep -E '\.env$|\.env\.' | grep -v '.env.example'
  git grep -l -E '(AKIA|sk-|ghp_|gho_|github_pat_|xox[bpas]-|Bearer [A-Za-z0-9])'
  git ls-files | grep -E '\.pem$|\.key$|id_rsa'

• Pass: all three return empty
• Fix: list offending files, suggest .gitignore updates, warn if history cleanup is required.

7. CI: Tests Run

• Detection:

  grep -rl -E 'npm test|pnpm test|yarn test|vitest|jest|pytest|cargo test|go test|bun test' .github/workflows/ 2>/dev/null

• Also check fallback CI files: .circleci/config.yml, .travis.yml, .gitlab-ci.yml, Jenkinsfile
• Pass: at least one workflow contains a test command
• Fix: generate starter CI workflow from references/ci-validation.md.

8. CI: Lint Runs

• Detection:

  grep -rl -E 'eslint|biome|prettier --check|clippy|ruff check|golangci|lint' .github/workflows/ 2>/dev/null

• Pass: at least one workflow contains a lint command
• Fix: add lint step to existing CI workflow or generate a new one.

9. GitHub Description Set

• Detection: gh repo view --json description -q '.description'
• Pass: non-empty string returned
• Fix: suggest description from package metadata or README first paragraph, then apply with gh repo edit --description "...".

10. CHANGELOG.md

• Detection: test -f CHANGELOG.md && grep -qE '## \[?[0-9]+\.[0-9]+' CHANGELOG.md
• Pass: file exists and contains at least one version heading
• Fix: scaffold initial CHANGELOG from tags and commit history.

11. llms.txt

• Detection: test -f llms.txt
• Pass: file exists and follows the expected H1 + link-list format
• Fix: route to llms generation flow.

12. llms-full.txt

• Detection: test -f llms-full.txt
• Pass: file exists and is non-empty (>1KB is a good heuristic)
• Fix: route to llms generation flow.

WARN Items (11)

13. GitHub Topics/Tags

• Detection: gh repo view --json repositoryTopics -q '.repositoryTopics[].name'
• Pass: at least 3 topics set
• Fix: suggest topics from package keywords, language, framework, and repo purpose.

14. AGENTS.md

• Detection: test -f AGENTS.md
• Pass: file exists and >200 bytes
• Fix: scaffold from templates/AGENTS.md. Treat it as the canonical agent-instructions file.

15. Harness-Specific Agent-Instruction Aliases

• Detection:

  find . -maxdepth 2 \( \
    -name 'CLAUDE.md' -o \
    -name '.cursorrules' -o \
    -name '.windsurfrules' -o \
    -name 'codex.md' -o \
    -path './.opencode/config' -o \
    -name '.aider.conf.yml' \
  \) | head -1

• Pass: at least one alias/mirror exists for the canonical AGENTS.md
• Fix: ask which harnesses need aliases, then symlink/copy from AGENTS.md when supported.
• Note: this is optional. AGENTS.md-only repos are still valid; this item improves discoverability across harnesses.

16. SECURITY.md

• Detection: test -f SECURITY.md || test -f .github/SECURITY.md
• Pass: file exists
• Fix: scaffold from templates/SECURITY.md with real/private reporting channel placeholders.

17. CODE_OF_CONDUCT.md

• Detection: test -f CODE_OF_CONDUCT.md
• Pass: file exists
• Fix: scaffold Contributor Covenant v2.1 from templates/CODE_OF_CONDUCT.md.

18. Issue Templates

• Detection: test -d .github/ISSUE_TEMPLATE && ls .github/ISSUE_TEMPLATE/*.yml 2>/dev/null | wc -l
• Pass: directory exists with at least 1 YAML form
• Fix: scaffold bug + feature templates + config.yml from templates/.

19. PR Template

• Detection: test -f .github/pull_request_template.md
• Pass: file exists
• Fix: scaffold from templates/pr-template.md.

20. CI: Publish Workflow (libraries only)

• Detection: only check when the repo looks like a publishable library.

  grep -rl -E 'npm publish|cargo publish|twine upload|goreleaser|semantic-release|changesets' .github/workflows/ 2>/dev/null

• Pass: at least one publish workflow found (or repo is not a library)
• Fix: suggest or scaffold a release workflow. See references/ci-validation.md.

21. docs/ Folder

• Detection: test -d docs && find docs -name "*.md" -type f | head -1
• Pass: directory exists with at least one Markdown file
• Fix: mkdir -p docs and suggest an initial docs structure.

22. Version in Docs Matches Package

• Detection: compare manifest/tag version against README.md, docs/**, llms.txt, llms-full.txt, AGENTS.md, and known alias files.
• Pass: no stale version references found
• Fix: route to version-sync flow.

23. No TODO/FIXME in Public src/

• Detection:

  grep -rn -E '(TODO|FIXME|HACK|XXX|TEMP)' src/ lib/ --include='*.ts' --include='*.js' --include='*.rs' --include='*.py' --include='*.go' 2>/dev/null | head -20

• Pass: zero matches (or no public source tree exists)
• Fix: list locations and suggest resolving or moving to issues.

Scaffold Order

When the fix flow is invoked, scaffold in this order:

1. .gitignore (first — helps prevent accidental secret commits)
2. LICENSE (ask user for type)
3. README.md
4. CONTRIBUTING.md
5. CODE_OF_CONDUCT.md
6. SECURITY.md
7. AGENTS.md (canonical instructions file)
8. Optional harness aliases for AGENTS.md
9. CHANGELOG.md
10. .github/ISSUE_TEMPLATE/ (bug + feature + config)
11. .github/pull_request_template.md
12. .github/workflows/ci.yml (if no CI exists)
13. llms.txt + llms-full.txt (last — after docs exist)

Scoring Algorithm

blocking_total = 12
blocking_pass = count(blocking items with status == PASS)
warn_total = 11
warn_pass = count(warn items with status == PASS)

score = (blocking_pass / blocking_total) * 70 + (warn_pass / warn_total) * 30

if blocking_pass == blocking_total:
    if score >= 90:
        grade = "A"
    elif score >= 75:
        grade = "B"
    else:
        grade = "C"
else:
    if score >= 60:
        grade = "C"
    elif score >= 40:
        grade = "D"
    else:
        grade = "F"

CI Validation

CI pipeline detection, workflow analysis, and starter workflow generation for the CI-check flow (/oss ci or equivalent natural-language request).

CI System Detection

# GitHub Actions (primary)
GH_WORKFLOWS=$(find .github/workflows -name "*.yml" -o -name "*.yaml" 2>/dev/null)

# Fallback CI systems
test -f .circleci/config.yml && CI_SYSTEM="circleci"
test -f .travis.yml && CI_SYSTEM="travis"
test -f Jenkinsfile && CI_SYSTEM="jenkins"
test -f .gitlab-ci.yml && CI_SYSTEM="gitlab"
test -f bitbucket-pipelines.yml && CI_SYSTEM="bitbucket"

If no CI detected: report as BLOCKING failure with scaffold option.

Workflow Analysis (GitHub Actions)

For each workflow file, grep for job types:

Trigger Validation

Branch Protection Check

# Check if branch protection exists on default branch
DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef -q '.defaultBranchRef.name')
gh api "repos/{owner}/{repo}/branches/$DEFAULT_BRANCH/protection" 2>/dev/null
# 200 = protected, 404 = not protected

CI Report Format

CI VALIDATION — {repo}
═══════════════════════════════════════

CI System: GitHub Actions
Workflows: {count} found

┌──────────────┬──────────┬────────────────────────────────┐
│ Check        │ Status   │ Details                        │
├──────────────┼──────────┼────────────────────────────────┤
│ Tests        │ PASS     │ ci.yml: vitest run             │
│ Lint         │ PASS     │ ci.yml: biome check            │
│ Build        │ PASS     │ ci.yml: tsc --noEmit           │
│ Publish      │ FAIL     │ No publish workflow found      │
│ Triggers     │ PASS     │ push + pull_request            │
│ Branch prot. │ WARN     │ No branch protection on main   │
└──────────────┴──────────┴────────────────────────────────┘

Starter Workflow Generation

When no CI exists, generate .github/workflows/ci.yml based on detected stack:

Node.js (pnpm example)

name: CI

on:
  pull_request:
    branches: [main]

concurrency:
  group: ci-${{ github.head_ref }}
  cancel-in-progress: true

jobs:
  quality:
    name: Quality Gates
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - name: Lint
        run: pnpm run lint
      - name: Typecheck
        run: pnpm run check-types     # or: pnpm exec tsc --noEmit
      - name: Build
        run: pnpm run build
      - name: Test
        run: pnpm test

Node.js (npm — fallback)

name: CI

on:
  pull_request:
    branches: [main]

concurrency:
  group: ci-${{ github.head_ref }}
  cancel-in-progress: true

jobs:
  quality:
    name: Quality Gates
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npm run lint
      - run: npm test

Rust (Cargo)

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
        with:
          components: clippy, rustfmt
      - run: cargo fmt --check
      - run: cargo clippy -- -D warnings
      - run: cargo test

Python (pip/poetry/uv)

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install -e ".[dev]"    # adjust for your setup
      - run: ruff check .               # or: flake8, pylint
      - run: pytest                      # adjust as needed

Go

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: 'stable'
      - run: go vet ./...
      - run: golangci-lint run          # install golangci-lint first
      - run: go test ./...

Package Manager Detection for Workflow

# Detect package manager for Node.js projects
if [ -f pnpm-lock.yaml ]; then PM="pnpm"
elif [ -f yarn.lock ]; then PM="yarn"
elif [ -f bun.lockb ]; then PM="bun"
elif [ -f package-lock.json ]; then PM="npm"
else PM="npm"
fi

Publish Workflow (Libraries Only — example pattern)

When IS_LIBRARY=true and no publish workflow exists, suggest a two-track publish:

• Canary: auto on push to main (version: x.y.z-canary.{sha}, tag: canary)
• Release: manual workflow_dispatch with version bump choice (patch/minor/major)

Both use npm OIDC provenance (no NPM_TOKEN secret needed — uses id-token: write).

name: Publish

on:
  push:
    branches: [main]
    paths:
      - "src/**"
      - "pnpm-lock.yaml"
      - ".github/workflows/publish.yml"
  workflow_dispatch:
    inputs:
      bump:
        description: "Version bump type"
        required: true
        type: choice
        options: [patch, minor, major]

permissions:
  contents: write
  id-token: write

jobs:
  quality:
    name: Quality Gates
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm run lint
      - run: pnpm run build
      - run: pnpm test

  canary:
    name: Publish Canary
    needs: quality
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
          registry-url: https://registry.npmjs.org
      - run: pnpm install --frozen-lockfile
      - run: pnpm run build
      - name: Upgrade npm for OIDC support
        run: npm install -g npm@latest
      - name: Publish canary
        run: |
          sed -i '/_authToken/d' "$NPM_CONFIG_USERCONFIG"
          unset NODE_AUTH_TOKEN
          BASE_VERSION=$(node -p "require('./package.json').version")
          SHORT_SHA=$(echo "$GITHUB_SHA" | cut -c1-7)
          CANARY_VERSION="${BASE_VERSION}-canary.${SHORT_SHA}"
          npm version "$CANARY_VERSION" --no-git-tag-version
          TARBALL=$(pnpm pack --pack-destination /tmp | tail -1)
          npm publish "$TARBALL" --tag canary --provenance --access public

  release:
    name: Publish Release
    needs: quality
    if: github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      id-token: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
          registry-url: https://registry.npmjs.org
      - run: pnpm install --frozen-lockfile
      - run: pnpm run build
      - name: Bump version
        id: version
        run: |
          npm version ${{ inputs.bump }} --no-git-tag-version
          VERSION=$(node -p "require('./package.json').version")
          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
      - name: Commit and tag
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add package.json
          git commit -m "chore(release): v${{ steps.version.outputs.version }}"
          git tag -a "v${{ steps.version.outputs.version }}" -m "v${{ steps.version.outputs.version }}"
          git push origin main --follow-tags
      - name: Upgrade npm for OIDC support
        run: npm install -g npm@latest
      - name: Publish to npm
        run: |
          sed -i '/_authToken/d' "$NPM_CONFIG_USERCONFIG"
          unset NODE_AUTH_TOKEN
          TARBALL=$(pnpm pack --pack-destination /tmp | tail -1)
          npm publish "$TARBALL" --tag latest --provenance --access public
      - name: Create GitHub Release
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh release create "v${{ steps.version.outputs.version }}" \
            --title "v${{ steps.version.outputs.version }}" \
            --generate-notes

Key patterns in this example:

• Full OIDC/provenance flow — avoids long-lived registry secrets when the registry supports it
• sed -i '/_authToken/d' clears package-manager auth before npm publish
• pnpm pack → npm publish avoids package-manager-specific publish auth edge cases
• Canary versions: {base}-canary.{sha7}
• Release via workflow_dispatch with bump type choice
• permissions: contents: write + id-token: write cover both git push and package provenance
• concurrency with cancel-in-progress reduces duplicate CI work

Non-GitHub CI Systems

For non-GitHub CI (CircleCI, Travis, GitLab CI), only validate existence + test/lint presence. Do not generate config — too many variations. Report:

CI System: {system} detected
Test job: {PASS|FAIL} — {details}
Lint job: {PASS|FAIL} — {details}

Note: Starter workflow generation only supports GitHub Actions.
For {system}, manually verify test and lint jobs exist.

LLMs Generation

Algorithm for generating llms.txt and llms-full.txt files per the llmstxt.org specification.

Overview

/oss llms
  │
  ├─ 1. Detect metadata (name, description, version)
  ├─ 2. Discover documentation files
  ├─ 3. Generate llms.txt (index with links)
  ├─ 4. Generate llms-full.txt (full content)
  └─ 5. Report results

Step 1: Metadata Detection

# Package name
NAME=$(
  node -e "console.log(require('./package.json').name)" 2>/dev/null ||
  grep '^name' Cargo.toml 2>/dev/null | head -1 | sed 's/.*= *"\(.*\)"/\1/' ||
  grep '^name' pyproject.toml 2>/dev/null | head -1 | sed 's/.*= *"\(.*\)"/\1/' ||
  basename $(git rev-parse --show-toplevel 2>/dev/null || pwd)
)

# Description
DESC=$(
  node -e "console.log(require('./package.json').description || '')" 2>/dev/null ||
  gh repo view --json description -q '.description' 2>/dev/null ||
  head -5 README.md 2>/dev/null | grep -v '^#' | head -1
)

# Version
VERSION=$(
  node -e "console.log(require('./package.json').version)" 2>/dev/null ||
  grep '^version' Cargo.toml 2>/dev/null | head -1 | sed 's/.*= *"\(.*\)"/\1/' ||
  grep '^version' pyproject.toml 2>/dev/null | head -1 | sed 's/.*= *"\(.*\)"/\1/' ||
  git describe --tags --abbrev=0 2>/dev/null ||
  echo "0.0.0"
)

Step 2: Content Discovery

Scan repo for documentation files in priority order:

# Core docs (always included)
README="README.md"
CONTRIBUTING=$(test -f CONTRIBUTING.md && echo "CONTRIBUTING.md")
CHANGELOG=$(test -f CHANGELOG.md && echo "CHANGELOG.md")
LICENSE=$(ls LICENSE* 2>/dev/null | head -1)

# Documentation directory
DOCS=$(find docs/ -name "*.md" -type f 2>/dev/null | sort)

# API documentation
API_DOCS=$(
  find docs/api* -name "*.md" 2>/dev/null ||
  find api-docs/ -name "*.md" 2>/dev/null ||
  find docs/ -name "api*.md" 2>/dev/null
)

# Examples
EXAMPLES=$(find examples/ -type f 2>/dev/null | sort)

# Additional docs
SECURITY=$(test -f SECURITY.md && echo "SECURITY.md")
COC=$(test -f CODE_OF_CONDUCT.md && echo "CODE_OF_CONDUCT.md")
AGENTS=$(test -f AGENTS.md && echo "AGENTS.md")

Step 3: Generate llms.txt

Format per llmstxt.org specification:

# {NAME}

> {DESC}

{First paragraph of README.md — extract text between H1 and first H2, strip markdown formatting}

## Docs

- [README](README.md): Project overview, installation, and usage guide
- [Contributing](CONTRIBUTING.md): How to contribute to this project
- [Changelog](CHANGELOG.md): Version history and release notes

## API Reference

- [{doc_name}]({doc_path}): {first line of file or generated description}

## Examples

- [{example_name}]({example_path}): {description from first comment or filename}

## Optional

- [Security Policy](SECURITY.md): Vulnerability reporting and disclosure policy
- [Code of Conduct](CODE_OF_CONDUCT.md): Community guidelines
- [License](LICENSE): {license type} license

llms.txt Format Rules

1. H1 (required): Package/project name — the only mandatory element 2. Blockquote (optional): One-line description with key context 3. Body (optional): Paragraphs/lists but NO headings — project overview 4. H2 sections (optional): Each contains a markdown list of resources 5. Each list item: - [name](url): description format (colon + description optional) 6. "Optional" section: If included, signals these URLs can be skipped for shorter contexts 7. Use relative paths for repo files (not absolute URLs)

Section Selection Logic

Always include:
  - Docs section (README, CONTRIBUTING, CHANGELOG — if they exist)

Include if files exist:
  - API Reference (docs/api*.md or similar)
  - Examples (examples/ directory)

Always include as Optional:
  - Security, Code of Conduct, License

Description Generation

For each linked file, generate a concise description:

• README.md: "Project overview, installation, and usage guide"
• CONTRIBUTING.md: "Contribution guidelines and development setup"
• CHANGELOG.md: "Version history and release notes"
• API docs: Extract first line/heading of the file
• Examples: Use filename or first comment line
• If unknown: "{filename} documentation"

Step 4: Generate llms-full.txt

Same H1 + blockquote header as llms.txt, but embeds full content:

# {NAME}

> {DESC}

{First paragraph of README.md}

## Docs

### README
{Full README.md content — strip badges/shields if desired}

### Contributing
{Full CONTRIBUTING.md content}

### Changelog
{CHANGELOG.md content — TRUNCATED to last 5 versions if file >20KB}

## API Reference

### {API Doc Title}
Source: {relative_path}

{Full content of API doc file}

## Examples

### {Example Name}
Source: {relative_path}

{Full content of example file}

## Optional

### Security Policy
Source: SECURITY.md

{Full SECURITY.md content}

### Code of Conduct
Source: CODE_OF_CONDUCT.md

{Full CODE_OF_CONDUCT.md content}

Content Embedding Rules

1. Each document becomes an H3 under its parent H2 section 2. Add Source: {path} line for attribution 3. Preserve all original markdown formatting 4. Code files wrapped in fenced code blocks with language tag 5. Binary files skipped with note: "Binary file — see source"

Size Management

TARGET_MAX = 100KB

If total size > 100KB:
  1. Truncate CHANGELOG to last 3 versions (not 5)
  2. Truncate examples to first 5 files
  3. Remove Optional section content (keep links only)
  4. If STILL > 100KB: truncate longest docs to first 500 lines each
  5. Add footer: "Full documentation available at {repo_url}"

CHANGELOG Truncation

# Extract last N version entries from CHANGELOG.md
# Versions detected by: ## [x.y.z] or ## x.y.z or ### [x.y.z]
# Keep everything from start of file to Nth version heading

Step 5: Report

After generation, output:

Generated:
  llms.txt     — {entry_count} entries, {size}KB
  llms-full.txt — {doc_count} documents, {size}KB

Files included:
  - README.md (core)
  - CONTRIBUTING.md (core)
  - CHANGELOG.md (core, last 5 versions)
  - docs/api.md (API reference)
  - examples/basic.ts (example)
  ...

Size budget: {used}KB / 100KB

Regeneration

When called:

• If llms.txt/llms-full.txt already exist, overwrite them
• After /oss bump, regenerate both files automatically
• After /oss fix scaffolds new docs, regenerate both files

Edge Cases

Release Messaging

Cross-platform rubric for evaluating OSS release titles, release-note openings, and launch-announcement framing.

Use this when the user asks things like:

• is this a good OSS release title?
• audit release messaging
• improve the release title
• rewrite the opening release notes
• does this announcement read like a real release?

Core Principle

The title and opening lines should make the release legible to an outsider in one glance.

That means:

• name the dominant user-facing change
• say it in plain language
• avoid internal-only framing
• avoid hype the diff does not support

Preconditions

Before writing a title or lead summary, confirm:

1. Stable scope

• The merged or imminent release diff is known

2. Dominant change selected

• One main external change is identified

3. Audience selected

• Users, contributors, operators, or developers evaluating the project

4. Truthfulness check

• The claim is strong but supported by the release

Title Rubric

A strong OSS release title is:

• specific
• outcome-first
• brief
• truthful
• aligned with the dominant change

Good:

• v1.13.1 — Code review, supercharged
• v0.8.0 — Faster local inference
• v2.4.0 — Rules discovery everywhere

Weak:

• v1.13.1 — Updates
• v0.8.0 — Workflow improvements
• v2.4.0 — Internal cleanup

Opening Summary Rubric

The first 1-3 sentences or first bullets should:

• reinforce the same story as the title
• surface the dominant change immediately
• avoid leading with maintenance work if the release is really about a feature or capability
• be understandable when quoted in chat previews or screenshots

Bad pattern:

v1.13.1 — Code review, supercharged

This release includes several cleanup items, internal refactors, and minor workflow changes...

Better pattern:

v1.13.1 — Code review, supercharged

This release hardens review in the workflow skill with line-by-line coverage, rule-by-rule enforcement, and fail-closed review output.

Anti-Patterns

Avoid:

• vague nouns: updates, improvements, changes
• internal-only framing when the release is externally meaningful
• hype words with no evidence
• titles that depend on prior context to make sense
• opening summaries that bury the real release story under housekeeping

Fast Evaluation Checklist

• Can a new reader tell what changed from the title alone?
• Does the title describe the dominant external outcome?
• Do the opening lines reinforce that same outcome?
• Would the title still work if shown alone on a social card?
• Is the wording strong without overselling?

If any answer is no, rewrite before publishing.

Version Sync

Version detection, reference scanning, and doc bumping logic for the version-sync flow (/oss bump or equivalent natural-language request).

Version Detection

Previous Version Detection

# Get all semver tags sorted descending
TAGS=$(git tag --sort=-v:refname | grep -E '^v?[0-9]+\.[0-9]+\.[0-9]+' | head -5)

# V_CURRENT = first tag (or from manifest)
# V_PREV = second tag
V_PREV=$(echo "$TAGS" | sed -n '2p')

If no tags exist: skip version bump, report "No version tags found. Tag a release first."

Version Reference Scanning

Files to Scan

README.md
docs/**/*.md
llms.txt
llms-full.txt
AGENTS.md
selected harness aliases (for example: CLAUDE.md, .cursorrules, .windsurfrules, codex.md, .opencode/config)
CHANGELOG.md (verify V_CURRENT entry exists)

Patterns to Match

# Exact version string (most common)
{V_PREV}

# Common version patterns in docs:
npm install {package}@{V_PREV}
pip install {package}=={V_PREV}
cargo add {package}@{V_PREV}
go get {module}@v{V_PREV}

# Badge URLs
badge/v{V_PREV}
shields.io/.*{V_PREV}

# Docker tags
:{V_PREV}

# CDN/download URLs
/v{V_PREV}/
/download/{V_PREV}/
/releases/tag/v{V_PREV}

Scan Command

# Strip 'v' prefix for matching both v1.2.3 and 1.2.3
V_BARE=$(echo "$V_PREV" | sed 's/^v//')

ALIASES=$(find . -maxdepth 2 \( \
  -name 'CLAUDE.md' -o \
  -name '.cursorrules' -o \
  -name '.windsurfrules' -o \
  -name 'codex.md' -o \
  -path './.opencode/config' -o \
  -name '.aider.conf.yml' \
\) 2>/dev/null)

# Scan all target files
printf '%s\n' README.md docs/ llms.txt llms-full.txt AGENTS.md $ALIASES |
  xargs -r grep -rn "$V_BARE" 2>/dev/null

Bump Preview

Present matches to user before applying:

Version bump: {V_PREV} → {V_CURRENT}

Found {N} references to update:

  README.md:15     npm install foo@1.2.3     →  npm install foo@1.3.0
  README.md:42     badge/v1.2.3              →  badge/v1.3.0
  docs/api.md:3    Since v1.2.3              →  Since v1.3.0
  llms.txt:2       > foo v1.2.3              →  > foo v1.3.0

Apply all? [yes / pick / cancel]

Bump Apply

After user confirmation:

1. For each match, replace V_PREV with V_CURRENT using the agent's file-edit capability 2. Verify CHANGELOG.md has entry for V_CURRENT

• If missing: warn "CHANGELOG.md has no entry for {V_CURRENT}. Add one?"

3. If llms.txt or llms-full.txt exist: regenerate via the llms generation flow 4. Re-scan to verify 0 stale references remain

CHANGELOG Verification

# Check CHANGELOG has current version
grep -q "$V_CURRENT" CHANGELOG.md

# If missing, suggest entry:
echo "## [{V_CURRENT}] - $(date +%Y-%m-%d)"
echo ""
echo "### Added"
echo "- "
echo ""
echo "### Changed"
echo "- "
echo ""
echo "### Fixed"
echo "- "

Edge Cases

{REPO_NAME}

{DESCRIPTION}

AGENTS.md is the canonical agent-instructions file for this repository. Optional harness-specific aliases (for example CLAUDE.md, .cursorrules, codex.md, or .opencode/config) may mirror this file when needed.

Project Overview

• Tech Stack: {STACK_WITH_VERSIONS}
• Runtime(s): {RUNTIMES}
• Package Manager / Tooling: {TOOLCHAIN}
• License: {LICENSE_TYPE}

Repository Layout

{REPO_NAME}/
├── src/            # Main source code
├── tests/          # Automated tests
├── docs/           # Human-facing docs
├── .github/        # CI, issue templates, PR template
└── {ENTRY_FILES}   # Main entrypoints / package metadata

Adjust the layout example to match the actual repository.

Common Commands

Remove commands that do not exist for the target repo.

Code Style

• Languages: {LANGUAGE_GUIDELINES}
• Formatting/Linting: {LINT_TOOLING}
• Testing: {TEST_TOOLING}
• Validation: {VALIDATION_APPROACH}
• Naming: {NAMING_CONVENTIONS}

Fill this section from the repo's actual conventions. Do not assume TypeScript, Node.js, or any single framework.

Git Workflow

• Branch from {PRIMARY_BRANCH}
• Prefer conventional commits: feat:, fix:, docs:, chore:, refactor:, test:, perf:
• Open focused PRs with passing CI before merge
• Document any repo-specific merge strategy here

Boundaries

Always:

• Follow existing code patterns
• Update tests when behavior changes
• Update docs when public behavior changes

Ask first:

• Adding new dependencies or services
• Changing public APIs or schemas
• Modifying CI/CD or release automation
• Touching security-sensitive configuration

Never:

• Commit secrets, credentials, or private keys
• Rewrite shared history without approval
• Disable quality gates without documenting why

Support / Community

• Repository: {PROJECT_REPO_URL}
• Homepage / Docs: {PROJECT_HOMEPAGE}
• Support / Discussion: {COMMUNITY_SUPPORT_URL}
• Security Reporting: {SECURITY_REPORTING_URL}
• Maintainer / Org: {MAINTAINER_NAME}
• Optional Contact: {MAINTAINER_CONTACT_URL}

Remove optional rows that the target project does not use.

Contributor Covenant Code of Conduct

Our Pledge

We as members, contributors, and leaders pledge to make participation in our community a welcoming experience for everyone, regardless of background or identity.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

Our Standards

Examples of behavior that contributes to a positive environment:

• Using welcoming and inclusive language
• Being respectful of differing viewpoints and experiences
• Gracefully accepting constructive criticism
• Focusing on what is best for the community
• Showing empathy towards other community members

Examples of unacceptable behavior:

• Trolling, insulting or derogatory comments, and personal attacks
• Public or private harassment
• Publishing others' private information without explicit permission
• Other conduct which could reasonably be considered inappropriate in a

professional setting

Enforcement Responsibilities

Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate or harmful.

Scope

This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces.

Enforcement

Instances of unacceptable behavior may be reported via {CODE_OF_CONDUCT_CONTACT}.

All complaints will be reviewed and investigated promptly and fairly.

Enforcement Guidelines

Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:

1. Correction

Impact: Minor unprofessional behavior. Consequence: A private, written warning with clarity around the nature of the violation.

2. Warning

Impact: A violation through a single incident or series of actions. Consequence: A warning with consequences for continued behavior. No interaction with the people involved for a specified period of time.

3. Temporary Ban

Impact: Serious violation of community standards. Consequence: A temporary ban from any sort of interaction or public communication with the community for a specified period of time.

4. Permanent Ban

Impact: Demonstrating a pattern of violation of community standards. Consequence: A permanent ban from any sort of public interaction within the community.

Attribution

This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].

[homepage]: https://www.contributor-covenant.org [v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

Contributing to {REPO_NAME}

Thanks for your interest in contributing.

Code of Conduct

This project follows the Contributor Covenant. By participating, you agree to uphold it. Report unacceptable behavior via {CODE_OF_CONDUCT_CONTACT}.

How to Contribute

Reporting Bugs

1. Check existing issues first 2. Use the bug report template 3. Include: steps to reproduce, expected vs actual behavior, environment details, and relevant logs

Suggesting Features

1. Check existing requests 2. Use the feature request template 3. Describe the problem you're solving, not just the proposed solution

Submitting Changes

1. Fork the repository 2. Create a feature branch: git checkout -b feat/your-change 3. Make your changes 4. Run quality checks:

   {QUALITY_COMMANDS}

5. Commit using conventional commits when they fit the repo workflow 6. Push and open a Pull Request against {PRIMARY_BRANCH}

Development Setup

git clone {PROJECT_REPO_URL}.git
cd {REPO_NAME}
{SETUP_COMMANDS}

Pull Request Guidelines

• Keep PRs focused — one feature or fix per PR
• Update tests for behavior changes
• Update docs for public behavior changes
• Ensure CI passes before requesting review
• Note any follow-up work or known limitations

Style Guide

• Follow existing code patterns in the repository
• See AGENTS.md for repo-specific agent/developer conventions
• Avoid unrelated refactors in feature PRs

First-Time Contributors

Look for issues labeled `good first issue`.

Community

• Repository: {PROJECT_REPO_URL}
• Homepage / Docs: {PROJECT_HOMEPAGE}
• Support / Discussion: {COMMUNITY_SUPPORT_URL}
• Security Reporting: {SECURITY_REPORTING_URL}
• Maintainer / Org: {MAINTAINER_NAME}
• Optional Contact: {MAINTAINER_CONTACT_URL}

Remove optional rows the target project does not use.

License

By contributing, you agree that your contributions will be licensed under the same license as the project ({LICENSE_TYPE}).

Bug Report Issue Template

Place this file at .github/ISSUE_TEMPLATE/bug_report.yml in the target repo.

name: Bug Report
description: Report a bug or unexpected behavior
title: "[Bug]: "
labels: ["bug", "triage"]
body:
  - type: markdown
    attributes:
      value: |
        Thanks for reporting. Please fill out the sections below.

  - type: textarea
    id: what-happened
    attributes:
      label: What happened?
      description: Describe the bug clearly
      placeholder: When I do X, Y happens instead of Z
    validations:
      required: true

  - type: textarea
    id: steps
    attributes:
      label: Steps to reproduce
      description: Minimal steps to reproduce the issue
      placeholder: |
        1. Install the project
        2. Run command or workflow X
        3. See error
    validations:
      required: true

  - type: textarea
    id: expected
    attributes:
      label: Expected behavior
      description: What did you expect to happen?
    validations:
      required: true

  - type: textarea
    id: environment
    attributes:
      label: Environment
      description: Your setup details
      value: |
        - OS:
        - Runtime / language version:
        - Project version / commit:
        - Package manager / tooling:
    validations:
      required: true

  - type: textarea
    id: logs
    attributes:
      label: Relevant logs
      description: Paste any error output or stack traces
      render: shell
    validations:
      required: false

  - type: checkboxes
    id: checks
    attributes:
      label: Before submitting
      options:
        - label: I searched existing issues and this hasn't been reported
          required: true
        - label: I tested against the latest supported version when possible
          required: false

Also create .github/ISSUE_TEMPLATE/config.yml:

blank_issues_enabled: false
contact_links:
  - name: Security Vulnerability
    url: {SECURITY_REPORTING_URL}
    about: Report security vulnerabilities privately
  - name: Support / Discussion
    url: {COMMUNITY_SUPPORT_URL}
    about: Ask questions or discuss usage
  - name: Project Homepage / Docs
    url: {PROJECT_HOMEPAGE}
    about: Learn more about the project

Feature Request Issue Template

Place this file at .github/ISSUE_TEMPLATE/feature_request.yml in the target repo.

name: Feature Request
description: Suggest a new feature or improvement
title: "[Feature]: "
labels: ["enhancement"]
body:
  - type: textarea
    id: problem
    attributes:
      label: Problem
      description: What problem does this solve? What's your use case?
      placeholder: I'm always frustrated when...
    validations:
      required: true

  - type: textarea
    id: solution
    attributes:
      label: Proposed solution
      description: How would you like this to work?
    validations:
      required: true

  - type: textarea
    id: alternatives
    attributes:
      label: Alternatives considered
      description: What else have you tried or considered?
    validations:
      required: false

  - type: checkboxes
    id: contribution
    attributes:
      label: Contribution
      options:
        - label: I'd be willing to help implement this
          required: false

<!-- Generated by the OSS readiness llms flow — do not edit manually --> <!-- Format: llmstxt.org specification (full content variant) --> <!-- Size budget: 100KB max. Truncation applied if exceeded. -->

{PACKAGE_NAME}

{DESCRIPTION}

{OVERVIEW_PARAGRAPH}

Docs

README

{FULL_README_CONTENT}

Contributing

{FULL_CONTRIBUTING_CONTENT}

Changelog

{FULL_CHANGELOG_CONTENT — last 5 versions only}

API Reference

{API_DOC_TITLE}

Source: {relative_path}

{FULL_API_DOC_CONTENT}

Examples

{EXAMPLE_NAME}

Source: {relative_path}

```{language} {FULL_EXAMPLE_CONTENT}

## Optional

### Security Policy

Source: SECURITY.md

{FULL_SECURITY_CONTENT}

### Code of Conduct

Source: CODE_OF_CONDUCT.md

{FULL_CODE_OF_CONDUCT_CONTENT}

<!-- Generated by the OSS readiness llms flow — do not edit manually --> <!-- Format: llmstxt.org specification -->

{PACKAGE_NAME}

{DESCRIPTION}

{OVERVIEW_PARAGRAPH}

Docs

• README: Project overview, installation, and usage
• Contributing: Contribution guidelines and development setup
• Changelog: Version history and release notes

API Reference

• {API_DOC_NAME}: {API_DOC_DESCRIPTION}

Examples

• {EXAMPLE_NAME}: {EXAMPLE_DESCRIPTION}

Optional

• Security: Vulnerability reporting policy
• Code of Conduct: Community guidelines
• License: {LICENSE_TYPE} license

Pull Request Template

Place this file at .github/pull_request_template.md in the target repo.

## Summary

<!-- What does this PR do and why? Link related issues with "Closes #123" -->

## Changes

<!-- Bullet list of specific changes made -->

-

## Type

<!-- Check the relevant box -->

- [ ] Feature (new functionality)
- [ ] Bug fix (non-breaking fix)
- [ ] Refactor (no behavior change)
- [ ] Docs (documentation only)
- [ ] Chore (dependencies, CI, tooling)

## Testing

<!-- How did you verify this works? Steps a reviewer can follow. -->

1.

## Checklist

- [ ] Tests pass locally
- [ ] Linter passes
- [ ] Self-reviewed the diff
- [ ] Updated docs (if behavior changed)
- [ ] No debug artifacts left behind

{REPO_NAME}

{DESCRIPTION}

Install

{INSTALL_COMMANDS}

Usage

{USAGE_EXAMPLE}

Key Concepts

• Purpose: {PROJECT_PURPOSE}
• Primary users: {TARGET_USERS}
• Core workflows: {CORE_WORKFLOWS}

API / Reference

• {API_REFERENCE_LINK_OR_NOTE}

Contributing

See CONTRIBUTING.md for development setup, contribution rules, and pull request expectations.

Security

Report vulnerabilities via {SECURITY_REPORTING_URL}.

License

Licensed under {LICENSE_TYPE}.

Security Policy

Supported Versions

Only the latest release receives security updates unless stated otherwise.

Reporting a Vulnerability

Do not open a public issue for security vulnerabilities unless the project explicitly says to do so.

Preferred Method

Report vulnerabilities privately via {SECURITY_REPORTING_URL}.

Examples:

• GitHub Security Advisories URL
• Dedicated security email address
• Private contact form
• Security intake portal

What to Include

• Description of the vulnerability
• Steps to reproduce
• Affected versions / commit range
• Potential impact
• Suggested fix or mitigation (if known)

Response Timeline

Adjust these targets to match the maintainer's actual policy.

Credit

We credit reporters in release notes, advisories, or CVE entries when appropriate. If you prefer to remain anonymous, say so in your report.

Scope

This policy covers the {REPO_NAME} project and the source code in this repository. Third-party dependencies are out of scope unless the maintainers explicitly state otherwise.

---

Maintained by {MAINTAINER_NAME}