# sc-managing-worktrees

Adopt this skill: https://proskills.md/skills/other/randlee-synaptic-canvas-claude-local-backup-20251130130230-skills-managing-workt

Page: https://proskills.md/skills/other/randlee-synaptic-canvas-claude-local-backup-20251130130230-skills-managing-workt
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .claude.local-backup-20251130130230/skills/managing-worktrees/SKILL.md
size: 5378
upstream: https://github.com/randlee/synaptic-canvas/blob/main/.claude.local-backup-20251130130230/skills/managing-worktrees/SKILL.md

```text
---
name: sc-managing-worktrees
description: >
  Create, manage, scan, and clean up git worktrees for parallel development.
  Use when working on multiple branches simultaneously, isolating experiments,
  or when user mentions "worktree", "parallel branches", "feature isolation",
  "branch cleanup", or "worktree status".
---

# Managing Git Worktrees

Use this skill to manage worktrees with a standard structure and tracking. Use the `/sc-git-worktree` command to invoke this skill.

## Agent Delegation

This skill delegates to specialized agents via the **Task tool**:

| Operation | Agent | Returns |
|-----------|-------|---------|
| Create | `sc-worktree-create` | JSON: success, path, branch, tracking_row |
| Scan | `sc-worktree-scan` | JSON: success, worktrees list, recommendations |
| Cleanup | `sc-worktree-cleanup` | JSON: success, branch_deleted, tracking_update |
| Abort | `sc-worktree-abort` | JSON: success, worktree_removed, tracking_update |

To invoke an agent, use the Task tool with:
- Prompt file: `.claude/agents/<agent-name>.md`
- Parameters as documented in each agent's Inputs section

## Standards and paths
- Repo root: current directory.
- Default worktree base: `../synaptic-canvas-worktrees`.
- Worktrees live in `<worktree_base>/<branch>`.
- Tracking document (if used): `<worktree_base>/worktree-tracking.md` must be updated on create/scan/cleanup/abandon. Allow a toggle to disable tracking for repos that don’t use it.
- Naming: worktree directory = branch name; branch naming follows repo policy (e.g., master release; develop/DevBranch integration; feature from integration; hotfix from master; release branches as needed).
- Branch protections/hooks: no direct commits to protected branches; ensure hooks/branch protections are respected across worktrees.
- Cleanliness: worktrees must be removed and tracking updated when work is complete or branch is merged.

## Workflows

### Scaffolding (if missing)
- Ensure base path exists: `<worktree_base>`. If missing, create it.
- If tracking is enabled, ensure tracking doc exists with headers.

### Create worktree (and branch)
1) Inputs: `--branch <name>`, `--base <master|develop|...>`, optional `--path`.
2) Ensure scaffolding/tracking doc exists (if enabled); fetch all: `git fetch --all --prune`.
3) Confirm base branch exists and is up to date.
4) Determine path: default `<worktree_base>/<branch>` (or override).
5) Create branch/worktree:
   - If branch does not yet exist: `git worktree add -b <branch> <path> <base>`.
   - If branch exists: `git worktree add <path> <branch>`.
6) In the new worktree, ensure hooks apply and verify status is clean.
7) If tracking enabled, add/refresh entry in tracking doc (branch, path, base, purpose, owner, created date, status).
8) Agent option: delegate to `sc-worktree-create` agent; it returns structured JSON (tracking row, status).

### Scan/verify worktrees
1) List worktrees: `git worktree list --porcelain`.
2) Cross-check tracking doc (if enabled); flag missing/stale entries or extra rows.
3) For each worktree, check status and merge state:
   - `git -C <path> status --short`
   - `git -C <path> fetch`
   - `git branch --remotes --contains <branch>` to see if merged.
4) Identify issues: untracked changes, diverged branches, merged-but-not-cleaned worktrees, missing tracking entries.
5) Update tracking doc with current state and issues (if enabled); propose cleanup where appropriate.
6) Agent option: delegate to `sc-worktree-scan` agent; it returns structured JSON.

### Clean-up worktree (post-merge or finished work)
1) If `git status` is not clean, stop and request explicit approval/coordination.
2) Ensure all work is committed/pushed or explicitly confirmed to discard.
3) Confirm target branch merged or otherwise approved for removal.
4) Remove worktree: `git worktree remove <path>` (use `--force` only with approval).
5) If merged and no unique commits, delete the branch locally (`git branch -d <branch>`) and remotely (`git push origin --delete <branch>`) by default; only skip if the user explicitly opts out. If the remote branch is already absent, continue without error. If not merged, only delete with explicit approval.
6) If tracking enabled, update tracking doc to remove/mark cleaned with merge SHA/date.
7) Agent option: delegate to `sc-worktree-cleanup` agent; it returns structured JSON.

### Abandon worktree (discard work)
1) If `git status` is not clean, stop and request explicit approval/coordination.
2) Confirm user approval to discard local changes and optionally delete the branch.
2) Remove worktree: `git worktree remove <path>` (force only with approval).
3) If instructed, delete the branch locally (`git branch -D <branch>`) and remotely (`git push origin --delete <branch>`).
4) If tracking enabled, update tracking doc to remove the entry and note abandonment.
5) Agent option: delegate to `sc-worktree-abort` agent; it returns structured JSON.

## Safety and reminders
- Never delete branches or force-remove worktrees without explicit approval.
- Never clean/abandon a worktree with uncommitted changes unless explicitly approved.
- Keep tracking doc in sync on every operation when enabled.
- Respect branch protections and hooks; no direct commits to protected branches.
- Use background agents for long scans/cleanups; keep the main context focused on decisions and summaries.
```

