[Feature]: Allow agent-namespaced branches (`claude/**`, `copilot/**`, etc.) to bypass numeric prefix requirement
- 主要語言
- Python
- 星號
- 137k
- 分支
- 12.3k
- 平均合併
- 2 天 13 小時
- 30 天內合併 PR
- 154
描述
## Background
AI coding agents create branches autonomously when working on tasks. Each major agent has an established convention for its branch names — typically a short agent identifier followed by a slash and a description:
| Agent | Example branch |
|---|---|
| GitHub Copilot | `copilot/fix-login-null-check` |
| Claude Code | `claude/add-user-profile-page` |
| Cursor | `cursor/refactor-auth-module` |
| Windsurf | `windsurf/update-api-client` |
| Gemini CLI | `gemini/improve-test-coverage` |
| Codex | `codex/migrate-to-typescript` |
| Trae | `trae/fix-rendering-bug` |
| Qwen Code | `qwen/add-search-endpoint` |
| opencode | `opencode/cleanup-dependencies` |
| VS Code (generic) | `vscode/implement-dark-mode` |
These names are meaningful and consistent — the agent prefix makes it immediately clear which tool created the branch — but they don't match spec-kit's required `###-description` pattern and are currently rejected by `check_feature_branch()`.
## Problem
When an AI agent creates a branch and then invokes a spec-kit command (e.g. `specify tasks`, `specify implement`), validation fails because the branch name doesn't follow the numeric prefix convention. The agent either has to abandon its natural naming scheme or the workflow silently breaks.
This is becoming more common as teams use AI agents as first-class contributors. Spec-kit is increasingly the workflow layer *inside* an agentic loop, not just a tool used by humans at a terminal.
## Proposal
Recognise agent-namespace branches as inherently valid — no numeric prefix required for branches that match `/**`.
The simplest implementation is a built-in allowlist in `check_feature_branch()`:
```bash
local agent_prefixes=(
"claude/"
"codex/"
"copilot/"
"cursor/"
"gemini/"
"opencode/"
"qwen/"
"trae/"
"vscode/"
"windsurf/"
)
for prefix in "${agent_prefixes[@]}"; do
[[ "$branch" == "$prefix"* ]] && return 0
done
```
A more extensible alternative — consistent with the extension manifest direction — would be a top-level `agent_prefixes` key in `extension.yml` or a dedicated config, allowing new agents to be registered without a spec-kit core change:
```yaml
# .specify/config.yml or extension.yml
agent_branches:
prefixes:
- "claude/"
- "copilot/"
- "cursor/"
# ...
```
Either approach solves the immediate problem; the config-driven approach ages better as the agent landscape continues to evolve.
## Why Not Just Use `###-` Branches
Agents can be instructed to use `###-` naming, but this:
- Requires per-agent prompt customisation to override their default behaviour
- Loses the agent provenance signal in the branch name (useful for auditing and PR review)
- Breaks when agents are updated and revert to their defaults
- Doesn't help in environments where the branch is created by the agent before spec-kit commands are invoked
## Acceptance Criteria
- [ ] Branches matching any built-in agent prefix (`claude/`, `copilot/`, `cursor/`, `gemini/`, `codex/`, `opencode/`, `qwen/`, `trae/`, `vscode/`, `windsurf/`) pass `check_feature_branch()` without a numeric prefix
- [ ] The allowlist is either configurable or clearly documented so teams can add prefixes for internal or emerging agents
- [ ] `specify doctor` reports the active agent prefix configuration
- [ ] The `specify tasks`, `specify implement`, and related commands work correctly on agent-prefixed branches (spec path resolution, branch detection, etc.)
貢獻指南
研究方向
先定位並閱讀 check_feature_branch(),然後追蹤 specify doctor、specify tasks 和 specify implement 如何解析分支與 spec 路徑。比較內建提案與設定驅動的提案,並驗證列出的 agent 前綴能通過驗證、設定會由 specify doctor 回報,以及相關命令能在這些分支上正常運作。
由索引模型根據 Issue 內容生成。
評估
- 技術堆疊
- shell
- 領域
- cli, developer-experience, tooling
- Issue 類型
- 功能
- 難度
- 4/5
- 預估耗時
- 3-5 天
- 活躍度
- 停滯
- 描述清晰度
- 基本清楚
- 新手友好度
- 45/100