Setup For Oss

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