worktree-stack-migrate

Migrates and aligns a Docker Compose development stack inside git worktrees.

8|4|Updated Jul 1, 2026
One-click install
npx skills add https://github.com/YuShenLiu06/PCHSystem --skill worktree-stack-migrate-yushenliu06
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: worktree-stack-migrate
Source: https://github.com/YuShenLiu06/PCHSystem/tree/main/.claude/skills/worktree-stack-migrate
Command: npx skills add https://github.com/YuShenLiu06/PCHSystem --skill worktree-stack-migrate-yushenliu06

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Git worktrees isolate directories, but the PCHSystem development stack (postgres, backend, mc-test, Vite frontend) anchors its bind mounts, networks, and .env interpolation to the main repository path, causing port conflicts, token mismatches, and containers reading the wrong source code. This Skill provides decision tables and alignment checklists to run the stack correctly from a worktree. ## Core Features & Use Cases - Strategy Decision Table: Chooses among five migration strategies (override mounts, image rebuild, independent stack, frontend-only, MCDR sync) based on what the worktree changed. - Alignment Checklists: Covers port offsets, token/secret consistency (MCDR_SERVICE_TOKEN, POSTGRES_PASSWORD, JWT_SECRET), and Docker network naming so worktree and main stacks do not collide. - Red-Line Traps: Documents hard constraints such as docker cp writing back to main-repo bind mounts, MCDR reload only reading main-repo plugin paths, and never committing vite.config.ts port changes. - Use Case: You created a worktree to test a backend branch while main has uncommitted WIP; the Skill tells you to write a docker-compose.override.yml in the main repo pointing mounts at the worktree, then verify with docker inspect and curl /healthz. ## Quick Start Ask the assistant to start the PCHSystem backend stack from your current git worktree and align its ports and tokens with the main repository stack.

Frequently Asked Questions about worktree-stack-migrate

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run a Docker Compose stack from a git worktree?

Run docker compose with an explicit project name (-p <feat>) from the worktree root so containers, networks, and volumes are isolated from the main stack. Symlink the main repo's .env for variable interpolation and offset host ports via a docker-compose.override.yml.

Why does my worktree container read the main repository source code?

Compose bind mounts like ./Backend/app:/app/app resolve relative to where compose runs, so a stack started in the main repo mounts main-repo source. Fix it with a docker-compose.override.yml that repoints build context and volumes to the worktree path.

How do I avoid port conflicts between worktree and main Docker stacks?

Offset only the host-to-container port mappings in the worktree's docker-compose.override.yml using ports: !override, for example 127.0.0.1:8002:8000 for backend and 127.0.0.1:5434:5432 for postgres. Container-internal ports stay unchanged.

Why does MCDR plugin reload not show my worktree changes?

The mc-test container mounts the main repository's McdrPlugin/pch_system directory, so !!MCDR plugin reload only reads main-repo files. Sync your worktree changes into the main repo path first, then reload in game.

When should I not use a separate worktree stack?

Skip worktree stack migration for pure documentation or single-file edits that do not touch the running stack, and for normal main-branch development where a plain docker compose up -d in the main repo suffices.