---
name: repo-manager
description: >
  Gerenciamento padronizado de repositorios GitHub — issues, milestones, pull requests, labels,
  branch protection e templates. Use SEMPRE que o usuario pedir para: criar ou gerenciar issues,
  criar ou acompanhar milestones, abrir ou revisar pull requests, configurar labels, proteger
  branches, inicializar um repo com boas praticas, fazer merge, fechar issues, ou qualquer
  tarefa de project management no GitHub. Tambem acione quando o usuario mencionar "setup do repo",
  "organizar o projeto", "criar backlog", "planejar sprint", "preparar release", ou pedir
  qualquer operacao com `gh` relacionada a gestao do repositorio.
---

# Repo Manager — Padrao Global de Gerenciamento GitHub

Esta skill define o padrao que TODOS os projetos devem seguir para gerenciamento no GitHub.
Todas as boas praticas descritas aqui sao o PADRAO — aplique-as automaticamente em toda
operacao, sem que o usuario precise pedir. O usuario nunca deveria dizer "com boas praticas"
porque esse e o unico modo de operar.

Todas as operacoes usam o GitHub CLI (`gh`). Antes de executar qualquer comando, confirme
que o usuario esta autenticado (`gh auth status`).

---

## Comportamento Padrao (aplique SEMPRE, automaticamente)

Toda vez que executar qualquer operacao nesta skill, aplique estas regras por padrao:

- **Criar issue** → incluir labels (`type:` + `priority:`), milestone ativo, descricao com criterios de aceite
- **Criar PR** → titulo com conventional commits, body com template (Summary/Changes/Test Plan), linkar issue com `Closes #N`, atribuir reviewer
- **Merge PR** → somente apos aprovacao; usar squash merge; deletar branch apos merge
- **Criar milestone** → incluir descricao e data de vencimento
- **Setup de repo** → labels + milestone + branch protection + templates, tudo de uma vez
- **Criar branch** → usar prefixo correto (`feature/`, `fix/`, etc.) a partir de `main`

Se alguma informacao obrigatoria estiver faltando (ex: milestone, labels, reviewer), pergunte
ao usuario antes de prosseguir — nao crie recursos incompletos.

---

## Workflow Padrao

O ciclo de vida de qualquer trabalho segue este fluxo:

```
Milestone → Issue → Branch → Commits → PR (linkado a issue) → Review → Aprovacao → Merge → Issue fechada
```

Nao pule etapas. Se nao existe milestone ativo, pergunte ao usuario se deve criar um.
Se nao existe issue para o trabalho, crie antes de abrir o PR.

---

## 1. Milestones

Milestones agrupam issues em entregas com prazo. Toda issue deveria pertencer a um milestone.

### Criar milestone

```bash
gh api --method POST /repos/{owner}/{repo}/milestones \
  -f title="v1.0 - MVP" \
  -f description="Primeira versao funcional com auth e dashboard" \
  -f due_on="2026-04-01T23:59:59Z" \
  -f state="open"
```

### Listar milestones e progresso

```bash
gh api /repos/{owner}/{repo}/milestones --jq '.[] | "\(.title): \(.open_issues) abertas, \(.closed_issues) fechadas"'
```

### Fechar milestone

Feche somente quando todas as issues estiverem fechadas:

```bash
gh api --method PATCH /repos/{owner}/{repo}/milestones/{number} \
  -f state="closed"
```

> Para mais comandos, consulte `references/gh-commands.md`.

---

## 2. Issues

Issues sao a unidade basica de trabalho. Toda tarefa, bug ou melhoria comeca como issue.

### Regras ao criar issues

1. **Titulo claro e descritivo** — verbo no infinitivo: "Implementar autenticacao JWT"
2. **Labels obrigatorias** — no minimo uma label `type:` e uma `priority:`
3. **Milestone** — associar ao milestone ativo quando existir
4. **Descricao** — contexto suficiente para alguem entender sem perguntar

### Criar issue

```bash
gh issue create \
  --title "Implementar autenticacao JWT" \
  --body "## Contexto
Precisamos de autenticacao stateless para a API.

## Criterios de aceite
- [ ] Endpoint POST /auth/login retorna token JWT
- [ ] Token expira em 24h
- [ ] Middleware valida token em rotas protegidas" \
  --label "type:feature,priority:high" \
  --milestone "v1.0 - MVP" \
  --assignee "@me"
```

### Labels padrao

Use o esquema namespaced com 3 categorias:

| Categoria | Labels |
|-----------|--------|
| `type:` | bug, feature, enhancement, chore, docs, refactor, test |
| `priority:` | critical, high, medium, low |
| `status:` | in-progress, blocked, needs-review, ready-to-merge |

> Esquema completo com cores hex em `references/labels.md`.

### Inicializar labels no repo

Para aplicar todas as labels padrao de uma vez:

```bash
# Ler references/labels.md e executar o script de criacao
# Cada label e criada via:
gh label create "type:bug" --color "d73a4a" --description "Algo nao funciona como esperado" --force
```

> O script completo esta em `references/labels.md`.

---

## 3. Branches

### Convencao de nomes

O padrao e `{tipo}/{descricao-curta}`:

| Prefixo | Uso |
|---------|-----|
| `feature/` | Nova funcionalidade |
| `fix/` | Correcao de bug |
| `hotfix/` | Correcao urgente em producao |
| `chore/` | Tarefas de manutencao (deps, config) |
| `docs/` | Documentacao |
| `refactor/` | Refatoracao sem mudanca de comportamento |
| `test/` | Adicionar ou corrigir testes |

