lvlup-sw/cleanup

Cleanup Skill

VCS Provider

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.

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.

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.

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

Prerequisites

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

Process

1. Identify Target Workflow

Read workflow state to get current phase and metadata:

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

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

mcp__exarchos__exarchos_view({ action: "pipeline" })

2. Verify Merge Status

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

Primary method — VCS MCP action:

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.

2.5. Post-Merge Regression Check (Advisory)

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

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.

3. Invoke Cleanup Action

Call the MCP cleanup action with collected data:

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

4. Worktree Cleanup

Remove all worktrees associated with the workflow:

# Read worktrees from state (already captured in step 1)
git worktree remove .worktrees/<name>
git worktree prune

Handle gracefully if worktrees are already removed.

5. Branch Sync

Remove merged local branches:

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

6. Report Completion

Output summary:

## Cleanup Complete

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

Dry Run

Use dryRun: true to preview what cleanup would do without modifying state:

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 |

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 |

Exarchos Integration

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

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