From 192e2c0f2113e8343d94ebf0a651eb1d29f010c0 Mon Sep 17 00:00:00 2001
From: Wilson <scorpioaoe@gmail.com>
Date: Thu, 7 May 2026 23:15:24 +0800
Subject: [PATCH] content: add new-project repo setup checklist guide (EN+ZH)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Document the one-time repo-level setup that makes the git-workflow
rule actually work in a new project: hosting-platform settings
(auto-delete, merge strategy, branch protection), a squash-aware
local cleanup script, and the agent-instructions pointer that
makes the cleanup discoverable.

The gap surfaced during companion-project setup — the git-workflow
rule covers behavior but does not cover repo configuration, so new
projects accumulate branches until someone invents their own
cleanup. This guide closes that loop with a concrete checklist.

Layer 1 content: universal principles, with platform-specific
commands (GitHub / GitLab / Bitbucket, npm / make / just) kept
in clearly marked adaptation callouts.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 ROADMAP.md                          |  1 +
 content/guides/new-repo-setup/en.md | 85 +++++++++++++++++++++++++++++
 content/guides/new-repo-setup/zh.md | 85 +++++++++++++++++++++++++++++
 3 files changed, 171 insertions(+)
 create mode 100644 content/guides/new-repo-setup/en.md
 create mode 100644 content/guides/new-repo-setup/zh.md

