Open Source Project Polish

Open Source Project Polish

Goal

Transform an existing project folder into a high-quality open source repository by improving public-facing documentation, community files, repository metadata, and Git/GitHub setup while preserving the original source code.

Hard Boundaries

• Do not modify original product/source code, generated logic, tests, notebooks, assets, or runtime behavior unless the user explicitly asks.
• Allowed changes are limited to project-facing metadata and documentation such as README, LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, CHANGELOG, SUPPORT, CITATION, issue/PR templates, release notes, badges, .gitignore, .gitattributes, .editorconfig, and GitHub workflow/docs scaffolding.
• Never include user-specific local machine paths in README or public docs, such as /home/<user>/..., /Users/<user>/..., drive-letter paths, personal workspace names, download folders, or machine-specific absolute project paths. Use relative paths, $HOME, <repo>, or placeholders instead.
• Default to MIT licensing when no license exists and no user preference overrides it.
• Default to automated public GitHub publication for folders without a Git remote. Determine the target owner/name if not obvious, then create a public remote and push documentation-only changes after secrets checks pass.
• When gh is authenticated, configuring low-risk GitHub repository settings is in scope and enabled by default, whether the remote was just created or already existed: set the repository description, homepage, and topics, and enable Discussions (the generated SUPPORT.md links to it, so it should exist). Do not disable existing features, change visibility, or alter branch-protection/security settings without an explicit request.
• If a network/GitHub command fails, retry once with the configured local proxy before declaring the remote step blocked.
• Preserve existing docs and community files where possible; improve them incrementally rather than replacing useful content.

Inputs to Clarify When Missing

Ask only for information that materially affects irreversible or public-facing actions:

1. Target scope: workspace project path, or current folder if already clear.
2. Public identity: GitHub owner/repo name before creating any remote if it cannot be inferred from the folder and authenticated GitHub account.
3. License override: use an existing license if present; otherwise apply MIT by default unless the user requests another license.
4. Project positioning: one-sentence value proposition, target users, and maturity if not inferable from code/docs.
5. Source-code edits: assume forbidden; ask before touching anything beyond metadata/docs.

Procedure

1. Audit Project State

• Inspect the folder structure, existing README/docs, package manifests, build files, examples, license files, and Git state.
• Check whether .git exists and whether any remote is configured.
• Identify secrets-risk files before any remote creation or push: .env, credentials, tokens, large binaries, datasets, private notes, local logs, and machine-specific paths.
• Summarize existing strengths, missing open-source essentials, and any uncertainty that needs user input.

2. Plan Non-Code Additions

Create a concise plan covering only allowed documentation and metadata work:

• README improvements using the create-readme skill as the basis for structure, tone, and GitHub-flavored Markdown.
• Bilingual README by default: after the primary (English) README is finalized, produce a Chinese version saved as README.zh-CN.md and cross-link the two. Author the mirror directly; reserve the baoyu-translate skill for long or terminology-dense docs where global term consistency matters.
• Community health files: MIT license by default, contributing guide, code of conduct, security policy, support guide, changelog, citation, governance, issue templates, PR template.
• Repository hygiene: .gitignore, .gitattributes, .editorconfig, docs index, examples index, badges, project description, topics, funding/sponsor metadata if relevant.
• Git/GitHub setup: initialize Git if absent, create public remote if absent, set default branch, and push documentation-only changes after safety checks. When gh is available, set the repository description/homepage/topics and enable Discussions by default.

3. Improve README

Use the create-readme skill for README creation or refresh. Ensure the README is concise, attractive, and useful:

• Clear project name, tagline, and short value proposition.
• Badges only when truthful and maintainable.
• Quick start with verified commands when possible.
• Commands must be copy-pastable from the repository root and must not contain the current user's absolute local paths; prefer ./script.sh, $HOME/..., /path/to/..., or <repo>/... examples.
• Installation, usage, configuration, examples, project structure, troubleshooting, and links to dedicated files.
• Do not duplicate full LICENSE, CONTRIBUTING, CHANGELOG, or SECURITY content inside README; link to those files.
• Preserve existing project-specific knowledge and examples.

After the English README.md is finalized, produce a Chinese translation by default:

• The English README.md must include a language-switch line near the top by default, e.g. English | [简体中文](README.zh-CN.md). Add it even when the Chinese file is still being generated in the same run — the link points to the path that will exist when the workflow completes.
• Produce the Chinese README.zh-CN.md from README.md. Authoring the mirror directly is preferred for a typical README (mostly short prose plus code/commands that must stay verbatim); invoke the baoyu-translate skill only when the README is long or terminology-dense and benefits from its analyze/translate/review flow and a shared glossary.
• The Chinese README.zh-CN.md carries the mirror switch line at the top, e.g. [English](README.md) | 简体中文.
• Keep all code blocks, commands, paths, links, badges, and placeholders unchanged; translate only prose.
• Skip the Chinese version only if the user explicitly opts out. If the project is already authored primarily in Chinese, treat README.md as the Chinese version, translate into README.en.md, and put the corresponding switch line at the top of each file.

