Add worktree skill for git worktree lifecycle

.devcontainer/CHANGELOG.md

@@ -7,8 +7,14 @@
 #### Docs
 - **CLAUDE.md** — new "Status Bar Widgets" section documenting widget properties, token color conventions, label fusion pattern, and available widget types
 
+#### Skills
+- **worktree** — New skill for git worktree creation, management, and cleanup. Covers `EnterWorktree` tool, `--worktree` CLI flag, `.worktreeinclude` setup, worktree naming conventions, cleanup lifecycle, and CodeForge integration (Project Manager auto-detection, agent isolation). Includes two reference files: manual worktree commands and parallel workflow patterns.
+
 ### Changed
 
+#### System Prompt
+- **`<git_worktrees>` section** — Updated to document Claude Code native worktree convention (`<repo>/.claude/worktrees/`) as the recommended approach alongside the legacy `.worktrees/` convention. Added `EnterWorktree` tool guidance, `.worktreeinclude` file documentation, and path convention comparison table.
+
 #### Configuration
 - Moved `.claude` directory from `/workspaces/.claude` to `~/.claude` (home directory)
 - Added Docker named volume for persistence across rebuilds (per-instance isolation via `${devcontainerId}`)

.devcontainer/CLAUDE.md

@@ -33,6 +33,34 @@ CodeForge devcontainer for AI-assisted development with Claude Code.
 
 Config files deploy via `file-manifest.json` on every container start. Most deploy to `~/.claude/`; ccstatusline config deploys to `~/.config/ccstatusline/`. Each entry supports `overwrite`: `"if-changed"` (default, sha256), `"always"`, or `"never"`. Supported variables: `${CLAUDE_CONFIG_DIR}`, `${WORKSPACE_ROOT}`, `${HOME}`.
 
+## Worktrees
+
+Git worktrees allow checking out multiple branches simultaneously, each in its own directory.
+
+**Native (recommended for Claude Code sessions):**
+- **In-session:** `EnterWorktree` tool — creates worktree at `<repo>/.claude/worktrees/<name>/`, branch `worktree-<name>`, auto-cleaned if no changes
+- **New session:** `claude --worktree <name>` — starts Claude in its own worktree; combine with `--tmux` for background work
+
+**Manual (legacy convention):**
+```bash
+mkdir -p /workspaces/projects/.worktrees
+git worktree add /workspaces/projects/.worktrees/<branch-name> -b <branch>
+```
+
+**Environment files:** Place a `.worktreeinclude` file at the project root listing `.gitignore`-excluded files to copy into new worktrees (e.g., `.env`). Uses `.gitignore` pattern syntax; only files matching both `.worktreeinclude` and `.gitignore` are copied.
+
+**Management:**
+
+| Command | Purpose |
+|---------|---------|
+| `git worktree list` | Show all active worktrees |
+| `git worktree remove <path>` | Remove a worktree (destructive — confirm first) |
+| `git worktree prune` | Clean up stale references (destructive — confirm first) |
+
+**Path conventions:**
+- **Native:** `<repo>/.claude/worktrees/<name>/` — used by `--worktree` flag and `EnterWorktree`
+- **Legacy:** `.worktrees/` as sibling to the main repo — used for manual `git worktree add` and Project Manager integration
+
 ## Commands
 
 | Command | Purpose |
@@ -52,7 +80,7 @@ Config files deploy via `file-manifest.json` on every container start. Most depl
 Declared in `settings.json` under `enabledPlugins`, auto-activated on start:
 
 - **agent-system** — 17 custom agents + built-in agent redirection
-- **skill-engine** — 21 general coding skills + auto-suggestion
+- **skill-engine** — 22 general coding skills + auto-suggestion
 - **spec-workflow** — 8 spec lifecycle skills + spec-reminder hook
 - **session-context** — Git state injection, TODO harvesting, commit reminders
 - **auto-code-quality** — Auto-format + auto-lint + advisory test runner

.devcontainer/README.md

@@ -344,11 +344,11 @@ Agent definitions in `plugins/devs-marketplace/plugins/agent-system/agents/` pro
 | `statusline-config` | ccstatusline configuration |
 | `test-writer` | Test authoring with pass verification |
 