diff --git a/ROADMAP.md b/ROADMAP.md
index 3e2ca49..7943504 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -42,6 +42,7 @@ Current status and next steps for Agent Master Handbook. Each item links to a Gi
 - [ ] Light/dark theme toggle (currently dark-only with prefers-color-scheme fallback)
 - [x] Git conflict prevention guide (EN+ZH) (#44)
 - [x] Proactive agent review guide (EN+ZH) (#45)
+- [x] New-project repository setup checklist (EN+ZH)
 
 ## Later
 
diff --git a/content/guides/new-repo-setup/en.md b/content/guides/new-repo-setup/en.md
new file mode 100644
index 0000000..9ffa97e
--- /dev/null
+++ b/content/guides/new-repo-setup/en.md
@@ -0,0 +1,85 @@
+---
+title: "New-Project Repository Setup Checklist"
+description: "A checklist for initializing a new repository so agents and humans share the same hygiene from day one — covering branch cleanup, merge strategy, and squash-aware scripts."
+lang: en
+pair: zh.md
+lastUpdated: 2026-05-07
+status: draft
+---
+
+# New-Project Repository Setup Checklist
+
+Git workflow rules describe how developers and agents should behave. They do not describe how the repository itself should be configured. That gap shows up early: the first few weeks of a new project accumulate stale branches, inconsistent merge histories, and cleanup scripts that everyone assumes someone else will write.
+
+This checklist covers the one-time repo-level setup that makes the git workflow actually work.
+
+## Why This Is a Separate Concern
+
+A rule says "delete local branches after PR merge." A repo without the right settings fights that rule:
+
+- Remote branches linger because the host does not auto-delete after merge.
+- Local branches look "unmerged" to plain `git branch -d` because the project squash-merges, so commit ancestry is lost.
+- Contributors each invent their own cleanup command, so cadence varies per session.
+
+Each of these is fixable in one step, but only if someone remembers to do it. The checklist makes that remembering explicit.
+
+## Hosting Platform Settings
+
+Configure these before the first PR merges:
+
+- [ ] **Auto-delete head branches after merge.** The remote should delete the branch as soon as a PR / MR is merged, so the only cleanup work is local.
+- [ ] **Pick one merge strategy and enforce it.** Squash, rebase, or merge — pick one, disable the others in the repo settings, and mention the choice in the agent instructions. Mixed strategies make history unreadable and break cleanup heuristics.
+- [ ] **Protect the default branch.** Require PRs / MRs, block force push, require CI checks where CI exists.
+- [ ] **Require linear history on squash-merge projects.** This keeps the "one commit per PR" invariant that downstream tools assume.
+
+> **Adapt to your project:** GitHub exposes these under *Settings → Branches* and *Settings → General → Pull Requests*. GitLab exposes them under *Settings → Repository → Protected branches* and *Settings → General → Merge requests*. Bitbucket, Gerrit, and self-hosted Forgejo have equivalent screens — the names differ, the settings do not.
+
+## Local Cleanup Script
+
+A squash merge rewrites the PR into a single new commit on the default branch. The original branch commits are not ancestors of that new commit, so `git branch -d <name>` sees the branch as "not merged" and refuses to delete. A squash-aware cleanup script is therefore mandatory, not optional.
+
+Add a cleanup command that:
+
+1. Prunes remote-tracking branches whose upstream is gone.
+2. Deletes local branches whose upstream is `[gone]`, regardless of whether commit ancestry agrees.
+3. Exits cleanly if there is nothing to delete.
+
+Example (Node project with npm):
+
+```json
+"scripts": {
+  "clean-branches": "git fetch -p && git for-each-ref refs/heads --format '%(refname:short) %(upstream:track)' | awk '$2 == \"[gone]\" {print $1}' | xargs git branch -D"
+}
+```
+
+The equivalent fits any project that runs shell — a `Makefile` target, a shell function, or a task in whatever runner the project uses.
+
+> **Adapt to your project:** Node → `npm run clean-branches` / `pnpm run clean-branches`. Python → a `tox`/`nox`/`just` task or `Makefile` target. Go → a `make` target. The cleanup logic is identical; only the runner changes.
+
+## Agent Instructions Pointer
+
+The cleanup command is useless if agents don't know it exists. Add a pointer in the project's agent instructions file (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`) under a pre-work checklist:
+
+- [ ] Before starting work, run the project's cleanup command.
+- [ ] Before branching, confirm the default branch is current.
+- [ ] Before opening a new PR, list open PRs / MRs and check for blocking conflicts.
+
+A rule that an agent never reads is a rule that does not exist. Pre-work checklists in the agent instructions are the mechanism that makes the rule reach the workflow.
+
+## Verification
+
+After the one-time setup, verify:
+
+- [ ] Merge a throwaway PR. Does the remote branch disappear automatically?
+- [ ] After that merge, run the cleanup command. Does the local branch disappear even though the squash merge broke ancestry?
+- [ ] Does the agent instructions file list the cleanup command with correct syntax?
+
+If any of these answer "no," the setup is not done, regardless of how many lines of rule documentation the repo has.
+
+## When to Run This Checklist
+
+- At the moment the repository is created, before the first feature branch.
+- When adopting a squash-merge policy in an existing repo that previously used merge commits.
+- When a new contributor or agent reports "my old branches aren't getting cleaned up."
+
+A recurring branch-accumulation complaint is almost always traceable to missing steps in this checklist, not to undisciplined developers.
diff --git a/content/guides/new-repo-setup/zh.md b/content/guides/new-repo-setup/zh.md
new file mode 100644
index 0000000..c05240c
--- /dev/null
+++ b/content/guides/new-repo-setup/zh.md
@@ -0,0 +1,85 @@
+---
+title: "新项目仓库初始化检查清单"
+description: "一份用于新仓库初始化的清单，让 agent 和人类从第一天起就共享同一套卫生约定——涵盖分支清理、合并策略与 squash 感知脚本。"
+lang: zh
+pair: en.md
+lastUpdated: 2026-05-07
+status: draft
+---
+
+# 新项目仓库初始化检查清单
+
+git workflow 规则描述的是人和 agent 该怎么操作，不是仓库本身该怎么配置。这个断层会在项目初期很快暴露：前几周里堆积的过期分支、参差不齐的合并历史、每个人都以为别人会写的清理脚本。
+
+这份清单覆盖的是一次性的、仓库层面的初始化，让 git workflow 真正能跑起来。
+
+## 为什么这是一个独立关注点
+
+规则说"PR 合并后删除本地分支"。没有正确设置的仓库会和规则对着干：
+
+- 远端分支在合并后仍然存在，因为 host 没有开启自动删除。
+- 项目采用 squash 合并，commit ancestry 被破坏，`git branch -d` 会认为本地分支"未合并"。
+- 每个贡献者都发明自己那一套清理命令，节奏因会话而异。
+
+这些问题每一个都能一步解决，但必须有人记得去做。清单的价值就是把"记得去做"显式化。
+
+## 托管平台设置
+
+在第一个 PR 合并之前配置：
+
+- [ ] **合并后自动删除 head 分支。** 远端应在 PR / MR 合并后立即删除分支，把清理工作压缩到只剩本地。
+- [ ] **选定一种合并策略并强制执行。** squash、rebase 或 merge，任选其一，在仓库设置里禁用其他选项，并在 agent 指令中说明选择。混合策略会让 history 无法阅读，并破坏清理脚本的启发式。
+- [ ] **保护默认分支。** 要求走 PR / MR，禁止 force push，在有 CI 的地方要求 CI 通过。
+- [ ] **在 squash-merge 项目里要求线性历史。** 这维持了"每个 PR 一个 commit"的不变式，下游工具多半依赖它。
+
+> **适配说明：** GitHub 的位置在 *Settings → Branches* 和 *Settings → General → Pull Requests*。GitLab 在 *Settings → Repository → Protected branches* 和 *Settings → General → Merge requests*。Bitbucket、Gerrit、自建 Forgejo 都有对应界面——名字不同，设置相同。
+
+## 本地清理脚本
+
+squash 合并会把整个 PR 压成一个新的 commit 并落到默认分支上，原分支上的 commit 不再是这个新 commit 的祖先，所以 `git branch -d <name>` 会把分支视为"未合并"而拒绝删除。因此 squash 感知的清理脚本不是可选项，而是必需品。
+
+加一条清理命令，做到：
+
+1. 清理上游已消失的远程追踪分支。
+2. 删除 upstream 标记为 `[gone]` 的本地分支，不管 commit ancestry 怎么说。
+3. 没有可删除分支时干净退出。
+
+示例（使用 npm 的 Node 项目）：
+
+```json
+"scripts": {
+  "clean-branches": "git fetch -p && git for-each-ref refs/heads --format '%(refname:short) %(upstream:track)' | awk '$2 == \"[gone]\" {print $1}' | xargs git branch -D"
+}
+```
+
+任何能跑 shell 的项目都能套同样的逻辑——一个 `Makefile` target、一个 shell function、或者项目里任何 task runner 的任务。
+
+> **适配说明：** Node → `npm run clean-branches` / `pnpm run clean-branches`。Python → `tox` / `nox` / `just` 任务或 `Makefile` target。Go → `make` target。清理逻辑一致，只有 runner 不同。
+
+## Agent 指令入口
+
+只要 agent 不知道命令存在，清理命令就是摆设。把入口写进项目的 agent 指令文件（`AGENTS.md`、`CLAUDE.md`、`.cursorrules`）的 pre-work checklist 里：
+
+- [ ] 开始工作前，运行项目的清理命令。
+- [ ] 开分支前，确认默认分支是最新的。
+- [ ] 提交新 PR 前，列出 open PR / MR 并检查是否存在阻塞冲突。
+
+一条 agent 从来不会读的规则等同于不存在。agent 指令里的 pre-work checklist 就是把规则真正接入工作流的机制。
+
+## 验证
+
+一次性设置完成后验证：
+
+- [ ] 合并一个临时 PR。远端分支会自动消失吗？
+- [ ] 合并之后运行清理命令。即使 squash 合并破坏了 ancestry，本地分支会被删除吗？
+- [ ] agent 指令文件里是否以正确语法列出了清理命令？
+
+任何一项回答"否"就代表设置没做完，无论仓库写了多少行规则文档。
+
+## 何时运行这份清单
+
+- 仓库创建的那一刻，在第一个 feature 分支之前。
+- 一个原本使用 merge commit 的老仓库改用 squash 合并策略时。
+- 一位新贡献者或新 agent 反馈"我的旧分支没被清理掉"时。
+
+"分支一直堆积"的反馈几乎总是能追到这份清单里漏掉的步骤，而不是贡献者不自律。