worktree-feature-execution

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Worktree Feature Execution

工作树功能执行流程

Purpose

目标

Execute feature delivery in isolated git worktrees with consistent automation for branch creation, synchronization, pull request creation, merge safety, and cleanup. Use this skill to reduce branch switching, minimize cross-feature interference, and maintain a clean integration path into

main

在隔离的git工作树中执行功能交付，实现分支创建、同步、拉取请求（PR）创建、安全合并和清理的自动化流程。使用本技能可减少分支切换操作，最小化跨功能干扰，保持向

main

分支集成的路径整洁。

Harness Contract

协作约定

Read project instructions from

AGENTS.md

first. Read

project.yaml

second when present. Prefer AGENTS-defined conventions over CLAUDE-specific conventions.

Use this directory resolution priority unless the project explicitly overrides it:

Existing
```
.worktrees/
```
Existing
```
worktrees/
```
Config value from
```
project.yaml
```
Default
```
.worktrees/
```

For project-local roots (

.worktrees/

worktrees/

), verify ignore coverage before worktree creation. Add ignore entries when missing.

首先从

AGENTS.md

中读取项目说明，若存在

project.yaml

则其次读取该文件。优先遵循AGENTS中定义的约定，而非Claude专属约定。

除非项目明确覆盖，否则使用以下目录解析优先级：

已存在的
```
.worktrees/
```
已存在的
```
worktrees/
```
```
project.yaml
```
中的配置值
默认的
```
.worktrees/
```

对于项目本地根目录（

.worktrees/

或

worktrees/

），在创建工作树前需验证忽略规则是否覆盖。若缺失则添加忽略条目。

Operating Principles

操作原则

Keep one feature per worktree and one branch per worktree.
Keep branch names predictable and slug-safe.
Keep PRs small and short-lived.
Rebase frequently to reduce conflict depth.
Run quality checks before PR creation and before merge.
Avoid destructive git actions.

每个工作树对应一个功能，每个工作树对应一个分支。
保持分支名称可预测且符合slug规范。
保持PR内容精简、生命周期短。
经常执行变基操作以减少冲突深度。
在创建PR和合并前运行质量检查。
避免执行破坏性的git操作。

Command Resources

命令资源

Use bundled scripts in

scripts/

for deterministic execution:

```
scripts/preflight-check.sh
```
- repository, branch, remote, and
```
gh
```
readiness checks.
```
scripts/create-worktree.sh
```
- branch + worktree creation with ignore safeguards.
```
scripts/sync-worktree.sh
```
- fetch + rebase branch onto base branch.
```
scripts/generate-pr-body.sh
```
- compatibility-aware PR body generation.
```
scripts/open-pr.sh
```
- push and create or reuse pull requests.
```
scripts/merge-pr.sh
```
- merge pull request with checks and queue support.
```
scripts/cleanup-worktree.sh
```
- safe worktree removal and prune.
```
scripts/run-feature-flow.sh
```
- orchestration wrapper for preflight to PR (and optional merge).
```
scripts/windows/run-feature-flow.cmd
```
- Windows wrapper for safer script invocation.
```
scripts/windows/doctor.cmd
```
- Windows environment diagnostics for
```
git
```
,
```
gh
```
, and
```
bash
```
.

All core scripts support machine-readable output using

--json

使用

scripts/

目录下的捆绑脚本确保执行结果一致：

```
scripts/preflight-check.sh
```
- 仓库、分支、远程仓库和
```
gh
```
工具的就绪性检查。
```
scripts/create-worktree.sh
```
- 带忽略规则防护的分支+工作树创建脚本。
```
scripts/sync-worktree.sh
```
- 拉取远程更新并将分支变基到基准分支。
```
scripts/generate-pr-body.sh
```
- 生成兼容型PR正文内容。
```
scripts/open-pr.sh
```
- 推送分支并创建或复用拉取请求。
```
scripts/merge-pr.sh
```
- 带检查和队列支持的PR合并脚本。
```
scripts/cleanup-worktree.sh
```
- 安全删除工作树并清理过时元数据。
```
scripts/run-feature-flow.sh
```
- 从预检到PR创建（及可选合并）的流程编排脚本。
```
scripts/windows/run-feature-flow.cmd
```
- Windows环境下的安全脚本调用包装器。
```
scripts/windows/doctor.cmd
```
- Windows环境下
```
git
```
、
```
gh
```
和
```
bash
```
的诊断脚本。

所有核心脚本支持通过

--json

参数输出机器可读格式。

One-Command Orchestration

一键式流程编排

Run the complete flow from the repository root:

bash

