# Shared Worktree

> Git worktree setup and management for parallel agent development. Use when working in isolated git worktrees to avoid merge conflicts between Developer and Tech Artist agents. Use when this capability is needed.

- Skill: `tomevault-io/shared-worktree` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/shared-worktree`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/shared-worktree/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/shared-worktree

---


# Worker Worktree Skill

> "Parallel development without conflicts – each agent works in their own worktree."

## Verification Checklist

Before starting work:

- [ ] Worktree exists (`git worktree list` shows your worktree)
- [ ] In worktree directory (`pwd` shows `../{agent}-worktree`)
- [ ] On correct branch (`git branch` shows `{agent}-worktree`)
- [ ] Main branch merged (`git merge origin/main` completed)
- [ ] No merge conflicts (`git status` is clean)
- [ ] Latest changes pulled (`git log` shows recent main commits)

## Quick Reference Commands

| Action               | Command                                                    |
| -------------------- | ---------------------------------------------------------- |
| List worktrees       | `git worktree list`                                        |
| Create worktree      | `git worktree add ../{agent}-worktree -b {agent}-worktree` |
| Remove worktree      | `git worktree remove ../{agent}-worktree`                  |
| Navigate to worktree | `cd ../{agent}-worktree`                                   |
| Merge main           | `git fetch origin main && git merge origin/main`           |
| Push worktree        | `git push origin {agent}-worktree`                         |
| Check current branch | `git branch --show-current`                                |

## Worktree Naming Convention

**MUST follow this pattern:** `{agent}-worktree`

| Agent       | Worktree Name         | Worktree Path            | Branch Name           |
| ----------- | --------------------- | ------------------------ | --------------------- |
| Developer   | `developer-worktree`  | `../developer-worktree`  | `developer-worktree`  |
| Tech Artist | `techartist-worktree` | `../techartist-worktree` | `techartist-worktree` |

## Initial Setup (One-Time Per Agent)

```bash
# Check if worktree already exists
git worktree list

# If NOT in list, create worktree with dedicated branch
git worktree add ../{agent}-worktree -b {agent}-worktree

# Verify creation
git worktree list
```

## Daily Workflow

### Before Starting ANY Task

**⚠️ CRITICAL: You MUST navigate to your worktree BEFORE doing any development work!**

**Why navigate to worktree first?**

- All code/asset edits MUST happen in worktree
- Commits go to worktree branch, NOT main
- QA validates from worktree, then merges to main
- Prevents file conflicts between parallel agents

**Why merge main first?**

- Ensures you have the latest changes from the other agent's work
- Prevents out-of-date code conflicts
- Both agents' work gets integrated through main

## Unit, E2E, and Playwright MCP Testing Protocol

Remember to always run the tests in the target worktree branches for validation

- Move to the target worktree
- Load the correct skills for this scope
- Run validation process
- During validation process, always double check in which port the client is running for proper URL check
- Investigate in case of issues and iterate until fixed

1. Developer in worktree:
   ├── Reads PRD from master (Get-MasterPrdPath)
   ├── Reads messages from CLI --message argument
   ├── Updates PRD status in master (atomic write)
   ├── Writes response file for next agent
   ├── Writes code in worktree
   ├── Commits code to worktree branch
   └── Sends validation_request via response file

2. PM in master:
   ├── Reads PRD (sees worker status updates)
   ├── Reads messages (sees worker messages)
   └── Coordinates everything

3. QA in master:
   ├── Navigates to worktree for testing
   ├── If validation passes: merges to master
   └── If validation fails: sends bug_report via master queue

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/feliperyba) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->