4. Add Community Files

Add or update files only when they help the project appear complete and trustworthy:

• LICENSE: use existing license if present; otherwise add MIT by default with the detected current year and owner/project name where appropriate.
• CONTRIBUTING.md: development setup, branch/commit conventions if inferable, test expectations, issue/PR process.
• CODE_OF_CONDUCT.md: use a standard concise contributor covenant style unless user has another policy.
• SECURITY.md: supported versions, responsible disclosure channel placeholder, vulnerability reporting expectations.
• CHANGELOG.md: initialize with Unreleased and current public baseline; do not invent release history.
• SUPPORT.md: where to ask questions, report bugs, and request features.
• .github/ISSUE_TEMPLATE/* and .github/PULL_REQUEST_TEMPLATE.md: practical forms/checklists tailored to the project.
• CITATION.cff only for research/academic/scientific projects or when authorship metadata is available.

5. Repository Hygiene

• Create or refine .gitignore based on detected languages/tools without excluding files that are likely source artifacts.
• Add .gitattributes for text normalization and common binary patterns when useful.
• Add .editorconfig with conservative whitespace defaults matching the repo style.
• Do not add CI workflows unless build/test commands are known or verified; if added, keep them minimal and non-invasive.

6. Git and Remote Handling

For folders without Git:

1. Initialize a repository for the target folder after verifying the folder path.
2. Stage only metadata/docs files created or changed by this workflow.
3. Commit with a documentation-focused message when publication is proceeding.

For Git repositories without a remote:

1. Infer the GitHub owner from gh authentication and the repo name from the folder when possible; ask only if ambiguous.
2. Check for gh authentication before creating a remote.
3. Create a public GitHub repository by default.
4. Add origin, set the default branch, and push after reviewing staged changes and confirming no secrets are included.

Recommended GitHub CLI flow, adapted to the project:

git status --short
git remote -v
gh auth status
gh repo create OWNER/REPO --public --source=. --remote=origin --push

If network commands fail, retry once with:

export {HTTP_PROXY,HTTPS_PROXY,ALL_PROXY,http_proxy,https_proxy,all_proxy}=http://127.0.0.1:7890

6a. Configure Repository Features (when gh is available)

Whether the remote was just created or already existed, when gh is authenticated, configure standard repository metadata and features by default. These changes are low-risk and reversible:

• Set the description, homepage, and relevant topics for discoverability:

  gh repo edit OWNER/REPO \
    --description "One-line value proposition." \
    --homepage "https://example.org/or/pypi/url" \
    --add-topic TOPIC1 --add-topic TOPIC2
  

• Enable Discussions by default, because the generated SUPPORT.md points contributors there and the link should resolve. There is no dedicated gh subcommand, so use the API endpoint:

  gh api --method PATCH repos/OWNER/REPO -F has_discussions=true --jq '.has_discussions'
  

Skip a feature only when it is already enabled/set or the user opts out; verify with gh repo view OWNER/REPO --json description,repositoryTopics,hasDiscussionsEnabled. If gh is unavailable or unauthenticated, list these as manual steps in the completion summary instead of performing them.

7. Quality Checks

Before finalizing:

• Re-open changed Markdown snippets to verify headings, links, code fences, and copy-pastable command indentation.
• Search README and public docs for local machine paths before finalizing, including /home/, /Users/, drive-letter paths, personal workspace names, and absolute paths copied from the current environment.
• Confirm no source code files were modified unless explicitly approved.
• Confirm all links to local files target files that exist.
• If a Chinese README was produced, confirm README.zh-CN.md exists, the language-switch links resolve in both files, and code/commands/paths remain identical to the English version.
• Run lightweight formatting or markdown linting if available; do not install heavy dependencies just for this workflow unless user agrees.
• Show git diff --stat and summarize changed files.
• If a remote was created, report the URL, visibility, default branch, and whether anything was pushed.

Decision Points

• Existing README is strong: preserve structure and patch missing sections rather than rewrite.
• No verified install/test commands: include clearly marked placeholders or "not yet documented" notes instead of inventing commands.
• License unknown: add MIT by default unless the user requests a different license.
• Possible secrets or private data: stop remote creation/push and report the risky paths.
• gh available and authenticated: set description/homepage/topics and enable Discussions by default as part of setup, since generated docs (e.g. SUPPORT.md) reference Discussions; verify each is not already set before changing it.
• No gh CLI or not authenticated: provide exact commands for the user to run (including the repository-feature commands from step 6a), but still complete local docs polish and prepare a documentation-only commit if safe.
• Monorepo: create or update root community files and per-package README files only when package boundaries are clear.

Completion Summary

End with:

• Files added/updated.
• What was intentionally not touched, especially source code.
• Validation performed.
• Remote repository status, if applicable.
• Repository features configured via gh (description, homepage, topics, Discussions), or the exact commands to run when gh is unavailable.
• Suggested next steps such as enabling CI, adding examples, or cutting a first release.