new-worktree

Creates a git worktree with dependencies, environment files, and a provisioned Convex dev deployment.

Updated Apr 17, 2026
One-click install
npx skills add https://github.com/hpark0011/mirror --skill new-worktree-hpark0011
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: new-worktree
Source: https://github.com/hpark0011/mirror/tree/main/.agents/skills/new-worktree
Command: npx skills add https://github.com/hpark0011/mirror --skill new-worktree-hpark0011

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Setting up an isolated git worktree for parallel feature development normally requires manual steps: creating the branch, installing dependencies, copying environment files, and provisioning a backend deployment. This Skill automates that entire setup in one command. ## Core Features & Use Cases - Three Input Modes: Invoke with no arguments (prompts for scope), a ticket markdown file (derives branch name from its type and title), or free-text requirements (infers prefix from intent). - Branch Naming Conventions: Enforces kebab-case slugs with prefixes like feature-, fix-, refactor-, docs-, chore-, or improvements-, capped at 40 characters. - Full Environment Provisioning: Runs pnpm install, copies apps/mirror/.env.local, provisions an expiring per-worktree Convex dev deployment, syncs secrets, pushes code, seeds demo data, and allowlists the owner's git email. - Use Case: You receive a bug ticket fix-nav-transition.md and want to work on it without disturbing your current checkout. Run the Skill with the ticket path and get a ready-to-use worktree at .worktrees/fix-nav-transition-bug with its own Convex backend. ## Quick Start Ask the AI to create a new worktree for your ticket file or requirement, for example by invoking /new-worktree with a ticket markdown path or a short description of the work.

Frequently Asked Questions about new-worktree

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

FAQPage Schema
How do I create a git worktree for parallel development?▼

Invoke /new-worktree with no arguments, a ticket markdown file, or free-text describing the work. The script creates .worktrees/<branch-name> from main, installs dependencies with pnpm, and provisions a dedicated Convex dev deployment.

How are branch names generated for new worktrees?▼

Branch names use a prefix (feature-, fix-, refactor-, docs-, chore-, or improvements-) plus a 2-4 word kebab-case slug, max 40 characters. Ticket files derive the prefix from their type field; free-text input is classified by intent.

What happens if the worktree or branch already exists?▼

The new-worktree.sh script checks whether the target path under .worktrees/ already exists and exits with an error before making any changes. It bails on its own, so no partial state is created from a duplicate name.

Why does worktree setup fail partway and how do I recover?▼

Failures usually occur during the finalize phase, which runs env coordinates, secrets sync, code push plus seed, and owner allowlist in order. Each phase is individually re-runnable by executing ./scripts/finalize-worktree.sh from inside the worktree.

Does each worktree get its own Convex backend?▼

Yes. The script provisions an expiring per-worktree Convex dev deployment as an empty shell, then finalize-worktree.sh syncs environment variables, pushes code, seeds demo data, and allowlists your git email as owner.