kworktree

Manages git worktrees and Docker sandboxes via the kinfra CLI.

2|1|Updated Feb 5, 2026
One-click install
npx skills add https://github.com/kpiteira/devops-ai --skill kworktree-kpiteira
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: kworktree
Source: https://github.com/kpiteira/devops-ai/tree/main/skills/kworktree
Command: npx skills add https://github.com/kpiteira/devops-ai --skill kworktree-kpiteira

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Setting up isolated development environments for parallel feature work requires manually coordinating git worktrees, Docker containers, port assignments, and agent sessions. This Skill automates that orchestration through the kinfra CLI so each milestone gets its own worktree, sandbox, and port-isolated services without conflicts. ## Core Features & Use Cases - Worktree Lifecycle Management: Create spec and implementation worktrees with kinfra spec and kinfra impl, list them with kinfra worktrees, and clean up with kinfra done. - Sandbox Provisioning: Start or rebuild Docker sandboxes with slot-based port isolation (actual_port = base_port + slot_id), with automatic secrets reuse and --refresh-secrets handling. - Observability Stack: Manage a shared Jaeger, Grafana, and Prometheus stack and filter traces by slot namespace. - Use Case: Launch an implementation environment for milestone M1 of a wellness-reminders feature with one command, get a worktree plus running sandbox plus an agent session kicked off with /kbuild, then tear everything down after the PR lands. ## Quick Start Ask the assistant to create an implementation worktree and sandbox for a feature milestone using kinfra, for example by requesting to run kinfra impl for wellness-reminders/M1.

Frequently Asked Questions about kworktree

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

FAQPage Schema
How do I create an isolated development environment for a feature milestone?

Run kinfra impl <feature>/<milestone> to create a worktree, claim a sandbox slot, start Docker services, and launch an agent session with /kbuild in one step. Use --no-session to skip the agent session, and always pass --group when sessions are involved.

How do I apply code changes to a running Docker sandbox?

Run kinfra sandbox rebuild from the worktree directory. Source code is copied into images at build time with no hot reload, so rebuild re-provisions files and runs docker compose up --build, while kinfra sandbox start only restarts existing images.

How does kinfra handle ports when multiple sandboxes run at once?

kinfra assigns each sandbox a slot ID and computes actual ports as base_port + slot_id, so sandboxes never collide. Run kinfra status to see the current slot's ports, and never hardcode base ports in application code.

Why does kinfra done fail when removing a worktree?

kinfra done fails when the worktree has uncommitted changes to prevent losing work. Commit or stash the changes first, or pass --force to remove the worktree and its sandbox despite the dirty state.

When are sandbox secrets re-resolved versus reused?

kinfra sandbox start and rebuild reuse the slot's materialised .env.secrets by default. Secrets are re-resolved only when none are materialised, a configured secret name was added or removed, the file is unreadable, or --refresh-secrets is passed.