shenxingy/worktree

Clade for Codex

This workflow runs directly in Codex. Do not launch the claude CLI or delegate the workflow to Clade's MCP bridge.

Codex compatibility rules:

• Read the nearest AGENTS.md files for repository instructions. If a project has only CLAUDE.md, treat it as legacy project guidance and read it too.
• Store new Clade working state under .clade/ (or ~/.clade/ for personal state). Existing legacy Claude state may be read for migration, but do not create new vendor-specific state.
• A /skill-name reference means the corresponding Codex $skill-name skill, or the same workflow invoked naturally when explicit skill invocation is not available.
• Use Codex web, file, shell, image, and subagent capabilities when the source workflow names a vendor-specific tool. If a capability is unavailable, use the documented fallback instead of spawning another agent CLI.
• Paths such as <plugin-root>/... are relative to the installed Clade plugin containing this SKILL.md; resolve that root before invoking a helper.

Canonical Clade workflow

You are the Worktree skill. You manage git worktrees to enable parallel Codex sessions without file conflicts.

Parse the command

The user's input after /worktree determines the action:

• No flags, just a quoted string → CREATE a new worktree (e.g., /worktree "Fix padding in settings")
• --list → LIST all active worktrees
• --merge <branch> → MERGE a specific worktree branch into the current branch
• --merge --all → MERGE all worktree branches (prefix wt/)
• --clean → REMOVE all worktrees and delete their branches

---

ACTION: CREATE

When the user provides a task prompt (e.g., /worktree "Fix padding in settings pages"):

Step 1: Determine project info

basename "$(git rev-parse --show-toplevel)"    # e.g., "companyOS"
git rev-parse --abbrev-ref HEAD                # current branch name

Step 2: Generate branch name

Convert the user's prompt into a short kebab-case slug (3-5 words max):

• "Fix padding in settings pages" → wt/fix-padding-settings
• "Add rate limiting to API routes" → wt/add-rate-limiting-api
• Always prefix with wt/

Step 3: Find the next worktree number

# Count existing worktrees with the project name pattern
ls -d ../$(basename $(pwd))-wt-* 2>/dev/null | wc -l

Use the next number (1, 2, 3...).

Step 4: Create the worktree

git worktree add ../<project>-wt-<N> -b <branch-name>

For example:

git worktree add ../companyOS-wt-1 -b wt/fix-padding-settings

If the command fails because the branch already exists, inform the user and suggest a different name.

Step 5: Write TASK.md

Write a TASK.md file in the root of the new worktree. This file will be automatically visible to a new Codex session opened in that directory.

The TASK.md should contain:

# Task

<the user's original prompt>

## Context

- Branch: `<branch-name>`
- Created from: `<source-branch>` at commit `<short-hash>`
- Main project: `../<project>/`

## Rules

- Only modify files related to the task above
- Do NOT modify shared config files (e.g., globals.css, layout.tsx, package.json) unless specifically asked
- Commit your changes to this branch when done
- When finished, go back to the main project and run: `/worktree --merge <branch-name>`

## Getting started

Read the relevant files first, understand the existing patterns, then make changes.

Step 6: Output to user

Print a clear message:

Worktree created:
  Directory: ../<project>-wt-<N>
  Branch:    <branch-name>

Start a new Codex session:
  cd ../<project>-wt-<N> && codex

When done, come back here and run:
  /worktree --merge <branch-name>

---

ACTION: LIST

Run:

git worktree list

Format the output nicely, showing:

• Path
• Branch name
• Whether it has uncommitted changes (run git -C <path> status --porcelain for each)

---

ACTION: MERGE

Single branch (--merge <branch>)

1. Check for uncommitted changes in the current worktree:

   git status --porcelain
   

   If there are changes, warn the user and ask whether to continue.

2. Merge the branch:

   git merge <branch-name>
   

3. If merge succeeds, suggest cleanup:

   Merged <branch-name> successfully.
   Run `/worktree --clean` to remove the worktree, or keep it for more work.
   

4. If there are merge conflicts, show the conflicting files and help resolve them.

All branches (--merge --all)

1. List all branches with wt/ prefix:

   git branch --list "wt/*"
   

2. Merge each one sequentially
3. Stop and report if any merge has conflicts

---

ACTION: CLEAN

1. List all worktrees (excluding the main one):

   git worktree list --porcelain
   

2. For each non-main worktree:

   • Check for uncommitted changes
   • If there are uncommitted changes, warn the user and ask for confirmation
   • Remove the worktree:

     git worktree remove <path>
     

   • Delete the branch if it's been merged:

     git branch -d <branch-name>
     

   • If the branch hasn't been merged, warn the user and ask if they want to force delete (-D)

3. Report what was cleaned up.

---

General rules

• Be concise. This is a utility, not a conversation.
• Always show the exact commands you're running.
• If something fails, show the error and suggest a fix.
• Never force-delete branches or worktrees without asking the user first.

---

Completion Status

• ✅ DONE — task completed successfully
• ⚠ DONE_WITH_CONCERNS — completed but with caveats to note
• ❌ BLOCKED — cannot proceed; write details to .clade/blockers.md
• ❓ NEEDS_CONTEXT — missing information; use AskUserQuestion

3-strike rule: If the same approach fails 3 times, switch to BLOCKED — do not retry indefinitely.

Additional skill reference

Worktree Skill

Quickly spin up isolated git worktrees so you can open parallel Codex sessions without conflicts. Each worktree gets its own branch and a TASK.md describing what to work on.

Usage

Create a new worktree

/worktree "Fix all padding issues in settings pages"

Creates a worktree, branch, and TASK.md. Prints the command to start a new Codex session in it.

List active worktrees

/worktree --list

Merge a worktree branch back

/worktree --merge wt/fix-padding-settings
/worktree --merge --all

Clean up all worktrees

/worktree --clean

How it works

1. Create: Makes a sibling directory ../<project>-wt-<n> with a new branch wt/<slug>
2. TASK.md: Written to the worktree root so the new Codex session auto-reads it
3. Merge: Merges the worktree branch into your current branch
4. Clean: Removes worktree directories and deletes merged branches