Exemplos: `feature/auth-jwt`, `fix/login-redirect-loop`, `chore/upgrade-node-22`

### Criar branch a partir de issue

```bash
git checkout -b feature/auth-jwt main
```

Sempre crie branches a partir de `main` (ou do branch base do projeto).

---

## 4. Pull Requests

PRs sao o unico caminho para codigo chegar em `main`. Nao existe commit direto.

### Regras obrigatorias

1. **Linkar a issue** — usar `Closes #N` ou `Fixes #N` no body para fechar automaticamente
2. **Titulo** — seguir conventional commits: `feat: implementar auth JWT`
3. **Body** — usar o template padrao (Summary, Changes, Test Plan)
4. **Review** — minimo 1 reviewer deve aprovar antes do merge
5. **Checks** — todos os status checks devem passar
6. **Merge** — somente apos aprovacao; preferir squash merge para historico limpo

### Prefixos de titulo (Conventional Commits)

| Prefixo | Quando usar |
|---------|------------|
| `feat:` | Nova funcionalidade |
| `fix:` | Correcao de bug |
| `chore:` | Manutencao, deps, config |
| `docs:` | Documentacao |
| `refactor:` | Refatoracao |
| `test:` | Testes |
| `perf:` | Performance |
| `ci:` | Mudancas em CI/CD |

### Criar PR

```bash
gh pr create \
  --title "feat: implementar autenticacao JWT" \
  --body "$(cat <<'EOF'
## Summary
Implementa autenticacao JWT para a API REST.

## Changes
- Endpoint POST /auth/login
- Middleware de validacao de token
- Testes de integracao

## Test Plan
- [ ] Login com credenciais validas retorna token
- [ ] Token expirado retorna 401
- [ ] Rota protegida sem token retorna 403

Closes #42
EOF
)" \
  --assignee "@me" \
  --reviewer "username-do-reviewer"
```

### Fluxo de review

```bash
# Listar PRs aguardando review
gh pr list --search "review:required"

# Aprovar PR
gh pr review {number} --approve --body "LGTM"

# Solicitar mudancas
gh pr review {number} --request-changes --body "Precisa ajustar X e Y"

# Merge apos aprovacao (squash)
gh pr merge {number} --squash --delete-branch
```

O `--delete-branch` remove o branch feature apos o merge, mantendo o repo limpo.

> Template completo de PR em `references/templates.md`.

---

## 5. Branch Protection

Configurar protecao no branch `main` garante que ninguem faca push direto e que todo
codigo passe por review.

### Aplicar protecao

```bash
gh api --method PUT /repos/{owner}/{repo}/branches/main/protection \
  -H "Accept: application/vnd.github.v3+json" \
  --input - <<'EOF'
{
  "required_status_checks": {
    "strict": true,
    "contexts": []
  },
  "enforce_admins": true,
  "required_pull_request_reviews": {
    "required_approving_review_count": 1,
    "dismiss_stale_reviews": true
  },
  "restrictions": null,
  "required_linear_history": true,
  "allow_force_pushes": false,
  "allow_deletions": false
}
EOF
```

Essa configuracao:
- Exige 1 aprovacao em PR
- Descarta reviews antigos quando novos commits sao adicionados
- Exige historico linear (sem merge commits)
- Bloqueia force push e delecao do branch main
- Aplica regras inclusive para admins

---

## 6. Setup Inicial de Repositorio

Quando o usuario pedir para "configurar", "inicializar" ou "preparar" um repositorio,
execute estas etapas na ordem:

1. **Verificar autenticacao**: `gh auth status`
2. **Criar labels padrao**: executar script de `references/labels.md`
3. **Criar milestone inicial**: perguntar titulo e data ao usuario
4. **Configurar branch protection**: aplicar regras no `main`
5. **Criar templates**: issue templates e PR template via `references/templates.md`
6. **Confirmar**: listar o que foi configurado

---

## 7. Boas Praticas Gerais

- **Uma issue, um PR** — evitar PRs que resolvem multiplas issues nao relacionadas
- **PRs pequenos** — mais faceis de revisar, menos risco de conflito
- **Commits atomicos** — cada commit deve compilar e passar nos testes
- **Nao acumular issues sem milestone** — se existe trabalho planejado, deve ter milestone
- **Fechar issues obsoletas** — com comentario explicando por que
- **Revisar PRs em ate 24h** — review rapido mantem o fluxo do time

---

## Referencia Rapida de Comandos

| Acao | Comando |
|------|---------|
| Criar issue | `gh issue create --title "..." --label "..." --milestone "..."` |
| Listar issues | `gh issue list --milestone "..." --state open` |
| Fechar issue | `gh issue close N --comment "..."` |
| Criar PR | `gh pr create --title "..." --body "..."` |
| Listar PRs para review | `gh pr list --search "review:required"` |
| Aprovar PR | `gh pr review N --approve` |
| Merge PR | `gh pr merge N --squash --delete-branch` |
| Criar milestone | ver `references/gh-commands.md` |
| Listar milestones | ver `references/gh-commands.md` |
| Configurar protecao | ver secao 5 acima |

> Para comandos avancados (editar milestone, deletar, filtrar), consulte `references/gh-commands.md`.