hex-worktree

Manage git worktrees for hex feature development with merge order enforcement.

4|Updated Mar 16, 2026
One-click install
npx skills add https://github.com/gaberger/hex --skill hex-worktree
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: hex-worktree
Source: https://github.com/gaberger/hex/tree/main/.claude/skills/hex-worktree
Command: npx skills add https://github.com/gaberger/hex --skill hex-worktree

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Hex feature development uses separate git worktrees per adapter boundary to ensure isolation. This skill automates and manages the full worktree lifecycle—creation, status tracking, merge ordering, and cleanup—so teams can coordinate parallel work without cross-boundary imports.

Core Features & Use Cases

  • Create and initialize per-feature worktrees from a documented workplan.
  • Track status, compare against main, and ensure proper merge order across tiers.
  • Cleanup and remove worktrees when features are merged, with memory state synchronization.

Quick Start

Run hex-worktree setup <feature-name> to create and initialize all worktrees for a feature.

Frequently Asked Questions about hex-worktree

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I manage git worktrees for feature development across multiple adapter boundaries?

Git worktree orchestration coordinates parallel work across adapter boundaries to prevent cross-boundary imports. It automates creation, status tracking, and merge ordering across domain, ports, and integration tiers using a workplan JSON.

How do I set up and initialize per-feature worktrees from a workplan?

Run the setup command with a feature name to create and initialize all worktrees from a documented workplan. This registers the worktrees in memory to track status across tiers throughout the feature lifecycle.

Why should I use isolated worktrees for adapter boundaries instead of a single branch?

Isolated worktrees prevent cross-boundary imports during parallel feature development. Using separate worktrees per adapter boundary enforces proper merge order across tiers, maintaining strict separation between domain, ports, adapters, and integration stages.

Can I track the merge status of feature worktrees against the main branch?

Yes, you can track status and compare worktrees against the main branch. The system registers worktrees in memory and synchronizes memory state during cleanup, ensuring accurate status tracking across all feature lifecycle tiers.

How do I clean up and remove worktrees after a feature is merged?

Cleanup and removal of worktrees happens after features are merged, with automatic memory state synchronization. Stale checks identify outdated worktrees, ensuring tracked status across tiers remains accurate and up to date.

Do I need a workplan JSON to coordinate feature worktree lifecycle stages?

Yes, a workplan JSON coordinates the worktree lifecycle. It supports setup, status, merge, cleanup, list, and stale checks, and optionally integrates with scripts or workflow hooks to enforce merge order across tiers.