Inicializar issues e projeto para um repositório
Configura as convenções que os outros skills issue-* esperam. Tudo aqui escreve no GitHub (labels, um projeto, um link de repositório): informe o que será criado e obtenha a autorização do usuário primeiro. Nada é enviado para o git.
Pré-requisitos: gh auth status mostra os escopos repo e project (caso contrário, gh auth refresh -s project); jq está instalado.
1. Inspecionar (somente leitura)
REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner); OWNER=${REPO%%/*}
gh label list --repo "$REPO" --limit 100
gh project list --owner "$OWNER"
2. Labels
Crie os labels padrão abaixo (nome|descrição|cor). Adicione os labels de componente específicos do repositório (padrão backend, frontend; remova ou adicione conforme necessário). Deixe os labels padrão do GitHub (enhancement, documentation, ...) intactos, a menos que solicitado.
while IFS='|' read -r n d c; do
gh label create "$n" --repo "$REPO" --description "$d" --color "$c" --force
done <<'EOF'
bug|Algo não está funcionando|d73a4a
feature|Nova funcionalidade voltada ao usuário|a2eeef
tech-debt|Dívida técnica rastreada|fbca04
epic|Esforço multi-issue|5319e7
backend|Backend / serviços|0e8a16
frontend|Frontend / aplicação web|1d76db
performance|Desempenho|fef2c0
security|Segurança|d93f0b
testing|Testes / CI / E2E|c5def5
privacy|Privacidade / LGPD|bfdadc
ai|Tratável por um agente de IA sem intervenção humana|7057ff
needs-context|Tratável por IA assim que uma verificação ou decisão rápida for respondida (também carrega ai)|fbca04
needs-human|Requer um dispositivo, decisão jurídica/de proprietário, acesso externo ou escolha de roadmap|d93f0b
wontfix|Não será trabalhado|ffffff
EOF
gh label list --repo "$REPO" # create é silencioso em caso de sucesso: verifique
3. Quadro
A. Copiar um quadro de referência (campos e visualizações, não itens):
gh project copy <número-fonte> --source-owner <proprietário> --target-owner "$OWNER" --title "<Nome do Repositório>"
B. Do zero:
gh project create --owner "$OWNER" --title "<Nome do Repositório>" --format json -q '.number' # anote como $N
for f in Reach Impact "Confidence (%)" "Effort (days)" RICE; do
gh project field-create "$N" --owner "$OWNER" --name "$f" --data-type NUMBER
done
Um novo quadro já possui um campo Status com Todo, In Progress, Done; isso é suficiente (uma opção Defer pode ser adicionada na interface do quadro).
Em seguida, vincule e verifique:
gh project link "$N" --owner "$OWNER" --repo "$REPO"
# em seguida, siga "Resolver IDs primeiro" em issue-project-fields: ele deve encontrar o quadro e todos os campos
4. Documentar no repositório
Adicione esta seção às instruções do agente do repositório (AGENTS.md, CLAUDE.md ou ambos), preenchendo os placeholders <...> (repositório, URL do quadro e os labels de componente criados no passo 2; se os skills vierem de um plugin, informe e nomeie-o). Faça commit em um branch, não no branch padrão.
## Rastreamento de Trabalho (GitHub Issues)
O backlog está em **GitHub Issues** (`<proprietário/repo>`), rastreado no projeto **<título do quadro>** (<URL do quadro>). A issue é a fonte da verdade para contexto *e* status; refira-se ao trabalho pelo número da issue (`#123`) e pelos labels. Skills de fluxo de trabalho: `issue-search`, `issue-file`, `issue-start`, `issue-pr-refs`, `issue-close-out`, `issue-project-fields`, `issue-score`, `issue-link`, `issue-plan-doc`, `issue-file-found`, `issue-audit-scores`, `issue-project-init` (<de onde vêm>).
### Labels
| Grupo | Labels | Regra |
|---|---|---|
| Tipo | `bug`, `feature`, `tech-debt`, `epic` | Exatamente um por issue |
| Componente | <ex.: `backend`, `frontend`> | Quantos forem aplicáveis |
| Tópico | `performance`, `security`, `testing`, `privacy` | Opcional |
| Roteamento de agente | `ai`, `needs-context`, `needs-human` | Opcional. `ai` = um agente pode fazer sem supervisão; `needs-context` = um agente pode assim que uma pergunta rápida for respondida (também carrega `ai`); `needs-human` = requer um dispositivo, acesso externo ou decisão do proprietário |
### Campos do projeto
| Campo | Valores | Notas |
|---|---|---|
| Status | Todo / In Progress / Done | Definido apenas pelo agente orquestrador |
| Reach | 1–5 | Quantos usuários atinge |
| Impact | 0.5–3 | Tamanho do efeito |
| Confidence (%) | percentual inteiro, ex.: `70` | |
| Effort (days) | número | |
| RICE | `(Reach × Impact × Confidence) / Effort` | Também escrito no corpo como `**Score:** RICE x = (R × I × C%) / Ed` para que a issue seja legível independentemente |
### Corpo da issue e fluxo de trabalho
**O corpo da issue** carrega todo o registro: Descrição, Estado Atual, O Que Precisa Ser Feito, Por Que É Importante, Arquivos Relacionados, estimativa. Vincule trabalhos relacionados com `#n`; expresse ordenação com "bloqueado por" (texto do corpo e a API de dependências, veja `issue-link`). Trabalho grande é uma `epic` cujo plano está no corpo da issue e cujas fatias são sub-issues.
- **Antes de começar:** pesquise primeiro (`issue-search`); reutilize ou estenda em vez de criar duplicatas.
- **Enquanto trabalha:** defina o item como Em Andamento e atribua-o (`issue-start`); nomes de branch carregam o número da issue (`feat/123-descricao-curta`). Bugs e dívida técnica começam com um teste que falha. Registre descobertas não relacionadas como novas issues em vez de expandir o escopo (`issue-file-found`).
- **Finalizando:** toda PR referencia suas issues (`Closes #n` por issue, `Part of #n` para a epic; `issue-pr-refs`); após o merge, defina Status = Done e atualize issues relacionadas (`issue-close-out`).
- `gh` precisa do escopo `project` (`gh auth refresh -s project`). Apenas o agente orquestrador altera o status de issue/projeto; subagentes delegados não criam, editam ou fecham issues.
5. Opcional: semear uma epic
issue-file (tipo epic) → issue-plan-doc → para cada fatia issue-file + issue-link + issue-project-fields + issue-score.
Armadilhas
gh label create,gh project copy|link|item-editsão silenciosos em caso de sucesso: sempre verifique.- Um quadro copiado começa vazio;
item-addé idempotente. - Chamadas REST de sub-issue e dependência usam o ID numérico do banco de dados da issue (veja
issue-link). - Confidence é um percentual inteiro (
70); IDs diferem por quadro, portanto sempre redescubra-os (issue-project-fields).