## File: README.md
upstream: https://github.com/randlee/synaptic-canvas/blob/main/README.md

````text
# Synaptic Canvas

[![Build Status](https://github.com/randlee/synaptic-canvas/actions/workflows/tests.yml/badge.svg)](https://github.com/randlee/synaptic-canvas/actions/workflows/tests.yml)
[![License MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Publisher Verified](https://img.shields.io/badge/publisher-verified-brightgreen)](docs/PUBLISHER-VERIFICATION.md)

**A marketplace for Claude Code skills, agents, and commands.**

Discover and install productivity packages for Claude development workflows. Register once, use across all your projects.

---

## 🚀 Quick Start (10 Seconds)

### Add the Marketplace

```bash
/plugin marketplace add randlee/synaptic-canvas
```

### Browse & Install Packages

```bash
# Browse all packages interactively
/plugin

# Or install directly
/plugin install sc-delay-tasks@synaptic-canvas
```

That's it! Commands, agents, and skills are immediately available in Claude Code.

---

## Alternative: Python CLI (Legacy)

For advanced use cases or automation, the Python CLI is still available:

```bash
# Register marketplace
python3 tools/sc-install.py registry add synaptic-canvas \
  https://raw.githubusercontent.com/randlee/synaptic-canvas/main/docs/registries/nuget/registry.json

# Install package
python3 tools/sc-install.py install sc-delay-tasks
```

> **⚠️ Deprecation Notice:** The Python CLI is deprecated and will be removed in v1.0.0. Please use `/plugin` commands.
>
> See [Legacy Installation Guide](docs/LEGACY-INSTALL.md) for details.

---

## 📦 Available Packages

### [sc-delay-tasks](packages/sc-delay-tasks/)
[![Stable](https://img.shields.io/badge/status-stable-green)](packages/sc-delay-tasks/CHANGELOG.md)
[![v1.0.0](https://img.shields.io/badge/version-1.0.0-blue)](packages/sc-delay-tasks/CHANGELOG.md)
[![Tier 0](https://img.shields.io/badge/tier-0-green)](README.md#-package-tiers-explained)
[![MIT License](https://img.shields.io/badge/license-MIT-green)](packages/sc-delay-tasks/LICENSE)

**Polling and delay utilities** — Wait for conditions and check on intervals with minimal overhead.

**Use when you need to:**
- Delay execution before running checks (perfect for CI/CD pipelines)
- Poll on bounded intervals for external system readiness
- Wait for GitHub Actions, PR reviews, or deployment completion

📖 **[Full README](packages/sc-delay-tasks/README.md)** | 💡 **[7 Use Cases](packages/sc-delay-tasks/USE-CASES.md)** | 🔧 **[Troubleshooting](packages/sc-delay-tasks/TROUBLESHOOTING.md)** | 📋 **[Changelog](packages/sc-delay-tasks/CHANGELOG.md)**

---

### [sc-git-worktree](packages/sc-git-worktree/)
[![Stable](https://img.shields.io/badge/status-stable-green)](packages/sc-git-worktree/CHANGELOG.md)
[![v1.0.0](https://img.shields.io/badge/version-1.0.0-blue)](packages/sc-git-worktree/CHANGELOG.md)
[![Tier 1](https://img.shields.io/badge/tier-1-yellow)](README.md#-package-tiers-explained)
[![MIT License](https://img.shields.io/badge/license-MIT-green)](packages/sc-git-worktree/LICENSE)

**Git worktree management** — Manage parallel development with automatic tracking and safety checks.

**Use when you need to:**
- Work on multiple branches simultaneously without context switching
- Isolate experiments in separate worktrees for safety
- Track worktree state across your team
- Clean up old worktrees with built-in safety checks

📖 **[Full README](packages/sc-git-worktree/README.md)** | 💡 **[7 Use Cases](packages/sc-git-worktree/USE-CASES.md)** | 🔧 **[Troubleshooting](packages/sc-git-worktree/TROUBLESHOOTING.md)** | 📋 **[Changelog](packages/sc-git-worktree/CHANGELOG.md)**

---

### [sc-manage](packages/sc-manage/)
[![Beta](https://img.shields.io/badge/status-beta-yellow)](packages/sc-manage/CHANGELOG.md)
[![v0.6.0](https://img.shields.io/badge/version-0.6.0-blue)](packages/sc-manage/CHANGELOG.md)
[![Tier 0](https://img.shields.io/badge/tier-0-green)](README.md#-package-tiers-explained)
[![MIT License](https://img.shields.io/badge/license-MIT-green)](packages/sc-manage/LICENSE)

**Package management** — Discover, install, and manage Synaptic Canvas packages.

**Use when you need to:**
- Discover packages available in the marketplace registry
- List installed packages and check their versions
- Install packages globally or locally in specific repos
- Check package compatibility with your environment

📖 **[Full README](packages/sc-manage/README.md)** | 💡 **[7 Use Cases](packages/sc-manage/USE-CASES.md)** | 🔧 **[Troubleshooting](packages/sc-manage/TROUBLESHOOTING.md)** | 📋 **[Changelog](packages/sc-manage/CHANGELOG.md)**

---

### [sc-repomix-nuget](packages/sc-repomix-nuget/)
[![Beta](https://img.shields.io/badge/status-beta-yellow)](packages/sc-repomix-nuget/CHANGELOG.md)
[![v0.6.0](https://img.shields.io/badge/version-0.6.0-blue)](packages/sc-repomix-nuget/CHANGELOG.md)
[![Tier 2](https://img.shields.io/badge/tier-2-orange)](README.md#-package-tiers-explained)
[![MIT License](https://img.shields.io/badge/license-MIT-green)](packages/sc-repomix-nuget/LICENSE)

**NuGet & C# analysis** — Generate AI-ready context from .NET projects for code review and documentation.

**Use when you need to:**
- Analyze .NET/NuGet projects with AI assistance
- Generate documentation from C# code automatically
- Check framework and dependency compatibility
- Create AI-ready context from large codebases

📖 **[Full README](packages/sc-repomix-nuget/README.md)** | 💡 **[7 Use Cases](packages/sc-repomix-nuget/USE-CASES.md)** | 🔧 **[Troubleshooting](packages/sc-repomix-nuget/TROUBLESHOOTING.md)** | 📋 **[Changelog](packages/sc-repomix-nuget/CHANGELOG.md)**

---

### [sc-github-issue](packages/sc-github-issue/)
[![Beta](https://img.shields.io/badge/status-beta-yellow)](packages/sc-github-issue/CHANGELOG.md)
[![v0.6.0](https://img.shields.io/badge/version-0.6.0-blue)](packages/sc-github-issue/CHANGELOG.md)
[![Tier 2](https://img.shields.io/badge/tier-2-orange)](README.md#-package-tiers-explained)
[![MIT License](https://img.shields.io/badge/license-MIT-green)](packages/sc-github-issue/LICENSE)

**GitHub issue lifecycle management** — List, create, update issues, and implement fixes in isolated worktrees with automated testing and PR creation.

**Use when you need to:**
- List and browse GitHub issues with filtering
- Create and update issues interactively
- Implement bug fixes in isolated worktrees
- Automate testing, commits, and PR creation
- Maintain clean main working directory during fixes

📖 **[Full README](packages/sc-github-issue/README.md)** | 💡 **[10 Use Cases](packages/sc-github-issue/USE-CASES.md)** | 🔧 **[Troubleshooting](packages/sc-github-issue/TROUBLESHOOTING.md)** | 📋 **[Changelog](packages/sc-github-issue/CHANGELOG.md)**

---

### [sc-ai-cli](packages/sc-ai-cli/)
[![Beta](https://img.shields.io/badge/status-beta-yellow)](packages/sc-ai-cli/CHANGELOG.md)
[![v0.12.0](https://img.shields.io/badge/version-0.12.0-blue)](packages/sc-ai-cli/CHANGELOG.md)
[![Tier 1](https://img.shields.io/badge/tier-1-yellow)](README.md#-package-tiers-explained)
[![MIT License](https://img.shields.io/badge/license-MIT-green)](../../LICENSE)

**AI-first CLI design toolkit** — Create, review, and harden JSON-first CLIs with MCP-ready contracts, typed error handling, and simulator-backed testing.

**Use when you need to:**
- Design CLIs whose primary contract is machine consumption, not human prose
- Review existing CLIs against AI-first contract standards (JSON, errors, auditability)
- Build stateful simulators for device, service, or database integrations
- Generate scaffolding for Rust, .NET, or Go CLI projects

📖 **[Full README](packages/sc-ai-cli/README.md)** | 💡 **[7 Use Cases](packages/sc-ai-cli/USE-CASES.md)** | 📋 **[Changelog](packages/sc-ai-cli/CHANGELOG.md)**

---

### [sc-ci-automation](packages/sc-ci-automation/)
[![Beta](https://img.shields.io/badge/status-beta-yellow)](packages/sc-ci-automation/CHANGELOG.md)
[![v0.12.0](https://img.shields.io/badge/version-0.12.0-blue)](packages/sc-ci-automation/CHANGELOG.md)
[![Tier 2](https://img.
````
