07f02e77db
New optional command between /ultraresearch-local and /ultraplan-local that matches brief+research against Claude Code features (hooks, subagents, skills, output-styles, MCP, plan-mode, worktrees, background-agents) and produces an architecture note with brief-anchored rationale plus explicit gaps. Added: - commands/ultra-cc-architect-local.md (--project, --fg, --quick, --no-gaps) - agents/architect-orchestrator.md (opus) — 6-phase background orchestrator - agents/feature-matcher.md (sonnet) — fallback-ranked feature proposals - agents/gap-identifier.md (sonnet) — 4 gap classes with issue-ready drafts - agents/architecture-critic.md (sonnet) — hallucination gate as BLOCKER - skills/cc-architect-catalog/ — SKILL.md + 10 seed entries (reference/pattern) Changed (non-breaking): - commands/ultraplan-local.md — auto-discovers architecture/overview.md - agents/planning-orchestrator.md — cross-references cc_features_proposed - plugin.json — 2.1.0 → 2.2.0, description, cc-architecture keyword - CHANGELOG, README, CLAUDE.md (plugin + marketplace root) Pipeline becomes brief → research → architect → plan → execute. Architect is optional; existing project dirs keep working unchanged. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
68 lines
2.6 KiB
Markdown
68 lines
2.6 KiB
Markdown
---
|
|
name: worktrees-reference
|
|
description: CC git worktree integration — isolated repo copies per agent for parallel or destructive work.
|
|
layer: reference
|
|
cc_feature: worktrees
|
|
source: https://docs.claude.com/en/docs/claude-code/worktrees
|
|
concept: git-worktree-isolation
|
|
last_verified: 2026-04-18
|
|
ngram_overlap_score: null
|
|
review_status: approved
|
|
---
|
|
|
|
# Worktrees — Reference
|
|
|
|
Git worktrees let a repo check out multiple branches simultaneously in
|
|
separate directories. Claude Code integrates with worktrees to give
|
|
agents isolated filesystem scopes — one agent's edits cannot clash
|
|
with another's.
|
|
|
|
## How it surfaces in CC
|
|
|
|
- **`isolation: "worktree"` on a subagent call** — the harness creates
|
|
a temporary worktree for the subagent. The subagent runs with its
|
|
cwd set to the worktree. Changes stay there until merged or
|
|
discarded.
|
|
- **`/worktree` skill / command** — interactive tooling for creating,
|
|
listing, and merging worktrees during a session.
|
|
- **Auto-cleanup** — worktrees created by subagents are removed if the
|
|
subagent made no changes. Otherwise the path is returned in the
|
|
result for the caller to review.
|
|
|
|
## Branch semantics
|
|
|
|
- Each worktree checks out a named branch. Two worktrees cannot check
|
|
out the same branch (git's rule).
|
|
- Creating a worktree creates a branch if one does not exist.
|
|
- Deleting a worktree does not delete the branch; use `git branch -d`
|
|
separately if desired.
|
|
|
|
## Use cases
|
|
|
|
- **Parallel exploration** — three subagents trying three approaches,
|
|
each in its own worktree. The parent compares diffs.
|
|
- **Destructive experiments** — upgrade a dependency, run the full
|
|
test suite, measure breakage. Discard the worktree if results are
|
|
bad.
|
|
- **Long-running session without blocking main** — execute a refactor
|
|
in a worktree while continuing other work in the main checkout.
|
|
|
|
## Pitfalls
|
|
|
|
- **Shared state leaks** — node_modules, .env, build artifacts are
|
|
per-worktree but may be symlinked in ways that defeat isolation.
|
|
Verify.
|
|
- **Disk use** — each worktree is a full checkout of the tree. For
|
|
large repos, disk pressure adds up.
|
|
- **Branch proliferation** — agents that create worktrees without
|
|
cleanup leave orphan branches. Prune periodically.
|
|
- **Not a sandbox** — a worktree isolates files, not network or
|
|
processes. A subagent in a worktree can still call the outside
|
|
world.
|
|
|
|
## Composition
|
|
|
|
- Worktrees + background agents: a background agent in a worktree can
|
|
work on a long task while the user continues in the main checkout.
|
|
- Worktrees + subagents + hooks: hooks fire inside the worktree cwd,
|
|
so path-based hooks naturally scope to the isolated work.
|