# Close Story Worktree

> Safely clean up a repository story after its pull request has been reviewed and merged. Use when Codex must verify a merged PR, remove the exact clean Git worktree, and delete its merged local branch. Supports codex/ID, worktree-ID, claude/ID, and explicit custom branch or worktree names. Never use before the human merge gate.

- Skill: `astropham1808/close-story-worktree` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add astropham1808/close-story-worktree`
- Raw SKILL.md: https://api.skillmd.com/api/skills/astropham1808/close-story-worktree/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: astropham1808 (https://skillmd.com/u/astropham1808)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/astropham1808/close-story-worktree

---


# Close Story Worktree

Clean up a merged story in a strict order. Keep this skill limited to GitHub
merge verification and local Git cleanup.

## Required inputs

Resolve these before changing state:

- story ID;
- repository root;
- exact head branch;
- exact worktree path;
- PR URL or number;
- base branch.

Read applicable `AGENTS.md` files. Preserve unrelated worktrees and branches.
Accept branch forms such as `codex/AL-151`, `worktree-AL-161`, or
`claude/AL-216`; never rewrite one naming convention into another.

## Sequence

1. Inspect `git status --short --branch` and
   `git worktree list --porcelain`.
2. Use `gh pr view` or the GitHub connector to confirm the exact PR has
   `mergedAt` set and targets the expected base branch.
3. If the PR is open, draft, closed without merge, or ambiguous, stop. Return
   the PR URL and leave the worktree and branch unchanged.
4. Require the story worktree to be clean. Never reset, clean, stash, or force
   removal to make it appear clean.
5. Run `scripts/cleanup-merged-story.sh` without `--apply` to preview the exact
   targets and safety checks.
6. Run the same command with `--apply` only when the user has placed cleanup in
   scope. The script fetches the PR base, verifies the branch tip is an ancestor
   of the updated base, removes the exact worktree without force, then uses
   `git branch -d`.
7. Confirm the path no longer appears in `git worktree list --porcelain` and
   the local branch no longer exists.
8. Report the merged PR, removed worktree, deleted local branch, and any
   intentionally retained remote branch.

## Safety rules

- Never merge the PR. The human reviews and merges.
- Never run cleanup based only on a story ID guess.
- Never use `git worktree remove --force`, `git branch -D`, `git reset`,
  `git clean`, or a recursive filesystem deletion.
- Never remove the primary worktree, repository root, or a dirty worktree.
- Keep source-tracker completion in a separate workflow.
- If a squash merge makes the branch tip not ancestral to the base, stop before
  removal. Ask the user whether to retain the branch or authorize a separate
  recoverability plan.
- Do not delete the remote branch unless the user explicitly requests it.

## Cleanup command

Preview:

```bash
scripts/cleanup-merged-story.sh AL-151 codex/AL-151
```

Apply with an explicit worktree when useful:

```bash
scripts/cleanup-merged-story.sh AL-151 codex/AL-151 \
  --worktree /absolute/path/to/worktree --apply
```

The script verifies merge state and targets in both modes.