github / github/spec-kit

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

Cerrado
#1,901 3 comentarios 0 reacciones 0 asignados Ver en GitHub
stale
Lenguaje dominante
Python
Estrellas
137k
Forks
12.3k
Merge medio
2 d 12 h
PR fusionados (30 d)
159

Descripción

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

Guía de contribución

Abrir la guía de contribución

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Evaluación

Stack tecnológico
shell
Área
cli, developer-experience, tooling
Tipo de issue
Nueva funcionalidad
Dificultad
4/5
Tiempo estimado
3-5 días
Estado de actividad
Estancado
Claridad
Bastante claro
Aptitud para principiantes
45/100

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.