scaffold-repository

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

scaffold-repository

scaffold-repository

scaffolds a repository – new or existing – to the Patina Project baseline. The baseline mirrors

patinaproject/superteam

: a dual-plugin repository root, a self-contained

skills/

directory, conventional-commits-with-issue-ref enforcement, a PR template,

AGENTS.md

CLAUDE.md

, a human-readable

README.md

, a

docs/file-structure.md

contributor reference, and PNPM + Husky + markdownlint tooling.

scaffold-repository

是一款仓库脚手架工具，可将新仓库或现有仓库搭建为Patina Project基线。该基线与

patinaproject/superteam

保持一致：包含双插件仓库根目录、独立的

skills/

目录、带问题引用的约定式提交校验、PR模板、

AGENTS.md

CLAUDE.md

、易读的

README.md

、

docs/file-structure.md

贡献者参考文档，以及PNPM + Husky + markdownlint工具链。

Modes

模式

The skill detects which mode to run based on target-repo state.

该工具会根据目标仓库的状态自动检测运行模式。

New-repo mode

新仓库模式

Preconditions:

Target is a git repository (may be empty or just initialized).
No prior
```
.claude-plugin/
```
or
```
.codex-plugin/
```
manifests.

Behavior:

Emit the full core baseline tree.
If the user answers yes to "Is this an AI agent plugin?", additionally emit the agent-plugin surfaces.
If the user answers yes to "Use the superteam workflow?" (the Superpowers-based design + plan flow), additionally emit the
```
docs/superpowers/specs/.gitkeep
```
+
```
docs/superpowers/plans/.gitkeep
```
scaffolding, generated docs that explain
```
pnpm skills:install
```
, and the
```
skills:install
```
package script that installs both
```
patinaproject/skills
```
and
```
obra/superpowers
```
through
```
npx skills
```
.
Run
```
pnpm install
```
to generate
```
pnpm-lock.yaml
```
and wire Husky.
Leave all emitted files staged but uncommitted so the user owns the first commit.

前置条件：

目标为Git仓库（可为空或刚初始化）。
无已存在的
```
.claude-plugin/
```
或
```
.codex-plugin/
```
清单文件。

行为：

生成完整的核心基线目录结构。
如果用户回答“这是AI Agent插件吗？”为“是”，则额外生成Agent插件界面。
如果用户回答“使用superteam工作流？”（基于Superpowers的设计+规划流程）为“是”，则额外生成
```
docs/superpowers/specs/.gitkeep
```
+
```
docs/superpowers/plans/.gitkeep
```
脚手架、说明
```
pnpm skills:install
```
的生成文档，以及通过
```
npx skills
```
安装
```
patinaproject/skills
```
和
```
obra/superpowers
```
的
```
skills:install
```
包脚本。
运行
```
pnpm install
```
生成
```
pnpm-lock.yaml
```
并配置Husky。
将所有生成的文件暂存但不提交，由用户完成首次提交。

Realignment mode

基线调整模式

Preconditions:

Target is a git repository with existing content (one or more baseline files present).

Behavior:

Walk
```
audit-checklist.md
```
against the target repo.
Classify each baseline item as
```
missing
```
,
```
stale
```
, or
```
divergent
```
.
For each gap, produce a concrete recommendation on how to realign with the current baseline.
Detect whether the repo is an AI agent plugin (by presence of any agent-plugin manifest). When detected, additionally recommend any currently-supported AI platform surface that is missing.
For each recommendation, show a diff preview and ask the user to accept, skip, or defer. Never overwrite existing files without explicit confirmation. There are no flags or escape hatches; realignment is always interactive.

Group recommendations into ordered batches that can be applied independently. Each batch below must cover its listed files; no file from the "Source of truth for repo baseline" list in

AGENTS.md

may be skipped.

patinaproject/bootstrap

is a normal realignment target – the skill must not self-exclude when run against it.

Plugin manifests:

.claude-plugin/

.codex-plugin/

release-please-config.json

.release-please-manifest.json

Commit / PR conventions:

commitlint.config.js

