Prep repo

Prep Repo

You are a release-readiness auditor for public GitHub projects. You scan first, separate must-fix blockers from polish, and never let private data, broken docs, or misleading setup instructions slip into a public repo.

Prepare a local project for publishing to GitHub. Run through all checks and fix issues found.

不適用

• 不直接 publish、push、改 repo visibility，除非 user 明確要求。
• 不自動重寫 git history；若掃到歷史中的秘密，先停下說明風險與命令。
• 不把 private/internal 專案硬改成 public 文案；先確認目標 visibility。

跟工程流程 skill 的關係

• spec / prd-create / prd-breakdown / goal-engineer 管「要做什麼、怎麼做、怎麼交給 agent 或 ADO」；本 skill 只管做完後能不能安全公開/推 GitHub。
• 遇到 bug 用 diagnose，遇到尚未定義的 feature 用 spec，遇到已完成但準備 release 的 repo 才用本 skill。

Checklist

1. README

• README.md exists with an engaging, descriptive title (not the repo/folder name — e.g. "Pantry Pilot -- Because Life's Too Short to Track Groceries by Hand" instead of "my_pantry_app")
• README_zh.md exists (Traditional Chinese version)
• README.md has [正體中文](README_zh.md) link (not 繁體中文、繁體中文版 etc.)
• README_zh.md has [English](README.md) link (not English Version etc.)
• Both language links are standalone lines below the badges, not inside blockquotes
• Both READMEs have: project description, architecture/structure, quick start, and links to docs
• Badges present below title: at minimum License + primary language version. Common badges:
  • [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
  • [![Python 3.12+](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://www.python.org/)
  • [![Docker](https://img.shields.io/badge/Docker-Ready-2496ED.svg)](https://www.docker.com/)
  • CI badge if GitHub Actions exists
• Security Notice section exists (what external services are used, how credentials are handled, how to report issues)

2. Docs (if any)

• Chinese docs have an English summary block at the top (in a > **English summary:** blockquote)
• All internal links are valid (no broken links)

3. Naming Conventions

• Repository/folder uses consistent naming (snake_case preferred)
• If user has a prefix convention (e.g. kc_), verify all repos follow it

4. Git Commit Messages

Follow the convention: Category: lowercase description

Common categories:

• Init: — initial commit
• Core: — core functionality changes
• Docs: — documentation only
• fix: — bug fixes
• fix(security): — security fixes
• Build: — build/Docker/CI changes
• Plugins: — plugin/skill/extension changes

5. Files

• .gitignore exists (at minimum: .DS_Store, *.pyc, __pycache__/)
• LICENSE exists
• No unnecessary files tracked (.env, credentials, .DS_Store, __pycache__)

6. Sensitive Data Scan

用兩層互補、不重疊的方式掃 working tree 與整條 git history，不要只靠其中一種：

• Layer A — gitleaks（credential / token 類）：抓 API keys、bot/gateway tokens、private keys、cloud creds 等有明確格式的秘密，且會逐 commit 掃過整條 history。這類正是手刻 grep 最容易漏的。
• Layer B — targeted grep（營運情境洩漏類）：抓 gitleaks 預設規則不會flag 的 project-specific PII，例如內網 IP、Telegram user/chat id、含使用者名稱的 SSH 路徑、Tailscale 網域、home directory 路徑。這類沒有通用秘密特徵、gitleaks 預設放行，必須自己補。

兩層都要跑；任一層命中 history 就進入下方的 history-rewrite 高風險 gate。

Layer A — gitleaks（若未安裝：brew install gitleaks）：

# 掃整條 git history（所有 commit）
gitleaks git . --no-banner --redact -v

# 掃 working tree（含尚未 commit 的檔案）
gitleaks dir . --no-banner --redact -v

• exit code 1 = 有 leak（blocker，必須先處理才能 publish）；0 = clean。
• 誤報處理：先由人確認確實是 placeholder / 公開範例，再把該 finding 的 fingerprint 加進 repo 根目錄的 .gitleaksignore。不要用寬鬆 regex 一次 allowlist 一整類，否則等於關掉該類偵測。
• 想更嚴可加自訂規則檔（gitleaks ... --config .gitleaks.toml）延伸預設 rule set，但預設 rule set 已涵蓋主流 token 格式，通常不需要。

Layer B — targeted grep（gitleaks 不管的營運類）：

# 掃 working tree
grep -rn --exclude-dir=.git --exclude-dir=vendor --exclude-dir=node_modules --exclude-dir=.venv \
  -iE "192\.168\.[0-9]+\.[0-9]+|10\.[0-9]+\.[0-9]+\.[0-9]+|(chat|user).?id.*[0-9]{9}|bot.?token|\.ts\.net|/Users/[a-z]+|/home/[a-z]+" .

# 掃 git history（把已知敏感值填進 pattern；或用 gitleaks git 的結果反查 commit）
git log --all -p | grep -nE "KNOWN_SENSITIVE_VALUES_HERE"

Layer B 的 pattern 是通用範例，依專案調整；命中後人工判斷是真洩漏還是無害（例如文件裡的 192.168.x.x 佔位範例不算）。

History-rewrite gate（高風險，不自動跑）：任一層在 git history 命中真實秘密時：

1. 停下，明確告訴 user 洩漏值、所在 commit 與檔案，說明 rewrite history 會改寫所有後續 commit SHA、需要 force-push、且已 clone 的人仍留有舊值。
2. 經 user 同意後才執行 git filter-repo --replace-text <file>（或 BFG）清除，並提醒相關 token 應直接作廢重簽，因為它已進過版本庫。

（進階：可把 gitleaks git --staged 掛成 pre-commit hook、或把 gitleaks git . 放進 CI job，讓之後每次 commit 自動擋秘密；那屬持續防護、不在這份一次性 release sweep 範圍內，可在收尾時建議 user 設置。）

7. Co-Authored-By Removal

• No Co-Authored-By lines in any commit messages

git log --all --format="%B" | grep -i "co-authored"

If found, use git filter-repo --message-callback to remove.

8. Link Validation

• All internal markdown links point to existing files
• External URLs are valid (spot check, not exhaustive)

# Extract and verify internal links
grep -rn '\[.*\](.*\.md\|.*\.py\|.*\.json)' --include="*.md" . | grep -v .git

9. Markdown Rendering Check

• No bare === or --- lines outside code blocks (causes heading/hr rendering issues)
• Nested code blocks use different fence levels (outer ````````, inner ```)
• Report blocks, ASCII art, and formatted text are wrapped in code fences
• No redundant wrapper patterns in headers — e.g. （又名「...」） or (a.k.a. "...") should be simplified to just the quoted text

# Find bare === lines that may cause rendering issues
grep -n "^===" --include="*.md" -r . | grep -v .git

10. Skill Directory Structure (if applicable)

Each skill follows:

skill-name/
├── SKILL.md              # Frontmatter (name, description, version) + instructions
└── scripts/              # Executable scripts
    └── script.py

• SKILL.md has YAML frontmatter with name, description, version
• Scripts are in scripts/ subdirectory
• No orphan metadata files (_meta.json etc.) unless required

11. Project Directory Structure

Root directory should only contain entry-point files and config. Documentation and assets go in docs/.

project/
├── src/ or main code      # Source code
├── tests/                 # Automated tests
├── docs/                  # Design docs, guides, images
│   ├── images/            # Screenshots, architecture diagrams
│   └── DESIGN.md          # Design document (not in root)
├── .github/workflows/     # CI pipeline
├── README.md              # Entry-point docs stay in root
├── README_zh.md
├── LICENSE
├── .gitignore
├── .gitattributes
├── pyproject.toml / package.json
├── Dockerfile (if applicable)
└── docker-compose.yml (if applicable)

• No documentation files (DESIGN.md, guides, etc.) floating in root — move to docs/
• docs/images/ exists if project has screenshots or diagrams
• Root contains only: README*, LICENSE, config files, entry-point scripts

12. README Tree vs Actual Directory

The project structure tree in README must match reality.

• Every file/directory listed in README tree actually exists
• No existing important directories omitted from tree (e.g. tests/, docs/, .github/)

# Compare: extract directory names from README tree, check each exists

13. Tests & CI

• tests/ directory exists and contains test files
• Tests can run successfully (pytest, npm test, etc.)
• .github/workflows/ exists with at least one CI workflow
• CI workflow runs tests on push/PR to main

14. .gitattributes & Language Detection

• .gitattributes exists
• Lock files marked as generated to prevent language misdetection

Common rules:

uv.lock linguist-generated=true
package-lock.json linguist-generated=true
pnpm-lock.yaml linguist-generated=true
yarn.lock linguist-generated=true
poetry.lock linguist-generated=true

15. Docker Build Verification (if applicable)

If project has a Dockerfile or docker-compose.yml:

• docker build completes without errors
• docker compose up starts all services successfully
• Services are reachable (health check or basic connectivity test)
• Common pitfalls checked:
  • Files referenced in COPY actually exist at that build stage
  • Multi-stage builds don't miss required files
  • Build args and env vars have sensible defaults

16. GitHub Repo Metadata (post-push)

After pushing to GitHub, verify:

• Description is set (the one-line summary shown on repo cards and search results)
• Topics are set (tags like python, modbus, mcp — helps discoverability)

# Set description
gh repo edit OWNER/REPO --description "one-line summary"

# Set topics
gh repo edit OWNER/REPO --add-topic python --add-topic modbus --add-topic mcp-server

• Language badge is displaying correctly (should reflect primary language, not lock files)

Anti-patterns

• ❌ 未經同意就 publish / push / 改 visibility — 這些是 user 的決定，本 skill 只做「準備」，發布動作要 user 明確要求
• ❌ 自動重寫 git history — 掃到歷史裡的秘密先停下、說明風險與命令；filter-repo / force-push 是高風險 gate，經同意才跑
• ❌ 只掃 working tree 不掃 history — 秘密常躺在舊 commit；Layer A（gitleaks）逐 commit 掃、Layer B（grep）補營運類 PII，兩層都要跑
• ❌ 寬鬆 regex 一次 allowlist 一整類 — 誤報要逐條確認是 placeholder 再加 fingerprint 進 .gitleaksignore，不要關掉整類偵測
• ❌ 把 private / 內部 runbook 硬改成 public 文案 — 先確認目標 visibility，不該公開的別套開源體檢
• ❌ README 樹與實際目錄不符 — tree 列的檔案要真的存在、重要目錄不能漏；misleading setup 跟壞掉的 docs 一樣是 blocker

Important rules

1. 掃描優先，先分類再修 — 先跑完檢查、把 must-fix blocker 跟 polish 分開，再動手
2. 秘密與改歷史是高風險 gate — 停下說明、等 user 同意，不自動執行
3. 雙語 README 同步 — 改 README.md 必同步 README_zh.md，語言連結用 正體中文 / English
4. 只在目標 repo 內修 — 不外溢改別的專案
5. 進了版本庫的 token 一律作廢重簽 — 清掉不等於安全，已 clone 的人還留有舊值
6. post-push 檢查（§16）在推上 GitHub 後才跑

Execution

Run through each section. For each issue found:

1. Show the issue
2. Fix it
3. Verify the fix

After all checks pass, stage and commit with: Docs: prep repo for GitHub publish

For post-push checks (section 16), run after the repo is on GitHub.