GitHub Issues e tarefas de Project
Você opera issues e itens de GitHub Projects pelo gh CLI, e pelo ghp.py onde o gh não
cobre (sub-issues, blocked-by, campos do Project por nome). Receitas exatas:
gh-recipes — leia a seção da intenção antes de executar.
GHP="<plugin-root>/scripts/ghp.py"
Contexto
- Repo e Project padrão:
.planning/github.json (repo, owner, project.number). Sem ele,
use o repo do diretório (gh repo view) e pergunte o Project só se a intenção precisar.
- Issues publicadas de um roadmap:
.planning/github/<slug>.map.json traduz IDs do roadmap
(F01-E02-FT01) em números (#14) — aceite os dois.
- Pré-requisitos:
gh auth status ok; operações de Project exigem o scope project
(! gh auth refresh -s project).
Mapa de intenção
| Intenção |
Como |
| Criar issue |
gh issue create --repo R --title --body-file --label --assignee --milestone; opcional: adicionar ao Project e setar Status |
| Ver / listar |
gh issue view N --json ... · gh issue list --search "..." |
| Editar |
gh issue edit N (--title, --body-file, --add-label/--remove-label, --add-assignee, --milestone) |
| Comentar |
gh issue comment N --body-file |
| Fechar |
gh issue close N --reason completed|"not planned" --comment "..." |
| Reabrir |
gh issue reopen N --comment "..." |
| Sub-issue |
ghp.py link sub|unsub --repo R --parent P --child C |
| Dependência |
ghp.py link block|unblock --repo R --issue N --blocker M (N fica bloqueada por M) |
| O que bloqueia / o que é bloqueado |
ghp.py deps --repo R --issue N |
| Mover no Project / editar campo |
ghp.py item set --owner O --number P --url URL --field Status --value "Em andamento" |
| Adicionar ao Project |
gh project item-add P --owner O --url URL |
| Arquivar item |
gh project item-archive P --owner O --id ITEM |
| Marcar task do checklist |
editar o corpo da feature trocando - [ ] T0n por - [x] T0n |
| Marcar critério de aceite atendido |
editar o corpo (feature, ou sub-issue da história) trocando - [ ] **CA-0n por - [x] **CA-0n da história US-xx citada; fechar a história só quando todos os CA estiverem marcados |
Regras
- Leitura é livre; escrita tem preview. Antes de qualquer escrita mostre o que muda
(issue, campo, de → para, texto do comentário) e espere um "sim". Um pedido explícito e
inequívoco do usuário para uma operação ("fecha a #12 como concluída") conta como
confirmação dessa operação; lotes sempre pedem confirmação.
- Fechar com contexto. Sempre
--reason e um comentário curto do porquê (o que foi
entregue, PR, ou por que não será feito). Antes de fechar, rode ghp.py deps:
- se a issue tem sub-issues abertas, avise e pergunte se fecha mesmo assim;
- liste as issues que ela bloqueia e que ficam desbloqueadas — ofereça movê-las para
Pronto no Project;
- se todas as irmãs sob o mesmo épico/pai ficaram fechadas, ofereça fechar o pai.
- Status acompanha o estado. Ao fechar como concluída, ofereça mover o item para
Concluído/Done; ao reabrir, para Em andamento/Backlog. Use os nomes de opção que o
Project realmente tem (ghp.py project fields).
- Em lote ("fechar todas as tasks concluídas da FT01", "mover a onda 2 para Pronto"):
resolva a lista (busca
gh issue list ou o mapa do roadmap), mostre a tabela
# · título · de → para, peça confirmação uma vez e execute item a item, relatando falhas
sem abortar o resto.
- Nunca apagar. Nada de
gh issue delete, gh project delete ou item-delete sem pedido
explícito com a palavra "apagar/excluir" — e mesmo assim confirme mostrando o alvo. Prefira
fechar ou arquivar.
- Corpo por arquivo. Textos com várias linhas vão por
--body-file (arquivo temporário
no scratchpad), nunca interpolados na linha de comando.
- Issue gerada por roadmap. Título e corpo são sobrescritos no próximo publish. Para
mudanças duráveis, diga que o lugar é o roadmap; comentários, labels extras, assignees e
Status são seguros.
Resposta
Curta: o que foi feito, com links (#N + URL) e o que mudou no Project. Em lotes, uma tabela
com resultado por item.
Idioma: responda no idioma de .planning/config.json (lang); sem config, no idioma do usuário. Caminhos <plugin-root>/..., references/, scripts/ e templates/ são relativos à raiz do plugin; nomes de ferramentas e a forma de citar comandos dependem do runtime (references/runtime.md).
1---2name: github-issues3description: >4 Cria, atualiza, comenta, fecha e reabre issues do GitHub e gerencia as tarefas de um5 GitHub Project — mover Status, editar campos, sub-issues e dependências "blocked by",6 inclusive em lote. Use quando o usuário disser "criar issue", "abrir uma issue", "fechar a7 issue #12", "reabrir", "comentar na issue", "atribuir para", "mover para Em andamento",8 "marcar como concluída", "bloqueada por", "sub-issue", "o que está bloqueando", "tarefas9 do project", "fechar as tasks da feature", ou citar #123 num repo GitHub. Não use para10 criar um Project novo (skill github-project) nem para publicar um roadmap inteiro11 (skill github-publish).12metadata:13 source: https://skillmd.com/skills/pwdev-solucoes/github-issues14 version: 0.1.015---1617# GitHub Issues e tarefas de Project1819Você opera issues e itens de GitHub Projects pelo `gh` CLI, e pelo `ghp.py` onde o `gh` não20cobre (sub-issues, blocked-by, campos do Project por nome). Receitas exatas:21[gh-recipes](../../references/gh-recipes.md) — leia a seção da intenção antes de executar.2223`GHP="<plugin-root>/scripts/ghp.py"`2425## Contexto26- Repo e Project padrão: `.planning/github.json` (`repo`, `owner`, `project.number`). Sem ele,27 use o repo do diretório (`gh repo view`) e pergunte o Project só se a intenção precisar.28- Issues publicadas de um roadmap: `.planning/github/<slug>.map.json` traduz IDs do roadmap29 (`F01-E02-FT01`) em números (`#14`) — aceite os dois.30- Pré-requisitos: `gh auth status` ok; operações de Project exigem o scope `project`31 (`! gh auth refresh -s project`).3233## Mapa de intenção3435| Intenção | Como |36|---|---|37| Criar issue | `gh issue create --repo R --title --body-file --label --assignee --milestone`; opcional: adicionar ao Project e setar Status |38| Ver / listar | `gh issue view N --json ...` · `gh issue list --search "..."` |39| Editar | `gh issue edit N` (`--title`, `--body-file`, `--add-label`/`--remove-label`, `--add-assignee`, `--milestone`) |40| Comentar | `gh issue comment N --body-file` |41| Fechar | `gh issue close N --reason completed\|"not planned" --comment "..."` |42| Reabrir | `gh issue reopen N --comment "..."` |43| Sub-issue | `ghp.py link sub\|unsub --repo R --parent P --child C` |44| Dependência | `ghp.py link block\|unblock --repo R --issue N --blocker M` (N fica bloqueada por M) |45| O que bloqueia / o que é bloqueado | `ghp.py deps --repo R --issue N` |46| Mover no Project / editar campo | `ghp.py item set --owner O --number P --url URL --field Status --value "Em andamento"` |47| Adicionar ao Project | `gh project item-add P --owner O --url URL` |48| Arquivar item | `gh project item-archive P --owner O --id ITEM` |49| Marcar task do checklist | editar o corpo da feature trocando `- [ ] T0n` por `- [x] T0n` |50| Marcar critério de aceite atendido | editar o corpo (feature, ou sub-issue da história) trocando `- [ ] **CA-0n` por `- [x] **CA-0n` da história `US-xx` citada; fechar a história só quando todos os CA estiverem marcados |5152## Regras53541. **Leitura é livre; escrita tem preview.** Antes de qualquer escrita mostre o que muda55 (issue, campo, de → para, texto do comentário) e espere um "sim". Um pedido explícito e56 inequívoco do usuário para *uma* operação ("fecha a #12 como concluída") conta como57 confirmação dessa operação; lotes sempre pedem confirmação.582. **Fechar com contexto.** Sempre `--reason` e um comentário curto do porquê (o que foi59 entregue, PR, ou por que não será feito). Antes de fechar, rode `ghp.py deps`:60 - se a issue tem sub-issues abertas, avise e pergunte se fecha mesmo assim;61 - liste as issues que ela **bloqueia** e que ficam desbloqueadas — ofereça movê-las para62 `Pronto` no Project;63 - se todas as irmãs sob o mesmo épico/pai ficaram fechadas, ofereça fechar o pai.643. **Status acompanha o estado.** Ao fechar como concluída, ofereça mover o item para65 `Concluído`/`Done`; ao reabrir, para `Em andamento`/`Backlog`. Use os nomes de opção que o66 Project realmente tem (`ghp.py project fields`).674. **Em lote** ("fechar todas as tasks concluídas da FT01", "mover a onda 2 para Pronto"):68 resolva a lista (busca `gh issue list` ou o mapa do roadmap), mostre a tabela69 `# · título · de → para`, peça confirmação uma vez e execute item a item, relatando falhas70 sem abortar o resto.715. **Nunca apagar.** Nada de `gh issue delete`, `gh project delete` ou `item-delete` sem pedido72 explícito com a palavra "apagar/excluir" — e mesmo assim confirme mostrando o alvo. Prefira73 fechar ou arquivar.746. **Corpo por arquivo.** Textos com várias linhas vão por `--body-file` (arquivo temporário75 no scratchpad), nunca interpolados na linha de comando.767. **Issue gerada por roadmap.** Título e corpo são sobrescritos no próximo publish. Para77 mudanças duráveis, diga que o lugar é o roadmap; comentários, labels extras, assignees e78 Status são seguros.7980## Resposta81Curta: o que foi feito, com links (`#N` + URL) e o que mudou no Project. Em lotes, uma tabela82com resultado por item.8384Idioma: responda no idioma de `.planning/config.json` (`lang`); sem config, no idioma do usuário. Caminhos `<plugin-root>/...`, `references/`, `scripts/` e `templates/` são relativos à raiz do plugin; nomes de ferramentas e a forma de citar comandos dependem do runtime (`references/runtime.md`).