github / github/spec-kit

[Feature]: Allow agent-namespaced branches (`claude/**`, `copilot/**`, etc.) to bypass numeric prefix requirement

Đã đóng
#1,901 3 bình luận 0 reaction 0 người được giao Xem trên GitHub
stale
Ngôn ngữ chính
Python
Star
137k
Fork
12.3k
Merge trung bình
2 ngày 12 giờ
Pull request đã merge (30 ngày)
159

Mô tả

## 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.)

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Hướng nghiên cứu

Start by locating and reading check_feature_branch(), then trace how specify doctor, specify tasks, and specify implement resolve branches and spec paths. Compare the built-in and config-driven proposals, and verify that the listed agent prefixes pass validation, configuration is reported by specify doctor, and related commands work on those branches.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
shell
Lĩnh vực
cli, developer-experience, tooling
Loại issue
Tính năng
Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức độ hoạt động
Đình trệ
Độ rõ ràng
Khá rõ ràng
Mức phù hợp với người mới
45/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.