When the user is on the master branch and raises a requirement that needs code changes, execute the following workflow. This process is adapted to the BlueShield (bk-ci) GitHub Issue-driven development model.
Hard constraint: once the user chooses to create a branch, the Agent is prohibited from making any content modifications to project files during this conversation turn (including writing, editing, and creating files). After the workflow ends, prompt the user to continue operating in the newly opened worktree window. Only when the user explicitly chooses "modify directly on master" should the workflow be skipped and the requirement executed normally.
Fixed parameters
- Repository owner =
TencentBlueKing,repo =bk-ci - Remote =
origin, new branch base =origin/master - Current GitHub user: obtain
get_mevialogin(used for issue assignee) - GitHub MCP server =
user-github
Pre-checks
0. Check the runtime environment
This skill only takes effect in Cursor IDE . If the current environment is not the Cursor IDE (for example, in a CLI, terminal, or other editor), skip this workflow and directly execute the user's requirement.
How to determine: the user information contains Workspace Path and the Shell can execute the cursor --version command.
1. Check the current branch
git branch --show-current
This workflow is triggered only when the current branch is master . If not on master, simply execute the user's requirement directly.
2. Check GitHub MCP availability
Confirm that the user-github MCP server is available. If it is not available, remind the user:
No GitHub MCP service is currently detected. Please first add a GitHub server in Cursor Settings → MCP and retry; or manually provide a branch name and skip the issue association step to create the worktree directly.
If the user does not have GitHub MCP but still wants to create a worktree, skip the issue step and directly have the user manually provide a branch name before executing worktree creation.
Workflow
Step 1: Ask whether to create a branch
Use the AskQuestion tool to confirm with the user:
- Prompt:
当前在 master 分支,需要先创建工作分支再改动代码。如何关联 GitHub Issue? - Options:
关联已有 Issue 建分支(the user must provide the issue number)新建 Issue 后建分支(create an issue in the upstream public repository; requires secondary confirmation)不关联 Issue,直接建分支(the user must provide the branch name)不建分支,直接在 master 上改(continue after giving a risk warning)
Step 2: Determine the associated Issue
A. Associate an existing Issue
After the user provides the issue number, read the title to generate branch keywords:
CallMcpTool:
server: user-github
toolName: issue_read
arguments:
method: get
owner: TencentBlueKing
repo: bk-ci
issue_number: <issue号>
From the response, take title and (if any)labels、issue_type, used to infer the type and extract keywords (see Step 3 "Infer type from Issue").
B. Create a new Issue (upstream public repository; requires secondary confirmation)
Before creating an Issue in the public upstream
TencentBlueKing/bk-ci, you must use AskQuestion to have the user confirm the title/body, and only call the creation interface after confirmation.
Issue title convention (aligned with branch type and commit marker):
- Format:
{type}: {简短描述}(keep one space after the English colon) - type consistent with the branch prefix in Step 3:
| type | Use cases |
|---|---|
feat |
New features, capability enhancements |
bug |
Bug fixes |
pref |
Performance, parameters, configuration optimization |
refactor |
Refactoring (no external behavior changes) |
issue |
Unclear type, miscellaneous tracking |
Example (refer to #13058 type of requirement ticket):
feat: 蓝盾智能助手支持项目级知识库、插件级知识库bug: 流水线构建完成后状态未更新pref: 构建详情页接口减少冗余查询
In the titleDo notwrite the issue number again; the number is assigned by GitHub. The body still uses structures such as Background / Requirements / Acceptance criteria, consistent with the github-repository-management Issue template.
get_meGet the current userlogin, as the assignee.- Select the
typefrom the user requirements according to the table above, and draft thetitle(must include the{type}:prefix) andbody。 - (optional)
list_issue_types(owner=TencentBlueKing) Confirm whether the organization has enabled issue type; if enabled and it corresponds totype, you may passtype(e.g., Feature / Bug); if not enabled, omit it. - Call create:
CallMcpTool:
server: user-github
toolName: issue_write
arguments:
method: create
owner: TencentBlueKing
repo: bk-ci
title: "<type>: <简短描述>"
body: <需求/缺陷描述,含背景、用例、实现要点>
assignees: ["<当前用户 login>"]
From the response, get the new issue's number。
C. Do not link an Issue
Have the user provide the branch name directly, or generate a branch name based on the requirement description (without an issue number suffix), and skip to Step 4.
Step 3: Generate branch name
Branch naming rules:{type}-{issue号} or {type}-{keywords}-{issue号}
Infer type from the Issue (by priority)
- Title prefix: if
titlestarts withfeat:、bug:、pref:、refactor:、issue:(case-insensitive), take the segment before the colon as the type (all lowercase). - GitHub
issue_type: e.g.,Feature→feat,Bug→bug(when consistent with the repository configuration). - labels: e.g.,
kind/bug→bug,kind/enhancement→feat。 - Still cannot determine →
issue。
Extract keywords from the title (optional)
-
Remove the
{type}:prefix, then extract 1–3 English keywords from the remaining title (all lowercase, joined by-); Chinese titles may be translated or abbreviated by meaning (e.g., "Knowledge Base" →knowledge)。 -
Example: title
feat: 蓝盾智能助手支持项目级知识库、插件级知识库,issue#13058→feat-ai-knowledge-13058orfeat-knowledge-13058。 -
issue number: GitHub Issue number (pure digits),mustbe the last segment of the branch name.
Example:
bug: …+#12994→bug-12994feat: …+#11524→feat-11524orfeat-tenant-3-11524- No type prefix, only
issue_typeis the Feature's#13058→feat-knowledge-13058(add keywords based on the title)
You may add 1–3 English keywords between the type and the issue number to improve readability (consistent with the existing
feat-tenant-3-11524、feat-ai-knowledge-13058style). Whether to add keywords is up to your judgment based on the title, but thelast segment must be the issue number, to facilitate parsing by subsequent commit/close skills.
If the user chooses not to link an Issue, have the user provide a branch name or generate one based on the requirement description (the last segment may not contain an issue number).
Step 4: Create the Worktree and create the branch at the same time
First pull the latest code to ensure the branch is created based on the latest master:
git remote set-url origin https://github.com/TencentBlueKing/bk-ci.git
git fetch origin master
Before running the script, first confirm that the target branch name does not already exist locally; this step requirescreating a new branch at the same time as the worktree, and does not reuse an existing local branch. If a branch with the same name already exists locally, prompt the user to rename it, or manually clean up the old branch/old worktree and then retry.
Choose the script according to the operating system,Specify the baseline origin/master:
Windows(PowerShell):
powershell -File .cursor/skills/github-worktree/scripts/git-worktree.ps1 -Action Add -Branch "<分支名>" -Base origin/master
macOS / Linux(Bash):
bash .cursor/skills/github-worktree/scripts/git-worktree.sh add -b "<分支名>" -B origin/master
The script will explicitly execute "based on origin/master create a new branch + create a worktree; after success, it automatically syncs from the main repository .idea and .cursor to the new worktree, ensuring that the IDEA project configuration, Gradle import configuration, local run configuration, and the Cursor rules/skills/config under the current project are kept as consistent as possible with the main repository window.
The script then enters the new worktree's src/backend/ciand executes for all modules using task-gen-jooq the jOOQ generation task. If the database is inaccessible or jOOQ generation fails, the script exits with failure, and the database connection or generation error must be resolved first.
Operating system detection
- In the user information,
OS Versioncontains win32 → use the PowerShell scriptwin32→ Use PowerShell script - contains darwin → use the Bash script
darwin→ Use Bash script - contains linux → use the Bash script
linux→ Use Bash script
Step 5: Open the Worktree in a new window
Extract from the Step 4 script output Created worktree: <path> the actual path (do not construct the path yourself).
Use the following command to open it in a new Cursor window:
cursor --new-window "<从脚本输出中提取的 worktree 路径>"
Inform the user that the new window has been opened and that development can continue in the new window.This conversation ends here; do not make any further modifications to any files.
Script description
| Script | System | Path |
|---|---|---|
| git-worktree.ps1 | Windows | .cursor/skills/github-worktree/scripts/git-worktree.ps1 |
| git-worktree.sh | macOS/Linux | .cursor/skills/github-worktree/scripts/git-worktree.sh |
The two scripts have identical functionality and support three operations:
- add: based on the base specified by
-B/-Basesimultaneously create a new branch and worktree; if a branch with the same name already exists locally, fail directly to avoid mistakenly reusing an old branch - list: list all worktrees
- remove: remove a worktree (supports by branch name or path)