luongnv89/oss-ready

OSS Ready

Transform a project into a professional open-source repository with standard community files and GitHub templates.

Repo Sync Before Edits (mandatory)

Before creating/updating/deleting files in an existing repository, sync the current branch with remote:

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

If the working tree is not clean, stash first, sync, then restore:

git stash push -u -m "pre-sync"
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"
git stash pop

If origin is missing, pull is unavailable, or rebase/stash conflicts occur, stop and ask the user before continuing.

Workflow

Before proceeding, check Edge Cases below for a non-MIT LICENSE, a monorepo, no detectable language, a private/internal repo, or a dirty/detached HEAD — handle the matching case first if it applies.

0. Create Feature Branch

Before making any changes:

1. Check the current branch - if already on a feature branch for this task, skip
2. Check the repo for branch naming conventions (e.g., feat/, feature/, etc.)
3. Create and switch to a new branch following the repo's convention, or fallback to: feat/oss-ready

1. Analyze Project

Identify:

• Primary language(s) and tech stack
• Project purpose and functionality
• Existing documentation to preserve
• Package manager (npm, pip, cargo, etc.)

2. Create/Update Core Files

README.md - Enhance with:

• Project overview and motivation
• Key features list
• Quick start (< 5 min setup)
• Prerequisites and installation
• Usage examples with code
• Project structure
• Technology stack
• Contributing link
• License badge

CONTRIBUTING.md - Include:

• How to contribute overview
• Development setup
• Branching strategy (feature branches from main)
• Commit conventions (Conventional Commits)
• PR process and review expectations
• Coding standards
• Testing requirements

LICENSE - Default to MIT unless specified. Copy from assets/LICENSE-MIT.

CODE_OF_CONDUCT.md - Use Contributor Covenant. Copy from assets/CODE_OF_CONDUCT.md.

SECURITY.md - Vulnerability reporting process. Copy from assets/SECURITY.md.

3. Create GitHub Templates

Copy from assets/.github/:

• ISSUE_TEMPLATE/bug_report.md
• ISSUE_TEMPLATE/feature_request.md
• PULL_REQUEST_TEMPLATE.md

4. Create Documentation Structure

docs/
├── ARCHITECTURE.md    # System design, components
├── DEVELOPMENT.md     # Dev setup, debugging
├── DEPLOYMENT.md      # Production deployment
└── CHANGELOG.md       # Version history

5. Update Project Metadata

Update package file based on tech stack:

• Node.js: package.json - name, description, keywords, repository, license
• Python: pyproject.toml or setup.py
• Rust: Cargo.toml
• Go: go.mod + README badges

6. Ensure .gitignore

Verify comprehensive patterns for the tech stack.

7. Present Checklist

After completion, show:

• [x] Files created/updated
• [ ] Items needing manual review
• Recommendations for next steps

Step Completion Reports

After completing each major step, output a status report in this format:

◆ [Step Name] ([step N of M] — [context])
··································································
  [Check 1]:          √ pass
  [Check 2]:          √ pass (note if relevant)
  [Check 3]:          × fail — [reason]
  [Check 4]:          √ pass
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

Adapt the check names to match what the step actually validates. Use √ for pass, × for fail, and — to add brief context. The "Criteria" line summarizes how many acceptance criteria were met. The "Result" line gives the overall verdict.

Analysis (step 1 of 4)

◆ Analysis (step 1 of 4 — project profiling)
··································································
  Language detected:       √ pass — TypeScript (primary)
  Project type identified: √ pass — CLI tool
  Existing docs found:     √ pass — README.md (partial), no LICENSE
  [Criteria]:              √ 3/3 met
  ____________________________
  Result:                  PASS

Repeat this format for each subsequent step (Core Files, GitHub Setup, Documentation), adapting the check names to what that step actually validates.

Guidelines

• Adapt to project's actual tech stack
• Include working examples from the actual codebase

Acceptance Criteria

The skill is complete when every item below can be verified with test -f, grep, or a quick visual check. Treat this as a checklist the agent must assert before reporting success.

