Setup for OSS

Quick start

1. Decide mode:

- Audit mode: user asks to review/check OSS health. - Scaffold mode: user asks to set up/add OSS files or workflows.

1. Collect context (minimal):

- Repo name, package manager, monorepo vs single package, publishable npm packages. - Author/org details from package.json or git config. - Existing health files and workflows.

1. Load references as needed:

- Health files: references/health-files.md - GitHub templates: references/github-templates.md - CI workflows: references/ci-workflows.md - Publishing: references/publishing.md - Linting/formatting: references/linting-formatting.md - Dependency/versioning: references/dependency-versioning.md

Mode decision tree

• If the request includes audit/review/check: run Audit mode and return a prioritized missing/incomplete list.
• If the request includes setup/add/bootstrap/scaffold: run Scaffold mode and create/modify files.
• If unclear, default to Audit mode and ask a single clarifying question only if blocking.

Context detection checklist

Use this before auditing or scaffolding:

• Project name: from package.json:name or repo folder name.
• Author/org: from package.json:author, repository, or git config.
• Package manager:

- pnpm-lock.yaml → pnpm - package-lock.json → npm - yarn.lock → yarn - bun.lockb → bun

• Monorepo vs single:

- workspaces in package.json, pnpm-workspace.yaml, or turbo.json → monorepo

• Publishable packages:

- package.json:private=false or packages with publishConfig

• Has tests:

- test script, vitest, jest, playwright, or tests directories

• Conventional commit scopes:

- workspace package/app names for monorepo; otherwise top-level areas (src/docs/ci)

Audit mode

1. Scan for required health files and templates:

- README, CONTRIBUTING, CODEOFCONDUCT, LICENSE, SECURITY - .github issue templates, PR template, release config, funding

1. Scan for CI/CD workflows:

- autofix.yml, ci.yml, semantic-pull-request.yml, label-pr.yml

1. If publishable npm packages exist, verify:

- ci.yml includes publish job using pkg-pr-new (PR-only) - release.yml uses npm Trusted Publishing (OIDC) and pinned SHAs

1. Scan for Renovate config, linting/formatting, versioning tooling:

- renovate.json, eslint.config.js, .editorconfig, .changeset/config.json, .npmrc, .config/automd.ts

1. Produce a report:

- Missing files - Incomplete/misaligned content (e.g., wrong license or missing security reporting) - Optional vs required (explicit) - Minimal next steps

Scaffold mode

1. Create any missing required files using templates in references.
2. Adapt content:

- Replace placeholders with project name, author/org, repo URLs, and package manager. - Include CI jobs only relevant to the repo (test job only if tests exist). - Include publishing and release workflows only if publishable packages exist.

1. Ensure all outputs are in English.
2. Summarize what was created/updated and any manual follow-ups (e.g., install GitHub Apps).

Required vs optional outputs

Required (always when scaffolding OSS setup):

• README.md
• CONTRIBUTING.md
• CODEOFCONDUCT.md
• LICENSE (Apache-2.0 default unless specified)
• SECURITY.md
• .github/funding.yml
• .github/ISSUE_TEMPLATE/bug-report.yml
• .github/ISSUE_TEMPLATE/enhancement-request.yml
• .github/ISSUE_TEMPLATE/feature-request.yml
• .github/ISSUE_TEMPLATE/question.yml
• .github/pullrequesttemplate.md
• .github/release.yml
• .github/workflows/autofix.yml
• .github/workflows/ci.yml
• .github/workflows/semantic-pull-request.yml
• .github/workflows/label-pr.yml
• renovate.json
• eslint.config.js
• .editorconfig
• .changeset/config.json
• .npmrc
• .config/automd.ts

Conditional (only when publishable npm packages exist):

• .github/workflows/release.yml with npm Trusted Publishing (OIDC)
• ci.yml publish job with pkg-pr-new

Manual follow-ups to report

• Install GitHub Apps: Renovate and pkg-pr-new (when needed).
• Configure npm Trusted Publisher in npmjs.com settings for publishable packages.
• Optionally enable npm 2FA and disallow tokens.

Reference map

• Health files and README structure → references/health-files.md
• GitHub templates and release categories → references/github-templates.md
• CI workflows and jobs → references/ci-workflows.md
• Publishing (pkg-pr-new + npm Trusted Publishing) → references/publishing.md
• Linting/formatting → references/linting-formatting.md
• Renovate, Changesets, .npmrc, automd → references/dependency-versioning.md