hex-worktree

name	hex-worktree
description	Manage git worktree lifecycle for hex feature development. Use when the user asks to "create worktrees", "setup worktrees", "merge worktrees", "cleanup worktrees", "list worktrees", "worktree status", or "feature branches".

Hex Worktree — Git Worktree Lifecycle for Hex Features

In hex architecture, each adapter boundary gets its own git worktree during feature development. This skill manages the full worktree lifecycle: creation, status tracking, merge ordering, and cleanup.

Why Worktrees?

Hexagonal architecture enforces strict import boundaries between layers. By giving each adapter its own worktree, hex ensures:

• Adapters cannot accidentally import each other (they're in separate directories)
• Parallel development — multiple agents can code different adapters simultaneously
• Clean merge ordering — domain/ports merge first, then adapters, then integration

Parameters

Ask the user for:

• action (required): One of: setup, status, merge, cleanup, list, stale
• feature_name (required for setup/status/merge/cleanup): The feature identifier
• skip_specs (optional, default: false): Bypass specs requirement (emergency hotfixes only)

Action: setup

Create worktrees from an existing workplan.

Prerequisites

1. Behavioral specs must exist at docs/specs/<feature-name>.json (enforced by hex-specs-required hook)
2. Workplan must exist at docs/workplans/feat-<feature-name>.json

Steps

1. Read the workplan:

cat docs/workplans/feat-<feature-name>.json

2. For each step in the workplan, create a worktree:

# Domain/ports changes (Tier 0)
git worktree add ../hex-feat-<feature>-domain feat/<feature>/domain
git worktree add ../hex-feat-<feature>-ports feat/<feature>/ports

# Secondary adapters (Tier 1)
git worktree add ../hex-feat-<feature>-<adapter> feat/<feature>/<adapter>

# Primary adapters (Tier 2)
git worktree add ../hex-feat-<feature>-<adapter> feat/<feature>/<adapter>

# Integration (Tier 5)
git worktree add ../hex-feat-<feature>-integration feat/<feature>/integration

3. Register worktrees in HexFlo memory:

mcp__hex__hex_hexflo_memory_store({
  key: "feature/<feature>/worktrees",
  value: {
    feature: "<feature>",
    worktrees: [
      { branch: "feat/<feature>/domain", path: "../hex-feat-<feature>-domain", tier: 0, status: "active" },
      ...
    ],
    created_at: "ISO timestamp"
  }
})

4. If scripts/feature-workflow.sh exists, prefer using it:

./scripts/feature-workflow.sh setup <feature-name>

Action: status

Show the current state of all worktrees for a feature.

Steps

1. List all worktrees:

git worktree list

2. Filter to the feature's worktrees (branches matching feat/<feature>/)

3. For each worktree, report:

   • Branch name and path
   • Tier (from workplan)
   • Commits ahead of main: git log main..feat/<feature>/<adapter> --oneline
   • Test status: run bun test in the worktree (if requested)
   • Merge readiness: all lower-tier worktrees merged?

4. Cross-reference with HexFlo task status:

mcp__hex__hex_hexflo_task_list()

Action: merge

Merge worktrees in dependency order.

Merge Order (ENFORCED)

Tier 0: domain → ports
Tier 1: secondary adapters (parallel within tier)
Tier 2: primary adapters (parallel within tier)
Tier 3: usecases
Tier 4: composition root
Tier 5: integration tests

Steps

1. Verify merge preconditions for each worktree (hex-merge-validation hook):

   • Tests pass in the worktree
   • All lower-tier worktrees already merged
   • No cross-adapter imports
   • Commit conventions followed

2. Merge in order:

git checkout main
git merge feat/<feature>/domain --no-ff -m "feat(domain): <feature> domain types"
git merge feat/<feature>/ports --no-ff -m "feat(ports): <feature> port contracts"
# ... secondary adapters ...
# ... primary adapters ...
git merge feat/<feature>/integration --no-ff -m "test(<feature>): integration tests"

3. After each merge, run the test suite:

bun run check && bun test

4. If conflicts arise:

   • Resolve manually (adapters should not conflict with each other)
   • Port/domain conflicts indicate a planning error — escalate to planner agent

5. If scripts/feature-workflow.sh exists:

./scripts/feature-workflow.sh merge <feature-name>

Action: cleanup

Remove worktrees and branches after successful merge.

Steps

1. Verify all worktrees are merged:

git branch --merged main | grep "feat/<feature>/"

2. Remove worktrees:

git worktree remove ../hex-feat-<feature>-domain
git worktree remove ../hex-feat-<feature>-ports
# ... all worktrees ...

3. Delete branches:

git branch -d feat/<feature>/domain
git branch -d feat/<feature>/ports
# ... all branches ...

4. Clean up HexFlo memory:

mcp__hex__hex_hexflo_memory_store({
  key: "feature/<feature>/worktrees",
  value: { status: "cleaned", cleaned_at: "ISO timestamp" }
})

5. If scripts/feature-workflow.sh exists:

./scripts/feature-workflow.sh cleanup <feature-name>

Action: list

List all active feature worktrees across all features.

git worktree list

Group by feature name and show tier/status for each.

Action: stale

Find abandoned worktrees (older than 24h with no new commits).

# List worktrees and check last commit date
for wt in $(git worktree list --porcelain | grep "^worktree" | cut -d' ' -f2); do
  last_commit=$(git -C "$wt" log -1 --format="%ci" 2>/dev/null)
  echo "$wt: $last_commit"
done

Flag worktrees with no commits in 24+ hours. Recommend cleanup or reassignment.

Worktree Limits

• Maximum 8 concurrent worktrees per feature (matches max parallel agents)
• Worktrees are created in the parent directory of the project root (../hex-feat-*)
• Each worktree gets a full copy of the repo — disk space scales linearly

Quick Reference

Command	What it does
/hex-worktree setup <feature>	Create worktrees from workplan
/hex-worktree status <feature>	Show worktree status and merge readiness
/hex-worktree merge <feature>	Merge worktrees in dependency order
/hex-worktree cleanup <feature>	Remove worktrees and branches
/hex-worktree list	List all active worktrees
/hex-worktree stale	Find abandoned worktrees