• [ ] LICENSE exists at repo root and contains a valid SPDX identifier (e.g., MIT, Apache-2.0). Verify: grep -E "MIT License|Apache License" LICENSE.
• [ ] README.md exists, is at least 40 lines, and includes sections for Installation, Usage, and License. Verify: grep -iE "^#+ (install|usage|license)" README.md | wc -l returns >= 3.
• [ ] CONTRIBUTING.md exists and references the issue tracker plus a branching/PR workflow. Verify: grep -iE "issue|pull request|branch" CONTRIBUTING.md.
• [ ] CODE_OF_CONDUCT.md exists and mentions the Contributor Covenant. Verify: grep -i "contributor covenant" CODE_OF_CONDUCT.md.
• [ ] SECURITY.md exists and lists at least one vulnerability-reporting contact (email or form URL). Verify: grep -E "@|https?://" SECURITY.md.
• [ ] .github/ISSUE_TEMPLATE/bug_report.md and .github/ISSUE_TEMPLATE/feature_request.md both exist with YAML frontmatter (name:, about:).
• [ ] .github/PULL_REQUEST_TEMPLATE.md exists and contains a checklist (- [ ]).
• [ ] .gitignore exists and excludes the language-appropriate build/temp artefacts (e.g., node_modules/, dist/, __pycache__/, target/).
• [ ] Project metadata file (package.json, pyproject.toml, Cargo.toml, or go.mod) declares license, description, and repository fields where the format supports them.
• [ ] No previously committed files were deleted; only additions and non-destructive enhancements were made.

Expected Output

After a successful run on a TypeScript CLI project that started with only a partial README.md, the agent emits a final report shaped like this:

◆ OSS Ready summary (4 of 4 steps complete)
··································································
  Files created:
    √ LICENSE                                  (MIT)
    √ CONTRIBUTING.md                          (33 lines)
    √ CODE_OF_CONDUCT.md                       (Contributor Covenant 2.1)
    √ SECURITY.md                              (reporting via [email protected])
    √ .github/ISSUE_TEMPLATE/bug_report.md
    √ .github/ISSUE_TEMPLATE/feature_request.md
    √ .github/PULL_REQUEST_TEMPLATE.md
    √ docs/ARCHITECTURE.md, DEVELOPMENT.md, DEPLOYMENT.md, CHANGELOG.md
  Files updated:
    √ README.md                                (+ Quick Start, Usage, License badge)
    √ package.json                             (license, repository, keywords)
    √ .gitignore                               (added dist/, .env)
  Acceptance criteria:    √ 10/10 met
  Manual review needed:
    - Confirm SECURITY.md contact email is monitored
    - Add real maintainer names to CODE_OF_CONDUCT enforcement section
  ____________________________
  Result:                 PASS

The agent must list the manual-review items explicitly so the user can finish what cannot be automated. Assert that the file tree printed by the agent matches what is actually on disk before declaring PASS.

Edge Cases

The skill should detect and handle these inputs explicitly rather than fail silently:

• Existing LICENSE with a non-MIT identifier — never overwrite. Read it, log the detected license, and skip the LICENSE step.
• Monorepo with multiple package.json files — update only the root metadata file unless the user names a sub-package.
• Repo with no detectable language (empty repo or only docs) — pause and ask the user which template stack to assume.
• Existing CODE_OF_CONDUCT.md or SECURITY.md — diff against the template; only append a missing section, never replace user content.
• Private/internal projects — confirm with the user before adding public-facing files like SECURITY.md or community templates.
• Pre-existing .github/ workflows or templates — preserve them; merge only the missing files.
• Non-English README — keep the existing language; do not translate, only add structurally missing sections in the same language.
• Detached HEAD or dirty working tree — abort with the sync warning above; never force changes onto an unstable branch.

Assets

Templates in assets/:

• LICENSE-MIT - MIT license template
• CODE_OF_CONDUCT.md - Contributor Covenant
• SECURITY.md - Security policy template
• .github/ISSUE_TEMPLATE/bug_report.md
• .github/ISSUE_TEMPLATE/feature_request.md
• .github/PULL_REQUEST_TEMPLATE.md