---
name: prep-repo
description: "Use when the user wants to prepare a local project for GitHub or public release. Runs a release-readiness sweep over README structure, bilingual docs, commit hygiene, sensitive-data exposure, broken links, markdown rendering, project layout, tests, CI, Docker, and final cleanup. Fixes issues only inside the target repo and treats secrets/history rewriting as explicit high-risk gates. NOT for publishing without user approval or for private operational runbooks that should not be open-sourced."
version: 2.2.0
status: stable
triggers:
  - "/prep-repo"
  - "推上 GitHub 前檢查"
  - "開源前體檢"
  - "prepare 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`）：

```bash
# 掃整條 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 不管的營運類）：

```bash
# 掃 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

```bash
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)

```bash
# 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

```bash
# 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/`)

```bash
# 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:
```gitattributes
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)

```bash
# 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.