Ctrl K

Tóm tắt nhanh / Lệnh

Bộ Engineer

/ak:worktree

Tách biệt bằng Git worktree

Tạo, kiểm tra và dọn Git worktree tách biệt cho làm feature song song, audit worktree, dọn metadata stale, monorepo và submodule.

Đọc thông tin repo

Nhận dạng tên chính xác

Suy ra loại branch

Tạo slug

Nguyên tắc 01

Bắt đầu bằng cách đọc metadata repo với scripts/worktree.cjs info --json.

Nguyên tắc 02

Dùng --no-prefix khi người dùng đã đưa tên branch hoặc quy ước chính xác.

Nguyên tắc 03

Để root worktree được resolve theo thứ tự cấu hình; chỉ dùng --worktree-root khi thật sự override.

Nguyên tắc 04

Trong monorepo, hỏi hoặc đưa project trước khi tạo worktree.

Nguyên tắc 05

Dựa vào việc copy env template và cài dependency nền trong worktree mới.

Bản đồ thực thi

Các nhánh chính từ đầu vào đến kết quả, bám theo cách command chạy khi dùng thật.

Khởi động

Đầu vào, phạm vi, route

1 Đọc thông tin repo Chạy node scripts/worktree.cjs info --json, rồi đọc loại repo, base branch, project, vị trí/nguồn root, trạng thái dirty và chi tiết dirty.
2 Nhận dạng tên chính xác Nếu người gọi đưa chữ hoa, mã issue, dấu slash hoặc yêu cầu tên branch chính xác, chọn --no-prefix và giữ nguyên làm slug.

Xử lý

Agent / skill thực thi

3 Suy ra loại branch Nếu không, suy ra fix, refactor, docs, test, chore hoặc perf từ mô tả, mặc định dùng prefix feat.
4 Tạo slug Đổi mô tả feature thành kebab-case tối đa 50 ký tự, chỉ bỏ qua bước này khi đã chọn --no-prefix.

Kiểm chứng

Gate, review, xác thực

5 Chọn project monorepo Với monorepo chưa có project được đưa sẵn, hỏi người dùng project path nào sẽ nhận worktree.
6 Chạy tạo worktree Chạy scripts/worktree.cjs create với tham số standalone hoặc monorepo cùng --prefix, --base, --checkout-submodules, --json, --dry-run hoặc override root khi cần.

Đóng

Báo cáo, bàn giao, artifact

7 Cài dependency Trong worktree mới, cài dependency nền theo lockfile hoặc manifest đã phát hiện: bun, pnpm, yarn, npm, poetry, pip, cargo hoặc go.
8 Vận hành worktree Dùng info, list, status, remove và prune để kiểm sức khỏe, chuẩn hóa path, xem độ lệch base branch, remove và dọn metadata stale.

Cú pháp, đối số, subcommand

Cách gọi skill: cú pháp, đối số vị trí, option dùng chung, rồi từng subcommand với cú pháp và kết quả riêng.

Cú pháp

/ak:worktree [feature-description]

hoặc

/ak:worktree [project] [feature]

hoặc

Đối số

[feature-description] Bắt buộc

Mô tả feature

Feature hoặc fix bằng ngôn ngữ tự nhiên cần tách vào worktree mới. Có thể là tên branch chính xác; bỏ qua khi chạy lệnh bảo trì rõ ràng.

/ak:worktree fix checkout retry handling

[project]

Project monorepo

Tên hoặc path project tùy chọn cho monorepo. Dùng để chọn project nhận checkout tách biệt mới.

/ak:worktree web fix checkout redirect

[feature]

Feature trong project

Mô tả feature dùng cùng project monorepo. Skill vẫn suy ra hoặc giữ nguyên tên branch từ giá trị này.

/ak:worktree web fix checkout redirect

Option dùng chung

--prefix <type>

Prefix branch

Override loại branch đã suy ra. Giá trị hợp lệ là feat, fix, refactor, docs, test, chore và perf.

/ak:worktree create login hardening --prefix fix

--base <branch>

Branch nền

Dùng branch đã tồn tại thay cho thứ tự tự phát hiện dev, develop, main rồi master.

/ak:worktree create analytics export --base release/next

--no-prefix

Giữ nguyên tên

Bỏ thêm prefix và giữ nguyên tên branch đã validate, gồm chữ hoa và segment dấu slash an toàn.

/ak:worktree create ND-1377-cleanup-docs --no-prefix

--worktree-root <path>

Root worktree

Override nơi skill này đặt worktree mới sau khi validate path. Không ảnh hưởng worktree do host tạo.

/ak:worktree create billing dashboard --worktree-root ../app-worktrees

--checkout-submodules

Checkout submodule

Chạy khởi tạo submodule recursive trong worktree mới sau khi tạo.

/ak:worktree create sdk update --checkout-submodules

--dry-run

Chỉ preview

Preview create, remove hoặc prune mà không áp dụng thao tác filesystem hay Git đó.

/ak:worktree prune --dry-run

--json

Output có cấu trúc

Trả result và error có cấu trúc cho automation và audit.

/ak:worktree status --json

Subcommand

create Tạo

/ak:worktree create [project] <feature> [--prefix <type>|--no-prefix] [--base <branch>] [--worktree-root <path>] [--checkout-submodules] [--dry-run] [--json]

Tạo hoặc attach branch trong worktree tách biệt mới. Monorepo có thể truyền project trước.