bash .agents/skills/worktree-feature-execution/scripts/run-feature-flow.sh \
  --feature "add billing retries" \
  --base "current-branch" \
  --pr-base "main" \
  --prefix "feat" \
  --summary "Improve retry reliability for transient payment failures"

Optional flags:

```
--draft
```
to create draft PR.
```
--merge --queue --merge-method squash
```
to queue merge after PR creation.
```
--no-pr
```
to stop after worktree creation and sync.
```
--setup auto|none|"<custom command>"
```
to control setup behavior.
```
--issue <number>
```
to append closing issue reference in PR body.

Windows invocation example:

cmd

.agents\skills\worktree-feature-execution\scripts\windows\run-feature-flow.cmd --feature "add billing retries"

在仓库根目录执行完整流程：

bash

bash .agents/skills/worktree-feature-execution/scripts/run-feature-flow.sh \
  --feature "add billing retries" \
  --base "current-branch" \
  --pr-base "main" \
  --prefix "feat" \
  --summary "Improve retry reliability for transient payment failures"

可选参数：

```
--draft
```
- 创建草稿PR。
```
--merge --queue --merge-method squash
```
- PR创建后将其加入合并队列。
```
--no-pr
```
- 在工作树创建和同步后停止流程。
```
--setup auto|none|"<custom command>"
```
- 控制初始化行为。
```
--issue <number>
```
- 在PR正文中添加关联的Issue关闭引用。

Windows环境调用示例：

cmd

.agents\skills\worktree-feature-execution\scripts\windows\run-feature-flow.cmd --feature "add billing retries"

Standard Workflow

标准工作流

1) Preflight

1) 预检

Run:

bash

bash .agents/skills/worktree-feature-execution/scripts/preflight-check.sh

Verify:

Current directory belongs to a git repository.
Base branch can be resolved.
```
origin
```
remote exists.
```
gh
```
is installed and authenticated.
```
git
```
and
```
gh
```
executable paths resolve correctly.
Current shell context is reported for diagnostics.

If authentication or permissions fail, stop and report the blocking condition.

执行：

bash

bash .agents/skills/worktree-feature-execution/scripts/preflight-check.sh

验证内容：

当前目录属于git仓库。
基准分支可解析。
```
origin
```
远程仓库存在。
```
gh
```
工具已安装并完成认证。
```
git
```
和
```
gh
```
的可执行文件路径可正确解析。
报告当前shell上下文用于诊断。

若认证或权限验证失败，立即停止并报告阻塞问题。

2) Create Isolated Worktree

2) 创建隔离工作树

Run:

bash

bash .agents/skills/worktree-feature-execution/scripts/create-worktree.sh \
  --feature "add billing retries" \
  --base "current-branch" \
  --prefix "feat"

Behavior:

Resolve base branch from current branch when
```
--base current-branch
```
.
Resolve worktree root using priority order.
Ensure root is gitignored when local to repository.
Create
```
feat/<slug>
```
branch if missing, or reuse existing branch.
Create worktree path
```
<root>/<slug>
```
.

Useful flags:

```
--no-gitignore-edit
```
to fail instead of mutating
```
.gitignore
```
.
```
--print-ignore-patch
```
to display the exact ignore line before apply.

执行：

bash

bash .agents/skills/worktree-feature-execution/scripts/create-worktree.sh \
  --feature "add billing retries" \
  --base "current-branch" \
  --prefix "feat"

行为说明：

当使用
```
--base current-branch
```
时，从当前分支解析基准分支。
按优先级顺序解析工作树根目录。
若根目录在仓库本地，确保已被git忽略。
若
```
feat/<slug>
```
分支不存在则创建，否则复用现有分支。
创建工作树路径
```
<root>/<slug>
```
。

实用参数：

```
--no-gitignore-edit
```
- 若
```
.gitignore
```
需要修改则直接失败，而非自动修改。
```
--print-ignore-patch
```
- 在应用前显示要添加的忽略规则内容。

3) Implement Feature

3) 功能实现

Perform implementation inside the created worktree path only. Keep scope aligned with the feature statement.

Recommended checks:

Type checks
Unit/integration tests
Build command

Record notable changes and compatibility concerns for PR body.

仅在创建的工作树路径内进行功能实现。保持实现范围与功能描述一致。

推荐执行的检查：

类型检查
单元/集成测试
构建命令

记录重要变更和兼容性问题，用于PR正文。

4) Sync With Base Branch

4) 与基准分支同步

Run in the worktree:

bash

bash .agents/skills/worktree-feature-execution/scripts/sync-worktree.sh \
  --base "main"

Behavior:

Fetch remote updates.
Rebase feature branch on top of latest base branch.
Stop on conflicts and report exact conflict files.

在工作树中执行：

bash

bash .agents/skills/worktree-feature-execution/scripts/sync-worktree.sh \
  --base "main"

行为说明：

拉取远程仓库更新。
将功能分支变基到最新的基准分支。
若遇到冲突则停止，并报告具体的冲突文件。

5) Open Pull Request

5) 创建拉取请求

Run in the worktree:

bash

bash .agents/skills/worktree-feature-execution/scripts/open-pr.sh \
  --base "main" \
  --title "feat: add billing retry policy" \
  --body-file ".git/PR_BODY.md"

Behavior:

Push branch with upstream tracking if needed.
Reuse open PR when one already exists.
Auto-generate PR body file when missing.
Create PR when missing.
Validate PR body is non-empty after create/update.
Return PR URL.

在工作树中执行：

bash

bash .agents/skills/worktree-feature-execution/scripts/open-pr.sh \
  --base "main" \
  --title "feat: add billing retry policy" \
  --body-file ".git/PR_BODY.md"

行为说明：

若需要则推送分支并设置上游跟踪。
若已有打开的PR则复用该PR。
若PR正文文件缺失则自动生成。
若不存在PR则创建新PR。
验证PR正文在创建/更新后非空。
返回PR的URL。

5a) Generate PR Body Template

5a) 生成PR正文模板

Run in the worktree:

bash

bash .agents/skills/worktree-feature-execution/scripts/generate-pr-body.sh \
  --base "main" \
  --feature "add billing retries" \
  --risk "medium" \
  --output ".git/PR_BODY.md"

Behavior:

Build compatibility-aware PR content from git diff context.
Include commit and changed-file counts against base.
Add risk and rollback sections.

在工作树中执行：

bash

bash .agents/skills/worktree-feature-execution/scripts/generate-pr-body.sh \
  --base "main" \
  --feature "add billing retries" \
  --risk "medium" \
  --output ".git/PR_BODY.md"

行为说明：

基于git diff上下文生成兼容型PR内容。
包含相对于基准分支的提交数和文件变更数。
添加风险评估和回滚方案章节。

6) Merge Pull Request

6) 合并拉取请求

Run:

bash

bash .agents/skills/worktree-feature-execution/scripts/merge-pr.sh \
  --pr "<url-or-number>" \
  --method "squash" \
  --queue

Behavior:

Validate merge method.
Confirm checks status.
Queue merge (
```
--auto
```
) when requested.
Delete remote branch after merge when supported.

执行：

bash

bash .agents/skills/worktree-feature-execution/scripts/merge-pr.sh \
  --pr "<url-or-number>" \
  --method "squash" \
  --queue

行为说明：

验证合并方法的有效性。
确认检查状态是否通过。
若请求则将合并加入队列（
```
--auto
```
）。
合并后若支持则删除远程分支。

7) Cleanup

7) 清理

Run:

bash

bash .agents/skills/worktree-feature-execution/scripts/cleanup-worktree.sh \
  --path ".worktrees/add-billing-retries"

Behavior:

Refuse cleanup when uncommitted changes exist unless
```
--force
```
.
Remove worktree and prune stale metadata.

执行：

bash

bash .agents/skills/worktree-feature-execution/scripts/cleanup-worktree.sh \
  --path ".worktrees/add-billing-retries"

行为说明：

若存在未提交变更则拒绝清理，除非使用
```
--force
```
参数。
删除工作树并清理过时元数据。

Multi-Agent Coordination

多Agent协同

Use one worktree per agent. Assign explicit ownership boundaries by directory, module, or capability.

Execution order:

Merge foundational PRs first.
Rebase dependent PRs after each upstream merge.
Re-run checks after every rebase.
Merge dependent PRs only after compatibility verification.

For shared contracts (API/schema/event payloads), include compatibility notes in PR body and require contract tests.

每个Agent使用一个独立工作树。按目录、模块或功能明确划分所有权边界。

执行顺序：

优先合并基础功能的PR。
每次上游分支合并后，对依赖PR执行变基操作。
每次变基后重新运行检查。
仅在兼容性验证通过后合并依赖PR。

对于共享契约（API/ schema/事件负载），需在PR正文中添加兼容性说明，并要求执行契约测试。

Serialization Rule

序列化规则

Do not run mutating git commands in parallel. Serialize all operations that write git state (

add

commit

stash

checkout

worktree add/remove

rebase

merge

). Parallelize read-only commands only.

不要并行执行会修改git状态的命令。所有会写入git状态的操作（

add

、

commit

、

stash

、