-### General Skills (21) — `skill-engine` plugin
+### General Skills (22) — `skill-engine` plugin
 
 Skills in `plugins/devs-marketplace/plugins/skill-engine/skills/` provide domain-specific coding references:
 
-`api-design` · `ast-grep-patterns` · `claude-agent-sdk` · `claude-code-headless` · `debugging` · `dependency-management` · `docker` · `docker-py` · `documentation-patterns` · `fastapi` · `git-forensics` · `migration-patterns` · `performance-profiling` · `pydantic-ai` · `refactoring-patterns` · `security-checklist` · `skill-building` · `sqlite` · `svelte5` · `team` · `testing`
+`api-design` · `ast-grep-patterns` · `claude-agent-sdk` · `claude-code-headless` · `debugging` · `dependency-management` · `docker` · `docker-py` · `documentation-patterns` · `fastapi` · `git-forensics` · `migration-patterns` · `performance-profiling` · `pydantic-ai` · `refactoring-patterns` · `security-checklist` · `skill-building` · `sqlite` · `svelte5` · `team` · `testing` · `worktree`
 
 ### Spec Skills (8) — `spec-workflow` plugin
 

.devcontainer/config/defaults/main-system-prompt.md

@@ -338,22 +338,30 @@ When blocked, do not use destructive actions as a shortcut. Investigate before d
 <git_worktrees>
 Git worktrees allow checking out multiple branches simultaneously, each in its own directory.
 
-Layout convention:
-- Worktrees go in a `.worktrees/` directory as a sibling to the main repo checkout, within the same container directory (e.g., `projects/.worktrees/feature-name`)
-- The main repo has a `.git` directory; worktrees have a `.git` file containing `gitdir:` pointing to the main repo's worktree metadata
+Creating worktrees (recommended — use Claude Code native tools):
+- **In-session:** Use `EnterWorktree` tool with a descriptive name. Creates worktree at `<repo>/.claude/worktrees/<name>/` with branch `worktree-<name>`. Auto-cleaned if no changes.
+- **New session:** `claude --worktree <name>` starts Claude in its own worktree. Combine with `--tmux` for background work.
 
-Creating worktrees:
+Creating worktrees (manual):
 ```bash
-# Always create inside .worktrees/
+# Legacy convention — detected by setup-projects.sh
 mkdir -p /workspaces/projects/.worktrees
-git worktree add /workspaces/projects/.worktrees/<branch-name> <branch>
+git worktree add /workspaces/projects/.worktrees/<branch-name> -b <branch>
 ```
 
+Environment files:
+- Place a `.worktreeinclude` file at the project root listing `.gitignore`-excluded files to copy into new worktrees (e.g., `.env`, `.env.local`)
+- Uses `.gitignore` pattern syntax; only files matching both `.worktreeinclude` and `.gitignore` are copied
+
 Managing worktrees:
 - `git worktree list` — show all active worktrees
 - `git worktree remove <path>` — remove a worktree (confirm with user first — destructive)
 - `git worktree prune` — clean up stale worktree references (confirm with user first — destructive)
 
+Path conventions:
+- **Native (recommended):** `<repo>/.claude/worktrees/<name>/` — used by `--worktree` flag and `EnterWorktree`
+- **Legacy:** `.worktrees/` as sibling to the main repo — used for manual `git worktree add` and Project Manager integration
+
 Project detection:
 - Worktrees in `.worktrees/` are auto-detected by `setup-projects.sh` and tagged with both `"git"` and `"worktree"` in Project Manager
 - Each worktree is an independent working directory — workspace-scope-guard treats them as separate project directories

.devcontainer/docs/plugins.md

@@ -16,7 +16,7 @@ plugins/devs-marketplace/
     ├── protected-files-guard/ # Safety: protect sensitive files
     ├── auto-code-quality/     # Batch formatter + linter + advisory test runner
     ├── agent-system/          # 17 custom agents + redirection hooks
-    ├── skill-engine/          # 21 coding skills + auto-suggestion
+    ├── skill-engine/          # 22 coding skills + auto-suggestion
     ├── spec-workflow/         # 8 spec lifecycle skills + spec-reminder
     ├── session-context/       # Git state, TODO harvesting, commit reminders
     └── workspace-scope-guard/ # Workspace scope enforcement
