codeforge-dev 1.14.2 → 2.0.0

package/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/worktree/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: worktree
+description: >-
+  Guides git worktree creation, management, and cleanup for parallel
+  development workflows including EnterWorktree usage, .worktreeinclude
+  setup, and worktree lifecycle. USE WHEN the user asks to "create a
+  worktree", "work in a worktree", "set up parallel branches", "isolate
+  my work", "clean up worktrees", "list worktrees", "enter worktree",
+  "worktree include", or works with git worktree commands, EnterWorktree,
+  or parallel development patterns. DO NOT USE for routine git branching
+  or single-branch workflows.
+version: 0.1.0
+allowed-tools: Bash, Read, Grep, Glob, EnterWorktree
+---
+
+# Git Worktrees
+
+## Mental Model
+
+A git worktree is a parallel checkout of the same repository. One `.git` database, multiple working directories, each on a different branch. Think of it as having multiple monitors for code — same project, different contexts, simultaneously active.
+
+The key difference from branches: a branch is a pointer to a commit; a worktree is a full working directory with its own index and working tree. Switching branches requires stashing, committing, or discarding changes. Switching worktrees means walking to a different directory.
+
+Use worktrees when:
+- **Parallel features** — work on two features without context-switching overhead
+- **Safe experimentation** — try a risky refactor without touching the main checkout
+- **Code review** — review a PR in one worktree while continuing work in another
+- **Hotfixes** — address an urgent bug without stashing mid-feature work
+- **Agent isolation** — give Claude Code agents their own working directory to prevent file conflicts
+
+---
+
+## Creating Worktrees
+
+### Primary: EnterWorktree Tool (In-Session)
+
+The fastest way to create a worktree during a Claude Code session. Call `EnterWorktree` with a descriptive name:
+
+```text
+EnterWorktree: feature-auth-oauth2
+```
+
+**Behavior:**
+- Creates worktree at `<repo>/.claude/worktrees/<name>/`
+- Branches from current HEAD
+- Auto-names the branch `worktree-<name>`
+- Session moves into the worktree directory
+- **Auto-cleanup:** If no changes are made, the worktree and branch are removed on session exit. If changes exist, Claude prompts to keep or remove.
+
+### CLI Flag: `--worktree`
+
+Start a new Claude Code session directly in a worktree:
+
+```bash
+# Named worktree
+claude --worktree feature-auth-oauth2
+
+# Auto-generated name
+claude --worktree
+
+# Combined with tmux for background work
+claude --worktree feature-auth-oauth2 --tmux
+```
+
+The worktree is created at `<repo>/.claude/worktrees/<name>/` with the same auto-cleanup behavior as `EnterWorktree`.
+
+### Manual: `git worktree add`
+
+For worktrees outside of Claude Code sessions, or when precise control over path and branch is needed:
+
+```bash
+# Create worktree with new branch
+git worktree add /path/to/worktree -b feature-branch-name
+
+# Create worktree tracking existing branch
+git worktree add /path/to/worktree existing-branch
+```
+
+> **Deep dive:** See `references/manual-worktree-commands.md` for the full command reference with all flags, path conventions, and troubleshooting.
+
+### Naming Conventions
+
+- **Kebab-case, descriptive:** `feature-auth-oauth2`, `bugfix-login-timeout`, `spike-new-db`
+- **Prefix with category:** `feature-`, `bugfix-`, `spike-`, `chore-`
+- **Claude Code auto-naming:** Branches created by `--worktree` or `EnterWorktree` are prefixed `worktree-`
+
+---
+
+## Environment Setup
+
+### `.worktreeinclude` File
+
+New worktrees start with only tracked files. Environment files (`.env`, `.env.local`) are typically `.gitignore`-excluded and will be missing. The `.worktreeinclude` file solves this.
+
+Place at the project root. It lists `.gitignore`-excluded files that should be **copied into every new worktree** automatically:
+
+```gitignore
+.env
+.env.local
+.env.*
+**/.claude/settings.local.json
+```
+
+**Rules:**
+- Uses `.gitignore` pattern syntax
+- Only files matching **both** `.worktreeinclude` and `.gitignore` are copied
+- Tracked files are never duplicated (they come from the checkout itself)
+- Commit `.worktreeinclude` to the repo so the team benefits
+
+**If `.worktreeinclude` doesn't exist:** Copy environment files manually after worktree creation, or create the file first.
+
+### Post-Creation Checklist
+
+After creating a worktree, the working directory needs initialization:
+
+1. **Install dependencies** — `npm install`, `uv sync`, `cargo build`, or whatever the project requires. Worktrees share the git database but not `node_modules/`, `.venv/`, or `target/`.
+2. **Run `/init`** — in a new Claude Code session within the worktree, run `/init` to orient Claude to the worktree context.
+3. **Verify the dev environment** — run the test suite or start the dev server to confirm everything works.
+
+---
+
+## Managing Worktrees
+
+### Listing
+
+```bash
+git worktree list
+```
+
+Output shows each worktree's path, HEAD commit, and branch:
+
+```text
+/workspaces/projects/CodeForge            d2ba55e [main]
+/workspaces/projects/.worktrees/feature-a abc1234 [feature-a]
+```
+
+### Switching Context
+
+Worktrees are directories. To switch context:
+- **Terminal:** Open a new terminal and `cd` to the worktree path
+- **VS Code Project Manager:** Worktrees in `.worktrees/` are auto-detected and tagged `"worktree"` — click to open
+- **Claude Code:** Start a new session with `claude --worktree <name>` or use `EnterWorktree`
+
+### Cleanup
+
+**Claude Code auto-cleanup:**
+- No changes → worktree and branch removed automatically on session exit
+- Changes exist → prompted to keep or remove
+
+**Manual cleanup** (confirm with user first — destructive):
+
+```bash
+# Remove a specific worktree
+git worktree remove /path/to/worktree
+
+# Force remove (discards uncommitted changes)
+git worktree remove --force /path/to/worktree
+
+# Clean up stale worktree references (after manual directory deletion)
+git worktree prune
+```
+
+### Merging Work Back
+
+After completing work in a worktree:
+
+1. **Commit and push** the worktree branch
+2. **Create a PR** from the worktree branch to the target branch
+3. **After merge**, clean up:
+   ```bash
+   git worktree remove /path/to/worktree
+   git branch -d worktree-feature-name  # delete merged branch
+   ```
+
+Alternatively, merge locally:
+```bash
+# From the main checkout
+git merge feature-branch-name
+```
+
+---
+
+## CodeForge Integration
+
+### Project Manager Auto-Detection
+
+The `setup-projects.sh` script scans `.worktrees/` directories at depth 3. Worktrees are detected by checking for a `.git` **file** (not directory) containing a `gitdir:` pointer. Detected worktrees receive both `"git"` and `"worktree"` tags in VS Code Project Manager.
+
+### Agent Isolation
+
+Four CodeForge agents use `isolation: worktree` in their frontmatter — refactorer, test-writer, migrator, and doc-writer. When spawned via the `Task` tool, these agents automatically get their own worktree copy of the repository. The worktree is cleaned up after the agent finishes (removed if no changes; kept if changes exist).
+
+### Workspace Scope Guard
+
+Each worktree is treated as an independent project directory by the workspace-scope-guard plugin. File operations are restricted to the worktree's directory boundary.
+
+### Path Conventions
+
+Two conventions coexist:
+
+| Convention | Path | Used by |
+|-----------|------|---------|
+| **Native (primary)** | `<repo>/.claude/worktrees/<name>/` | `--worktree` flag, `EnterWorktree` tool |
+| **Legacy** | `<container-dir>/.worktrees/<name>/` | Manual `git worktree add`, Project Manager detection |
+
+Native is recommended for Claude Code sessions. Legacy is used for manual worktree management and remains supported by `setup-projects.sh`.
+
+---
+
+## Ambiguity Policy
+
+- Default to `EnterWorktree` for in-session worktree creation.
+- Default to the native path convention unless the user specifies otherwise.
+- When the purpose is unclear, ask: "What will you work on in the worktree?"
+- Default branch base: current branch HEAD, not main/master.
+- Default cleanup: prompt before removing worktrees with uncommitted changes.
+- When `.worktreeinclude` doesn't exist and the project has `.env` files, suggest creating one.
+- For agent work, defer to the `team` skill for orchestration — worktree isolation is automatic for agents that declare it.
+
+---
+
+## Reference Files
+
+| File | Contents |
+|------|----------|
+| `references/manual-worktree-commands.md` | Full `git worktree` command reference with all flags, path conventions, `.git` file anatomy, and troubleshooting |
+| `references/parallel-workflow-patterns.md` | Workflow patterns for multi-worktree development, agent swarms, hooks, and anti-patterns |