[project]: Tên hoặc path project monorepo tùy chọn.
<feature>: Mô tả feature, slug hoặc tên branch chính xác cần tách.

Kết quả: Path worktree mới, branch, branch nền, nguồn root, env template đã copy, warning và bằng chứng setup dependency nếu có.

/ak:worktree create web fix checkout redirect

info Thông tin

/ak:worktree info [--json]

Đọc loại repository, base phát hiện được, project, root worktree, tên file env và số lượng dirty-state.

Kết quả: Metadata repository để quyết định project, branch, base và vị trí trước khi tạo worktree.

/ak:worktree info --json

list Liệt kê

/ak:worktree list [--json]

Liệt kê record worktree đã chuẩn hóa mà không remove hay thay đổi chúng.

Kết quả: Path, branch và record worktree đã chuẩn hóa để audit hoặc chọn mục.

/ak:worktree list --json

status Trạng thái

/ak:worktree status [--json]

Kiểm sức khỏe worktree, path chuẩn hóa, cờ current/main, dirty state, branch tồn tại, base phát hiện và số ahead/behind.

Kết quả: Sức khỏe checkout hiện tại cùng record worktree chuẩn hóa và chi tiết độ lệch với branch nền.

/ak:worktree status --json

remove Remove

/ak:worktree remove <name-or-path> [--dry-run] [--json]

Force-remove một worktree khớp theo tên hoặc path chính xác, rồi thử xóa branch an toàn.

<name-or-path>: Tên worktree chính xác hoặc path tuyệt đối. Dùng status và dry-run trước vì remove có thể xóa file checkout chưa commit.

Kết quả: Worktree khớp được remove khi không dry-run; branch đã merge có thể được xóa an toàn, branch chưa merge được giữ và báo rõ.

/ak:worktree remove /Users/me/app-worktrees/feat-demo --dry-run

prune Prune

/ak:worktree prune [--dry-run] [--json]

Dọn metadata Git worktree stale. Dùng dry-run trước cho lượt audit.

Kết quả: Entry metadata stale được liệt kê khi preview hoặc bị xóa trong thao tác prune đã xác nhận.

/ak:worktree prune --dry-run

Tính năng đặc biệt

Chế độ giữ nguyên tên

Chọn --no-prefix cho mã kiểu Jira, tên branch có chữ hoa, branch nhiều segment hoặc yêu cầu giữ đúng tên.

Resolve root

Thứ tự vị trí là --worktree-root trên CLI, config project, config user, WORKTREE_ROOT, superproject, monorepo, rồi thư mục sibling.

Prune an toàn

Dùng prune --dry-run làm lượt đầu khi audit metadata worktree stale.

Prompt mẫu

Ví dụ gọi command theo từng flag, subcommand, mode hoặc route dùng được trong workflow thực tế.

Tạo worktree feature Khuyến nghị

/ak:worktree create billing dashboard

Dùng khi:: Cần một worktree tách biệt để phát triển feature song song.
Kết quả:: Đọc thông tin repo, suy ra feat và billing-dashboard, tạo checkout, copy env template rồi cài dependency đã phát hiện.

Giữ nguyên branch

/ak:worktree create ND-1377-cleanup-docs

Dùng khi:: Issue tracker hoặc quy ước team đã đưa sẵn tên branch.
Kết quả:: Chọn --no-prefix, giữ nguyên chữ hoa và ký tự mã issue, rồi tạo worktree mà không thêm prefix feat/fix.

Project monorepo

/ak:worktree create web fix checkout redirect

Dùng khi:: Một project cụ thể trong monorepo cần checkout tách biệt mới.
Kết quả:: Dùng web làm project, suy ra loại branch fix, tạo slug checkout-redirect, rồi tạo và khởi tạo worktree cho project đó.

Kiểm sức khỏe worktree

/ak:worktree status --json

Dùng khi:: Cần audit worktree với path chuẩn hóa hoặc độ lệch base branch.
Kết quả:: Chạy lệnh status, trả về record worktree đã chuẩn hóa, gồm sức khỏe checkout hiện tại và chi tiết độ lệch.

Xem trước dọn stale

/ak:worktree prune --dry-run

Dùng khi:: Metadata worktree có thể stale sau khi dọn branch hoặc thư mục bằng tay.
Kết quả:: Audit metadata stale một cách an toàn trước, báo các entry prune mà chưa xóa, và để quyết định dọn thật được rõ ràng.

Info repo

/ak:worktree info --json

Dùng khi:: Khi cần fact repo và vị trí worktree dạng parse được trước khi tạo checkout.
Kết quả:: Trả repoType, baseBranch, worktreeRoot và dirtyState mà không tạo hoặc xóa worktree.

Liệt kê worktree

/ak:worktree list --json

Dùng khi:: Khi cần mọi path và branch worktree đã đăng ký trong một listing.
Kết quả:: Liệt kê worktree đã đăng ký với path chuẩn hóa và tên branch, không mutate checkout.

Xóa worktree

/ak:worktree remove billing-dashboard

Dùng khi:: Khi worktree feature đã đặt tên cần được xóa sau khi branch xong.
Kết quả:: Xóa checkout worktree đúng tên sau khi xác nhận và không đụng các worktree khác.

Phạm vi xử lý

Đọc thông tin repo
Nhận dạng tên chính xác
Suy ra loại branch
Tạo slug
Chọn project monorepo
Chạy tạo worktree