@@ -153,9 +153,9 @@ For detailed agent documentation, see `plugins/devs-marketplace/plugins/agent-sy
 
 ### skill-engine
 
-**Purpose**: 21 domain-specific coding reference skills with auto-suggestion.
+**Purpose**: 22 domain-specific coding reference skills with auto-suggestion.
 
-**Skills**: fastapi, svelte5, docker, docker-py, pydantic-ai, sqlite, testing, debugging, security-checklist, refactoring-patterns, git-forensics, performance-profiling, documentation-patterns, migration-patterns, dependency-management, claude-code-headless, claude-agent-sdk, ast-grep-patterns, api-design, skill-building, team
+**Skills**: fastapi, svelte5, docker, docker-py, pydantic-ai, sqlite, testing, debugging, security-checklist, refactoring-patterns, git-forensics, performance-profiling, documentation-patterns, migration-patterns, dependency-management, claude-code-headless, claude-agent-sdk, ast-grep-patterns, api-design, skill-building, team, worktree
 
 **How it works**: Skills are loaded on demand via the Skill tool. A PreToolUse hook auto-suggests relevant skills based on conversation context.
 

.devcontainer/plugins/devs-marketplace/plugins/skill-engine/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "skill-engine",
-	"description": "21 coding knowledge packs with auto-suggestion for frameworks, tools, and patterns",
+	"description": "22 coding knowledge packs with auto-suggestion for frameworks, tools, and patterns",
 	"author": {
 		"name": "AnExiledDev"
 	}

.devcontainer/plugins/devs-marketplace/plugins/skill-engine/README.md

@@ -1,12 +1,12 @@
 # skill-engine
 
-Claude Code plugin that provides 21 coding knowledge packs (skills) with automatic suggestion based on user prompts. Each skill contains domain-specific instructions and reference material that Claude loads on demand via the `/skill` command.
+Claude Code plugin that provides 22 coding knowledge packs (skills) with automatic suggestion based on user prompts. Each skill contains domain-specific instructions and reference material that Claude loads on demand via the `/skill` command.
 
 ## What It Does
 
 Two capabilities:
 
-1. **Skill library** — 21 skills covering frameworks, tools, and development patterns. Each skill is a structured knowledge pack with a `SKILL.md` entrypoint and `references/` subdirectory containing detailed reference docs.
+1. **Skill library** — 22 skills covering frameworks, tools, and development patterns. Each skill is a structured knowledge pack with a `SKILL.md` entrypoint and `references/` subdirectory containing detailed reference docs.
 
 2. **Auto-suggestion** — A `UserPromptSubmit` hook watches user prompts for keyword matches and suggests relevant skills as context, so Claude can proactively load the right knowledge.
 
@@ -35,6 +35,7 @@ Two capabilities:
 | svelte5 | Runes, reactivity, components, SPA routing, LayerCake |
 | team | Agent team orchestration, parallel workstreams, task coordination |
 | testing | Testing frameworks, FastAPI testing, Svelte testing |
+| worktree | Git worktree lifecycle, EnterWorktree, parallel development |
 
 ### Auto-Suggestion
 
@@ -128,7 +129,7 @@ skill-engine/
 +-- scripts/
 |   +-- skill-suggester.py           # Keyword-based skill auto-suggestion
 +-- skills/
-|   +-- api-design/                  # 21 skill directories
+|   +-- api-design/                  # 22 skill directories
 |   +-- ast-grep-patterns/
 |   +-- claude-agent-sdk/
 |   +-- claude-code-headless/
@@ -149,6 +150,7 @@ skill-engine/
 |   +-- svelte5/
 |   +-- team/
 |   +-- testing/
+|   +-- worktree/
 +-- README.md                        # This file
 ```
 

.devcontainer/plugins/devs-marketplace/plugins/skill-engine/scripts/skill-suggester.py

@@ -415,6 +415,21 @@
         ],
         "terms": ["TeamCreate", "SendMessage"],
     },
+    "worktree": {
+        "phrases": [
+            "create a worktree",
+            "work in a worktree",
+            "git worktree",
+            "worktree",
+            "parallel branches",
+            "isolate my work",
+            "clean up worktrees",
+            "list worktrees",
+            "set up a worktree",
+            "enter worktree",
+        ],
+        "terms": ["worktree", "EnterWorktree", "WorktreeCreate"],
+    },
 }
 
 # Pre-compile term patterns for whole-word matching