Project Kanban Worktrees

Project-linked kanban worktrees and branch names.

Skill metadata

Source	Bundled (installed by default)
Path	skills/software-development/project-kanban-worktrees
Version	1.0.0
Author	VibeOS
License	MIT
Platforms	linux, macos
Tags	kanban, project, worktree, branch, git
Related skills	git-local-workflow, github-pr-workflow

Reference: full SKILL.md

info

The following is the complete skill definition that VibeOS loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.

Project Kanban Worktrees

Use this when creating kanban tasks that should land in a git worktree under a first-class VibeOS project. The kernel already picks a deterministic branch (<project-slug>/<task-id>[-<title>]) and worktree path (<primary-repo>/.worktrees/<task-id>) when the task is linked to a project.

Do not invent random wt/<id> branch names when a project is bound.

When to Use

• User wants parallel agent work on a repo via kanban + worktrees
• Binding a project to a kanban board (bind-board)
• Creating tasks that should open a PR from a stable branch name
• Explaining why a worker cwd is under .worktrees/

Prerequisites

• Git repo as the project's primary folder
• Project registered: vibeos project create … / /projects in TUI
• Board bound (optional but recommended): vibeos project bind-board <project> <board-slug>

How to Run

1. Ensure the project exists and primary path is a git repo:

vibeos project show <slug>
vibeos project check <slug>

2. Bind the board (sets board default_workdir to the primary when possible):

vibeos project bind-board <slug> <board>

3. Create a worktree-backed task (project link + worktree):

vibeos kanban create "Add login form" \
  --assignee coder \
  --workspace worktree \
  --board <board>

If the board's default workdir / project link is set, the dispatcher creates:

Artifact	Shape
Branch	<project-slug>/<task-id>-<title-slug>
Worktree dir	<primary>/.worktrees/<task-id>

Preview a branch name without creating a task:

vibeos project branch-name <slug> t_example --title "Add login form"

4. After the worker finishes, use git-local-workflow then github-pr-workflow if a PR is requested. Do not push unless asked.

Quick Reference

Goal	Command
List projects / missing folders	vibeos project list / check
Switch project in TUI	/projects
Bind board	vibeos project bind-board <proj> <board>
Worktree task	vibeos kanban create … --workspace worktree
Preview branch	vibeos project branch-name <proj> <task-id> [--title …]
Explicit branch override	--workspace worktree --branch <name>

Procedure

1. Confirm primary repo exists on disk (project check).
2. Bind board if kanban should inherit the repo as default workdir.
3. Create tasks with --workspace worktree (not bare scratch) for code work.
4. Prefer letting the kernel name the branch via branch_name_for — only pass --branch when the user asked for a specific name.
5. Keep tenants separate from branch naming: use --tenant for client isolation; branch names stay project-scoped.

Pitfalls

• --branch is only valid with --workspace worktree.
• Relative dir: workspaces are rejected — use absolute paths.
• Missing primary folder: activation still works in /projects, but cwd/worktree setup fails until the path is mounted or re-added.
• Scratch workspaces are deleted on task completion — do not use them for code that must survive for a PR.

Verification

vibeos project branch-name demo t_abcd --title "ship it"
# → demo/t_abcd-ship-it

vibeos kanban show <task-id>
# workspace_kind=worktree, branch_name=<project-slug>/…