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.
• 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.
• 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.

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.

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:

bash

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:

bash

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

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.
• 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.
• No gh CLI or not authenticated: provide exact commands for the user to run, 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.
• Suggested next steps such as enabling CI, adding examples, cutting a first release, or creating project topics.