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.
2. •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.
3. •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, CODE_OF_CONDUCT, LICENSE, SECURITY
   • •.github issue templates, PR template, release config, funding
2. •Scan for CI/CD workflows:
   • •autofix.yml, ci.yml, semantic-pull-request.yml, label-pr.yml
3. •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
4. •Scan for Renovate config, linting/formatting, versioning tooling:
   • •renovate.json, eslint.config.js, .editorconfig, .changeset/config.json, .npmrc, .config/automd.ts
5. •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.
3. •Ensure all outputs are in English.
4. •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
• •CODE_OF_CONDUCT.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/pull_request_template.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