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.