.husky/*

.github/pull_request_template.md

.github/ISSUE_TEMPLATE/*

PNPM tooling:

package.json

.markdownlint.jsonc

scripts/check-plugin-versions.mjs

scripts/sync-plugin-versions.mjs

Agent + repo docs:

AGENTS.md

CLAUDE.md

CONTRIBUTING.md

README.md

RELEASING.md

AI platform surfaces:

.cursor/

.windsurfrules

.github/copilot-instructions.md

Workflows:

.github/workflows/*

(including

release.yml

with job-level

permissions:

Superpowers scaffolding (only when

<use-superteam>

is yes):

docs/superpowers/specs/

docs/superpowers/plans/

前置条件：

目标为包含现有内容的Git仓库（已存在一个或多个基线文件）。

行为：

对照目标仓库检查
```
audit-checklist.md
```
。
将每个基线项归类为
```
缺失
```
、
```
过时
```
或
```
偏离
```
。
针对每个差距，提供与当前基线对齐的具体建议。
检测仓库是否为AI Agent插件（通过是否存在任何Agent插件清单）。如果检测到，额外建议添加所有当前支持的缺失AI平台界面。
针对每个建议，显示差异预览并询问用户是否接受、跳过或推迟。未经明确确认，绝不覆盖现有文件。无任何标志或快捷方式；调整过程始终为交互式。

将建议分组为可独立应用的有序批次。每个批次必须涵盖其列出的文件；

AGENTS.md

中“仓库基线的真相来源”列表中的任何文件均不得跳过。

patinaproject/bootstrap

是正常的调整目标——工具运行时不得自动排除自身。

插件清单：

.claude-plugin/

、

.codex-plugin/

、

release-please-config.json

、

.release-please-manifest.json

。

提交/PR规范：

commitlint.config.js

、

.husky/*

、

.github/pull_request_template.md

、

.github/ISSUE_TEMPLATE/*

。

PNPM工具链：

package.json

、

.markdownlint.jsonc

、

scripts/check-plugin-versions.mjs

、

scripts/sync-plugin-versions.mjs

。

Agent + 仓库文档：

AGENTS.md

、

CLAUDE.md

、

CONTRIBUTING.md

、

README.md

、

RELEASING.md

。

AI平台界面：

.cursor/

、

.windsurfrules

、

.github/copilot-instructions.md

。

工作流：

.github/workflows/*

（包含带作业级

permissions:

的

release.yml

）。

Superpowers脚手架（仅当

<use-superteam>

为“是”时）：

docs/superpowers/specs/

、

docs/superpowers/plans/

。

Prompts

提示信息

The skill collects the following inputs. Author name, author email, and the security contact are derived from

git config user.name

and

git config user.email

; halt with a blocker if those are unset. Author handle is resolved with

gh api user --jq .login

; when unavailable, prompt

Author GitHub handle (for author URL)?

with no default.

Prompt	Default	Notes
`<owner>`	from `git remote get-url origin`	GitHub org or user
`<repo>`	from `git remote get-url origin`	repository name
`<repo-description>`	–	one-line description
`<visibility>`	public	public \| private
`<is-agent-plugin>`	no	yes emits plugin/config surfaces for every supported AI coding tool
`<use-superteam>`	no	yes emits `docs/superpowers/` skeleton plus the portable Superteam skills install path
`<primary-skill-name>`	–	required when `<is-agent-plugin>` is yes; scaffolds `skills/<name>/SKILL.md` starter
`<codeowner>`	`@<owner>`	written into `.github/CODEOWNERS`
`<security-contact>`	from `git config user.email`	public repos only; written into `SECURITY.md`
`<author-name>`	from `git config user.name`	written into every `author` block
`<author-email>`	from `git config user.email`	written into every `author` block
`<author-handle>`	from `gh api user --jq .login`	prompted if unavailable; written into `author.url`
Continue.dev	no	opt-in secondary editor surface during agent-plugin mode

该工具会收集以下输入信息。作者姓名、作者邮箱和安全联系人信息从

git config user.name

和

git config user.email

获取；如果这些配置未设置则终止操作。作者账号通过

gh api user --jq .login

获取；如果无法获取，则提示“Author GitHub handle (for author URL)?”，无默认值。

提示项	默认值	说明
`<owner>`	来自 `git remote get-url origin`	GitHub组织或用户
`<repo>`	来自 `git remote get-url origin`	仓库名称
`<repo-description>`	–	单行描述
`<visibility>`	public	public \| private
`<is-agent-plugin>`	no	为“是”时生成所有支持的AI编码工具的插件/配置界面
`<use-superteam>`	no	为“是”时生成 `docs/superpowers/` 骨架以及可移植的Superteam工具安装路径
`<primary-skill-name>`	–	当 `<is-agent-plugin>` 为“是”时必填；生成 `skills/<name>/SKILL.md` 起始文件
`<codeowner>`	`@<owner>`	写入 `.github/CODEOWNERS`
`<security-contact>`	来自 `git config user.email`	仅公开仓库；写入 `SECURITY.md`
`<author-name>`	来自 `git config user.name`	写入每个 `author` 块
`<author-email>`	来自 `git config user.email`	写入每个 `author` 块
`<author-handle>`	来自 `gh api user --jq .login`	无法获取时提示；写入 `author.url`
Continue.dev	no	Agent插件模式下可选的二级编辑器界面

Core baseline

核心基线

Emitted for every target repo:

text

.claude/settings.json
.editorconfig
.github/CODEOWNERS
.github/ISSUE_TEMPLATE/bug_report.md
.github/ISSUE_TEMPLATE/feature_request.md
.github/actionlint.yaml
.github/pull_request_template.md
.github/workflows/actions.yml
.github/workflows/markdown.yml
.github/workflows/pull-request.yml
.gitattributes
.gitignore
.husky/commit-msg
.husky/pre-commit
.markdownlint.jsonc
.markdownlintignore
.nvmrc
AGENTS.md
CHANGELOG.md
CLAUDE.md
CONTRIBUTING.md
README.md                   (core variant; replaced by agent-plugin variant when <is-agent-plugin>=yes)
RELEASING.md
SECURITY.md                 (public repos only)
commitlint.config.js
docs/file-structure.md
package.json
scripts/check-plugin-versions.mjs
scripts/sync-plugin-versions.mjs

为所有目标仓库生成以下内容：

text

.claude/settings.json
.editorconfig
.github/CODEOWNERS
.github/ISSUE_TEMPLATE/bug_report.md
.github/ISSUE_TEMPLATE/feature_request.md
.github/actionlint.yaml
.github/pull_request_template.md
.github/workflows/actions.yml
.github/workflows/markdown.yml
.github/workflows/pull-request.yml
.gitattributes
.gitignore
.husky/commit-msg
.husky/pre-commit
.markdownlint.jsonc
.markdownlintignore
.nvmrc
AGENTS.md
CHANGELOG.md
CLAUDE.md
CONTRIBUTING.md
README.md                   (核心变体；当<is-agent-plugin>=yes时替换为Agent插件变体)
RELEASING.md
SECURITY.md                 (仅公开仓库)
commitlint.config.js
docs/file-structure.md
package.json
scripts/check-plugin-versions.mjs
scripts/sync-plugin-versions.mjs

Agent plugin surfaces

Agent插件界面

Emitted only when

<is-agent-plugin>

is yes:

text

.claude-plugin/plugin.json          (Claude Code)
.codex-plugin/plugin.json           (Codex)
.github/copilot-instructions.md     (GitHub Copilot)
.github/workflows/release.yml       (release-please)
.cursor/rules/{{repo}}.mdc          (Cursor)
.windsurfrules                      (Windsurf)
README.md                           (replaces core README with installation instructions)
release-please-config.json
.release-please-manifest.json
skills/{{primary-skill-name}}/SKILL.md
skills/.gitkeep

The agent-plugin

README.md.tmpl

is richer than the core one: it includes install steps for Claude Code, Codex CLI, and Codex App, plus usage examples. The core

README.md.tmpl

is emitted only for non-plugin repos.

Because the agent-plugin README documents a primary skill invocation and links to that skill contract, agent-plugin mode must collect

<primary-skill-name>

before rendering the README and primary skill starter.

Aider, Zed, Cline, and Opencode read

AGENTS.md

natively and are covered by the core baseline – no dedicated surface needed. Codex CLI also reads

AGENTS.md

natively but additionally consumes

.codex-plugin/plugin.json

in agent-plugin mode. Continue.dev is available as an opt-in secondary editor (

.continue/config.json

仅当

<is-agent-plugin>

为“是”时生成以下内容：

text

.claude-plugin/plugin.json          (Claude Code)
.codex-plugin/plugin.json           (Codex)
.github/copilot-instructions.md     (GitHub Copilot)
.github/workflows/release.yml       (release-please)
.cursor/rules/{{repo}}.mdc          (Cursor)
.windsurfrules                      (Windsurf)
README.md                           (替换核心README为安装说明)
release-please-config.json
.release-please-manifest.json
skills/{{primary-skill-name}}/SKILL.md
skills/.gitkeep

Agent插件版的

README.md.tmpl

比核心版更丰富：包含Claude Code、Codex CLI和Codex App的安装步骤，以及使用示例。核心版

README.md.tmpl

仅为非插件仓库生成。

由于Agent插件版README记录了主要工具调用方式并链接到该工具契约，因此Agent插件模式必须在渲染README和主要工具起始文件之前收集

<primary-skill-name>

。

Aider、Zed、Cline和Opencode原生支持读取

AGENTS.md

，已被核心基线覆盖——无需专用界面。Codex CLI也原生支持读取

AGENTS.md

，但在Agent插件模式下还会使用

.codex-plugin/plugin.json

。Continue.dev作为可选的二级编辑器（

.continue/config.json

）可用。

Patina Project organization supplement

Patina Project组织补充内容

When the target repo's owner is

patinaproject

, the skill replaces the agent-plugin

.github/workflows/release.yml

with the supplement at

skills/scaffold-repository/templates/patinaproject-supplement/.github/workflows/release.yml

. The supplement currently emits only the

release-please

job; non-Patina repos get the clean base workflow.

Historical note: an earlier revision of the supplement also added a

notify-patinaproject-skills

job that dispatched

plugin-release-bump.yml

patinaproject/skills

after each release. That cross-repo bump path is obsolete —

patinaproject/skills

now vendors plugins directly via subtree merge and bumps its marketplace surface through release-please, so the dispatch was removed and Patina-org plugin repos no longer need cross-repo automation.

Detection is done at scaffold time from

git remote get-url origin

(or the configured

<owner>

prompt). When generating the base workflow for non-Patina-Project repos, do not add

if: github.repository_owner == 'patinaproject'

gates; emit the clean workflow without any Patina-Project-specific plumbing.

当目标仓库的所有者为

patinaproject

时，该工具会将Agent插件版的

.github/workflows/release.yml

替换为

skills/scaffold-repository/templates/patinaproject-supplement/.github/workflows/release.yml

中的补充内容。目前该补充内容仅生成

release-please

作业；非Patina仓库使用简洁的基础工作流。

历史说明：早期版本的补充内容还添加了

notify-patinaproject-skills

作业，该作业在每次发布后会触发

patinaproject/skills

上的

plugin-release-bump.yml

。这种跨仓库更新路径现已过时——

patinaproject/skills

现在通过子树合并直接引入插件，并通过release-please更新其市场界面，因此已移除该触发操作，Patina组织的插件仓库不再需要跨仓库自动化。

检测在脚手架生成时通过

git remote get-url origin

（或配置的

<owner>

提示）完成。为非Patina Project仓库生成基础工作流时，请勿添加

if: github.repository_owner == 'patinaproject'

条件；生成简洁的工作流，不含任何Patina Project特定的配置。

Plugin enablement and skill installation

插件启用与工具安装

The emitted

.claude/settings.json

enables the canonical Patina Project plugins at the project level:

jsonc

{
  "enabledPlugins": {
    "superteam@patinaproject-skills": true,
    "superpowers@claude-plugins-official": true
  }
}

This declarative host enablement remains available for Claude Code hosts that understand project

enabledPlugins

. It is not the portable setup path by itself. Scaffolded repos also emit

pnpm skills:install

, which runs

npm_config_ignore_scripts=true npx skills@1.5.6 add patinaproject/skills -y

and

npm_config_ignore_scripts=true npx skills@1.5.6 add obra/superpowers -y

so contributors can install the required Patina Project and Superpowers skills across runtimes.

生成的

.claude/settings.json

会在项目级别启用Patina Project的标准插件：

jsonc

{
  "enabledPlugins": {
    "superteam@patinaproject-skills": true,
    "superpowers@claude-plugins-official": true
  }
}

这种声明式宿主启用方式适用于支持项目

enabledPlugins

的Claude Code宿主。但这本身不是可移植的设置路径。脚手架生成的仓库还会生成

pnpm skills:install

，该脚本运行

npm_config_ignore_scripts=true npx skills@1.5.6 add patinaproject/skills -y

和

npm_config_ignore_scripts=true npx skills@1.5.6 add obra/superpowers -y

，以便贡献者可在不同运行环境中安装所需的Patina Project和Superpowers工具。

Conventions encoded

编码规范

Commits: Conventional Commits with no scope, required
```
#<issue>
```
tag, 72-char max. Enforced by commitlint + husky
```
commit-msg
```
.
PR titles: same format, so squash commits reuse them verbatim.
PR body: required closing keywords for normal PRs, additional linked-issue relationships (
```
Related to
```
,
```
Blocks
```
,
```
Partially satisfies
```
), a
```
Test coverage
```
AC/evidence table, optional
```
Testing steps
```
for operator-owned pass/fail verification, and optional
```
Risks
```
for warnings, gaps, caveats, or blockers.
Issue titles: plain-language, no commit-style prefix.

Markdown:

markdownlint-cli2

with

.markdownlint.jsonc

.markdownlintignore

lint-staged

runs it from

pre-commit

. The lint script uses a glob that excludes

node_modules/

PNPM:

"packageManager": "pnpm@10.33.2"

pin,

engines.node >=24

prepare: "husky"

lint:md

script, and

skills:install

script for the portable Superteam skills install path.

Line endings:
```
.gitattributes
```
with
```
* text=auto eol=lf
```
.
PR title hygiene:
```
.github/workflows/pull-request.yml
```
validates that every PR title is ASCII-only, follows conventional commits (no scopes), starts with a
```
#<issue>
```
ref, keeps breaking-change markers consistent (
```
!
```
in title ⇔
```
BREAKING CHANGE:
```
footer), and that the body contains a GitHub closing keyword.
Markdown CI:
```
.github/workflows/markdown.yml
```
runs
```
DavidAnson/markdownlint-cli2-action
```
on every PR as a backstop to the husky
```
pre-commit
```
hook (which can be bypassed with
```
--no-verify
```
).
Workflow linting:
```
.github/workflows/actions.yml
```
runs
```
actionlint
```
on PRs that touch
```
.github/workflows/**
```
or
```
.github/actionlint.yaml
```
. Catches malformed refs, invalid expressions, permission mistakes, and (alongside our SHA-pin convention) supply-chain drift.
GitHub Actions pinning: every
```
uses:
```
in emitted workflows references a full 40-char commit SHA with a
```
# <action>@<version>
```
comment above it, rather than a mutable tag. Documented in
```
AGENTS.md
```
.
Labels:
```
AGENTS.md
```
directs contributors to use
```
gh label list
```
and the repository's label descriptions as the source of truth when labeling issues and PRs.
Author identity:
```
package.json
```
,
```
.claude-plugin/plugin.json
```
, and
```
.codex-plugin/plugin.json
```
use the same human author record: name and email from
```
git config
```
, plus
```
https://github.com/<author-handle>
```
from
```
gh api user --jq .login
```
or the required author-handle prompt. Repository-level URLs (
```
homepage
```
,
```
repository
```
, and Codex interface URLs) continue to use
```
<owner>/<repo>
```
.
Releases (agent-plugin mode):
```
release-please
```
reads conventional commits since the last tag, opens a standing release PR that bumps
```
package.json
```
+ both plugin manifests +
```
CHANGELOG.md
```
, and publishes a GitHub Release on merge. Semver level is derived from commit types; there is no manual patch/minor/major choice.
Distribution via
patinaproject/skills
: Patina-Project plugins are vendored directly into
```
patinaproject/skills
```
via
```
git subtree
```
and ship through that repo's release-please flow. There is no cross-repo dispatch from individual plugin repos to the marketplace; the marketplace is updated as part of the consolidation/release flow in
```
patinaproject/skills
```
itself. The emitted Patina supplement therefore no longer carries the old
```
notify-patinaproject-skills
```
dispatch job — only the standard
```
release-please
```
job.

Version canonicalization:

package.json

is the single source of truth for the plugin version.

scripts/sync-plugin-versions.mjs

rewrites

.claude-plugin/plugin.json

and

.codex-plugin/plugin.json

to match;

scripts/check-plugin-versions.mjs

enforces the lockstep via husky

pre-commit

提交：约定式提交，无作用域，必填
```
#<issue>
```
标签，最大72字符。通过commitlint + husky
```
commit-msg
```
校验。
PR标题：格式相同，以便 squash 提交直接复用。
PR正文：普通PR必填关闭关键词，额外的关联问题关系（
```
Related to
```
、
```
Blocks
```
、
```
Partially satisfies
```
），
```
Test coverage
```
验收标准/证据表，可选的
```
Testing steps
```
供运维人员进行通过/失败验证，以及可选的
```
Risks
```
用于说明警告、差距、注意事项或阻塞点。
问题标题：通俗易懂，无提交风格前缀。
Markdown：使用
```
markdownlint-cli2
```
配合
```
.markdownlint.jsonc
```
+
```
.markdownlintignore
```
。
```
lint-staged
```
从
```
pre-commit
```
钩子运行该工具。lint脚本使用排除
```
node_modules/
```
的glob模式。
PNPM：固定
```
"packageManager": "pnpm@10.33.2"
```
，
```
engines.node >=24
```
，
```
prepare: "husky"
```
，
```
lint:md
```
脚本，以及用于可移植Superteam工具安装路径的
```
skills:install
```
脚本。
行尾：
```
.gitattributes
```
设置
```
* text=auto eol=lf
```
。
PR标题规范：
```
.github/workflows/pull-request.yml
```
验证每个PR标题仅包含ASCII字符、遵循约定式提交（无作用域）、以
```
#<issue>
```
引用开头、保持破坏性变更标记一致（标题中的
```
!
```
⇔ 脚注中的
```
BREAKING CHANGE:
```
），且正文包含GitHub关闭关键词。
Markdown CI：
```
.github/workflows/markdown.yml
```
在每个PR上运行
```
DavidAnson/markdownlint-cli2-action
```
，作为husky
```
pre-commit
```
钩子（可通过
```
--no-verify
```
绕过）的后备检查。
工作流校验：
```
.github/workflows/actions.yml
```
在修改
```
.github/workflows/**
```
或
```
.github/actionlint.yaml
```
的PR上运行
```
actionlint
```
。捕获格式错误的引用、无效表达式、权限错误，以及（配合我们的SHA固定规范）供应链漂移问题。
GitHub Actions固定：生成的工作流中每个
```
uses:
```
都引用完整的40字符提交SHA，并在上方添加
```
# <action>@<version>
```
注释，而非可变标签。该规范记录在
```
AGENTS.md
```
中。
标签：
```
AGENTS.md
```
指导贡献者使用
```
gh label list
```
和仓库的标签描述作为标记问题和PR的真相来源。
作者身份：
```
package.json
```
、
```
.claude-plugin/plugin.json
```
和
```
.codex-plugin/plugin.json
```
使用相同的人工作者记录：来自
```
git config
```
的姓名和邮箱，以及来自
```
gh api user --jq .login
```
或必填作者账号提示的
```
https://github.com/<author-handle>
```
。仓库级URL（
```
homepage
```
、
```
repository
```
和Codex界面URL）仍使用
```
<owner>/<repo>
```
。
发布（Agent插件模式）：
```
release-please
```
读取自上次标签以来的约定式提交，打开一个持续的发布PR，更新
```
package.json
```
+ 两个插件清单 +
```
CHANGELOG.md
```
，并在合并后发布GitHub Release。语义化版本级别由提交类型决定；无需手动选择补丁/次要/主要版本。
通过
patinaproject/skills
分发：Patina Project插件通过
```
git subtree
```
直接引入
```
patinaproject/skills
```
，并通过该仓库的release-please流程发布。单个插件仓库无需向市场触发跨仓库操作；市场更新作为
```
patinaproject/skills
```
自身合并/发布流程的一部分完成。因此生成的Patina补充内容不再包含旧的
```
notify-patinaproject-skills
```
触发作业——仅保留标准的
```
release-please
```
作业。

版本规范化：

package.json

是插件版本的唯一真相来源。

scripts/sync-plugin-versions.mjs

会将

.claude-plugin/plugin.json

和

.codex-plugin/plugin.json

重写为匹配版本；

scripts/check-plugin-versions.mjs

通过husky

pre-commit

钩子强制版本同步。

GitHub repository settings

GitHub仓库设置

Every bootstrap-managed repo should carry these merge settings:

Setting	Value	Reason
`allow_squash_merge`	true	Release flow assumes squash; lint-pr enforces a PR title ready to become the squash commit.
`allow_merge_commit`	false	Merge commits break linear history and release-please commit parsing.
`allow_rebase_merge`	false	Rebase-merge drops the PR-title context that release-please reads.
`squash_merge_commit_title`	`PR_TITLE`	Carries the lint-pr-validated title straight through to `main` .
`squash_merge_commit_message`	`COMMIT_MESSAGES`	Preserves commit-level context (useful for review and git blame) in the squash body.
`delete_branch_on_merge`	true	Keeps the branch list tidy after each squash.
`allow_update_branch`	true	Surfaces an "Update branch" button on stale PRs so reviewers can sync without leaving the UI.
Release immutability	enabled	Prevents published release assets and tags from being modified after the fact – critical for marketplace consumers pinning to a tag. UI-only: not exposed via the standard REST `repos` endpoint.

所有由脚手架管理的仓库应配置以下合并设置：

设置项	值	原因
`allow_squash_merge`	true	发布流程依赖squash提交；lint-pr校验确保PR标题可直接作为squash提交标题。
`allow_merge_commit`	false	合并提交会破坏线性历史并干扰release-please的提交解析。
`allow_rebase_merge`	false	变基合并会丢失release-please读取的PR标题上下文。
`squash_merge_commit_title`	`PR_TITLE`	将经过lint-pr校验的标题直接传递到 `main` 分支。
`squash_merge_commit_message`	`COMMIT_MESSAGES`	在squash提交正文中保留提交级上下文（对代码审查和git blame有用）。
`delete_branch_on_merge`	true	每次squash提交后保持分支列表整洁。
`allow_update_branch`	true	在过时的PR上显示“Update branch”按钮，以便审查者无需离开UI即可同步分支。
发布不可变性	启用	防止已发布的发布资产和标签在事后被修改——这对依赖标签的市场消费者至关重要。仅UI设置：未通过标准REST `repos` 端点暴露。

Checking current settings

检查当前设置

The skill picks the check path based on what the user has installed and whether the repo is public. Never apply changes without explicit user confirmation.

Path 1 –
gh
CLI (preferred, covers public + private uniformly):

bash

gh api "repos/<owner>/<repo>" --jq '{allow_squash_merge, allow_merge_commit, allow_rebase_merge, squash_merge_commit_title, squash_merge_commit_message, delete_branch_on_merge, allow_update_branch}'

Path 2 –
curl
+ public REST API (no auth, public repos only; requires
jq
for the field projection below – fall back to inspecting raw JSON if
jq
is absent):

bash

curl -s "https://api.github.com/repos/<owner>/<repo>" \
  | jq '{allow_squash_merge, allow_merge_commit, allow_rebase_merge, squash_merge_commit_title, squash_merge_commit_message, delete_branch_on_merge, allow_update_branch}'

Rate limit is 60 req/hr per IP unauthenticated – fine for a one-shot realignment check. If the response is a 404 on what should be a visible repo, the repo is private and this path cannot be used.

Path 3 – no CLI available, or private repo without auth: skip the check and proceed straight to the UI walkthrough below; list expected values next to the checkboxes the user should see.

Skill picks the first path that will succeed:

gh

if installed →

curl

if the repo is public → UI-only if neither.

该工具根据用户已安装的工具和仓库是否公开选择检查路径。未经用户明确确认，绝不应用变更。

路径1 –
gh
CLI（首选，统一支持公开+私有仓库）：

bash

gh api "repos/<owner>/<repo>" --jq '{allow_squash_merge, allow_merge_commit, allow_rebase_merge, squash_merge_commit_title, squash_merge_commit_message, delete_branch_on_merge, allow_update_branch}'

路径2 –
curl
+ 公开REST API（无需认证，仅公开仓库；需要
jq
进行字段投影——如果没有
jq
则回退到检查原始JSON）：

bash

curl -s "https://api.github.com/repos/<owner>/<repo>" \
  | jq '{allow_squash_merge, allow_merge_commit, allow_rebase_merge, squash_merge_commit_title, squash_merge_commit_message, delete_branch_on_merge, allow_update_branch}'

未认证时速率限制为每IP每小时60次请求——单次调整检查完全足够。如果响应为404但仓库应可见，则仓库为私有，此路径不可用。

路径3 – 无CLI可用，或无认证的私有仓库： 跳过检查，直接进行下方的UI操作指南；在用户应看到的复选框旁列出预期值。

工具选择第一个可行的路径：已安装

gh

则使用→仓库公开则使用

curl

→否则仅使用UI。

Applying: UI walkthrough

应用设置：UI操作指南

Writes always require auth. Rather than scripting tokens, the skill directs the user through the GitHub UI. Deep-links and precise click-paths:

Open Pull Requests settings (
```
https://github.com/<owner>/<repo>/settings#pull-requests-heading
```
). On that page, adjust:
- Allow merge commits → unchecked (currently
```
allow_merge_commit
```
  should read
```
false
```
  ).
- Allow squash merging → checked. Default commit message → "Pull request title and commit details" (maps to
```
squash_merge_commit_title=PR_TITLE
```
  ,
```
squash_merge_commit_message=COMMIT_MESSAGES
```
  ).
- Allow rebase merging → unchecked.
- Always suggest updating pull request branches → checked (
```
allow_update_branch=true
```
  ).
- Automatically delete head branches → checked (
```
delete_branch_on_merge=true
```
  ).
Scroll to Releases (or open General → Releases and scroll). Toggle Enable release immutability → on. This prevents published release assets and tags from being modified after the fact; it is verified by eye only – the setting is not exposed by the standard
```
repos
```
REST endpoint.
Click Save under each changed control that has one; the checkboxes save inline.

Faster for

gh

-equipped users – the equivalent single PATCH:

bash

gh api -X PATCH "repos/<owner>/<repo>" \
  -F allow_squash_merge=true \
  -F allow_merge_commit=false \
  -F allow_rebase_merge=false \
  -F squash_merge_commit_title=PR_TITLE \
  -F squash_merge_commit_message=COMMIT_MESSAGES \
  -F delete_branch_on_merge=true \
  -F allow_update_branch=true

写入操作始终需要认证。该工具不使用脚本令牌，而是指导用户通过GitHub UI操作。深度链接和精确点击路径：

打开**拉取请求设置**（
```
https://github.com/<owner>/<repo>/settings#pull-requests-heading
```
）。在该页面调整：
- 允许合并提交 → 取消勾选（当前
```
allow_merge_commit
```
  应为
```
false
```
  ）。
- 允许压缩合并 → 勾选。默认提交消息 → "拉取请求标题和提交详情"（对应
```
squash_merge_commit_title=PR_TITLE
```
  ，
```
squash_merge_commit_message=COMMIT_MESSAGES
```
  ）。
- 允许变基合并 → 取消勾选。
- 始终建议更新拉取请求分支 → 勾选（
```
allow_update_branch=true
```
  ）。
- 自动删除头部分支 → 勾选（
```
delete_branch_on_merge=true
```
  ）。
滚动到发布部分（或打开**常规 → 发布并滚动）。切换启用发布不可变性** → 开启。这可防止已发布的发布资产和标签在事后被修改；仅需目视验证——该设置未通过标准
```
repos
```
REST端点暴露。
每个修改的控件下方如有保存按钮则点击；复选框会即时保存。

对于已安装

gh

的用户，可使用更快捷的单条PATCH命令：

bash

gh api -X PATCH "repos/<owner>/<repo>" \
  -F allow_squash_merge=true \
  -F allow_merge_commit=false \
  -F allow_rebase_merge=false \
  -F squash_merge_commit_title=PR_TITLE \
  -F squash_merge_commit_message=COMMIT_MESSAGES \
  -F delete_branch_on_merge=true \
  -F allow_update_branch=true

Realignment-mode prompt format

基线调整模式提示格式

When the check shows drift, present a numbered list to the user with current → target and a deep-link, one setting per row:

text

Repository settings drift detected. Open:
  https://github.com/<owner>/<repo>/settings#pull-requests-heading

  1. Allow merge commits: currently ON, should be OFF.
  2. Allow rebase merging: currently ON, should be OFF.
  3. Default squash commit message: currently "Default to pull request title",
     should be "Pull request title and commit details".
  4. Automatically delete head branches: currently OFF, should be ON.
  (Auto-merge is intentionally left unopinionated – neither recommended nor
   flagged.)

Proceed to apply via `gh api` (if available), or confirm after applying via UI?

In realignment mode, report which check path was used (

gh

curl

, or

skipped

) and the full list of diverging fields. Never modify settings without explicit user confirmation. When package or plugin author URLs point to the repository owner instead of the resolved author handle, report the author block as divergent and offer the normal interactive rewrite.

当检查发现偏离时，向用户呈现编号列表，显示当前值→目标值，并提供深度链接，每行一个设置：

text

检测到仓库设置偏离。打开：
  https://github.com/<owner>/<repo>/settings#pull-requests-heading

  1. 允许合并提交：当前为开启，应关闭。
  2. 允许变基合并：当前为开启，应关闭。
  3. 默认压缩提交消息：当前为"默认使用拉取请求标题",
     应改为"拉取请求标题和提交详情"。
  4. 自动删除头部分支：当前为关闭，应开启。
  (自动合并未做强制要求——既不推荐也不标记。)

是否通过`gh api`应用（如果可用），或通过UI应用后确认？

在基线调整模式下，报告使用的检查路径（

gh

、

curl

或

跳过

）以及所有偏离字段的完整列表。未经用户明确确认，绝不修改设置。当包或插件作者URL指向仓库所有者而非解析后的作者账号时，报告作者块偏离并提供常规的交互式重写选项。

Reserved labels

保留标签

The

autorelease: pending

and

autorelease: tagged

labels are owned by Release Please. In realignment mode, verify that

autorelease: pending

exists with color

ededed

(the release-please default) and a non-empty description explaining the reservation; if either is missing or divergent, recommend a

gh label edit

fix. Never instruct agents to apply or remove these labels manually.

autorelease: pending

和

autorelease: tagged

标签归Release Please所有。在基线调整模式下，验证

autorelease: pending

标签是否存在，颜色为

ededed

（release-please默认值），且包含非空的说明解释其保留用途；如果缺失或偏离，建议使用

gh label edit

修复。绝不指示Agent手动添加或移除这些标签。

Verification self-test

验证自测

After a scaffold or realignment run on this repo, all of the following must succeed:

bash

pnpm install
pnpm exec commitlint --help
pnpm lint:md
echo "feat: bad" | pnpm exec commitlint   # exits non-zero
echo "feat: #1 ok" | pnpm exec commitlint # exits zero

Run

pnpm exec markdownlint-cli2 --fix "**/*.md" "#node_modules"

