sc-worktree

Worktree 管理技能

通过简单、安全的工作流，使用 Git worktree 隔离并行 Agent 开发。

快速开始

# Create isolated worktree for a task
/sc:worktree create feature-auth

# List all active worktrees
/sc:worktree list

# Propose changes for human review
/sc:worktree propose feature-auth

# Clean up stale worktrees
/sc:worktree cleanup

行为流程

1. 创建 - 初始化具有唯一名称的隔离 worktree
2. 验证 - 执行预检（仓库干净、无冲突）
3. 分配 - 启动工作目录设为该 worktree 的子 Agent
4. 工作 - Agent 在隔离环境中操作，并提交到分支
5. 提议 - 推送分支并创建 PR，供人工审核
6. 清理 - 移除已合并或过时的 worktree

命令

命令	用途	Git 操作
create <task-id>	创建隔离 worktree	git worktree add -b wt/<task>
list	显示所有活动 worktree	git worktree list
status <task-id>	检查 worktree 状态	git status、git log
cleanup [--all]	移除过时的 worktree	git worktree remove、prune
propose <task-id>	创建 PR，供人工审核	git push、gh pr create

标志

标志	类型	默认值	描述
--commits	bool	true	Agent 直接提交到分支
--patches	bool	false	Agent 仅生成补丁文件
--run-tests	bool	false	提议前运行测试
--force	bool	false	覆盖现有 worktree/分支
--base	string	main	worktree 的基础分支

证据要求

此技能不要求硬性证据。Worktree 操作可通过以下内容自行记录：

• Git worktree 列表输出
• 分支历史
• PR 创建确认

命名约定

Worktree 使用确定性命名以防止冲突：

Path:   .worktrees/<task-id>/
Branch: wt/<task-id>

示例：

Path:   .worktrees/feature-auth/
Branch: wt/feature-auth

操作

创建 Worktree

/sc:worktree create feature-auth

# Executes:
# 1. mkdir -p .worktrees
# 2. git worktree add -b wt/feature-auth .worktrees/feature-auth
# 3. Returns worktree path for subagent CWD

列出 Worktree

/sc:worktree list

# Shows:
# - Active worktrees
# - Associated branches
# - Last commit info

检查状态

/sc:worktree status feature-auth

# Shows:
# - Uncommitted changes
# - Commits ahead of base branch
# - Conflict warnings

提议更改

/sc:worktree propose feature-auth

# Executes:
# 1. git push -u origin wt/feature-auth
# 2. gh pr create --title "feat: feature-auth" --body "..."
# 3. Returns PR URL for human review

清理 Worktree

/sc:worktree cleanup          # Remove merged worktrees
/sc:worktree cleanup --all    # Remove ALL worktrees
/sc:worktree cleanup feature-auth  # Remove specific worktree

# Executes:
# 1. git worktree remove .worktrees/<task-id>
# 2. git branch -d wt/<task-id>
# 3. git worktree prune

子 Agent 集成

启动子 Agent 在 worktree 中工作时：

# 1. Create worktree
/sc:worktree create feature-auth

# 2. Spawn subagent with CWD
Task(
    prompt="Implement JWT authentication",
    subagent_type="general-purpose",
    # CWD implicitly set to .worktrees/feature-auth/
)

# 3. Agent works in isolation
# - All file operations scoped to worktree
# - Commits go to wt/feature-auth branch

# 4. Propose for review
/sc:worktree propose feature-auth

预检

创建 worktree 前，此技能会验证：

1. 仓库状态

   • 仓库干净，或已提供 --force 标志
   • 主分支为最新状态

2. 分支可用性

   • wt/<task-id> 分支不存在，或明确选择复用
   • 不存在冲突的远程分支

3. 路径可用性

   • .worktrees/<task-id> 不存在，或已提供 --force 标志

冲突检测

提议前，此技能会检查冲突：

# Fetch latest changes
git fetch origin main

# Check if worktree is behind
git merge-base --is-ancestor origin/main HEAD