package/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/worktree/references/manual-worktree-commands.md

@@ -0,0 +1,238 @@
+# Git Worktree Command Reference
+
+Complete reference for `git worktree` subcommands with flags, path conventions, and troubleshooting.
+
+---
+
+## `git worktree add`
+
+Create a new worktree linked to the current repository.
+
+```bash
+# New branch from HEAD
+git worktree add <path> -b <new-branch>
+
+# Existing branch
+git worktree add <path> <existing-branch>
+
+# Detached HEAD at specific commit
+git worktree add --detach <path> <commit>
+
+# Track a remote branch
+git worktree add <path> --track -b <local-name> origin/<remote-branch>
+```
+
+### Common Flags
+
+| Flag | Purpose |
+|------|---------|
+| `-b <branch>` | Create and checkout a new branch |
+| `-B <branch>` | Create or reset and checkout a branch |
+| `--detach` | Checkout in detached HEAD state |
+| `--track` | Set up tracking for the new branch |
+| `--no-checkout` | Create worktree without checking out files (fast, populate later) |
+| `--lock` | Lock the worktree immediately after creation |
+| `-f` / `--force` | Override safeguards (e.g., allow checking out a branch already in another worktree) |
+| `--orphan` | Create worktree with a new orphan branch (no parent commits) |
+
+### Path Conventions
+
+**Claude Code native convention (recommended for Claude sessions):**
+```bash
+# Automatic — handled by --worktree flag or EnterWorktree
+# Path: <repo>/.claude/worktrees/<name>/
+# Branch: worktree-<name>
+claude --worktree feature-auth
+```
+
+**Legacy CodeForge convention (for manual management):**
+```bash
+# Container directory .worktrees/ sibling to repos
+mkdir -p /workspaces/projects/.worktrees
+git worktree add /workspaces/projects/.worktrees/<name> -b <branch>
+```
+
+**General best practice:**
+- Keep worktrees in a predictable location
+- Use the same naming pattern for worktree directories and branches
+- Add the worktree directory to `.gitignore` if it lives inside the repo
+
+---
+
+## `git worktree list`
+
+Show all worktrees linked to the repository.
+
+```bash
+# Default format
+git worktree list
+
+# Porcelain format (machine-readable)
+git worktree list --porcelain
+```
+
+**Default output:**
+```text
+/workspaces/projects/CodeForge            d2ba55e [main]
+/workspaces/projects/.worktrees/feature-a abc1234 [feature-a]
+/workspaces/projects/.worktrees/bugfix-b  def5678 [bugfix-b] locked
+```
+
+**Porcelain output:**
+```text
+worktree /workspaces/projects/CodeForge
+HEAD d2ba55eabc1234def5678901234567890abcdef
+branch refs/heads/main
+
+worktree /workspaces/projects/.worktrees/feature-a
+HEAD abc1234def5678901234567890abcdef01234567
+branch refs/heads/feature-a
+```
+
+---
+
+## `git worktree remove`
+
+Remove a worktree and its administrative files. **Destructive — confirm before executing.**
+
+```bash
+# Remove (fails if there are uncommitted changes)
+git worktree remove <path>
+
+# Force remove (discards uncommitted changes)
+git worktree remove --force <path>
+```
+
+**Safety notes:**
+- Without `--force`, refuses to remove worktrees with modified or untracked files
+- Does NOT delete the branch — use `git branch -d <branch>` separately
+- The main worktree (the original checkout) cannot be removed
+
+---
+
+## `git worktree prune`
+
+Clean up stale worktree administrative data. Run this when a worktree directory was deleted manually without using `git worktree remove`.
+
+```bash
+# Prune stale references
+git worktree prune
+
+# Dry run — show what would be pruned
+git worktree prune --dry-run
+
+# Verbose — show details
+git worktree prune --verbose
+```
+
+**When to use:**
+- After manually deleting a worktree directory (e.g., `rm -rf`)
+- When `git worktree list` shows a worktree that no longer exists on disk
+- During routine repository maintenance
+
+---
+
+## `git worktree move`
+
+Relocate an existing worktree to a new path.
+
+```bash
+git worktree move <old-path> <new-path>
+
+# Force move (even if locked)
+git worktree move --force <old-path> <new-path>
+```
+
+**Notes:**
+- The main worktree cannot be moved
+- Updates the `.git` file in the worktree and the metadata in the main repo
+- Locked worktrees require `--force`
+
+---
+
+## `git worktree lock` / `unlock`
+
+Prevent a worktree from being pruned (useful for worktrees on removable media or network shares).
+
+```bash
+# Lock with reason
+git worktree lock --reason "on USB drive" <path>
+
+# Unlock
+git worktree unlock <path>
+```
+
+---
+
+## Worktree `.git` File Anatomy
+
+The main repository has a `.git` **directory**. Each worktree has a `.git` **file** (not directory) containing a pointer:
+
+```text
+gitdir: /workspaces/projects/CodeForge/.git/worktrees/feature-a
+```
+
+This pointer tells git where the worktree metadata is stored within the main repository's `.git/worktrees/` directory. The metadata includes:
+- `HEAD` — current commit reference
+- `commondir` — path back to the shared `.git` directory
+- `gitdir` — path to the worktree's working directory
+
+**Detection pattern:** To check if a directory is a worktree (not a standalone repo):
+```bash
+[ -f "$dir/.git" ] && grep -q "gitdir:" "$dir/.git"
+```
+
+---
+
+## Troubleshooting
+
+### "fatal: '<branch>' is already checked out"
+
+A branch can only be checked out in one worktree at a time.
+
+**Fix:** Use a different branch name, or remove the worktree that has it checked out:
+```bash
+git worktree list  # find which worktree has the branch
+git worktree remove <path>  # remove it
+```
+
+### "fatal: '<path>' is a missing but locked worktree"
+
+The worktree directory was deleted but the lock prevents pruning.
+
+**Fix:**
+```bash
+git worktree unlock <path>
+git worktree prune
+```
+
+### Stale worktree references after directory deletion
+
+`git worktree list` shows worktrees that no longer exist on disk.
+
+**Fix:**
+```bash
+git worktree prune --verbose
+```
+
+### Worktree not detected by `setup-projects.sh`
+
+CodeForge auto-detection scans `.worktrees/` directories. Ensure:
+1. The worktree is inside a `.worktrees/` directory
+2. The worktree has a `.git` file with `gitdir:` (not a standalone repo)
+3. Run `check-setup` to re-trigger project detection
+
+### Shared state issues between worktrees
+
+Worktrees share:
+- The `.git` database (commits, branches, refs, stash)
+- Git configuration (`.git/config`)
+- Hooks (`.git/hooks/`)
+
+Worktrees do NOT share:
+- Working tree files
+- Index (staging area)
+- `node_modules/`, `.venv/`, `target/` (dependency directories)
+- `.env` files (unless `.worktreeinclude` copies them)
+
+If one worktree's operations seem to affect another, check for shared state leaks through the `.git` database (e.g., `git stash` is shared across all worktrees).