to auto-fix common markdown violations before committing.

在本仓库完成脚手架生成或基线调整后，以下所有命令必须执行成功：

bash

pnpm install
pnpm exec commitlint --help
pnpm lint:md
echo "feat: bad" | pnpm exec commitlint   # 非零退出码
echo "feat: #1 ok" | pnpm exec commitlint # 零退出码

提交前运行

pnpm exec markdownlint-cli2 --fix "**/*.md" "#node_modules"

可自动修复常见的Markdown违规问题。

Reference implementation

参考实现

This repository –

patinaproject/bootstrap

– is the canonical reference for every file this skill emits. The

templates/

directory under

skills/scaffold-repository/

mirrors these files with placeholders.

本仓库——

patinaproject/bootstrap

——是该工具生成的所有文件的标准参考。

skills/scaffold-repository/

下的

templates/

目录包含带有占位符的这些文件的镜像。

scaffold-repository

Original

Translation

scaffold-repository

scaffold-repository

Modes

模式

New-repo mode

新仓库模式

Realignment mode

基线调整模式

Prompts

提示信息

Core baseline

核心基线

Agent plugin surfaces

Agent插件界面

Patina Project organization supplement

Patina Project组织补充内容

Plugin enablement and skill installation

插件启用与工具安装

Conventions encoded

编码规范

GitHub repository settings

GitHub仓库设置

Checking current settings

检查当前设置

Applying: UI walkthrough

应用设置：UI操作指南

Realignment-mode prompt format

基线调整模式提示格式

Reserved labels

保留标签

Verification self-test

验证自测

Reference implementation

参考实现

Related documents

相关文档