codeforge-dev 1.14.1 → 2.0.1

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

@@ -165,7 +165,7 @@ Choose the agent whose domain matches the work. **Generalist is a last resort.**
 | `researcher` | Codebase & web research | Read-only |
 | `test-writer` | Write test suites | Read + Write + Bash |
 | `refactorer` | Safe code transformations | Read + Write + Bash |
-| `doc-writer` | README, API docs, docstrings | Read + Write |
+| `documenter` | README, API docs, docstrings | Read + Write |
 | `migrator` | Framework upgrades, version bumps | Read + Write + Bash |
 | `security-auditor` | OWASP audit, secrets scan | Read-only |
 | `git-archaeologist` | Git history investigation | Read-only + Bash |
@@ -198,14 +198,14 @@ Prefix with `agent-system:` when spawning (e.g., `agent-system:test-writer`).
 
 | Purpose | Recommended Team |
 |---------|-----------------|
-| Feature build | `researcher` + `test-writer` + `doc-writer` |
+| Feature build | `researcher` + `test-writer` + `documenter` |
 | Security hardening | `security-auditor` + `dependency-analyst` |
 | Codebase cleanup | `refactorer` + `test-writer` |
 | Migration project | `researcher` + `migrator` |
 | Performance work | `perf-profiler` + `refactorer` |
 | Full-stack feature | `architect` + `generalist` (backend) + `generalist` (frontend) + `test-writer` |
 | Code audit | `security-auditor` + `dependency-analyst` + `perf-profiler` |
-| Documentation sprint | `researcher` + `doc-writer` |
+| Documentation sprint | `researcher` + `documenter` |
 
 ---
 
@@ -230,7 +230,7 @@ Prefix with `agent-system:` when spawning (e.g., `agent-system:test-writer`).
 - **Wait for teammates to finish** — leads sometimes start implementing work that teammates are handling. If you notice this, redirect yourself to monitoring and coordination.
 - **Start with research and review** — for first-time team use, prefer tasks with clear boundaries that don't require code changes: reviewing PRs, researching libraries, investigating bugs.
 - **Monitor and steer** — check progress via `TaskList`, redirect failing approaches, synthesize findings. Unattended teams risk wasted effort.
-- **Avoid file conflicts** — break work so each teammate owns different files. Agents with `isolation: worktree` (test-writer, refactorer, doc-writer, migrator) get automatic file isolation via git worktrees.
+- **Avoid file conflicts** — break work so each teammate owns different files. Agents with `isolation: worktree` (test-writer, refactorer, documenter, migrator) get automatic file isolation via git worktrees.
 
 ---
 

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
+
+Five CodeForge agents use `isolation: worktree` in their frontmatter — refactorer, test-writer, migrator, documenter, and implementer. 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).