package/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/worktree/references/parallel-workflow-patterns.md

@@ -0,0 +1,228 @@
+# Parallel Workflow Patterns
+
+Worktree usage patterns for multi-context development, agent orchestration, and lifecycle customization.
+
+---
+
+## Pattern 1: Feature + Review
+
+Work on a feature in one worktree while reviewing a PR in another.
+
+**Setup:**
+```bash
+# Main checkout: feature work
+# New worktree: PR review
+git worktree add /workspaces/projects/.worktrees/review-pr-123 -b review/pr-123
+cd /workspaces/projects/.worktrees/review-pr-123
+git fetch origin pull/123/head:review/pr-123
+git checkout review/pr-123
+```
+
+**Workflow:**
+1. Continue feature work in the main checkout
+2. Switch to the review worktree to read, test, and comment on the PR
+3. No stashing, no context loss
+4. Remove review worktree after PR is merged
+
+**When to use:** Long-running feature work that cannot be interrupted, combined with review responsibilities.
+
+---
+
+## Pattern 2: Safe Experimentation
+
+Try a risky refactor or architectural change without affecting the working checkout.
+
+**Setup:**
+```bash
+claude --worktree spike-new-architecture
+# or
+EnterWorktree: spike-new-architecture
+```
+
+**Workflow:**
+1. Experiment freely in the worktree — break things, try approaches
+2. If the experiment succeeds: commit, create PR
+3. If it fails: exit the session → Claude auto-removes the worktree (no changes kept)
+4. Main checkout is untouched regardless of outcome
+
+**When to use:** Evaluating whether an approach works before committing to it. Especially useful for refactors that touch many files.
+
+---
+
+## Pattern 3: Agent Swarm
+
+Multiple Claude Code sessions working in parallel, each in their own worktree.
+
+**Setup (manual):**
+```bash
+# Terminal 1
+claude --worktree feature-auth --tmux
+
+# Terminal 2
+claude --worktree feature-search --tmux
+
+# Terminal 3
+claude --worktree fix-tests --tmux
+```
+
+**Setup (via agent teams):**
+Agents with `isolation: worktree` in their frontmatter (refactorer, test-writer, migrator, doc-writer) automatically get worktrees when spawned via the `Task` tool. The lead agent coordinates, and each teammate operates in its own isolated copy.
+
+**Workflow:**
+1. Each agent/session works on independent files
+2. Changes stay isolated until explicitly merged
+3. Reduced conflict risk when file ownership is respected
+4. After each session completes, review changes via PR
+
+**When to use:** Large tasks that decompose into independent workstreams. Effective for feature builds, migrations, or test suites where each agent owns a different set of files.
+
+**File ownership rule:** Assign each parallel session/agent to a distinct set of files. Two agents editing the same file causes merge conflicts that are difficult to resolve.
+
+---
+
+## Pattern 4: Hotfix While Mid-Feature
+
+An urgent production bug arrives while deep in unfinished feature work.
+
+**Without worktrees:**
+```bash
+git stash          # hope you remember what's stashed
+git checkout main
+# fix the bug
+git checkout feature-branch
+git stash pop      # hope there are no conflicts
+```
+
+**With worktrees:**
+```bash
+claude --worktree hotfix-critical-bug
+# fix the bug in the worktree, commit, create PR
+# exit → worktree cleaned up
+# continue feature work — never interrupted
+```
+
+**When to use:** Anytime urgent work arrives while mid-task. The worktree avoids the stash-switch-pop dance entirely.
+
+---
+
+## Pattern 5: Long-Running Migration
+
+Incremental migration work spread across multiple sessions.
+
+**Setup:**
+```bash
+git worktree add /workspaces/projects/.worktrees/migrate-v2 -b migrate/v2-upgrade
+```
+
+**Workflow:**
+1. Work on the migration across multiple Claude sessions using `claude --resume`
+2. The worktree persists between sessions (not auto-cleaned because it has changes)
+3. Make incremental commits as milestones are reached
+4. When migration is complete, create PR from the worktree branch
+5. Clean up after merge
+
+**When to use:** Multi-day migrations where the work cannot be completed in a single session. Keep the worktree alive until the migration PR is merged.
+
+---
+
+## Anti-Patterns
+
+### Too Many Worktrees
+
+**Problem:** Five or more active worktrees with partially-complete work scattered across them.
+
+**Consequence:** Cognitive overhead of tracking what's where. Dependency directories (`node_modules/`, `.venv/`) duplicated across worktrees consume disk space.
+
+**Guideline:** Limit to 2-3 active worktrees. Finish and clean up before starting new ones.
+
+### Forgetting Cleanup
+
+**Problem:** Worktrees accumulate after sessions end. `git worktree list` shows stale entries.
+
+**Consequence:** Branch namespace pollution, stale references, wasted disk space.
+
+**Guideline:** Clean up worktrees as part of completing a task. Run `git worktree list` periodically. Use `git worktree prune` for stale references.
+
+### Shared State Leaks
+
+**Problem:** Operations in one worktree unexpectedly affect another.
+
+**Examples:**
+- `git stash` — the stash is shared across all worktrees
+- `git gc` — can repack objects used by other worktrees
+- `.git/config` changes — affect all worktrees
+- Global hooks — run in all worktrees
+
+**Guideline:** Avoid `git stash` in worktree workflows (use commits instead). Be cautious with global git config changes.
+
+### Editing the Same File in Multiple Worktrees
+
+**Problem:** Two worktrees modify the same file independently.
+
+**Consequence:** Merge conflict when integrating changes, requiring manual resolution.
+
+**Guideline:** Assign file ownership. Each worktree/agent edits a distinct set of files. If overlap is unavoidable, coordinate explicitly before merging.
+
+---
+
+## Worktree Lifecycle Hooks
+
+Claude Code provides `WorktreeCreate` and `WorktreeRemove` hooks for customizing worktree lifecycle behavior.
+
+### WorktreeCreate Hook
+
+Fires when a worktree is being created via `--worktree` or `isolation: "worktree"`. **Replaces** the default git worktree behavior entirely.
+
+**Input:**
+```json
+{
+  "session_id": "abc123",
+  "cwd": "/workspaces/projects/CodeForge",
+  "hook_event_name": "WorktreeCreate",
+  "name": "feature-auth"
+}
+```
+
+**Output:** Print the absolute path to the created worktree directory on stdout.
+
+**Use cases:**
+- Custom directory layout (override the default `.claude/worktrees/` path)
+- Non-git VCS (SVN, Mercurial) worktree creation
+- Post-creation setup (install dependencies, copy config files)
+
+### WorktreeRemove Hook
+
+Fires when a worktree is being removed (session exit or subagent finish). Cleanup counterpart to WorktreeCreate.
+
+**Input:**
+```json
+{
+  "session_id": "abc123",
+  "hook_event_name": "WorktreeRemove",
+  "worktree_path": "/workspaces/projects/CodeForge/.claude/worktrees/feature-auth"
+}
+```
+
+**Use cases:**
+- Custom cleanup (remove dependency directories, revoke temporary credentials)
+- Non-git VCS cleanup
+- Logging or notification on worktree removal
+
+**Configuration:** Hooks are defined in `.claude/settings.json` or `.claude/settings.local.json`:
+
+```json
+{
+  "hooks": {
+    "WorktreeCreate": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash /path/to/create-worktree.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```

package/.devcontainer/plugins/devs-marketplace/plugins/ticket-workflow/scripts/ticket-linker.py

@@ -71,7 +71,7 @@ def fetch_ticket(number: int) -> str | None:
 
     try:
         data = json.loads(result.stdout)
-    except (json.JSONDecodeError, ValueError):
+    except json.JSONDecodeError:
         return None
 
     title = data.get("title", "(no title)")
@@ -103,7 +103,7 @@ def main():
 
     try:
         data = json.loads(raw)
-    except (json.JSONDecodeError, ValueError):
+    except json.JSONDecodeError:
         sys.exit(0)
 
     prompt = data.get("prompt", "")