cleanup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cleanup Skill

Cleanup 技能

VCS Provider

VCS 提供商

This skill uses VCS operations through Exarchos MCP actions (

list_prs

get_pr_comments

, etc.). These actions automatically detect and route to the correct VCS provider (GitHub, GitLab, Azure DevOps). No

gh

glab

az

commands needed — the MCP server handles provider dispatch.

本技能通过Exarchos MCP动作（

list_prs

、

get_pr_comments

等）执行VCS操作。这些动作会自动检测并路由到正确的VCS提供商（GitHub、GitLab、Azure DevOps）。无需使用

gh

glab

az

命令——MCP服务器会处理提供商调度。

Overview

概述

Resolve merged workflows to

completed

state in a single operation. Replaces the manual multi-step process of navigating HSM guards after PR stacks merge.

通过单次操作将已合并的工作流转换为

completed

状态。替代PR栈合并后手动导航HSM防护的多步骤流程。

Batch Pruning for Stale Workflows

陈旧工作流批量清理

For bulk cleanup of accumulated stale or abandoned workflows (as opposed to resolving a single merged workflow), use

@skills/prune-workflows/SKILL.md

. That skill invokes

exarchos_orchestrate prune_stale_workflows

in dry-run mode, displays candidates, and applies after user confirmation. Safeguards automatically skip workflows with open PRs or recent commits.

Rule of thumb: cleanup is per-workflow (one merged feature →

completed

); prune is bulk (N inactive workflows →

cancelled

). They are complementary, not alternatives.

对于累积的陈旧或废弃工作流的批量清理（与处理单个已合并工作流相对），请使用

@skills/prune-workflows/SKILL.md

。该技能会以试运行模式调用

exarchos_orchestrate prune_stale_workflows

，显示候选对象，并在用户确认后执行清理。防护机制会自动跳过包含未关闭PR或近期提交的工作流。

经验法则： cleanup针对单个工作流（一个已合并的功能→

completed

）；prune针对批量操作（N个非活跃工作流→

cancelled

）。二者互补，而非替代关系。

Triggers

触发条件

Activate this skill when:

User runs
```
/cleanup
```
command
User says "cleanup", "resolve workflow", "mark as done"
PR stack has merged and workflow needs resolution
User wants to close out a completed feature

在以下情况激活本技能：

用户运行
```
/cleanup
```
命令
用户提到“cleanup”、“resolve workflow”、“mark as done”
PR栈已合并，工作流需要处理
用户希望结束已完成的功能

Prerequisites

前置条件

Active workflow in any non-terminal phase
All PRs merged on GitHub

处于任何非终端阶段的活跃工作流
GitHub上所有PR均已合并

Process

流程

1. Identify Target Workflow

1. 识别目标工作流

Read workflow state to get current phase and metadata:

typescript

mcp__exarchos__exarchos_workflow({ action: "get", featureId: "<id>" })

If featureId not provided, use pipeline view to list active workflows:

typescript

mcp__exarchos__exarchos_view({ action: "pipeline" })

读取工作流状态以获取当前阶段和元数据：

typescript

mcp__exarchos__exarchos_workflow({ action: "get", featureId: "<id>" })

如果未提供featureId，使用流水线视图列出活跃工作流：

typescript

mcp__exarchos__exarchos_view({ action: "pipeline" })

2. Verify Merge Status

2. 验证合并状态

For each PR associated with the workflow, verify it is merged.

Primary method — VCS MCP action:

typescript

exarchos_orchestrate({ action: "list_prs", state: "merged" })

For individual PR details, use

exarchos_orchestrate({ action: "get_pr_comments", prId: "<number>" })

or the VCS provider's native API.

Collect from merged PRs:

```
prUrl
```
: The PR URL (or array of URLs for stacked PRs)
```
mergedBranches
```
: The head branch names that were merged

Safety check: If ANY PR is not merged, abort with clear error message.

For detailed verification guidance, see

references/merge-verification.md

针对工作流关联的每个PR，验证其已合并。

主要方法 —— VCS MCP动作：

typescript

exarchos_orchestrate({ action: "list_prs", state: "merged" })

如需单个PR详情，使用

exarchos_orchestrate({ action: "get_pr_comments", prId: "<number>" })

或VCS提供商的原生API。

从已合并PR中收集：

```
prUrl
```
：PR的URL（对于堆叠PR则为URL数组）
```
mergedBranches
```
：已合并的头部分支名称

安全检查： 如果有任何PR未合并，中止操作并显示清晰的错误信息。

详细的验证指南请参阅

references/merge-verification.md

。

2.5. Post-Merge Regression Check (Advisory)

2.5. 合并后回归检查（建议性）

After verifying merge status, run the post-merge regression check:

typescript

exarchos_orchestrate({
  action: "check_post_merge",
  featureId: "<id>",
  prUrl: "<url>",
  mergeSha: "<sha>"
})