# Warn but don't block if behind
# Human reviewer handles merge strategy

示例

单 Agent 工作流

# Create worktree
/sc:worktree create add-logging

# Work in worktree (agent operates here)
# ... agent makes changes, commits ...

# Propose changes
/sc:worktree propose add-logging

# Human reviews PR, merges

# Cleanup
/sc:worktree cleanup add-logging

并行多 Agent 工作流

# Orchestrator creates multiple worktrees
/sc:worktree create feature-auth
/sc:worktree create feature-logging
/sc:worktree create feature-metrics

# Spawn agents in parallel (each with own worktree)
# Agent A -> .worktrees/feature-auth/
# Agent B -> .worktrees/feature-logging/
# Agent C -> .worktrees/feature-metrics/

# Propose all changes
/sc:worktree propose feature-auth
/sc:worktree propose feature-logging
/sc:worktree propose feature-metrics

# Human reviews 3 PRs, merges sequentially

# Cleanup all
/sc:worktree cleanup --all

补丁模式（不直接提交）

/sc:worktree create refactor-api --patches

# Agent produces .patch files instead of commits
# Orchestrator reviews patches before applying

/sc:worktree propose refactor-api  # Creates PR from patches

MCP 集成

PAL MCP（验证与审核）

工具	使用时机	用途
mcp__pal__precommit	提议前	验证 worktree 中的更改
mcp__pal__codereview	提议前	审核 worktree 中的更改
mcp__pal__consensus	冲突解决	多模型合并策略

PAL 使用模式

# Validate worktree changes before proposing
mcp__pal__precommit(
    path=".worktrees/feature-auth",
    step="Validating worktree changes",
    findings="Security, test coverage, completeness",
    compare_to="main"
)

# Review worktree branch
mcp__pal__codereview(
    review_type="full",
    step="Reviewing feature-auth worktree",
    relevant_files=[".worktrees/feature-auth/src/auth.py"]
)

Rube MCP（自动化与通知）

工具	使用时机	用途
mcp__rube__RUBE_SEARCH_TOOLS	GitHub 集成	查找 PR 工具
mcp__rube__RUBE_MULTI_EXECUTE_TOOL	提议命令	创建 PR、通知团队

Rube 使用模式

# Create PR and notify team
mcp__rube__RUBE_MULTI_EXECUTE_TOOL(tools=[
    {"tool_slug": "GITHUB_CREATE_PULL_REQUEST", "arguments": {
        "repo": "myapp",
        "title": "feat: feature-auth from worktree",
        "body": "## Worktree: feature-auth\nCreated via /sc:worktree",
        "base": "main",
        "head": "wt/feature-auth"
    }},
    {"tool_slug": "SLACK_SEND_MESSAGE", "arguments": {
        "channel": "#pull-requests",
        "text": "New PR from worktree: wt/feature-auth"
    }}
])

标志（扩展）

标志	类型	默认值	描述
--pal-review	bool	false	提议前使用 PAL codereview
--create-pr	bool	true	通过 Rube 创建 GitHub PR
--notify	string	-	通过 Rube 通知（slack、teams）
--draft	bool	false	创建草稿 PR

工具协调

• Bash - Git worktree 命令、目录操作
• Read - 检查 worktree 状态和日志
• Task - 启动工作目录设为 worktree 的子 Agent
• PAL MCP - 提议前验证、代码审核
• Rube MCP - 创建 PR、团队通知

安全保障

1. 隔离 - 每个工作树都有独立的工作目录
2. 不自动合并 - 所有合并都必须经过人工审核
3. 命名唯一 - 确定性路径可防止冲突
4. 防崩溃 - cleanup --all 会移除过期的工作树
5. 冲突仅警告 - 冲突会触发警告，但不会阻止操作

限制

• 不会自动评估质量（请使用 CI/测试）
• 不会跟踪租约（改为定期清理）
• 不提供复杂的冲突解决功能（需要人工审核）
• 不会自动合并到 main（基于 PR 的工作流）