checkout

、

worktree add/remove

、

rebase

、

merge

）都需串行执行。仅可并行执行只读命令。

Windows Compatibility

Windows兼容性

Prefer Git Bash for all

.sh

scripts on Windows. In restricted runners, use explicit wrapper commands under

scripts/windows/

Recommended sequence:

Run
```
scripts/windows/doctor.cmd
```
.
Fix PATH for
```
git
```
,
```
gh
```
, and
```
bash
```
if missing.
Run
```
scripts/windows/run-feature-flow.cmd
```
.

When

bash

is not in PATH, set

GIT_BASH

to an explicit

bash.exe

location.

在Windows环境下优先使用Git Bash运行所有

.sh

脚本。在受限运行环境中，使用

scripts/windows/

目录下的显式包装器命令。

推荐执行顺序：

运行
```
scripts/windows/doctor.cmd
```
。
若
```
git
```
、
```
gh
```
和
```
bash
```
的路径缺失则修复PATH配置。
运行
```
scripts/windows/run-feature-flow.cmd
```
。

若

bash

不在PATH中，需将

GIT_BASH

设置为

bash.exe

的明确路径。

Manual Fallback Checklist

手动回退检查清单

Use this fallback path when orchestration cannot run end-to-end:

Run preflight.
Create worktree.
Sync worktree with base branch.
Generate PR body.
Open PR using
```
--body-file
```
.
Merge only after checks pass.
Clean up worktree.

当编排脚本无法端到端运行时，使用以下回退流程：

执行预检。
创建工作树。
将工作树与基准分支同步。
生成PR正文。
使用
```
--body-file
```
参数创建PR。
仅在检查通过后合并PR。
清理工作树。

Edge Cases

边缘情况处理

Detached HEAD

分离HEAD状态

Resolve base branch using

origin/HEAD

fallback. Stop when neither current branch nor remote default branch can be resolved.

使用

origin/HEAD

作为基准分支的回退方案。若当前分支和远程默认分支均无法解析则停止操作。

Existing Branch Already Checked Out

分支已被检出

If branch is already attached to another worktree, stop and select a new branch name or reuse that worktree.

若分支已关联到其他工作树，则停止操作并提示选择新分支名称或复用该工作树。

Worktree Path Exists

工作树路径已存在

Refuse creation when target path exists and is non-empty.

若目标路径已存在且非空，则拒绝创建工作树。

Missing Ignore Rule

忽略规则缺失

Append missing root ignore entry to

.gitignore

before creating local worktree roots.

在创建本地工作树根目录前，向

.gitignore

添加缺失的根目录忽略条目。

Diverged Branches

分支分叉

Require rebase and conflict resolution before PR creation.

要求在创建PR前执行变基和冲突解决。

Existing PR

PR已存在

Return existing PR URL instead of creating duplicate PR.

返回已存在的PR URL，而非创建重复PR。

CI Failures

CI检查失败

Do not merge. Report failed checks and keep worktree active for remediation.

不执行合并操作。报告失败的检查项，并保持工作树活跃以便修复问题。

Merge Queue Enabled

合并队列已启用

Use

--queue

flow and avoid direct merge bypass.

使用

--queue

流程，避免直接绕过队列进行合并。

Permission Errors

权限错误

Stop and report required

gh

scope or repository role.

停止操作并报告所需的

gh

权限或仓库角色。

Red Flags

注意事项

Never:

Run
```
git reset --hard
```
or force-push to
```
main
```
.
Merge with known failing checks.
Delete worktree containing uncommitted work without explicit force signal.
Create worktrees in unignored project-local directories.

Always:

Run preflight before worktree creation.
Run sync before PR and before merge.
Surface PR URL and merge status.
Clean up merged worktrees.

绝对禁止：

对
```
main
```
分支执行
```
git reset --hard
```
或强制推送操作。
合并已知检查失败的PR。
在未收到明确
```
--force
```
信号时，删除包含未提交变更的工作树。
在未被忽略的项目本地目录中创建工作树。

必须执行：

在创建工作树前执行预检。
在创建PR和合并前执行同步操作。
提供PR URL和合并状态。
合并完成后清理工作树。

Additional Resources

附加资源

Reference files:

```
references/branch-naming.md
```
```
references/conflict-playbook.md
```
```
references/merge-policy.md
```
```
references/pr-template.md
```
```
CHANGELOG.md
```
```
VERSION
```

参考文件：

```
references/branch-naming.md
```
```
references/conflict-playbook.md
```
```
references/merge-policy.md
```
```
references/pr-template.md
```
```
CHANGELOG.md
```
```
VERSION
```