This check is advisory — findings are reported but do not block cleanup. If findings are detected, log them for the user's awareness before proceeding.

验证合并状态后，运行合并后回归检查：

typescript

exarchos_orchestrate({
  action: "check_post_merge",
  featureId: "<id>",
  prUrl: "<url>",
  mergeSha: "<sha>"
})

此检查为建议性——检测到的问题会被报告，但不会阻止清理。如果发现问题，在继续操作前记录并告知用户。

3. Invoke Cleanup Action

3. 调用清理动作

Call the MCP cleanup action with collected data:

typescript

mcp__exarchos__exarchos_workflow({
  action: "cleanup",
  featureId: "<id>",
  mergeVerified: true,
  prUrl: "<url-or-array>",
  mergedBranches: ["branch1", "branch2"]
})

This single call:

Backfills
```
synthesis.prUrl
```
and
```
synthesis.mergedBranches
```
Force-resolves all blocking review statuses to
```
approved
```
Transitions to
```
completed
```
via universal cleanup path
Emits
```
workflow.cleanup
```
event to event store

使用收集的数据调用MCP清理动作：

typescript

mcp__exarchos__exarchos_workflow({
  action: "cleanup",
  featureId: "<id>",
  mergeVerified: true,
  prUrl: "<url-or-array>",
  mergedBranches: ["branch1", "branch2"]
})

该单次调用会：

回填
```
synthesis.prUrl
```
和
```
synthesis.mergedBranches
```
将所有阻塞的审核状态强制解决为
```
approved
```
通过通用清理路径转换为
```
completed
```
状态
向事件存储发送
```
workflow.cleanup
```
事件

4. Worktree Cleanup

4. 工作树清理

Remove all worktrees associated with the workflow:

bash

undefined

移除与工作流关联的所有工作树：

bash

undefined

Read worktrees from state (already captured in step 1)

从状态中读取工作树（已在步骤1中捕获）

git worktree remove .worktrees/<name> git worktree prune


Handle gracefully if worktrees are already removed.

git worktree remove .worktrees/<name> git worktree prune


如果工作树已被移除，需优雅处理。

5. Branch Sync

5. 分支同步

Remove merged local branches:

bash

git fetch --prune
git branch -d <merged-branch-1> <merged-branch-2> ...

移除已合并的本地分支：

bash

git fetch --prune
git branch -d <merged-branch-1> <merged-branch-2> ...

6. Report Completion

6. 报告完成情况

Output summary:

markdown

undefined

输出摘要：

markdown

undefined

Cleanup Complete

清理完成

Feature: <featureId> Transition: <previousPhase> → completed PRs merged: <count> Worktrees removed: <count> Branches synced: ✓

undefined

功能： <featureId> 状态转换： <previousPhase> → completed 已合并PR数量： <count> 已移除工作树数量： <count> 分支已同步： ✓

undefined

Dry Run

试运行模式

Use

dryRun: true

to preview what cleanup would do without modifying state:

typescript

mcp__exarchos__exarchos_workflow({
  action: "cleanup",
  featureId: "<id>",
  mergeVerified: true,
  dryRun: true
})

使用

dryRun: true

预览清理操作的效果，而不会修改状态：

typescript

mcp__exarchos__exarchos_workflow({
  action: "cleanup",
  featureId: "<id>",
  mergeVerified: true,
  dryRun: true
})

Error Handling

错误处理

Error	Cause	Resolution
STATE_NOT_FOUND	Invalid featureId	Check pipeline view for active workflows
ALREADY_COMPLETED	Workflow already done	No action needed
INVALID_TRANSITION	Workflow is cancelled	Cannot cleanup cancelled workflows
GUARD_FAILED	mergeVerified is false	Verify PRs are merged before cleanup

错误	原因	解决方法
STATE_NOT_FOUND	无效的featureId	检查流水线视图中的活跃工作流
ALREADY_COMPLETED	工作流已完成	无需操作
INVALID_TRANSITION	工作流已取消	无法清理已取消的工作流
GUARD_FAILED	mergeVerified为false	清理前验证所有PR已合并

Anti-Patterns

反模式

Don't	Do Instead
Use cleanup as escape hatch during implementation	Only use after PRs are merged
Skip merge verification	Always verify via GitHub API
Manually navigate HSM guards post-merge	Use /cleanup
Leave worktrees after cleanup	Include worktree removal in process

请勿	建议做法
在实现过程中将cleanup作为逃避方式	仅在PR合并后使用
跳过合并验证	始终通过GitHub API进行验证
合并后手动导航HSM防护	使用/cleanup命令
清理后保留工作树	在流程中包含工作树移除步骤

Exarchos Integration

Exarchos 集成

The cleanup action auto-emits events — do NOT manually emit:

```
workflow.cleanup
```
— emitted by the MCP cleanup action for the phase change to completed

清理动作会自动发送事件——请勿手动发送：

```
workflow.cleanup
```
—— 当状态转换为completed时，由MCP清理动作发送