From 62ce8863986b1b695778bd4fc44ed4d8cc7542ba Mon Sep 17 00:00:00 2001 From: AnExiledDev Date: Tue, 24 Feb 2026 23:12:48 +0000 Subject: [PATCH 1/2] Add worktree skill for git worktree lifecycle guidance New skill-engine skill covering EnterWorktree, --worktree CLI flag, .worktreeinclude setup, worktree management, and CodeForge integration. Updates system prompt to recommend native Claude Code convention alongside legacy .worktrees/ path. --- .devcontainer/CHANGELOG.md | 6 + .devcontainer/CLAUDE.md | 2 +- .devcontainer/README.md | 2 +- .../config/defaults/main-system-prompt.md | 20 +- .devcontainer/docs/plugins.md | 6 +- .../skill-engine/.claude-plugin/plugin.json | 2 +- .../plugins/skill-engine/README.md | 8 +- .../skill-engine/scripts/skill-suggester.py | 15 ++ .../skill-engine/skills/worktree/SKILL.md | 227 +++++++++++++++++ .../references/manual-worktree-commands.md | 238 ++++++++++++++++++ .../references/parallel-workflow-patterns.md | 228 +++++++++++++++++ README.md | 4 +- docs/src/components/Hero.astro | 2 +- docs/src/content/docs/features/skills.md | 12 +- .../docs/getting-started/first-session.md | 5 + docs/src/content/docs/plugins/index.md | 2 +- docs/src/content/docs/plugins/skill-engine.md | 4 +- .../content/docs/reference/architecture.md | 2 +- 18 files changed, 761 insertions(+), 24 deletions(-) create mode 100644 .devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/worktree/SKILL.md create mode 100644 .devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/worktree/references/manual-worktree-commands.md create mode 100644 .devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/worktree/references/parallel-workflow-patterns.md diff --git a/.devcontainer/CHANGELOG.md b/.devcontainer/CHANGELOG.md index 8e779af..416a6eb 100644 --- a/.devcontainer/CHANGELOG.md +++ b/.devcontainer/CHANGELOG.md @@ -7,6 +7,12 @@ #### 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. + +#### System Prompt +- **`` section** — Updated to document Claude Code native worktree convention (`/.claude/worktrees/`) as the recommended approach alongside the legacy `.worktrees/` convention. Added `EnterWorktree` tool guidance, `.worktreeinclude` file documentation, and path convention comparison table. + ### Changed #### Configuration diff --git a/.devcontainer/CLAUDE.md b/.devcontainer/CLAUDE.md index 59a4c52..7be0807 100644 --- a/.devcontainer/CLAUDE.md +++ b/.devcontainer/CLAUDE.md @@ -52,7 +52,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 diff --git a/.devcontainer/README.md b/.devcontainer/README.md index c7c45d2..15fc97d 100644 --- a/.devcontainer/README.md +++ b/.devcontainer/README.md @@ -344,7 +344,7 @@ 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: diff --git a/.devcontainer/config/defaults/main-system-prompt.md b/.devcontainer/config/defaults/main-system-prompt.md index 56ae9be..92cf373 100755 --- a/.devcontainer/config/defaults/main-system-prompt.md +++ b/.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 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 `/.claude/worktrees//` with branch `worktree-`. Auto-cleaned if no changes. +- **New session:** `claude --worktree ` 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/ +git worktree add /workspaces/projects/.worktrees/ -b ``` +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 ` — 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):** `/.claude/worktrees//` — 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 diff --git a/.devcontainer/docs/plugins.md b/.devcontainer/docs/plugins.md index 71218cb..74fe627 100644 --- a/.devcontainer/docs/plugins.md +++ b/.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. diff --git a/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/.claude-plugin/plugin.json b/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/.claude-plugin/plugin.json index e23ce21..d9e488d 100644 --- a/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/.claude-plugin/plugin.json +++ b/.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" } diff --git a/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/README.md b/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/README.md index cc3a2ab..a142e0c 100644 --- a/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/README.md +++ b/.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 ``` diff --git a/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/scripts/skill-suggester.py b/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/scripts/skill-suggester.py index 8ad1efd..7363c61 100644 --- a/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/scripts/skill-suggester.py +++ b/.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 diff --git a/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/worktree/SKILL.md b/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/worktree/SKILL.md new file mode 100644 index 0000000..6c75a71 --- /dev/null +++ b/.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 +--- + +# 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: + +``` +EnterWorktree: feature-auth-oauth2 +``` + +**Behavior:** +- Creates worktree at `/.claude/worktrees//` +- Branches from current HEAD +- Auto-names the branch `worktree-` +- 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 `/.claude/worktrees//` 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: + +``` +/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 ` 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)** | `/.claude/worktrees//` | `--worktree` flag, `EnterWorktree` tool | +| **Legacy** | `/.worktrees//` | 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 | diff --git a/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/worktree/references/manual-worktree-commands.md b/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/worktree/references/manual-worktree-commands.md new file mode 100644 index 0000000..0b36ba7 --- /dev/null +++ b/.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 -b + +# Existing branch +git worktree add + +# Detached HEAD at specific commit +git worktree add --detach + +# Track a remote branch +git worktree add --track -b origin/ +``` + +### Common Flags + +| Flag | Purpose | +|------|---------| +| `-b ` | Create and checkout a new branch | +| `-B ` | 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: /.claude/worktrees// +# Branch: worktree- +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/ -b +``` + +**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:** +``` +/workspaces/projects/CodeForge d2ba55e [main] +/workspaces/projects/.worktrees/feature-a abc1234 [feature-a] +/workspaces/projects/.worktrees/bugfix-b def5678 [bugfix-b] locked +``` + +**Porcelain output:** +``` +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 + +# Force remove (discards uncommitted changes) +git worktree remove --force +``` + +**Safety notes:** +- Without `--force`, refuses to remove worktrees with modified or untracked files +- Does NOT delete the branch — use `git branch -d ` 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 + +# Force move (even if locked) +git worktree move --force +``` + +**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" + +# Unlock +git worktree unlock +``` + +--- + +## Worktree `.git` File Anatomy + +The main repository has a `.git` **directory**. Each worktree has a `.git` **file** (not directory) containing a pointer: + +``` +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: '' 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 # remove it +``` + +### "fatal: '' is a missing but locked worktree" + +The worktree directory was deleted but the lock prevents pruning. + +**Fix:** +```bash +git worktree unlock +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). diff --git a/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/worktree/references/parallel-workflow-patterns.md b/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/worktree/references/parallel-workflow-patterns.md new file mode 100644 index 0000000..0902ef2 --- /dev/null +++ b/.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. No merge conflicts during parallel work +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" + } + ] + } + ] + } +} +``` diff --git a/README.md b/README.md index 7fcc455..492e01d 100644 --- a/README.md +++ b/README.md @@ -70,9 +70,9 @@ tree-sitter (JS/TS/Python), ast-grep, Pyright, TypeScript LSP tmux, agent-browser, claude-monitor, ccusage, ccburn, ccstatusline, ast-grep, tree-sitter, lsp-servers, biome, ruff, shfmt, shellcheck, hadolint, dprint, ccms, notify-hook, mcp-qdrant, chromaterm, kitty-terminfo, claude-session-dashboard -### Agents (17) & Skills (34) +### Agents (17) & Skills (35) -The `agent-system` plugin includes 17 specialized agents (architect, explorer, test-writer, security-auditor, etc.). The `skill-engine` plugin provides 21 general coding skills, `spec-workflow` adds 8 spec lifecycle skills, and `ticket-workflow` provides 4 ticket management skills. +The `agent-system` plugin includes 17 specialized agents (architect, explorer, test-writer, security-auditor, etc.). The `skill-engine` plugin provides 22 general coding skills, `spec-workflow` adds 8 spec lifecycle skills, and `ticket-workflow` provides 4 ticket management skills. ## Quick Start diff --git a/docs/src/components/Hero.astro b/docs/src/components/Hero.astro index dfb186a..df89dc8 100644 --- a/docs/src/components/Hero.astro +++ b/docs/src/components/Hero.astro @@ -64,7 +64,7 @@ const _props = Astro.props; 12 Plugins 21 Tools 17 AI Agents - 21 Skills + 22 Skills diff --git a/docs/src/content/docs/features/skills.md b/docs/src/content/docs/features/skills.md index 9b5b040..222be04 100644 --- a/docs/src/content/docs/features/skills.md +++ b/docs/src/content/docs/features/skills.md @@ -1,6 +1,6 @@ --- title: Skills -description: Complete reference for all 21 CodeForge skills — domain knowledge packs for frameworks, patterns, and workflows. +description: Complete reference for all 22 CodeForge skills — domain knowledge packs for frameworks, patterns, and workflows. sidebar: order: 3 --- @@ -211,13 +211,21 @@ Agent team orchestration for parallel workstreams. Guides the creation and coord **Auto-suggested when:** You mention spawning a team, working in parallel, coordinating multiple agents, or splitting work across agents. +### worktree + +Git worktree creation, management, and cleanup for parallel development workflows. Covers the full worktree lifecycle — creating worktrees via `EnterWorktree` or CLI, setting up `.worktreeinclude` for environment files, managing active worktrees, and cleanup. Integrates with CodeForge's Project Manager auto-detection and agent isolation system. + +**Key topics:** `EnterWorktree` tool, `--worktree` CLI flag, `.worktreeinclude` setup, worktree naming conventions, cleanup and merging, agent isolation via `isolation: worktree`, native vs legacy path conventions. + +**Auto-suggested when:** You mention creating a worktree, `EnterWorktree`, git worktree commands, parallel branches, or isolating work. + ## Skill Categories Summary | Category | Skills | Focus | |----------|--------|-------| | **Frameworks** | fastapi, svelte5, pydantic-ai, docker, docker-py, sqlite | Framework-specific patterns and APIs | | **Practices** | testing, debugging, refactoring-patterns, security-checklist, api-design, documentation-patterns, performance-profiling, dependency-management, migration-patterns | Methodologies and established patterns | -| **Claude & CodeForge** | claude-code-headless, claude-agent-sdk, skill-building, git-forensics, specification-writing, ast-grep-patterns, team | Building on and extending the Claude ecosystem | +| **Claude & CodeForge** | claude-code-headless, claude-agent-sdk, skill-building, git-forensics, specification-writing, ast-grep-patterns, team, worktree | Building on and extending the Claude ecosystem | :::note[Skills vs Agents] Skills and agents serve different purposes. An **agent** is a specialized Claude instance with specific tools and constraints — it *does work*. A **skill** is a knowledge pack that *informs work* — it provides the patterns, best practices, and domain knowledge that make an agent (or the main Claude session) more effective. Many agents have associated skills that load automatically when the agent is spawned. diff --git a/docs/src/content/docs/getting-started/first-session.md b/docs/src/content/docs/getting-started/first-session.md index abdbe6d..e693713 100644 --- a/docs/src/content/docs/getting-started/first-session.md +++ b/docs/src/content/docs/getting-started/first-session.md @@ -101,6 +101,11 @@ CodeForge includes **17 specialized agents** and **34 skills** that activate aut - **[Agents](../features/agents/)** — specialized AI personas for architecture, debugging, testing, security, migrations, and more - **[Skills](../features/skills/)** — domain-specific knowledge packs (FastAPI, Docker, Svelte, debugging patterns, etc.) that the skill engine suggests automatically or you invoke with slash commands like `/spec-new` +## Understanding the Status Line + +If your terminal supports it, CodeForge provides a status line that shows session information at a glance. The `ccstatusline` feature adds session metadata to your terminal prompt, so you always know which session you're in and its current state. +>>>>>>> b9f14e6 (Add worktree skill for git worktree lifecycle guidance) + ## Tips for Effective Sessions :::tip[Be specific with requests] diff --git a/docs/src/content/docs/plugins/index.md b/docs/src/content/docs/plugins/index.md index e49a352..f6bd375 100644 --- a/docs/src/content/docs/plugins/index.md +++ b/docs/src/content/docs/plugins/index.md @@ -105,7 +105,7 @@ These plugins deliver the headline features of CodeForge — intelligent delegat | Plugin | What It Does | |--------|-------------| | [Agent System](./agent-system/) | 17 specialized agents with automatic delegation, CWD injection, and read-only enforcement | -| [Skill Engine](./skill-engine/) | 21 domain skills with context-aware auto-suggestion | +| [Skill Engine](./skill-engine/) | 22 domain skills with context-aware auto-suggestion | | [Spec Workflow](./spec-workflow/) | Full specification lifecycle from creation through implementation to as-built closure | | [Ticket Workflow](./ticket-workflow/) | GitHub issue integration with EARS-formatted tickets and automated PR reviews | diff --git a/docs/src/content/docs/plugins/skill-engine.md b/docs/src/content/docs/plugins/skill-engine.md index a4ff6c7..252e0a8 100644 --- a/docs/src/content/docs/plugins/skill-engine.md +++ b/docs/src/content/docs/plugins/skill-engine.md @@ -35,7 +35,7 @@ Skills are designed to be practical, not encyclopedic. A typical skill includes: ## Available Skills -CodeForge ships with 21 skills organized into three categories. +CodeForge ships with 22 skills organized into three categories. ### Frameworks and Libraries @@ -171,7 +171,7 @@ skill-engine/ │ └── SKILL.md ├── debugging/ │ └── SKILL.md - └── ... # 21 skills total + └── ... # 22 skills total ``` ## Related diff --git a/docs/src/content/docs/reference/architecture.md b/docs/src/content/docs/reference/architecture.md index 06fea16..a7a7e71 100644 --- a/docs/src/content/docs/reference/architecture.md +++ b/docs/src/content/docs/reference/architecture.md @@ -146,7 +146,7 @@ CodeForge ships 34 skills across the skill-engine, spec-workflow, ticket-workflo | +-- devs-marketplace/ | +-- plugins/ | +-- agent-system/ # 17 agents + redirection hooks -| +-- skill-engine/ # 21 skills + auto-suggestion +| +-- skill-engine/ # 22 skills + auto-suggestion | +-- spec-workflow/ # 8 spec lifecycle skills | +-- session-context/ # Git state, TODOs, commit reminders | +-- auto-code-quality/ # Format + lint + test at Stop From 5f4c7872fa81d687727017f2e7d75bcf36ddd997 Mon Sep 17 00:00:00 2001 From: AnExiledDev Date: Wed, 25 Feb 2026 05:16:19 +0000 Subject: [PATCH 2/2] Fix 11 CodeRabbit review issues: docs consistency, MD040, missing content MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Move system prompt changelog entry from Added to Changed section - Add Worktrees section to CLAUDE.md matching system prompt guidance - Add language tags to 5 fenced code blocks (MD040) across SKILL.md and manual-worktree-commands.md - Soften absolute merge conflict claim in parallel-workflow-patterns.md - Add EnterWorktree to SKILL.md allowed-tools - Add worktree to README.md skills list (21→22 entries) - Fix stale skill counts: 21→22 in features/index.md, getting-started/index.md, plugins/skill-engine.md (description + table); 34→35 in reference/architecture.md --- .devcontainer/CHANGELOG.md | 4 +-- .devcontainer/CLAUDE.md | 28 +++++++++++++++++++ .devcontainer/README.md | 2 +- .../skill-engine/skills/worktree/SKILL.md | 6 ++-- .../references/manual-worktree-commands.md | 6 ++-- .../references/parallel-workflow-patterns.md | 2 +- .../src/content/docs/getting-started/index.md | 2 +- docs/src/content/docs/plugins/skill-engine.md | 3 +- .../content/docs/reference/architecture.md | 2 +- 9 files changed, 42 insertions(+), 13 deletions(-) diff --git a/.devcontainer/CHANGELOG.md b/.devcontainer/CHANGELOG.md index 416a6eb..43ded81 100644 --- a/.devcontainer/CHANGELOG.md +++ b/.devcontainer/CHANGELOG.md @@ -10,11 +10,11 @@ #### 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 - **`` section** — Updated to document Claude Code native worktree convention (`/.claude/worktrees/`) as the recommended approach alongside the legacy `.worktrees/` convention. Added `EnterWorktree` tool guidance, `.worktreeinclude` file documentation, and path convention comparison table. -### Changed - #### Configuration - Moved `.claude` directory from `/workspaces/.claude` to `~/.claude` (home directory) - Added Docker named volume for persistence across rebuilds (per-instance isolation via `${devcontainerId}`) diff --git a/.devcontainer/CLAUDE.md b/.devcontainer/CLAUDE.md index 7be0807..200e892 100644 --- a/.devcontainer/CLAUDE.md +++ b/.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 `/.claude/worktrees//`, branch `worktree-`, auto-cleaned if no changes +- **New session:** `claude --worktree ` — 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/ -b +``` + +**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 ` | Remove a worktree (destructive — confirm first) | +| `git worktree prune` | Clean up stale references (destructive — confirm first) | + +**Path conventions:** +- **Native:** `/.claude/worktrees//` — 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 | diff --git a/.devcontainer/README.md b/.devcontainer/README.md index 15fc97d..45dfdc1 100644 --- a/.devcontainer/README.md +++ b/.devcontainer/README.md @@ -348,7 +348,7 @@ Agent definitions in `plugins/devs-marketplace/plugins/agent-system/agents/` pro 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 diff --git a/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/worktree/SKILL.md b/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/worktree/SKILL.md index 6c75a71..38cffe6 100644 --- a/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/worktree/SKILL.md +++ b/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/worktree/SKILL.md @@ -10,7 +10,7 @@ description: >- 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 +allowed-tools: Bash, Read, Grep, Glob, EnterWorktree --- # Git Worktrees @@ -36,7 +36,7 @@ Use worktrees when: The fastest way to create a worktree during a Claude Code session. Call `EnterWorktree` with a descriptive name: -``` +```text EnterWorktree: feature-auth-oauth2 ``` @@ -129,7 +129,7 @@ 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] ``` diff --git a/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/worktree/references/manual-worktree-commands.md b/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/worktree/references/manual-worktree-commands.md index 0b36ba7..915173b 100644 --- a/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/worktree/references/manual-worktree-commands.md +++ b/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/worktree/references/manual-worktree-commands.md @@ -72,14 +72,14 @@ 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 @@ -168,7 +168,7 @@ git worktree unlock 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 ``` diff --git a/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/worktree/references/parallel-workflow-patterns.md b/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/worktree/references/parallel-workflow-patterns.md index 0902ef2..9ab420d 100644 --- a/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/worktree/references/parallel-workflow-patterns.md +++ b/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/worktree/references/parallel-workflow-patterns.md @@ -71,7 +71,7 @@ Agents with `isolation: worktree` in their frontmatter (refactorer, test-writer, **Workflow:** 1. Each agent/session works on independent files 2. Changes stay isolated until explicitly merged -3. No merge conflicts during parallel work +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. diff --git a/docs/src/content/docs/getting-started/index.md b/docs/src/content/docs/getting-started/index.md index ff41e9d..54372bf 100644 --- a/docs/src/content/docs/getting-started/index.md +++ b/docs/src/content/docs/getting-started/index.md @@ -42,7 +42,7 @@ If you already have Docker and VS Code installed, you can go from zero to a runn Plugins are the backbone of CodeForge. They hook into Claude Code's lifecycle to enhance, guard, and automate your workflow. Highlights include: - **Agent System** — 17 specialized agents for architecture, debugging, testing, security, and more -- **Skill Engine** — 21 domain-specific knowledge packs covering frameworks, patterns, and workflows +- **Skill Engine** — 22 domain-specific knowledge packs covering frameworks, patterns, and workflows - **Spec Workflow** — specification-driven development with 8 lifecycle skills - **Session Context** — automatic git state injection, TODO harvesting, and commit reminders - **Auto Code Quality** — formatting, linting, and advisory test runs on every change diff --git a/docs/src/content/docs/plugins/skill-engine.md b/docs/src/content/docs/plugins/skill-engine.md index 252e0a8..9ec2c34 100644 --- a/docs/src/content/docs/plugins/skill-engine.md +++ b/docs/src/content/docs/plugins/skill-engine.md @@ -1,6 +1,6 @@ --- title: Skill Engine -description: The skill engine plugin provides 21 domain-specific knowledge packs with automatic suggestion based on conversation context. +description: The skill engine plugin provides 22 domain-specific knowledge packs with automatic suggestion based on conversation context. sidebar: order: 3 --- @@ -78,6 +78,7 @@ Skills for working with Claude Code itself and extending CodeForge. | **git-forensics** | Git history analysis, blame, bisect, pickaxe search, reflog recovery | | **ast-grep-patterns** | AST-grep pattern writing for syntax-aware code search | | **team** | Multi-agent team coordination, task decomposition, parallel workstreams | +| **worktree** | Git worktree lifecycle, EnterWorktree tool, `.worktreeinclude` setup, parallel workflows | :::note[Cross-Plugin Skills] The `specification-writing` skill and the spec lifecycle skills (`spec-new`, `spec-build`, etc.) live in the [Spec Workflow](./spec-workflow/) plugin, not the skill engine. However, the skill-suggester registers keywords for them so they are auto-suggested alongside skill-engine skills. diff --git a/docs/src/content/docs/reference/architecture.md b/docs/src/content/docs/reference/architecture.md index a7a7e71..ec7fe77 100644 --- a/docs/src/content/docs/reference/architecture.md +++ b/docs/src/content/docs/reference/architecture.md @@ -111,7 +111,7 @@ Skills are Markdown knowledge files loaded on demand during a session: 4. The skill content is injected into the conversation context 5. Claude uses the skill knowledge for the current task -CodeForge ships 34 skills across the skill-engine, spec-workflow, ticket-workflow, and agent-system plugins. +CodeForge ships 35 skills across the skill-engine, spec-workflow, ticket-workflow, and agent-system plugins. ## Directory Structure