github / github/spec-kit

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

Fechada
#1,901 3 comentários 0 reações 0 responsáveis Ver no GitHub

Ninguém assumiu esta issue ainda.

stale
Linguagem predominante
Python
Estrelas
138k
Forks
12.4k
Merge médio
2d 13h
PRs com merge (30d)
154

Descrição

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 <agent>/**.

The simplest implementation is a built-in allowlist in check_feature_branch():

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:

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

Guia de contribuição

Abrir o guia de contribuição

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Direção de pesquisa

Comece localizando e lendo check_feature_branch(); em seguida, acompanhe como specify doctor, specify tasks e specify implement resolvem branches e caminhos de spec. Compare as propostas integradas e orientadas por configuração e verifique se os prefixos de agente listados passam pela validação, se a configuração é reportada por specify doctor e se os comandos relacionados funcionam nesses branches.

Escrita pelo modelo de indexação a partir do texto da issue.

Avaliação

Stack de tecnologia
shell
Domínio
cli, developer-experience, tooling
Tipo de issue
Funcionalidade
Dificuldade
4/5
Tempo estimado
3-5 dias
Status de atividade
Estagnada
Clareza
Razoavelmente clara
Facilidade para iniciantes
45/100

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.