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

Capability	Used For	Required	Fallback
File read/write/edit	Audit and scaffold docs/templates	Yes	—
Shell access	git/gh/grep/find-based checks	Recommended	Manual file inspection
`git`	Repo metadata, tags, tracked-file checks	Recommended	Filesystem-only audit
`gh`	GitHub metadata, PR/issue/security settings	Optional	Report as unchecked/manual
`node` or `python`	Manifest/version extraction helpers	Optional	Grep/parse text manually

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.

Intent	Example prompts	Route
Full audit	`audit OSS readiness`, `/oss`	`references/checklist.md`
Scaffold missing files	`scaffold missing OSS files`, `/oss fix`	`references/checklist.md`
Generate LLM docs	`generate llms.txt`, `/oss llms`	`references/llms-generation.md`
Sync version refs	`bump stale version refs in docs`, `/oss bump`	`references/version-sync.md`
Validate CI	`check OSS CI readiness`, `/oss ci`	`references/ci-validation.md`
Review release title / notes / announcement framing	`audit release messaging`, `is this a good OSS release title?`	`references/release-messaging.md`

Template Variables

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

Placeholder	Meaning
`{REPO_NAME}`	Repository/project name
`{ORG}` / `{REPO}`	Git hosting owner + repo slug
`{DESCRIPTION}`	One-line project description
`{LICENSE_TYPE}`	Chosen OSS license
`{PRIMARY_BRANCH}`	Default branch name
`{PROJECT_REPO_URL}`	Canonical source repository URL
`{PROJECT_HOMEPAGE}`	Public project or docs homepage
`{COMMUNITY_SUPPORT_URL}`	Support/discussion channel
`{SECURITY_REPORTING_URL}`	Private vulnerability reporting channel
`{CODE_OF_CONDUCT_CONTACT}`	Contact path for conduct reports
`{MAINTAINER_NAME}`	Maintainer or org display name
`{MAINTAINER_URL}`	Maintainer/org profile or homepage
`{MAINTAINER_CONTACT_URL}`	Optional generic contact page/social/profile

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

#	Item	Severity
1	LICENSE file	BLOCKING
2	README.md exists	BLOCKING
3	README.md quality (H1, desc, install, usage, license)	BLOCKING
4	CONTRIBUTING.md	BLOCKING
5	.gitignore	BLOCKING
6	No secrets in repo	BLOCKING
7	CI: tests run	BLOCKING
8	CI: lint runs	BLOCKING
9	GitHub description set	BLOCKING
10	CHANGELOG.md with version entry	BLOCKING
11	llms.txt exists	BLOCKING
12	llms-full.txt exists	BLOCKING

WARN (11) — recommended

#	Item	Severity
13	GitHub topics/tags	WARN
14	AGENTS.md	WARN
15	Harness-specific agent-instruction aliases	WARN
16	SECURITY.md	WARN
17	CODE_OF_CONDUCT.md	WARN
18	Issue templates	WARN
19	PR template	WARN
20	CI: publish workflow (libraries)	WARN
21	docs/ folder	WARN
22	Version in docs matches package	WARN
23	No TODO/FIXME in public src/	WARN

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

Error	Response
Not a git repo	"Not a git repository. OSS audit requires a repo."
Private repo	Works but warns: "Repo is private. Audit shows readiness for going public."
No package manager	Skip version-specific checks, note in output
`gh` unavailable/auth missing	Continue filesystem checks; mark GitHub metadata as manual
Maintainer contact unknown	Keep placeholder or omit optional contact block

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.